feat(auth): magic-link sign-in and a rotating-refresh session layer

[dvd90]

Adds passwordless sign-in by emailed link, the session layer every local auth variant now shares, and a module split that lets a project be scaffolded with password auth removed entirely.

Design note: docs/design/magic-link.md — §8 lists the conventions this change had to bend, §9 records where the implementation departed from the plan.

The module split

chassis:jwt bundled four unrelated things — password hashing, JWT minting, the user store and the web sign-in form. So magic-link auth could not be added without inheriting passwords, and passwords could not be removed without losing the session layer with them.

It becomes three implied modules composed by auth variants:

--auth	Sign in with	Implies
jwt	email + password	session, password
magic-only	emailed link or code	session, magic
password+magic	either	session, password, magic

implies is necessary rather than stylistic: a file may be claimed by exactly one module (the catalog test enforces it), so password+magic — needing the union of two file sets — cannot be expressed as a flat files list. jwt keeps its name, so --auth jwt, all four presets, the already-published create-chassis and the catalog-derived chassis-mcp schema keep working unchanged.

Magic link

• GET and HEAD never consume a token. Mail security scanners prefetch links, and a single-use token burned by a scanner is how this feature usually breaks in production. The link renders a confirmation page; redemption is a POST, on a click.
• Every email carries a six-digit code too, so someone who requests on a laptop and reads their mail on a phone can still finish on the laptop.
• The request endpoint reveals nothing. 202 with a byte-identical body for every address, sent before the store is touched, so neither the body nor the timing distinguishes a known address from an unknown one.
• Nothing is stored in the clear. SHA-256 at rest for both credentials; codes compare in constant time and are capped, after which the link dies with them. Issuing voids everything outstanding for that address.
• returnTo cannot become an open redirect. Validated at issue, stored server-side, re-validated at redemption, deny-by-default against RFC 3986 path characters. The browser never gets to post one back.

Sessions

15-minute access token plus a refresh token rotated on every use. Replaying a spent token revokes the entire family — the only thing that catches a stolen refresh token at all. Sliding SESSION_IDLE (30d) inside a hard SESSION_ABSOLUTE cap (90d), both read through an injected clock, so the 91-day behaviour is tested in microseconds. POST /auth/refresh, /auth/logout (idempotent), /auth/revoke-all.

Delivery is a seam, not a binding

MailTransport ships a console logger and SMTP (mailpit). SmsTransport ships nothing and stays silent until a product binds both a gateway and a recipient resolver — which is why this adds no phone column and no channel switch. Resend, SendGrid, SES, Postmark, Twilio, Vonage, SNS and MessageBird are documented ten-line bindings in docs/guides/transports.md and nothing more.

Proving an address sets verified_at and fires setOnVerified(). That is the whole extension surface: no consent machinery, no double opt-in, no GDPR copy.

A bug this found

POST /api/session proxied to the API's /auth/login, which does not exist in a magic-only project. Sign-in is now per-method (/api/session/password, /api/session/magic) and /api/session keeps only what they share: turning an API response into cookies, and signing out.

Pipeline

• assertNoModuleResidue holds password, magic and session to the same standard, rather than special-casing one grep. It caught the bug above and eleven pieces of prose that would have shipped into projects that had pruned the module they described.
• A new invariant keeps chassis: markers out of .tsx, where neither the pruner nor the residue grep in published.yml can see them. The two sign-in forms sit behind a marked .ts registry instead.
• The scaffold matrix picks the three variants up from the catalog automatically; three stacks were added to the SCAFFOLD_BUILD layer.
• A mail-e2e job (marked chassis:magic, so generated magic projects inherit it) runs the flow against real SMTP.

Verification

npm run verify (138 + 16), npm run build, node --test cli/*.test.mjs (96), npm run check --prefix site, npm test --prefix mcp-server (9) — all green.

A scaffolded --auth magic-only --db postgres project installs, runs its own 116 tests, and builds. The mailpit e2e ran against real SMTP end to end: request → email carrying link and code → two GETs and a HEAD leaving the token redeemable → POST redeem → session → 20-day gap → silent refresh → day 91 → forced re-auth.

One deviation worth a look

rg -i password on a generated magic-only app returns POSTGRES_PASSWORD (the database's own credential, correctly kept) plus two docs — docs/modules.md and docs/reference/cli.md. Those describe the scaffolder itself, so naming variants you did not pick is their job, and one variant is literally called password+magic. That is the same reason .md is already exempt from marker pruning. Everything else — code, config, env and all other prose — is scanned. If you want the criterion to hold with zero exemptions, renaming that variant is the change that gets you there.

🤖 Generated with Claude Code