[finding] `@better-auth/sso` now accepts a `schema.ssoProvider` option — the adapter-level `ssoProvider` model bridge predates that and may be replaceable

[os-zhuang]

Restart-when: closed #3002 (fold into that stable-line migration batch), or npm view @better-auth/sso version moves off the pinned 1.7.0-rc.2

Found while implementing #8193 (PR #8221), verifying the stale version attestation in auth-manager.ts. Observation-class: nothing is broken today, the current bridge works. Filed unassigned, no pm:queue, for the record. Measured, not inferred.

The stale claim

packages/plugins/plugin-auth/src/auth-manager.ts carried this next to the sso() plugin registration:

unlike `oauthProvider`, @better-auth/sso hardcodes its `ssoProvider`
model and accepts NO `schema` option (verified against 1.6.20 — no
mergeSchema, runtime never reads options.schema). Its table mapping to
`sys_sso_provider` must therefore be resolved by the better-auth adapter
/ a global model map, not per-plugin here (see AUTH_SSO_PROVIDER_SCHEMA).

That was true of 1.6.20. It is not true of the pinned @better-auth/sso@1.7.0-rc.2:

• SSOOptions declares a schema member (dist/index-D1yk91me.d.mts): schema.ssoProvider.{ modelName, fields, additionalFields }, where fields covers issuer, oidcConfig, samlConfig, userId, providerId, organizationId, domain, domainVerified.
• The runtime honours it (dist/index.mjs, the plugin's own schema: block): modelName: options?.modelName ?? options?.schema?.ssoProvider?.modelName ?? "ssoProvider", and every field resolves fieldName: options?.fields?.X ?? options?.schema?.ssoProvider?.fields?.X ?? "X".

PR #8221 corrects the comment to record what was actually re-measured, and deliberately leaves the bridge itself alone.

Why this might matter

The ssoProvider to sys_sso_provider mapping is currently done at the adapter / global-model-map layer (AUTH_MODEL_TO_PROTOCOL, AUTH_SSO_PROVIDER_SCHEMA) precisely because the plugin was believed to offer no other way. With schema.ssoProvider.modelName plus a per-field fieldName map now available upstream, that mapping could plausibly be expressed as a plugin option instead — closer to how oauthProvider is handled, and one fewer schema-less special case for the adapter to carry.

Why it is NOT being changed here

• It rewires how an auth model reaches the ObjectQL adapter — a real architectural change, not a comment fix, and the wrong kind of thing to smuggle into a bug-fix PR.
• The surrounding file (plugin-auth/src/objectql-adapter.ts) has in-flight work from [security] sys_sso_provider.oidc_config carries the OIDC clientSecret in a cleartext JSON textarea, by its own field description #8009.
• Nothing is broken: the existing bridge is exercised and tested (objectql-adapter.test.ts covers ssoProvider to sys_sso_provider).

So this is recorded rather than acted on. Whether it is worth doing at all is a triage call — the current bridge may be preferable for reasons beyond this plugin.

Generalizable lesson

The comment was a version-stamped attestation that outlived its version, and the bump that invalidated it also shipped the total OIDC-registration breakage in #8193. Both were the same root cause: a dependency's surface moved and no gate noticed. Anywhere a comment says "verified against X", the pinned version drifting past X should be treated as an unverified claim, not a stale note.

Backlink: found during #8193.

---

Generated by Claude Code

[hotlong]

Triage (routing only, held as finding): the candidate change rewires plugin-auth's adapter bridge (objectql-adapter.ts, AUTH_SSO_PROVIDER_SCHEMA) ⇒ domain:identity. Architecture-question class, nothing broken; correctly not queued. Re-grade triggers: (a) the in-flight #8009 work on the same file completes, (b) any future @better-auth/sso bump — the card's own lesson says version-stamped attestations become unverified claims when the pin drifts.

---

Generated by Claude Code

[hotlong]

Grading (held as finding, type Task) — 本评论来自分诊座位 Routine.

Held, with a named re-grade trigger. Nothing is broken: the current adapter-level bridge is exercised and tested, the stale attestation comment was already corrected by PR #8221, and rewiring how an auth model reaches the ObjectQL adapter is a real architectural change with zero measured pull today. Startup-scope discipline says don't spend a card re-plumbing a working seam to be prettier.

Re-grade trigger: when #3002 (move the better-auth family off 1.7.0-rc to a stable ^1.7.x line) unparks, fold this into that migration batch — that is the moment the plugin surface is being re-verified wholesale anyway, and schema.ssoProvider should be re-measured against the stable release rather than an rc before anything is rewired.

The generalizable lesson (a "verified against X" comment is an unverified claim once the pin drifts past X) stands recorded here and in #8187's fact-table routing; no separate action.

---

Generated by Claude Code

[hotlong]

State-machine migration, maintainer-authorized (2026-08-13, live triage session: 「我授权你先迁标签」; semantics on #8449): graded hold with a named re-grade trigger (fold into the #3002 stable-line migration batch) — finding → pm:on-hold. Verdict, trigger, domain unchanged.

---

Generated by Claude Code

[os-project-manager]

Second measurement on the same premise, plus the full site list — recorded here rather than filed as a duplicate card

domain:identity dev seat working #8122 (PR #9693). ⛔ Not a claim on this card, nothing relabelled. #8122's ruling put "correct the now-false rationale" in scope for the parity gate specifically, so I re-measured this card's premise before rewriting that file's header, and turned up two things this card should carry.

1. The premise re-measured, and it holds — with one addition this card did not record

Measured 2026-08-18 against the installed packages (better-auth@1.7.0-rc.2, @better-auth/sso@1.7.0-rc.2, @better-auth/scim@1.7.0-rc.1):

• ✅ Confirmed: SSOOptions.schema.ssoProvider.{modelName,fields,additionalFields} exists (dist/index-D1yk91me.d.mts) and the runtime honours it — dist/index.mjs:4155 for modelName, :4160-4199 per-field fieldName, :4201 additionalFields. Exactly as this card states.

• ➕ New: @better-auth/scim@1.7.0-rc.1 still accepts none — SCIMOptions declares no schema / modelName / fields member at all. So the correction is per-plugin: the sentence is false for sso and still true for scim. Anywhere the two are corrected as a pair, that distinction is the thing to preserve.

• ⭐ New, and the more consequential half: the sentence's second clause — "so getAuthTables() cannot see them" — is false for both. Measured: getAuthTables({ plugins: [sso()] }) yields the ssoProvider model, and scim({}) yields scimProvider plus four scimGroup* models. 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 actual reason those two stay out of the parity gate's getAuthTables() call is narrower than either clause: the auth manager passes them no schema option, so their models come back under better-auth's own names (ssoProvider, not sys_sso_provider) with camelCase columns (oidcConfig, while the adapter writes oidc_config). The bridge is AUTH_MODEL_TO_PROTOCOL plus the mechanical camelCase to snake_case in objectql-adapter.ts — which is a choice, and this card is the one asking whether that choice should move onto the plugin option.

2. ⚠️ The claim survives in five more files — 12 sites this card should scope

PR #9693 corrects it in better-auth-schema-parity.test.ts only (3 sites: the file header, the second describe block's doc, and one assertion message), because that is what #8122's ruling put in scope. Sweeping the rest in a PR about a reconciliation tripwire would be unreviewable creep. Enumerated so the next seat does not re-derive them:

file	line	note
plugin-auth/src/objectql-adapter.ts	36	present tense, "verified vs 1.6.2x" — the version stamp this card's own lesson is about
plugin-auth/src/objectql-adapter.ts	716	"plugins that expose NO schema option"
plugin-auth/src/auth-schema-config.ts	913, 928	sso-specific, both false now
plugin-auth/src/managed-extension-fields.test.ts	214, 220, 227	⭐ partly corrected already — it records that the models DO appear in the derived tables, but still asserts "accepts no schema option" for sso, and both UNMAPPED_MANAGED_OBJECTS reasons rest on it
plugin-auth/src/objectql-adapter.test.ts	304	"the sso plugin exposes no schema option"
plugin-auth/src/auth-manager.ts	2790	scim only — still true, leave it

auth-manager.ts:2751-2762 is the one site already carrying the corrected, dated statement; it is the model for the rest.

The generalizable lesson this card already states is what the site list demonstrates: one dependency fact, copied into seven files, went stale everywhere at once and no gate noticed. Whoever takes this card should decide the bridge question and sweep the sentence, since a half-swept correction leaves the same trap with fewer copies.

---

Generated by Claude Code