用途:为 Convex 项目实现安全认证,包括用户管理、身份映射与访问控制。
主要能力:
- 认证提供商选择:Convex Auth、Clerk、WorkOS AuthKit、Auth0 或自定义 JWT。编写设置代码前先确认用户想用哪种方案;若仓库已明显使用某提供商则延续该提供商,除非用户要求更换。可先查找仓库信号,例如依赖 @clerk/、@workos-inc/、@auth0/*,现有 convex/auth.config.ts、认证中间件、提供商包装器,以及指向某提供商的环境变量。
- 数据模型:在 convex/schema.ts 中定义 users 表,字段含 tokenIdentifier、name、email、pictureUrl(可选)、role(user/admin 联合)、createdAt、updatedAt(可选),并按 by_token(tokenIdentifier)与 by_email(email)建索引。
- 辅助函数:在 convex/lib/auth.ts 中实现 getCurrentUser(未认证抛 Not authenticated,用户不存在抛 User not found)、getCurrentUserOrNull、requireAdmin(非 admin 抛 Admin access required)。均通过 ctx.auth.getUserIdentity() 获取身份,再以 by_token 索引查询用户。
- 用户创建/更新:storeUser mutation 在首次登录时插入用户记录;若已存在则用 patch 更新 updatedAt 并返回其 _id。
- 访问控制模式:资源归属校验(如删除任务时校验 task.userId 是否等于当前用户 _id,否则提示只能删除自己的任务);团队访问校验(按 by_team_and_user 索引查询 teamMembers,无成员记录则拒绝访问)。
- 检查清单:写设置代码前选定提供商、users 表含 tokenIdentifier 索引、提供 getCurrentUser、提供首次登录用的 storeUser mutation、所有受保护函数均做认证检查、做资源访问的授权检查、错误信息清晰(如 Not authenticated、Unauthorized)、配置客户端认证提供商。
限制:资料未提供具体安装命令、各提供商的详细配置步骤、客户端接入代码与版本要求,使用时应结合官方文档补充。