用途
为当前的 Convex 应用添加登录认证：安装并接入 @convex-dev/auth，配置认证提供方、服务端配置、客户端 hooks 以及一个登录界面。默认使用 passkeys，也可按需切换为 OAuth 或密码方式。资料特别强调要正确处理 auth.config.ts，称其为真实项目中最常见的认证陷阱。
主要能力与流程
- 安装 @convex-dev/auth（固定构建版本）并将其加入 convex.config.ts。若使用 pnpm，还需额外执行 pnpm add jose（否则不会被提升），第 3 步需要它。
- 在 convex/auth.ts 中添加提供方，默认 Passkey，也可按要求改用 Password 或 Google 等 OAuth。
- 以无头（headless）方式生成认证密钥。资料明确要求不要运行交互式的 npx @convex-dev/auth 向导，因为它需要登录/TTY，在非交互、匿名或 CI 环境中会挂起，被称为“最大的认证时间黑洞”。应使用 jose 确定性生成 JWT_PRIVATE_KEY 与 JWKS，并给出了具体命令。
- 将 JWT_PRIVATE_KEY、JWKS（来自 .auth-keys.json）以及 SITE_URL 设置到部署上。优先使用 Convex MCP 的 envSet 工具，一次设置一个变量，以避免多行密钥的 shell 引号问题。CLI 回退方案需使用 NAME=VALUE 形式（npx convex env set "JWT_PRIVATE_KEY=$JWT"），绝不要写成 env set JWT_PRIVATE_KEY "$JWT"，因为值以 -----BEGIN 开头，CLI 会把开头的 - 解析为未知参数。SITE_URL 为开发地址（例如 http://localhost:3000）。完成后删除 .auth-keys.json。
- 编写 convex/auth.config.ts，资料指出若写错，会出现“静默地始终已登出”的 bug。
- 接入客户端：ConvexAuthProvider、登录组件以及路由守卫。如果导入 shadcn/ui 原语（button、input、textarea、label 等），需先用 npx shadcn@latest add <name> 安装；缺少 @/components/ui/* 会导致硬性构建错误。
- 在宣布完成前验证登录能完整往返（round-trip）。
规则
- 使用 jose 生成 JWT_PRIVATE_KEY/JWKS：可导出的 RS256；PKCS8 换行转为空格；JWKS 结构为 {keys:[{use:"sig", ...publicJwk}]}。不要运行交互式的 npx @convex-dev/auth 向导，它在无头/匿名环境下会挂起。
- 通过 MCP envSet 工具或 NAME=VALUE CLI 形式设置变量。
- 始终编写 auth.config.ts：缺失或不正确会导致应用静默地始终处于已登出状态且无报错。
- 默认使用 passkeys；仅在明确要求时才切换到密码/OAuth。
- 提前安装所导入的任何 shadcn/ui 原语（npx shadcn@latest add ...）；缺少 @/components/ui/* 会导致硬性构建失败。
- 完成前验证真实登录可用。
适用场景
需要为 Convex 项目接入认证、尤其是在无 TTY、匿名或 CI 等非交互环境中执行、或希望避免交互式向导挂起与 auth.config.ts 配置错误的场景。
限制
资料仅围绕 Convex 应用与 @convex-dev/auth 展开，未提供除上述提供方以外的其他认证方式说明，也未提供定价、平台支持范围或性能指标等信息。