fix(plugin-auth): open the SCIM request scope at handleRequest so SCIM provisioning runs inside one engine transaction (#14624)

The adapter's `transaction` config opens a real `engine.transaction()` only
while `inScimRequestScope()` reads true. The scope was stamped with
`AsyncLocalStorage.enterWith` inside the `verifyBearerToken` callback handed
to `@better-auth/scim`, and on 1.7.2 the store never reached the writes: an
`enterWith` marks only the async resource it runs in and its descendants,
and the vendor resumes the endpoint handler from a continuation captured
before the verifier ran. Measured: zero `engine.transaction` and zero
`driver.beginTransaction` calls across POST /Users + PATCH /Users/{id},
`inScimRequestScope()` false inside every sys_user / sys_scim_user write.

`AuthManager.handleRequest` now opens the scope with `run(...)` around every
request whose better-auth endpoint path is under `/scim/v2` — the same seam
the actor-attribution scope and the subject-erasure transaction use, and
exactly as narrow as before: non-SCIM flows keep their sequential posture.

A refused last-administrator deactivation now rolls the vendor's own
`scimUser.active = false` write back; the #14360 suite's face (c) pin on that
residual is flipped from `false` to `true` deliberately. A new runtime pin
(`scim-transaction-scope.test.ts`) observes each SCIM mutation calling
`engine.transaction`, a failed provisioning leaving no partial identity, and
sign-up/sign-in opening zero transactions.


Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

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

Author: os-sales

.changeset/scim-transaction-scope-at-request-door.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+SCIM provisioning multi-writes now run inside one engine transaction, as the adapter's `#3653` scoping note already declared. On `@better-auth/scim` 1.7.2 the SCIM request scope was stamped with `AsyncLocalStorage.enterWith` inside the `verifyBearerToken` callback and was not observed at write time (measured: zero `engine.transaction` calls across `POST /scim/v2/Users` and `PATCH /scim/v2/Users/{id}`), so `sys_user`, `sys_scim_subject` and `sys_scim_user` landed as separate autocommits, and a refused deactivation left the SCIM resource reporting `active: false` for an account that was still enabled. `AuthManager.handleRequest` now opens the scope with `run(...)` around every request under `/scim/v2` — exactly as narrow as before; non-SCIM better-auth flows keep their sequential posture. A refused last-administrator deactivation now rolls the vendor's own `scimUser.active = false` write back, so the SCIM resource keeps reading `active: true`. The pin the #14360 suite held on that residual (`scim-deactivation-reconcile-user.test.ts`, face (c)) is flipped from `false` to `true` deliberately with this change, and a new runtime pin (`scim-transaction-scope.test.ts`) observes each SCIM mutation calling `engine.transaction`.

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

@@ -923,6 +923,22 @@ export function ipMatchesRange(ip: string, range: string): boolean {
  */
 const SMS_QUOTA_EXCEEDED_CODE = 'TOO_MANY_REQUESTS';
 
+/**
+ * [#14522] The better-auth endpoint path prefix every SCIM 2.0 protocol
+ * endpoint lives under (`/scim/v2/Users`, `/scim/v2/Groups/:groupId`, …) —
+ * the same predicate `@better-auth/scim` uses for its own after-hook matcher
+ * (`context.path?.startsWith("/scim/v2")`). A request under it runs inside
+ * `scimRequestScope`; see `handleRequest`.
+ */
+const SCIM_PROTOCOL_PATH_PREFIX = '/scim/v2';
+
+function isScimProtocolPath(endpointPath: string | undefined): boolean {
+  return (
+    endpointPath === SCIM_PROTOCOL_PATH_PREFIX ||
+    endpointPath?.startsWith(`${SCIM_PROTOCOL_PATH_PREFIX}/`) === true
+  );
+}
+
 /**
  * #6039 — is this `SendSmsResult.error` the quota wall's refusal?
  *
@@ -3266,17 +3282,22 @@ export class AuthManager {
     if (enabled.scim) {
       await this.addOptionalPlugin(plugins, 'scim', async () => {
         const { scim } = await import('@better-auth/scim');
-        const { verifyScimBearerToken, scimRequestScope } = await import('./scim-connection-service.js');
+        const { verifyScimBearerToken } = await import('./scim-connection-service.js');
         const secret = this.resolveAuthSecret();
         return scim({
           connections: [],
           authentication: {
             verifyBearerToken: async (input) => {
-              // Mark the remainder of this request's async chain as a SCIM
-              // protocol request, so the adapter runs its provisioning writes
-              // inside a REAL engine transaction (see scimRequestScope's
-              // rationale in scim-connection-service.ts).
-              scimRequestScope.enterWith({ scim: true });
+              // ⛔ No `scimRequestScope.enterWith(...)` here. The SCIM request
+              // scope that makes the adapter open a REAL engine transaction is
+              // opened by `handleRequest` with `run(...)` around the whole
+              // request (see `SCIM_PROTOCOL_PATH_PREFIX`). It used to be
+              // stamped from this callback and never reached the writes: an
+              // `enterWith` marks only the async resource it runs in and that
+              // resource's descendants, and the vendor resumes the endpoint
+              // handler from a continuation captured BEFORE this verifier ran
+              // (measured on 1.7.2 — zero engine transactions across a SCIM
+              // POST + PATCH; pinned by `scim-transaction-scope.test.ts`).
               const engine = this.config.dataEngine;
               if (!engine) return null; // no store to verify against — fail closed
               return verifyScimBearerToken(engine as never, secret, input.token);
@@ -4740,10 +4761,32 @@ 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);
+
+    // [#3653 / #14522] A SCIM protocol request (`/scim/v2/*`) runs inside
+    // `scimRequestScope`, which is what makes the adapter's `transaction`
+    // config open a REAL engine transaction around the vendor's provisioning
+    // multi-writes (`objectql-adapter.ts`, the scoping note there). Opened
+    // HERE, with `run(...)` around the whole request, for the same reason the
+    // actor-attribution scope above is: `run` has a callback boundary that
+    // every `als.run` the vendor performs underneath nests inside. The stamp
+    // used to be an `enterWith` inside the SCIM plugin's `verifyBearerToken`
+    // callback, and it never reached the writes — the vendor resumes the
+    // endpoint handler from a continuation captured before the verifier ran
+    // (measured on 1.7.2: zero `engine.transaction` calls across
+    // `POST /Users` + `PATCH /Users/{id}`). Keyed on the endpoint path prefix
+    // so it is exactly as narrow as before — SCIM protocol requests only; the
+    // non-SCIM flows keep their sequential posture, which the scoping note
+    // records as load-bearing. Pinned by `scim-transaction-scope.test.ts`.
+    const runRequest = isScimProtocolPath(endpointPath)
+      ? async (): Promise<Response> => {
+          const { scimRequestScope } = await import('./scim-connection-service.js');
+          return scimRequestScope.run({ scim: true }, runHandler);
+        }
+      : runHandler;
     const vendorResponse =
       endpointPath !== undefined && SESSION_ERASURE_PATHS.has(endpointPath)
-        ? await this.runSubjectErasureAtomically(runHandler)
-        : await runHandler();
+        ? await this.runSubjectErasureAtomically(runRequest)
+        : await runRequest();
 
     // [#10349] The better-auth-native `/admin/` routes refuse an anonymous
     // caller through the vendor's `adminMiddleware`
@@ -4925,15 +4968,15 @@ export class AuthManager {
    * 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
+   * What ALSO rolls back: 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
+   * while `scimRequestScope` is set — and `handleRequest` opens that scope
+   * around every SCIM protocol request (#14522; it was once stamped inside
+   * `verifyBearerToken` with `enterWith` and never reached the writes). 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.
+   * callback, is rolled back with the refusal, and the SCIM resource keeps
+   * reading `active: true` for the account that stayed enabled — pinned by
+   * the #14360 suite's face (c).
    *
    * Deliberately NOT applied here: the last-LOCAL-credential guard the admin
    * mount re-runs (`isLastLocalCredentialHolder`). That guard protects the
@@ -4946,8 +4989,8 @@ export class AuthManager {
    *
    * 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.
+   * resolved outside it, so the ban commits or rolls back with the SCIM
+   * mutation it belongs to.
    */
   private async reconcileScimUserLifecycle(
     state: SCIMIdentityState,

packages/plugins/plugin-auth/src/objectql-adapter.ts

@@ -791,8 +791,16 @@ export function createObjectQLAdapterFactory(rawDataEngine: IDataEngine) {
   // Core better-auth flows never had native DB transactions here (the factory
   // default is the sequential as-is fallback), so they KEEP that historical
   // posture; the real transaction opens exactly where upstream's assertion
-  // demands it — inside an authenticated SCIM protocol request, marked by the
-  // auth manager's `verifyBearerToken` via `scimRequestScope`. Remaining
+  // demands it — inside a SCIM protocol request (`/scim/v2/*`), the scope
+  // `AuthManager.handleRequest` opens with `scimRequestScope.run(...)` around
+  // the whole request. ⚠️ It was once stamped with `enterWith` inside the
+  // `verifyBearerToken` callback and never reached this seam: an `enterWith`
+  // marks only the async resource it runs in and that resource's descendants,
+  // and the vendor resumes the endpoint handler from a continuation captured
+  // before the verifier ran — measured on 1.7.2 as zero engine transactions
+  // across POST + PATCH /Users while the mount-time assertion stayed green.
+  // The scope is therefore pinned at RUN time (`scim-transaction-scope.test.ts`:
+  // a SCIM mutation observed to call `engine.transaction`). Remaining
   // declared degrades on that path: an engine with no `transaction` API runs
   // the callback directly, and a driver without `beginTransaction` follows
   // the engine's ADR-0119 D1 warn-once degrade.

packages/plugins/plugin-auth/src/scim-connection-service.ts

@@ -42,10 +42,21 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 
 /**
  * Request-scoped marker: "the current async chain is a SCIM protocol
- * request". Entered by the auth manager's `verifyBearerToken` wrapper (the
- * first application code every authenticated SCIM request runs) via
- * `enterWith`, so it holds for the remainder of that request's async chain —
- * including the provisioning writes the plugin performs afterwards.
+ * request". Opened by `AuthManager.handleRequest` with `run(...)` around every
+ * request whose better-auth endpoint path is under `/scim/v2`, so it holds
+ * for that request's whole async chain — the endpoint handler and the
+ * provisioning writes the plugin performs inside it.
+ *
+ * ⛔ Not `enterWith`, and not from inside the `verifyBearerToken` callback:
+ * that is where it used to be stamped, and the store never reached the
+ * writes. An `enterWith` marks only the async resource it runs in and that
+ * resource's descendants; the vendor awaits the verifier from the endpoint's
+ * own frame and resumes the handler from a continuation captured before the
+ * verifier ran. Measured on `@better-auth/scim` 1.7.2: zero
+ * `engine.transaction` calls across `POST /Users` + `PATCH /Users/{id}`,
+ * `inScimRequestScope()` false inside every identity write. `run(...)` has a
+ * callback boundary; every `als.run` the vendor performs underneath nests
+ * inside it. Pinned at run time by `scim-transaction-scope.test.ts`.
  *
  * Read by `objectql-adapter.ts`'s `config.transaction`: SCIM requests get a
  * REAL engine transaction (the atomicity upstream's

packages/plugins/plugin-auth/src/scim-deactivation-reconcile-user.test.ts

@@ -475,16 +475,17 @@ describe('[#14360] deactivating the last administrator is refused through SCIM,
     expect(row?.ban_reason ?? null).toBeNull();
     await expectSignInAccepted(h, owner.email);
 
-    // RESIDUAL — pinned as observed, filed as #14522, ⛔ not this card's to
-    // fix: the vendor's own `scimUser.active = false` write, made BEFORE the
-    // callback inside what it believes is a transaction, survives the
-    // refusal, because the adapter's #3653 SCIM transaction scoping never
-    // opens an engine transaction on 1.7.2 (measured: 0 `engine.transaction`
-    // and 0 `driver.beginTransaction` calls across POST + PATCH /Users). So
-    // the SCIM resource reports `active: false` while the account is still
-    // enabled. When #14522 lands, this line flips to `true` DELIBERATELY —
-    // that is the whole reason it is asserted rather than left unread.
-    expect(await scimActive(h, owner.scimId)).toBe(false);
+    // [#14522] The vendor's own `scimUser.active = false` write, made BEFORE
+    // the callback inside its transaction, is rolled back WITH the refusal:
+    // the adapter's #3653 SCIM transaction scoping opens a real engine
+    // transaction now that the scope is opened at `handleRequest` (it was
+    // stamped with `enterWith` inside `verifyBearerToken` and never reached
+    // the writes — measured as 0 `engine.transaction` calls across POST +
+    // PATCH /Users). So the SCIM resource keeps reporting `active: true` for
+    // the account that stayed enabled. This line read `false` on purpose
+    // while that residual was open and was flipped DELIBERATELY with the fix;
+    // the positive control below is the genuine `false`.
+    expect(await scimActive(h, owner.scimId)).toBe(true);
   }, 60_000);
 
   it('(c) positive control: with a second administrator left behind, the same request succeeds', async () => {