fix(plugin-auth): serve /admin/ban-user and /admin/unban-user with the ADR-0068 platform-admin gate

[os-warren]

Part of #9652

⚠️ Deliberately Part of, not the closing keyword. #9652's title is
"every better-auth-native /admin/ route"; this PR repairs two of eleven and
splits the rest into #9968 / #9969 with the measurement attached. Merging must
not close the parent while its scope is still open. Switch this line to the
closing form only if the maintainer accepts the split as the final scope.

The first deliverable: the measured branch answer is Option 2

The 2026-08-18 ruling asked for a measurement before code: can better-auth's
admin plugin be pointed at ObjectStack's predicate (Option 1), or must the
routes be re-implemented as ObjectStack raw mounts (Option 2)?

Measured against the installed better-auth 1.7.1 (the family moved onto
stable in #9869 / 03520ebef, so the card's rc-era text was not used).

The vendor cannot express the predicate. Evidence, in the order it decides
the question:

1. The whole option surface. AdminOptions declares exactly defaultRole,
   adminRoles, defaultBanReason, defaultBanExpiresIn,
   impersonationSessionDuration, schema, ac, roles, adminUserIds,
   bannedUserMessage, allowImpersonatingAdmins. There is no predicate
   hook, no roles-source callback, and no async resolver — the shapes the
   ruling asked me to look for do not exist.

2. Authorization has exactly two inputs. Every gated route calls
   hasPermission({ userId, role: session.user.role, options: opts, permissions }),
   whose body short-circuits on options.adminUserIds?.includes(userId) and
   otherwise splits session.user.role on commas against options.roles.

3. adminUserIds cannot carry a dynamic predicate. opts is built once at
   plugin construction (const opts = { ...options, ... }), so the array is
   frozen there, while ObjectStack's platform-admin set is a per-request read of
   sys_user_permission_set for a row pointing at admin_full_access with
   organization_id = null. Every way to make that array dynamic is worse than
   the bug: mutating a shared array leaves a demoted admin a stale pass
   (fail-open — turning a broken-capability defect into a security one), and
   overriding includes needs a synchronous answer to an asynchronous question.

4. The session-scoped middle path is mechanically shut — this is the one the
   dispatch explicitly asked me to watch for, and it is the reason the answer is
   not "configure it". Every /admin/* route mounts adminMiddleware, which
   calls getAuthoritativeSessionFromCtx. On any deployment carrying a
   database — i.e. every ObjectStack deployment, since
   hasServerSessionStore(options) is !!options.database || !!options.secondaryStorage
   — that helper sets ctx.context.session = null and re-reads the session from
   the DB with disableCookieCache: true. Anything ObjectStack writes onto
   the in-memory session user is discarded before hasPermission sees it.
   customSession is not a second door either: it overrides the /get-session
   endpoint, not the session the admin routes resolve internally.

So the only input the vendor will accept is the persisted user.role scalar,
and producing that is Option 3 — permanently vetoed. Option 2 it is.

What this PR ships

/admin/ban-user and /admin/unban-user become ObjectStack raw mounts carrying
the ADR-0068 gate, joining create-user / set-user-password / unlock-user /
import-users / oauth2/toggle-disabled. These are the two routes that (a) a
sys_user action actually calls and (b) re-implement faithfully — the vendor
handlers are internalAdapter.updateUser plus deleteUserSessions, mirrored
field for field (banned / banReason / banExpires / updatedAt, default
reason 'No reason'). A banned user is still refused at sign-in by the vendor's
own untouched session hook (BANNED_USER).

Two supporting extractions, both of which close a class rather than an instance:

• platform-admin-gate.ts — the ADR-0068 gate existed as four near-identical
  inline copies. One exported judge now serves every ObjectStack /admin/*
  mount. role === 'admin' survives only as the back-compat fallback it already
  was; nothing synthesizes it.
• last-local-credential.ts — ⚠️ shadowing a vendor path with a raw mount
  silently detaches every better-auth hook keyed on that path.
  /admin/ban-user carried one: the break-glass "never remove the last local
  password login" guard in auth-manager.ts. It is now one module with two call
  sites rather than a guard a future raw mount can forget. This trap is written
  into the module header because it is the main hazard in finishing impersonate_user and set_user_role still 403 every platform admin — neither route is safely raw-mountable, and each blocks for a different reason #9968/finding: seven better-auth /admin/ routes refuse platform admins and have no ObjectStack consumer — decide whether they are capability or just vendor surface #9969.

A 501 NOT_IMPLEMENTED guard mirrors create-user's: without it the mounts would
answer 200 on a deployment with no admin plugin, writing banned: true while
the vendor hook that enforces a ban is not loaded — a ban the console reports
as succeeding and the banned user signs straight through.

What this PR deliberately does not ship

• impersonate_user and set_user_role still 403 every platform admin — neither route is safely raw-mountable, and each blocks for a different reason #9968 — impersonate-user (the user-visible residue) and set-role. The
  console's "Impersonate User" button still 403s for platform admins after this
  PR. impersonate-user is not safely raw-mountable: the vendor handler mints
  a session and signs cookies with helpers that exist only inside a better-auth
  endpoint context, its admin_session cookie payload is a parsing contract with
  /admin/stop-impersonating, and shadowing it would detach
  rotateCallerBearerOnImpersonation — reintroducing the better-auth bearer plugin lets a bearer session silently shadow an impersonation the server just created — /admin/impersonate-user returns 200 and is a no-op for any bearer client #8243 defect with
  nothing to notice. set-role is one line to re-implement, and that line writes
  the exact legacy scalar Option 3 forbids (it still feeds positions[] via
  storedRole.split(',')), so shipping it would hand an admin a supported UI
  path to resurrect the dual identity representation one user at a time.
• finding: seven better-auth /admin/ routes refuse platform admins and have no ObjectStack consumer — decide whether they are capability or just vendor surface #9969 — the seven routes with no ObjectStack consumer at all
  (remove-user, revoke-user-session, revoke-user-sessions,
  list-user-sessions, update-user, list-users, get-user). Named
  explicitly there so the record needs no re-derivation.

Verification

Ablation, per the standing lane clause — the predicate wiring removed,
plugin-auth rebuilt, and the mutation proven to have reached dist
(ablation-dist-preflight ... --absent gives marker absent from all 12 built
files) before any colour was read:

/auth/admin/ban-user     admin  -> 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_BAN_USERS"}
/auth/admin/ban-user     member -> 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_BAN_USERS"}
/auth/admin/unban-user   admin  -> 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_BAN_USERS"}
/auth/admin/unban-user   member -> 403 {"code":"YOU_ARE_NOT_ALLOWED_TO_BAN_USERS"}

The platform admin and the plain member receive byte-identical refusals —
the defect, reproduced by construction at this branch point, which also
re-confirms the card's repro set on 1.7.1. The pin goes red in that state
(1 failed / 6 passed) and the control holds: the universal-invariant test — no
anonymous caller and no plain member gets a 2xx from any of the 31 derived
/admin/ routes — stayed green through the ablated leg.

The restore leg was rebuilt too, and the marker proven present in dist
(2 built files) before re-reading: 7 passed (7). The source file was restored
byte-identically, verified by git hash-object
(9a502aae96527ac9d87cf2a88efe2214287905e7 before and after), not by a matching
diffstat.

Gates and suites, all at final head d9a09995:

check	result
pnpm --filter @objectstack/plugin-auth typecheck	pass (tsc --noEmit, no output)
pnpm --filter @objectstack/plugin-auth test	1283 passed (1283), 56 files
dogfood admin-route-nonadmin-refusal	7 passed (7)
check:slot-lookup · check:test-source-alias · check:type-source-resolution · check-affected-docs	pass (the four named at dispatch)
check:route-envelope · check:changeset-gate-self-tests · check:objectui-changeset · check:engine-double-contract · check:where-matcher · check:query-options-erasure · check:nul-bytes	pass
spec check:liveness · check:empty-state · check:strictness-ledger · check:variant-docs	pass
check-adr-0087-registration · check-changeset-no-major · check-empty-changeset	pass

The set beyond the four named at dispatch came from re-deriving against the
actual diff with node scripts/pm/dispatch-gates.mjs (no hand-built path list).
check:route-envelope was the notable addition — it is triggered by
auth-plugin.ts specifically and the dispatch list did not name it.

One declared narrowing: check:type-check-debt --re-measure was not run
locally — it requires the whole workspace closure built and CI runs it on every
PR regardless.

The refactor's oracle is the pre-existing pins on the five already-gated routes:
the objectstack-gate bucket asserts anonymous 401 UNAUTHENTICATED, member
403 PERMISSION_DENIED and admin-not-refused on each of its routes, and it is
green across all 7 (5 pre-existing + 2 new) after the gate was collapsed into
one judge — zero behaviour change on the five.

Rejection cases assert code and status per ADR-0112, and the two
envelopes are kept apart on purpose: ObjectStack's {success,error:{code}} where
these mounts answer, better-auth's flat {message,code} where the vendor still
does.

Notes

• Serialisation note for the sibling card finding: the four /admin/sso/* bridges carry no ObjectStack-side admin gate, and their delegated authorization is unprovable on a stock boot #9653: this PR does touch
  auth-plugin.ts (two new mounts plus the gate collapse) and does not touch
  register-sso-provider.ts.
• The unit tests hand-patching role = 'admin' (e.g. remove-user-atomicity.test.ts)
  are left alone — they cover /admin/remove-user, which this PR does not
  re-mount, so the workaround is still load-bearing there.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth, touching 27 documentable anchor(s).

33 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 6aceca97143088c9c33e568c5dd49e5b7cfdf347.

⛔ 5 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/plugins/plugin-auth/src/index.ts) — pages documenting those are invisible to this run
• 4 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 11 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 6aceca97143088c9c33e568c5dd49e5b7cfdf347 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f4ef3fd964be59afa01fbb263170f5d31625ebae — the merge of head d9a099951478b643d754a998856924dd6642105c into base 6aceca97143088c9c33e568c5dd49e5b7cfdf347, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f4ef3fd964be59afa01fbb263170f5d31625ebae && git checkout f4ef3fd964be59afa01fbb263170f5d31625ebae
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 6aceca97143088c9c33e568c5dd49e5b7cfdf347 d9a099951478b643d754a998856924dd6642105c && git checkout -B drift-repro 6aceca97143088c9c33e568c5dd49e5b7cfdf347 && git merge --no-ff d9a099951478b643d754a998856924dd6642105c

node scripts/docs-audit/affected-docs.mjs --json 6aceca97143088c9c33e568c5dd49e5b7cfdf347

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 6aceca97143088c9c33e568c5dd49e5b7cfdf347 → pass the list as
args.docs, on the commit named under Which tree this was computed on.