nexarch/mail/internal/mailapi/mailapi.go

// Package mailapi implementiert INT-01: die Mail-spezifischen
// REST-Endpunkte (Mail-Liste, Mail-Detail, Anhang-Download) v1 — sowie
// (UX-03) die Anhangsliste mit serverseitig per Magic-Bytes bestimmtem
// Content-Type, Grundlage der Anhang-Vorschau im Frontend.
//
// Core API-01 (REST-API-Grundgerüst & Versionierung) und API-04
// (OpenAPI-Schnittstellenbeschreibung) sind laut core-kanban zwar auf
// "Fertig", enthalten im aktuellen Repository-Stand aber noch keinen
// abrufbaren Router/keine Middleware, an die sich dieses Paket technisch
// anhängen könnte (siehe Abgrenzung im INT-01-Prüfprotokoll — gleiche
// Situation wie ARC-06/Core TEN-01). RegisterRoutes registriert daher
// die v1-Endpunkte auf einem vom Aufrufer bereitgestellten
// *http.ServeMux mit dem dokumentierten Pfadschema
// "/api/v1/mail/..." — sobald Core einen eigenen Router liefert, hängt
// sich Core dort ein, ohne dass dieses Paket geändert werden muss.
//
// INT-18: Jede Route verlangt ein gueltiges Core-Modul-Token
// (mail/internal/moduleauth, aud=mail seit API-18); der Mandant kommt
// ausschliesslich aus dessen Claims. Ein evtl. mitgesendeter
// "tenant"-Query-Parameter wird nicht gelesen (Akzeptanzkriterium 2:
// ignoriert, nicht nur zusaetzlich geprueft) — es gibt technisch keinen
// Weg mehr, den Mandanten ueber die Anfrage selbst zu beeinflussen.
package mailapi

import (
	"context"
	"encoding/json"
	"errors"
	"net/http"
	"strconv"

	"gitea.perlbach24.de/scripte/nexarch/mail/internal/moduleauth"
	"gitea.perlbach24.de/scripte/nexarch/mail/internal/policyclient"
	"gitea.perlbach24.de/scripte/nexarch/mail/internal/search"
	"gitea.perlbach24.de/scripte/nexarch/mail/internal/storage"
)

// SearchClient ist die für diese API benötigte Teilmenge von
// *search.Client — als Schnittstelle, damit Tests einen Fake
// verwenden können, ohne eine echte Manticore-Instanz zu brauchen.
type SearchClient interface {
	Search(ctx context.Context, tenantSlug, queryText string) ([]search.Result, error)
	GetByMessageID(ctx context.Context, tenantSlug, messageID string) (search.Document, bool, error)
}

// StorageProvider liefert den mandantenspezifischen Objekt-Storage-
// Service (ARC-06: physisch getrennter Bucket je Mandant) für
// Anhang-Downloads. Ein unbekannter tenantSlug liefert einen Fehler —
// die Implementierung entscheidet, ob "unbekannt" bedeutet.
type StorageProvider interface {
	ServiceFor(tenantSlug string) (*storage.Service, error)
}

// Server bündelt die Abhängigkeiten der Mail-API v1.
type Server struct {
	search  SearchClient
	storage StorageProvider
	policy  *policyclient.Client
}

// WithPolicy aktiviert RBAC-12: echte Rechteprüfung gegen Core (POST
// /authorize) für ausgewählte Routen, zusätzlich zur Modul-Token-Prüfung.
// Ohne WithPolicy verhält sich der Server wie bisher (kein Verhaltenswechsel
// für Aufrufer, die das nicht nutzen).
func (s *Server) WithPolicy(client *policyclient.Client) *Server {
	s.policy = client
	return s
}

// requirePermission prueft (bei gesetztem s.policy) das angegebene Recht
// gegen Rolle/Mandant aus der bereits verifizierten Modul-Token-Identitaet.
func (s *Server) requirePermission(permission string, next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if s.policy != nil {
			id, _ := moduleauth.IdentityFrom(r.Context())
			allowed, err := s.policy.Allowed(r.Context(), id.Tenant, id.Role, permission)
			if err != nil {
				writeError(w, http.StatusServiceUnavailable, "berechtigungsdienst nicht erreichbar")
				return
			}
			if !allowed {
				writeError(w, http.StatusForbidden, "keine berechtigung")
				return
			}
		}
		next(w, r)
	}
}

func NewServer(searchClient SearchClient, storageProvider StorageProvider) *Server {
	return &Server{search: searchClient, storage: storageProvider}
}

// RegisterRoutes registriert die v1-Endpunkte (Akzeptanzkriterium 1)
// auf mux, jede Route einzeln hinter moduleauth.RequireAuth(verifier, ...)
// (Pflichtpruefung 2: Routenliste ohne ungeschuetzte Route — strukturell
// garantiert, nicht abhaengig davon, wie mux spaeter eingebunden wird).
// Pfadschema exakt wie im OpenAPI-Beitrag (openapi.yaml, Akzeptanzkriterium
// 4) dokumentiert.
//
// Bindet verifier IMMER an audience "mail" (Expect, enforce=true) — ein
// echter Fund im e2e-Test: ohne diese Bindung akzeptierte die API auch
// Tokens anderer Module (z.B. aud=dms), weil ein unkonfigurierter Verifier
// jede Audience durchlaesst. Ein zukuenftiger Aufrufer kann das nicht mehr
// vergessen, weil es hier passiert statt beim Aufrufer (Akzeptanzkriterium
// 1: "aud=mail" ist Teil DIESER Kachel, nicht der spaeteren Verdrahtung).
func (s *Server) RegisterRoutes(mux *http.ServeMux, verifier *moduleauth.Verifier) {
	verifier.Expect("mail", "", true)
	mux.Handle("GET /api/v1/mail/messages", moduleauth.RequireAuth(verifier, s.requirePermission("mail.message.read", s.handleListMessages)))
	mux.Handle("GET /api/v1/mail/messages/{messageID}", moduleauth.RequireAuth(verifier, http.HandlerFunc(s.handleGetMessage)))
	mux.Handle("GET /api/v1/mail/messages/{messageID}/attachments", moduleauth.RequireAuth(verifier, http.HandlerFunc(s.handleListAttachments)))
	mux.Handle("GET /api/v1/mail/messages/{messageID}/attachments/{index}", moduleauth.RequireAuth(verifier, http.HandlerFunc(s.handleGetAttachment)))
}

// errorResponse ist die einheitliche Fehlerantwortform (im
// OpenAPI-Beitrag als Schema dokumentiert).
type errorResponse struct {
	Error string `json:"error"`
}

func writeError(w http.ResponseWriter, status int, message string) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(errorResponse{Error: message})
}

// tenantFromRequest liest den Mandanten aus der per moduleauth.RequireAuth
// gesetzten Identitaet (Akzeptanzkriterium 1/2). Fehlt sie, ist die Route
// nicht ueber RegisterRoutes verdrahtet worden — Verteidigung in der Tiefe,
// dieser Fall darf bei korrekter Verdrahtung nie eintreten.
func tenantFromRequest(w http.ResponseWriter, r *http.Request) (string, bool) {
	id, ok := moduleauth.IdentityFrom(r.Context())
	if !ok || id.Tenant == "" {
		writeError(w, http.StatusUnauthorized, "nicht angemeldet")
		return "", false
	}
	return id.Tenant, true
}

// messageListItem ist ein Eintrag der Mail-Liste.
type messageListItem struct {
	MessageID string `json:"messageId"`
	Subject   string `json:"subject"`
	SentAt    int64  `json:"sentAt"`
}

type listMessagesResponse struct {
	Messages []messageListItem `json:"messages"`
}

// handleListMessages ist GET /api/v1/mail/messages (Akzeptanzkriterium
// 1: Mail-Liste). Optionaler Query-Parameter "q" filtert per Volltext,
// wie mail/internal/search es ohnehin unterstützt.
func (s *Server) handleListMessages(w http.ResponseWriter, r *http.Request) {
	tenant, ok := tenantFromRequest(w, r)
	if !ok {
		return
	}
	query := r.URL.Query().Get("q")

	results, err := s.search.Search(r.Context(), tenant, query)
	if err != nil {
		writeError(w, http.StatusBadGateway, "suche fehlgeschlagen")
		return
	}

	resp := listMessagesResponse{Messages: make([]messageListItem, 0, len(results))}
	for _, res := range results {
		resp.Messages = append(resp.Messages, messageListItem{
			MessageID: res.MessageID,
			Subject:   res.Subject,
			SentAt:    res.SentAtUnixEpoch,
		})
	}
	writeJSON(w, http.StatusOK, resp)
}

// messageDetailResponse ist die Antwort von GET
// /api/v1/mail/messages/{messageID}.
type messageDetailResponse struct {
	MessageID string `json:"messageId"`
	Subject   string `json:"subject"`
	Body      string `json:"body"`
	Sender    string `json:"sender"`
	Mailbox   string `json:"mailbox"`
	SentAt    int64  `json:"sentAt"`
}

// handleGetMessage ist GET /api/v1/mail/messages/{messageID}
// (Akzeptanzkriterium 1: Mail-Detail). Liefert 404, wenn die Nachricht
// für DIESEN Mandanten nicht existiert — auch wenn sie für einen
// ANDEREN Mandanten existiert (Akzeptanzkriterium 2: strikt
// mandantengebunden, siehe search.Client.GetByMessageID).
func (s *Server) handleGetMessage(w http.ResponseWriter, r *http.Request) {
	tenant, ok := tenantFromRequest(w, r)
	if !ok {
		return
	}
	messageID := r.PathValue("messageID")

	doc, found, err := s.search.GetByMessageID(r.Context(), tenant, messageID)
	if err != nil {
		writeError(w, http.StatusBadGateway, "abruf fehlgeschlagen")
		return
	}
	if !found {
		writeError(w, http.StatusNotFound, "nachricht nicht gefunden")
		return
	}

	writeJSON(w, http.StatusOK, messageDetailResponse{
		MessageID: doc.MessageID,
		Subject:   doc.Subject,
		Body:      doc.Body,
		Sender:    doc.Sender,
		Mailbox:   doc.Mailbox,
		SentAt:    doc.SentAtUnixEpoch,
	})
}

// maxAttachmentProbe begrenzt, wie viele Anhang-Indizes je Nachricht
// abgefragt werden (gleicher Wert/Zweck wie mailexport.maxAttachmentProbe
// — Schutz gegen einen fehlerhaften Driver, der nie storage.ErrNotFound
// liefert; kein Cross-Package-Export, um mailexport nicht anzufassen).
const maxAttachmentProbe = 200

// attachmentListItem ist EIN Eintrag der Anhangsliste (UX-03
// Akzeptanzkriterium 1). Bewusst OHNE Dateiname/-endung — die einzige
// Information, auf der die Oberfläche die Vorschauart wählt, ist
// ContentType, serverseitig aus den tatsächlichen Bytes gesniffed
// (Akzeptanzkriterium 2), nicht irgendeine vom Absender/Importpfad
// behauptete Endung.
type attachmentListItem struct {
	Index       int    `json:"index"`
	ContentType string `json:"contentType"`
	Size        int64  `json:"size"`
}

type listAttachmentsResponse struct {
	Attachments []attachmentListItem `json:"attachments"`
}

// handleListAttachments ist GET
// /api/v1/mail/messages/{messageID}/attachments (UX-03 Akzeptanzkriterium
// 1: Grundlage für die Anhang-Vorschau-Liste). Es gibt keinen Anhang-
// Katalog in einer eigenen Tabelle — wie mailexport.fetchAttachments
// tastet dieser Handler die Indizes ab 0 ab, bis storage.ErrNotFound den
// ersten fehlenden Index meldet.
func (s *Server) handleListAttachments(w http.ResponseWriter, r *http.Request) {
	tenant, ok := tenantFromRequest(w, r)
	if !ok {
		return
	}
	messageID := r.PathValue("messageID")

	if _, found, err := s.search.GetByMessageID(r.Context(), tenant, messageID); err != nil {
		writeError(w, http.StatusBadGateway, "abruf fehlgeschlagen")
		return
	} else if !found {
		writeError(w, http.StatusNotFound, "nachricht nicht gefunden")
		return
	}

	svc, err := s.storage.ServiceFor(tenant)
	if err != nil {
		writeError(w, http.StatusBadRequest, "unbekannter mandant")
		return
	}

	resp := listAttachmentsResponse{Attachments: []attachmentListItem{}}
	for i := 0; i < maxAttachmentProbe; i++ {
		content, err := svc.GetVerified(r.Context(), storage.ObjectKey(messageID, i))
		if errors.Is(err, storage.ErrNotFound) {
			break
		}
		if err != nil {
			writeError(w, http.StatusBadGateway, "anhang-abruf fehlgeschlagen")
			return
		}
		resp.Attachments = append(resp.Attachments, attachmentListItem{
			Index:       i,
			ContentType: http.DetectContentType(content),
			Size:        int64(len(content)),
		})
	}
	writeJSON(w, http.StatusOK, resp)
}

// handleGetAttachment ist GET
// /api/v1/mail/messages/{messageID}/attachments/{index}
// (Akzeptanzkriterium 1: Anhang-Download). {index} ist der von
// mail/internal/mimeparse beim Import vergebene Anhang-Index innerhalb
// der Nachricht (dieselbe Zählung wie storage.ObjectKey).
//
// Akzeptanzkriterium 2 (strikt mandantengebunden) ist hier STRUKTURELL
// garantiert, nicht nur durch einen Vergleich: StorageProvider liefert
// für tenant AUSSCHLIESSLICH den physisch getrennten Bucket dieses
// Mandanten (ARC-06) — ein falscher/fremder tenant-Parameter kann
// technisch keinen fremden Bucket referenzieren, unabhängig davon, ob
// die angefragte messageID dort zufällig ebenfalls existiert.
func (s *Server) handleGetAttachment(w http.ResponseWriter, r *http.Request) {
	tenant, ok := tenantFromRequest(w, r)
	if !ok {
		return
	}
	messageID := r.PathValue("messageID")
	indexStr := r.PathValue("index")
	index, err := strconv.Atoi(indexStr)
	if err != nil || index < 0 {
		writeError(w, http.StatusBadRequest, "ungültiger anhang-index")
		return
	}

	// Zuerst bestätigen, dass die Nachricht für DIESEN Mandanten
	// überhaupt existiert — verhindert, dass eine geratene messageID
	// eines fremden Mandanten (dessen Bucket hier ohnehin nicht
	// referenzierbar wäre) einen irreführenden Fehlercode liefert.
	if _, found, err := s.search.GetByMessageID(r.Context(), tenant, messageID); err != nil {
		writeError(w, http.StatusBadGateway, "abruf fehlgeschlagen")
		return
	} else if !found {
		writeError(w, http.StatusNotFound, "nachricht nicht gefunden")
		return
	}

	svc, err := s.storage.ServiceFor(tenant)
	if err != nil {
		writeError(w, http.StatusBadRequest, "unbekannter mandant")
		return
	}

	content, err := svc.GetVerified(r.Context(), storage.ObjectKey(messageID, index))
	if err != nil {
		if errors.Is(err, storage.ErrNotFound) {
			writeError(w, http.StatusNotFound, "anhang nicht gefunden")
			return
		}
		writeError(w, http.StatusBadGateway, "anhang-abruf fehlgeschlagen")
		return
	}

	// UX-03 Akzeptanzkriterium 2: Content-Type kommt AUSSCHLIESSLICH aus
	// den tatsächlich gelesenen Bytes (http.DetectContentType, RFC-
	// basierte Signaturerkennung) — es gibt an dieser Stelle gar keinen
	// Dateinamen/keine Endung, die stattdessen herangezogen werden
	// könnte. "inline" statt "attachment": die Oberfläche zeigt eine
	// Vorschau an (Akzeptanzkriterium 1), kein erzwungener Download.
	w.Header().Set("Content-Type", http.DetectContentType(content))
	w.Header().Set("Content-Disposition", "inline")
	w.WriteHeader(http.StatusOK)
	_, _ = w.Write(content)
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(v)
}