convex-auth 是一个面向 Convex 应用的认证配置技能，目标是为当前应用快速、正确地加入登录能力。
用途 为现有 Convex 应用安装并接通 @convex-dev/auth，提供登录与身份认证支持。默认使用通行密钥（passkeys），仅在明确要求时切换为密码或 OAuth（如 Google）等提供方。
主要能力
- 安装 @convex-dev/auth（固定构建）并写入 convex.config.ts；使用 pnpm 时额外安装 jose。
- 在 convex/auth.ts 中配置认证提供方，默认 Passkey，可改为 Password 或 OAuth。
- 以无头方式生成认证密钥：使用 jose 确定性地生成 JWT_PRIVATE_KEY 与 JWKS，避免运行需要登录或 TTY 的交互式向导。
- 在部署上设置 JWT_PRIVATE_KEY、JWKS 与 SITE_URL；优先通过 Convex MCP 的 envSet 工具逐个设置变量，或使用 CLI 的 NAME=VALUE 形式（例如 npx convex env set "JWT_PRIVATE_KEY=$JWT"），避免因值以 -----BEGIN 开头被 CLI 误判为未知参数。SITE_URL 为开发地址（例如 http://localhost:3000）。生成后删除 .auth-keys.json。
- 编写 convex/auth.config.ts，该文件缺失或错误会导致应用静默地始终处于未登录状态且不报错。
- 接入客户端：ConvexAuthProvider、登录组件与路由守卫。若引用 shadcn/ui 原语（button、input、textarea、label 等），需先通过 npx shadcn@latest add <name> 安装，缺少 @/components/ui/* 会导致构建失败。
- 在宣告完成前验证一次真实的登录往返流程。
使用方式 按技能描述的工作流逐步执行：安装依赖并写入配置文件、在 convex/auth.ts 中配置提供方、无头生成密钥、设置环境变量、编写 auth.config.ts、接入客户端并安装所需 UI 组件、最后验证登录。
适用场景 需要为当前 Convex 应用添加认证与登录界面的开发场景，尤其是希望默认使用通行密钥、并避免交互式向导在无头、匿名或 CI 环境中挂起的情况。
限制 资料未提供该技能的价格、收费方式、支持平台范围及具体效果数据。不要在无头、匿名或 CI 环境中运行交互式 npx @convex-dev/auth 向导。必须正确编写 auth.config.ts，否则会出现无报错的静默未登录问题。默认使用通行密钥，切换其他方式需明确请求。