用途
auth-setup 是 Convex Agent Plugins 提供的一个认证搭建技能，用于在 Convex 项目中实现安全的身份认证、用户管理与访问控制。资料说明其适用场景包括：首次设置认证、实现用户管理（用户表、身份映射）、创建认证辅助函数，以及配置 OAuth 提供商（如 WorkOS、Auth0 等）。
架构概览
资料将 Convex 认证划分为两个主要部分：
- 客户端认证：使用认证提供商（WorkOS、Auth0 或自定义 JWT）。
- 后端身份：将认证提供商的身份映射到自己的 users 表。
主要能力
1. Schema 设计
示例中 users 表包含 tokenIdentifier（每个认证提供商唯一）、name、email、pictureUrl（可选）、role（user/admin 联合类型）、createdAt、updatedAt（可选），并建立 by_token 与 by_email 索引。
2. 核心辅助函数
- getCurrentUser：获取当前用户，未认证或用户不存在时抛错。
- getCurrentUserOrNull：未认证时返回 null，用于可选认证场景。
- requireAdmin：要求当前用户角色为 admin。
3. 用户创建与更新
storeUser mutation 在身份存在时按 tokenIdentifier 查询；已有用户则更新 updatedAt，否则插入新用户（默认角色 user），返回用户 ID。
4. 访问控制模式
- 仅所有者：如 updateProfile 只修改当前用户资料。
- 资源所有权：如 deleteTask 校验 task.userId 与当前用户一致。
- 团队访问：通过 teamMembers 表及 by_team_and_user 索引，requireTeamAccess 校验成员身份。
- 公开/私有/混合查询：分别展示无需认证、必须认证、可选认证三种查询写法。
5. 客户端接入（WorkOS AuthKit）
React/Vite：安装 @workos-inc/authkit-react，用 AuthKitProvider 包裹，并调用 convex.setAuth(useAuth)。
Next.js：安装 @workos-inc/authkit-nextjs，在 ConvexClientProvider 中使用 useAuth 的 getToken 设置 convex.setAuth。
资料还列出相应环境变量：VITE_CONVEX_URL、VITE_WORKOS_CLIENT_ID，以及 Next.js 下的 NEXT_PUBLIC_CONVEX_URL、NEXT_PUBLIC_WORKOS_CLIENT_ID、WORKOS_API_KEY、WORKOS_COOKIE_PASSWORD。
6. 登录后调用 storeUser
在客户端用户登录后通过 useMutation(api.users.storeUser) 触发用户创建/更新。
使用方式
资料以代码示例形式给出完整步骤：定义 schema、编写辅助函数、实现 storeUser、在受保护函数中调用鉴权、配置客户端提供商与环境变量。也给出检查清单：users 表与 tokenIdentifier 索引、getCurrentUser 辅助函数、storeUser mutation、受保护函数的认证检查、资源访问的授权检查、清晰的错误消息、客户端认证提供商配置。
适用场景
需要为 Convex 项目建立用户体系与权限控制的开发场景，包括个人资料、资源归属、团队协作、公开与私有数据读取等。
限制
资料仅以 WorkOS AuthKit 为客户端的详细示例，其他提供商（自定义 JWT、Auth0、其他 OAuth）仅提及可查阅 Convex 认证文档，未提供具体步骤。资料未说明付费、价格、平台要求或效果评估。