docs(plugin-auth): sweep the stale "@better-auth/sso accepts no schema option" claim, re-measured against 1.7.1

[os-warren]

Fixes#8224

One dependency fact — "@better-auth/sso accepts NO schema option" — was copied into six files and went stale everywhere at once when the pin moved. This sweeps it. The adapter-level bridge is deliberately untouched; the architecture question the card also raises is left open (see the bottom of this description).

Re-measured first, against the installed packages

⛔ No version number in this PR is copied from the issue, its comments, or the dispatch. Every one was read from node_modules in this worktree on 2026-08-19:

package	installed version
better-auth	1.7.1
@better-auth/sso	1.7.1
@better-auth/scim	1.7.0-rc.1

Independently corroborated by a pnpm store path in the test run's own output: node_modules/.pnpm/@better-auth+sso@1.7.1_.../node_modules/@better-auth/sso/dist/index.mjs.

Fact 1 — sso accepts a schema option; scim still does not

• @better-auth/sso@1.7.1 declares SSOOptions.schema.ssoProvider.{modelName,fields,additionalFields} (dist/index-CZytzKv6.d.mts — note the chunk hash differs from the one the issue names, which is itself a reason not to quote it from memory). The runtime honours it in the plugin's own schema: block (dist/index.mjs): modelName: options?.modelName ?? options?.schema?.ssoProvider?.modelName ?? "ssoProvider", plus a per-field fieldName fallback each and a spread of additionalFields.
• @better-auth/scim@1.7.0-rc.1 accepts none. SCIMOptions declares no schema, modelName or fields member at all — its eight top-level members are requiredRole, staticProviders, mapGroupToRoles, linkExistingUsers, beforeSCIMTokenGenerated, afterSCIMTokenGenerated, canGenerateToken, storeSCIMToken.

So the correction is per-plugin, and every rewritten site now names the plugin it speaks about.

Fact 2 — the sentence's second clause was false for BOTH

"so getAuthTables() cannot see them" — measured by calling it:

getAuthTables({ plugins: [sso()] }) -> ssoProvider
getAuthTables({ plugins: [scim({})] }) -> scimProvider, scimGroup, scimGroupMember,
scimGroupRole, scimGroupRoleGrant

Both plugins DECLARE a schema the function reads. Accepting a schema option and declaring a schema are different facts, and the old wording conflated them. The real reason those models stay outside the parity gate's call is narrower: the auth manager passes them no schema option, so they come back under better-auth's own names with camelCase columns. Confirmed end-to-end that the option would change that — passing one flips both halves:

sso({ schema: { ssoProvider: { modelName: 'sys_sso_provider',
fields: { oidcConfig: 'oidc_config' } } } })
-> model key=ssoProvider modelName=sys_sso_provider fields: oidcConfig->oidc_config

That measurement is evidence for the open question below — it is not acted on in this diff.

What changed — 13 sites in 6 files, comments and messages only

objectql-adapter.ts ×2 · auth-schema-config.ts ×2 · managed-extension-fields.test.ts ×4 · objectql-adapter.test.ts ×1 · auth-manager.ts ×2 · better-auth-schema-parity.test.ts ×2.

Every replacement sentence names the version and the date it was measured against, so it fails loudly rather than expiring silently — the card's own lesson.

No executable change in any shipped source file. Verified mechanically: stripping comment lines from the diff of auth-manager.ts, auth-schema-config.ts and objectql-adapter.ts leaves nothing. The only non-comment change anywhere is one describe() title in a test file (schema-less plugin bridging is no longer an accurate name for the block, so it now reads adapter-layer plugin bridging).

Three sites beyond the four files the dispatch enumerated — declared, not smuggled

1. auth-manager.ts, sso block — carried Re-checked against the pinned 1.7.0-rc.2 … on 2026-08-12 and named index-D1yk91me.d.mts. The pin has moved to ^1.7.1 and that chunk file no longer exists, so the site the dispatch offered as the model for the rest had itself expired. Re-stamped to the measurement above. Substance unchanged.
2. better-auth-schema-parity.test.ts — two version stamps only (see the reviewer note below).
3. ⚠️auth-manager.ts, scim block — this one contradicts an explicit instruction, please rule on it. See below.

⚠️ Reviewer: the one place I did not follow the dispatch

The dispatch said, twice and with a ⛔: auth-manager.ts:2790 is "the scim-only site — leave it alone", because correcting it "would introduce a new false claim while removing an old one" — and also said "re-verify this yourself before trusting it." I did, and the premise does not hold: the line is not scim-only. It read:

// tokens need the organization plugin. Like @better-auth/sso it hardcodes
// its scimProvider model (no schema option) — bridged to sys_scim_provider

The scim half is true and preserved (and now carries the measured version and date). The clause Like @better-auth/sso is false as of 1.7.1 — sso no longer hardcodes its model and no longer refuses a schema option. I corrected only that comparative and left the scim fact intact, so this removes a false claim without introducing one, which is what the ⛔'s stated rationale was protecting.

I am flagging rather than assuming: if you disagree, this is one comment hunk in auth-manager.ts and reverts cleanly on its own. My reasoning for acting is that leaving a live false statement about sso inside the very file offered as the corrected model is the half-swept outcome the card warns about — it would re-open this card.

Reviewer note — better-auth-schema-parity.test.ts vs PR #9693

Confirming the distinction requested: I did not rewrite or revert anything #9693 corrected. Both hunks in that file are pure version-stamp refreshes (2026-08-18 / sso@1.7.0-rc.2 → 2026-08-19 / sso@1.7.1):

• the date+version line inside the file header paragraph — test(plugin-auth): reconcile the schema-parity gate's plugin list against auth-manager.ts #9693's surrounding prose is untouched;
• the AUTH_MANAGER_PLUGINS.sso.skip string's trailing it does, on 1.7.0-rc.2 stamp.

Left completely untouched: the header's three substantive bullets, the second describe block's doc comment, and every executable assertion in that block (getAuthTables() DOES see them, the modelName / PLATFORM_OBJECTS / oidcConfig vs oidc_config checks). scim.skip also untouched — it says 1.7.0-rc.1, which is still the installed version.

Verification — all at c0fe12604

pnpm --filter @objectstack/plugin-auth test → Test Files 59 passed (59) / Tests 1320 passed (1320). Counts unchanged, as a comment-only sweep should be: mechanically confirmed that no it(/test( count moved in any changed file (12/12, 23/23, 40/40 vs origin/main).

pnpm --filter @objectstack/plugin-auth typecheck → tsc --noEmit, exit 0.

Gate union re-derived from the ACTUAL diff with node scripts/pm/dispatch-gates.mjs (no hand-built path list), then run to completion — quoting each gate's own verdict line:

• check:slot-lookup — ✓ slot-lookup ratchet holds: 107 unswept site(s) in 25 file(s), none new.
• check:test-source-alias — check-test-source-alias OK — 72 packages with tests scanned
• check:type-source-resolution — check-type-source-resolution OK — 76 packages with a tsconfig.json scanned
• check-affected-docs.mjs — exit 0
• check:query-options-erasure — ✓ query-options-erasure ratchet holds: 67 unswept non-test site(s) in 17 file(s), none new.
• check:type-check-coverage — check-type-check-coverage: OK — 64/77 workspace packages type-checked
• check:type-check-debt — check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 269.0s, 1924 raw tsc error(s) total, none above its recorded number.@objectstack/plugin-auth holds at exactly 109 — the ledger file is not in this diff.
• check:engine-double-contract — check-engine-double-contract: OK — 325 pinned, 133 in the DEBT ledger, 2 exempt.
• check:where-matcher — ✓ where-matcher conformance holds: 263 matcher(s) discovered
• check:nul-bytes — check-nul-bytes: OK (scanned 6367 text file(s) … no raw ASCII control bytes).

The ratchet family was re-run at the final head after the authorship amend; the tree is byte-identical to the pre-amend commit (git diff between them is empty).

Ablation: NOT APPLICABLE. Nothing executable changed, so there is no guard to mutate and no assertion whose failure could be demonstrated. Inventing one would be theatre.

No changeset — skip-changeset. The diff is comments, doc strings, assertion messages and one describe() title; nothing reaches dist/ and nothing is user-visible.

⛔ Deliberately NOT done — the bridge rewire

Moving the ssoProvider → sys_sso_provider mapping off AUTH_MODEL_TO_PROTOCOL onto the plugin's schema.ssoProvider option is not in this diff. The card calls it "a real architectural change"; triage graded it zero-pull. The restart trigger unlocked re-measurement, not that decision. The measurement above shows the option now works, which is exactly why it deserves its own decision card rather than a silent ride-along here. My recommendation is recorded in the dev report on #8224 — briefly: do not rewire. It buys no capability (the bridge is exercised and tested), scim would still need the adapter path so the special case does not actually go away, and under startup-scope discipline a working seam is not worth re-plumbing to be prettier.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth, touching 4 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/authentication.mdx(via AUTH_MODEL_TO_PROTOCOL (symbol), createObjectQLAdapterFactory (symbol))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/plugins/plugin-auth/src/auth-schema-config.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 11 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json a8509eba86503c2dba386354f0b4fd753b7821e1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from df9a5372c9fbee92ddac6530225397089a8e2e7a — the merge of head c0fe12604e59a1e449acf86fe4bf5524e58f119e into base a8509eba86503c2dba386354f0b4fd753b7821e1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin df9a5372c9fbee92ddac6530225397089a8e2e7a && git checkout df9a5372c9fbee92ddac6530225397089a8e2e7a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a8509eba86503c2dba386354f0b4fd753b7821e1 c0fe12604e59a1e449acf86fe4bf5524e58f119e && git checkout -B drift-repro a8509eba86503c2dba386354f0b4fd753b7821e1 && git merge --no-ff c0fe12604e59a1e449acf86fe4bf5524e58f119e
node scripts/docs-audit/affected-docs.mjs --json a8509eba86503c2dba386354f0b4fd753b7821e1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs a8509eba86503c2dba386354f0b4fd753b7821e1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.