mcpField
C
convex-auth

convex-auth

github.com/convex安全6937.3k 次安装1 天前更新
代码仓库

关于 convex-auth

使用 @convex-dev/auth 为应用添加登录功能，包括提供方配置、服务端和客户端接入以及登录界面。默认采用 Passkey，并验证认证流程能否完整往返。

主要功能

  1. 01配置 Passkey、密码或 OAuth 提供方
  2. 02使用 jose 生成 JWT 密钥
  3. 03设置 auth.config.ts
  4. 04接入提供方、钩子、界面和路由守卫
  5. 05验证登录往返流程

适用场景

  1. 01为应用添加 Passkey 登录
  2. 02设置指定的密码或 OAuth 登录
  3. 03排查配置导致的静默登出问题

MCP 相关

该技能可使用 Convex MCP 的 envSet 工具设置部署环境变量，也提供 CLI 替代方式。

安装

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

$npx skills add https://github.com/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