feat(auth): @better-auth/sso scaffold — per-env external IdP (OIDC/SAML) RP

[os-zhuang]

Draft / scaffold. Compiles green and is off by default (OS_SSO_ENABLED). Implements the wiring for ADR-0024 V1's open per-env SSO mechanism (let an environment federate login to a customer's own OIDC/SAML IdP), and documents a real framework gap that must be closed before it's functional.

What's here (builds green — DTS ok for plugin-auth + platform-objects)

• sys_sso_provider object (platform-objects/.../identity/) mirroring @better-auth/sso@1.6.20's BaseSSOProvider (issuer, oidc_config/saml_config JSON blobs, user_id, provider_id, organization_id, domain); managedBy: 'better-auth'; mutations via /api/v1/auth/sso/{register,delete-provider}.
• plugin-auth wiring: sso() plugin gated by enabled.sso (OS_SSO_ENABLED, mirrors OS_OIDC_PROVIDER_ENABLED); ssoProvider → sys_sso_provider added to AUTH_MODEL_TO_PROTOCOL.
• deps: @better-auth/sso ^1.6.20 (+ lockfile).

The gap I uncovered (the real remaining work)

@better-auth/sso@1.6.20 exposes no schema option — verified: no mergeSchema, and the runtime never reads options.schema (unlike oauthProvider, which the framework remaps via buildOauthProviderPluginSchema). So the sso plugin cannot declare its model/field names.

The active adapter (createObjectQLAdapterFactory) passes the raw better-auth model name to the data engine (dataEngine.insert(model, …)) and maps fields only from per-model declarations (core user/session/account config or a plugin schema option). The sso plugin provides neither, so at runtime:

• model ssoProvider won't resolve to sys_sso_provider, and
• camelCase fields (oidcConfig, …) won't map to snake columns.

To finish (next PR): extend objectql-adapter so the factory adapter resolves schema-less plugin model names (consult resolveProtocolName/AUTH_MODEL_TO_PROTOCOL) and maps camelCase→snake fields for them; update objectql-adapter.test.ts; then full local E2E (register an OIDC IdP → login → confirm JIT sys_user + sys_account.provider_id + default role). provisionUser default-role, ssoClient(), and the admin UI are also follow-ups.

Open-core / refs

Per-env SSO mechanism is OPEN (framework; self-host needs it — ADR-0024 topology boundary). Refs: ADR-0024 (objectstack-ai/cloud#502), tracker objectstack-ai/cloud#500.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 25, 2026 11:05am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/platform-objects, @objectstack/plugin-auth.

11 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/implementation-status.mdx (via @objectstack/plugin-auth)
• content/docs/concepts/packages.mdx (via @objectstack/platform-objects, @objectstack/plugin-auth)
• content/docs/concepts/setup-app.mdx (via @objectstack/platform-objects)
• content/docs/getting-started/cli.mdx (via @objectstack/plugin-auth)
• content/docs/guides/auth-sso.mdx (via @objectstack/plugin-auth)
• content/docs/guides/authentication.mdx (via @objectstack/plugin-auth)
• content/docs/guides/kernel-services.mdx (via @objectstack/plugin-auth)
• content/docs/guides/packages.mdx (via @objectstack/platform-objects, @objectstack/plugin-auth)
• content/docs/guides/plugins.mdx (via @objectstack/plugin-auth)
• content/docs/guides/production-readiness.mdx (via @objectstack/plugin-auth)
• content/docs/releases/v9.mdx (via @objectstack/plugin-auth)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

Update — the adapter gap is now implemented + verified at the data layer.

createObjectQLAdapterFactory now resolves the table name (resolveProtocolName) and maps camelCase↔snake fields for schema-less plugin models, scoped by objectName !== model so core / schema-declared models are byte-for-byte unchanged. This makes the @better-auth/sso → sys_sso_provider integration functional.

29 unit tests pass — 3 new sso-bridging tests drive the real better-auth adapter wrapper (sso plugin loaded):

• create(ssoProvider, { oidcConfig }) → dataEngine.insert('sys_sso_provider', { oidc_config })
• reads map snake columns back to camelCase; where-clause fields are snaked
• the 26 existing core-path tests are unchanged.

Compiles green (plugin-auth + platform-objects DTS).

Remaining before "done": full browser E2E — OS_SSO_ENABLED=true, register a live external OIDC IdP via /api/v1/auth/sso/register, log in, confirm JIT sys_user + sys_account.provider_id + default role. Staying draft until that passes.

[os-zhuang]

✅ Full live E2E passed — two federated objectos instances

Ran a real two-node OIDC federation from this branch: OP = a framework objectos with OS_OIDC_PROVIDER_ENABLED (standard oauth-provider = the cloud-IdP role); RP = a framework objectos with OS_SSO_ENABLED (this PR's @better-auth/sso).

1. Boot — RP comes up clean with OS_SSO_ENABLED (29 plugins); sys_sso_provider provisions with the correct snake columns.
2. Register — POST /api/v1/auth/sso/register (it fetched the OP's /.well-known/openid-configuration) → row written through the adapter bridging: providerId→provider_id, oidcConfig→oidc_config.
3. Initiate — POST /api/v1/auth/sign-in/sso by providerId and by email-domain routing (alice@acme.test→acme-op) → correct OIDC authorize URL built from the stored provider (read-bridging snake→camelCase) + PKCE/redirect_uri.
4. Login — full authorization-code exchange → JIT user admin@op.test created in the RP + sys_account.provider_id="acme-op" linked; the RP session is the federated user.

Surfaced + fixed by the E2E: SysSsoProvider wasn't in authIdentityObjects, so the table never provisioned — fixed in e78dc96.

One caveat: the OP consent screen is /_console/oauth/consent (objectui console, not built in this worktree), so I marked the test client skip_consent in the OP DB to drive the code flow headlessly. The consent UI is framework oauth-provider (unchanged by this PR); it renders normally in a real deploy.

Net: the new code is verified end-to-end (boot → provision → register → initiate → federated login → JIT) in a live runtime, on top of the 29 passing unit tests. Follow-ups remain (provisionUser default-role; ssoClient() + admin UI = PR-2).

[os-zhuang]

UI half landed → the login-page "Sign in with SSO" entry is objectstack-ai/objectui#2000.

Together with this backend PR, the per-env external-IdP SSO flow is complete and browser-verified end-to-end (two federated objectos instances): login page → click "Sign in with SSO" → IdP login → consent → JIT federated session (sys_user + sys_account.provider_id).