feat(auth): opt-in SSO domain verification — DNS-TXT proof + resultDialog UI (ADR-0024 ②)

[os-zhuang]

What

Adds DNS-TXT domain-ownership verification for external SSO providers — the remaining ② item of the ADR-0024 Unified-Identity V1 plan (per-env external IdP). Gated behind a new OS_SSO_DOMAIN_VERIFICATION flag (off by default).

When off (default): today's behavior is unchanged — register → login immediately.
When on: @better-auth/sso mounts /sso/request-domain-verification + /sso/verify-domainand enforces a hard login gate — a provider whose email domain is not DNS-verified rejects logins (Provider domain has not been verified). These two are coupled in @better-auth/sso (the endpoints only register when domainVerification.enabled), so one flag governs both. This prevents an org admin from registering a provider for a domain they don't control.

Changes

• auth-manager.ts — new ssoDomainVerification enabled-flag (readBooleanEnv, accepts true/1/yes/on) → passes domainVerification: { enabled: true } to sso(); public isSsoDomainVerificationEnabled() helper.
• register-sso-provider.ts — runRequestDomainVerification / runVerifyDomain bridges: re-dispatch through the gated better-auth endpoints (so the per-provider admin gate runs) and reshape the response into the { success, data } envelope the action resultDialog reads — request returns the ready-to-paste DNS TXT record ({ dnsRecordName, dnsRecordValue }); verify returns a clear success/error. A bare 404 from the inner endpoint is surfaced as "not enabled for this environment".
• auth-plugin.ts — mount the two bridges as rawApp routes (/admin/sso/{request-domain-verification,verify-domain}).
• sys_sso_provider — domain_verified field + list column + Request Domain Verification / Verify Domain actions (request uses resultDialog to one-shot-reveal the DNS record); domainVerified documented in AUTH_SSO_PROVIDER_SCHEMA.

Verification (local prod-like stack, OS_SSO_DOMAIN_VERIFICATION=true)

• request-domain-verification → 200 with the exact DNS record (_better-auth-token-<id>.<domain> = _better-auth-token-<id>=<token>); rendered in the action's resultDialog (revealed values match byte-for-byte).
• verify-domain (no DNS) → 502 + friendly "DNS TXT record not found yet…".
• Provider org-scoped (organizationId set), domainVerified:false.
• Hard login gate: sign-in/sso for the unverified domain → 401 Provider domain has not been verified.
• List shows the Domain Verified column; both row actions appear.
• The DNS-success path (TXT present → domain_verified:true) is inherently un-testable locally (needs a real domain + DNS TXT) — verified up to that boundary.

The cloud env-runtime mount (AuthProxyPlugin) + .framework-sha bump land in a companion cloud PR.

🤖 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 28, 2026 2:27am

[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.