SuperAPI AI 工具集

convex-authz

数据与分析

查看项目

更新于 10-15 21:51

技能介绍

用途:审计并加固 Convex 应用的授权(authz)。它是专注权限的专项检查,不是通用代码评审;命中性能、schema、校验器等问题应交给 convex-reviewer。项目中没有 convex/ 目录时直接跳过。

主要能力与四类扫描目标:

  1. identity-from-arg:公开 query/mutation 的 args 声明 userId/actorId/ownerId/authorId/accountId(v.id(...)),而整个函数块不引用 ctx.auth,等于由客户端冒充身份。
  2. missing-ownership-check:公开 query/mutation 用 ctx.db.get(args.<xId>) 读取文档后直接 patch/delete/replace 或返回字段,块内没有任何 owner 字段与身份值的比较。
  3. PII 泄露的公开查询:公开 query 返回 email、revenue、ssn、password、token、auditLog 等敏感字段,且由客户端传入的 id 参数化、无 ctx.auth 把关。
  4. 写入时的父引用归属:公开 mutation 的 args 含父/容器表 v.id(...)(projectId、boardId、teamId、orgId 等),在 insert/patch 中作为外键使用,却未校验调用者拥有或属于该父文档。修复第 1 类后常残留此类,需单独复查每个剩余 v.id(...) 参数。

强制前置步骤:注入 ctx.auth 校验前,先确认存在带 provider 的 auth.config.ts,以及以认证主体(tokenIdentifier/identity.subject)为键的 users/identities 表。两者缺一即不得添加 requireIdentity/requireOwner——无基础的应用中 getUserIdentity() 恒为 null,强校验要么全部 401,要么与非 subject 字段(如 email 字符串)错误比较而被绕过。此时应:对特权/管理操作把公开 query/mutation 改为 internalQuery/internalMutation(消除公开可达性,无需 ctx.auth),并提示用户先运行 /add auth 或完成认证配置,再重跑 convex-authz。

加固方式:仅在有认证基础时进行,逐字复用 content/convex-expert.md 中的规范模式,不新造 helper。若有缺失则添加 convex/model/auth.ts,导出 requireIdentity(ctx)(identity 为 null 时抛 401)与 requireOwner(ctx, doc)(doc 为 null 抛 404,doc.ownerId !== identity.subject 抛 403)。改写命中函数:用 requireIdentity(ctx) 取代客户端传入的身份参数;对按 _id 读取/变更的调用先包一层 requireOwner;PII 查询经 requireIdentity/requireOwner 或显式 staff/role 校验收窄作用域;对第 4 类先加载父文档并校验归属或成员关系(如 participantIds.includes(user._id))再写子行。若 schema 以 users 行 id 记录归属,需先由 subject 索引解析调用者的 users 行,再与 user._id 比较,直接比较 Id<"users"> 与 subject 永不匹配。不得放宽作用域,正当操作任意用户的内部函数保持 internal 且不改动。

验证与报告:编辑后运行 npx tsc --noEmit(或项目 typecheck 脚本),未通过类型检查不算完成;再重跑扫描确认命中为 0。报告按四类规则分组,给出 文件:行、可利用性说明(谁能冒充谁、读谁的数据)以及具体 diff;无认证基础时给出内部化并延后的 diff 与认证设置提示,不要只做文字描述。