用途
Convex Security 是一套针对 Convex 函数的安全最佳实践集合，用于在开发 Convex 后端时落实错误处理、输入输出校验、认证与授权、访问控制、速率限制等安全约束。它面向使用 Convex 构建应用的开发者，帮助在函数层面建立统一的安全规范。
主要能力
使用 ConvexError 处理错误
对面向用户的错误使用 ConvexError，并携带结构化错误码。示例中从 convex/values 导入 ConvexError，在 mutation 中当任务不存在时抛出包含 code 与 message 的错误对象。文档列出的常见错误码包括：UNAUTHENTICATED、FORBIDDEN、NOT_FOUND、RATE_LIMITED、VALIDATION_ERROR。
参数与返回值验证器
要求同时定义 args 和 returns 验证器。示例中 createTask 的 args 包含 title（字符串）与 priority（联合字面量 low/medium/high），returns 为 v.id("tasks")，并强调“始终包含 returns”。同时建议使用 ESLint 规则 @convex-dev/require-argument-validators。
认证辅助函数
建议创建可复用的认证辅助函数，示例文件为 convex/lib/auth.ts，包含：
- getUser：通过 ctx.auth.getUserIdentity() 获取身份，若不存在返回 null，否则按 by_tokenIdentifier 索引查询 users 表并返回唯一记录。
- requireAuth：调用 getUser，若未找到用户则抛出 code 为 UNAUTHENTICATED 的 ConvexError。
- requireRole：在 requireAuth 基础上，依据 roleHierarchy（user: 0、moderator: 1、admin: 2）比较用户角色等级，不足时抛出 code 为 FORBIDDEN 的 ConvexError。
示例展示了在 mutation 中调用 requireRole(ctx, "admin") 的用法。
行级访问控制
在执行操作前校验资源所有权。示例中 updateTask 先调用 requireAuth 获取用户，再读取任务，若任务不存在或 task.userId 不等于 user._id，则抛出 code 为 FORBIDDEN 的 ConvexError。
速率限制
通过速率限制防止滥用。示例定义了 RATE_LIMITS 配置：message 为每 60 秒 10 次请求，upload 为每 300 秒 5 次请求。checkRateLimit mutation 根据 action 取限额，计算窗口起点，查询 rateLimits 表（按 by_user_and_action 索引过滤 userId 与 action，并筛选时间戳大于窗口起点），若请求数达到上限则返回 allowed: false 与 retryAfter，否则插入一条记录并返回 allowed: true。
调度仅使用内部函数
对于 ctx.run* 与调度，始终使用 internal.*。示例对比了错误做法（使用 api.tasks.process 暴露公共函数）与正确做法（使用 internal.tasks.process），并给出 internalMutation 定义示例。提示：不要在 Convex 函数中从 _generated/api.ts 导入 api。
ctx.db 中显式包含表名
始终将表名作为第一个参数传入。示例对比了错误写法 ctx.db.get(movieId)、ctx.db.patch(movieId, { title: "Whiplash" }) 与正确写法 ctx.db.get("movies", movieId)、ctx.db.patch("movies", movieId, { title: "Whiplash" })。建议使用 ESLint 规则 @convex-dev/explicit-table-ids 并启用自动修复。
使用方式
该技能以代码示例与规范说明的形式提供，开发者可参照示例在 Convex 项目中编写函数、认证辅助模块与速率限制逻辑，并按建议配置 ESLint 规则。具体安装命令与集成步骤暂未提供。
适用场景
适用于使用 Convex 构建后端函数的项目，尤其是需要处理用户认证、角色权限、资源所有权校验、防滥用限流以及函数调度安全性的应用。
限制
资料未提供该技能的安装方式、依赖版本、运行环境要求、收费信息或效果保证；相关细节暂未提供。