fix(auth): scope the adapter's native transactions to SCIM protocol requests (#3653)

Measured twice on the unscoped variant: better-auth wraps whole request
flows in adapter.transaction (runWithTransaction), so opening a real
driver transaction around every sign-in/sign-up starved the
single-connection sqlite pools — the dogfood showcase boot deadlocked on
'Acquire connection error' until the 180s hook timeout, in CI and
reproduced locally on this branch, with 337 sibling dogfood tests green.

The scim verifier now marks its request's async chain (AsyncLocalStorage
enterWith), and config.transaction opens a real engine.transaction only
inside that scope — exactly where assertNativeSCIMTransactions demands
atomicity. Every other better-auth flow keeps the sequential behaviour
it has always had under the factory's as-is fallback, so nothing existing
weakens. Re-measured after the fix: the deadlocked dogfood file passes in
19s (13/13), the credential-at-rest suite (which drives a real SCIM 2.0
request through the scoped transaction over better-sqlite3) stays green,
and the full plugin-auth suite is 81 files / 1660 tests green.

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

Author: claude

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

@@ -3120,12 +3120,17 @@ export class AuthManager {
     if (enabled.scim) {
       await this.addOptionalPlugin(plugins, 'scim', async () => {
         const { scim } = await import('@better-auth/scim');
-        const { verifyScimBearerToken } = await import('./scim-connection-service.js');
+        const { verifyScimBearerToken, scimRequestScope } = 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 });
               const engine = this.config.dataEngine;
               if (!engine) return null; // no store to verify against — fail closed
               return verifyScimBearerToken(engine as never, secret, input.token);

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

@@ -5,6 +5,7 @@ import { createAdapterFactory } from 'better-auth/adapters';
 import type { CleanedWhere, WhereOperator } from 'better-auth/adapters';
 import { SystemObjectName } from '@objectstack/spec/system';
 import { resolveAttributedUserId } from './auth-actor-attribution.js';
+import { inScimRequestScope } from './scim-connection-service.js';
 import { adoptExistingMembership } from './adopt-membership.js';
 import {
   filterRevokedSessionRows,
@@ -768,30 +769,34 @@ export function createObjectQLAdapterFactory(rawDataEngine: IDataEngine) {
   const remapWhere = (where: CleanedWhere[]): CleanedWhere[] =>
     where.map((c) => ({ ...c, field: camelToSnake(c.field) }));
 
-  // [#3653] NATIVE transactions. Stable `@better-auth/scim` refuses to mount
-  // on an adapter whose `transaction` is the factory's sequential fallback
-  // (`assertNativeSCIMTransactions` reads `adapterConfig.transaction` and
-  // demands a function) — provisioning multi-writes must be atomic. The
-  // implementation is ObjectQL's own `engine.transaction()`: it publishes the
-  // handle into the engine's AMBIENT transaction store (ADR-0034), so every
-  // engine call the raw methods below make inside the callback automatically
-  // binds to the same connection/rollback scope — the trx adapter handed to
-  // the callback is therefore the SAME wrapped adapter, captured at factory
-  // time below.
+  // [#3653] NATIVE transactions, SCOPED to SCIM protocol requests. Stable
+  // `@better-auth/scim` refuses to mount on an adapter whose `transaction` is
+  // the factory's sequential fallback (`assertNativeSCIMTransactions` reads
+  // `adapterConfig.transaction` and demands a function) — provisioning
+  // multi-writes must be atomic. The implementation is ObjectQL's own
+  // `engine.transaction()`: it publishes the handle into the engine's AMBIENT
+  // transaction store (ADR-0034), so every engine call the raw methods below
+  // make inside the callback automatically binds to the same
+  // connection/rollback scope — the trx adapter handed to the callback is
+  // therefore the SAME wrapped adapter, captured at factory time below.
   //
-  // ⚠️ Scope this honestly: better-auth routes its OWN multi-writes through
-  // `adapter.transaction` too — sign-up (user + account) included, measured —
-  // so this is the transaction path for EVERY better-auth flow, not a
-  // scim-only seam, and it must keep the same degrade contract those flows
-  // had under the factory's sequential fallback. Two declared degrades:
-  //  - an engine with no `transaction` API at all (test doubles, minimal
-  //    IDataEngine implementations) runs the callback directly — exactly the
-  //    factory's own `createAsIsTransaction` behaviour;
-  //  - a driver without `beginTransaction` follows the engine's OWN declared
-  //    contract (ADR-0119 D1): run directly, warn once (#4619). Every SQL
-  //    production driver has `beginTransaction`, so a real deployment's scim
-  //    provisioning is genuinely atomic; fail-closed here (`require: true`)
-  //    was measured to 500 every sign-up on the memory engine.
+  // ⚠️ The scoping is load-bearing, measured twice, not a hedge. better-auth
+  // wraps its OWN whole request flows in `adapter.transaction` too
+  // (`runWithTransaction` — sign-in/sign-up included), and two unscoped
+  // variants each broke a measured surface:
+  //  - `require: true` (fail closed on non-transactional drivers) 500'd every
+  //    sign-up on the memory engine — 275 plugin-auth tests red;
+  //  - unconditional real transactions starved the single-connection sqlite
+  //    pools: the dogfood showcase boot deadlocked on `Acquire connection
+  //    error` until the 180s hook timeout, in CI and reproduced locally.
+  // 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
+  // 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.
   let wrappedAdapter: unknown = null;
   const engineWithTx = rawDataEngine as unknown as {
     transaction?<T>(
@@ -819,8 +824,12 @@ export function createObjectQLAdapterFactory(rawDataEngine: IDataEngine) {
           // rather than hand the callback a null adapter.
           throw new Error('[objectql-adapter] transaction requested before the adapter was constructed');
         }
+        // Non-SCIM better-auth flows keep their historical sequential
+        // behaviour — see the #3653 scoping note above for the two measured
+        // breakages that make this conditional load-bearing.
+        if (!inScimRequestScope()) return cb(wrappedAdapter as never);
         if (typeof engineWithTx.transaction !== 'function') {
-          // Declared degrade #1 (see the #3653 note above): no transaction API
+          // Declared degrade (see the #3653 note above): no transaction API
           // on this engine — run directly, as the factory fallback would.
           return cb(wrappedAdapter as never);
         }

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

@@ -38,6 +38,34 @@
  */
 
 import { createHmac, randomBytes } from 'node:crypto';
+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.
+ *
+ * Read by `objectql-adapter.ts`'s `config.transaction`: SCIM requests get a
+ * REAL engine transaction (the atomicity upstream's
+ * `assertNativeSCIMTransactions` exists to demand), while every other
+ * better-auth flow keeps the sequential behaviour it has always had. The
+ * scoping is load-bearing, measured, not a convenience: better-auth wraps
+ * WHOLE request flows in `adapter.transaction` (`runWithTransaction`), and
+ * opening a real driver transaction around every sign-in/sign-up starved the
+ * single-connection sqlite pools — the dogfood showcase boot deadlocked on
+ * `Acquire connection error` until the hook timeout, reproduced in CI and
+ * locally (#3653). Core flows never had native DB transactions before (the
+ * adapter factory's default is the sequential as-is fallback), so this keeps
+ * them at their historical posture rather than weakening anything.
+ */
+export const scimRequestScope = new AsyncLocalStorage<{ scim: true }>();
+
+/** Is the current async chain inside an authenticated SCIM protocol request? */
+export function inScimRequestScope(): boolean {
+  return scimRequestScope.getStore()?.scim === true;
+}
 
 /** The ObjectStack-owned credential store (see platform-objects/identity). */
 export const SCIM_CREDENTIAL_OBJECT = 'sys_scim_connection_credential';