用途:为 Convex 应用提供深度安全审计模式,帮助开发者检查并加固授权逻辑、数据访问边界、Action 隔离、限流和敏感操作保护。
主要能力:
- 授权逻辑审计:基于角色的访问控制(RBAC),用 roleHierarchy 定义 user、moderator、admin、superadmin 层级,提供 requireRole 与基于权限的 requirePermission 校验,未认证或权限不足时抛出 ConvexError。
- 数据访问边界审计:查询按 userId 过滤,返回敏感数据前校验所有权,共享资源通过 documentAccess 访问列表判断 public、owner 或共享级别。
- Action 隔离审计:外部 API 调用前验证身份,API 密钥从环境变量读取,记录审计日志,错误信息脱敏;支付等敏感逻辑使用 internalAction,不暴露给客户端。
- 限流审计:为 message、upload、api 等操作定义请求数与时间窗口,通过 rateLimits 表统计并返回 retryAfter,超限抛出 RATE_LIMITED。
- 敏感操作保护:危险操作要求 superadmin 角色与一次性确认码,确认码带过期时间且用后删除,删除任务通过 scheduler 异步执行并写入审计日志。
使用方式:文档以 Convex 的 query、mutation、action、internalAction 与 ConvexError 为例,展示在 convex/lib/auth.ts、convex/data.ts、convex/actions.ts、convex/rateLimit.ts、convex/admin.ts、convex/audit.ts 等文件中实现上述模式。实施前建议先查阅官方文档:https://docs.convex.dev/auth/functions-auth 与 https://docs.convex.dev/production,更广上下文见 https://docs.convex.dev/llms.txt。
适用场景:需要为 Convex 后端做安全审查、加固权限体系、防止越权访问与滥用、保护支付等关键函数的项目。
限制与注意事项:资料明确要求除非被明确指示,否则不要运行 npx convex deploy,也不要运行任何 git 命令;应实施纵深防御、记录敏感操作审计日志、对破坏性操作使用确认码、对所有面向用户的端点限流、不暴露内部 API 密钥或错误详情,并定期审查访问模式。常见陷阱包括单点认证失败、缺少审计日志、信任客户端数据、暴露错误详情和无限流。具体部署与收费信息暂未提供。