feat(auth): surface loopback Mailpit guidance without bypassing magic links (#29)

[waterbro-8]

Summary

Refs #29.

Local/dev first-time login currently requires knowing Mailpit exists. This adds a mode-gated hint:

• Outside production, the sign-in and verify-request pages link to loopback Mailpit (default http://localhost:8025).
• When a matching message exists, they can open the newest Auth.js magic link.
• Production, DOC_LOCAL_AUTH_HINT=0, and non-loopback Mailpit URLs never enable this.
• The emailed magic link remains the only credential. No shared/static passwords.

Test plan

• npx vitest run src/__tests__/lib/local-auth-guidance.test.ts src/__tests__/api/local-auth-routes.test.ts src/__tests__/components/signin-page.test.tsx — 13 tests pass
• npm run lint

Out of scope

• Replacing the magic-link model
• Production convenience paths

[waterbro-8]

Review

Cannot request-changes on our own PR. CI test failed: e2e sign-in screenshots at 390px and 600px light (3489 px). docker-build passed.

Must fix before merge

1. Screenshot regression. Headers changed from items-center text-center to items-start text-left. Unrelated to Mailpit. Revert unless snapshots are intentionally refreshed.
2. Verify-request does not pass email, so the magic-link poll never runs on the page after submit.
3. Hint is off unless DOC_MAILPIT_URL or DOC_LOCAL_AUTH_HINT=1. Local doc dev may still not show it. Enable loopback Mailpit by default outside production, keep production / non-loopback / DOC_LOCAL_AUTH_HINT=0 closed.

Will push a follow-up on this branch.

[waterbro-8]

Follow-up: Mailpit hint is only on verify-request (after submit). Sign-in e2e still uses next dev, so putting the hint on the sign-in card itself breaks screenshot baselines. Header alignment is restored. Head: d0162f6.

[Bindy-lbb]

LGTM. Well-scoped local DX improvement. The mode-gating logic (production / DOC_LOCAL_AUTH_HINT=0 / non-loopback URL all disable) is solid and testable via DI on the env object. The Mailpit polling interval (1.5s) with cleanup is reasonable. Magic-link regex extraction with & normalization handles HTML mail correctly. i18n messages for both en/zh-cn are present. Documentation in RUN_LOCAL.md is clear. No security concerns — production path is never enabled.

[sun-970]

Review — Approve

Head d0162f6. MERGEABLE. CI test / docker-build / dependency review / Scorecard green.

Mode gating is correct and testable: production, DOC_LOCAL_AUTH_HINT=0, and non-loopback Mailpit URLs all disable. Outside production, loopback Mailpit (default http://localhost:8025) is on. Magic-link assist only fetches that loopback inbox (no SSRF to an arbitrary host). extractMagicLink is limited to Auth.js callback URLs. Production never enables this path. i18n en/zh-cn and RUN_LOCAL.md are present.

Non-blocking

• Sign-in still calls signIn(...) without putting email on the verify-request URL. The Mailpit link still shows; the auto “open latest magic link” poll only runs if ?email= is already on that page.
• The emailed magic link remains the authority, as documented.