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

package/src/server/types.ts

@@ -1,27 +1,107 @@
 import {
   AnyDataModel,
+  DataModelFromSchemaDefinition,
   DocumentByName,
   FunctionReference,
   GenericActionCtx,
   GenericDataModel,
   GenericMutationCtx,
+  GenericQueryCtx,
   RegisteredAction,
   RegisteredMutation,
   RegisteredQuery,
   TableNamesInDataModel,
 } from "convex/server";
+import type { Infer } from "convex/values";
 import { GenericId, Value } from "convex/values";
-import { CredentialsUserConfig } from "../providers/credentials";
+
+import {
+  vApiKeyDoc,
+  vAuthVerifierDoc,
+  vDeviceCodeDoc,
+  vPasskeyDoc,
+  vTotpFactorDoc,
+  vUserDoc,
+} from "../component/model";
+import schema from "../component/schema";
+import type { CredentialsConfig } from "../providers/credentials";
 
 // ============================================================================
 // Utility types
 // ============================================================================
 
-/** 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.
+ */
 export 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}
+ */
+export 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}
+ */
+export 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}
+ */
+export 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}
+ */
+export 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`.
  */
 export type ConvexAuthConfig = {
   /**
@@ -46,12 +126,16 @@ export 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;
   };
@@ -63,6 +147,8 @@ export type ConvexAuthConfig = {
      * How long is the JWT valid for after it is signed initially.
      *
      * Defaults to 1 hour.
+     *
+     * @defaultValue 3_600_000
      */
     durationMs?: number;
   };
@@ -76,63 +162,11 @@ export 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.
    *
@@ -145,20 +179,21 @@ export 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
@@ -201,7 +236,7 @@ export 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.
@@ -230,7 +265,7 @@ export type ConvexAuthConfig = {
          */
         shouldLink?: boolean;
       },
-    ) => Promise<GenericId<"user">>;
+    ) => Promise<GenericId<"User">>;
     /**
      * Perform additional writes after a user is created.
      *
@@ -251,12 +286,12 @@ export 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.
@@ -287,6 +322,18 @@ export type ConvexAuthConfig = {
       },
     ) => Promise<void>;
   };
+  /**
+   * Application-defined role and grant model used by membership access checks.
+   */
+  authorization?: {
+    roles: Record<
+      string,
+      {
+        label?: string;
+        grants: string[];
+      }
+    >;
+  };
 };
 
 /**
@@ -299,6 +346,14 @@ export type ConvexAuthConfig = {
  */
 export type AuthProviderConfig =
   | import("../providers/oauth").OAuthProviderInstance
+  | import("../providers/password").Password
+  | import("../providers/passkey").Passkey
+  | import("../providers/totp").Totp
+  | import("../providers/anonymous").Anonymous
+  | import("../providers/device").Device
+  | import("../providers/sso").SSO
+  | import("../providers/email").Email
+  | import("../providers/phone").Phone
   | OAuthMaterializedConfig
   | ConvexCredentialsConfig
   | ((...args: any) => ConvexCredentialsConfig)
@@ -311,10 +366,117 @@ export type AuthProviderConfig =
   | TotpProviderConfig
   | ((...args: any) => TotpProviderConfig)
   | DeviceProviderConfig
-  | ((...args: any) => DeviceProviderConfig);
+  | ((...args: any) => DeviceProviderConfig)
+  | SSOProviderConfig;
+
+/**
+ * Minimal config stored for the SSO provider at runtime.
+ * No options — enterprise configuration is entirely per-tenant runtime state.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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}
+ */
+export 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.
+ */
+export 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.
  */
 export interface EmailConfig<
   DataModel extends GenericDataModel = GenericDataModel,
@@ -327,7 +489,11 @@ export interface EmailConfig<
   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.
@@ -369,14 +535,18 @@ export interface EmailConfig<
      * The values passed to the `signIn` function.
      */
     params: Record<string, Value | undefined>,
-    account: GenericDoc<DataModel, "account">,
+    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.
  */
 export type EmailUserConfig<
   DataModel extends GenericDataModel = GenericDataModel,
@@ -385,6 +555,8 @@ export type EmailUserConfig<
 /**
  * Same as email provider config, but verifies
  * phone number instead of the email address.
+ *
+ * @typeParam DataModel - The Convex data model for typed action contexts.
  */
 export interface PhoneConfig<
   DataModel extends GenericDataModel = GenericDataModel,
@@ -439,22 +611,26 @@ export interface PhoneConfig<
      * The values passed to the `signIn` function.
      */
     params: Record<string, Value | undefined>,
-    account: GenericDoc<DataModel, "account">,
+    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.
  */
 export 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.
  */
-export type ConvexCredentialsConfig = CredentialsUserConfig<any> & {
+export type ConvexCredentialsConfig = CredentialsConfig<any> & {
   type: "credentials";
   id: string;
 };
@@ -472,17 +648,37 @@ export interface PasskeyProviderConfig {
     rpId?: string;
     /** Allowed origins for credential verification. Defaults to SITE_URL. */
     origin?: string | string[];
-    /** Attestation conveyance preference. Defaults to "none". */
+    /**
+     * Attestation conveyance preference. Defaults to "none".
+     *
+     * @defaultValue "none"
+     */
     attestation?: "none" | "direct";
-    /** User verification requirement. Defaults to "required". */
+    /**
+     * User verification requirement. Defaults to "required".
+     *
+     * @defaultValue "required"
+     */
     userVerification?: "required" | "preferred" | "discouraged";
-    /** Resident key (discoverable credential) preference. Defaults to "preferred". */
+    /**
+     * 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)]. */
+    /**
+     * Supported COSE algorithms. Defaults to [-7 (ES256), -257 (RS256)].
+     *
+     * @defaultValue [-7, -257]
+     */
     algorithms?: number[];
-    /** Challenge expiration in ms. Defaults to 300_000 (5 minutes). */
+    /**
+     * Challenge expiration in ms. Defaults to 300_000 (5 minutes).
+     *
+     * @defaultValue 300_000
+     */
     challengeExpirationMs?: number;
   };
 }
@@ -496,9 +692,17 @@ export interface TotpProviderConfig {
   options: {
     /** Issuer name shown in authenticator apps (e.g. "My App"). */
     issuer: string;
-    /** Number of digits in each code (default: 6). */
+    /**
+     * Number of digits in each code (default: 6).
+     *
+     * @defaultValue 6
+     */
     digits: number;
-    /** Time period in seconds for code rotation (default: 30). */
+    /**
+     * Time period in seconds for code rotation (default: 30).
+     *
+     * @defaultValue 30
+     */
     period: number;
   };
 }
@@ -526,6 +730,8 @@ export interface OAuthProfile {
  *
  * This is what the OAuth flow code receives — it maps to the user-facing
  * `OAuthConfig` from `@robelest/convex-auth/providers`.
+ *
+ * @internal
  */
 export interface OAuthProviderConfig {
   /** OAuth scopes to request. */
@@ -573,52 +779,107 @@ export type AuthUpdateAccountArgs = {
 
 /** Arguments for `auth.session.invalidate()`. */
 export type AuthInvalidateSessionsArgs = {
-  userId: GenericId<"user">;
-  except?: GenericId<"session">[];
+  userId: GenericId<"User">;
+  except?: GenericId<"Session">[];
 };
 
 /** Arguments for `auth.provider.signIn()`. */
 export 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. */
 export 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()`. */
+export 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. */
+export 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 },
+ * });
+ * ```
+ */
 export type AuthServerHelpers = {
+  /** 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<void>;
+    ) => Promise<{ ok: true; accountId: GenericId<"Account"> }>;
   };
   session: {
-    current: (
-      ctx: { auth: GenericActionCtx<GenericDataModel>["auth"] },
-    ) => Promise<GenericId<"session"> | null>;
+    current: (ctx: {
+      auth: GenericActionCtx<GenericDataModel>["auth"];
+    }) => Promise<GenericId<"Session"> | null>;
     invalidate: (
       ctx: GenericActionCtx<any>,
       args: AuthInvalidateSessionsArgs,
-    ) => Promise<void>;
+    ) => Promise<{
+      ok: true;
+      userId: GenericId<"User">;
+      except: GenericId<"Session">[];
+    }>;
+  };
+  member: {
+    resolve: (
+      ctx: GenericActionCtx<any>,
+      args: AuthMemberResolveArgs,
+    ) => Promise<AuthMemberResolveResult>;
   };
   provider: {
     signIn: (
@@ -631,7 +892,9 @@ export 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.
  */
 export type GenericActionCtxWithAuthConfig<DataModel extends GenericDataModel> =
   GenericActionCtx<DataModel> & {
@@ -641,7 +904,7 @@ export type GenericActionCtxWithAuthConfig<DataModel extends GenericDataModel> =
   };
 
 /**
- * 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}
@@ -650,29 +913,67 @@ export type ConvexAuthMaterializedConfig = {
   providers: AuthProviderMaterializedConfig[];
 } & Pick<
   ConvexAuthConfig,
-  "component" | "session" | "jwt" | "signIn" | "callbacks"
+  "component" | "session" | "jwt" | "signIn" | "callbacks" | "authorization"
 >;
 
+/**
+ * Maps SAML assertion attribute names to user profile fields.
+ *
+ * Use this to tell the SSO flow which SAML attributes correspond to
+ * the user's subject identifier, email, and display name fields.
+ */
+export interface SAMLAttributeMapping {
+  /** SAML attribute for the unique subject identifier (NameID). */
+  subject?: string;
+  /** SAML attribute for the user's email address. */
+  email?: string;
+  /** SAML attribute for the user's full display name. */
+  name?: string;
+  /** SAML attribute for the user's first / given name. */
+  firstName?: string;
+  /** SAML attribute for the user's last / family name. */
+  lastName?: string;
+}
+
 /**
  * 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`.
  */
 export 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. */
-  readonly profile?: (tokens: import("arctic").OAuth2Tokens) => Promise<OAuthProfile>;
   /**
-   * Allow linking accounts by email even if the email is unverified.
-   * Use with caution — only enable for providers you trust.
+   * User-provided profile extraction callback.
+   * @readonly
+   */
+  readonly profile?: (
+    tokens: import("arctic").OAuth2Tokens,
+  ) => Promise<OAuthProfile>;
+  /**
+   * Account-linking policy for OAuth identities. Defaults to verified email linking.
+   * @readonly
    */
-  readonly allowDangerousEmailAccountLinking?: boolean;
+  readonly accountLinking?: "verifiedEmail" | "none";
 }
 
 /**
@@ -711,58 +1012,26 @@ export type AuthProviderMaterializedConfig =
   | ConvexCredentialsConfig
   | PasskeyProviderConfig
   | TotpProviderConfig
-  | DeviceProviderConfig;
-
-// ============================================================================
-// Email transport types
-// ============================================================================
-
-/**
- * Email delivery parameters passed to `EmailTransport.send`.
- */
-export 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;
-}
+  | DeviceProviderConfig
+  | SSOProviderConfig;
 
 /**
- * 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.
  */
-export 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>;
-}
+export type HasSSO<P extends AuthProviderConfig[]> =
+  import("../providers/sso").SSO extends P[number] ? true : false;
+
+export type HasPasskeyProvider<P extends AuthProviderConfig[]> =
+  import("../providers/passkey").Passkey extends P[number] ? true : false;
+
+export type HasTotpProvider<P extends AuthProviderConfig[]> =
+  import("../providers/totp").Totp extends P[number] ? true : false;
+
+export type HasDeviceProvider<P extends AuthProviderConfig[]> =
+  import("../providers/device").Device extends P[number] ? true : false;
 
 // ============================================================================
 // API Key types
@@ -799,39 +1068,6 @@ export interface ScopeChecker {
   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 },
- *   },
- * });
- * ```
- */
-export 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.
@@ -841,7 +1077,7 @@ export 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;
@@ -857,6 +1093,8 @@ export 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>;
 }
 
 // ============================================================================
@@ -867,6 +1105,9 @@ export interface KeyRecord {
  * Options for paginated list queries. Every entity list method uses this
  * same shape with entity-specific `TWhere` and `TOrderBy` type parameters.
  *
+ * @typeParam TWhere - The type of the optional filter object.
+ * @typeParam TOrderBy - The union of sortable field names.
+ *
  * ```ts
  * const result = await auth.group.list(ctx, {
  *   where: { type: "team" },
@@ -894,6 +1135,8 @@ export type ListOptions<
 
 /**
  * Paginated list result returned by every entity list method.
+ *
+ * @typeParam T - The type of items in the result array.
  */
 export type ListResult<T> = {
   /** The page of items. */
@@ -938,16 +1181,16 @@ export type GroupWhere = {
 /** Sortable fields for `auth.group.list()`. */
 export type GroupOrderBy = "_creationTime" | "name" | "slug" | "type";
 
-/** Filter fields for `auth.group.member.list()`. All optional. */
+/** Filter fields for `auth.member.list()`. All optional. */
 export type MemberWhere = {
   groupId?: string;
   userId?: string;
-  role?: string;
+  roleId?: string;
   status?: string;
 };
 
-/** Sortable fields for `auth.group.member.list()`. */
-export type MemberOrderBy = "_creationTime" | "role" | "status";
+/** Sortable fields for `auth.member.list()`. */
+export type MemberOrderBy = "_creationTime" | "status";
 
 /** Filter fields for `auth.invite.list()`. All optional. */
 export type InviteWhere = {
@@ -956,7 +1199,7 @@ export type InviteWhere = {
   status?: "pending" | "accepted" | "revoked" | "expired";
   email?: string;
   invitedByUserId?: string;
-  role?: string;
+  roleId?: string;
   acceptedByUserId?: string;
 };
 
@@ -1043,7 +1286,7 @@ export interface CorsConfig {
  * 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.
+ * between minor versions. Pass `components.auth` directly to `createAuth`.
  */
 export type AuthComponentApi = {
   public: {
@@ -1054,9 +1297,11 @@ export type AuthComponentApi = {
     userInsert: FunctionReference<"mutation", "internal">;
     userUpsert: FunctionReference<"mutation", "internal">;
     userPatch: FunctionReference<"mutation", "internal">;
+    userDelete: FunctionReference<"mutation", "internal">;
     accountGet: FunctionReference<"query", "internal">;
     accountGetById: FunctionReference<"query", "internal">;
     accountInsert: FunctionReference<"mutation", "internal">;
+    accountListByUser: FunctionReference<"query", "internal">;
     accountPatch: FunctionReference<"mutation", "internal">;
     accountDelete: FunctionReference<"mutation", "internal">;
     sessionCreate: FunctionReference<"mutation", "internal">;
@@ -1091,20 +1336,20 @@ export type AuthComponentApi = {
     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">;
+    inviteGetByTokenHash: FunctionReference<"query", "internal">;
     inviteList: FunctionReference<"query", "internal">;
     inviteAccept: FunctionReference<"mutation", "internal">;
+    inviteAcceptByToken: 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">;
@@ -1126,6 +1371,142 @@ export type AuthComponentApi = {
     deviceAuthorize: FunctionReference<"mutation", "internal", any, any>;
     deviceUpdateLastPolled: FunctionReference<"mutation", "internal", any, any>;
     deviceDelete: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseCreate: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseGet: FunctionReference<"query", "internal", any, any>;
+    enterpriseGetByGroup: FunctionReference<"query", "internal", any, any>;
+    enterpriseGetByDomain: FunctionReference<"query", "internal", any, any>;
+    enterpriseList: FunctionReference<"query", "internal", any, any>;
+    enterpriseUpdate: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseDelete: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseDomainAdd: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseDomainList: FunctionReference<"query", "internal", any, any>;
+    enterpriseDomainDelete: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseDomainVerificationGet: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseDomainVerificationUpsert: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseDomainVerificationDelete: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseDomainVerify: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseSecretUpsert: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseSecretGet: FunctionReference<"query", "internal", any, any>;
+    enterpriseSecretDelete: FunctionReference<"mutation", "internal", any, any>;
+    enterpriseScimConfigUpsert: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimConfigGetByEnterprise: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimConfigGetByTokenHash: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimIdentityGet: FunctionReference<"query", "internal", any, any>;
+    enterpriseScimIdentityGetByUser: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimIdentityGetByEnterpriseAndUser: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimIdentityGetByMappedGroup: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimIdentityListByEnterprise: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimIdentityUpsert: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseScimIdentityDelete: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseAuditEventCreate: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseAuditEventList: FunctionReference<"query", "internal", any, any>;
+    enterpriseWebhookEndpointCreate: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseWebhookEndpointList: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseWebhookEndpointGet: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseWebhookEndpointUpdate: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseWebhookDeliveryEnqueue: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseWebhookDeliveryListReady: FunctionReference<
+      "query",
+      "internal",
+      any,
+      any
+    >;
+    enterpriseWebhookDeliveryPatch: FunctionReference<
+      "mutation",
+      "internal",
+      any,
+      any
+    >;
   };
 };
 
@@ -1177,3 +1558,387 @@ export type FunctionReferenceFromExport<Export> =
 type ConvertReturnType<T> = UndefinedToNull<Awaited<T>>;
 
 type UndefinedToNull<T> = T extends void ? null : T;
+
+// Internal server data-model types (merged from former internalTypes.ts)
+
+/** Data model derived from the component schema. */
+export type AuthDataModel = DataModelFromSchemaDefinition<typeof schema>;
+
+/** Action context typed to the auth component's data model. */
+export type ActionCtx = GenericActionCtx<AuthDataModel>;
+
+/** Mutation context typed to the auth component's data model. */
+export type MutationCtx = GenericMutationCtx<AuthDataModel>;
+
+/** Query context typed to the auth component's data model. */
+export type QueryCtx = GenericQueryCtx<AuthDataModel>;
+
+/** A document from any table in the auth component schema. */
+export type Doc<T extends TableNamesInDataModel<AuthDataModel>> = GenericDoc<
+  AuthDataModel,
+  T
+>;
+
+/** A pair of JWT access token and refresh token. */
+export type Tokens = { token: string; refreshToken: string };
+
+/** Session information returned after authentication. */
+export type SessionInfo = {
+  userId: GenericId<"User">;
+  sessionId: GenericId<"Session">;
+  tokens: Tokens | null;
+};
+
+/** Session information with guaranteed non-null tokens. */
+export type SessionInfoWithTokens = {
+  userId: GenericId<"User">;
+  sessionId: GenericId<"Session">;
+  tokens: Tokens;
+};
+
+// ---------------------------------------------------------------------------
+// Cross-component document shapes
+// ---------------------------------------------------------------------------
+// These mirror the component schema tables. They exist so that server-side
+// code can work with typed results from cross-component queries/mutations
+// instead of casting to `any` at every field access.
+
+export type TotpDoc = Infer<typeof vTotpFactorDoc>;
+
+export type PasskeyDoc = Infer<typeof vPasskeyDoc>;
+
+export type VerifierDoc = Infer<typeof vAuthVerifierDoc>;
+
+/**
+ * Cross-component user document shape inferred from the component validator.
+ *
+ * Used by internal typed wrappers (`queryUserById`, etc.) so server code stays
+ * aligned with the component runtime contract. Not intended for consumer use —
+ * consumers should use `UserDoc` (exported from
+ * `@robelest/convex-auth/component`).
+ *
+ * @internal
+ */
+export type CrossComponentUserDoc = Infer<typeof vUserDoc>;
+
+export type KeyDoc = Infer<typeof vApiKeyDoc>;
+
+// ---------------------------------------------------------------------------
+// Cross-component wrapper context
+// ---------------------------------------------------------------------------
+// Structural type accepted by all wrappers below.  Works for both action and
+// mutation contexts — the only capabilities we need are runQuery / runMutation
+// and access to the component API via `auth.config.component`.
+
+/** @internal */
+export type ComponentCallCtx = {
+  runQuery: GenericActionCtx<AuthDataModel>["runQuery"];
+  runMutation: GenericActionCtx<AuthDataModel>["runMutation"];
+  auth: { config: { component: AuthComponentApi } };
+};
+
+// ---------------------------------------------------------------------------
+// Typed wrappers for cross-component calls
+// ---------------------------------------------------------------------------
+// Each wrapper encapsulates the single `as any` cast at the component
+// boundary so that callers get full type safety on both args and return
+// values.
+
+// -- User queries --
+
+export async function queryUserById(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<CrossComponentUserDoc | null> {
+  return (await ctx.runQuery(ctx.auth.config.component.public.userGetById, {
+    userId,
+  })) as CrossComponentUserDoc | null;
+}
+
+export async function queryUserByVerifiedEmail(
+  ctx: ComponentCallCtx,
+  email: string,
+): Promise<CrossComponentUserDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.userFindByVerifiedEmail,
+    { email },
+  )) as CrossComponentUserDoc | null;
+}
+
+// -- Verifier queries / mutations --
+
+export async function queryVerifierById(
+  ctx: ComponentCallCtx,
+  verifierId: string,
+): Promise<VerifierDoc | null> {
+  return (await ctx.runQuery(ctx.auth.config.component.public.verifierGetById, {
+    verifierId,
+  })) as VerifierDoc | null;
+}
+
+export async function mutateVerifierDelete(
+  ctx: ComponentCallCtx,
+  verifierId: string,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.verifierDelete, {
+    verifierId,
+  });
+}
+
+// -- TOTP queries / mutations --
+
+export async function queryTotpById(
+  ctx: ComponentCallCtx,
+  totpId: string,
+): Promise<TotpDoc | null> {
+  return (await ctx.runQuery(ctx.auth.config.component.public.totpGetById, {
+    totpId,
+  })) as TotpDoc | null;
+}
+
+export async function queryTotpVerifiedByUserId(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<TotpDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.totpGetVerifiedByUserId,
+    { userId },
+  )) as TotpDoc | null;
+}
+
+export async function mutateTotpInsert(
+  ctx: ComponentCallCtx,
+  args: {
+    userId: string;
+    secret: ArrayBuffer;
+    digits: number;
+    period: number;
+    verified: boolean;
+    name?: string;
+    createdAt: number;
+  },
+): Promise<string> {
+  return (await ctx.runMutation(
+    ctx.auth.config.component.public.totpInsert,
+    args,
+  )) as string;
+}
+
+export async function mutateTotpMarkVerified(
+  ctx: ComponentCallCtx,
+  totpId: string,
+  lastUsedAt: number,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.totpMarkVerified, {
+    totpId,
+    lastUsedAt,
+  });
+}
+
+export async function mutateTotpUpdateLastUsed(
+  ctx: ComponentCallCtx,
+  totpId: string,
+  lastUsedAt: number,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.totpUpdateLastUsed, {
+    totpId,
+    lastUsedAt,
+  });
+}
+
+// -- Passkey queries / mutations --
+
+export async function queryPasskeysByUserId(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<PasskeyDoc[]> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.passkeyListByUserId,
+    { userId },
+  )) as PasskeyDoc[];
+}
+
+export async function queryPasskeyByCredentialId(
+  ctx: ComponentCallCtx,
+  credentialId: string,
+): Promise<PasskeyDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.passkeyGetByCredentialId,
+    { credentialId },
+  )) as PasskeyDoc | null;
+}
+
+export async function mutatePasskeyInsert(
+  ctx: ComponentCallCtx,
+  args: {
+    userId: string;
+    credentialId: string;
+    publicKey: ArrayBuffer | ArrayBufferLike;
+    algorithm: number;
+    counter: number;
+    transports?: string[];
+    deviceType: string;
+    backedUp: boolean;
+    name?: string;
+    createdAt: number;
+  },
+): Promise<string> {
+  return (await ctx.runMutation(
+    ctx.auth.config.component.public.passkeyInsert,
+    args,
+  )) as string;
+}
+
+export async function mutatePasskeyUpdateCounter(
+  ctx: ComponentCallCtx,
+  passkeyId: string,
+  counter: number,
+  lastUsedAt: number,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.passkeyUpdateCounter, {
+    passkeyId,
+    counter,
+    lastUsedAt,
+  });
+}
+
+// -- Key queries / mutations --
+
+export async function mutateKeyInsert(
+  ctx: ComponentCallCtx,
+  args: {
+    userId: string;
+    prefix: string;
+    hashedKey: string;
+    name: string;
+    scopes: Array<{ resource: string; actions: string[] }>;
+    rateLimit?: { maxRequests: number; windowMs: number };
+    expiresAt?: number;
+  },
+): Promise<string> {
+  return (await ctx.runMutation(
+    ctx.auth.config.component.public.keyInsert,
+    args,
+  )) as string;
+}
+
+export async function queryKeysByUserId(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<KeyDoc[]> {
+  const items: KeyDoc[] = [];
+  let cursor: string | null = null;
+  do {
+    const page = (await ctx.runQuery(ctx.auth.config.component.public.keyList, {
+      where: { userId },
+      limit: 100,
+      cursor,
+    })) as {
+      items: KeyDoc[];
+      nextCursor: string | null;
+    };
+    items.push(...page.items);
+    cursor = page.nextCursor;
+  } while (cursor !== null);
+  return items;
+}
+
+export async function queryKeyById(
+  ctx: ComponentCallCtx,
+  keyId: string,
+): Promise<KeyDoc | null> {
+  return (await ctx.runQuery(ctx.auth.config.component.public.keyGetById, {
+    keyId,
+  })) as KeyDoc | null;
+}
+
+export async function mutateKeyPatch(
+  ctx: ComponentCallCtx,
+  keyId: string,
+  data: Record<string, unknown>,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.keyPatch, {
+    keyId,
+    data,
+  });
+}
+
+export async function mutateKeyDelete(
+  ctx: ComponentCallCtx,
+  keyId: string,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.keyDelete, { keyId });
+}
+
+// -- Device authorization queries / mutations --
+
+export type DeviceDoc = Infer<typeof vDeviceCodeDoc>;
+
+export async function mutateDeviceInsert(
+  ctx: ComponentCallCtx,
+  args: {
+    deviceCodeHash: string;
+    userCode: string;
+    expiresAt: number;
+    interval: number;
+    status: "pending" | "authorized" | "denied";
+  },
+): Promise<string> {
+  return (await ctx.runMutation(
+    ctx.auth.config.component.public.deviceInsert,
+    args,
+  )) as string;
+}
+
+export async function queryDeviceByCodeHash(
+  ctx: ComponentCallCtx,
+  deviceCodeHash: string,
+): Promise<DeviceDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.deviceGetByCodeHash,
+    { deviceCodeHash },
+  )) as DeviceDoc | null;
+}
+
+export async function queryDeviceByUserCode(
+  ctx: ComponentCallCtx,
+  userCode: string,
+): Promise<DeviceDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.deviceGetByUserCode,
+    { userCode },
+  )) as DeviceDoc | null;
+}
+
+export async function mutateDeviceAuthorize(
+  ctx: ComponentCallCtx,
+  deviceId: string,
+  userId: string,
+  sessionId: string,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.deviceAuthorize, {
+    deviceId,
+    userId,
+    sessionId,
+  });
+}
+
+export async function mutateDeviceUpdateLastPolled(
+  ctx: ComponentCallCtx,
+  deviceId: string,
+  lastPolledAt: number,
+): Promise<void> {
+  await ctx.runMutation(
+    ctx.auth.config.component.public.deviceUpdateLastPolled,
+    { deviceId, lastPolledAt },
+  );
+}
+
+export async function mutateDeviceDelete(
+  ctx: ComponentCallCtx,
+  deviceId: string,
+): Promise<void> {
+  await ctx.runMutation(ctx.auth.config.component.public.deviceDelete, {
+    deviceId,
+  });
+}