@objectstack/plugin-auth 10.3.0 → 11.1.0

package/dist/index.d.mts

@@ -169,6 +169,34 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      * Required for database operations using ObjectQL instead of third-party ORMs
      */
     dataEngine?: IDataEngine;
+    /**
+     * Optional callback invoked AFTER an organization is created via better-auth's
+     * `createOrganization` (the org-plugin `afterCreateOrganization` hook). Lets a
+     * host stack run org-creation side effects that core `databaseHooks` can't —
+     * better-auth's org-plugin models (`organization`/`member`) do NOT fire those.
+     * The cloud control plane uses it to provision an org's born-with production
+     * environment. Failure-isolated: org creation is never rolled back.
+     */
+    onOrganizationCreated?: (data: {
+        organizationId: string;
+        userId?: string;
+        name?: string;
+        slug?: string;
+    }) => void | Promise<void>;
+    /**
+     * D5.1 — OIDC OP authorization gate (cloud-as-IdP app-assignment).
+     * When set, it is called for an AUTHENTICATED subject on
+     * `/oauth2/authorize` before an authorization code is issued, with the
+     * subject + the requesting `clientId`. Return `false` to DENY (no code).
+     * The cloud control plane uses it to require org-membership: a cloud user
+     * may only obtain a code for an env client (`project_<envId>`) of an org
+     * they belong to. Unset (open editions / self-host, where the OP is not a
+     * multi-tenant issuer) = allow. Host is expected to fail CLOSED on error.
+     */
+    oidcAuthorizeGate?: (params: {
+        userId: string;
+        clientId: string;
+    }) => boolean | Promise<boolean>;
     /**
      * Base path for auth routes
      * Forwarded to better-auth's basePath option so it can match incoming
@@ -231,22 +259,82 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      * "create organization" screen.
      */
     databaseHooks?: BetterAuthOptions['databaseHooks'];
+    /**
+     * ADR-0069 D2 — account lockout (anti-brute-force). After this many
+     * consecutive failed sign-ins the account is locked for
+     * {@link lockoutDurationMinutes}. `0` (default) disables lockout.
+     * Enforced per-identity in the `/sign-in/email` before/after hooks
+     * (survives IP rotation, unlike the per-IP {@link rateLimit}).
+     */
+    lockoutThreshold?: number;
+    /** Minutes an account stays locked once the threshold is crossed. Default 15. */
+    lockoutDurationMinutes?: number;
+    /**
+     * ADR-0069 D1 — password complexity. When `passwordRequireComplexity` is on,
+     * a new password must contain at least `passwordMinClasses` (1-4) of the
+     * character classes upper / lower / digit / symbol. Enforced by a validator
+     * in the `/sign-up/email`, `/reset-password`, `/change-password` before hook
+     * (better-auth only enforces min/max length natively).
+     */
+    passwordRequireComplexity?: boolean;
+    /** Minimum distinct character classes required (1-4). Default 3. */
+    passwordMinClasses?: number;
+    /**
+     * ADR-0069 D1 — password history depth. When > 0, a password change/reset is
+     * rejected if the new password matches the current or any of the last
+     * `passwordHistoryCount` hashes (`sys_account.previous_password_hashes`).
+     * 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`
+     * for the auth endpoints (`/sign-in/email`, `/sign-up/email`,
+     * `/reset-password`). Multi-node deployments need a shared `storage`.
+     */
+    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`
@@ -391,6 +479,16 @@ declare class AuthManager {
      * sign in with email/password going forward.
      */
     getAuthContext(): Promise<any>;
+    /**
+     * SSO-only ("enforced") login mode: the login UI hides the local password
+     * form + self-registration so the team signs in via the IdP only.
+     * `OS_AUTH_SSO_ONLY` (when set) wins over the `ssoOnlyMode` config knob —
+     * parity with the `disableSignUp` env override — so a deployment can force
+     * it regardless of the per-env/config value. Break-glass is preserved: this
+     * NEVER disables `emailAndPassword.enabled`; it only forces `disableSignUp`
+     * and signals the UI to hide the password form. Generic over the IdP.
+     */
+    private resolveSsoOnly;
     getPublicConfig(): {
         emailPassword: {
             enabled: boolean;
@@ -417,10 +515,215 @@ declare class AuthManager {
             organization: boolean;
             multiOrgEnabled: boolean;
             oidcProvider: boolean;
+            sso: boolean;
+            ssoEnforced: boolean;
             deviceAuthorization: boolean;
             admin: boolean;
         };
     };
+    /**
+     * Coarse "is the domain-routed `@better-auth/sso` plugin wired" flag.
+     * Resolved with the EXACT logic that decides whether the plugin is mounted
+     * 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`).
+     */
+    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
+     * matching still happens at `/sign-in/sso`; this answers the coarser "is
+     * there any point showing the SSO button at all", so a freshly-enabled but
+     * unconfigured SSO setup doesn't advertise a button that errors for everyone.
+     *
+     * Fails OPEN to the wired flag when providers can't be counted (no data
+     * engine, query error) — a config-introspection hiccup must never make the
+     * login page hide a button that genuinely works.
+     */
+    isSsoUsable(): Promise<boolean>;
+    /**
+     * Extra `trustedOrigins` entries derived from an external-SSO registration
+     * request. For a `POST /sso/register` | `/sso/update-provider`, parse the
+     * (cloned) body and return the PUBLIC-ROUTABLE origins of the declared
+     * `issuer` / `oidcConfig` endpoints so `@better-auth/sso`'s discovery
+     * validation accepts a customer IdP registered at runtime (ADR-0024) without
+     * the operator pre-listing it in boot config. Only public-routable hosts are
+     * returned — private / internal / loopback hosts are never auto-trusted
+     * (better-auth's `isPublicRoutableHost`, the same predicate its own
+     * sub-endpoint check uses). Best-effort: any parse error yields `[]`.
+     */
+    private ssoDiscoveryTrustedOrigins;
+    /**
+     * Resolve the acting user (+ their active org) for a before-hook gate,
+     * hook-order-independent. Tries the standard cookie session first, then falls
+     * back to explicit token resolution (bearer or the session cookie's token
+     * part) — the bearer plugin may convert `Authorization: Bearer` to a session
+     * AFTER this global before-hook runs. Returns `null` when no valid session
+     * can be resolved (→ caller lets `sessionMiddleware` issue the 401).
+     */
+    private resolveActor;
+    /**
+     * True when `userId` is a platform admin (a `sys_user_permission_set` row
+     * pointing at `admin_full_access` with `organization_id = null`) OR an
+     * owner/admin member of `activeOrgId` (any org membership with role
+     * owner/admin when no active org is set). Mirrors the role-derivation in
+     * `customSession`; reads through `withSystemReadContext` so the lookups are
+     * not themselves RLS-scoped to the acting (possibly non-privileged) user.
+     * Fails CLOSED (returns false) on any lookup error — this backs a security
+     * gate, so an unverifiable actor must never pass.
+     */
+    private isOrgOrPlatformAdmin;
+    /**
+     * Compose the framework's identity-source stamp (`account.create.after`)
+     * with any host-supplied `databaseHooks`, preserving BOTH. The cloud passes
+     * `user.create.after` (personal-org provisioning) + `session.create.before`
+     * (active-org) — different model/op, so no collision — but if a host ever
+     * adds its own `account.create.after` we chain it after the stamp rather
+     * than silently dropping one.
+     */
+    private composeDatabaseHooks;
+    /**
+     * Maintain `sys_user.source` (ADR-0024 D4 provenance) as accounts are linked.
+     * Drives the managed-vs-native user-mgmt gating: a managed (`idp-provisioned`)
+     * user holds no local credential, so the password / identity-edit actions
+     * hide for them — preventing a managed user from self-minting a local
+     * password that would bypass enforced SSO.
+     *
+     * Two cases, both break-glass safe and idempotent (only writes on a real
+     * change, so trackHistory stays quiet):
+     *
+     *  • A **federated** account (any non-`credential` provider — the cloud-as-IdP
+     *    `objectstack-cloud` provider OR a customer's own OIDC/SAML IdP) is
+     *    linked AND the user holds NO local credential → mark `idp-provisioned`.
+     *    A user who already has a `credential` account (an env-native user who
+     *    linked SSO) is left `env-native` — they keep a usable password.
+     *
+     *  • A **credential** account is created (local signup, or the break-glass
+     *    owner's password set via set-initial-password — which can land AFTER the
+     *    first SSO link) → ensure `env-native`. This flips a previously-stamped
+     *    owner back, so the break-glass admin never loses self-service password
+     *    management.
+     *
+     * Best-effort: any failure leaves the prior value (the gate fails open — a
+     * managed user might transiently show a password action that simply errors —
+     * never a hard login failure).
+     */
+    private stampIdentitySource;
+    /**
+     * ADR-0069 D1 — reject a password that doesn't meet the configured character-
+     * class complexity. No-op when `passwordRequireComplexity` is off. Counts the
+     * four classes (upper / lower / digit / symbol) present and throws
+     * `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.
+     */
+    private parseHashes;
+    /**
+     * ADR-0069 D1 — resolve the user whose password is being changed. For
+     * `/change-password` the caller is authenticated (session); for
+     * `/reset-password` the user is carried by the reset token's verification
+     * value (the same lookup better-auth's own handler uses).
+     */
+    private resolvePasswordChangeUserId;
+    /**
+     * ADR-0069 D1 — throw `PASSWORD_REUSE` when `candidate` matches the user's
+     * current password or any hash in the bounded history. Reuses better-auth's
+     * native `password.verify` (passed in) rather than re-hashing. Returns the
+     * current hash (for the after-hook to append) when the candidate is fresh, or
+     * undefined when the feature is off / nothing to compare.
+     */
+    private assertPasswordNotReused;
+    /**
+     * ADR-0069 D1 — append `oldHash` to the bounded password-history ring after a
+     * successful change/reset. Best-effort; never throws.
+     */
+    private recordPasswordHistory;
+    /**
+     * ADR-0069 D2 — throw `ACCOUNT_LOCKED` when the identity is currently locked
+     * out (brute-force protection). No-op when lockout is disabled
+     * (`lockoutThreshold <= 0`) or no data engine is wired. Fails OPEN on a
+     * lookup error: an infra hiccup must never block every login.
+     */
+    private assertAccountNotLocked;
+    /**
+     * ADR-0069 D2 — record a sign-in outcome for lockout accounting. On failure
+     * increments `failed_login_count` and, once it reaches `lockoutThreshold`,
+     * stamps `locked_until = now + lockoutDurationMinutes`. On success resets
+     * both (only writing when there is something to clear, to avoid a no-op
+     * history row on every login). No-op when lockout is disabled. Never throws —
+     * a counter write must not turn a valid login into an error.
+     */
+    private recordSignInOutcome;
+    /**
+     * ADR-0069 D2 — clear a user's lockout state (admin "Unlock" action).
+     * Resets `failed_login_count` and `locked_until`. Returns false when no data
+     * 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
@@ -480,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.
  *
@@ -492,6 +887,18 @@ declare const AUTH_MODEL_TO_PROTOCOL: Record<string, string>;
  * Falls back to the original model name for custom / non-core models.
  */
 declare function resolveProtocolName(model: string): string;
+/**
+ * Wrap a data engine so its READ operations (find / findOne / count) run as
+ * SYSTEM reads — injecting `context.isSystem: true` (merged; any caller-supplied
+ * context still wins on other keys). better-auth has already authenticated the
+ * session and scopes every query by its OWN where-clauses (e.g. member.userId =
+ * session.user). A deployment's control-plane org-scope read hook, however, keys
+ * off the CALLER's user id, and these adapter reads carry no caller context — so
+ * without isSystem that hook filters sys_member / sys_organization reads down to
+ * zero and `organization.list()` returns no orgs for a real member. Writes pass
+ * through untouched (org-scope is a read-only hook).
+ */
+declare function withSystemReadContext(engine: IDataEngine): IDataEngine;
 /**
  * Create an ObjectQL adapter **factory** for better-auth.
  *
@@ -508,7 +915,7 @@ declare function resolveProtocolName(model: string): string;
  * @param dataEngine - ObjectQL data engine instance
  * @returns better-auth AdapterFactory
  */
-declare function createObjectQLAdapterFactory(dataEngine: IDataEngine): better_auth_adapters.AdapterFactory<better_auth.BetterAuthOptions>;
+declare function createObjectQLAdapterFactory(rawDataEngine: IDataEngine): better_auth_adapters.AdapterFactory<better_auth.BetterAuthOptions>;
 /**
  * Create a raw ObjectQL adapter for better-auth (without factory wrapping).
  *
@@ -523,7 +930,7 @@ declare function createObjectQLAdapterFactory(dataEngine: IDataEngine): better_a
  * @param dataEngine - ObjectQL data engine instance
  * @returns better-auth CustomAdapter (raw, without factory wrapping)
  */
-declare function createObjectQLAdapter(dataEngine: IDataEngine): {
+declare function createObjectQLAdapter(rawDataEngine: IDataEngine): {
     create: <T extends Record<string, any>>({ model, data, select: _select }: {
         model: string;
         data: T;
@@ -1225,6 +1632,60 @@ declare function buildOauthProviderPluginSchema(): {
  * from the deprecated `better-auth/plugins/oidc-provider` plugin.
  */
 declare const buildOidcProviderPluginSchema: typeof buildOauthProviderPluginSchema;
+/**
+ * `@better-auth/sso` plugin `ssoProvider` model mapping.
+ *
+ * Each row is an external OIDC/SAML IdP this environment federates login to
+ * (the relying-party side — ADR-0024's OPEN per-env SSO mechanism). The
+ * protocol detail lives in JSON blobs (`oidcConfig` / `samlConfig`); the model
+ * itself is thin. Mirrors @better-auth/sso@1.6.20's `BaseSSOProvider`.
+ *
+ * | camelCase (better-auth) | snake_case (ObjectStack) |
+ * |:------------------------|:-------------------------|
+ * | providerId              | provider_id              |
+ * | oidcConfig              | oidc_config              |
+ * | samlConfig              | saml_config              |
+ * | userId                  | user_id                  |
+ * | organizationId          | organization_id          |
+ * | issuer / domain         | (same name — no remap) |
+ */
+declare const AUTH_SSO_PROVIDER_SCHEMA: {
+    readonly modelName: "sys_sso_provider";
+    readonly fields: {
+        readonly providerId: "provider_id";
+        readonly oidcConfig: "oidc_config";
+        readonly samlConfig: "saml_config";
+        readonly userId: "user_id";
+        readonly organizationId: "organization_id";
+        readonly domainVerified: "domain_verified";
+    };
+};
+/**
+ * `@better-auth/scim` plugin `scimProvider` model mapping.
+ *
+ * Each row is a SCIM connection: a bearer token an external IdP (Okta / Entra)
+ * uses to auto-provision / deprovision THIS environment's users — the env is
+ * the SCIM Service Provider (ADR-0071). Like `@better-auth/sso`, the plugin
+ * hardcodes its model and exposes NO `schema` option, so the mapping is
+ * consumed at the ADAPTER layer (AUTH_MODEL_TO_PROTOCOL + field resolution in
+ * objectql-adapter.ts), NOT handed to the plugin.
+ *
+ * | camelCase (better-auth) | snake_case (ObjectStack) |
+ * |:------------------------|:-------------------------|
+ * | providerId              | provider_id              |
+ * | scimToken               | scim_token               |
+ * | organizationId          | organization_id          |
+ * | userId                  | user_id                  |
+ */
+declare const AUTH_SCIM_PROVIDER_SCHEMA: {
+    readonly modelName: "sys_scim_provider";
+    readonly fields: {
+        readonly providerId: "provider_id";
+        readonly scimToken: "scim_token";
+        readonly organizationId: "organization_id";
+        readonly userId: "user_id";
+    };
+};
 /**
  * Builds the `schema` option for better-auth's `deviceAuthorization()` plugin.
  *
@@ -1249,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_SESSION_CONFIG, 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 };
+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 };