plugin-auth 的两处审计注释断言「better-auth 写入绕过 plugin-audit 订阅的 ObjectQL 生命周期钩子」——同 #4802 一类的机制漂移,需核实

[xuyushun441-sys]

在 #4802（databaseHooks 注释里「better-auth 适配器绕过 ql.registerMiddleware 链」已不成立）的核实过程中，发现同一包内另一条同类断言，落在不同的机制面上（生命周期钩子 / plugin-audit），与 #4802 的改动范围不重叠，按 Prime Directive #10 单独记录。

断言（两处同源抄写）

• packages/plugins/plugin-auth/src/admin-user-endpoints.ts（writeAdminAudit 上方）：

  Best-effort explicit audit row. better-auth writes bypass the ObjectQL lifecycle hooks that plugin-audit subscribes to, so admin identity operations would otherwise leave no compliance trail.

• packages/plugins/plugin-auth/src/admin-import-users.ts（run-level audit 上方）：

  Run-level audit (better-auth writes bypass the ObjectQL hooks that plugin-audit subscribes to).

初步反证（对着 origin/main 6bc93dc）

1. packages/objectql/src/engine.ts — insert() 的 triggerHooks('beforeInsert'/'afterInsert') 在 executeWithMiddleware() 的 executor 内部执行；better-auth 适配器走的就是普通 dataEngine.insert(...)（plugin-auth 的 databaseHooks 文档注释断言「better-auth 的适配器绕过 ObjectQL 中间件链」——已过时，今天 dataEngine 与 ql 是同一个实例 #4802 的逐跳核对已确认适配器与内核是同一个 ObjectQL 实例，且没有 bypass 选项）。
2. packages/plugins/plugin-audit/src/audit-writers.ts — writeAudit 以 engine.registerHook('afterInsert', writeAudit, { packageId }) 注册，没有 object 过滤；SKIP_OBJECTS 里有 sys_account / sys_session，没有 sys_user。
3. 同包内已有反例：auth-plugin.ts 的 SCIM 身份来源印戳正是用 engine.registerHook('afterInsert', …) 去接 better-auth 适配器直写 sys_account 的那条路径——即注册在 ObjectQL 上的生命周期钩子对适配器写入确实会触发。

即：admin/create-user 创建 sys_user 时，plugin-audit 的 afterInsert 看起来是会跑的，那两条注释给出的理由（"bypass 生命周期钩子"）与 #4802 是同一类过时机制断言。

但结论不一定错——需要有人认真核一遍

显式审计行大概率仍然该留，只是理由不同，候选理由至少有三条，需要核实后择一写进注释：

1. plugin-audit 是可选插件——admin 端点不能假定它装了；不装就真的没有合规痕迹。
2. 元数据不同——显式行记录的是 action: 'create' | 'update' + admin actor + 结构化 metadata（以及 import 的 run-level 汇总），plugin-audit 的通用行记录的是逐行 diff，两者不是一回事。
3. 可能反而是重复行——如果 plugin-audit 装了且钩子确实跑，sys_user 上是否已经在写第二条审计行？这是个独立的、值得量一量的问题。

建议做法

与 #4802 同款：保留纪律、更换理由，把注释改成核实后真实成立的那条，并指向代码位置；同时确认（或否认）第 3 点的重复行。

关联

• plugin-auth 的 databaseHooks 文档注释断言「better-auth 的适配器绕过 ObjectQL 中间件链」——已过时，今天 dataEngine 与 ql 是同一个实例 #4802（databaseHooks 注释的同类漂移，已修）
• objectstack-ai/cloud#1022（cloud 侧抄写）

未指派——记录的 finding，谁开工谁认领。

[xuyushun441-sys]

认领(PM 分派)

• session:session_018iARDqtrhQgz6fVHDeDkbQ
• 分支:claude/issue-4940-admin-audit-bypass-claim
• 车道:domain:identity(落点 packages/plugins/plugin-auth 的 admin-user-endpoints / admin-import-users,与在飞 PR docs(plugin-auth): 纠正 databaseHooks 的中间件绕过断言 (#4802) #4942 的文件不相交)

---

Generated by Claude Code

[xuyushun441-sys]

审核通过 — PR #4970 已取消草稿并挂上 auto-merge(SQUASH)

测量先行,而测量结果把两个对象劈成了两半 —— 这正是当初"分开测"警告的价值:

• sys_user:重复确认。 admin 建用户落两条 create 审计(显式 user.admin_created 一条 + plugin-audit 的 generic 一条),后者只可能来自 afterInsert hook —— 对 bypass 断言的直接驳倒。import 路径同理。
• sys_account:零重复。 它在 SKIP_OBJECTS 里,管理员重置密码的唯一痕迹就是那条显式行。"hook 都覆盖了,删掉显式行"是丢数据的改法 —— 所以 rationale-swap(留纪律、换理由)而非行为变更,判对了。

反向验证的构造是本单最亮的一笔:把 sys_user 临时塞进 SKIP_OBJECTS,造出旧注释描述的那个世界,新 gate 三个用例全红、失败输出里只剩显式那一行。断言是承重的,不是恒真。

测试落点的取舍与 #4802 形成正反两例,值得记成方法:plugin-auth 既不依赖 objectql 也不依赖 plugin-audit,所以 #4802 的跨包断言钉不进本包(指向既有 exact-match 断言是对的);而 qa/dogfood 两者都依赖,这次能钉就必须钉 —— 只改注释不加 gate,等于又立一条未验证断言,恰是本单要消灭的形状。小幅扩面(新增一个 dogfood 测试文件)有正当理由且与 #4942 零冲突,接受。

全仓扫尾干净:无第四处同错;pinyin-search / dogfood 那三处的 "bypass" 是另一个且为真的断言(直连 driver 确实跳过 engine hook),正确地未动。

两条未立单的观察,处置都对:① must_change_password 戳的 generic update 行 actor 为 NULL 而同请求的 create 行带 admin id —— dev 判断不了是否有意(可能属 system write),没有瞎立单,留给 #4586/ADR-0118 的 owner;记录在此,engine/services 车道 PM 若认为值得追,线索齐全。② @objectstack/verify 缺一个干净的 auth BootOption(现在只能靠 OS_SCIM_ENABLED 迂回打开 admin 面)—— 属他包公共 API,未擅自加;若 dogfood 后续再撞这堵墙,值得立单。

---

Generated by Claude Code