docs(adr): ADR-0092 — sys_user 档案字段经引擎 hook 委托，放开 edit affordance（RFC #2784）#2787
Merged
Merged
Conversation
…ne hook (#2784) Evaluation outcome for RFC #2784: open a narrow, server-enforced profile write path on sys_user instead of keeping name/image edits endpoint-only or relying on UI readonly flags. - D1 field tiers: profile-editable (name, image) / admin-surface-only (role, phone_number, manager_id, ai_access, ban columns) / never-direct (email, credentials, system-managed stamps) - D2 fail-closed beforeUpdate whitelist guard in plugin-auth, user-context writes only (better-auth adapter + system writes bypass); also closes the existing admin_full_access raw-write hole on sys_user - D3 single whitelist module; import upsert's UPDATE_ALLOWED_FIELDS becomes a superset-by-construction re-export (anti-drift, PR #2771) - D4 userActions.edit flip ships only after the guard exists (ADR-0049) - D5 permission topology unchanged: platform-admin only; self-service stays on better-auth /update-user - D6 afterUpdate hook invalidates cached session snapshots Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YGAN5VvvBi4YRGwpNT6e21
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
July 10, 2026 12:48
This was referenced Jul 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
针对 RFC #2784 的评估产出：新增 ADR-0092（Proposed），决策是否/如何放开
sys_user纯档案字段的标准表单编辑。仅文档，不含实现代码；ADR 通过后再立实现 issue。结论（TL;DR）
放开一条窄口径、服务端强制的档案写路径：
name、image；role/phone_number/manager_id/ai_access/ ban 列归专用管理面；email、凭据、全部 system-managed stamp 列永不直写。phone_number是登录标识（唯一索引）、manager_id驱动own_and_reportsRLS 范围，都排除在表单层之外。beforeUpdate白名单守卫 hook（fail-closed，仅拦截用户上下文写入；better-auth adapter 与 system 写入不受影响）。不采用仅 UI readonly 的方案 —— 调研发现字段级readonly在服务端只是校验跳过而非写入拦截，违反 ADR-0049。附带收益：堵上现存漏洞 ——admin_full_access今天就能经 data API 裸写sys_user任意列（含 email）。UPDATE_ALLOWED_FIELDS（PR feat(auth): 管理员直建用户 + 手机号登录 + sys_user 批量导入（#2766 V1/V1.5/V2） #2771）改为 superset-by-construction 复用，杜绝两处漂移。sys_user上加userActions: { edit: true }（create/import/delete 保持关闭）；顺序是硬约束（ADR-0049）。allowEdit: false，标准编辑路径实际只对平台管理员开放；自助改档案继续走 better-auth/update-user（既有update_my_profileaction）。afterUpdatehook 令该用户的 secondary-storage 会话快照失效，不把写入委托给internalAdapter.updateUser（避免 adapter→engine 重入与 API 耦合）。主要调研依据
packages/spec/src/data/object.zod.ts—resolveCrudAffordances/userActions仅为 UI 提示；sys_user的 data API 全量开启。packages/objectql/src/engine.ts+validation/record-validator.ts— 静态readonly不在服务端拦截写入（仅readonlyWhen被 strip）。packages/plugins/plugin-auth/src/objectql-adapter.ts— better-auth 写入本身走engine.update，守卫必须按调用上下文而非对象区分。packages/plugins/plugin-security/src/objects/default-permission-sets.ts— 现有 deny 拓扑与sys_userRLS carve-out。packages/plugins/plugin-auth/src/admin-import-users.ts—UPDATE_ALLOWED_FIELDS = {name, phone_number, role}（与表单层白名单刻意不同，故取"同源派生"而非"同一份集合"）。后续
ADR 接受后按 Rollout 章节立实现 issue（守卫 hook + 白名单模块 + import 重构 + 测试 → D6 → affordance 翻转 + objectui 验证）。
Closes #2784 需等实现落地，此 PR 仅关联不关闭。
🤖 Generated with Claude Code
https://claude.ai/code/session_01YGAN5VvvBi4YRGwpNT6e21
Generated by Claude Code