WebAuthn 无密码认证与 Passkey 实践

注册时：
  用户的认证器（安全密钥/手机/系统钥匙串）生成一对密钥
  私钥：永不出设备，只在本机签名
  公钥：发给服务器保存

登录时：
  服务器给一个随机挑战（challenge）
  认证器用私钥对挑战签名
  服务器用公钥验签，确认"私钥确实在用户手里"

对比密码：
  密码：服务器存"能冒充你的东西"，泄露即被盗
  公钥：服务器只存"能验证你的东西"，泄露也冒充不了

协议分层（示意）：

  Web 应用（RP） ↔ WebAuthn API ↔ 浏览器
                                     │
                              CTAP2/平台层
                                     │
                              认证器（私钥保管处）

公钥凭证注册与认证都在这条链上完成，
整个过程中服务器始终只接触公钥与签名结果。

注册时产生：
  id            → 凭证 ID（对应认证器里那把私钥）
  response.attestationObject → 注册信息（含公钥、认证器元数据）
  response.clientDataJSON    → 包含来源 origin、挑战 challenge

登录时产生：
  id            → 凭证 ID
  response.authenticatorData → 认证器输出（含签名计数、来源）
  response.signature        → 私钥对挑战的签名
  response.clientDataJSON   → 包含 origin 与挑战

// 服务端生成注册选项（伪代码）
function registrationOptions(user) {
  return {
    challenge: generateRandomChallenge(),      // 一次性随机挑战
    rp: { id: "example.com", name: "示例站" },  // 依赖方标识
    user: {
      id: encodeUserId(user.id),               // 用户唯一标识
      name: user.username,
      displayName: user.displayName
    },
    pubKeyCredParams: [
      { type: "public-key", alg: -7 },         // ES256
      { type: "public-key", alg: -257 }        // RS256
    ],
    timeout: 60000,
    authenticatorSelection: {
      residentKey: "preferred",                // 是否需要可发现凭证
      userVerification: "preferred"            // 是否要求用户验证（指纹等）
    }
  };
}

// 浏览器侧注册
const options = await fetchRegisterOptions();
const publicKey = preparePublicKeyOptions(options);

const credential = await navigator.credentials.create({
  publicKey: publicKey
});

// 把结果交给服务端验签与存储
await fetch('/api/webauthn/register/verify', {
  method: 'POST',
  body: JSON.stringify({
    id: credential.id,
    rawId: arrayToBase64(credential.rawId),
    type: credential.type,
    response: {
      attestationObject: arrayToBase64(credential.response.attestationObject),
      clientDataJSON: arrayToBase64(credential.response.clientDataJSON)
    }
  })
});

注册验证必须检查：
  ① clientDataJSON 里的 origin 必须等于你声明的站点来源
  ② challenge 必须等于刚才发的那一个，且一次性
  ③ 解析 attestationObject，取出公钥与凭证 ID
  ④ 按安全级别决定是否验证"认证器证明"（attestation）
  ⑤ 存储：凭证 ID + 公钥 + 签名计数器（初始值）
常见坑：
  · 忘记校验 origin/challenge → 凭证可被跨站注册
  · 挑战可复用 → 重放攻击
  · 公钥不校验算法白名单 → 可能接受弱算法

// 服务端生成认证选项（伪代码）
function authenticationOptions(user) {
  return {
    challenge: generateRandomChallenge(),
    rpId: "example.com",
    allowCredentials: [                       // 允许的凭证白名单
      { id: getCredentialId(user), type: "public-key" }
    ],
    userVerification: "preferred",
    timeout: 60000
  };
}

// 浏览器侧认证
const options = await fetchAuthOptions();
const credential = await navigator.credentials.get({
  publicKey: prepareAuthOptions(options)
});

await fetch('/api/webauthn/login/verify', {
  method: 'POST',
  body: JSON.stringify({
    id: credential.id,
    type: credential.type,
    response: {
      authenticatorData: arrayToBase64(credential.response.authenticatorData),
      signature: arrayToBase64(credential.response.signature),
      clientDataJSON: arrayToBase64(credential.response.clientDataJSON)
    }
  })
});

认证验证必须检查（按顺序）：
  ① 凭证 ID 是否存在于库中
  ② clientDataJSON 的 origin 与 challenge 校验
  ③ 从 authenticatorData 解析来源 rpIdHash，必须等于你的站点
  ④ 用存储的公钥验证 signature
  ⑤ 检查签名计数器：新计数必须大于旧计数（防克隆）

一次性挑战 + 签名：即使攻击者截获认证响应，
也无法重放，因为 challenge 已失效、origin 不匹配。

钓鱼页面伪造 example.com 的登录页，诱导用户"验证"：

  真 WebAuthn：
    认证器签名的是"挑战 + 真实 origin(example.com)"
    钓鱼页 origin 是 attacker.com，验签必然失败
    私钥绑定站点，绝不替 attacker.com 签名

对比密码：
    钓鱼页只需拿到密码字符串，到真站就能用
    WebAuthn 的凭证永远绑死一个 rpId，跨站即失效

· 恶意软件本地键盘记录：键盘记录器拿不到私钥，但可能截获其他输入
· 用户恶意授权：社会工程诱骗用户"亲自"在真站签名，仍需用户意识
· 认证器自身安全：受信任平台与设备须保持系统更新
· 恢复过程：找回流程若退化为"邮箱 + 密码"，仍是攻击入口

无密码最大的工程风险是"用户换了设备就登不进去"。
恢复策略：
  ① 多凭证：同一账号绑定多个认证器（手机 + 安全密钥）
  ② 同步通行密钥：用系统云同步（iCloud/Google）保留 Passkey
  ③ 备用因子：保留 TOTP/恢复码作为降级手段
  ④ 可验证的找回流程：找回必须经过同等强度的验证
提示：
  · 不要设计"通过密码重置"这种与无密码背道而驰的后门
  · 恢复码一次性、加密存储，与凭证强度匹配

□ origin 校验严格，站点来源白名单
□ challenge 一次性、过期短
□ 签名计数器持久化并递增校验
□ 支持多凭证管理与展示
□ 提供备用登录途径与恢复流程
□ 日志审计：认证成功/失败、凭证变更留痕
□ 合规：生物识别数据本地处理，不入服务端

Passkey 同步（如 iCloud 钥匙串、Google 密码管理器）：
  私钥在设备上生成，通过端到端加密同步到同一生态的其他设备
  服务器仍是只存公钥，同步只在用户自己的生态内发生

企业/高安全场景：
  可关闭"同步 Passkey"，强制使用独立漫游密钥
  用策略控制：是否允许可发现凭证、是否要求用户验证
  通过强制验证（userVerification: required）保证"人在设备前"

· 平台覆盖：主流浏览器均已支持 WebAuthn，但历史版本有差异
· 降级路径：老浏览器/老设备保留密码或 TOTP 兜底
· 证书方案：内部系统可借助 FIDO2 设备实现无密码桌面登录
· 迁移成本：从密码迁移建议"先并跑、再逐步收紧"