WebAuthn / Passkey 实现规则
# WebAuthn / Passkey 实现规则
## 必须使用的库
- 禁止手写任何 CBOR/COSE 解析或签名验证逻辑。
- 服务端使用当前维护的 WebAuthn 库(如 Node.js 的 @simplewebauthn/server)。
- 客户端使用配套的浏览器库(如 @simplewebauthn/browser),但必须直接调用原生 navigator.credentials API,不得用第三方库完全包裹。
## 服务端验证的强制检查项(每一步都必须存在)
1. 验证响应中的 origin 与预期的生产 origin 完全匹配。
2. 验证响应中的 rpIdHash 与预期的 RP ID 匹配。
3. 验证 challenge 与本次会话中存储的 challenge 一致,且只能使用一次。
4. 验证签名,使用数据库中存储的该凭据的公钥。
5. 检查 userVerification 标志,要求用户完成本地验证(指纹/面容/PIN)。
## 数据存储
- 凭据必须存入独立的数据表,字段至少包括:credentialId、publicKey、signCount、userId、transports、deviceInfo。
- 禁止将私钥或任何可推导私钥的信息存入服务器。
## 安全上下文
- 生产环境必须 HTTPS。
- 本地开发允许 http://localhost,但生产 origin 必须显式配置,不得依赖运行时推断。