nodewarden/docs/passkey-login-research.md

# NodeWarden Passkey 登录研究记录

记录日期：2026-06-09  
研究范围：NodeWarden 自己的 server、web 登录/注册链路，以及官方 Bitwarden server、web、browser extension 对账户 passkey 登录的实现方式。

## 结论先放前面

NodeWarden 现在已经有完整的主密码注册、主密码登录、刷新 token、2FA、设备记录、官方客户端兼容的 `UserDecryptionOptions`，也支持 vault item 里的 `login.fido2Credentials` 字段。但它还没有“账户 passkey 登录”。现有 `src/utils/passkey.ts` 只有 base64url、challenge、clientData 解析这类工具函数，不能完成 FIDO2/WebAuthn 服务端注册和认证验证。

要支持“自己的 web 用 passkey 登录”和“官方/自定义浏览器扩展也能 passkey 登录”，不能只加一个登录按钮。必须补齐四块：

1. Server 端新增账户 WebAuthn credential 表、challenge/token 防重放机制、FIDO2 attestation/assertion 验证、`grant_type=webauthn`。
2. Server 响应里按 Bitwarden 形状返回 PRF 解密材料：登录 token 响应用单个 `UserDecryptionOptions.WebAuthnPrfOption`，sync 响应用多个 `UserDecryption.WebAuthnPrfOptions`。
3. NodeWarden web 新增 passkey 注册、管理、登录和 PRF 解锁 vault key 的客户端流程。
4. 扩展兼容要跟官方 Bitwarden endpoint 和 response shape 对齐。官方 browser extension 当前只在 Chromium 系浏览器开放 passkey 登录，因为 Firefox/Safari 扩展环境还不能按官方代码需要的方式覆盖 RP ID。

下面按代码链路展开。

## 术语边界

这里有三个容易混淆的东西，文档后面严格区分：

- 账户 passkey 登录：用户不用主密码，使用 WebAuthn/passkey 完成账号认证，并且用 PRF 解开 vault user key。官方 Bitwarden 叫 `WebAuthnLogin`。
- Vault item 里的 passkey：某个登录条目保存网站 passkey/FIDO2 credential 数据，对应 NodeWarden 的 `cipher.login.fido2Credentials`。这是“保险库保存别的网站 passkey”，不是“登录 NodeWarden 账号”。
- WebAuthn 2FA：主密码登录之后用安全密钥做第二因素。官方旧 web repo 里主要是这一类，不等于 passkey 登录。

## NodeWarden 现状

### 路由和入口

NodeWarden 后端是 Cloudflare Workers + D1。主入口 `src/index.ts` 初始化存储后进入 router。认证边界在：

- `src/router-public.ts`：公开接口，包含 `/identity/connect/token`、`/identity/accounts/prelogin`、`/api/accounts/register`。
- `src/router-authenticated.ts`：需要 access token 的接口，包含 profile、change password、TOTP、sync、vault、devices。
- `src/handlers/identity.ts`：OAuth/token 兼容入口。
- `src/handlers/accounts.ts`：注册、profile、密码变更、TOTP、API key 等账户接口。

目前公开路由没有：

- `GET /identity/accounts/webauthn/assertion-options`
- `POST /identity/connect/token` 的 `grant_type=webauthn`
- `POST /api/webauthn/attestation-options`
- `POST /api/webauthn/assertion-options`
- `GET/POST/PUT /api/webauthn`

### 注册链路

NodeWarden 自己 web 的注册入口在 `webapp/src/lib/api/auth.ts` 的 `registerAccount()`：

- 使用邮箱作为 salt，用 PBKDF2 派生 master key。
- 再用 PBKDF2(masterKey, password, 1) 得到 client master password hash。
- 随机生成 64 字节 vault symmetric key。
- 用 masterKey 经 HKDF 拆成 enc/mac，把 vault key 加密成 Bitwarden `Key`。
- 生成 RSA-OAEP key pair，把 private key 用 vault symmetric key 加密。
- POST `/api/accounts/register`，提交 `email`、`name`、`masterPasswordHash`、`key`、KDF 参数、invite code、`keys.publicKey`、`keys.encryptedPrivateKey`。

后端 `src/handlers/accounts.ts` 的 `handleRegister()`：

- 第一个用户自动成为 admin，后续用户需要 invite。
- 校验 `JWT_SECRET`、邮箱、KDF 下限、加密字符串形状、公钥/私钥。
- 不直接保存 client hash，而是 `AuthService.hashPasswordServer(masterPasswordHash, email)` 后保存到 `users.master_password_hash`。
- 保存 `users.key`、`users.private_key`、`users.public_key`、KDF 参数、`security_stamp`。

结论：账户 passkey 注册不是替代账号注册，而是“用户已登录后在安全设置里新增一个可登录 credential”。仍然需要已有 vault user key 来生成 PRF keyset。

### 主密码登录链路

NodeWarden 自己 web 的登录入口是 `webapp/src/lib/app-auth.ts` 的 `performPasswordLogin()`：

- 先 `deriveLoginHashLocally()` 得到 masterKey 和 client hash。
- 调 `loginWithPassword()` POST `/identity/connect/token`。
- token 成功后 `completeLogin()` 用 `token.Key` 和本地 masterKey 解开 vault key。
- 保存离线解锁记录。

`webapp/src/lib/api/auth.ts` 也有 `deriveLoginHash()` 和 `getPreloginKdfConfig()` 会调用 `/identity/accounts/prelogin`，但当前 `performPasswordLogin()` 走的是本地 fallback iterations。passkey 登录不应复用这条 masterKey 路径，因为 passkey 登录没有主密码，拿不到 password-derived masterKey。

后端 `src/handlers/identity.ts` 的 `handleToken()` 当前支持：

- `grant_type=password`
- `grant_type=client_credentials`
- `grant_type=refresh_token`

密码登录成功后会：

- 验证 IP 登录频率和用户状态。
- `AuthService.verifyPassword()` 验证 client hash。
- 处理 TOTP 或 remember 2FA token。
- 记录/更新 device。
- 生成 access token 和 refresh token。
- 返回 `Key`、`PrivateKey`、`AccountKeys`、KDF 参数、`UserDecryptionOptions`。

### UserDecryptionOptions 和 sync

NodeWarden 的 `src/utils/user-decryption.ts` 当前只构造主密码解锁：

- `HasMasterPassword: true`
- `MasterPasswordUnlock`
- `TrustedDeviceOption: null`
- `KeyConnectorOption: null`

`src/types/index.ts` 的 sync 类型里预留了 `UserDecryption.WebAuthnPrfOption?: null`，但当前 `src/handlers/sync.ts` 实际只返回 `MasterPasswordUnlock`，没有账户 passkey PRF 解密选项。

passkey 登录必须新增两类 shape：

- 登录 token 响应：`UserDecryptionOptions.WebAuthnPrfOption`，只返回本次认证所用 credential 的 PRF 解密材料。
- sync 响应：`UserDecryption.WebAuthnPrfOptions`，返回该用户所有已启用 PRF keyset 的 passkey 解密材料，供官方客户端锁定/解锁和 key rotation 使用。

### 现有 passkey 相关代码

NodeWarden 已支持 vault item 里的 FIDO2/passkey 字段：

- `src/types/index.ts`：`CipherLogin.fido2Credentials`
- `src/handlers/ciphers.ts`：读写 cipher 时保留/规范化 `fido2Credentials`
- `webapp/src/lib/api/vault.ts`：加密/解密 vault item 内的 `fido2Credentials`
- `webapp/src/lib/types.ts`：`CipherLoginPasskey`

这部分是“保存网站 passkey”，不是账户登录。

`src/utils/passkey.ts` 只有：

- `bytesToBase64Url()`
- `base64UrlToBytes()`
- `randomChallenge()`
- `parseClientDataJSON()`

缺少的核心能力：

- attestation verification
- assertion verification
- authenticator public key 格式处理
- signature verification
- sign counter 更新
- userHandle 与 user id 绑定验证
- origin/RP ID 验证
- challenge 过期和防重放

### 数据库和备份影响

NodeWarden schema 在这些地方需要同步：

- `migrations/0001_init.sql`
- `src/services/storage-schema.ts`
- `wrangler.toml` migrations
- `src/services/backup-archive.ts`
- `src/services/backup-import.ts`
- `shared/backup-schema` 相关类型

当前表里没有账户 passkey credential，也没有 WebAuthn challenge 表。`devices` 表保存设备 trust/key 信息，不适合混入 passkey credential，因为 WebAuthn credential 需要自己的 public key、credential id、counter、AAGUID、PRF keyset 等字段。

## 官方 Bitwarden server 参考

上游代码位置：

- `.codex-upstream/bitwarden-server`
- 研究时 HEAD：`574f3fd`

官方 server 里也有两个 WebAuthn 概念：

- 传统 WebAuthn 2FA：`TwoFactorController`、`WebAuthnTokenProvider`
- 账户 passkey 登录：`WebAuthnLogin`

本项目要参考的是后者。

### 公开 passkey 登录入口

`src/Identity/Controllers/AccountsController.cs`

- `GET /accounts/webauthn/assertion-options`
- 返回 `WebAuthnLoginAssertionOptionsResponseModel`
- response 包含：
  - `options`
  - `token`
- token 使用 `WebAuthnLoginAssertionOptionsTokenable`
- scope 为 `Authentication`
- token 生命周期约 17 分钟

`src/Identity/IdentityServer/RequestValidators/WebAuthnGrantValidator.cs`

- 新增 OAuth extension grant：`grant_type=webauthn`
- 从 form 读取：
  - `token`
  - `deviceResponse`
- 解开 token，校验 scope 必须是 `Authentication`
- 反序列化 `AuthenticatorAssertionRawResponse`
- 调用 `AssertWebAuthnLoginCredential`
- 把成功认证的 credential 传给 `UserDecryptionOptionsBuilder.WithWebAuthnLoginCredential(credential)`
- 之后走通用登录成功逻辑，返回 access/refresh token 和账号加密状态。

`src/Identity/IdentityServer/ApiClient.cs`

- official identity client 的 allowed grant types 包含 `WebAuthnGrantValidator.GrantType`。

`TwoFactorAuthenticationValidator` 里有一个重要行为：FIDO2 user verification 已经被视为第二因素，所以 passkey 登录成功后官方不会再要求额外 2FA。NodeWarden 之后需要明确策略：要兼容官方客户端，应把 passkey 登录视作已满足 2FA，否则官方 `LoginViaWebAuthnComponent` 会显示“不支持 passkey 2FA”的错误。

### 账户 passkey 管理接口

`src/Api/Auth/Controllers/WebAuthnController.cs`

官方 authenticated API：

- `GET /webauthn`：列出账户 passkey credentials。
- `POST /webauthn/attestation-options`：主密码/secret verification 后生成 credential create options 和 token。
- `POST /webauthn/assertion-options`：主密码/secret verification 后生成 assertion options 和 token，用于给已有 credential 启用/更新 PRF keyset。
- `POST /webauthn`：保存新 credential。
- `PUT /webauthn`：更新 credential 的 PRF encryption keyset。
- `POST /webauthn/{id}/delete`：删除 credential。

官方创建 credential 时保存：

- `name`
- `token`
- `deviceResponse`
- `supportsPrf`
- 可选 `encryptedUserKey`
- 可选 `encryptedPublicKey`
- 可选 `encryptedPrivateKey`

官方最多允许 5 个账户 passkey credentials。

### 官方 WebAuthnCredential 表

`src/Core/Auth/Entities/WebAuthnCredential.cs`

字段：

- `Id`
- `UserId`
- `Name`
- `PublicKey`
- `CredentialId`
- `Counter`
- `Type`
- `AaGuid`
- `EncryptedUserKey`
- `EncryptedPrivateKey`
- `EncryptedPublicKey`
- `SupportsPrf`
- `CreationDate`
- `RevisionDate`

SQLite migration：`util/SqliteMigrations/Migrations/20231213032045_WebAuthnLoginCredentials.cs`

表名是 `WebAuthnCredential`，对 `User` 做 cascade delete，并按 `UserId` 建索引。

`GetPrfStatus()`：

- `Unsupported`：`SupportsPrf` 为 false。
- `Supported`：credential 支持 PRF，但还没有完整 encrypted keyset。
- `Enabled`：`EncryptedUserKey`、`EncryptedPrivateKey`、`EncryptedPublicKey` 都存在。

### 官方创建和认证策略

`GetWebAuthnLoginCredentialCreateOptionsCommand.cs`

- 使用 Fido2NetLib。
- `user.id` 是用户 id bytes。
- `user.name/displayName` 使用用户邮箱。
- 排除当前用户已有 credential ids。
- `residentKey: required`
- `userVerification: required`
- `attestation: none`

`GetWebAuthnLoginCredentialAssertionOptionsCommand.cs`

- `allowCredentials` 传空数组。
- `userVerification: required`
- 空 allow list 代表使用 discoverable credentials，也就是 passkey 登录页可以不先输入邮箱。

`CreateWebAuthnLoginCredentialCommand.cs`

- 限制每用户最多 5 个。
- 检查 credential id 在该用户下不能重复。
- FIDO `MakeNewCredentialAsync` 验证 attestation。
- 保存 credential id/public key/counter/type/AAGUID/PRF keyset。

`AssertWebAuthnLoginCredentialCommand.cs`

- 先用 challenge cache 防重放。
- 从 assertion response 的 `userHandle` 解析出 user id。
- 加载该用户所有 WebAuthn credentials。
- 用 credential id 找到记录。
- FIDO `MakeAssertionAsync` 验证签名、challenge、origin、RP ID、user verification。
- 成功后更新 counter。

### 官方 PRF 解密协议

`src/Core/Auth/Models/Api/Response/UserDecryptionOptions.cs`

`WebAuthnPrfDecryptionOption` 字段：

- `EncryptedPrivateKey`
- `EncryptedUserKey`
- `CredentialId`
- `Transports`

`src/Identity/IdentityServer/UserDecryptionOptionsBuilder.cs`

- `WithWebAuthnLoginCredential()` 只在 credential 的 PRF status 是 `Enabled` 时加入 `WebAuthnPrfOption`。
- 如果 credential 没有 PRF keyset，passkey 只能认证账号，不能解开 vault。

`src/Api/Vault/Models/Response/SyncResponseModel.cs`

- sync response 会把所有 enabled PRF credentials 放进 `UserDecryption.WebAuthnPrfOptions`。

## 官方 Bitwarden web/browser client 参考

上游代码位置：

- `.codex-upstream/bitwarden-clients`
- `.codex-upstream/bitwarden-browser`
- 两者研究时 HEAD 都是 `825f9be`，browser repo 内容和 clients monorepo 对应。

旧的 `.codex-upstream/bitwarden-web` 主要有 WebAuthn connector 和 2FA 设置页，没有现代账户 passkey 登录主流程。账户 passkey 登录应以 `bitwarden-clients` 为准。

### 登录按钮可见性

`libs/auth/src/angular/login/default-login-component.service.ts`

- 默认只对 `ClientType.Web` 开启 passkey 登录。

`apps/browser/src/auth/popup/login/extension-login-component.service.ts`

- browser extension 覆盖逻辑：只对 Chromium 开启。
- 注释说明 Firefox 和 Safari 不能在扩展里覆盖 relying party ID。
- 官方代码引用了 W3C webextensions issue 238、Mozilla bug 1956484、Apple forum thread 774351。

结论：NodeWarden 后端即使完全兼容官方 passkey API，官方扩展也只有 Chromium 系会显示 passkey 登录入口。

### Passkey 登录页

`libs/angular/src/auth/login-via-webauthn/login-via-webauthn.component.ts`

流程：

1. 进入 `/login-with-passkey` 后自动开始认证。
2. 调 `webAuthnLoginService.getCredentialAssertionOptions()`。
3. 调 `webAuthnLoginService.assertCredential(options)` 触发 `navigator.credentials.get()`。
4. 调 `webAuthnLoginService.logIn(assertion)` 走 identity token grant。
5. 如果 `authResult.requiresTwoFactor` 为 true，显示“客户端不支持 passkey 2FA”错误。
6. 只有本地 `keyService.userKey$(authResult.userId)` 已经拿到 user key，才运行 login success handler。
7. 成功路由：
   - Web：`/vault`
   - Browser：`/tabs/vault`
   - Desktop：`/vault`

Browser popout 下还会在成功后重新打开普通 popup 并关闭 popout。

### 客户端 passkey 登录请求

`libs/common/src/auth/services/webauthn-login/webauthn-login-api.service.ts`

- GET `${identityUrl}/accounts/webauthn/assertion-options`
- 如果 NodeWarden 的 identityUrl 是站点 origin + `/identity`，实际路径就是 `/identity/accounts/webauthn/assertion-options`。

`libs/common/src/auth/services/webauthn-login/webauthn-login.service.ts`

- `navigator.credentials.get({ publicKey: options })`
- 会主动加 PRF extension：
  - salt 是 `SHA-256("passwordless-login")`
  - extension shape 是 `extensions.prf.eval.first`
- 从 `credential.getClientExtensionResults().prf.results.first` 取 PRF 输出。
- 用 `WebAuthnLoginPrfKeyService.createSymmetricKeyFromPrf()` 转成 PRF key。
- 构造 `WebAuthnLoginAssertionResponseRequest`。
- 明确检查 `deviceResponse.extensions` 里不能含 `prf`，避免把 PRF 输出泄漏给服务端。

`libs/common/src/auth/services/webauthn-login/webauthn-login-prf-key.service.ts`

- salt 常量：`passwordless-login`
- 先 SHA-256。
- 再用 HKDF expand 拆成 64 字节：
  - `"enc"` 32 bytes
  - `"mac"` 32 bytes

`libs/common/src/auth/models/request/identity-token/webauthn-login-token.request.ts`

form encoded token 请求字段：

- `grant_type=webauthn`
- `token=<server assertion options token>`
- `deviceResponse=<JSON string>`
- 还会带 common device request 字段。

`libs/common/src/auth/services/webauthn-login/request/webauthn-login-assertion-response.request.ts`

`deviceResponse` shape：

- `id`
- `rawId`
- `type`
- `extensions: {}`
- `response.authenticatorData`
- `response.signature`
- `response.clientDataJSON`
- `response.userHandle`

全部二进制字段使用 base64url。

### 客户端如何用 PRF 解 vault key

`libs/auth/src/common/login-strategies/webauthn-login.strategy.ts`

- `setMasterKey()` 是空实现，因为 passkey 登录没有主密码 masterKey。
- `setUserKey()`：
  - 如果 token response 有 `key`，保存为 master-key-encrypted user key，兼容主密码解锁。
  - 如果 `userDecryptionOptions.webAuthnPrfOption` 存在，且本地 assertion 得到了 `prfKey`：
    1. 用 PRF key unwrap `encryptedPrivateKey`。
    2. 用 private key decapsulate `encryptedUserKey`。
    3. 得到 user key，写入 `keyService`。

核心约束：服务端永远看不到 PRF 输出。服务端只保存和返回被 PRF 相关密钥加密后的 keyset。

### 官方 web 设置页注册 passkey

`apps/web/src/app/auth/core/services/webauthn-login/webauthn-login-admin-api.service.ts`

调用的 API：

- `POST /webauthn/attestation-options`
- `POST /webauthn/assertion-options`
- `POST /webauthn`
- `GET /webauthn`
- `POST /webauthn/{id}/delete`
- `PUT /webauthn`

`apps/web/src/app/auth/core/services/webauthn-login/webauthn-login-admin.service.ts`

创建流程：

1. 用户做 secret verification。
2. 请求 attestation options。
3. `navigator.credentials.create({ publicKey: options })`，并带 `extensions.prf = {}`。
4. 从 client extension results 判断 `supportsPrf`。
5. 如果要用于 vault encryption，再立即做一次 `navigator.credentials.get()`：
   - `allowCredentials` 锁定刚创建的 credential。
   - 使用同一个 challenge、rpId、timeout、userVerification。
   - 带 PRF eval salt。
6. 用 PRF key 和当前 user key 创建 rotateable keyset。
7. 保存 credential，带上 `encryptedUserKey`、`encryptedPublicKey`、`encryptedPrivateKey`。

删除流程需要 secret verification。启用 encryption 的流程是对已有 credential 做 assertion，再创建并 PUT keyset。

`apps/web/src/app/auth/core/enums/webauthn-login-credential-prf-status.enum.ts`

- `Enabled = 0`
- `Supported = 1`
- `Unsupported = 2`

## NodeWarden 应实现的协议形状

### 公开登录流程

目标兼容官方客户端和 NodeWarden 自己 web：

1. `GET /identity/accounts/webauthn/assertion-options`
   - 生成 discoverable credential assertion options。
   - `allowCredentials: []`
   - `userVerification: "required"`
   - 返回 `{ options, token }`。
   - token 绑定 challenge、scope=`Authentication`、RP ID、origin/audience、过期时间。

2. Browser/web 调 `navigator.credentials.get()`。
   - NodeWarden 自己 web 也要使用 PRF extension。
   - PRF salt 必须和官方一致：`SHA-256("passwordless-login")`。

3. `POST /identity/connect/token`
   - 支持 `grant_type=webauthn`。
   - 接收 `token`、`deviceResponse`、device fields。
   - 解 token，校验 challenge/scope/过期。
   - 验证 assertion。
   - 从 `userHandle` 找到 user id。
   - 从 credential id 找到 passkey record。
   - 更新 counter。
   - 记录/更新 device。
   - 返回 access/refresh token、`AccountKeys`、`UserDecryptionOptions.WebAuthnPrfOption`。

如果用户启用了 TOTP，建议为了官方兼容先遵循 Bitwarden：passkey 的 user verification 视作已满足第二因素。否则官方 passkey 登录页会进入 unsupported 2FA 错误状态。

### 账户 passkey 管理流程

建议对齐官方 API，同时在 NodeWarden 内部可挂到 `/api/webauthn`：

- `GET /api/webauthn`
- `POST /api/webauthn/attestation-options`
- `POST /api/webauthn/assertion-options`
- `POST /api/webauthn`
- `PUT /api/webauthn`
- `POST /api/webauthn/:id/delete`

为了官方客户端兼容，可能还需要接受无 `/api` 前缀的 aliases：

- `/webauthn`
- `/webauthn/attestation-options`
- `/webauthn/assertion-options`
- `/webauthn/:id/delete`

NodeWarden 自己 web 可以直接用 `/api/webauthn`，官方 web/browser 客户端会按它自己的 API base 组装 `/webauthn`。

### 建议新增表

按 NodeWarden 命名风格，建议用小写 snake_case：

```sql
CREATE TABLE IF NOT EXISTS webauthn_credentials (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  name TEXT NOT NULL,
  public_key TEXT NOT NULL,
  credential_id TEXT NOT NULL,
  counter INTEGER NOT NULL DEFAULT 0,
  type TEXT,
  aa_guid TEXT,
  transports TEXT,
  encrypted_user_key TEXT,
  encrypted_public_key TEXT,
  encrypted_private_key TEXT,
  supports_prf INTEGER NOT NULL DEFAULT 0,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE UNIQUE INDEX IF NOT EXISTS idx_webauthn_credentials_user_credential
  ON webauthn_credentials(user_id, credential_id);

CREATE INDEX IF NOT EXISTS idx_webauthn_credentials_user
  ON webauthn_credentials(user_id);
```

如果要更严格防止同一个 credential id 被跨用户重复注册，也可以加全局 unique index `credential_id`。官方代码至少检查同用户唯一；实际安全上更建议全局唯一，因为 credential id 本身应该唯一标识 authenticator credential。

PRF status 不必落库为枚举，可以由字段计算：

- `supports_prf = 0` => `Unsupported`
- `supports_prf = 1` 且三段 encrypted key 不全 => `Supported`
- `supports_prf = 1` 且三段 encrypted key 全存在 => `Enabled`

### Challenge/token 存储

官方 server 用 protected token 携带 options，再用 challenge cache 防重放。NodeWarden 在 Workers/D1 里建议组合：

- token：HMAC/JWT 样式，绑定 `scope`、`challenge`、`userId?`、`rpId`、`createdAt`、`expiresAt`。
- D1 表或 KV：记录 challenge 是否使用过，至少字段 `challenge_hash`、`scope`、`user_id`、`expires_at`、`used_at`。
- 登录 assertion options 是公开接口，不绑定 user id；create/update/delete 管理流程应绑定 user id。
- 验证成功后立即 mark used。

建议 scopes：

- `Authentication`
- `CreateCredential`
- `UpdateKeySet`

官方还有 `PrfRegistration` 语义，NodeWarden 可以用 `CreateCredential` 覆盖，只要 token 逻辑严谨即可。

### 服务端 WebAuthn 验证库

NodeWarden 当前没有 FIDO2/WebAuthn 服务端验证依赖。不要手写签名和 attestation 解析。

候选：`@simplewebauthn/server`。官方文档当前说明它提供 `generateRegistrationOptions`、`verifyRegistrationResponse`、`generateAuthenticationOptions`、`verifyAuthenticationResponse`，并记录了 RP ID、origin、credential public key、counter、transports 等数据结构。文档地址：https://simplewebauthn.dev/docs/packages/server

注意：NodeWarden 跑在 Cloudflare Workers，不是普通 Node server。正式选库前需要做一次构建/runtime 验证，确认包不会依赖 Workers 不支持的 Node API。这个验证属于实现阶段，不在本研究文档里写测试程序。

## NodeWarden web 需要改的地方

### 登录页

当前登录 UI 在 `webapp/src/components/AuthViews.tsx`，状态和行为主要由 `webapp/src/App.tsx`、`webapp/src/lib/app-auth.ts` 管。

新增：

- 登录页增加“使用 passkey 登录”按钮。
- 新增 `performPasskeyLogin()`：
  1. GET `/identity/accounts/webauthn/assertion-options`
  2. 转换 server options 里的 base64url challenge/user id/credential id 为 ArrayBuffer。
  3. `navigator.credentials.get()`，带 PRF salt。
  4. POST `/identity/connect/token`，`grant_type=webauthn`。
  5. 从 response 的 `UserDecryptionOptions.WebAuthnPrfOption` 取 encrypted keyset。
  6. 用本地 PRF key 解出 user key。
  7. 构造 `SessionState` 并进入 app。

不能复用 `completeLogin(token, email, masterKey, fallbackKdfIterations)`，因为它要求 masterKey。应新增 passkey 专用 complete 函数。

### 设置页

当前账户/安全相关 UI 在 `webapp/src/components/SettingsPage.tsx` 一带。

新增：

- Passkey 列表。
- 新建 passkey dialog。
- 删除 passkey。
- 对支持 PRF 但未启用 encryption 的 passkey，提供“启用用于登录解锁”的操作。

自己 web 的新建流程要和官方一致：

1. 已登录状态下先验证主密码或现有 session secret。
2. 请求 attestation options。
3. `navigator.credentials.create()` 带 `extensions.prf = {}`。
4. 如果用户希望这个 passkey 可直接解锁 vault，再对刚创建 credential 做一次 `navigator.credentials.get()` 获取 PRF 输出。
5. 用 PRF key 加密/封装当前 user key，发送到 server 保存。

### 客户端加密能力

NodeWarden web 当前已经有：

- PBKDF2
- HKDF expand
- Bitwarden EncString 加解密
- RSA-OAEP private key 加密

但 passkey PRF keyset 需要和官方策略对齐：

- PRF key 是 64 字节 symmetric key，前 32 enc、后 32 mac。
- `encryptedPrivateKey` 用 PRF key wrap 一个 decapsulation private key。
- `encryptedUserKey` 用对应 public key encapsulate user key。
- `encryptedPublicKey` 用于 key rotation。

这里需要认真复用或补齐 NodeWarden 现有 crypto helper，避免做出和官方客户端无法互解的 keyset。

## 扩展兼容要求

### 官方 browser extension

官方 extension passkey 登录入口在：

- `apps/browser/src/auth/popup/login/extension-login-component.service.ts`
- 只在 Chromium 开启。

如果要官方/派生扩展能对 NodeWarden passkey 登录：

- identity URL 必须能访问 `/accounts/webauthn/assertion-options`。
- token URL 必须支持 `grant_type=webauthn`。
- API URL 必须能访问 `/webauthn` 管理接口。
- response 大小写和字段名要同时照顾 PascalCase/camelCase，NodeWarden 当前 token response 已经在一些字段上双写，这个风格应继续沿用。
- passkey 登录成功时必须返回可解开 vault 的 `webAuthnPrfOption`，否则官方组件虽然认证成功，也不会进入可用 vault。

### RP ID 和 origin

自己的 web：

- RP ID 通常是站点 host，例如 `vault.example.com`。
- origin 是 `https://vault.example.com`。

官方 browser extension：

- 扩展页面 origin 是 `chrome-extension://...`。
- 官方之所以只开 Chromium，是因为 Chromium extension 具备它需要的 RP ID 覆盖能力。
- NodeWarden server 验证 assertion 时必须允许正确的 origin/RP ID 组合。这里不能简单只接受当前 request origin，否则扩展登录会失败。

建议配置化：

- `WEBAUTHN_RP_ID`
- `WEBAUTHN_RP_NAME`
- `WEBAUTHN_ALLOWED_ORIGINS`

默认可以从 request URL 推导 web origin，但生产建议显式配置。

## 安全约束

- 所有账户 passkey 必须 `userVerification: required`。
- 登录 assertion 使用 discoverable credential，`userHandle` 必须能解析成 user id 并和 credential 记录一致。
- challenge 必须有过期时间和一次性使用标记。
- PRF 输出绝不能传给 server，也不能写入日志。
- token 里要绑定 scope，防止 attestation token 被拿去 authentication 用。
- counter 要更新。遇到 counter 异常时至少记录 audit event，是否阻断要结合 multi-device passkey 现实处理。
- 每用户 credential 数量限制建议沿用官方 5 个。
- 删除/新增/启用 encryption 必须要求已登录用户二次验证。
- 密码变更、user key rotation 后，所有 enabled PRF credentials 的 keyset 也要 rotation，否则 passkey 登录会解不开新 vault key。
- 备份导出/导入必须包含账户 passkey 表，否则恢复后 passkey 登录会全部失效。
- 审计日志建议新增：
  - `auth.passkey.login.success`
  - `auth.passkey.login.failed`
  - `account.passkey.create`
  - `account.passkey.delete`
  - `account.passkey.encryption.enable`
  - `account.passkey.rotate`

## 建议实施顺序

### 第一阶段：后端基础

1. 新增 `webauthn_credentials` 和 challenge 表。
2. 新增 storage repo。
3. 接入 WebAuthn 服务端验证库。
4. 实现 assertion options 和 `grant_type=webauthn`。
5. token response 加 `WebAuthnPrfOption` shape。

这阶段先能让“已有手工塞入的 enabled credential”完成登录验证，但还不做 UI。

### 第二阶段：账户 passkey 管理 API

1. 实现 `/api/webauthn` 和 `/webauthn` aliases。
2. 实现 attestation options、save credential、list、delete、enable/update encryption。
3. 加 audit event。
4. 接入 backup export/import。
5. sync response 加 `WebAuthnPrfOptions`。

### 第三阶段：NodeWarden 自己 web

1. 登录页 passkey 按钮和 `performPasskeyLogin()`。
2. Passkey 设置页。
3. PRF keyset 创建、保存、删除、启用 encryption。
4. 浏览器能力判断和错误提示。

### 第四阶段：扩展兼容

1. 用官方 browser extension 的 Chromium passkey 登录流程校对 endpoint。
2. 校对 `/config` 里 identity/api/web vault URL。
3. 校对 RP ID、allowed origins。
4. 必要时加兼容字段或 alias route。

按用户要求，本阶段只需要代码跑通不报错；不在这里写可视化测试或测试程序。

## 待实现清单

- [ ] 设计并落库 `webauthn_credentials`。
- [ ] 设计并落库 WebAuthn challenge/replay cache。
- [ ] 选定并验证 Workers 可用的 WebAuthn server library。
- [ ] `GET /identity/accounts/webauthn/assertion-options`。
- [ ] `POST /identity/connect/token` 支持 `grant_type=webauthn`。
- [ ] `UserDecryptionOptions.WebAuthnPrfOption`。
- [ ] `UserDecryption.WebAuthnPrfOptions`。
- [ ] `/api/webauthn` 管理接口。
- [ ] `/webauthn` 官方客户端 alias。
- [ ] NodeWarden web passkey 登录入口。
- [ ] NodeWarden web passkey 管理页。
- [ ] key rotation 时同步 rotate PRF keysets。
- [ ] backup export/import 覆盖新表。
- [ ] audit logs 覆盖 passkey 管理和登录。

## 关键文件索引

NodeWarden：

- `src/router-public.ts`
- `src/router-authenticated.ts`
- `src/handlers/accounts.ts`
- `src/handlers/identity.ts`
- `src/handlers/sync.ts`
- `src/services/auth.ts`
- `src/services/storage-schema.ts`
- `src/services/storage-user-repo.ts`
- `src/services/storage-device-repo.ts`
- `src/utils/passkey.ts`
- `src/utils/user-decryption.ts`
- `src/types/index.ts`
- `webapp/src/lib/api/auth.ts`
- `webapp/src/lib/app-auth.ts`
- `webapp/src/components/AuthViews.tsx`
- `webapp/src/components/SettingsPage.tsx`

Bitwarden server：

- `.codex-upstream/bitwarden-server/src/Identity/Controllers/AccountsController.cs`
- `.codex-upstream/bitwarden-server/src/Identity/IdentityServer/RequestValidators/WebAuthnGrantValidator.cs`
- `.codex-upstream/bitwarden-server/src/Identity/IdentityServer/ApiClient.cs`
- `.codex-upstream/bitwarden-server/src/Api/Auth/Controllers/WebAuthnController.cs`
- `.codex-upstream/bitwarden-server/src/Core/Auth/Entities/WebAuthnCredential.cs`
- `.codex-upstream/bitwarden-server/src/Core/Auth/UserFeatures/WebAuthnLogin/Implementations/GetWebAuthnLoginCredentialCreateOptionsCommand.cs`
- `.codex-upstream/bitwarden-server/src/Core/Auth/UserFeatures/WebAuthnLogin/Implementations/GetWebAuthnLoginCredentialAssertionOptionsCommand.cs`
- `.codex-upstream/bitwarden-server/src/Core/Auth/UserFeatures/WebAuthnLogin/Implementations/CreateWebAuthnLoginCredentialCommand.cs`
- `.codex-upstream/bitwarden-server/src/Core/Auth/UserFeatures/WebAuthnLogin/Implementations/AssertWebAuthnLoginCredentialCommand.cs`
- `.codex-upstream/bitwarden-server/src/Core/Auth/Models/Api/Response/UserDecryptionOptions.cs`
- `.codex-upstream/bitwarden-server/util/SqliteMigrations/Migrations/20231213032045_WebAuthnLoginCredentials.cs`

Bitwarden clients/browser：

- `.codex-upstream/bitwarden-clients/libs/auth/src/angular/login/default-login-component.service.ts`
- `.codex-upstream/bitwarden-clients/apps/browser/src/auth/popup/login/extension-login-component.service.ts`
- `.codex-upstream/bitwarden-clients/libs/angular/src/auth/login-via-webauthn/login-via-webauthn.component.ts`
- `.codex-upstream/bitwarden-clients/libs/common/src/auth/services/webauthn-login/webauthn-login-api.service.ts`
- `.codex-upstream/bitwarden-clients/libs/common/src/auth/services/webauthn-login/webauthn-login.service.ts`
- `.codex-upstream/bitwarden-clients/libs/common/src/auth/services/webauthn-login/webauthn-login-prf-key.service.ts`
- `.codex-upstream/bitwarden-clients/libs/common/src/auth/models/request/identity-token/webauthn-login-token.request.ts`
- `.codex-upstream/bitwarden-clients/libs/common/src/auth/services/webauthn-login/request/webauthn-login-response.request.ts`
- `.codex-upstream/bitwarden-clients/libs/common/src/auth/services/webauthn-login/request/webauthn-login-assertion-response.request.ts`
- `.codex-upstream/bitwarden-clients/libs/auth/src/common/login-strategies/webauthn-login.strategy.ts`
- `.codex-upstream/bitwarden-clients/apps/web/src/app/auth/core/services/webauthn-login/webauthn-login-admin-api.service.ts`
- `.codex-upstream/bitwarden-clients/apps/web/src/app/auth/core/services/webauthn-login/webauthn-login-admin.service.ts`
- `.codex-upstream/bitwarden-clients/apps/web/src/app/auth/core/services/webauthn-login/request/save-credential.request.ts`
- `.codex-upstream/bitwarden-clients/apps/web/src/app/auth/core/services/webauthn-login/request/enable-credential-encryption.request.ts`
- `.codex-upstream/bitwarden-clients/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-attestation-response.request.ts`
- `.codex-upstream/bitwarden-clients/apps/web/src/app/auth/core/enums/webauthn-login-credential-prf-status.enum.ts`
- `.codex-upstream/bitwarden-clients/libs/common/src/auth/models/response/user-decryption-options/webauthn-prf-decryption-option.response.ts`
- `.codex-upstream/bitwarden-clients/libs/auth/src/common/models/domain/user-decryption-options.ts`