feat(auth): reduce login hop friction without lowering the security bar

[PeterGuy326]

schemaVersion: requirement-record.v1
revision: R1
status: needs-design
priority: P1
productOwner: "@PeterGuy326"
technicalOwner: "unassigned"
userOutcome: "A non-technical first-time user completes doc login with fewer cognitive hops, while the magic-link security model remains the authoritative mechanism."
requirements:
  - REQ-001
  - REQ-002
acceptanceCriteria:
  - AC-001
  - AC-002
parent: null
dependencies: []
supersedes: []
lastDecisionAt: null

User problem and observable outcome

Ops dogfood (2026-08-29): login requires email → Mailpit(8025) retrieval of the magic link → return to 3100; a first-time non-technical user must understand what Mailpit is before logging in. Multi-hop friction is real; the security model (magic link via mail) is not itself the defect. Design space intentionally left open at needs-design.

Requirements

• REQ-001: Hop reduction within the security baseline — reduce the cognitive hops of first-time login (design space: dev/local-mode link surfacing, first-run guidance, or equivalent) without weakening the magic-link mechanism or introducing shared/static credentials.
• REQ-002: Security baseline unchanged — no new credential surface, no bypass of the mail-verification flow; any convenience path is mode-gated and documented as such.

Acceptance criteria

• AC-001: Acceptance anchor — a non-technical user completes login within the documented reduced-hop path (step count defined at design time); magic link remains the authority.
• AC-002: Security fixture — the convenience path introduces no bypass; mode gating asserted.

Non-goals and forbidden shortcuts

• No replacement of the magic-link model; no shared/static credentials; no production-mode convenience that lowers the security bar.

Lifecycle, status, priority, blockers, and open decisions

• status=needs-design; priority P1; technicalOwner unassigned; design space open (mechanism to be proposed).
• Blockers: none.

Evidence plan

• Design-time definition of the hop-count anchor; security fixtures.

Decisions

• DEC-DOC-29-001 (2026-08-29T02:26:00Z): issue created per founder-approved dogfood intake (2026-08-29); design space deliberately open; security baseline frozen as a requirement, not a goal.

Revision history

• R1 (2026-08-29T02:26:00Z): initial record created per founder-approved draft D (dogfood P1 login hop reduction).

[waterbro-8]

Proposed reduced-hop path for local/dev (does not lower the production security bar):

• Outside production, sign-in and verify-request show a loopback Mailpit link (default http://localhost:8025).
• If Mailpit already has a matching message, the page can open the newest Auth.js callback.
• Disabled in production, when DOC_LOCAL_AUTH_HINT=0, and when Mailpit is not loopback.
• Magic link remains the authority; no shared/static credentials.

PR: #75

[waterbro-8]

Reduced-hop local/dev path is in open PR #75 (feat/auth: surface loopback Mailpit guidance without bypassing magic links). Production magic-link remains the authority. I am not opening a duplicate.

[waterbro-8]

平台组分工补派（冯浩然 / waterbro-8）

• 跟进人：崔泽生（GitHub xiaocui-big，仓库暂不能指派，以钉钉+本评论为准）
• 仓库：bytefolk/doc feat(auth): reduce login hop friction without lowering the security bar #29
• 动作：现在提 PR
• 说明：减少登录 hop 且不降安全水位，按 issue 提 PR
• 流程：fork 后提 PR，标题带 feat(auth): reduce login hop friction without lowering the security bar #29，然后 @waterbro-8 审核。我不能合自己的 CODEOWNER PR。

[waterbro-8]

平台组群成员派活（冯浩然 / waterbro-8）

• 跟进人：崔泽生（钉钉平台组；本仓库可能无法 GitHub 指派，以钉钉+本评论为准）
• 仓库：bytefolk/doc feat(auth): reduce login hop friction without lowering the security bar #29
• 动作：现在提 PR
• 说明：减少登录 hop 且不降安全水位，直接提 PR
• 流程：有 GitHub 权限就直接开 PR；没有就 fork 后提。标题带 feat(auth): reduce login hop friction without lowering the security bar #29。提完 @waterbro-8 审核。
• 李彬彬这批不用做。

[waterbro-8]

验收结论：已由 PR #75 完成并合入 main（merge commit 2234019）。最终 head 2be1779 已获正式 Approve，hosted checks 全绿；仅 local/dev loopback 展示 Mailpit 引导，production、显式关闭和非 loopback 均 fail closed，magic link 仍是唯一凭据。该 issue 已满足，可关闭。