fix(plugin-auth): the better-auth-native /admin/ routes refuse an anonymous caller with the ADR-0112 envelope (#10800)

* fix(plugin-auth): envelope the better-auth-native /admin/ refusals (#10349)

The `/api/v1/auth/admin/` namespace answered the same question in two shapes.
ObjectStack's raw mounts refuse an anonymous caller with the ADR-0112 envelope
and `code: 'UNAUTHENTICATED'` (`platform-admin-gate.ts`); the routes better-auth
serves itself refuse through the vendor's `adminMiddleware`
(`APIError.fromStatus('UNAUTHORIZED')`, no body argument), which reaches the
client as a 401 announcing `application/json` and carrying the EMPTY STRING.

Measured on better-auth 1.7.1 through `AuthManager.handleRequest`, anonymous:
ten vendor-lane routes answered `401 ct=application/json len=0 body=""`.

`handleRequest` now gives those refusals the declared envelope at the one seam
every vendor route passes through, with the code DERIVED from the status by
ADR-0112's own `standardErrorCodeForHttpStatus` map — no new error code, no
literal to drift. Statuses and admission are unchanged.

Scope is the `/admin/` namespace (option C, not option B). The prefix test costs
no new concept: `handleRequest` already discriminates on `betterAuthEndpointPath`
twice, for `STOP_IMPERSONATING_PATH` and `SESSION_ERASURE_PATHS`.

Three narrowings, each pinned: a refusal that already carried a body keeps it
byte-for-byte; only 401/403 are named (a bodyless `/admin/oauth2/*` 404 and any
semantic 4xx the vendor owns stay as they are); nothing outside `/admin/` is
touched.

The dogfood sweep's `better-auth-gate` bucket tightens from
`[401, 403].includes(anon.status)` to the full ADR-0112 pin — status AND code —
which is the fix's own falsifiable assertion. That bucket documented this gap
instead of closing it, and nothing tracked closing it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

* test(dogfood): record the #10792 member-arm exception the tightened bucket exposed

The `better-auth-gate` bucket's member-arm vocabulary check was guarded by
`if (member.code !== undefined)`, and on every bodyless refusal the code WAS
undefined — so for those routes the check had never executed. Giving the vendor
lane an envelope made it executable, and it went red on the first run:
`/admin/remove-user` answers a SIGNED-IN member `401 UNAUTHENTICATED`, while
`set-role` and `update-user` answer the same bearer `403 YOU_ARE_NOT_ALLOWED_*`.

Measured on the booted showcase stack and controlled hermetically: the same
three fires against the in-memory engine give the member 403, both with no
`transaction` on the engine and with a pass-through one. So it is the real
erasure transaction (#7724, `SESSION_ERASURE_PATHS`) that the session re-read
inside `adminMiddleware` does not survive. Filed as #10792.

Recorded here as an ADDITIONAL accepted code for that one route, never as a
pin — the same reasoning the platform-admin arm below already carries. Pinning
today's 401 would turn the fix red, pinning the 403 is red today, and widening
the vocabulary for every route would let the next one drift in silence.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-warren

.changeset/admin-vendor-refusal-envelope.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/plugin-auth": minor
+---
+
+fix(plugin-auth): the better-auth-native `/admin/` routes refuse an anonymous caller with the ADR-0112 envelope (#10349)
+
+**BREAKING** response-shape change on the `/api/v1/auth/admin/` namespace,
+shipped as `minor` under the repo's launch-window convention for breaking
+changes.
+
+`/api/v1/auth/admin/` is served by two implementations and answered the same
+question in two shapes. ObjectStack's raw mounts (`create-user`,
+`set-user-password`, `unlock-user`, `import-users`, `ban-user`, `unban-user`,
+`oauth2/toggle-disabled`, `sso/*`) refuse an anonymous caller through
+`judgePlatformAdmin` with the declared envelope and `code: 'UNAUTHENTICATED'`.
+The routes better-auth serves itself refuse through the vendor's
+`adminMiddleware` — `getAuthoritativeSessionFromCtx(ctx)` then
+`APIError.fromStatus('UNAUTHORIZED')`, with no body argument at all.
+
+Measured on the installed better-auth 1.7.1, anonymous, through
+`AuthManager.handleRequest`: ten vendor-lane routes (`impersonate-user`,
+`set-role`, `revoke-user-sessions`, `revoke-user-session`,
+`list-user-sessions`, `update-user`, `list-users`, `get-user`,
+`has-permission`, `stop-impersonating`) answered `401` with a
+`content-type: application/json` header and the **empty string** as the body.
+A client that believes that header and parses the body throws on the refusal
+instead of branching on it, and a client that wants to branch has to know, per
+route, which of the two implementations happens to serve it — an
+implementation detail, not a contract.
+
+`AuthManager.handleRequest` now gives those refusals the declared envelope at
+the one seam every vendor route passes through. **Statuses are unchanged and
+admission is unchanged**: nothing that was refused is now admitted, nothing
+that was admitted is now refused, and no status moved. What is added is the
+machine-readable `code`, derived from the status by ADR-0112's own
+`standardErrorCodeForHttpStatus` map rather than spelled out again — so no new
+error code is registered and the vendor lane's anonymous refusal is now
+byte-identical to the ObjectStack lane's.
+
+Scope is the `/admin/` namespace only. Three narrowings hold the rest of the
+surface still, and each is pinned:
+
+- **A refusal that already carried a body keeps it, byte for byte.** The
+  signed-in non-admin's `403` with the vendor's own
+  `YOU_ARE_NOT_ALLOWED_TO_*` vocabulary is untouched; this change fills in an
+  empty body and never rewrites a spoken one.
+- **Only the two refusal statuses are named** (`401`, `403`). A bodyless `404`
+  such as `/admin/oauth2/*` with the `oidcProvider` plugin off, and any
+  semantic `4xx` the vendor owns, are left exactly as they are.
+- **Nothing outside `/admin/` is touched.** `POST /sign-in/email` still answers
+  `401 {"message":"Invalid email or password","code":"INVALID_EMAIL_OR_PASSWORD"}`,
+  measured identical on both sides of the change.
+
+Consumers that branch on the HTTP status are unaffected. Consumers that already
+parse the ObjectStack `/admin/*` envelope now get the same shape everywhere in
+the namespace, with no per-route knowledge required.
+
+<!-- adr-0087: not-required (no-migration-prescription) nothing is removed, renamed or narrowed: a refusal that carried an empty body under an `application/json` header now carries the declared envelope at the same status. No consumer expression has to be rewritten — a status branch keeps working unchanged, and an envelope branch that only ever matched the ObjectStack lane now also matches the vendor lane. There is no old spelling to migrate off, so there is nothing for `os migrate meta` to rewrite and no ADR-0087 ledger entry to make. -->

packages/plugins/plugin-auth/src/admin-impersonate-endpoint.test.ts

@@ -243,15 +243,23 @@ describe('the other direction — a non-entitled caller is still refused', () =>
     // "the gate said no".
     expect(res.status).toBe(401);
 
-    // ⚠️ Measured, and deliberately not dressed up: this refusal carries an
-    // EMPTY body — no ADR-0112 envelope, no `code`. It comes from the vendor's
-    // `adminMiddleware` (`APIError.fromStatus('UNAUTHORIZED')`), which runs
-    // before this endpoint's handler and is byte-identical on stock
-    // better-auth 1.7.1 for both `/admin/impersonate-user` and
-    // `/admin/set-role`. This card changes the AUTHORIZATION predicate, not the
-    // authentication middleware, so the shape is pinned as it is rather than
-    // asserted to be something it is not.
-    expect(await res.text()).toBe('');
+    // ⚠️ This assertion USED to read `expect(await res.text()).toBe('')` — the
+    // vendor's `adminMiddleware` (`APIError.fromStatus('UNAUTHORIZED')`, no body
+    // argument) refused an anonymous caller with the EMPTY STRING under a
+    // `content-type: application/json` header, on every better-auth-native
+    // `/admin/` route. #9968 changed the AUTHORIZATION predicate only and pinned
+    // that shape as it was rather than dressing it up.
+    //
+    // #10349 closed it at the ONE seam every vendor route passes through
+    // (`AuthManager.handleRequest` → `vendor-admin-refusal-envelope.ts`), so the
+    // anonymous refusal now carries the ADR-0112 envelope — `code` AND `status`
+    // — and is byte-identical to what the ObjectStack raw `/admin/*` mounts
+    // answer. Authorization here is still untouched: the 403 assertions above
+    // and the 200 below are unchanged.
+    expect(JSON.parse(await res.text())).toEqual({
+      success: false,
+      error: { code: 'UNAUTHENTICATED', message: 'Sign in first' },
+    });
   });
 
   it('an org owner/admin who is NOT a platform admin is refused', async () => {

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -30,6 +30,7 @@ import {
   type AuthEventAuditSurface,
 } from './auth-session-audit.js';
 import { SESSION_ERASURE_PATHS } from './session-tombstone.js';
+import { envelopeVendorAdminRefusal } from './vendor-admin-refusal-envelope.js';
 import {
   ADMIN_SESSION_COOKIE_KEY,
   STOP_IMPERSONATING_PATH,
@@ -3680,11 +3681,31 @@ export class AuthManager {
     // is left with an identity that still occupies the org roster and can no
     // longer sign in. Nothing tells the operator, and there is no way back.
     const endpointPath = this.betterAuthEndpointPath(request);
-    const response =
+    const vendorResponse =
       endpointPath !== undefined && SESSION_ERASURE_PATHS.has(endpointPath)
         ? await this.runSubjectErasureAtomically(runHandler)
         : await runHandler();
 
+    // [#10349] The better-auth-native `/admin/` routes refuse an anonymous
+    // caller through the vendor's `adminMiddleware`
+    // (`APIError.fromStatus('UNAUTHORIZED')`, no body argument), so the refusal
+    // reaches the client as a 401 that announces `application/json` and carries
+    // the EMPTY STRING — no envelope, nothing to branch on. The ObjectStack raw
+    // `/admin/*` mounts answer the identical question with the ADR-0112
+    // envelope and `code: 'UNAUTHENTICATED'` (`platform-admin-gate.ts`), and
+    // which of the two a caller gets depends only on which implementation
+    // happens to serve that route — an implementation detail, not a contract.
+    //
+    // This is the ONE seam every vendor route passes through, which is why the
+    // normalization belongs here and not in ten routes we do not own. It is
+    // scoped to the `/admin/` NAMESPACE (option C): the prefix test costs no new
+    // concept, because this method already discriminates on `endpointPath` twice
+    // above — `STOP_IMPERSONATING_PATH` and `SESSION_ERASURE_PATHS`.
+    //
+    // Status and admission are untouched; see the module header for the three
+    // narrowings and the measurement behind each.
+    const response = await envelopeVendorAdminRefusal(endpointPath, vendorResponse);
+
     if (response.status >= 500) {
       try {
         const body = await response.clone().text();

packages/plugins/plugin-auth/src/platform-admin-gate.ts

@@ -40,6 +40,21 @@ export type PlatformAdminVerdict =
   | { ok: true; actor: PlatformAdminActor }
   | { ok: false; refusal: PlatformAdminRefusal };
 
+/**
+ * The human half of the two refusals, keyed by the status that carries them.
+ *
+ * Lifted out of `judgePlatformAdmin` (whose bytes are unchanged) so the
+ * better-auth-native `/admin/` lane can answer an anonymous caller with the
+ * SAME body rather than a second string that merely looks the same today —
+ * see `vendor-admin-refusal-envelope.ts` (#10349). The machine half is not
+ * duplicated anywhere: it is ADR-0112's own derived-code map,
+ * `standardErrorCodeForHttpStatus`.
+ */
+export const PLATFORM_ADMIN_REFUSAL_MESSAGES: Readonly<Record<401 | 403, string>> = {
+  401: 'Sign in first',
+  403: 'Admin role required',
+};
+
 /**
  * Is this session user a platform admin under ADR-0068 D2?
  *
@@ -82,7 +97,10 @@ export function judgePlatformAdmin(session: unknown): PlatformAdminVerdict {
       ok: false,
       refusal: {
         status: 401,
-        body: { success: false, error: { code: 'UNAUTHENTICATED', message: 'Sign in first' } },
+        body: {
+          success: false,
+          error: { code: 'UNAUTHENTICATED', message: PLATFORM_ADMIN_REFUSAL_MESSAGES[401] },
+        },
       },
     };
   }
@@ -92,7 +110,10 @@ export function judgePlatformAdmin(session: unknown): PlatformAdminVerdict {
       ok: false,
       refusal: {
         status: 403,
-        body: { success: false, error: { code: 'PERMISSION_DENIED', message: 'Admin role required' } },
+        body: {
+          success: false,
+          error: { code: 'PERMISSION_DENIED', message: PLATFORM_ADMIN_REFUSAL_MESSAGES[403] },
+        },
       },
     };
   }