@objectstack/plugin-auth 11.0.0 → 11.1.0

package/dist/index.d.mts

@@ -286,6 +286,40 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      * Reuses better-auth's native hash/verify — no bespoke crypto.
      */
     passwordHistoryCount?: number;
+    /**
+     * ADR-0069 D1 — password expiry (days). When > 0, an authenticated user whose
+     * `sys_user.password_changed_at` is older than this is gated out of protected
+     * resources (`PASSWORD_EXPIRED`) until they change their password. Computed in
+     * `customSession` (→ `user.authGate`) and enforced at the transport seam. 0 =
+     * off. A null `password_changed_at` never expires (existing users on upgrade).
+     */
+    passwordExpiryDays?: number;
+    /**
+     * ADR-0069 D3 — enforced MFA. When true, an authenticated user without TOTP
+     * enrolled (`sys_user.two_factor_enabled`) is gated out of protected resources
+     * (`MFA_REQUIRED`) once their grace window elapses, until they enroll. Shares
+     * the `customSession` → `user.authGate` seam with password expiry.
+     */
+    mfaRequired?: boolean;
+    /** Days a user may defer MFA enrollment before the hard block. Default 7. */
+    mfaGracePeriodDays?: number;
+    /**
+     * ADR-0069 D4 — session controls. Enforced in `customSession` (idle/absolute)
+     * and the sign-in hook (concurrent). 0 = off for each. A revoked session is
+     * expired in place (`sys_session.expires_at` past + `revoked_at`/`revoke_reason`)
+     * so better-auth returns no session on the next request (→ 401 → re-login).
+     */
+    sessionIdleTimeoutMinutes?: number;
+    sessionAbsoluteMaxHours?: number;
+    maxConcurrentSessions?: number;
+    /**
+     * ADR-0069 D5 — network gating. When non-empty, auth requests (sign-in,
+     * session) from a client IP outside these CIDR / exact ranges are rejected
+     * with `IP_NOT_ALLOWED` at the auth-route middleware. Requires a trusted proxy
+     * to set `x-forwarded-for` / `cf-connecting-ip`; fails OPEN when the client IP
+     * can't be determined (so a missing proxy header is a no-op, not a lockout).
+     */
+    allowedIpRanges?: string[];
     /**
      * ADR-0069 D2 — better-auth-native per-IP rate limiting, passed through to
      * better-auth's core `rateLimit`. The settings bind tightens `customRules`
@@ -294,21 +328,13 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      */
     rateLimit?: BetterAuthOptions['rateLimit'];
 }
-/**
- * Authentication Manager
- *
- * Wraps better-auth and provides authentication services for ObjectStack.
- * Supports multiple authentication methods:
- * - Email/password
- * - OAuth providers (Google, GitHub, etc.)
- * - Magic links
- * - Two-factor authentication
- * - Passkeys
- * - Organization/teams
- */
+/** ADR-0069 D5 — does `ip` match `range` (IPv4 CIDR `a.b.c.d/n`, or exact IP)? */
+declare function ipMatchesRange(ip: string, range: string): boolean;
 declare class AuthManager {
     private auth;
     private config;
+    private _orgMfaCache;
+    private _orgMfaRefreshing;
     /**
      * Result of the dev-only admin seed (set by `AuthPlugin.maybeSeedDevAdmin`
      * when it provisions the well-known admin on an empty DB). The `serve`
@@ -501,8 +527,21 @@ declare class AuthManager {
      * in `buildPlugins()` (`ssoFromEnv ?? pluginConfig.sso ?? false`) so the
      * advertised capability can never disagree with the actual `/sign-in/sso`
      * route. `OS_SSO_ENABLED` (when set) wins over the config-file setting.
+     * Public so `AuthPlugin` can gate the Setup-nav "SSO Providers" entry on it
+     * (captures both self-host `OS_SSO_ENABLED` and the cloud per-env
+     * `planAllowsSso` config, since that arrives via `plugins.sso`).
      */
-    private isSsoWired;
+    isSsoWired(): boolean;
+    /**
+     * Whether opt-in DNS domain-verification (ADR-0024 ②) is wired — i.e. the
+     * `/sso/request-domain-verification` + `/sso/verify-domain` endpoints are
+     * mounted (and the hard "domain must be verified to log in" gate is active).
+     * Resolved with the EXACT logic `buildPluginList` uses for the `sso()`
+     * `domainVerification.enabled` option, so the bridge can return a clear
+     * "not enabled for this environment" instead of a bare 404 when off.
+     * Implies `isSsoWired()` (the sso plugin must be loaded to honor it).
+     */
+    isSsoDomainVerificationEnabled(): boolean;
     /**
      * Whether enterprise SSO is actually *usable*, not merely wired: the plugin
      * is on AND at least one `sys_sso_provider` row exists. Per-email domain→IdP
@@ -590,6 +629,33 @@ declare class AuthManager {
      * `PASSWORD_POLICY_VIOLATION` when fewer than `passwordMinClasses` are used.
      */
     private assertPasswordComplexity;
+    /**
+     * ADR-0069 — is any authentication-policy gate enabled? Cheap, synchronous;
+     * lets the transport seams skip session lookups entirely when off (the
+     * default), keeping the gate zero-overhead until an admin opts in.
+     */
+    isAuthGateActive(): boolean;
+    /**
+     * ADR-0069 — refresh the "any org requires MFA" cache in the background when
+     * stale (60s TTL). Fire-and-forget: a brand-new per-org requirement activates
+     * the gate on the next request, never blocking this one. No-op when global MFA
+     * is already on (the gate is active regardless).
+     */
+    private refreshOrgMfaCacheIfStale;
+    /**
+     * ADR-0069 — compute the auth-policy gate posture for a session. Returns an
+     * `{ code, message }` when the user is currently blocked (e.g. password
+     * expired), else undefined. No-op (and no DB read) when no gate feature is
+     * enabled. Fails OPEN on any lookup error — a transient hiccup must never lock
+     * a compliant user out.
+     */
+    private computeAuthGate;
+    /**
+     * ADR-0069 D1 — stamp `sys_user.password_changed_at = now` after a password is
+     * set (sign-up / change / reset). Best-effort; never throws. Written as a Date
+     * (never epoch-ms) per ADR-0074.
+     */
+    private stampPasswordChangedAt;
     /**
      * ADR-0069 D1 — parse the bounded `previous_password_hashes` JSON column into
      * a string[] of hashes, tolerating null / malformed values.
@@ -637,6 +703,27 @@ declare class AuthManager {
      * engine is wired or the user does not exist.
      */
     unlockUser(userId: string): Promise<boolean>;
+    /**
+     * ADR-0069 D4 — idle / absolute session enforcement, run per request from
+     * `customSession`. No-op when both are off. Revokes (expires in place +
+     * stamps revoked_at/revoke_reason) when a limit is exceeded so better-auth
+     * returns no session on the NEXT request; otherwise touches `last_activity_at`
+     * (throttled to once a minute). Best-effort — never throws.
+     */
+    private enforceSessionControls;
+    /**
+     * ADR-0069 D4 — concurrent-session cap, run from the sign-in after-hook.
+     * Keeps the newest `maxConcurrentSessions` live sessions for the user and
+     * revokes the rest (oldest first). No-op when off. Best-effort.
+     */
+    private enforceConcurrentCap;
+    /**
+     * ADR-0069 D5 — is `ip` within the configured allow-list? True (allow) when no
+     * ranges are configured, OR when the IP can't be determined (fail-open so a
+     * misconfigured proxy never locks everyone out — an admin enabling this must
+     * ensure forwarded headers are trusted). Supports IPv4 CIDR + exact IPv4/IPv6.
+     */
+    isClientIpAllowed(ip: string | undefined): boolean;
     /**
      * Returns the data engine wired into this auth manager. Used by route
      * handlers (e.g. bootstrap-status) that need to query identity tables
@@ -696,6 +783,98 @@ interface SetInitialPasswordResult {
  */
 declare function runSetInitialPassword(authApi: SetPasswordCapableApi, request: Request): Promise<SetInitialPasswordResult>;
 
+/**
+ * Shared `register-sso-provider` (form) handler.
+ *
+ * `@better-auth/sso`'s `POST /sso/register` expects the OIDC protocol fields
+ * NESTED under `oidcConfig` ({ clientId, clientSecret, discoveryEndpoint,
+ * scopes, mapping }). The `sys_sso_provider` `register_sso_provider` UI action
+ * collects FLAT form fields (the action param schema has no nested-path
+ * support), so posting them straight to `/sso/register` drops
+ * clientId/clientSecret at the top level (Zod-stripped) and persists an
+ * unusable `oidc_config = null` provider that can never complete a login
+ * (ADR-0024).
+ *
+ * This helper reshapes the flat form body into the nested shape and
+ * RE-DISPATCHES it through the real `/sso/register` endpoint (via the
+ * better-auth universal handler passed in) so the admin gate, the
+ * public-routable `trustedOrigins` allowance, discovery hydration, and secret
+ * handling all still run — no logic is duplicated. It is the single source of
+ * truth for the two mount points that must stay in lockstep: the full
+ * `AuthPlugin` (self-host / OSS host kernel) and the cloud `AuthProxyPlugin`
+ * (per-environment runtime) — mirroring `runSetInitialPassword`.
+ */
+interface RegisterSsoFormResult {
+    /** HTTP status to return to the caller. */
+    status: number;
+    /** JSON body; mirrors the `{ success, data?, error? }` envelope the client parses. */
+    body: {
+        success: boolean;
+        data?: {
+            providerId: string;
+        };
+        error?: {
+            code: string;
+            message: string;
+        };
+    };
+}
+/** A better-auth universal handler: `(request) => Response`. */
+type AuthRequestHandler = (request: Request) => Promise<Response>;
+/**
+ * Reshape a flat SSO-provider registration form body and register it.
+ *
+ * @param handle  the better-auth universal handler (`AuthManager.handleRequest`
+ *                on the host kernel, or the resolved per-env handler in the
+ *                cloud proxy). Used to re-dispatch the nested body to the real
+ *                `/sso/register` route so all of its gates run.
+ * @param request the raw Web `Request` — its headers carry the caller's session
+ *                cookie / bearer + Origin; its body carries the flat form
+ *                fields ({ providerId, issuer, domain, clientId, clientSecret,
+ *                discoveryEndpoint?, scopes?, mapId?, mapEmail?, mapName? }).
+ */
+declare function runRegisterSsoProviderFromForm(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult>;
+/**
+ * ADR-0069 P3 — SAML 2.0 sibling of {@link runRegisterSsoProviderFromForm}.
+ *
+ * `@better-auth/sso` (samlify-backed) registers a SAML IdP via the SAME
+ * `/sso/register` endpoint, with the protocol fields nested under `samlConfig`
+ * ({ entryPoint, cert, callbackUrl, identifierFormat? }) instead of `oidcConfig`.
+ * The UI action collects FLAT fields; this helper reshapes them, derives the
+ * per-provider ACS callback URL (`/sso/saml2/sp/acs/<providerId>`), and
+ * re-dispatches through `/sso/register` so the admin gate + provisioning run.
+ * Returns the SP ACS + metadata URLs the admin must configure on the IdP.
+ */
+declare function runRegisterSamlProviderFromForm(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult & {
+    body: RegisterSsoFormResult['body'] & {
+        acsUrl?: string;
+        spMetadataUrl?: string;
+    };
+}>;
+/**
+ * Request a DNS-TXT domain-verification challenge for a registered provider and
+ * return the ready-to-paste DNS record (for a one-shot `resultDialog`).
+ *
+ * Body: `{ providerId, domain? }` (domain only shapes the displayed record name).
+ */
+declare function runRequestDomainVerification(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult & {
+    body: RegisterSsoFormResult['body'] & {
+        data?: any;
+    };
+}>;
+/**
+ * Verify a provider's domain ownership (re-checks the DNS-TXT record). Reshapes
+ * @better-auth/sso's empty `204` / `502` into a `{ success, data:{ message } }`
+ * envelope so the action surfaces a clear toast.
+ *
+ * Body: `{ providerId }`.
+ */
+declare function runVerifyDomain(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult & {
+    body: RegisterSsoFormResult['body'] & {
+        data?: any;
+    };
+}>;
+
 /**
  * Mapping from better-auth model names to ObjectStack protocol object names.
  *
@@ -1478,6 +1657,7 @@ declare const AUTH_SSO_PROVIDER_SCHEMA: {
         readonly samlConfig: "saml_config";
         readonly userId: "user_id";
         readonly organizationId: "organization_id";
+        readonly domainVerified: "domain_verified";
     };
 };
 /**
@@ -1530,4 +1710,4 @@ declare function buildDeviceAuthorizationPluginSchema(): {
     };
 };
 
-export { AUTH_ACCOUNT_CONFIG, AUTH_ADMIN_SESSION_FIELDS, AUTH_ADMIN_USER_FIELDS, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SCIM_PROVIDER_SCHEMA, AUTH_SESSION_CONFIG, AUTH_SSO_PROVIDER_SCHEMA, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, type SetInitialPasswordResult, type SetPasswordCapableApi, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, resolveProtocolName, runSetInitialPassword, withSystemReadContext };
+export { AUTH_ACCOUNT_CONFIG, AUTH_ADMIN_SESSION_FIELDS, AUTH_ADMIN_USER_FIELDS, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SCIM_PROVIDER_SCHEMA, AUTH_SESSION_CONFIG, AUTH_SSO_PROVIDER_SCHEMA, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, type AuthRequestHandler, type RegisterSsoFormResult, type SetInitialPasswordResult, type SetPasswordCapableApi, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, ipMatchesRange, resolveProtocolName, runRegisterSamlProviderFromForm, runRegisterSsoProviderFromForm, runRequestDomainVerification, runSetInitialPassword, runVerifyDomain, withSystemReadContext };

package/dist/index.d.ts

@@ -286,6 +286,40 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      * Reuses better-auth's native hash/verify — no bespoke crypto.
      */
     passwordHistoryCount?: number;
+    /**
+     * ADR-0069 D1 — password expiry (days). When > 0, an authenticated user whose
+     * `sys_user.password_changed_at` is older than this is gated out of protected
+     * resources (`PASSWORD_EXPIRED`) until they change their password. Computed in
+     * `customSession` (→ `user.authGate`) and enforced at the transport seam. 0 =
+     * off. A null `password_changed_at` never expires (existing users on upgrade).
+     */
+    passwordExpiryDays?: number;
+    /**
+     * ADR-0069 D3 — enforced MFA. When true, an authenticated user without TOTP
+     * enrolled (`sys_user.two_factor_enabled`) is gated out of protected resources
+     * (`MFA_REQUIRED`) once their grace window elapses, until they enroll. Shares
+     * the `customSession` → `user.authGate` seam with password expiry.
+     */
+    mfaRequired?: boolean;
+    /** Days a user may defer MFA enrollment before the hard block. Default 7. */
+    mfaGracePeriodDays?: number;
+    /**
+     * ADR-0069 D4 — session controls. Enforced in `customSession` (idle/absolute)
+     * and the sign-in hook (concurrent). 0 = off for each. A revoked session is
+     * expired in place (`sys_session.expires_at` past + `revoked_at`/`revoke_reason`)
+     * so better-auth returns no session on the next request (→ 401 → re-login).
+     */
+    sessionIdleTimeoutMinutes?: number;
+    sessionAbsoluteMaxHours?: number;
+    maxConcurrentSessions?: number;
+    /**
+     * ADR-0069 D5 — network gating. When non-empty, auth requests (sign-in,
+     * session) from a client IP outside these CIDR / exact ranges are rejected
+     * with `IP_NOT_ALLOWED` at the auth-route middleware. Requires a trusted proxy
+     * to set `x-forwarded-for` / `cf-connecting-ip`; fails OPEN when the client IP
+     * can't be determined (so a missing proxy header is a no-op, not a lockout).
+     */
+    allowedIpRanges?: string[];
     /**
      * ADR-0069 D2 — better-auth-native per-IP rate limiting, passed through to
      * better-auth's core `rateLimit`. The settings bind tightens `customRules`
@@ -294,21 +328,13 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      */
     rateLimit?: BetterAuthOptions['rateLimit'];
 }
-/**
- * Authentication Manager
- *
- * Wraps better-auth and provides authentication services for ObjectStack.
- * Supports multiple authentication methods:
- * - Email/password
- * - OAuth providers (Google, GitHub, etc.)
- * - Magic links
- * - Two-factor authentication
- * - Passkeys
- * - Organization/teams
- */
+/** ADR-0069 D5 — does `ip` match `range` (IPv4 CIDR `a.b.c.d/n`, or exact IP)? */
+declare function ipMatchesRange(ip: string, range: string): boolean;
 declare class AuthManager {
     private auth;
     private config;
+    private _orgMfaCache;
+    private _orgMfaRefreshing;
     /**
      * Result of the dev-only admin seed (set by `AuthPlugin.maybeSeedDevAdmin`
      * when it provisions the well-known admin on an empty DB). The `serve`
@@ -501,8 +527,21 @@ declare class AuthManager {
      * in `buildPlugins()` (`ssoFromEnv ?? pluginConfig.sso ?? false`) so the
      * advertised capability can never disagree with the actual `/sign-in/sso`
      * route. `OS_SSO_ENABLED` (when set) wins over the config-file setting.
+     * Public so `AuthPlugin` can gate the Setup-nav "SSO Providers" entry on it
+     * (captures both self-host `OS_SSO_ENABLED` and the cloud per-env
+     * `planAllowsSso` config, since that arrives via `plugins.sso`).
      */
-    private isSsoWired;
+    isSsoWired(): boolean;
+    /**
+     * Whether opt-in DNS domain-verification (ADR-0024 ②) is wired — i.e. the
+     * `/sso/request-domain-verification` + `/sso/verify-domain` endpoints are
+     * mounted (and the hard "domain must be verified to log in" gate is active).
+     * Resolved with the EXACT logic `buildPluginList` uses for the `sso()`
+     * `domainVerification.enabled` option, so the bridge can return a clear
+     * "not enabled for this environment" instead of a bare 404 when off.
+     * Implies `isSsoWired()` (the sso plugin must be loaded to honor it).
+     */
+    isSsoDomainVerificationEnabled(): boolean;
     /**
      * Whether enterprise SSO is actually *usable*, not merely wired: the plugin
      * is on AND at least one `sys_sso_provider` row exists. Per-email domain→IdP
@@ -590,6 +629,33 @@ declare class AuthManager {
      * `PASSWORD_POLICY_VIOLATION` when fewer than `passwordMinClasses` are used.
      */
     private assertPasswordComplexity;
+    /**
+     * ADR-0069 — is any authentication-policy gate enabled? Cheap, synchronous;
+     * lets the transport seams skip session lookups entirely when off (the
+     * default), keeping the gate zero-overhead until an admin opts in.
+     */
+    isAuthGateActive(): boolean;
+    /**
+     * ADR-0069 — refresh the "any org requires MFA" cache in the background when
+     * stale (60s TTL). Fire-and-forget: a brand-new per-org requirement activates
+     * the gate on the next request, never blocking this one. No-op when global MFA
+     * is already on (the gate is active regardless).
+     */
+    private refreshOrgMfaCacheIfStale;
+    /**
+     * ADR-0069 — compute the auth-policy gate posture for a session. Returns an
+     * `{ code, message }` when the user is currently blocked (e.g. password
+     * expired), else undefined. No-op (and no DB read) when no gate feature is
+     * enabled. Fails OPEN on any lookup error — a transient hiccup must never lock
+     * a compliant user out.
+     */
+    private computeAuthGate;
+    /**
+     * ADR-0069 D1 — stamp `sys_user.password_changed_at = now` after a password is
+     * set (sign-up / change / reset). Best-effort; never throws. Written as a Date
+     * (never epoch-ms) per ADR-0074.
+     */
+    private stampPasswordChangedAt;
     /**
      * ADR-0069 D1 — parse the bounded `previous_password_hashes` JSON column into
      * a string[] of hashes, tolerating null / malformed values.
@@ -637,6 +703,27 @@ declare class AuthManager {
      * engine is wired or the user does not exist.
      */
     unlockUser(userId: string): Promise<boolean>;
+    /**
+     * ADR-0069 D4 — idle / absolute session enforcement, run per request from
+     * `customSession`. No-op when both are off. Revokes (expires in place +
+     * stamps revoked_at/revoke_reason) when a limit is exceeded so better-auth
+     * returns no session on the NEXT request; otherwise touches `last_activity_at`
+     * (throttled to once a minute). Best-effort — never throws.
+     */
+    private enforceSessionControls;
+    /**
+     * ADR-0069 D4 — concurrent-session cap, run from the sign-in after-hook.
+     * Keeps the newest `maxConcurrentSessions` live sessions for the user and
+     * revokes the rest (oldest first). No-op when off. Best-effort.
+     */
+    private enforceConcurrentCap;
+    /**
+     * ADR-0069 D5 — is `ip` within the configured allow-list? True (allow) when no
+     * ranges are configured, OR when the IP can't be determined (fail-open so a
+     * misconfigured proxy never locks everyone out — an admin enabling this must
+     * ensure forwarded headers are trusted). Supports IPv4 CIDR + exact IPv4/IPv6.
+     */
+    isClientIpAllowed(ip: string | undefined): boolean;
     /**
      * Returns the data engine wired into this auth manager. Used by route
      * handlers (e.g. bootstrap-status) that need to query identity tables
@@ -696,6 +783,98 @@ interface SetInitialPasswordResult {
  */
 declare function runSetInitialPassword(authApi: SetPasswordCapableApi, request: Request): Promise<SetInitialPasswordResult>;
 
+/**
+ * Shared `register-sso-provider` (form) handler.
+ *
+ * `@better-auth/sso`'s `POST /sso/register` expects the OIDC protocol fields
+ * NESTED under `oidcConfig` ({ clientId, clientSecret, discoveryEndpoint,
+ * scopes, mapping }). The `sys_sso_provider` `register_sso_provider` UI action
+ * collects FLAT form fields (the action param schema has no nested-path
+ * support), so posting them straight to `/sso/register` drops
+ * clientId/clientSecret at the top level (Zod-stripped) and persists an
+ * unusable `oidc_config = null` provider that can never complete a login
+ * (ADR-0024).
+ *
+ * This helper reshapes the flat form body into the nested shape and
+ * RE-DISPATCHES it through the real `/sso/register` endpoint (via the
+ * better-auth universal handler passed in) so the admin gate, the
+ * public-routable `trustedOrigins` allowance, discovery hydration, and secret
+ * handling all still run — no logic is duplicated. It is the single source of
+ * truth for the two mount points that must stay in lockstep: the full
+ * `AuthPlugin` (self-host / OSS host kernel) and the cloud `AuthProxyPlugin`
+ * (per-environment runtime) — mirroring `runSetInitialPassword`.
+ */
+interface RegisterSsoFormResult {
+    /** HTTP status to return to the caller. */
+    status: number;
+    /** JSON body; mirrors the `{ success, data?, error? }` envelope the client parses. */
+    body: {
+        success: boolean;
+        data?: {
+            providerId: string;
+        };
+        error?: {
+            code: string;
+            message: string;
+        };
+    };
+}
+/** A better-auth universal handler: `(request) => Response`. */
+type AuthRequestHandler = (request: Request) => Promise<Response>;
+/**
+ * Reshape a flat SSO-provider registration form body and register it.
+ *
+ * @param handle  the better-auth universal handler (`AuthManager.handleRequest`
+ *                on the host kernel, or the resolved per-env handler in the
+ *                cloud proxy). Used to re-dispatch the nested body to the real
+ *                `/sso/register` route so all of its gates run.
+ * @param request the raw Web `Request` — its headers carry the caller's session
+ *                cookie / bearer + Origin; its body carries the flat form
+ *                fields ({ providerId, issuer, domain, clientId, clientSecret,
+ *                discoveryEndpoint?, scopes?, mapId?, mapEmail?, mapName? }).
+ */
+declare function runRegisterSsoProviderFromForm(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult>;
+/**
+ * ADR-0069 P3 — SAML 2.0 sibling of {@link runRegisterSsoProviderFromForm}.
+ *
+ * `@better-auth/sso` (samlify-backed) registers a SAML IdP via the SAME
+ * `/sso/register` endpoint, with the protocol fields nested under `samlConfig`
+ * ({ entryPoint, cert, callbackUrl, identifierFormat? }) instead of `oidcConfig`.
+ * The UI action collects FLAT fields; this helper reshapes them, derives the
+ * per-provider ACS callback URL (`/sso/saml2/sp/acs/<providerId>`), and
+ * re-dispatches through `/sso/register` so the admin gate + provisioning run.
+ * Returns the SP ACS + metadata URLs the admin must configure on the IdP.
+ */
+declare function runRegisterSamlProviderFromForm(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult & {
+    body: RegisterSsoFormResult['body'] & {
+        acsUrl?: string;
+        spMetadataUrl?: string;
+    };
+}>;
+/**
+ * Request a DNS-TXT domain-verification challenge for a registered provider and
+ * return the ready-to-paste DNS record (for a one-shot `resultDialog`).
+ *
+ * Body: `{ providerId, domain? }` (domain only shapes the displayed record name).
+ */
+declare function runRequestDomainVerification(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult & {
+    body: RegisterSsoFormResult['body'] & {
+        data?: any;
+    };
+}>;
+/**
+ * Verify a provider's domain ownership (re-checks the DNS-TXT record). Reshapes
+ * @better-auth/sso's empty `204` / `502` into a `{ success, data:{ message } }`
+ * envelope so the action surfaces a clear toast.
+ *
+ * Body: `{ providerId }`.
+ */
+declare function runVerifyDomain(handle: AuthRequestHandler, request: Request): Promise<RegisterSsoFormResult & {
+    body: RegisterSsoFormResult['body'] & {
+        data?: any;
+    };
+}>;
+
 /**
  * Mapping from better-auth model names to ObjectStack protocol object names.
  *
@@ -1478,6 +1657,7 @@ declare const AUTH_SSO_PROVIDER_SCHEMA: {
         readonly samlConfig: "saml_config";
         readonly userId: "user_id";
         readonly organizationId: "organization_id";
+        readonly domainVerified: "domain_verified";
     };
 };
 /**
@@ -1530,4 +1710,4 @@ declare function buildDeviceAuthorizationPluginSchema(): {
     };
 };
 
-export { AUTH_ACCOUNT_CONFIG, AUTH_ADMIN_SESSION_FIELDS, AUTH_ADMIN_USER_FIELDS, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SCIM_PROVIDER_SCHEMA, AUTH_SESSION_CONFIG, AUTH_SSO_PROVIDER_SCHEMA, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, type SetInitialPasswordResult, type SetPasswordCapableApi, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, resolveProtocolName, runSetInitialPassword, withSystemReadContext };
+export { AUTH_ACCOUNT_CONFIG, AUTH_ADMIN_SESSION_FIELDS, AUTH_ADMIN_USER_FIELDS, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SCIM_PROVIDER_SCHEMA, AUTH_SESSION_CONFIG, AUTH_SSO_PROVIDER_SCHEMA, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, type AuthRequestHandler, type RegisterSsoFormResult, type SetInitialPasswordResult, type SetPasswordCapableApi, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, ipMatchesRange, resolveProtocolName, runRegisterSamlProviderFromForm, runRegisterSsoProviderFromForm, runRequestDomainVerification, runSetInitialPassword, runVerifyDomain, withSystemReadContext };