fix(plugin-auth): SCIM active:false disables the account again — route the vendor's reconcileUser hook to the platform ban write (#14360) (#14540)

* fix(plugin-auth): route @better-auth/scim's identity.reconcileUser to the platform ban write

SCIM active:false revoked sessions and wrote nothing on stable
@better-auth/scim (the vendor's ban write left the package in 1.7.0);
sys_user.banned was never set and a local-password user signed straight
back in. Wire identity.reconcileUser into the scim() options and route it
to the shared ban/unban write in admin-ban-endpoints.ts, inside the SCIM
transaction; the engine-level last-administrator guard judges it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

* test(plugin-auth): pin the refused-deactivation residual the dead SCIM transaction scope leaves (#14522)

The (c) face keeps the account enabled and the SCIM 403 shape; the vendor's
own scimUser.active write surviving the refusal is pinned as observed and
attributed to the adapter's SCIM transaction scoping never engaging on
1.7.2, so the fix for that seam flips the pin deliberately.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

* fix(plugin-auth): make a deactivated principal's expiring ban permanent; move the shared ban write off the barrel

Contract review round 1 (#14360): a SCIM active:false over an
administrator's TIMED ban left the expiry in place, and the vendor's
session hook auto-lifts an expired ban - so the principal was re-admitted
while the IdP still held them deactivated. The hook now clears banExpires
on that row (reason and banned untouched). The shared write moves to the
package-internal user-ban-write.ts (not re-exported from index.ts), so no
new public symbol ships and the changeset drops to patch. Two faces added:
the expiring-ban overlap and POST /Users with active:false.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

---------

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

Author: claude[bot]

.changeset/scim-active-false-reconcile-user.md

@@ -0,0 +1,5 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+SCIM `active: false` disables the account again. Stable `@better-auth/scim` (1.7.0+) no longer writes the admin plugin's `banned` column itself — it hands the aggregate lifecycle state to an optional host callback, `identity.reconcileUser`, and only revokes sessions. `plugin-auth` passed no `identity` member, so an identity provider deactivating a user revoked sessions and wrote nothing: `sys_user.banned` stayed false and a user holding a local password signed straight back in. `AuthManager` now implements the callback and routes it to the platform's own ban write: `active: false` bans the user (reason `Deactivated via SCIM`, no expiry) — and makes an administrator's existing EXPIRING ban permanent (`banExpires` cleared, the administrator's reason kept), because the vendor's session hook auto-lifts an expired ban and would otherwise admit a principal the identity provider still holds deactivated — and the vendor's `BANNED_USER` sign-in refusal applies; `POST /Users` with `active: false` provisions the account disabled. `active: true` lifts a ban that carries that reason — an administrator's ban (any other reason) is not the identity provider's to lift, so an attribute sync never re-admits a user banned for cause; the one documented collision is an administrator who types the reason `Deactivated via SCIM` themselves, which produces a ban the identity provider can lift. The last-LOCAL-credential guard the `/admin/ban-user` mount re-runs is deliberately not applied on the SCIM path: an identity-provider deprovision can disable the last password-holding account while non-administrator SSO users remain. The break-glass last-administrator guard (ADR-0024 D5.2) judges the write at the engine, so deactivating the last administrator through SCIM is refused with a 403 SCIM error and the account stays active. A SCIM `DELETE /Users/{id}` — which on 1.7.2 tombstones the source rather than deleting the user — now leaves that account disabled too. No new public symbol: the shared write lives in a package-internal module.

packages/plugins/plugin-auth/src/admin-ban-endpoints.ts

@@ -51,7 +51,9 @@
  * The writes mirror better-auth's own handlers field for field — `banned` /
  * `banReason` / `banExpires` / `updatedAt`, then `deleteUserSessions` — so a
  * banned user is signed out and refused at sign-in by the vendor's OWN session
- * hook (`BANNED_USER`), which is untouched. The default ban reason is
+ * hook (`BANNED_USER`), which is untouched. The write itself lives in the
+ * package-internal `user-ban-write.ts` (#14360), shared with the SCIM
+ * deprovisioning hook in `auth-manager.ts` — one write, two callers. The default ban reason is
  * `'No reason'` because ObjectStack configures no `defaultBanReason`.
  *
  * ⚠️ Shadowing a vendor route detaches every better-auth hook keyed on its
@@ -72,6 +74,7 @@ import {
   type CredentialAccountAdapter,
 } from './last-local-credential.js';
 import type { AdminActor, EndpointResult } from './admin-user-endpoints.js';
+import { applyUserBan, applyUserUnban } from './user-ban-write.js';
 
 /**
  * Minimal better-auth `$context` surface these two routes touch. Mirrors what
@@ -161,11 +164,9 @@ export async function runAdminBanUser(
     };
   }
 
-  await ctx.internalAdapter.updateUser(userId, {
-    banned: true,
+  await applyUserBan(ctx.internalAdapter, userId, {
     banReason,
     ...(banExpires ? { banExpires } : {}),
-    updatedAt: new Date(),
   });
   // Sign the banned user out everywhere, exactly as the vendor handler does.
   await ctx.internalAdapter.deleteUserSessions(userId);
@@ -197,12 +198,7 @@ export async function runAdminUnbanUser(
   const ctx = await deps.getAuthContext();
   if (!(await ctx.internalAdapter.findUserById(userId))) return notFound();
 
-  await ctx.internalAdapter.updateUser(userId, {
-    banned: false,
-    banReason: null,
-    banExpires: null,
-    updatedAt: new Date(),
-  });
+  await applyUserUnban(ctx.internalAdapter, userId);
 
   return { status: 200, body: { success: true, data: { userId, banned: false } } };
 }

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

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { Auth, BetterAuthOptions } from 'better-auth';
+import type { SCIMIdentityState, SCIMTransactionContext } from '@better-auth/scim';
 // better-auth value imports (betterAuth + plugins) are deferred via dynamic
 // import() in getOrCreateAuth() / buildPluginList() so that disabled plugins
 // never get loaded into the process. See Stage 2F (RSS investigation).
@@ -101,6 +102,11 @@ import {
   LAST_LOCAL_CREDENTIAL_CODE,
   LAST_LOCAL_CREDENTIAL_MESSAGE,
 } from './last-local-credential.js';
+import {
+  applyUserBan,
+  applyUserUnban,
+  SCIM_DEACTIVATION_BAN_REASON,
+} from './user-ban-write.js';
 import {
   PHONE_SMS_TOPICS,
   builtinPhoneSmsBody,
@@ -3276,6 +3282,16 @@ export class AuthManager {
               return verifyScimBearerToken(engine as never, secret, input.token);
             },
           },
+          // [#14360] The host half of `active`: stable @better-auth/scim
+          // writes no `banned` itself any more (the 1.6.x coupling left the
+          // package in 1.7.0) — it hands the aggregate lifecycle state to
+          // this callback inside the SCIM transaction and only revokes
+          // sessions. Routed to the platform's own ban write; the break-glass
+          // last-administrator guard judges it at the engine. See
+          // `reconcileScimUserLifecycle` for the contract and the measurement.
+          identity: {
+            reconcileUser: (state, context) => this.reconcileScimUserLifecycle(state, context),
+          },
         });
       });
     }
@@ -4840,6 +4856,140 @@ export class AuthManager {
     return auth.api;
   }
 
+  /**
+   * [#14360] `identity.reconcileUser` — the host half of SCIM `active`.
+   *
+   * `@better-auth/scim` 1.7.0 removed its own `banned` write (1.6.30 mapped
+   * `active` onto the admin plugin's ban and refused a deactivation without
+   * that plugin; on the installed 1.7.2 the substring `ban` occurs zero times
+   * in the package) and replaced it with this optional callback: the vendor
+   * computes the user's AGGREGATE lifecycle state — `active` is true while
+   * any participating SCIM source says so — inside the request's
+   * transaction, calls the host, and then revokes the user's sessions when
+   * the state is inactive (`dist/index.mjs`, the identity facade's
+   * `reconcileUser`). Without a host implementation an IdP's `active: false`
+   * revoked sessions and wrote nothing: `sys_user.banned` stayed false and a
+   * local-password user signed straight back in, while ADR-0071, the
+   * generated docs and the #13816 refusal all asserted the ban.
+   *
+   * This method restores declared = enforced by routing the state to the
+   * platform's OWN ban write (`admin-ban-endpoints.ts`):
+   *
+   *  - `active: false` on a row that is not banned ⇒ `applyUserBan` with
+   *    `SCIM_DEACTIVATION_BAN_REASON` and no expiry. The vendor's
+   *    `session.create` hook (`BANNED_USER`) then refuses sign-in — the same
+   *    enforcement the admin ban has, because it is the same write. On a row
+   *    that is ALREADY banned with an expiry (an administrator's timed ban),
+   *    the deactivation makes that ban permanent — `banExpires` is cleared,
+   *    `banned` and the administrator's reason are left untouched — because
+   *    the vendor's session hook auto-lifts an expired ban and would admit a
+   *    principal the IdP still holds deactivated, and this callback is not
+   *    re-invoked until the IdP mutates that user again.
+   *  - `active: true` on a row banned WITH that reason ⇒ `applyUserUnban`.
+   *    A ban carrying any other reason was placed by an administrator and is
+   *    not the IdP's to lift: an attribute sync (every SCIM PUT carries
+   *    `active: true`) must not silently re-admit a user banned for cause.
+   *    Known collision, documented rather than reserved: an administrator
+   *    who types the reason `Deactivated via SCIM` on the admin mount
+   *    produces a ban this rule reads as the IdP's, so an `active: true`
+   *    lifts it. Reserving the string on the admin mount would change that
+   *    surface, which is not this hook's to do.
+   *  - Anything else is a no-op. The callback is contractually idempotent
+   *    ("Implementations must be idempotent") and the vendor invokes it on
+   *    EVERY user mutation, so a PATCH that changes only `displayName`
+   *    touches no ban column.
+   *
+   * A consequence worth stating: on 1.7.2 a SCIM `DELETE /Users/{id}` no
+   * longer deletes the better-auth user (the vendor tombstones the source);
+   * it leaves the user with no active source, so this callback disables the
+   * account. Re-provisioning through the tombstone re-links the same user,
+   * the state turns active, and the SCIM ban is lifted by the second bullet.
+   *
+   * The break-glass last-administrator guard (ADR-0024 D5.2, #5892) is an
+   * ENGINE `beforeUpdate` hook on `sys_user`, so it judges this write exactly
+   * as it judges the admin mount's: deactivating the last administrator
+   * throws its 403 `PERMISSION_DENIED`, the adapter rethrows it as an
+   * `APIError`, the vendor re-throws `APIError`s unchanged out of this
+   * callback (`runSCIMApplicationCallback`, measured on 1.7.2 — any other
+   * throw becomes a SCIM 500 "SCIM identity reconciliation failed" carrying
+   * the original as `cause`), and the IdP receives a SCIM error with
+   * `status: "403"` and the guard's own explanation. The ban is ONE write,
+   * so it never half-lands: the account stays enabled and nothing is
+   * skipped silently.
+   *
+   * ⚠️ What does NOT roll back today: the vendor runs this callback inside
+   * `runWithTransaction`, which on this adapter is a real engine transaction
+   * only while `scimRequestScope` is set — and that scope, stamped inside
+   * `verifyBearerToken`, is not observed at write time on 1.7.2 (measured:
+   * zero `engine.transaction` calls across a SCIM POST + PATCH; #14522). So
+   * the vendor's own `scimUser.active = false` write, made before this
+   * callback, survives a refusal and the SCIM resource reads inactive while
+   * the account is enabled. #14522 owns that seam; the #14360 suite pins the
+   * residual so its fix flips the pin deliberately.
+   *
+   * Deliberately NOT applied here: the last-LOCAL-credential guard the admin
+   * mount re-runs (`isLastLocalCredentialHolder`). That guard protects the
+   * password escape hatch from an administrator's click; on this path the
+   * identity provider is the authority for the user it deprovisions, and
+   * keeping a departed user's password alive because it happened to be the
+   * last one is the wrong direction for a deprovisioning contract. 1.6.x
+   * never applied it on the SCIM path either — the vendor wrote the column
+   * straight through the adapter.
+   *
+   * Every read and write goes through `context.database` — the adapter the
+   * vendor bound to its transaction — never through an `internalAdapter`
+   * resolved outside it, so the moment #14522 makes that transaction real,
+   * the ban commits or rolls back with the SCIM mutation it belongs to.
+   */
+  private async reconcileScimUserLifecycle(
+    state: SCIMIdentityState,
+    context: SCIMTransactionContext,
+  ): Promise<void> {
+    const db = context.database;
+    const user = await db.findOne<{ banned?: unknown; banReason?: unknown; banExpires?: unknown }>({
+      model: 'user',
+      where: [{ field: 'id', value: state.userId }],
+    });
+    if (!user) {
+      // The vendor holds a `scimSubject` for this user inside the same
+      // transaction, so a missing row is an invariant break, not a state to
+      // reconcile. Thrown, not logged: the vendor turns it into a SCIM 500
+      // and rolls the mutation back — a deactivation that cannot find its
+      // account must not report success.
+      throw new Error(
+        `[auth] SCIM identity reconciliation: better-auth user '${state.userId}' has no sys_user row`,
+      );
+    }
+    const writer = {
+      updateUser: (id: string, data: Record<string, unknown>) =>
+        db.update({ model: 'user', where: [{ field: 'id', value: id }], update: data }),
+    };
+    const banned = user.banned === true;
+    if (!state.active) {
+      if (banned) {
+        // Already disabled — by an earlier SCIM pass or by an administrator.
+        // An administrator's TIMED ban is made permanent: the vendor's session
+        // hook auto-lifts an expired ban, and nothing re-invokes this callback
+        // until the IdP mutates the user again — so left alone, the expiry
+        // would re-admit a principal the IdP still holds deactivated. The
+        // reason stays the administrator's; only the expiry goes.
+        if (user.banExpires !== null && user.banExpires !== undefined) {
+          await writer.updateUser(state.userId, { banExpires: null, updatedAt: new Date() });
+        }
+        return;
+      }
+      await applyUserBan(writer, state.userId, {
+        banReason: SCIM_DEACTIVATION_BAN_REASON,
+        banExpires: null,
+      });
+      return;
+    }
+    if (!banned) return;
+    // An administrator's ban is not the IdP's to lift.
+    if (user.banReason !== SCIM_DEACTIVATION_BAN_REASON) return;
+    await applyUserUnban(writer, state.userId);
+  }
+
   /**
    * Get the underlying better-auth context for low-level operations such as
    * `internalAdapter.createAccount` / `password.hash`.