@objectstack/plugin-auth 10.3.0 → 11.0.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,6 +259,40 @@ 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 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
@@ -391,6 +453,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 +489,154 @@ 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.
+     */
+    private isSsoWired;
+    /**
+     * 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 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>;
     /**
      * Returns the data engine wired into this auth manager. Used by route
      * handlers (e.g. bootstrap-status) that need to query identity tables
@@ -492,6 +708,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 +736,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 +751,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 +1453,59 @@ 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";
+    };
+};
+/**
+ * `@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 +1530,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 SetInitialPasswordResult, type SetPasswordCapableApi, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, resolveProtocolName, runSetInitialPassword, withSystemReadContext };