#21: serve the webmail mail API from the protocols service

The mail screens had no backend at all: they rendered a hardcoded array,
and the storage service that ADR-001 assigned this to is still a health
stub. The API lands here instead, because the folder, UID, MODSEQ, flag
and blob logic already exists and is tested in this service for IMAP.
Reimplementing it in TypeScript would mean two implementations of the
same semantics and two chances to disagree about what a UID means.

Reads use a projected read model rather than hydrated aggregates, which
is the CQRS exception PLAN.md section 2 carves out for webmail queries.
Every query is scoped to the mailbox resolved from the verified session,
never to an identifier taken from the request, so one account cannot read
another's mail by guessing a UID - covered by a test that tries exactly
that and expects 404.

Sending reuses ProcessOutboundEmailUseCase, so mail written in the browser
gets the same treatment as mail submitted over 587: send limits, DKIM
signing, and the durable queue. The From address comes from the session
and never from the request body; letting the body choose it is how a
webmail becomes a relay for spoofed mail.

MIME is parsed server-side because this service already depends on a MIME
library. A message that will not parse still returns its raw text - an
unreadable message beats an inbox that refuses to open one.

Marking a message read updates the flag and the folder counter in one
transaction, and only on a real transition, so re-opening a message cannot
drive unread_count negative.

Verified against the running stack: a message delivered over port 25
appears in the list with its decoded subject and sender, opens, marks
itself read, is found by search, and a message composed in the webmail
reaches outbound_jobs with the session's address as the envelope sender.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

services/protocols/internal/presentation/http/mail_api.go

@@ -0,0 +1,199 @@
+package httppresentation
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"lambdamail/protocols/internal/application/usecase"
+	"lambdamail/protocols/internal/infrastructure/postgres"
+)
+
+// maxComposeBytes caps a single submission from the webmail. The SMTP ports
+// have their own limit; this one stops an authenticated browser session from
+// buffering an unbounded body in this process.
+const maxComposeBytes = 32 << 20 // 32 MiB
+
+// mailAPI serves /api/v1/mail/* for the webmail's message screens.
+type mailAPI struct {
+	useCase  *usecase.WebmailUseCase
+	sessions *WebSessionVerifier
+}
+
+func writeJSON(w http.ResponseWriter, status int, payload any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(payload)
+}
+
+func writeError(w http.ResponseWriter, status int, code, message string) {
+	writeJSON(w, status, map[string]string{"error": code, "message": message})
+}
+
+// authenticate resolves the caller's session, refusing anything that is not a
+// /user session token signed by the auth service.
+func (m *mailAPI) authenticate(w http.ResponseWriter, r *http.Request) (*WebSession, bool) {
+	token := ""
+	if header := r.Header.Get("Authorization"); strings.HasPrefix(header, "Bearer ") {
+		token = strings.TrimPrefix(header, "Bearer ")
+	} else if cookie, err := r.Cookie("lm_user_session"); err == nil {
+		token = cookie.Value
+	}
+
+	if token == "" {
+		writeError(w, http.StatusUnauthorized, "UNAUTHORIZED", "User session required")
+		return nil, false
+	}
+
+	session, err := m.sessions.RequireSurface(token, "user")
+	if err != nil {
+		// The reason is deliberately not echoed back: whether a token expired,
+		// was forged or belongs to the other surface is not the caller's
+		// business.
+		writeError(w, http.StatusUnauthorized, "UNAUTHORIZED", "User session required")
+		return nil, false
+	}
+	return session, true
+}
+
+func (m *mailAPI) handleFolders(w http.ResponseWriter, r *http.Request) {
+	session, ok := m.authenticate(w, r)
+	if !ok {
+		return
+	}
+	folders, err := m.useCase.ListFolders(r.Context(), session.Email)
+	if err != nil {
+		m.fail(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, folders)
+}
+
+func (m *mailAPI) handleMessages(w http.ResponseWriter, r *http.Request) {
+	session, ok := m.authenticate(w, r)
+	if !ok {
+		return
+	}
+
+	query := r.URL.Query()
+	folder := query.Get("folder")
+	if folder == "" {
+		folder = "inbox"
+	}
+	limit, _ := strconv.Atoi(query.Get("limit"))
+	offset, _ := strconv.Atoi(query.Get("offset"))
+
+	messages, err := m.useCase.ListMessages(r.Context(), session.Email, folder, query.Get("q"), limit, offset)
+	if err != nil {
+		m.fail(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, messages)
+}
+
+func (m *mailAPI) handleMessage(w http.ResponseWriter, r *http.Request) {
+	session, ok := m.authenticate(w, r)
+	if !ok {
+		return
+	}
+
+	uid, err := strconv.ParseUint(strings.TrimPrefix(r.URL.Path, "/api/v1/mail/message/"), 10, 32)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "INVALID_UID", "Message UID must be a number")
+		return
+	}
+
+	folder := r.URL.Query().Get("folder")
+	if folder == "" {
+		folder = "inbox"
+	}
+
+	raw, err := m.useCase.GetMessage(r.Context(), session.Email, folder, uint32(uid))
+	if err != nil {
+		m.fail(w, err)
+		return
+	}
+
+	// Parsed here rather than in the browser: this service already depends on
+	// a MIME library, and a second parser in TypeScript would be a second set
+	// of edge cases to get wrong.
+	writeJSON(w, http.StatusOK, usecase.RenderMessage(raw, uint32(uid)))
+}
+
+func (m *mailAPI) handleSeen(w http.ResponseWriter, r *http.Request) {
+	session, ok := m.authenticate(w, r)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		Folder string `json:"folder"`
+		UID    uint32 `json:"uid"`
+		Seen   bool   `json:"seen"`
+	}
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "BAD_REQUEST", "Invalid JSON")
+		return
+	}
+	if body.Folder == "" {
+		body.Folder = "inbox"
+	}
+
+	if err := m.useCase.SetSeen(r.Context(), session.Email, body.Folder, body.UID, body.Seen); err != nil {
+		m.fail(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]bool{"ok": true})
+}
+
+func (m *mailAPI) handleSend(w http.ResponseWriter, r *http.Request) {
+	session, ok := m.authenticate(w, r)
+	if !ok {
+		return
+	}
+
+	var body struct {
+		To      []string `json:"to"`
+		Cc      []string `json:"cc"`
+		Subject string   `json:"subject"`
+		Body    string   `json:"body"`
+	}
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxComposeBytes)).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "BAD_REQUEST", "Invalid JSON")
+		return
+	}
+
+	// The sender is the session's address, never a field in the request:
+	// letting the body choose From is how a webmail becomes an open relay for
+	// spoofed mail.
+	err := m.useCase.Send(r.Context(), usecase.ComposeInput{
+		From:    session.Email,
+		To:      body.To,
+		Cc:      body.Cc,
+		Subject: body.Subject,
+		Body:    body.Body,
+	})
+	if err != nil {
+		m.fail(w, err)
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]bool{"queued": true})
+}
+
+// fail maps domain errors onto status codes without leaking internals.
+func (m *mailAPI) fail(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, postgres.ErrMessageNotFound), errors.Is(err, usecase.ErrNoSuchMailbox):
+		writeError(w, http.StatusNotFound, "NOT_FOUND", "Message not found")
+	case errors.Is(err, usecase.ErrNoRecipients):
+		writeError(w, http.StatusBadRequest, "NO_RECIPIENTS", "At least one valid recipient is required")
+	case errors.Is(err, usecase.ErrSendLimitExceeded):
+		writeError(w, http.StatusTooManyRequests, "SEND_LIMIT_EXCEEDED", "Hourly recipient limit reached")
+	case errors.Is(err, usecase.ErrSenderNotOwned):
+		writeError(w, http.StatusForbidden, "FORBIDDEN", "Sender address does not belong to this account")
+	default:
+		writeError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "Request could not be processed")
+	}
+}

services/protocols/internal/presentation/http/router.go

@@ -22,6 +22,10 @@ type Router struct {
 	reportUseCase *appusecase.IngestReportsUseCase
 	pingFunc      func() error
 	mtaStsMode    valueobject.MtaStsMode
+	// mail serves the webmail's message screens. It stays nil when no session
+	// secret is configured, and the routes then answer 503 rather than
+	// pretending to be open.
+	mail *mailAPI
 	// degradedFunc reports a condition that leaves the service running but
 	// not fit for production, the clearest case being a self-signed
 	// certificate standing in for one Traefik never issued
@@ -63,6 +67,11 @@ func (r *Router) registerRoutes() {
 	r.mux.HandleFunc("/mail/config-v1.1.xml", r.handleThunderbirdAutoconfig)
 	r.mux.HandleFunc("/.well-known/autoconfig/mail/config-v1.1.xml", r.handleThunderbirdAutoconfig)
 	r.mux.HandleFunc("/autodiscover/autodiscover.xml", r.handleOutlookAutodiscover)
+	r.mux.HandleFunc("/api/v1/mail/folders", r.handleMailFolders)
+	r.mux.HandleFunc("/api/v1/mail/messages", r.handleMailMessages)
+	r.mux.HandleFunc("/api/v1/mail/message/", r.handleMailMessage)
+	r.mux.HandleFunc("/api/v1/mail/seen", r.handleMailSeen)
+	r.mux.HandleFunc("/api/v1/mail/send", r.handleMailSend)
 	r.mux.HandleFunc("/api/v1/reports/dmarc", r.handleDmarcIngest)
 	r.mux.HandleFunc("/api/v1/reports/tlsrpt", r.handleTlsRptIngest)
 }
@@ -219,3 +228,60 @@ func baseDomain(host string) string {
 	}
 	return host
 }
+
+// SetMailAPI wires the webmail message API. Without it the mail routes exist
+// but report that the feature is not configured, which is a clearer failure
+// than a 404 that looks like a typo in the path.
+func (r *Router) SetMailAPI(useCase *appusecase.WebmailUseCase, sessionSecret string) {
+	if useCase == nil || sessionSecret == "" {
+		return
+	}
+	r.mail = &mailAPI{useCase: useCase, sessions: NewWebSessionVerifier(sessionSecret)}
+}
+
+func (r *Router) mailReady(w http.ResponseWriter) bool {
+	if r.mail == nil {
+		writeError(w, http.StatusServiceUnavailable, "MAIL_API_DISABLED",
+			"The mail API needs JWT_SECRET to verify webmail sessions")
+		return false
+	}
+	return true
+}
+
+func (r *Router) handleMailFolders(w http.ResponseWriter, req *http.Request) {
+	if r.mailReady(w) {
+		r.mail.handleFolders(w, req)
+	}
+}
+
+func (r *Router) handleMailMessages(w http.ResponseWriter, req *http.Request) {
+	if r.mailReady(w) {
+		r.mail.handleMessages(w, req)
+	}
+}
+
+func (r *Router) handleMailMessage(w http.ResponseWriter, req *http.Request) {
+	if r.mailReady(w) {
+		r.mail.handleMessage(w, req)
+	}
+}
+
+func (r *Router) handleMailSeen(w http.ResponseWriter, req *http.Request) {
+	if req.Method != http.MethodPost {
+		writeError(w, http.StatusMethodNotAllowed, "METHOD_NOT_ALLOWED", "POST required")
+		return
+	}
+	if r.mailReady(w) {
+		r.mail.handleSeen(w, req)
+	}
+}
+
+func (r *Router) handleMailSend(w http.ResponseWriter, req *http.Request) {
+	if req.Method != http.MethodPost {
+		writeError(w, http.StatusMethodNotAllowed, "METHOD_NOT_ALLOWED", "POST required")
+		return
+	}
+	if r.mailReady(w) {
+		r.mail.handleSend(w, req)
+	}
+}