feat(cli,create-objectstack): retire the @better-auth/scim>better-call suppression with the pin; adapter transaction degrades declared (#3653)

Epic item 7, same stroke as the pin move: stable 1.7.1 peers
better-call@1.4.0 exactly, so the rc-era allowedVersions key retires in
its two declared places (SCAFFOLD_ALLOWED_PEER_VERSIONS and the blank
template) and both presence ratchets flip to absence pins. The
better-auth>better-sqlite3 and four @better-auth/utils entries stay —
re-derived from the tree, their conditions are separate and unmet; the
separation pin now guards that they survived the retirement.

Adapter transactions: better-auth routes its own multi-writes (sign-up
included) through adapter.transaction — measured: a fail-closed
require:true 500'd every sign-up on the memory engine — so the
implementation keeps the two declared degrades those flows always had
(no-transaction-API engines run the callback directly; drivers without
beginTransaction follow the engine's ADR-0119 D1 warn-once degrade).
SQL drivers get real atomic transactions.

Also: changeset (minor across the six touched published packages, level
argued in the body), and two stale-prose corrections where files
described the retired rc.1 storeSCIMToken wiring as current.

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

Author: claude

.changeset/scim-stable-migration.md

@@ -0,0 +1,63 @@
+---
+"@objectstack/plugin-auth": minor
+"@objectstack/platform-objects": minor
+"@objectstack/spec": minor
+"@objectstack/plugin-security": minor
+"@objectstack/cli": minor
+"create-objectstack": minor
+---
+
+feat(auth): migrate `@better-auth/scim` from `1.7.0-rc.1` to stable `1.7.1` — the whole-model SCIM migration (#3653, epic #11632)
+
+The stable line is the rc.2-lineage rewrite: the rc.1 `scimProvider` model,
+`/scim/generate-token` endpoint and `storeSCIMToken` option no longer exist,
+replaced by seven new models and a three-way connection contract. This lands
+the migration atomically:
+
+- **Seven new platform objects** back the stable models —
+  `sys_scim_connection_binding`, `sys_scim_group`, `sys_scim_group_member`,
+  `sys_scim_identity_tombstone`, `sys_scim_projection_grant`,
+  `sys_scim_subject`, `sys_scim_user` — bridged via `AUTH_MODEL_TO_PROTOCOL`,
+  registered in the platform-object-names registry, listed in
+  `BETTER_AUTH_MANAGED_OBJECTS`, and column-pinned by the parity gate (whose
+  `KNOWN_UNMAPPED_MODELS` shrinks to the empty set: the rc.1-era group
+  provisioning gap — IdP `/Groups` pushes hitting tables that did not exist —
+  is closed).
+- **SCIM connections stay runtime data.** The stable constructor is satisfied
+  with an application-owned `authentication.verifyBearerToken` that resolves
+  the connection from a row at request time — not static boot config, and not
+  the upstream `managedConnections` catalog (deliberately not adopted).
+- **ObjectStack owns SCIM credentials outright** (stable upstream stores no
+  credential at all): `sys_scim_connection_credential` plus
+  `scim-connection-service.ts` mint/digest/verify. At rest only an
+  HMAC-SHA-256 keyed by the deployment auth secret (base64url,
+  domain-separated) is stored — at parity or better than the rc.1 unsalted
+  SHA-256 — pinned by `credential-at-rest-posture.test.ts` including live
+  401 paths for forged, revoked and expired bearers.
+- **The ObjectQL better-auth adapter gains native transactions**
+  (`engine.transaction`, fail-closed on drivers without `beginTransaction`),
+  which stable scim requires by assertion for atomic provisioning writes.
+- **Scaffold suppression retired**: the `@better-auth/scim>better-call`
+  `allowedVersions` entry (CLI renderer + blank template) is gone — stable
+  1.7.1 peers `better-call@1.4.0` exactly — and its presence ratchets flipped
+  to absence pins. The `better-auth>better-sqlite3` and four
+  `@better-auth/utils` entries stay; their retirement conditions are separate
+  and unmet.
+- The pin resolves **1.7.1 exactly** (not `^1.7.1`): 1.7.2 peers
+  `better-auth`/`@better-auth/core` at `^1.7.2`, which only the workspace
+  overrides' silencing would "satisfy" while the family is 1.7.1. Floating is
+  its own follow-up.
+
+**Semver: minor, argued.** The rc.1 SCIM surface this replaces (generate-token
+endpoint, rc.1 bearer tokens, `sys_scim_provider` rows) changes incompatibly —
+but that surface is default-off (`OS_SCIM_ENABLED`), was shipped with a
+documented "do not let the IdP push groups" boundary, and the maintainer ruled
+(2026-08-25) that SCIM has no real customers and old data need not carry: the
+one binding constraint is that an existing system upgrades smoothly, which it
+does — every table the installed library can write exists at this version, and
+SCIM-disabled deployments see no behavior change. A major would move the whole
+fixed version group for a feature surface with zero consumers. Deployments
+that had SCIM enabled must mint new connection credentials (digests are not
+portable from rc.1 on any path — IdP token reissue is a migration-day
+operator action regardless of semver level). `sys_scim_provider` itself is
+NOT removed here; its retirement is tracked separately (#11757).

packages/cli/src/commands/init.ts

@@ -109,15 +109,11 @@ export const SCAFFOLD_BUILT_DEPENDENCIES = ['better-sqlite3', 'esbuild'];
  *    and on 12.11.1. So the upstream range is stale and 13 is right — widening
  *    is the correct remedy, not pinning our own declaration back to 12.
  *
- *  - `@better-auth/scim>better-call` — scim is held at `1.7.0-rc.1`
- *    deliberately (stable 1.7.x ships a whole-model rewrite that is its own
- *    migration), and the rc peers an exact `better-call@1.3.7` while
- *    better-auth itself depends on 1.4.0. A better-auth plugin must share the
- *    HOST's better-call instance, so the single 1.4.0 copy every install
- *    already resolves is the correct tree, not a skew to repair.
- *    ⚠️ This entry retires together with the SCIM rc pin — delete both at once.
- *    Stable `@better-auth/scim@1.7.1` peers `better-call@1.4.0`, so the skew
- *    this line covers is genuinely gone the moment the pin moves.
+ *  - RETIRED (#3653): `@better-auth/scim>better-call` — the rc.1-era scim pin
+ *    peered an exact `better-call@1.3.7` against the host's 1.4.0, and this
+ *    map declared that skew away. Stable `@better-auth/scim@1.7.1` (the pin
+ *    since #3653 landed) peers `better-call@1.4.0`, so the skew is genuinely
+ *    gone and the entry retired WITH the pin move, as its ratchet demanded.
  *
  *  - `<four>@better-auth/utils` — `@better-auth/core`, `/oauth-provider`,
  *    `/scim` and `/sso` each peer an EXACT `@better-auth/utils@0.4.2`, while a
@@ -167,7 +163,9 @@ export const SCAFFOLD_BUILT_DEPENDENCIES = ['better-sqlite3', 'esbuild'];
  */
 export const SCAFFOLD_ALLOWED_PEER_VERSIONS: Record<string, string> = {
   'better-auth>better-sqlite3': '13',
-  '@better-auth/scim>better-call': '1.4.0',
+  // '@better-auth/scim>better-call' retired with the scim rc pin (#3653) —
+  // stable 1.7.1 peers better-call@1.4.0 exactly, the copy every install
+  // already resolves. init.test.ts pins its ABSENCE now.
   '@better-auth/core>@better-auth/utils': '0.5.0',
   '@better-auth/oauth-provider>@better-auth/utils': '0.5.0',
   '@better-auth/scim>@better-auth/utils': '0.5.0',

packages/cli/test/init.test.ts

@@ -333,13 +333,15 @@ describe('benign peer-skew declarations (#10326)', () => {
     expect(settings).toMatch(/^ {4}'better-auth>better-sqlite3': '13'$/m);
   });
 
-  it('accepts the single better-call copy @better-auth/scim resolves to', () => {
-    // scim is held at 1.7.0-rc.1 on purpose; the rc peers an EXACT
-    // `better-call@1.3.7` while better-auth depends on 1.4.0. A better-auth
-    // plugin must share the HOST's better-call instance, so one 1.4.0 copy is
-    // the correct tree. Retires with the scim rc pin.
-    expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>better-call']).toBe('1.4.0');
-    expect(settings).toMatch(/^ {4}'@better-auth\/scim>better-call': '1\.4\.0'$/m);
+  it('keeps the retired @better-auth/scim>better-call suppression OUT (#3653)', () => {
+    // FLIPPED from a presence ratchet when the scim pin moved off the rc.
+    // Stable @better-auth/scim 1.7.1 peers better-call@1.4.0 exactly — the
+    // copy every install already resolves — so the skew the entry declared
+    // away no longer exists, and a suppression with no skew behind it would
+    // hide the NEXT real better-call peer break from a newcomer's first
+    // screen. Re-adding it needs a new measured skew, not a revert.
+    expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>better-call']).toBeUndefined();
+    expect(settings).not.toMatch(/'@better-auth\/scim>better-call'/);
   });
 
   it.each([
@@ -384,14 +386,16 @@ describe('benign peer-skew declarations (#10326)', () => {
     ]);
   });
 
-  it('keeps the @better-auth/utils widening separate from the retiring better-call pin', () => {
-    // @better-auth/scim appears in TWO entries for two unrelated reasons, and
-    // they retire on different days: the better-call one goes when scim leaves
-    // the rc (stable 1.7.1 peers better-call 1.4.0), while the utils one
-    // outlives it (stable 1.7.1 still peers @better-auth/utils 0.4.2). Deleting
-    // both together — the obvious move when the rc pin lifts — would silently
-    // put the utils report back on a newcomer's first screen.
-    expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>better-call']).toBe('1.4.0');
+  it('kept the @better-auth/utils widening when the better-call pin retired (#3653)', () => {
+    // @better-auth/scim appeared in TWO entries for two unrelated reasons, and
+    // they retire on different days — which HAPPENED: the better-call one went
+    // with the rc pin (stable 1.7.1 peers better-call 1.4.0), while the utils
+    // one outlives it (stable 1.7.1 still peers @better-auth/utils 0.4.2;
+    // its own retirement key is the pnpm 10.31 floor). Deleting both together
+    // — the obvious move when the rc pin lifted — would have silently put the
+    // utils report back on a newcomer's first screen; this pin is what stops
+    // that regression from ever landing quietly.
+    expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>better-call']).toBeUndefined();
     expect(SCAFFOLD_ALLOWED_PEER_VERSIONS['@better-auth/scim>@better-auth/utils']).toBe('0.5.0');
   });
 

packages/create-objectstack/src/template-consistency.test.ts

@@ -502,14 +502,17 @@ describe('blank template peer-skew declarations (#10326)', () => {
     ).toBe(true);
   });
 
-  it('declares the frozen @better-auth/scim > better-call peer', () => {
-    // scim is held at 1.7.0-rc.1 deliberately; the rc peers an EXACT 1.3.7
-    // while better-auth depends on 1.4.0. A better-auth plugin must share the
-    // host's better-call instance, so the single 1.4.0 copy is correct.
+  it('keeps the retired @better-auth/scim > better-call suppression OUT (#3653)', () => {
+    // FLIPPED from a presence ratchet when the scim pin moved off the rc:
+    // stable @better-auth/scim 1.7.1 peers better-call@1.4.0 exactly, so the
+    // rc-era skew the entry declared away is gone. A suppression with no skew
+    // behind it would hide the NEXT real better-call peer break from an
+    // `npx create-objectstack` user's first screen — re-adding it needs a new
+    // measured skew, not a revert.
     expect(
-      /^\s*'@better-auth\/scim>better-call':\s*'1\.4\.0'\s*$/m.test(allowed),
-      'allowedVersions must accept the single better-call 1.4.0 copy scim resolves to',
-    ).toBe(true);
+      /'@better-auth\/scim>better-call'/.test(allowed),
+      'the retired @better-auth/scim>better-call suppression must stay out of allowedVersions',
+    ).toBe(false);
   });
 
   it.each([

packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml

@@ -44,12 +44,9 @@ allowBuilds:
 #   sign-in and adapter find/update/delete — 1.7.1 behaves identically on
 #   better-sqlite3 13.0.3 and on 12.11.1. The upstream range is stale.
 #
-#   @better-auth/scim (held at a release candidate deliberately, not by
-#   neglect) peers better-call at an exact 1.3.7, while better-auth itself
-#   depends on 1.4.0. A better-auth plugin has to share the host's better-call
-#   instance, so the single 1.4.0 copy is the correct resolution rather than a
-#   skew to repair. This entry retires when SCIM moves off the rc: stable
-#   @better-auth/scim 1.7.1 already peers better-call 1.4.0.
+#   (The '@better-auth/scim>better-call' entry that used to sit here retired
+#   with the scim release-candidate pin — stable @better-auth/scim 1.7.1 peers
+#   better-call 1.4.0 exactly, so the skew it declared away is gone.)
 #
 #   @better-auth/core, @better-auth/oauth-provider, @better-auth/scim and
 #   @better-auth/sso each peer an exact @better-auth/utils 0.4.2, while the
@@ -75,7 +72,6 @@ allowBuilds:
 peerDependencyRules:
   allowedVersions:
     'better-auth>better-sqlite3': '13'
-    '@better-auth/scim>better-call': '1.4.0'
     '@better-auth/core>@better-auth/utils': '0.5.0'
     '@better-auth/oauth-provider>@better-auth/utils': '0.5.0'
     '@better-auth/scim>@better-auth/utils': '0.5.0'

packages/platform-objects/src/identity/sys-scim-provider.object.ts

@@ -13,11 +13,18 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
  * is OPEN (here, framework `plugin-auth`); enablement is entitlement-gated by
  * the cloud / EE license.
  *
- * `scim_token` holds the connection's bearer credential. With the plugin's
- * `storeSCIMToken: 'hashed'` (the default this env wires) it stores only a
- * HASH — the plaintext is returned exactly once at `/scim/generate-token`. Even
- * so, treat this object as sensitive: it is read-only over the generic data API
- * and the token is excluded from list views.
+ * ⚠️ RC.1-ERA OBJECT — retirement tracked by #11757. The stable
+ * `@better-auth/scim` line (#3653) derives no `scimProvider` model, exposes no
+ * `/scim/generate-token`, and has no `storeSCIMToken` option, so nothing
+ * writes rows here any more; SCIM connection credentials live in
+ * `sys_scim_connection_credential` (ObjectStack-owned). The paragraphs below
+ * describe the rc.1 behaviour this object was built for.
+ *
+ * `scim_token` holds the connection's bearer credential. With the rc.1
+ * plugin's `storeSCIMToken: 'hashed'` (which this env wired) it stored only a
+ * HASH — the plaintext was returned exactly once at `/scim/generate-token`.
+ * Even so, treat this object as sensitive: it is read-only over the generic
+ * data API and the token is excluded from list views.
  *
  * All mutations route through @better-auth/scim's endpoints under
  * `/api/v1/auth/scim/*` (generate-token / delete-provider-connection) and the

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

@@ -777,12 +777,24 @@ export function createObjectQLAdapterFactory(rawDataEngine: IDataEngine) {
   // 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. `require: true` fails CLOSED on a driver without
-  // `beginTransaction` (#5696): a sequential fallback here would be exactly
-  // the degraded posture upstream's assertion exists to refuse.
+  // 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.
   let wrappedAdapter: unknown = null;
   const engineWithTx = rawDataEngine as unknown as {
-    transaction<T>(
+    transaction?<T>(
       cb: (trxCtx: unknown, info: unknown) => Promise<T>,
       baseContext?: unknown,
       opts?: { require?: boolean },
@@ -807,11 +819,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');
         }
-        return engineWithTx.transaction(
-          async () => cb(wrappedAdapter as never),
-          undefined,
-          { require: true },
-        );
+        if (typeof engineWithTx.transaction !== 'function') {
+          // Declared degrade #1 (see the #3653 note above): no transaction API
+          // on this engine — run directly, as the factory fallback would.
+          return cb(wrappedAdapter as never);
+        }
+        return engineWithTx.transaction(async () => cb(wrappedAdapter as never));
       },
     },
     adapter: () => withValidationErrorMapping({

packages/plugins/plugin-auth/src/sso-client-secret.ts

@@ -22,8 +22,11 @@
  *
  * ## The seam
  * `@better-auth/sso` has NO secret-at-rest option, so there is no upstream
- * switch to flip: `SSOOptions` has no equivalent of
- * `scim({ storeSCIMToken: 'hashed' })`. Measured 2026-08-20 against the
+ * switch to flip: `SSOOptions` has no equivalent of the rc.1-era
+ * `scim({ storeSCIMToken: 'hashed' })` (an option stable scim has since
+ * dropped entirely — ObjectStack owns SCIM credentials outright now, #3653,
+ * which only sharpens the point that at-rest posture is ours to establish).
+ * Measured 2026-08-20 against the
  * installed `@better-auth/sso@1.7.1` by enumerating the top-level members of
  * `SSOOptions` in the shipped `dist/index-CZytzKv6.d.mts` — `resolveUser`,
  * `guardProviderMutation`, `provisionUser`, `provisionUserOnEveryLogin`,