fix(auth): admin-gate self-service SSO provider registration + default-role JIT (ADR-0024 / cloud#551)

[os-zhuang]

Why

Part of the cloud#551 Unified Identity V1 (ADR-0024) E2E. Local browser testing surfaced a real gap that static review had missed.

@better-auth/sso's POST /sso/register only enforces org-admin when body.organizationId is supplied (index.mjs: if (ctx.body.organizationId) { … hasOrgAdminRole … }). A global (org-less) provider passes on nothing but a valid session — so any authenticated env member can register an env-wide external IdP, a JIT-provisioning / login-routing vector. This violates ADR-0024's "registerSSOProvider is admin-only".

What

• A3 — admin gate: a before-hook on /sso/register requiring the caller to be a platform admin OR an owner/admin of their active org, regardless of whether organizationId is passed. Fail-closed; unauthenticated requests still fall through to sessionMiddleware (→ 401). New helpers resolveActor() (hook-order-independent cookie/bearer resolution) and isOrgOrPlatformAdmin() (mirrors customSession's role derivation; reads via withSystemReadContext).
• A4 — default role: pass organizationProvisioning.defaultRole:'member' to sso() so a first-time federated login lands with an explicit role (over SecurityPlugin's member_default baseline).

Verification (browser E2E, local prod-like stack + a mock OIDC IdP)

• Non-admin member register → 403 SSO_REGISTER_FORBIDDEN (was 200 before this change).
• Org owner register → 200 (discovery hydrated).
• External-IdP OIDC login → JIT user created; better-auth list-accounts shows providerId set = the sys_account source marker.
• Role-less federated user reaches a usable env (member_default); anon denied.
• tsc adds no new errors (the two pre-existing DTS errors — @better-auth/scim @1241 and passwordRejectBreached @865 — are from prior commits, not this one).

Scope

Only packages/plugins/plugin-auth/src/auth-manager.ts. The SSO mechanism stays framework-open (no identity-governance added). Closes the A-workstream gap for cloud#551.

🤖 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 27, 2026 12:52pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth.

10 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/plugin-auth)
• 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/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.