nexarch/mail/internal/mailapi/mailapi.go

// Package mailapi implementiert INT-01: die Mail-spezifischen
// REST-Endpunkte (Mail-Liste, Mail-Detail, Anhangsliste, Anhang-Download)
// v1 — Anhangsliste ist UX-02-Zusatz (Grundlage der Anhangsliste in der
// Detailansicht, siehe UX-02-PRUEFPROTOKOLL.md), mit (UX-03) 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/common/policyclient"
	"gitea.perlbach24.de/scripte/nexarch/mail/internal/moduleauth"
	"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.
//
// UX-01 (Postfach-/Ordneransicht) braucht zusätzlich zur Volltextsuche
// den Ordnerbaum (Facets, mailbox-Dimension) und die ungefilterte/nach
// Ordner gefilterte Nachrichtenliste (ListByMailbox, SearchWithFilters) —
// beide bereits von *search.Client für ARC-07/SRC-05/SRC-06
// implementiert, hier nur durchgereicht.
type SearchClient interface {
	Search(ctx context.Context, tenantSlug, queryText string) ([]search.Result, error)
	SearchWithFilters(ctx context.Context, tenantSlug, queryText string, filters []search.FacetFilter) ([]search.Result, error)
	GetByMessageID(ctx context.Context, tenantSlug, messageID string) (search.Document, bool, error)
	ListByMailbox(ctx context.Context, tenantSlug, mailbox string) ([]search.Document, error)
	Facets(ctx context.Context, tenantSlug, queryText string, filters []search.FacetFilter) (search.FacetResult, 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/mailboxes", moduleauth.RequireAuth(verifier, s.requirePermission("mail.message.read", s.handleListMailboxes)))
	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. Sender/Mailbox sind
// UX-01-Zusatzfelder (Akzeptanzkriterium 2: Sortierung nach Absender
// braucht den Wert auch in der Liste, nicht nur im Detail).
type messageListItem struct {
	MessageID string `json:"messageId"`
	Subject   string `json:"subject"`
	Sender    string `json:"sender"`
	Mailbox   string `json:"mailbox"`
	SentAt    int64  `json:"sentAt"`
}

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

// handleListMessages ist GET /api/v1/mail/messages (Akzeptanzkriterium
// 1: Mail-Liste). Optionale Query-Parameter: "q" filtert per Volltext
// (Grundsuche), "mailbox" grenzt auf einen Ordner ein (UX-01
// Akzeptanzkriterium 1: Ordnerauswahl). Sortierung passiert im Frontend
// auf der vollständigen, bereits mandantengebundenen Liste — kein
// weiterer Serverzustand nötig.
func (s *Server) handleListMessages(w http.ResponseWriter, r *http.Request) {
	tenant, ok := tenantFromRequest(w, r)
	if !ok {
		return
	}
	query := r.URL.Query().Get("q")
	mailbox := r.URL.Query().Get("mailbox")

	var items []messageListItem
	if query != "" {
		results, err := s.searchResults(r.Context(), tenant, query, mailbox)
		if err != nil {
			writeError(w, http.StatusBadGateway, "suche fehlgeschlagen")
			return
		}
		items = make([]messageListItem, 0, len(results))
		for _, res := range results {
			items = append(items, messageListItem{
				MessageID: res.MessageID,
				Subject:   res.Subject,
				Sender:    res.Sender,
				Mailbox:   res.Mailbox,
				SentAt:    res.SentAtUnixEpoch,
			})
		}
	} else {
		docs, err := s.search.ListByMailbox(r.Context(), tenant, mailbox)
		if err != nil {
			writeError(w, http.StatusBadGateway, "postfachliste fehlgeschlagen")
			return
		}
		items = make([]messageListItem, 0, len(docs))
		for _, doc := range docs {
			items = append(items, messageListItem{
				MessageID: doc.MessageID,
				Subject:   doc.Subject,
				Sender:    doc.Sender,
				Mailbox:   doc.Mailbox,
				SentAt:    doc.SentAtUnixEpoch,
			})
		}
	}
	writeJSON(w, http.StatusOK, listMessagesResponse{Messages: items})
}

// searchResults wählt zwischen Search (kein Ordnerfilter) und
// SearchWithFilters (Ordnerfilter zusätzlich zum Suchtext) — beide
// bereits mandantengebunden in mail/internal/search implementiert.
func (s *Server) searchResults(ctx context.Context, tenant, query, mailbox string) ([]search.Result, error) {
	if mailbox == "" {
		return s.search.Search(ctx, tenant, query)
	}
	return s.search.SearchWithFilters(ctx, tenant, query, []search.FacetFilter{{Field: search.FacetFieldMailbox, Value: mailbox}})
}

// mailboxListItem ist ein Eintrag des Ordnerbaums.
type mailboxListItem struct {
	Name         string `json:"name"`
	MessageCount int64  `json:"messageCount"`
}

type listMailboxesResponse struct {
	Mailboxes []mailboxListItem `json:"mailboxes"`
}

// handleListMailboxes ist GET /api/v1/mail/mailboxes (UX-01
// Akzeptanzkriterium 1: Ordnerbaum). Leitet die Ordnerliste aus der
// mailbox-Facette ab (SRC-05) statt eine eigene Verwaltung zu bauen —
// strikt mandantengebunden wie jede andere Facette/Suche dieser API.
func (s *Server) handleListMailboxes(w http.ResponseWriter, r *http.Request) {
	tenant, ok := tenantFromRequest(w, r)
	if !ok {
		return
	}
	result, err := s.search.Facets(r.Context(), tenant, "", nil)
	if err != nil {
		writeError(w, http.StatusBadGateway, "postfächer abrufen fehlgeschlagen")
		return
	}
	values := result.Values[string(search.FacetFieldMailbox)]
	mailboxes := make([]mailboxListItem, 0, len(values))
	for _, v := range values {
		mailboxes = append(mailboxes, mailboxListItem{Name: v.Value, MessageCount: v.Count})
	}
	writeJSON(w, http.StatusOK, listMailboxesResponse{Mailboxes: mailboxes})
}

// 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). Es
// gibt keinen Anhang-Katalog, nur fortlaufende Indizes im Objekt-Storage.
const maxAttachmentProbe = 200

// attachmentListItem ist EIN Eintrag der Anhangsliste (UX-03
// Akzeptanzkriterium 1, Grundlage der UX-02-Anhangsliste in der
// Detailansicht). Bewusst OHNE Dateiname/-endung — der Ingestion-Pfad
// (mimeparse → storage) persistiert nirgends einen Originaldateinamen,
// nur rohe Teil-Bytes je Index. 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 sowohl der Anhang-Vorschau-Liste als auch der
// UX-02-Anhangsliste in der Detailansicht). 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. ContentType kommt aus den echten Bytes
// (http.DetectContentType), nicht aus einer Dateiendung.
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)
}