Files
pages/docs/design/smtp-magic-link-hardening.md
T
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

85 lines
4.3 KiB
Markdown

# 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](https://pkg.go.dev/net/mail#ParseAddress) and
[SMTP client](https://pkg.go.dev/net/smtp#Client.StartTLS); 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.
```sh
go test -race ./internal/server -run 'TestSMTP|TestMagicLink' -count=1
```