fix(plugin-auth): run better-auth adapter writes as system context (#3164)

[os-zhuang]

背景

关闭 #3164(在 #3043 探索中发现)。better-auth 的 ObjectQL adapter(plugin-auth/src/objectql-adapter.ts)对读注入了 isSystem(绕开 control-plane 的 org-scope 读 hook),但写是无上下文透传。#2948 的静态 readonly UPDATE 剥离对任何非 system 的 update 生效;adapter 不带 caller context → !ctx?.isSystem 为 true → 剥离命中,静默丢弃 better-auth 自己对 readonly sys_user 列的写入:email(change-email)、banned/ban_reason/ban_expires(admin ban)。表现为「操作返回成功但数据没变」。

复现(机制级,已实证)

用真实引擎(ObjectQLPlugin,#2948 剥离生效)按 adapter 的确切调用形态engine.update(model, {id,...patch})(无 context)更新 readonly 列 email/banned:驱动实际收到的 update payload 只剩 { id, updated_at } —— email/banned 都被剥离。

dogfood HTTP 层不能直接触发用户可见症状:/auth/change-email 在 dev harness 返回 CHANGE_EMAIL_DISABLED,/auth/admin/ban-user 未挂载(404)。即在这些 better-auth 功能启用的部署里症状才显现;机制已在引擎层确证。

修复

withSystemReadContext → 重命名为 withSystemContext(保留一个发布周期的 deprecated 别名),对 insert/update/delete 也注入 isSystem(与读对称)。这是正确的:这些本就是身份权威自身的写入——对 managedBy: 'better-auth' 表的 user-context 写入已被上游 ADR-0092 的 identity write guard 拒绝,故此路径只承载 better-auth 的内部写入。

同时修正 content/docs/data-modeling/fields.mdx:readonly 行原写「insert may still seed it」,在 #3043(PR #3162,已合并)后已过时——readonly 现在在 INSERT 面也被服务端强制(经数据 API),创建时播种 readonly 列须 system 上下文。

关系

• security: 服务端 readonly 字段在 UPDATE 时未强制（可被用户上下文覆盖） #2948 / 安全:静态字段 readonly: true 仅 UI 层生效、服务端不强制 → 审批/状态/金额字段可被直接 PATCH 绕过写入(FLS 缺口) #3003(引擎级 readonly UPDATE 剥离)—— 本 issue 是其对 adapter 写入的回归面。
• 安全/设计:静态 readonly 的 INSERT 豁免让审批/状态字段可在创建时被直接播种(比 #3003 少一步) #3043 / PR fix(metadata-protocol): strip static readonly on INSERT at the data-write ingress (#3043) #3162(INSERT 面)—— 本修复是其 UPDATE 侧对偶:安全/设计:静态 readonly 的 INSERT 豁免让审批/状态字段可在创建时被直接播种(比 #3003 少一步) #3043 因「内部/adapter 写入不带 isSystem」把 INSERT 剥离改到了外部入口;引擎级的 UPDATE 剥离无此腾挪,故让 adapter 显式声明其写入为 system。
• tech-debt/tracking: 让「特权内部写入必须显式声明 isSystem」成为可检查契约(先立约束 → 增量迁移 → 收敛强制) #3166(内部写入方 isSystem 债的 tracking)—— 本修复是其中一项的落地。

测试 / 验证

• plugin-auth 全套 460 passed(adapter 写入现断言携带 isSystem;新增「writes run as system」用例)。
• dogfood 回归:two-doors-permission / single-tenant-identity-create / showcase-scope-depth / showcase-permission-seeding 共 17 passed(sign-in、org/member 读、权限播种、provenance 403 均正常)。
• 全量 pnpm build 71/71。

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Building	Preview, Comment	Jul 18, 2026 6:26am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth.

9 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/deployment/production-readiness.mdx(via @objectstack/plugin-auth)
• content/docs/getting-started/cli.mdx(via @objectstack/plugin-auth)
• content/docs/kernel/services-checklist.mdx(via @objectstack/plugin-auth)
• content/docs/permissions/authentication.mdx(via @objectstack/plugin-auth)
• content/docs/permissions/sso.mdx(via @objectstack/plugin-auth)
• content/docs/plugins/index.mdx(via @objectstack/plugin-auth)
• content/docs/plugins/packages.mdx(via @objectstack/plugin-auth)
• content/docs/releases/implementation-status.mdx(via @objectstack/plugin-auth)
• content/docs/releases/v9.mdx(via @objectstack/plugin-auth)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.