@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/dist/component/server/types.d.ts

@@ -1,14 +1,80 @@
+import _default from "../schema.js";
 import { OAuthProviderInstance } from "../providers/oauth.js";
-import { CredentialsUserConfig } from "../providers/credentials.js";
-import { AnyDataModel, DocumentByName, FunctionReference, GenericActionCtx, GenericDataModel, GenericMutationCtx, RegisteredAction, RegisteredMutation, RegisteredQuery, TableNamesInDataModel } from "convex/server";
-import { GenericId, Value } from "convex/values";
+import { CredentialsConfig } from "../providers/credentials.js";
+import { Password } from "../providers/password.js";
+import { Passkey } from "../providers/passkey.js";
+import { Totp } from "../providers/totp.js";
+import { Anonymous } from "../providers/anonymous.js";
+import { Device } from "../providers/device.js";
+import { SSO } from "../providers/sso.js";
+import { Email } from "../providers/email.js";
+import { Phone } from "../providers/phone.js";
+import "../model.js";
+import { AnyDataModel, DataModelFromSchemaDefinition, DocumentByName, GenericActionCtx, GenericDataModel, GenericMutationCtx, GenericQueryCtx, TableNamesInDataModel } from "convex/server";
+import { GenericId, Infer, Value } from "convex/values";
 import * as arctic0 from "arctic";
 
 //#region src/server/types.d.ts
-/** A value that is either `T` or a `PromiseLike<T>`. */
+/**
+ * A value that is either `T` or a `PromiseLike<T>`.
+ *
+ * @typeParam T - The underlying value type.
+ */
 type Awaitable<T> = T | PromiseLike<T>;
 /**
- * The config for the Convex Auth library, passed to `Auth`.
+ * A single role definition within the authorization config.
+ *
+ * Each role has an optional human-readable label and a list of grant strings
+ * that members with this role receive.
+ *
+ * @see {@link AuthAuthorizationConfig}
+ */
+type AuthRoleDefinition = {
+  /** Optional stable identifier (defaults to the record key). */id?: string; /** Human-readable label for admin UIs. */
+  label?: string; /** Permission grant strings conferred by this role. */
+  grants: string[];
+};
+/**
+ * Authorization configuration mapping role IDs to {@link AuthRoleDefinition}s.
+ *
+ * Passed as `authorization.roles` in {@link ConvexAuthConfig}.
+ *
+ * @see {@link AuthRoleDefinition}
+ * @see {@link ConvexAuthConfig}
+ */
+type AuthAuthorizationConfig = {
+  roles: Record<string, AuthRoleDefinition>;
+};
+/**
+ * Extracts the union of role ID strings from an authorization config.
+ *
+ * When `TAuthorization` is defined, this resolves to the literal key union
+ * of the `roles` record. Otherwise falls back to `string`.
+ *
+ * @typeParam TAuthorization - The authorization config type, or `undefined`.
+ *
+ * @see {@link AuthGrant}
+ */
+type AuthRoleId<TAuthorization extends AuthAuthorizationConfig | undefined> = TAuthorization extends {
+  roles: infer TRoles extends Record<string, any>;
+} ? keyof TRoles & string : string;
+/**
+ * Extracts the union of grant strings from all roles in an authorization config.
+ *
+ * When `TAuthorization` is defined, this resolves to the literal union
+ * of all `grants` array elements across every role. Otherwise falls back to `string`.
+ *
+ * @typeParam TAuthorization - The authorization config type, or `undefined`.
+ *
+ * @see {@link AuthRoleId}
+ */
+type AuthGrant<TAuthorization extends AuthAuthorizationConfig | undefined> = TAuthorization extends {
+  roles: infer TRoles extends Record<string, {
+    grants: readonly any[];
+  }>;
+} ? TRoles[keyof TRoles]["grants"][number] & string : string;
+/**
+ * The config for the Convex Auth library, passed to `createAuth`.
  */
 type ConvexAuthConfig = {
   /**
@@ -33,12 +99,16 @@ type ConvexAuthConfig = {
      * How long can a user session last without the user reauthenticating.
      *
      * Defaults to 30 days.
+     *
+     * @defaultValue 2_592_000_000
      */
     totalDurationMs?: number;
     /**
      * How long can a user session last without the user being active.
      *
      * Defaults to 30 days.
+     *
+     * @defaultValue 2_592_000_000
      */
     inactiveDurationMs?: number;
   };
@@ -50,6 +120,8 @@ type ConvexAuthConfig = {
      * How long is the JWT valid for after it is signed initially.
      *
      * Defaults to 1 hour.
+     *
+     * @defaultValue 3_600_000
      */
     durationMs?: number;
   };
@@ -63,63 +135,11 @@ type ConvexAuthConfig = {
      *
      * Defaults to 10 times per hour (that is 10 failed attempts, and then
      * allow another one every 6 minutes).
+     *
+     * @defaultValue 10
      */
-    maxFailedAttempsPerHour?: number;
+    maxFailedAttemptsPerHour?: number;
   };
-  /**
-   * API key configuration for programmatic access.
-   *
-   * Enables `auth.key.*` helpers for creating, verifying, and managing
-   * API keys with scoped permissions and optional per-key rate limiting.
-   */
-  apiKeys?: ApiKeyConfig;
-  /**
-   * Email transport configuration.
-   *
-   * Required for magic link authentication.
-   * The library generates email content (subject, styled HTML); you
-   * provide the delivery mechanism — Resend, SendGrid, SES, Postmark,
-   * or any other provider.
-   *
-   * When configured, a magic link email provider (`id: "email"`) is
-   * auto-registered — no need to add a separate Auth.js email provider
-   * to `providers`.
-   *
-   * Works seamlessly with the `@convex-dev/resend` Convex component:
-   *
-   * ```ts
-   * import { Resend } from "@convex-dev/resend";
-   *
-   * const resend = new Resend(components.resend, { testMode: false });
-   *
-   * const auth = new Auth(components.auth, {
-   *   providers: [google],
-   *   email: {
-   *     from: "My App <noreply@example.com>",
-   *     send: (ctx, params) => resend.sendEmail(ctx, params),
-   *   },
-   * });
-   * ```
-   *
-   * Or with any email API directly:
-   *
-   * ```ts
-   * email: {
-   *   from: "My App <noreply@example.com>",
-   *   send: async (_ctx, { from, to, subject, html }) => {
-   *     await fetch("https://api.resend.com/emails", {
-   *       method: "POST",
-   *       headers: {
-   *         Authorization: `Bearer ${process.env.AUTH_RESEND_KEY}`,
-   *         "Content-Type": "application/json",
-   *       },
-   *       body: JSON.stringify({ from, to, subject, html }),
-   *     });
-   *   },
-   * },
-   * ```
-   */
-  email?: EmailTransport;
   /**
    * Lifecycle callbacks for customizing sign-in behavior.
    *
@@ -132,20 +152,21 @@ type ConvexAuthConfig = {
      * Control which URLs are allowed as a destination after OAuth sign-in
      * and for magic links:
      *
-      * ```ts
-      * import { Auth } from "@robelest/convex-auth/component";
-      *
-      * export const { auth, signIn, signOut, store } = Auth({
-      *   providers: [google],
-      *   callbacks: {
-      *     async redirect({ redirectTo }) {
-      *       // Check that redirectTo is valid
-      *       // and return the relative or absolute URL
-      *       // to redirect to.
-      *     },
-      *   },
-      * });
-      * ```
+     * ```ts
+     * import { createAuth } from "@robelest/convex-auth/component";
+     * import { components } from "./_generated/api";
+     *
+     * const auth = createAuth(components.auth, {
+     *   providers: [google],
+     *   callbacks: {
+     *     async redirect({ redirectTo }) {
+     *       // Check that redirectTo is valid
+     *       // and return the relative or absolute URL
+     *       // to redirect to.
+     *     },
+     *   },
+     * });
+     * ```
      *
      * Convex Auth performs redirect only during OAuth sign-in. By default,
      * it redirects back to the URL specified via the `SITE_URL` environment
@@ -186,7 +207,7 @@ type ConvexAuthConfig = {
        * If this is a sign-in to an existing account,
        * this is the existing user ID linked to that account.
        */
-      existingUserId: GenericId<"user"> | null;
+      existingUserId: GenericId<"User"> | null;
       /**
        * The provider type or "verification" if this callback is called
        * after an email or phone token verification.
@@ -214,7 +235,7 @@ type ConvexAuthConfig = {
        * The `shouldLink` argument passed to `createAccount`.
        */
       shouldLink?: boolean;
-    }) => Promise<GenericId<"user">>;
+    }) => Promise<GenericId<"User">>;
     /**
      * Perform additional writes after a user is created.
      *
@@ -233,12 +254,12 @@ type ConvexAuthConfig = {
       /**
        * The ID of the user that is being signed in.
        */
-      userId: GenericId<"user">;
+      userId: GenericId<"User">;
       /**
        * If this is a sign-in to an existing account,
        * this is the existing user ID linked to that account.
        */
-      existingUserId: GenericId<"user"> | null;
+      existingUserId: GenericId<"User"> | null;
       /**
        * The provider type or "verification" if this callback is called
        * after an email or phone token verification.
@@ -268,6 +289,15 @@ type ConvexAuthConfig = {
       shouldLink?: boolean;
     }) => Promise<void>;
   };
+  /**
+   * Application-defined role and grant model used by membership access checks.
+   */
+  authorization?: {
+    roles: Record<string, {
+      label?: string;
+      grants: string[];
+    }>;
+  };
 };
 /**
  * Union of all supported auth provider config types.
@@ -277,9 +307,105 @@ type ConvexAuthConfig = {
  * (WebAuthn), and TOTP (2FA). Each can be passed as a config object
  * or a factory function.
  */
-type AuthProviderConfig = OAuthProviderInstance | OAuthMaterializedConfig | ConvexCredentialsConfig | ((...args: any) => ConvexCredentialsConfig) | EmailConfig | ((...args: any) => EmailConfig) | PhoneConfig | ((...args: any) => PhoneConfig) | PasskeyProviderConfig | ((...args: any) => PasskeyProviderConfig) | TotpProviderConfig | ((...args: any) => TotpProviderConfig) | DeviceProviderConfig | ((...args: any) => DeviceProviderConfig);
+type AuthProviderConfig = OAuthProviderInstance | Password | Passkey | Totp | Anonymous | Device | SSO | Email | Phone | OAuthMaterializedConfig | ConvexCredentialsConfig | ((...args: any) => ConvexCredentialsConfig) | EmailConfig | ((...args: any) => EmailConfig) | PhoneConfig | ((...args: any) => PhoneConfig) | PasskeyProviderConfig | ((...args: any) => PasskeyProviderConfig) | TotpProviderConfig | ((...args: any) => TotpProviderConfig) | DeviceProviderConfig | ((...args: any) => DeviceProviderConfig) | SSOProviderConfig;
+/**
+ * Minimal config stored for the SSO provider at runtime.
+ * No options — enterprise configuration is entirely per-tenant runtime state.
+ */
+interface SSOProviderConfig {
+  id: string;
+  type: "sso";
+}
+/**
+ * Account linking strategy for enterprise SSO sign-in.
+ *
+ * - `"verifiedEmail"` — link accounts when the IdP-provided email matches a verified email on an existing user.
+ * - `"none"` — never auto-link; always create a new account.
+ */
+type EnterpriseAccountLinkingPolicy = "verifiedEmail" | "none";
+/**
+ * Policy for reusing existing users during SCIM provisioning.
+ *
+ * - `"externalId"` — match by the SCIM `externalId` to reuse a previously provisioned user.
+ * - `"none"` — always create a new user for each SCIM provision request.
+ */
+type EnterpriseScimReuseUserPolicy = "externalId" | "none";
+/**
+ * Just-in-time provisioning mode for enterprise SSO.
+ *
+ * - `"off"` — no JIT provisioning; users must be pre-provisioned.
+ * - `"createUser"` — create a user record on first SSO sign-in.
+ * - `"createUserAndMembership"` — create a user and add them to the enterprise group on first SSO sign-in.
+ */
+type EnterpriseJitProvisioningMode = "off" | "createUser" | "createUserAndMembership";
+/**
+ * Deprovisioning strategy when a SCIM user is deleted.
+ *
+ * - `"soft"` — mark the user as inactive but preserve the record.
+ * - `"hard"` — permanently delete the user and associated data.
+ */
+type EnterpriseDeprovisionMode = "soft" | "hard";
+/**
+ * Effective enterprise policy document stored for an SSO/SCIM tenant.
+ *
+ * Controls account linking, JIT provisioning, SCIM reuse behavior,
+ * deprovisioning, and any app-defined extension metadata.
+ *
+ * @see {@link EnterprisePolicyPatch}
+ */
+interface EnterprisePolicy {
+  version: 1;
+  identity: {
+    accountLinking: {
+      oidc: EnterpriseAccountLinkingPolicy;
+      saml: EnterpriseAccountLinkingPolicy;
+    };
+  };
+  provisioning: {
+    scimReuse: {
+      user: EnterpriseScimReuseUserPolicy;
+    };
+    jit: {
+      mode: EnterpriseJitProvisioningMode;
+      defaultRoleIds: string[];
+    };
+    deprovision: {
+      mode: EnterpriseDeprovisionMode;
+    };
+  };
+  extend?: Record<string, unknown>;
+}
+/**
+ * Partial update payload for {@link EnterprisePolicy}.
+ *
+ * Use this when patching only selected enterprise policy sections without
+ * replacing the entire stored policy document.
+ */
+interface EnterprisePolicyPatch {
+  identity?: {
+    accountLinking?: {
+      oidc?: EnterpriseAccountLinkingPolicy;
+      saml?: EnterpriseAccountLinkingPolicy;
+    };
+  };
+  provisioning?: {
+    scimReuse?: {
+      user?: EnterpriseScimReuseUserPolicy;
+    };
+    jit?: {
+      mode?: EnterpriseJitProvisioningMode;
+      defaultRoleIds?: string[];
+    };
+    deprovision?: {
+      mode?: EnterpriseDeprovisionMode;
+    };
+  };
+  extend?: Record<string, unknown>;
+}
 /**
  * Email provider config for magic link / OTP sign-in.
+ *
+ * @typeParam DataModel - The Convex data model for typed action contexts.
  */
 interface EmailConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /** Provider identifier (e.g. `"email"`, `"resend"`). */
@@ -290,7 +416,11 @@ interface EmailConfig<DataModel extends GenericDataModel = GenericDataModel> {
   name?: string;
   /** Sender address (e.g. `"My App <noreply@example.com>"`). */
   from?: string;
-  /** Token expiration in seconds. Defaults to 86 400 (24 hours). */
+  /**
+   * Token expiration in seconds. Defaults to 86 400 (24 hours).
+   *
+   * @defaultValue 86400
+   */
   maxAge?: number;
   /**
    * Send the verification token to the user.
@@ -328,17 +458,23 @@ interface EmailConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /**
    * The values passed to the `signIn` function.
    */
-  params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "account">) => Promise<void>;
+  params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "Account">) => Promise<void>;
   /** Raw user options before merging with defaults. */
   options: EmailUserConfig<DataModel>;
 }
 /**
- * Configurable options for an email provider config.
+ * User-facing configuration shape accepted by the email provider.
+ *
+ * Equivalent to `Partial<EmailConfig>` without internal runtime-only fields.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 type EmailUserConfig<DataModel extends GenericDataModel = GenericDataModel> = Omit<Partial<EmailConfig<DataModel>>, "options" | "type">;
 /**
  * Same as email provider config, but verifies
  * phone number instead of the email address.
+ *
+ * @typeParam DataModel - The Convex data model for typed action contexts.
  */
 interface PhoneConfig<DataModel extends GenericDataModel = GenericDataModel> {
   id: string;
@@ -387,17 +523,21 @@ interface PhoneConfig<DataModel extends GenericDataModel = GenericDataModel> {
   /**
    * The values passed to the `signIn` function.
    */
-  params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "account">) => Promise<void>;
+  params: Record<string, Value | undefined>, account: GenericDoc<DataModel, "Account">) => Promise<void>;
   options: PhoneUserConfig<DataModel>;
 }
 /**
- * Configurable options for a phone provider config.
+ * User-facing configuration shape accepted by the phone provider.
+ *
+ * Equivalent to `Partial<PhoneConfig>` without internal runtime-only fields.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 type PhoneUserConfig<DataModel extends GenericDataModel = GenericDataModel> = Omit<Partial<PhoneConfig<DataModel>>, "options" | "type">;
 /**
- * Similar to Auth.js Credentials config.
+ * Credentials provider config used by Convex Auth.
  */
-type ConvexCredentialsConfig = CredentialsUserConfig<any> & {
+type ConvexCredentialsConfig = CredentialsConfig<any> & {
   type: "credentials";
   id: string;
 };
@@ -410,12 +550,37 @@ interface PasskeyProviderConfig {
   options: {
     /** Relying Party display name. Defaults to SITE_URL hostname. */rpName?: string; /** Relying Party ID (hostname). Defaults to SITE_URL hostname. */
     rpId?: string; /** Allowed origins for credential verification. Defaults to SITE_URL. */
-    origin?: string | string[]; /** Attestation conveyance preference. Defaults to "none". */
-    attestation?: "none" | "direct"; /** User verification requirement. Defaults to "required". */
-    userVerification?: "required" | "preferred" | "discouraged"; /** Resident key (discoverable credential) preference. Defaults to "preferred". */
+    origin?: string | string[];
+    /**
+     * Attestation conveyance preference. Defaults to "none".
+     *
+     * @defaultValue "none"
+     */
+    attestation?: "none" | "direct";
+    /**
+     * User verification requirement. Defaults to "required".
+     *
+     * @defaultValue "required"
+     */
+    userVerification?: "required" | "preferred" | "discouraged";
+    /**
+     * Resident key (discoverable credential) preference. Defaults to "preferred".
+     *
+     * @defaultValue "preferred"
+     */
     residentKey?: "required" | "preferred" | "discouraged"; /** Restrict to platform or cross-platform authenticators. */
-    authenticatorAttachment?: "platform" | "cross-platform"; /** Supported COSE algorithms. Defaults to [-7 (ES256), -257 (RS256)]. */
-    algorithms?: number[]; /** Challenge expiration in ms. Defaults to 300_000 (5 minutes). */
+    authenticatorAttachment?: "platform" | "cross-platform";
+    /**
+     * Supported COSE algorithms. Defaults to [-7 (ES256), -257 (RS256)].
+     *
+     * @defaultValue [-7, -257]
+     */
+    algorithms?: number[];
+    /**
+     * Challenge expiration in ms. Defaults to 300_000 (5 minutes).
+     *
+     * @defaultValue 300_000
+     */
     challengeExpirationMs?: number;
   };
 }
@@ -426,8 +591,18 @@ interface TotpProviderConfig {
   id: string;
   type: "totp";
   options: {
-    /** Issuer name shown in authenticator apps (e.g. "My App"). */issuer: string; /** Number of digits in each code (default: 6). */
-    digits: number; /** Time period in seconds for code rotation (default: 30). */
+    /** Issuer name shown in authenticator apps (e.g. "My App"). */issuer: string;
+    /**
+     * Number of digits in each code (default: 6).
+     *
+     * @defaultValue 6
+     */
+    digits: number;
+    /**
+     * Time period in seconds for code rotation (default: 30).
+     *
+     * @defaultValue 30
+     */
     period: number;
   };
 }
@@ -477,37 +652,89 @@ type AuthUpdateAccountArgs = {
 };
 /** Arguments for `auth.session.invalidate()`. */
 type AuthInvalidateSessionsArgs = {
-  userId: GenericId<"user">;
-  except?: GenericId<"session">[];
+  userId: GenericId<"User">;
+  except?: GenericId<"Session">[];
 };
 /** Arguments for `auth.provider.signIn()`. */
 type AuthProviderSignInArgs = {
-  accountId?: GenericId<"account">;
+  accountId?: GenericId<"Account">;
   params?: Record<string, Value | undefined>;
 };
 /** Return type of `auth.provider.signIn()` — user and session IDs, or `null` on failure. */
 type AuthProviderSignInResult = {
-  userId: GenericId<"user">;
-  sessionId: GenericId<"session">;
+  userId: GenericId<"User">;
+  sessionId: GenericId<"Session">;
 } | null;
-/** Server-side auth helpers available on enriched action contexts. */
+/** Arguments for `auth.member.resolve()`. */
+type AuthMemberResolveArgs = {
+  userId: GenericId<"User">;
+  groupId: GenericId<"Group">;
+  ancestry?: boolean;
+  roleIds?: string[];
+  grants?: string[];
+  maxDepth?: number;
+};
+/** Result of `auth.member.resolve()` — membership check with role and grant details. */
+type AuthMemberResolveResult = {
+  ok: boolean;
+  membership: GenericDoc<GenericDataModel, "GroupMember"> | null;
+  matchedGroupId: GenericId<"Group"> | null;
+  roleIds: string[];
+  grants: string[];
+  missingGrants: string[];
+  depth: number | null;
+  isDirect: boolean;
+  isInherited: boolean;
+  traversedGroupIds: GenericId<"Group">[];
+  code?: "INVALID_ROLE_IDS";
+  invalidRoleIds?: string[];
+};
+/**
+ * Server-side auth helper methods injected into `ctx.auth` within provider actions.
+ *
+ * Provides programmatic access to account management, session lifecycle,
+ * membership resolution, and provider sign-in from within Convex actions
+ * that use {@link GenericActionCtxWithAuthConfig}.
+ *
+ * @see {@link GenericActionCtxWithAuthConfig}
+ *
+ * @example
+ * ```ts
+ * // Inside a credentials provider's authorize callback:
+ * const { account, user } = await ctx.auth.account.get(ctx, {
+ *   provider: "password",
+ *   account: { id: email },
+ * });
+ * ```
+ */
 type AuthServerHelpers = {
-  account: {
+  /** Account management: create, retrieve, and update provider-linked accounts. */account: {
     create: (ctx: GenericActionCtx<any>, args: AuthCreateAccountArgs) => Promise<{
-      account: GenericDoc<GenericDataModel, "account">;
-      user: GenericDoc<GenericDataModel, "user">;
+      ok: true;
+      account: GenericDoc<GenericDataModel, "Account">;
+      user: GenericDoc<GenericDataModel, "User">;
     }>;
     get: (ctx: GenericActionCtx<any>, args: AuthRetrieveAccountArgs) => Promise<{
-      account: GenericDoc<GenericDataModel, "account">;
-      user: GenericDoc<GenericDataModel, "user">;
+      account: GenericDoc<GenericDataModel, "Account">;
+      user: GenericDoc<GenericDataModel, "User">;
+    }>;
+    update: (ctx: GenericActionCtx<any>, args: AuthUpdateAccountArgs) => Promise<{
+      ok: true;
+      accountId: GenericId<"Account">;
     }>;
-    update: (ctx: GenericActionCtx<any>, args: AuthUpdateAccountArgs) => Promise<void>;
   };
   session: {
     current: (ctx: {
       auth: GenericActionCtx<GenericDataModel>["auth"];
-    }) => Promise<GenericId<"session"> | null>;
-    invalidate: (ctx: GenericActionCtx<any>, args: AuthInvalidateSessionsArgs) => Promise<void>;
+    }) => Promise<GenericId<"Session"> | null>;
+    invalidate: (ctx: GenericActionCtx<any>, args: AuthInvalidateSessionsArgs) => Promise<{
+      ok: true;
+      userId: GenericId<"User">;
+      except: GenericId<"Session">[];
+    }>;
+  };
+  member: {
+    resolve: (ctx: GenericActionCtx<any>, args: AuthMemberResolveArgs) => Promise<AuthMemberResolveResult>;
   };
   provider: {
     signIn: (ctx: GenericActionCtx<any>, provider: AuthProviderConfig, args: AuthProviderSignInArgs) => Promise<AuthProviderSignInResult>;
@@ -515,7 +742,9 @@ type AuthServerHelpers = {
 };
 /**
  * Your `ActionCtx` enriched with `ctx.auth.config` field with
- * the config passed to `Auth`.
+ * the config passed to `createAuth`.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 type GenericActionCtxWithAuthConfig<DataModel extends GenericDataModel> = GenericActionCtx<DataModel> & {
   auth: GenericActionCtx<DataModel>["auth"] & {
@@ -523,34 +752,51 @@ type GenericActionCtxWithAuthConfig<DataModel extends GenericDataModel> = Generi
   } & AuthServerHelpers;
 };
 /**
- * The config for the Convex Auth library, passed to `Auth`,
+ * The config for the Convex Auth library, passed to `createAuth`,
  * with defaults and initialized providers.
  *
  * See {@link ConvexAuthConfig}
  */
 type ConvexAuthMaterializedConfig = {
   providers: AuthProviderMaterializedConfig[];
-} & Pick<ConvexAuthConfig, "component" | "session" | "jwt" | "signIn" | "callbacks">;
+} & Pick<ConvexAuthConfig, "component" | "session" | "jwt" | "signIn" | "callbacks" | "authorization">;
 /**
  * Materialized OAuth provider config (Arctic-based).
  *
  * Carries the Arctic provider instance along with scopes and profile config.
- * Produced by materializing an `OAuthProviderInstance` during `configDefaults`.
+  * Produced by materializing an `OAuthProviderInstance` during `configDefaults`.
  */
 interface OAuthMaterializedConfig {
+  /**
+   * Provider identifier (e.g. `"google"`, `"github"`).
+   * @readonly
+   */
   readonly id: string;
+  /**
+   * Discriminant for provider type routing.
+   * @readonly
+   */
   readonly type: "oauth";
-  /** The Arctic provider instance. */
+  /**
+   * The Arctic provider instance.
+   * @readonly
+   */
   readonly provider: any;
-  /** OAuth scopes to request. */
+  /**
+   * OAuth scopes to request.
+   * @readonly
+   */
   readonly scopes: string[];
-  /** User-provided profile extraction callback. */
+  /**
+   * User-provided profile extraction callback.
+   * @readonly
+   */
   readonly profile?: (tokens: arctic0.OAuth2Tokens) => Promise<OAuthProfile>;
   /**
-   * Allow linking accounts by email even if the email is unverified.
-   * Use with caution — only enable for providers you trust.
+   * Account-linking policy for OAuth identities. Defaults to verified email linking.
+   * @readonly
    */
-  readonly allowDangerousEmailAccountLinking?: boolean;
+  readonly accountLinking?: "verifiedEmail" | "none";
 }
 /**
  * Device authorization provider config (RFC 8628).
@@ -580,49 +826,14 @@ interface DeviceProviderConfig {
 /**
  * Materialized auth provider config — the fully resolved form stored at runtime.
  */
-type AuthProviderMaterializedConfig = OAuthMaterializedConfig | EmailConfig | PhoneConfig | ConvexCredentialsConfig | PasskeyProviderConfig | TotpProviderConfig | DeviceProviderConfig;
+type AuthProviderMaterializedConfig = OAuthMaterializedConfig | EmailConfig | PhoneConfig | ConvexCredentialsConfig | PasskeyProviderConfig | TotpProviderConfig | DeviceProviderConfig | SSOProviderConfig;
 /**
- * Email delivery parameters passed to `EmailTransport.send`.
- */
-interface EmailMessage {
-  /** Sender address (from `email.from` in your Auth config). */
-  from: string;
-  /** Recipient email address. */
-  to: string;
-  /** Email subject line. */
-  subject: string;
-  /** HTML body content. */
-  html: string;
-}
-/**
- * Email transport configuration for the Auth library.
+ * Resolves to `true` when the providers list includes `SSO`, otherwise `false`.
  *
- * Provides a delivery mechanism for library-generated emails.
- * The library owns the email content; you provide the transport.
+ * Used to make `auth.sso` conditionally present on the `createAuth`
+ * return type — it only appears when `new SSO()` is in the providers array.
  */
-interface EmailTransport {
-  /** Sender address shown in the From field (e.g. "My App \<noreply@example.com\>"). */
-  from: string;
-  /**
-   * Deliver an email. Called by the library for magic links.
-   *
-   * Receives the Convex action context as the first argument, enabling
-   * use with Convex components like `@convex-dev/resend`:
-   *
-   * ```ts
-   * send: (ctx, params) => resend.sendEmail(ctx, params)
-   * ```
-   *
-   * For plain HTTP email APIs, ignore the `ctx` parameter:
-   *
-   * ```ts
-   * send: async (_ctx, { from, to, subject, html }) => {
-   *   await fetch("https://api.resend.com/emails", { ... });
-   * }
-   * ```
-   */
-  send: (ctx: GenericActionCtx<any>, params: EmailMessage) => Promise<void>;
-}
+type HasSSO<P extends AuthProviderConfig[]> = SSO extends P[number] ? true : false;
 /**
  * A single scope entry stored per API key.
  * Uses a resource:action pattern for structured permissions.
@@ -652,41 +863,6 @@ interface ScopeChecker {
   /** The raw scope entries from the key. */
   scopes: KeyScope[];
 }
-/**
- * Configuration for API key support on the Auth class.
- *
- * ```ts
- * const auth = new Auth(components.auth, {
- *   providers: [github],
- *   apiKeys: {
- *     scopes: {
- *       users: ["read", "list", "create", "delete"],
- *       messages: ["read", "write"],
- *     },
- *     defaultRateLimit: { maxRequests: 1000, windowMs: 3600000 },
- *   },
- * });
- * ```
- */
-interface ApiKeyConfig {
-  /**
-   * Define the available resource:action scopes for your API keys.
-   * Keys can only be created with scopes that are a subset of these.
-   */
-  scopes?: Record<string, string[]>;
-  /**
-   * Default rate limit applied to new keys when not specified per-key.
-   * Uses a token-bucket algorithm.
-   */
-  defaultRateLimit?: {
-    maxRequests: number;
-    windowMs: number;
-  };
-  /**
-   * Key prefix. Defaults to `"sk_live_"`.
-   */
-  prefix?: string;
-}
 /**
  * An API key record as returned by `auth.key.list()` and `auth.key.get()`.
  * Never includes the raw key material — only the display prefix.
@@ -696,7 +872,7 @@ interface KeyRecord {
   _id: string;
   /** Owner user ID. */
   userId: string;
-  /** Display prefix (e.g. `"sk_live_abc1"`). Safe to show in UIs. */
+  /** Display prefix (e.g. `"sk_abc1"`). Safe to show in UIs. */
   prefix: string;
   /** Human-readable name (e.g. "CI Pipeline"). */
   name: string;
@@ -715,16 +891,9 @@ interface KeyRecord {
   createdAt: number;
   /** `true` when the key has been revoked (soft-deleted). */
   revoked: boolean;
+  /** Arbitrary app-specific metadata attached to the key. */
+  metadata?: Record<string, unknown>;
 }
-/** Filter fields for `auth.user.list()`. All optional. */
-type UserWhere = {
-  email?: string;
-  phone?: string;
-  isAnonymous?: boolean;
-  name?: string;
-};
-/** Sortable fields for `auth.user.list()`. */
-type UserOrderBy = "_creationTime" | "name" | "email" | "phone";
 /**
  * Context injected into `auth.http.action()` and `auth.http.route()` handlers.
  *
@@ -760,95 +929,6 @@ interface CorsConfig {
   /** Allowed request headers. Defaults to `"Content-Type,Authorization"`. */
   headers?: string;
 }
-/**
- * Component function references required by core auth runtime.
- *
- * @internal Consumers should not depend on this shape — it may change
- * between minor versions. Pass `components.auth` directly to the `Auth` constructor.
- */
-type AuthComponentApi = {
-  public: {
-    userGetById: FunctionReference<"query", "internal">;
-    userList: FunctionReference<"query", "internal">;
-    userFindByVerifiedEmail: FunctionReference<"query", "internal">;
-    userFindByVerifiedPhone: FunctionReference<"query", "internal">;
-    userInsert: FunctionReference<"mutation", "internal">;
-    userUpsert: FunctionReference<"mutation", "internal">;
-    userPatch: FunctionReference<"mutation", "internal">;
-    accountGet: FunctionReference<"query", "internal">;
-    accountGetById: FunctionReference<"query", "internal">;
-    accountInsert: FunctionReference<"mutation", "internal">;
-    accountPatch: FunctionReference<"mutation", "internal">;
-    accountDelete: FunctionReference<"mutation", "internal">;
-    sessionCreate: FunctionReference<"mutation", "internal">;
-    sessionGetById: FunctionReference<"query", "internal">;
-    sessionDelete: FunctionReference<"mutation", "internal">;
-    sessionListByUser: FunctionReference<"query", "internal">;
-    verifierCreate: FunctionReference<"mutation", "internal">;
-    verifierGetById: FunctionReference<"query", "internal">;
-    verifierGetBySignature: FunctionReference<"query", "internal">;
-    verifierPatch: FunctionReference<"mutation", "internal">;
-    verifierDelete: FunctionReference<"mutation", "internal">;
-    verificationCodeGetByAccountId: FunctionReference<"query", "internal">;
-    verificationCodeGetByCode: FunctionReference<"query", "internal">;
-    verificationCodeCreate: FunctionReference<"mutation", "internal">;
-    verificationCodeDelete: FunctionReference<"mutation", "internal">;
-    refreshTokenCreate: FunctionReference<"mutation", "internal">;
-    refreshTokenGetById: FunctionReference<"query", "internal">;
-    refreshTokenPatch: FunctionReference<"mutation", "internal">;
-    refreshTokenGetChildren: FunctionReference<"query", "internal">;
-    refreshTokenListBySession: FunctionReference<"query", "internal">;
-    refreshTokenDeleteAll: FunctionReference<"mutation", "internal">;
-    refreshTokenGetActive: FunctionReference<"query", "internal">;
-    rateLimitGet: FunctionReference<"query", "internal">;
-    rateLimitCreate: FunctionReference<"mutation", "internal">;
-    rateLimitPatch: FunctionReference<"mutation", "internal">;
-    rateLimitDelete: FunctionReference<"mutation", "internal">;
-    groupCreate: FunctionReference<"mutation", "internal">;
-    groupGet: FunctionReference<"query", "internal">;
-    groupList: FunctionReference<"query", "internal">;
-    groupUpdate: FunctionReference<"mutation", "internal">;
-    groupDelete: FunctionReference<"mutation", "internal">;
-    memberAdd: FunctionReference<"mutation", "internal">;
-    memberGet: FunctionReference<"query", "internal">;
-    memberList: FunctionReference<"query", "internal">;
-    memberListByUser: FunctionReference<"query", "internal">;
-    memberGetByGroupAndUser: FunctionReference<"query", "internal">;
-    memberRemove: FunctionReference<"mutation", "internal">;
-    memberUpdate: FunctionReference<"mutation", "internal">;
-    inviteCreate: FunctionReference<"mutation", "internal">;
-    inviteGet: FunctionReference<"query", "internal">;
-    inviteList: FunctionReference<"query", "internal">;
-    inviteAccept: FunctionReference<"mutation", "internal">;
-    inviteRevoke: FunctionReference<"mutation", "internal">;
-    keyInsert: FunctionReference<"mutation", "internal">;
-    keyGetByHashedKey: FunctionReference<"query", "internal">;
-    keyGetById: FunctionReference<"query", "internal">;
-    keyList: FunctionReference<"query", "internal">;
-    keyListByUserId: FunctionReference<"query", "internal">;
-    keyPatch: FunctionReference<"mutation", "internal">;
-    keyDelete: FunctionReference<"mutation", "internal">;
-    passkeyInsert: FunctionReference<"mutation", "internal">;
-    passkeyGetByCredentialId: FunctionReference<"query", "internal">;
-    passkeyListByUserId: FunctionReference<"query", "internal">;
-    passkeyUpdateCounter: FunctionReference<"mutation", "internal">;
-    passkeyUpdateMeta: FunctionReference<"mutation", "internal">;
-    passkeyDelete: FunctionReference<"mutation", "internal">;
-    totpInsert: FunctionReference<"mutation", "internal", any, any>;
-    totpGetVerifiedByUserId: FunctionReference<"query", "internal", any, any>;
-    totpListByUserId: FunctionReference<"query", "internal", any, any>;
-    totpGetById: FunctionReference<"query", "internal", any, any>;
-    totpMarkVerified: FunctionReference<"mutation", "internal", any, any>;
-    totpUpdateLastUsed: FunctionReference<"mutation", "internal", any, any>;
-    totpDelete: FunctionReference<"mutation", "internal", any, any>;
-    deviceInsert: FunctionReference<"mutation", "internal", any, any>;
-    deviceGetByCodeHash: FunctionReference<"query", "internal", any, any>;
-    deviceGetByUserCode: FunctionReference<"query", "internal", any, any>;
-    deviceAuthorize: FunctionReference<"mutation", "internal", any, any>;
-    deviceUpdateLastPolled: FunctionReference<"mutation", "internal", any, any>;
-    deviceDelete: FunctionReference<"mutation", "internal", any, any>;
-  };
-};
 /**
  * Convex document from a given table.
  */
@@ -856,12 +936,21 @@ type GenericDoc<DataModel extends GenericDataModel, TableName extends TableNames
   _id: GenericId<TableName>;
   _creationTime: number;
 };
-/**
- * @internal
- */
-type FunctionReferenceFromExport<Export> = Export extends RegisteredQuery<infer Visibility, infer Args, infer Output> ? FunctionReference<"query", Visibility, Args, ConvertReturnType<Output>> : Export extends RegisteredMutation<infer Visibility, infer Args, infer Output> ? FunctionReference<"mutation", Visibility, Args, ConvertReturnType<Output>> : Export extends RegisteredAction<infer Visibility, infer Args, infer Output> ? FunctionReference<"action", Visibility, Args, ConvertReturnType<Output>> : never;
-type ConvertReturnType<T> = UndefinedToNull<Awaited<T>>;
-type UndefinedToNull<T> = T extends void ? null : T;
+/** Data model derived from the component schema. */
+type AuthDataModel = DataModelFromSchemaDefinition<typeof _default>;
+/** A document from any table in the auth component schema. */
+type Doc<T extends TableNamesInDataModel<AuthDataModel>> = GenericDoc<AuthDataModel, T>;
+/** A pair of JWT access token and refresh token. */
+type Tokens = {
+  token: string;
+  refreshToken: string;
+};
+/** Session information returned after authentication. */
+type SessionInfo = {
+  userId: GenericId<"User">;
+  sessionId: GenericId<"Session">;
+  tokens: Tokens | null;
+};
 //#endregion
-export { ApiKeyConfig, AuthProviderConfig, AuthProviderMaterializedConfig, ConvexAuthConfig, ConvexAuthMaterializedConfig, ConvexCredentialsConfig, CorsConfig, DeviceProviderConfig, EmailConfig, EmailUserConfig, FunctionReferenceFromExport, GenericActionCtxWithAuthConfig, GenericDoc, HttpKeyContext, KeyRecord, KeyScope, OAuthProfile, PhoneConfig, PhoneUserConfig, ScopeChecker, UserOrderBy, UserWhere };
+export { AuthAuthorizationConfig, AuthGrant, AuthProviderConfig, AuthRoleId, ConvexAuthConfig, ConvexCredentialsConfig, CorsConfig, DeviceProviderConfig, Doc, EmailConfig, EmailUserConfig, EnterprisePolicy, EnterprisePolicyPatch, GenericActionCtxWithAuthConfig, GenericDoc, HasSSO, HttpKeyContext, KeyRecord, KeyScope, OAuthProfile, PhoneConfig, PhoneUserConfig, ScopeChecker, SessionInfo };
 //# sourceMappingURL=types.d.ts.map