mcpField
C
convex-auth

convex-auth

github.com/get-convex开发6931.5k 次安装1 天前更新
代码仓库

关于 convex-auth

convex-auth 是用于在应用中接入 @convex-dev/auth 的开发技能，面向构建 Convex 应用的开发者。它涵盖服务端配置、客户端登录界面及密钥生成，并特别处理无交互环境中的配置流程。

主要功能

  1. 01配置 @convex-dev/auth 提供方
  2. 02默认使用 Passkey 登录
  3. 03无交互生成 JWT 密钥
  4. 04设置认证环境变量
  5. 05接入客户端登录与路由保护
  6. 06验证登录流程

适用场景

  1. 01为 Convex 应用添加 Passkey 登录
  2. 02在 CI 环境配置认证密钥
  3. 03接入 OAuth 或密码登录
  4. 04检查登录流程是否成功

MCP 相关

说明中建议优先使用 Convex MCP 的 envSet 工具设置部署环境变量。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/get-convex/agent-skills --skill convex-auth

安装后在 Claude Code 中输入/convex-auth确认已加载。

详细介绍

为应用添加登录功能

为当前应用安装并接入 @convex-dev/auth：配置提供方（默认使用通行密钥，也可按需使用 OAuth/密码）、服务端配置、客户端钩子和登录界面，并确保配置正确，尤其是容易出错的 auth.config.ts。

工作流

  1. 安装固定版本的 @convex-dev/auth，并将其添加到 convex.config.ts。使用 pnpm 时，还要运行 pnpm add jose（否则它不会被提升到顶层）；第 3 步需要用到它。
  2. 在 convex/auth.ts 中添加提供方（默认使用 Passkey；如有要求，可使用 Password 或 Google 等 OAuth）。
  3. 以无头方式生成身份验证密钥。不要运行交互式 npx @convex-dev/auth 向导：它需要登录和 TTY，在非交互、匿名或 CI 环境中会卡住（这是最常见的身份验证耗时问题）。使用 jose 确定性地生成 JWT_PRIVATE_KEY + JWKS： node -e 'import("jose").then(async({generateKeyPair,exportPKCS8,exportJWK})=>{const k=await generateKeyPair("RS256",{extractable:true});const priv=await exportPKCS8(k.privateKey);const pub=await exportJWK(k.publicKey);process.stdout.write(JSON.stringify({JWT_PRIVATE_KEY:priv.trimEnd().replace(/\n/g," "),JWKS:JSON.stringify({keys:[{use:"sig",...pub}]})}))})' > .auth-keys.json 然后在部署环境中设置 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 是开发 URL（例如 http://localhost:3000）。之后删除 .auth-keys.json。
  4. 编写 convex/auth.config.ts（配置错误会导致应用始终处于已退出登录状态，且不会报错）。
  5. 接入客户端：添加 ConvexAuthProvider、登录组件和路由守卫。如果导入 shadcn/ui 基础组件（button、input、textarea、label 等），先使用 npx shadcn@latest add <name> 添加；缺少 @/components/ui/* 会导致构建失败。
  6. 在宣布完成前，验证登录流程能够成功往返。

规则

  • 使用 jose 生成 JWT_PRIVATE_KEY/JWKS（可导出的 RS256；将 PKCS8 换行符替换为空格；JWKS = {keys:[{use:"sig", ...publicJwk}]}）。不要运行交互式 npx @convex-dev/auth 向导：它在无头或匿名环境中会卡住。通过 MCP envSet 工具或 NAME=VALUE CLI 格式设置变量。
  • 始终编写 auth.config.ts：缺少或配置错误会导致应用始终处于已退出登录状态，且不会报错。
  • 默认使用 Passkey；只有在明确要求时才切换为密码/OAuth。
  • 提前安装导入的所有 shadcn/ui 基础组件（npx shadcn@latest add ...）；缺少 @/components/ui/* 会导致构建失败。
  • 完成前验证真实登录可用。

评论

支持 Markdown