mcpField
C
convex-auth

convex-auth

github.com/growthx-club开发0171 次安装5 周前更新
代码仓库

关于 convex-auth

convex-auth 指导开发者在现有应用中接入 @convex-dev/auth，涵盖身份提供方、服务端配置、客户端组件和登录界面。其重点是无交互生成密钥，并验证完整登录流程。

主要功能

  1. 01默认配置 Passkey 登录
  2. 02按需配置密码或 OAuth 登录
  3. 03无交互生成 JWT 密钥和 JWKS
  4. 04配置服务端认证与客户端路由
  5. 05验证真实登录往返流程

适用场景

  1. 01为 Convex 应用添加用户登录
  2. 02在 CI 或无终端环境配置认证
  3. 03排查始终处于未登录状态的配置问题

MCP 相关

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

安装

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

$npx skills add https://github.com/growthx-club/build-sprint-skills --skill convex-auth

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

附带文件UPSTREAM-LICENSEUPSTREAM-THIRD_PARTY_NOTICES.md

详细介绍

为应用添加登录功能

为当前应用安装并接入 @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