用途:在实现或审查前端认证流程时使用,包括登录、注册、密码重置、邮箱验证、一次性验证码登录、Passkey 注册与认证、认证回调以及敏感账户操作。核心观点是认证 UI 是浏览器与后端之间的契约,不只是表单。
主要能力:
- 认证跳转:保留用户原定目标,但在恢复前校验 returnTo/next/callback 目标,避免开放重定向。
- 密码表单:不要静默 trim/规范化/清洗凭据,使用正确的 autocomplete 并给出通用登录错误。
- 邮箱与验证码流程:展示过期/重试/重发状态,设置 autocomplete="one-time-code",并叠加 WebOTP API 以支持 Android Chrome 短信取码;避免账户枚举。
- Passkeys/WebAuthn:使用服务端挑战、特性检测、条件调解回退(其 promise 可能长期挂起,绝不能阻塞登录 UI),并加 passkey autofill 提示。
- 敏感操作:在更改密码/邮箱/Passkey 等破坏性操作前要求新鲜身份验证。
- 测试:冷 URL 直达认证页、可访问错误、autocomplete 属性、非法 return 拒绝、过期验证码与 passkey 取消路径。
使用方式:默认工作流为先识别流程,再在改动前定义浏览器可见契约(URL 输入、允许的返回目标、表单字段/autocomplete、pending/expired/retry 状态、错误文案、回退路径),然后添加从冷 URL 进入、断言可访问表单与错误语义并覆盖失败状态的测试,最后在 UI 契约中明确后端约束(服务端挑战、一次性验证码失效、限流/重试窗口、高风险操作的新鲜验证)。详细清单见 references/browser-auth-contracts.md。
适用场景:认证流程中回跳目标丢失或不安全、凭据/autocomplete 行为错误、可枚举错误、过期/重试状态无恢复、passkey 回退失败、敏感操作缺少新鲜验证等浏览器可见的契约失败。
限制与边界:不处理 token 存储、Cookie、SameSite、CSRF、CSP、XSS、source map 等安全原语(由 frontend-security-baseline 负责);不处理通用路由就绪与 URL 到屏幕重建(由 deeplink-hydration 负责);不处理通用角色/名称/焦点语义(由 a11y-contract-testing 负责);不处理原生 HTML 表单校验接线(由 constraint-validation-contracts 负责);不实现后端密码学(Argon2/Bcrypt、CBOR、ECDSA/RSA/EdDSA、会话令牌存储为服务端细节),只将其转换为过期、重试、挑战和回退等前端契约。
参考来源:OWASP 认证、CSRF 与会话管理备忘单,W3C WebAuthn Level 2,NIST SP 800-63B-4,MDN Web Authentication API、HTML autocomplete 属性与 WebOTP API。