Every better-auth-native /admin/ route refuses ObjectStack platform admins — the vendor gates on the legacy `user.role === 'admin'` scalar ADR-0068 D2 stopped synthesizing

[os-zhuang]

Measured 2026-08-18 while pinning identity-auth.admin-lifecycle-operations (#9482). Filed unassigned; not fixed there — the fix is a product decision, and #9482 is a tests-only card.

What happens

On a stock showcase boot with the better-auth admin plugin on (OS_SCIM_ENABLED=true, the documented ADR-0071 derivation), the seeded platform admin is refused by every better-auth-native /admin/ endpoint:

POST /api/v1/auth/admin/ban-user 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_BAN_USERS"}
POST /api/v1/auth/admin/unban-user 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_BAN_USERS"}
POST /api/v1/auth/admin/set-role 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_CHANGE_USERS_ROLE"}
POST /api/v1/auth/admin/impersonate-user 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_IMPERSONATE_USERS"}
POST /api/v1/auth/admin/revoke-user-sessions 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_REVOKE_USERS_SESSIONS"}
POST /api/v1/auth/admin/list-user-sessions 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_LIST_USERS_SESSIONS"}
GET /api/v1/auth/admin/list-users 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_LIST_USERS"}
GET /api/v1/auth/admin/get-user 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_GET_USER"}

The admin identity is correct in every ObjectStack sense — get-session returns positions: ["user","platform_admin"], isPlatformAdmin: true — and sys_user.role is 'user'.

Why

Two decisions that are each individually reasonable meet head-on:

1. auth-manager.ts constructs the vendor plugin as admin({ schema: buildAdminPluginSchema() }) — no adminRoles, no adminUserIds — so better-auth's default adminRoles: ['admin'] applies and its adminMiddleware authorizes on the user.role scalar.
2. ADR-0068 D2 deliberately stopped producing that scalar. auth-manager.ts says so in as many words: "rather than synthesizing user.role = 'admin', both paths now contribute CANONICAL names to user.positions", and "consumers must gate on positions[] / isPlatformAdmin … never on user.role === 'admin'".

Confirmed by construction, same boot: writing role = 'admin' onto that same admin row flips ban-user, unban-user, list-users and impersonate-user to 200 immediately (ban then persists banned: true / ban_reason, and the banned user's sign-in is refused 403 BANNED_USER). So the endpoints work; only the identity predicate does not match.

Corroboration this is not a harness artifact

• admin-user-endpoints.ts documents the same mechanism as the reason it exists: /admin/create-user and /admin/set-user-password are re-implemented as ObjectStack raw mounts because the stock endpoint's adminMiddleware "would 403 a platform admin whose legacy role scalar was never synthesized". Those two, plus unlock-user, import-users and oauth2/toggle-disabled, carry the ADR-0068 gate and work correctly (member 403 PERMISSION_DENIED, admin 2xx). The rest were never re-implemented.
• remove-user-atomicity.test.ts works around it in-process: userRow(engine, admin.userId).role = 'admin' with the comment "better-auth's admin plugin authorizes by user.role (default adminRoles: ['admin'])". That is why no existing test observes this — the unit tests synthesize the scalar a real deployment never gets.

User-visible impact

sys_user's ban_user, unban_user and impersonate_user actions are type: 'api' proxies onto exactly these routes, gated requiresFeature: 'admin'. On any deployment where the admin plugin is on (SCIM forces it, ADR-0071), the console renders Ban / Unban / Impersonate buttons that 403 for a platform admin.

This fails closed — no unauthorized access, and QA run #9401's "no access-control hole" verdict is unaffected. It is a broken admin capability, not an escalation. Same defect class as #4839 (an admin exemption reading a field nothing populates).

Options (a decision, not an obvious fix)

1. Configure the vendor to ObjectStack's predicate — admin({ adminRoles: [...] }) or adminUserIds, if better-auth can be pointed at positions[]. Smallest change; depends on what the vendor's option surface allows.
2. Re-implement the remaining routes as ObjectStack raw mounts with the ADR-0068 gate, as create-user / set-user-password already are. Consistent with the established pattern; the most code.
3. Synthesize role = 'admin' for platform admins again. Directly contradicts ADR-0068 D2 and would need that ADR revisited, not just an edit.

Option 1 or 2 keeps ADR-0068 intact; 3 reopens it. Recommending 1 if the vendor supports a custom predicate, otherwise 2.

Repro

packages/qa/dogfood/test/admin-route-nonadmin-refusal.dogfood.test.ts (landing on #9482) derives the whole /admin/ surface and records this bucket; it deliberately asserts neither side of the admin's answer, so it stays green before and after a fix.

[os-support-ai]

Triage: needs-user-decision, domain:identity, type Bug. This is a real declared≠enforced defect (the sys_user ban/unban/impersonate actions and console buttons are declared and 403 for every platform admin on a real deployment), but every fix option changes an authorization predicate on the auth surface — that is the manual floor (security/permission boundary), not the auto-adjudication lane, even though it fails closed today. Dedup: no duplicate; #9653/#9654 are distinct /admin/ findings (SSO bridges, pre-auth shape probing).

Four-prism block (decision inputs; filer's options 1–3 in the card body):

1. Platform long-term coherence — Option 1 (point the vendor's admin predicate at ObjectStack's identity, if its option surface allows) keeps one authorization vocabulary (positions[], ADR-0068 D2) and zero re-implemented routes. Option 2 (raw-mount re-implementation with the ADR-0068 gate) extends an already-established in-repo pattern (create-user / set-user-password) but permanently forks the vendor's route surface. Option 3 (re-synthesize role='admin') reopens ADR-0068 D2 — contract regression, worst for coherence.
2. Measured business pull — real: on any SCIM-enabled deployment the console renders Ban / Unban / Impersonate buttons that always 403 for the platform admin; measured on a stock showcase boot, with a by-construction confirmation that the endpoints work once the predicate matches.
3. AI-agent error-resistance — Option 1 concentrates the predicate in one construction site (auth-manager.ts); Option 3 re-introduces the exact dual-source-of-truth (role scalar vs positions[]) that ADR-0068 D2 removed and that unit tests already have to hand-patch — the most error-prone shape. Option 2 is middling: correct gates, but N copies of them.
4. Startup scope discipline — Option 1 is the smallest diff if the vendor supports it (config, not code); Option 2 is the most code for capability parity we already claim. Recommend: Option 1 if better-auth's admin plugin accepts a custom predicate/roles source; else Option 2 — matching the filer's recommendation. Option 3 not recommended.

---

Generated by Claude Code

[os-support-ai]

Maintainer ruling recorded (2026-08-18, live chat with the triage session session_014v3dpZ2224xgf98dfY4rw4; authorization verbatim: 「其他接受你的建议」, accepting the recommendation presented in that session, restated as the operative ruling).

Ruling: Option 1 first, Option 2 as the fallback; Option 3 permanently vetoed.

1. First: probe better-auth's option surface for pointing the admin plugin's authorization at ObjectStack's predicate (positions[] / isPlatformAdmin) — adminRoles, adminUserIds, or a custom predicate hook if the vendor exposes one. If it can express the predicate, configure it; smallest change.
2. If the vendor cannot express it: re-implement the remaining /admin/ routes as ObjectStack raw mounts carrying the ADR-0068 gate, exactly as create-user / set-user-password / unlock-user / import-users / oauth2/toggle-disabled already are. The dev's first deliverable is the measured answer to which branch applies.
3. ⛔ Option 3 (re-synthesizing user.role = 'admin') is permanently vetoed — it reopens ADR-0068 D2 and resurrects the dual identity representation that decision exists to kill. Any future card proposing it needs a full ADR revisit, not a code change.

Label: needs-user-decision → pm:queue, domain:identity. The #9482 dogfood spec (admin-route-nonadmin-refusal.dogfood.test.ts) deliberately asserts neither side of the admin's answer — after the fix, tighten it to assert the 2xx side.

---

Generated by Claude Code