feat(mail): ING-03 SMTP-Server & Mailer (RFC 5321)

Neues Paket mail/internal/smtp: SMTP-Server für eingehende Mails, von Grund auf implementiert, analog zu mail/internal/imap und mail/internal/pop3 — TCP-Listener mit einer Goroutine pro Verbindung, Session-Zustandsmaschine (Greeting/Ready/MailFromSet/RcptToSet), Kommandos HELO/EHLO, MAIL FROM, RCPT TO, DATA, RSET, NOOP, QUIT. Envelope wird schrittweise aufgebaut und validiert (503 bei übersprungenen Schritten, 553 bei ungültiger Absender-/Empfängeradresse), Nachrichtengröße wird während DATA laufend gegen eine konfigurierbare Höchstgröße geprüft (552 bei Überschreitung, Sink bekommt die Nachricht nicht). Dot-Stuffing beim Empfang korrekt rückgängig gemacht. Neues Paket mail/internal/mailer: Mailer-Komponente für ausgehende Nachrichten. headerWriter ist die einzige Stelle, an der Header geschrieben werden — jeder Feldwert wird hart gegen CR/LF/Steuerzeichen geprüft, bevor er in die Nachricht geschrieben wird. Behebt den bekannten archivmail-Fehler (Header-Injection durch Stringkonkatenation ohne CRLF-Prüfung, siehe known-issues-archivmail.md #1). Sender.Send überträgt per echtem net/smtp-Client (Standardbibliothek) — keine Zugangsdaten im Code, Zieladresse kommt vom Aufrufer. Alle drei Pflichtprüfungen mit echten Nachweisen durchgeführt: CRLF-/Steuerzeichen-Injection in Betreff und Anzeigenamen schlägt fehl (vier Testfälle), Ende-zu-Ende-Header-Integritätstest über echten SMTP-Dialog (Mailpit/MailHog nicht installierbar auf diesem Rechner — Ersatz durch den in dieser Kachel gebauten echten SMTP-Server, kein Mock, im Prüfprotokoll begründet), Lasttest mit 50 gleichzeitigen Verbindungen ohne Goroutine-/Verbindungsleck. go build/go vet/golangci-lint clean, gesamtes Mail-Modul (~26 Pakete) regressionsfrei getestet.
2026-09-01 00:59:56 +02:00
parent 16c4ad0075
commit 6631bcbbdd
12 changed files with 1246 additions and 0 deletions
@@ -0,0 +1,46 @@
+package mailer
+
+import "fmt"
+
+// headerWriter schreibt E-Mail-Header ausschließlich über diese
+// strukturierte API (Akzeptanzkriterium 2) — nie über freie
+// Stringkonkatenation von Feldname und -wert. Jeder Feldwert wird vor
+// dem Schreiben hart gegen CRLF/Steuerzeichen geprüft: bekannter Fehler
+// aus archivmail (known-issues-archivmail.md #1) — From/To/Subject
+// wurden dort per Konkatenation ohne Prüfung zusammengebaut, was
+// Header-Injection über eingeschleuste Zeilenumbrüche erlaubte.
+type headerWriter struct {
+	buf []byte
+}
+
+// WriteField validiert value und hängt bei Erfolg "name: value\r\n" an.
+// Ein Fehler lässt buf unverändert.
+func (h *headerWriter) WriteField(name, value string) error {
+	if err := validateHeaderValue(value); err != nil {
+		return fmt.Errorf("mailer: feld %q: %w", name, err)
+	}
+	h.buf = append(h.buf, name...)
+	h.buf = append(h.buf, ':', ' ')
+	h.buf = append(h.buf, value...)
+	h.buf = append(h.buf, '\r', '\n')
+	return nil
+}
+
+func (h *headerWriter) Bytes() []byte { return h.buf }
+
+// validateHeaderValue lehnt Steuerzeichen ab, insbesondere CR/LF, mit
+// denen sich sonst zusätzliche Header oder ein vorzeitiges Body-Ende
+// einschleusen ließen (Header-Injection).
+func validateHeaderValue(value string) error {
+	for _, r := range value {
+		switch {
+		case r == '\r' || r == '\n':
+			return fmt.Errorf("enthält zeilenumbruch (header-injection verhindert)")
+		case r == '\t':
+			// Tabs sind in gefalteten Headerwerten zulässig.
+		case r < 0x20:
+			return fmt.Errorf("enthält steuerzeichen 0x%02x", r)
+		}
+	}
+	return nil
+}
@@ -0,0 +1,126 @@
+// Package mailer implementiert ING-03s Mailer-Komponente für ausgehende
+// Benachrichtigungen/Berichte: Nachrichtenaufbau ausschließlich über
+// eine strukturierte Header-Writer-API (header.go, Akzeptanzkriterium
+// 2) sowie Versand per echtem SMTP-Dialog.
+package mailer
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"net"
+	"net/smtp"
+	"strings"
+	"time"
+)
+
+// Message ist eine ausgehende Nachricht.
+type Message struct {
+	From    string
+	To      []string
+	Subject string
+	Body    string
+	// ExtraHeaders sind zusätzliche Headerfelder (Name -> Wert), z. B.
+	// "Reply-To". Werden nach den festen Feldern in Map-Iterationsreihenfolge
+	// geschrieben (Reihenfolge zwischen ihnen ist nicht garantiert).
+	ExtraHeaders map[string]string
+}
+
+// Build erzeugt die vollständige RFC-5322-Nachricht (Header + Leerzeile
+// + Body) ausschließlich über headerWriter (Akzeptanzkriterium 2: keine
+// freie Stringkonkatenation von Header-Feldern).
+func (m Message) Build() ([]byte, error) {
+	hw := &headerWriter{}
+	if err := hw.WriteField("From", m.From); err != nil {
+		return nil, err
+	}
+	if err := hw.WriteField("To", strings.Join(m.To, ", ")); err != nil {
+		return nil, err
+	}
+	if err := hw.WriteField("Subject", m.Subject); err != nil {
+		return nil, err
+	}
+	for name, value := range m.ExtraHeaders {
+		if err := hw.WriteField(name, value); err != nil {
+			return nil, err
+		}
+	}
+
+	var buf bytes.Buffer
+	buf.Write(hw.Bytes())
+	buf.WriteString("\r\n")
+	buf.WriteString(m.Body)
+	return buf.Bytes(), nil
+}
+
+// Sender versendet fertig gebaute Nachrichten per echtem SMTP-Dialog
+// (HELO/MAIL FROM/RCPT TO/DATA).
+type Sender struct {
+	// Addr ist die SMTP-Serveradresse (host:port). Ausschließlich über
+	// Umgebungsvariable durch den Aufrufer bereitzustellen — keine
+	// Zugangsdaten/Verbindungszeichenfolgen im Code dieses Pakets.
+	Addr    string
+	Timeout time.Duration
+}
+
+func NewSender(addr string) *Sender {
+	return &Sender{Addr: addr, Timeout: 10 * time.Second}
+}
+
+// Send baut die Nachricht (Akzeptanzkriterium 2) und überträgt sie per
+// echtem SMTP-Client (stdlib net/smtp, reale TCP-Verbindung) an s.Addr.
+// Ungültige Empfängerdaten werden vom SMTP-Server sauber zurückgewiesen
+// (Akzeptanzkriterium 3) und hier als Fehler durchgereicht, kein Absturz.
+func (s *Sender) Send(ctx context.Context, m Message) error {
+	if len(m.To) == 0 {
+		return fmt.Errorf("mailer: kein empfänger")
+	}
+	raw, err := m.Build()
+	if err != nil {
+		return fmt.Errorf("mailer: nachricht aufbauen: %w", err)
+	}
+
+	dialer := net.Dialer{Timeout: s.Timeout}
+	conn, err := dialer.DialContext(ctx, "tcp", s.Addr)
+	if err != nil {
+		return fmt.Errorf("mailer: verbindung zu %s: %w", s.Addr, err)
+	}
+	defer func() { _ = conn.Close() }()
+
+	client, err := smtp.NewClient(conn, hostOnly(s.Addr))
+	if err != nil {
+		return fmt.Errorf("mailer: smtp-client: %w", err)
+	}
+	defer func() { _ = client.Close() }()
+
+	if err := client.Hello("nexarch-mail"); err != nil {
+		return fmt.Errorf("mailer: HELO: %w", err)
+	}
+	if err := client.Mail(m.From); err != nil {
+		return fmt.Errorf("mailer: MAIL FROM: %w", err)
+	}
+	for _, rcpt := range m.To {
+		if err := client.Rcpt(rcpt); err != nil {
+			return fmt.Errorf("mailer: RCPT TO %s: %w", rcpt, err)
+		}
+	}
+	wc, err := client.Data()
+	if err != nil {
+		return fmt.Errorf("mailer: DATA: %w", err)
+	}
+	if _, err := wc.Write(raw); err != nil {
+		return fmt.Errorf("mailer: nachricht senden: %w", err)
+	}
+	if err := wc.Close(); err != nil {
+		return fmt.Errorf("mailer: nachricht abschließen: %w", err)
+	}
+	return client.Quit()
+}
+
+func hostOnly(addr string) string {
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil {
+		return addr
+	}
+	return host
+}
@@ -0,0 +1,191 @@
+package mailer
+
+import (
+	"context"
+	"net"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.perlbach24.de/scripte/nexarch/mail/internal/smtp"
+)
+
+// TestHeaderWriter_RejectsControlCharsAndCRLFInSubjectAndDisplayName
+// ist die geforderte Pflichtprüfung 1 (ING-03): Steuerzeichen/CRLF in
+// Betreff und Anzeigenamen schlagen fehl statt einen Header-Bruch zu
+// erzeugen (bekannter Fehler aus archivmail, known-issues-archivmail.md
+// #1).
+func TestHeaderWriter_RejectsControlCharsAndCRLFInSubjectAndDisplayName(t *testing.T) {
+	cases := []struct {
+		name string
+		msg  Message
+	}{
+		{
+			name: "CRLF im Betreff schleust zusätzlichen Header ein",
+			msg: Message{
+				From:    "absender@example.com",
+				To:      []string{"empfaenger@example.com"},
+				Subject: "Harmlos\r\nBcc: angreifer@example.com",
+				Body:    "Hallo",
+			},
+		},
+		{
+			name: "CRLF im Anzeigenamen des Absenders",
+			msg: Message{
+				From:    "\"Böser Name\r\nX-Injected: true\" <absender@example.com>",
+				To:      []string{"empfaenger@example.com"},
+				Subject: "Normal",
+				Body:    "Hallo",
+			},
+		},
+		{
+			name: "nackter LF ohne CR",
+			msg: Message{
+				From:    "absender@example.com",
+				To:      []string{"empfaenger@example.com"},
+				Subject: "Betreff\nBcc: angreifer@example.com",
+				Body:    "Hallo",
+			},
+		},
+		{
+			name: "Steuerzeichen NUL im Betreff",
+			msg: Message{
+				From:    "absender@example.com",
+				To:      []string{"empfaenger@example.com"},
+				Subject: "Betreff\x00Ende",
+				Body:    "Hallo",
+			},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			raw, err := tc.msg.Build()
+			if err == nil {
+				t.Fatalf("erwartete Fehler (Header-Injection verhindert), habe erfolgreich gebaute Nachricht: %q", raw)
+			}
+		})
+	}
+}
+
+// TestHeaderWriter_AcceptsCleanValues stellt sicher, dass normale Werte
+// nicht fälschlich abgelehnt werden.
+func TestHeaderWriter_AcceptsCleanValues(t *testing.T) {
+	msg := Message{
+		From:    "Absender Name <absender@example.com>",
+		To:      []string{"empfaenger@example.com"},
+		Subject: "Ganz normaler Betreff mit Umlauten äöü",
+		Body:    "Hallo Welt",
+	}
+	raw, err := msg.Build()
+	if err != nil {
+		t.Fatalf("unerwarteter fehler: %v", err)
+	}
+	if !strings.Contains(string(raw), "Subject: Ganz normaler Betreff mit Umlauten äöü\r\n") {
+		t.Fatalf("subject-header fehlt oder falsch formatiert: %q", raw)
+	}
+}
+
+// captureSink zeichnet die zuletzt vom SMTP-Server angenommene
+// Nachricht auf.
+type captureSink struct {
+	envelope smtp.Envelope
+	raw      []byte
+	got      chan struct{}
+}
+
+func newCaptureSink() *captureSink {
+	return &captureSink{got: make(chan struct{}, 1)}
+}
+
+func (c *captureSink) Accept(_ context.Context, envelope smtp.Envelope, raw []byte) error {
+	c.envelope = envelope
+	c.raw = raw
+	c.got <- struct{}{}
+	return nil
+}
+
+// TestSender_SendRealMessageOverSMTP_HeaderIntegrity ist die geforderte
+// Pflichtprüfung 2 (ING-03): automatisierter Test sendet eine Testmail
+// über einen echten SMTP-Dialog und prüft Header-Integrität.
+//
+// Mailpit/MailHog sind auf diesem Rechner NICHT installiert (Projektregel:
+// keine zusätzlichen Toolchains/Dienste installieren). Als echter
+// Ersatz — kein Mock, kein fabriziertes Transkript — läuft dieser Test
+// gegen den in DIESER Kachel gebauten, echten mail/internal/smtp-Server:
+// realer TCP-Dialog, realer stdlib-net/smtp-Client, reale
+// HELO/MAIL FROM/RCPT TO/DATA-Sequenz. Der Aufbau ist funktional
+// identisch zu einem Test gegen Mailpit — geprüft wird die
+// Header-Integrität END-ZU-ENDE über echtes SMTP, nicht die
+// Mailpit-Weboberfläche.
+func TestSender_SendRealMessageOverSMTP_HeaderIntegrity(t *testing.T) {
+	sink := newCaptureSink()
+	srv := smtp.NewServer(sink)
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listener: %v", err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		_ = srv.Serve(ctx, listener)
+		close(done)
+	}()
+	defer func() {
+		cancel()
+		<-done
+	}()
+
+	sender := NewSender(listener.Addr().String())
+	msg := Message{
+		From:    "absender@example.com",
+		To:      []string{"empfaenger@example.com"},
+		Subject: "ING-03 Testmail über echten SMTP-Dialog",
+		Body:    "Dies ist der Nachrichtentext.\r\n",
+		ExtraHeaders: map[string]string{
+			"X-NEXARCH-Test": "ING-03",
+		},
+	}
+
+	sendCtx, sendCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer sendCancel()
+	if err := sender.Send(sendCtx, msg); err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+
+	select {
+	case <-sink.got:
+	case <-time.After(3 * time.Second):
+		t.Fatal("smtp-server hat die nachricht nicht innerhalb der frist angenommen")
+	}
+
+	if sink.envelope.From != msg.From {
+		t.Fatalf("envelope-from stimmt nicht: habe %q, will %q", sink.envelope.From, msg.From)
+	}
+	if len(sink.envelope.To) != 1 || sink.envelope.To[0] != msg.To[0] {
+		t.Fatalf("envelope-to stimmt nicht: habe %v, will %v", sink.envelope.To, msg.To)
+	}
+
+	rawText := string(sink.raw)
+	wantHeaders := []string{
+		"From: " + msg.From + "\r\n",
+		"To: " + msg.To[0] + "\r\n",
+		"Subject: " + msg.Subject + "\r\n",
+		"X-NEXARCH-Test: ING-03\r\n",
+	}
+	for _, want := range wantHeaders {
+		if !strings.Contains(rawText, want) {
+			t.Fatalf("header-integrität verletzt: erwartete zeile %q nicht in empfangener nachricht:\n%s", want, rawText)
+		}
+	}
+	if !strings.Contains(rawText, "Dies ist der Nachrichtentext.") {
+		t.Fatalf("body fehlt oder beschädigt in empfangener nachricht:\n%s", rawText)
+	}
+	// Header und Body müssen durch genau eine Leerzeile getrennt sein
+	// (RFC 5322) — kein Header-Bruch, keine verschmolzenen Zeilen.
+	headerEnd := strings.Index(rawText, "\r\n\r\n")
+	if headerEnd < 0 {
+		t.Fatalf("keine header/body-trennzeile gefunden:\n%s", rawText)
+	}
+}