Files
pages/docs/design/smtp-magic-link-hardening.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

4.3 KiB

SMTP magic-link delivery bounds

Implemented: 2026-09-14.

Request and verification

/_/auth/magic-link accepts POST only and limits the form body to 64 KiB. Unknown accounts, malformed mailbox values, disabled providers, invalid mail configuration, and a full delivery queue all receive the same ordinary submitted-request page. Invalid/oversized form encoding is a generic 400.

Sender and recipient each pass single-mailbox parsing and explicit CR/LF/NUL rejection. SMTP envelope addresses use the parsed mailbox, while message headers use its safely serialized display form. Neither raw user input nor configured display names are concatenated directly into mail headers. The SMTP endpoint must be a host plus numeric TCP port; IPv6 brackets are supported.

The two existing delivery slots are acquired without waiting, before a new challenge is written. Accepted challenges remain Domain-scoped, hash-only, one-use tokens with fifteen-minute expiry. Their payload now records the current recipient email in addition to the safe return Path.

/_/auth/magic-link/verify accepts GET only, consumes the challenge once, and then checks that the provider remains enabled, the Principal is active or readonly, Domain membership is active, and the account email still matches the delivered challenge. Email changes, suspended/quarantined accounts, suspended/removed membership, disabled providers, and replay are rejected with one generic invalid/expired response. The common browser-session issuance path also checks Principal and membership state atomically when inserting a session. Pending links from the earlier email-unbound challenge format must be requested again after this change.

Both endpoints return Cache-Control: no-store. No raw SMTP response, recipient address, password, message body, or login URL is logged.

Delivery

Delivery uses the existing Go SMTP client over an explicitly managed connection instead of the unbounded convenience smtp.SendMail call:

  • Three-second context-aware dial timeout.
  • Ten-second total delivery deadline, covering greeting, EHLO, STARTTLS, authentication, envelope commands, DATA acknowledgement, and QUIT.
  • Context cancellation closes the underlying connection immediately.
  • At most 256 KiB of inbound connection data, including TLS negotiation, prevents a malicious multiline SMTP reply from growing without bound.
  • Every completion/error path closes the connection and releases the slot.
  • STARTTLS is used whenever advertised, with certificate/hostname verification and TLS 1.2 minimum. Failed advertised TLS never falls back to plaintext.
  • Password authentication requires TLS even for a localhost server. PLAIN authentication is not sent over an unencrypted channel.

Mailbox serialization and STARTTLS behavior use the Go standard library's mail parser and SMTP client; there is no new dependency or external mail-service integration.

Remaining policy decisions

Unauthenticated relays without STARTTLS retain the earlier plaintext behavior. Deployments must provide a trusted local relay or a TLS-capable SMTP endpoint; transport-wide mandatory TLS / explicit relay exceptions are a future setting. Implicit SMTPS on port 465, custom CA configuration, OAuth SMTP authentication, durable retries, delivery status/audit UI, and per-account/source abuse quotas are not implemented by this hardening slice. Admission slots bound concurrent work, not request rates. A failed admitted delivery leaves an inaccessible hashed challenge until normal expiry/cleanup.

Magic links are bearer challenges intentionally usable on another device; browser-bound OIDC state cookies are not reused for this flow. A dedicated confirmation screen to mitigate link-scanner consumption is separate work.

Tests

Local fake SMTP servers verify successful STARTTLS delivery and safe envelope serialization, refusal of plaintext credentials/untrusted certificates, timeouts at greeting/EHLO/DATA/QUIT, oversized responses, mailbox/header/link injection rejection, and background-slot release. HTTP/store fixtures cover generic request responses, form bounds, full queues, account/membership/email/ provider changes, active/readonly success, and challenge replay.

go test -race ./internal/server -run 'TestSMTP|TestMagicLink' -count=1