---
url: /docs/auth/passkeys.md
---
# 通行密钥

## 当前完成范围

通行密钥通过 WebAuthn 使用设备生物识别或安全密钥登录。服务端保存公钥，不保存设备上的私钥。

当前模板提供已有账号的登录入口。Better Auth 提供注册凭据接口，但模板尚未完成面向用户的凭据注册、列表、撤销和恢复界面。新用户必须保留密码、邮箱验证码或第三方登录中的可用入口，不能把通行密钥作为唯一注册方式。

## 域名配置

`websiteConfig.auth.passkey` 控制插件与入口。`apps/api/lib/auth.ts` 从 `APP_ORIGIN` 提取 `rpID`，使用站点品牌作为 `rpName`。本地可使用 localhost；线上使用 HTTPS 和与凭据一致的域名。

不同域名注册的凭据不能默认互用。更换站点域名、预发布子域或 `APP_ORIGIN` 后，需要重新检查注册和登录。

## 登录流程

`apps/app/components/auth/passkey-login.tsx` 检查 `window.PublicKeyCredential`，用户点击后调用 `auth.signIn.passkey()`，成功后刷新会话。

当前没有启用自动填充式凭据选择。如果后续添加，需要持久显示带 `autocomplete="email webauthn"` 的输入框，并先检测浏览器是否支持相应模式。

## 数据与错误

凭据表在 `db/schema/passkey.ts`，包括公钥、凭据 ID、计数器、设备类型和传输方式。扩展字段不代表插件会自动填充，应核对写入逻辑。

取消设备提示、超时、不支持 WebAuthn、凭据不匹配和网络故障需要分别处理。取消不是认证成功；浏览器不支持时要保留其他登录方式。

## 验收

补齐凭据管理界面后，分别测试首次注册、已绑定设备登录、跨设备同步、撤销后拒绝登录、取消提示及账号恢复。真实设备验收完成前，模块状态仍是部分接入。