#21: fill in message metadata and stop losing mail to a missing folder

Two problems the mail screens exposed, both in the delivery path.

The subject, snippet, sender name and message-id columns have existed
since the first migration, but nothing ever wrote them: every row went in
with those fields NULL. A message list built on the database would have
shown blank subjects for every message. Delivery now parses them once per
message and stores them, decoding RFC 2047 encoded words so an accented
subject is readable rather than raw. Parsing failures are non-fatal: a
message with unreadable headers is still delivered, just with less
metadata, because refusing it would lose mail over a malformed Subject.

Worse, a message the spam filter routed to Junk failed delivery outright
when the mailbox had no Junk folder - the sender got 451 and retried
forever against a mailbox that would never grow one on its own. Delivery
now falls back to INBOX and says so in the log. Found by sending a real
message through port 25 against the running stack.

The SMTP handler also swallowed the cause of any unexpected failure: the
peer saw "temporary error" and the operator got nothing. It is logged now,
which is how the missing folder was diagnosed at all.

Also adds the JWT verifier the mail API needs. The tokens are minted by
the auth service and verified here under the same secret, so the test
fixtures are real tokens produced by that service: if the two
implementations drift, this fails before the webmail does. Challenge
tokens, wrong secrets, tampered payloads, expired tokens and the other
surface's audience are all rejected.

The dev seed gained the standard folder set, which is what a provisioned
mailbox has and what the fallback above should not have to compensate for.

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

services/protocols/internal/application/port/inbound_message_repository.go

@@ -14,9 +14,17 @@ type PersistInboundMessageInput struct {
 	SenderAddress    string
 	RecipientAddress string
 	TargetFolderName string // "INBOX", "Junk", etc. (defaults to "INBOX" if empty)
-	SPFResult        string
-	DKIMResult       string
-	DMARCResult      string
+	// Header-derived fields. The columns for these have existed since the
+	// first migration but nothing filled them, so every message listed in the
+	// webmail had a blank subject and sender name.
+	Subject         string
+	Snippet         string
+	FromDisplayName string
+	MessageIDHeader string
+	HasAttachments  bool
+	SPFResult       string
+	DKIMResult      string
+	DMARCResult     string
 }
 
 // InboundMessageRepository durably records an accepted inbound message: for

services/protocols/internal/application/usecase/message_headers.go

@@ -0,0 +1,116 @@
+package usecase
+
+import (
+	"bytes"
+	"io"
+	"mime"
+	"net/mail"
+	"strings"
+	"unicode/utf8"
+)
+
+// snippetLength is how much of the body is kept for the message list. It is a
+// preview, not the message: the body itself stays in the blob.
+const snippetLength = 200
+
+// MessageHeaders is the subset of a message the webmail list needs, so that
+// showing an inbox does not mean reading every blob off disk.
+type MessageHeaders struct {
+	Subject         string
+	FromDisplayName string
+	MessageID       string
+	Snippet         string
+	HasAttachments  bool
+}
+
+// wordDecoder tolerates the charsets that turn up in real mail. An unknown
+// charset yields the raw bytes rather than an error, because a subject that
+// renders imperfectly beats a delivery that fails.
+var wordDecoder = mime.WordDecoder{
+	CharsetReader: func(_ string, input io.Reader) (io.Reader, error) {
+		return input, nil
+	},
+}
+
+func decodeHeader(value string) string {
+	decoded, err := wordDecoder.DecodeHeader(value)
+	if err != nil {
+		return value
+	}
+	return decoded
+}
+
+// ExtractMessageHeaders parses the fields the message list displays.
+//
+// Every failure is non-fatal: a message with unparseable headers is still
+// delivered, just with less metadata. Refusing it would lose mail over a
+// malformed Subject, which is exactly the kind of thing spam is full of.
+func ExtractMessageHeaders(payload []byte) MessageHeaders {
+	var out MessageHeaders
+
+	msg, err := mail.ReadMessage(bytes.NewReader(payload))
+	if err != nil {
+		return out
+	}
+
+	out.Subject = truncateUTF8(decodeHeader(msg.Header.Get("Subject")), 998)
+	out.MessageID = truncateUTF8(strings.Trim(msg.Header.Get("Message-ID"), "<>"), 998)
+
+	if from := msg.Header.Get("From"); from != "" {
+		if addr, err := mail.ParseAddress(from); err == nil {
+			out.FromDisplayName = truncateUTF8(decodeHeader(addr.Name), 255)
+		} else {
+			// A From that does not parse still often carries a usable name
+			// before the angle bracket.
+			if idx := strings.Index(from, "<"); idx > 0 {
+				out.FromDisplayName = truncateUTF8(decodeHeader(strings.TrimSpace(strings.Trim(from[:idx], `"`))), 255)
+			}
+		}
+	}
+
+	contentType := msg.Header.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(contentType)
+	if err == nil && strings.HasPrefix(mediaType, "multipart/") {
+		// mixed and related carry parts that are not the body; alternative is
+		// just the same text twice, so it does not count as an attachment.
+		out.HasAttachments = mediaType != "multipart/alternative"
+		_ = params
+	}
+
+	out.Snippet = buildSnippet(msg, mediaType)
+	return out
+}
+
+// buildSnippet takes the opening of the body as a plain-text preview.
+func buildSnippet(msg *mail.Message, mediaType string) string {
+	// Only a flat text body is previewed. Walking MIME parts here would mean
+	// decoding attachments on the delivery path, which is the hot path.
+	if mediaType != "" && !strings.HasPrefix(mediaType, "text/") {
+		return ""
+	}
+
+	buf := make([]byte, 8*1024)
+	n, _ := msg.Body.Read(buf)
+	if n <= 0 {
+		return ""
+	}
+
+	text := string(buf[:n])
+	text = strings.ReplaceAll(text, "\r\n", " ")
+	text = strings.ReplaceAll(text, "\n", " ")
+	text = strings.Join(strings.Fields(text), " ")
+	return truncateUTF8(text, snippetLength)
+}
+
+// truncateUTF8 cuts to at most max bytes without splitting a rune, so a
+// truncated subject cannot become invalid UTF-8 and break the JSON encoding.
+func truncateUTF8(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	cut := s[:max]
+	for len(cut) > 0 && !utf8.ValidString(cut) {
+		cut = cut[:len(cut)-1]
+	}
+	return cut
+}

services/protocols/internal/application/usecase/message_headers_test.go

@@ -0,0 +1,88 @@
+package usecase
+
+import "testing"
+
+func TestExtractMessageHeaders_ReadsSubjectSenderAndSnippet(t *testing.T) {
+	msg := "From: Alice Example <alice@remote.test>\r\n" +
+		"To: bob@example.test\r\n" +
+		"Subject: Quarterly report\r\n" +
+		"Message-ID: <abc123@remote.test>\r\n" +
+		"Content-Type: text/plain; charset=utf-8\r\n" +
+		"\r\n" +
+		"Here is the report you asked for.\r\nSecond line.\r\n"
+
+	h := ExtractMessageHeaders([]byte(msg))
+
+	if h.Subject != "Quarterly report" {
+		t.Errorf("Subject = %q", h.Subject)
+	}
+	if h.FromDisplayName != "Alice Example" {
+		t.Errorf("FromDisplayName = %q", h.FromDisplayName)
+	}
+	if h.MessageID != "abc123@remote.test" {
+		t.Errorf("MessageID = %q, angle brackets should be stripped", h.MessageID)
+	}
+	if h.Snippet != "Here is the report you asked for. Second line." {
+		t.Errorf("Snippet = %q", h.Snippet)
+	}
+	if h.HasAttachments {
+		t.Error("a text/plain message was reported as having attachments")
+	}
+}
+
+// Real subjects arrive RFC 2047 encoded; showing the raw encoded word in the
+// message list is the usual symptom of skipping this.
+func TestExtractMessageHeaders_DecodesEncodedWords(t *testing.T) {
+	msg := "From: =?UTF-8?B?SsO6bGlv?= <julio@remote.test>\r\n" +
+		"Subject: =?UTF-8?Q?Relat=C3=B3rio_mensal?=\r\n" +
+		"\r\n" +
+		"corpo\r\n"
+
+	h := ExtractMessageHeaders([]byte(msg))
+	if h.Subject != "Relatório mensal" {
+		t.Errorf("Subject = %q, want the decoded form", h.Subject)
+	}
+	if h.FromDisplayName != "Júlio" {
+		t.Errorf("FromDisplayName = %q, want the decoded form", h.FromDisplayName)
+	}
+}
+
+func TestExtractMessageHeaders_FlagsMultipartMixedAsAttachment(t *testing.T) {
+	withAttachment := "From: a@b.test\r\nSubject: s\r\n" +
+		"Content-Type: multipart/mixed; boundary=xyz\r\n\r\n--xyz\r\n\r\nbody\r\n--xyz--\r\n"
+	if !ExtractMessageHeaders([]byte(withAttachment)).HasAttachments {
+		t.Error("multipart/mixed should be flagged as carrying attachments")
+	}
+
+	// alternative is the same body twice, not an attachment.
+	altOnly := "From: a@b.test\r\nSubject: s\r\n" +
+		"Content-Type: multipart/alternative; boundary=xyz\r\n\r\n--xyz\r\n\r\nbody\r\n--xyz--\r\n"
+	if ExtractMessageHeaders([]byte(altOnly)).HasAttachments {
+		t.Error("multipart/alternative should not count as an attachment")
+	}
+}
+
+// A malformed message must still be delivered - refusing it would lose mail
+// over a bad header, which is what spam is full of.
+func TestExtractMessageHeaders_SurvivesGarbage(t *testing.T) {
+	for _, payload := range []string{"", "not a message at all", "Subject: no body follows"} {
+		h := ExtractMessageHeaders([]byte(payload))
+		_ = h // no panic, no error: absent metadata is the worst outcome
+	}
+}
+
+func TestExtractMessageHeaders_TruncatesWithoutBreakingUTF8(t *testing.T) {
+	long := ""
+	for range 300 {
+		long += "á"
+	}
+	h := ExtractMessageHeaders([]byte("Subject: s\r\n\r\n" + long + "\r\n"))
+	if len(h.Snippet) > snippetLength {
+		t.Errorf("snippet is %d bytes, want at most %d", len(h.Snippet), snippetLength)
+	}
+	for _, r := range h.Snippet {
+		if r == '�' {
+			t.Fatal("truncation split a multi-byte rune")
+		}
+	}
+}

services/protocols/internal/application/usecase/process_inbound_email.go

@@ -234,6 +234,10 @@ func (uc *ProcessInboundEmailUseCase) Handle(ctx context.Context, input ProcessI
 	// would mean a failure halfway through leaves the earlier recipients with
 	// a copy while the sender is told to retry - and the retry delivers to
 	// them a second time.
+	// Parsed once for the whole delivery: every recipient's row carries the
+	// same headers, and the list view reads them instead of the blob.
+	headers := ExtractMessageHeaders(payload)
+
 	persistInputs := make([]port.PersistInboundMessageInput, len(input.Recipients))
 	for i, recipient := range input.Recipients {
 		persistInputs[i] = port.PersistInboundMessageInput{
@@ -242,6 +246,11 @@ func (uc *ProcessInboundEmailUseCase) Handle(ctx context.Context, input ProcessI
 			SenderAddress:    input.Sender,
 			RecipientAddress: input.RecipientAddresses[i],
 			TargetFolderName: targetFolder,
+			Subject:          headers.Subject,
+			Snippet:          headers.Snippet,
+			FromDisplayName:  headers.FromDisplayName,
+			MessageIDHeader:  headers.MessageID,
+			HasAttachments:   headers.HasAttachments,
 			SPFResult:        authResult.SPF,
 			DKIMResult:       authResult.DKIM,
 			DMARCResult:      authResult.DMARC,