@robelest/convex-auth 0.0.4-preview.13 → 0.0.4-preview.16

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

@@ -1,1264 +0,0 @@
-import { AuthProviderConfig, ConvexAuthConfig, CorsConfig, Doc, HttpKeyContext, KeyDoc, KeyScope, ScopeChecker, SessionInfo, UserOrderBy, UserWhere } from "./types.js";
-import * as convex_server23 from "convex/server";
-import { GenericActionCtx, GenericDataModel, HttpRouter } from "convex/server";
-import { GenericId } from "convex/values";
-
-//#region src/server/implementation.d.ts
-/**
- * Configure the Convex Auth library. Returns an object with
- * functions and `auth` helper. You must export the functions
- * from `convex/auth.ts` to make them callable:
- *
- * ```ts filename="convex/auth.ts"
- * import { createAuth } from "@robelest/convex-auth/component";
- * import { components } from "./_generated/api";
- *
- * export const auth = createAuth(components.auth, {
- *   providers: [],
- * });
- * export const { signIn, signOut, store } = auth;
- * ```
- *
- * @returns An object with fields you should reexport from your
- *          `convex/auth.ts` file.
- */
-declare function Auth(config_: ConvexAuthConfig): {
-  /**
-   * Helper for configuring HTTP actions.
-   */
-  auth: {
-    user: {
-      /**
-       * Get the current user's ID, or `null` if not signed in.
-       *
-       * Tries session JWT first. If `request` is provided, falls back to
-       * verifying an `Authorization: Bearer sk_...` API key header.
-       *
-       * @param ctx - Any Convex context with an `auth` field.
-       * @param request - Optional `Request`; enables API key fallback.
-       * @returns The user's ID string, or `null` when unauthenticated.
-       */
-      current: (ctx: {
-        auth: Auth;
-      } & Partial<Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">>, request?: Request) => Promise<string | null>;
-      /**
-       * Get the current user's ID, or throw `NOT_SIGNED_IN` if not signed in.
-       *
-       * Tries session JWT first. If `request` is provided, falls back to
-       * verifying an `Authorization: Bearer sk_...` API key header.
-       *
-       * @param ctx - Any Convex context with an `auth` field.
-       * @param request - Optional `Request`; enables API key fallback.
-       * @returns The user's ID string.
-       * @throws `ConvexError` with code `NOT_SIGNED_IN` when unauthenticated.
-       */
-      require: (ctx: {
-        auth: Auth;
-      } & Partial<Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">>, request?: Request) => Promise<string>;
-      /**
-       * Retrieve a user document by their ID.
-       *
-       * @param ctx - Convex context with `runQuery`.
-       * @param userId - The user document ID.
-       * @returns The user document, or `null` if not found.
-       */
-      get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, userId: string) => Promise<any>;
-      /**
-       * List users with optional filters, sorting, and pagination.
-       *
-       * @param opts.where - Optional filters (email, phone, name, anonymous).
-       * @param opts.limit - Max users to return (default 50).
-       * @param opts.cursor - Pagination cursor from a previous page.
-       * @param opts.orderBy - Sort field.
-       * @param opts.order - Sort direction.
-       * @returns `{ items, nextCursor }`.
-       */
-      list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts?: {
-        where?: UserWhere;
-        limit?: number;
-        cursor?: string | null;
-        orderBy?: UserOrderBy;
-        order?: "asc" | "desc";
-      }) => Promise<any>;
-      /**
-       * Get the currently signed-in user's document, or `null` if not
-       * signed in. Convenience combining `current()` + `get()`.
-       *
-       * @param ctx - Convex context with `auth` and `runQuery`.
-       * @returns The user document, or `null` when unauthenticated.
-       */
-      viewer: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery"> & {
-        auth: Auth;
-      }) => Promise<any>;
-      /**
-       * Update a user document with partial data.
-       *
-       * @param ctx - Convex context with `runMutation`.
-       * @param userId - The user document ID.
-       * @param data - Partial data to merge into the user document.
-       */
-      patch: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, userId: string, data: Record<string, unknown>) => Promise<void>;
-      /**
-       * Set or clear a user's active group in `user.extend.lastActiveGroup`.
-       *
-       * This helper preserves other keys under `user.extend`.
-       * Pass `groupId: null` to clear `lastActiveGroup`.
-       */
-      setActiveGroup: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, opts: {
-        userId: string;
-        groupId: string | null;
-      }) => Promise<void>;
-      /**
-       * Get the user's active group ID from `user.extend.lastActiveGroup`.
-       *
-       * @param ctx - Convex context with `runQuery`.
-       * @param opts.userId - The user document ID.
-       * @returns The active group ID, or `null` if none is set.
-       */
-      getActiveGroup: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-      }) => Promise<string | null>;
-      /**
-       * Delete a user and optionally cascade-delete all linked records.
-       *
-       * When `cascade` is `true` (default), this removes all sessions,
-       * accounts, API keys, group memberships, passkeys, and TOTP
-       * enrollments before deleting the user document itself.
-       *
-       * When `cascade` is `false`, the method throws if the user has any
-       * linked records — the caller must clean them up explicitly first.
-       *
-       * @param ctx - Convex action context with `runMutation` and `runQuery`.
-       * @param userId - The user document ID to delete.
-       * @param opts.cascade - Whether to cascade-delete linked records (default: `true`).
-       */
-      remove: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, userId: string, opts?: {
-        cascade?: boolean;
-      }) => Promise<void>;
-    };
-    session: {
-      /**
-       * Get the current session ID from the auth context, or `null` if
-       * not signed in.
-       *
-       * @param ctx - Any Convex context with an `auth` field.
-       * @returns The session's `Id<"Session">`, or `null` when unauthenticated.
-       */
-      current: (ctx: {
-        auth: Auth;
-      }) => Promise<GenericId<"Session"> | null>;
-      /**
-       * Invalidate sessions for a user, optionally preserving specific sessions.
-       *
-       * @param ctx - Convex action context.
-       * @param args.userId - The user whose sessions to invalidate.
-       * @param args.except - Session IDs to preserve (e.g. the current session).
-       */
-      invalidate: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
-        userId: GenericId<"User">;
-        except?: GenericId<"Session">[];
-      }) => Promise<void>;
-      /**
-       * Get a session by its document ID.
-       *
-       * @param ctx - Convex context with `runQuery`.
-       * @param sessionId - The session document ID.
-       * @returns The session document, or `null` if not found.
-       */
-      get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, sessionId: string) => Promise<any>;
-      /**
-       * List all active sessions for a user.
-       *
-       * @param ctx - Convex context with `runQuery`.
-       * @param opts.userId - The user whose sessions to list.
-       * @returns Array of session documents.
-       */
-      list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-      }) => Promise<any>;
-    };
-    account: {
-      /**
-       * Create an account and user for a credentials provider.
-       *
-       * @param ctx - Convex action context.
-       * @param args - Provider ID, account credentials, profile data, and link flags.
-       * @returns `{ account, user }` — the created account and user documents.
-       */
-      create: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
-        provider: string;
-        account: {
-          id: string;
-          secret?: string;
-        };
-        profile: Record<string, unknown>;
-        shouldLinkViaEmail?: boolean;
-        shouldLinkViaPhone?: boolean;
-      }) => Promise<{
-        account: Doc<"Account">;
-        user: Doc<"User">;
-      }>;
-      /**
-       * Retrieve an account and user for a credentials provider.
-       *
-       * @param ctx - Convex action context.
-       * @param args - Provider ID and account credentials (id, optional secret).
-       * @returns `{ account, user }` — the matched account and user documents.
-       * @throws `ConvexError` with code `ACCOUNT_NOT_FOUND` when no match exists.
-       */
-      get: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
-        provider: string;
-        account: {
-          id: string;
-          secret?: string;
-        };
-      }) => Promise<{
-        account: Doc<"Account">;
-        user: Doc<"User">;
-      }>;
-      /**
-       * Update account credentials (secret) for an existing account.
-       *
-       * @param ctx - Convex action context.
-       * @param args - Provider ID and new account credentials (id + secret).
-       */
-      update: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
-        provider: string;
-        account: {
-          id: string;
-          secret: string;
-        };
-      }) => Promise<void>;
-      /**
-       * Unlink (delete) an account from a user.
-       *
-       * Throws if the account is the user's only account and the user has
-       * no other way to sign in (prevents locking the user out).
-       *
-       * @param ctx - Convex context with `runQuery` and `runMutation`.
-       * @param accountId - The account document ID to unlink.
-       */
-      remove: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, accountId: string) => Promise<void>; /** List all passkeys for a user. */
-      listPasskeys: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-      }) => Promise<any>; /** Rename a passkey (set a user-friendly display name). */
-      renamePasskey: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, passkeyId: string, name: string) => Promise<void>; /** Delete a passkey credential. */
-      removePasskey: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, passkeyId: string) => Promise<void>; /** List all TOTP enrollments for a user. */
-      listTotps: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-      }) => Promise<any>; /** Delete a TOTP enrollment. */
-      removeTotp: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, totpId: string) => Promise<void>;
-    };
-    provider: {
-      /**
-       * Sign in via another provider, typically from a credentials flow.
-       *
-       * @param ctx - Convex action context.
-       * @param provider - The provider config to sign in with.
-       * @param args - Optional account ID and params.
-       * @returns `{ userId, sessionId }` on success, or `null`.
-       */
-      signIn: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, provider: AuthProviderConfig, args: {
-        accountId?: GenericId<"Account">;
-        params?: Record<string, unknown>;
-      }) => Promise<{
-        userId: GenericId<"User">;
-        sessionId: GenericId<"Session">;
-      } | null>;
-    };
-    /**
-     * Hierarchical group management. Groups can nest arbitrarily deep
-     * via `parentGroupId`. A root group has no parent.
-     *
-     * ```ts
-     * const groupId = await auth.group.create(ctx, { name: "Acme Corp" });
-     * const subGroupId = await auth.group.create(ctx, {
-     *   name: "Engineering",
-     *   parentGroupId: groupId,
-     * });
-     * ```
-     */
-    group: {
-      /**
-       * Create a new group. Omit `parentGroupId` for a root-level group,
-       * or provide it to create a nested group.
-       *
-       * @returns The ID of the newly created group.
-       */
-      create: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-        name: string;
-        slug?: string;
-        type?: string;
-        parentGroupId?: string;
-        tags?: Array<{
-          key: string;
-          value: string;
-        }>;
-        extend?: Record<string, unknown>;
-      }) => Promise<string>;
-      /**
-       * Retrieve a group by its ID. Returns `null` if not found.
-       */
-      get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, groupId: string) => Promise<any>;
-      /**
-       * List groups with optional filtering, sorting, and pagination.
-       *
-       * Empty `where` returns **all** groups.
-       *
-       * ```ts
-       * // All groups of type "team"
-       * await auth.group.list(ctx, { where: { type: "team" } });
-       *
-       * // Paginated
-       * const page1 = await auth.group.list(ctx, { limit: 10 });
-       * const page2 = await auth.group.list(ctx, { limit: 10, cursor: page1.nextCursor });
-       * ```
-       */
-      list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts?: {
-        where?: {
-          slug?: string;
-          type?: string;
-          parentGroupId?: string;
-          name?: string;
-          isRoot?: boolean;
-          tagsAll?: Array<{
-            key: string;
-            value: string;
-          }>;
-          tagsAny?: Array<{
-            key: string;
-            value: string;
-          }>;
-        };
-        limit?: number;
-        cursor?: string | null;
-        orderBy?: "_creationTime" | "name" | "slug" | "type";
-        order?: "asc" | "desc";
-      }) => Promise<any>;
-      /**
-       * Update a group's fields (name, slug, tags, extend, parentGroupId).
-       */
-      update: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, groupId: string, data: Record<string, unknown>) => Promise<void>;
-      /**
-       * Delete a group and cascade to all descendants. Deletes child groups
-       * (recursively), all members, and all invites for this group and its
-       * descendants.
-       */
-      delete: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, groupId: string) => Promise<void>;
-      /**
-       * Retrieve the ancestor chain for a group by walking `parentGroupId`
-       * upward toward the root.
-       *
-       * Useful for breadcrumbs, permission inheritance visualization, and
-       * operations that need the full hierarchy path.
-       *
-       * @param ctx - Convex context with `runQuery`.
-       * @param opts.groupId - The starting group.
-       * @param opts.maxDepth - Maximum traversal depth (default 32).
-       * @param opts.includeSelf - Include the starting group as the first
-       *   element (default `false`).
-       * @returns Ancestors ordered from immediate parent to root, plus
-       *   diagnostic flags.
-       */
-      ancestors: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        groupId: string;
-        maxDepth?: number;
-        includeSelf?: boolean;
-      }) => Promise<{
-        ancestors: any[];
-        cycleDetected: boolean;
-        maxDepthReached: boolean;
-      }>;
-    };
-    /**
-     * Manage group membership. A member links a user to a group with an
-     * application-defined role string (e.g. "owner", "admin", "member").
-     *
-     * The auth component stores roles but does not enforce access control.
-     * Your application defines what each role means.
-     */
-    member: {
-      /**
-       * Add a user as a member of a group.
-       *
-       * @param data.groupId - The group to add the member to.
-       * @param data.userId - The user to add.
-       * @param data.role - Application-defined role (e.g. "owner", "admin", "member").
-       * @param data.status - Optional membership status (e.g. "active", "suspended").
-       * @param data.extend - Optional arbitrary JSON extension data.
-       * @throws ConvexError with code `DUPLICATE_MEMBERSHIP` if the user is
-       * already a member of the target group.
-       * @returns The ID of the new member record.
-       */
-      add: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-        groupId: string;
-        userId: string;
-        role?: string;
-        status?: string;
-        extend?: Record<string, unknown>;
-      }) => Promise<string>;
-      /**
-       * Retrieve a member record by its ID. Returns `null` if not found.
-       */
-      get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, memberId: string) => Promise<any>;
-      /**
-       * Look up a user's membership in a specific group.
-       */
-      getByUserAndGroup: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-        groupId: string;
-      }) => Promise<any>;
-      /**
-       * List members with optional filtering, sorting, and pagination.
-       *
-       * ```ts
-       * // All members of a group
-       * await auth.member.list(ctx, { where: { groupId } });
-       *
-       * // Admins only
-       * await auth.member.list(ctx, { where: { groupId, role: "admin" } });
-       * ```
-       */
-      list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts?: {
-        where?: {
-          groupId?: string;
-          userId?: string;
-          role?: string;
-          status?: string;
-        };
-        limit?: number;
-        cursor?: string | null;
-        orderBy?: "_creationTime" | "role" | "status";
-        order?: "asc" | "desc";
-      }) => Promise<any>;
-      /**
-       * Remove a member from a group by deleting the member record.
-       */
-      remove: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, memberId: string) => Promise<void>;
-      /**
-       * Update a member's fields (role, status, extend).
-       */
-      update: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, memberId: string, data: Record<string, unknown>) => Promise<void>;
-      /**
-       * Resolve membership for a group, including inherited membership
-       * from ancestor groups (`parentGroupId` chain).
-       *
-       * Returns direct membership when found on `opts.groupId`, otherwise
-       * returns the nearest ancestor membership. Use `roles` to only match
-       * specific roles (for example `admin`/`lead`).
-       */
-      inherit: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-        groupId: string;
-        roles?: string[];
-        maxDepth?: number;
-      }) => Promise<{
-        requestedGroupId: string;
-        matchedGroupId: string;
-        membership: any;
-        depth: number;
-        isDirect: boolean;
-        isInherited: boolean;
-        traversedGroupIds: string[];
-        cycleDetected: boolean;
-        maxDepthReached: boolean;
-      } | {
-        requestedGroupId: string;
-        matchedGroupId: null;
-        membership: null;
-        depth: null;
-        isDirect: boolean;
-        isInherited: boolean;
-        traversedGroupIds: string[];
-        cycleDetected: boolean;
-        maxDepthReached: boolean;
-      }>;
-      /**
-       * Require membership on a group, checking inherited membership
-       * from ancestor groups when no direct membership exists.
-       *
-       * Throws `FORBIDDEN` if no matching membership is found.
-       */
-      require: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-        groupId: string;
-        roles?: string[];
-        maxDepth?: number;
-      }) => Promise<{
-        membership: any;
-        matchedGroupId: string | null;
-        isDirect: boolean;
-        isInherited: boolean;
-        depth: number | null;
-      }>;
-    };
-    /**
-     * Manage platform-level invitations.
-     *
-     * Invites can optionally target a group by setting `groupId`, but they do
-     * not require groups and can be used in apps with user-only collaboration.
-     */
-    invite: {
-      /**
-       * Create a new invitation.
-       *
-       * @param data.groupId - Optional group to invite the user into.
-       * @param data.invitedByUserId - Optional user sending the invitation
-       *   (omit for CLI-generated invites).
-       * @param data.email - Optional email of the invitee (omit for
-       *   CLI-generated invite links where the email is unknown upfront).
-       * @param data.role - Optional role to assign on acceptance.
-       * @param data.expiresTime - Optional expiration timestamp (omit for
-       *   single-use, non-expiring invites).
-       * @param data.extend - Optional arbitrary JSON extension data.
-       * @throws ConvexError with code `DUPLICATE_INVITE` if a pending invite
-       * already exists for this email and scope.
-       * @returns An object with `inviteId` and raw `token`.
-       */
-      create: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-        groupId?: string;
-        invitedByUserId?: string;
-        email?: string;
-        role?: string;
-        expiresTime?: number;
-        extend?: Record<string, unknown>;
-      }) => Promise<{
-        inviteId: string;
-        token: string;
-      }>;
-      /**
-       * Retrieve an invite by its ID. Returns `null` if not found.
-       */
-      get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, inviteId: string) => Promise<any>;
-      /**
-       * Token-based invite helpers.
-       */
-      token: {
-        /**
-         * Retrieve an invite by raw token.
-         */
-        get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, token: string) => Promise<any>;
-        /**
-         * Accept an invitation by raw token and atomically add group membership
-         * when the invite is group-scoped.
-         */
-        accept: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, args: {
-          token: string;
-          acceptedByUserId: string;
-        }) => Promise<any>;
-      };
-      /**
-       * List invites with optional filtering, sorting, and pagination.
-       *
-       * ```ts
-       * // Pending invites for a group
-       * await auth.invite.list(ctx, { where: { groupId, status: "pending" } });
-       * ```
-       */
-      list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts?: {
-        where?: {
-          tokenHash?: string;
-          groupId?: string;
-          status?: "pending" | "accepted" | "revoked" | "expired";
-          email?: string;
-          invitedByUserId?: string;
-          role?: string;
-          acceptedByUserId?: string;
-        };
-        limit?: number;
-        cursor?: string | null;
-        orderBy?: "_creationTime" | "status" | "email" | "expiresTime" | "acceptedTime";
-        order?: "asc" | "desc";
-      }) => Promise<any>;
-      /**
-       * Accept an invitation. Marks the invite as "accepted" and records
-       * the timestamp. If the invite has a group, the caller is responsible
-       * for creating the member record via `auth.member.add` in the
-       * same Convex mutation for transactional safety.
-       *
-       * @param ctx - Convex context with `runMutation`.
-       * @param inviteId - The invite document ID.
-       * @param acceptedByUserId - User accepting the invite (recorded for audit).
-       * @throws `ConvexError` with code `INVITE_NOT_FOUND` when the invite does not exist.
-       * @throws `ConvexError` with code `INVITE_NOT_PENDING` when the invite is not in `pending` status.
-       *
-       * @example
-       * ```ts
-       * export const acceptInvite = mutation({
-       *   args: { inviteId: v.string() },
-       *   handler: async (ctx, { inviteId }) => {
-       *     const userId = await auth.user.require(ctx);
-       *     const invite = await auth.invite.get(ctx, inviteId);
-       *     if (!invite) throw new Error("Invite not found");
-       *
-       *     await auth.invite.accept(ctx, inviteId);
-       *     if (invite.groupId) {
-       *       await auth.member.add(ctx, {
-       *         groupId: invite.groupId,
-       *         userId,
-       *         role: invite.role,
-       *       });
-       *     }
-       *   },
-       * });
-       * ```
-       */
-      accept: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, inviteId: string, acceptedByUserId?: string) => Promise<void>;
-      /**
-       * Revoke a pending invitation.
-       *
-       * @param ctx - Convex context with `runMutation`.
-       * @param inviteId - The invite document ID.
-       * @throws `ConvexError` with code `INVITE_NOT_FOUND` when the invite does not exist.
-       * @throws `ConvexError` with code `INVITE_NOT_PENDING` when the invite is not in `pending` status.
-       */
-      revoke: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, inviteId: string) => Promise<void>;
-    };
-    /**
-     * Manage passkey credentials for users.
-     *
-     * ```ts
-     * const passkeys = await auth.passkey.list(ctx, { userId });
-     * await auth.passkey.rename(ctx, passkeyId, "MacBook Touch ID");
-    /**
-     * Manage API keys for programmatic access.
-     *
-     * Keys use SHA-256 hashing (via `@oslojs/crypto`) and support
-     * scoped resource:action permissions with optional per-key rate limiting.
-     *
-     * ```ts
-     * const { keyId, raw } = await auth.key.create(ctx, {
-     *   userId,
-     *   name: "CI Pipeline",
-     *   scopes: [{ resource: "data", actions: ["read"] }],
-     * });
-     * // raw = "sk_abc123..." — show once, never stored
-     *
-     * const result = await auth.key.verify(ctx, rawKey);
-     * result.scopes.can("data", "read"); // true
-     * ```
-     */
-    key: {
-      /**
-       * Create a new API key. Returns the raw key **once** — it cannot
-       * be retrieved again after creation.
-       *
-       * @param opts.userId - The user this key belongs to.
-       * @param opts.name - Human-readable name (e.g. "CI Pipeline").
-       * @param opts.scopes - Resource:action permissions for this key.
-       * @param opts.rateLimit - Optional per-key rate limit override.
-       * @param opts.expiresAt - Optional expiration timestamp.
-       * @param opts.metadata - Optional arbitrary app data attached to the key.
-       * @returns `{ keyId, raw }` where `raw` is the full key string.
-       */
-      create: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, opts: {
-        userId: string;
-        name: string;
-        scopes: KeyScope[];
-        rateLimit?: {
-          maxRequests: number;
-          windowMs: number;
-        };
-        expiresAt?: number;
-        metadata?: Record<string, unknown>;
-      }) => Promise<{
-        keyId: string;
-        raw: string;
-      }>;
-      /**
-       * Verify a raw API key string. Returns the userId and a scope checker
-       * if the key is valid, not revoked, not expired, and not rate-limited.
-       *
-       * Also updates `lastUsedAt` and rate limit state as a side effect.
-       *
-       * @throws Error if the key is invalid, revoked, expired, or rate-limited.
-       */
-      verify: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, rawKey: string) => Promise<{
-        userId: string;
-        keyId: string;
-        scopes: ScopeChecker;
-      }>;
-      /**
-       * List API keys with optional filtering, sorting, and pagination.
-       * Never includes the raw key — only the display prefix.
-       *
-       * ```ts
-       * // All keys for a user
-       * await auth.key.list(ctx, { where: { userId } });
-       *
-       * // Only active (non-revoked)
-       * await auth.key.list(ctx, { where: { userId, revoked: false } });
-       * ```
-       */
-      list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts?: {
-        where?: {
-          userId?: string;
-          revoked?: boolean;
-          name?: string;
-          prefix?: string;
-        };
-        limit?: number;
-        cursor?: string | null;
-        orderBy?: "_creationTime" | "name" | "lastUsedAt" | "expiresAt" | "revoked";
-        order?: "asc" | "desc";
-      }) => Promise<any>;
-      /**
-       * Get a single API key by its document ID.
-       * Returns `null` if not found.
-       */
-      get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, keyId: string) => Promise<KeyDoc | null>;
-      /**
-       * Update an API key's metadata (name, scopes, rate limit).
-       */
-      update: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, keyId: string, data: {
-        name?: string;
-        scopes?: KeyScope[];
-        rateLimit?: {
-          maxRequests: number;
-          windowMs: number;
-        };
-      }) => Promise<void>;
-      /**
-       * Revoke an API key (soft delete). The key record is preserved
-       * for audit purposes but can no longer be used for authentication.
-       */
-      revoke: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, keyId: string) => Promise<void>;
-      /**
-       * Hard delete an API key record.
-       */
-      remove: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, keyId: string) => Promise<void>;
-      /**
-       * Rotate an API key — revoke the old key and issue a replacement with
-       * the same `userId`, `name`, `scopes`, and `rateLimit`.
-       *
-       * The old key is soft-revoked immediately; the replacement is a brand
-       * new key with a new raw value. Returns the new `keyId` and `raw` key
-       * (shown once, same as `auth.key.create`).
-       *
-       * @throws If the key does not exist or is already revoked.
-       *
-       * @example
-       * ```ts
-       * const { keyId, raw } = await auth.key.rotate(ctx, oldKeyId);
-       * // raw = "sk_abc..." — new key to hand to the caller
-       * // old key is now revoked and verify() will throw API_KEY_REVOKED
-       * ```
-       */
-      rotate: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, keyId: string, opts?: {
-        name?: string;
-        expiresAt?: number;
-      }) => Promise<{
-        keyId: string;
-        raw: string;
-      }>;
-    };
-    /**
-     * SSO namespace — enterprise SSO connection management, domain, OIDC,
-     * SAML, SCIM, audit, and webhook helpers.
-     */
-    sso: {
-      connection: {
-        create: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-          groupId: string;
-          slug?: string;
-          name?: string;
-          status?: "draft" | "active" | "disabled";
-          config?: Record<string, unknown>;
-          extend?: Record<string, unknown>;
-        }) => Promise<string>;
-        get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<any>;
-        getByGroup: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, groupId: string) => Promise<any>;
-        getByDomain: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, domain: string) => Promise<any>;
-        list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, opts?: {
-          where?: {
-            groupId?: string;
-            slug?: string;
-            status?: "draft" | "active" | "disabled";
-          };
-          limit?: number;
-          cursor?: string | null;
-          orderBy?: "_creationTime" | "name" | "slug" | "status";
-          order?: "asc" | "desc";
-        }) => Promise<any>;
-        update: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, enterpriseId: string, data: Record<string, unknown>) => Promise<void>;
-        remove: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, enterpriseId: string) => Promise<void>;
-        /**
-         * Aggregate readiness status across all configured protocols for an
-         * enterprise connection.
-         *
-         * Returns a structured result indicating whether the connection is
-         * ready, with per-protocol checks so callers can surface actionable
-         * diagnostics without running full network validation.
-         */
-        status: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<{
-          enterpriseId: any;
-          status: any;
-          ready: boolean;
-          domainCount: number;
-          protocols: {
-            oidc: {
-              configured: boolean;
-              ready: boolean;
-              clientId: any;
-              issuer: any;
-            };
-            saml: {
-              configured: boolean;
-              ready: boolean;
-              entityId: any;
-            };
-            scim: {
-              configured: boolean;
-              ready: boolean;
-              basePath: any;
-              deprovisionMode: any;
-            };
-          };
-        }>;
-      };
-      domain: {
-        add: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-          enterpriseId: string;
-          groupId: string;
-          domain: string;
-          isPrimary?: boolean;
-          verifiedAt?: number;
-        }) => Promise<string>;
-        list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<any>;
-        remove: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, domainId: string) => Promise<void>;
-      };
-      saml: {
-        configure: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, data: {
-          enterpriseId: string;
-          metadataXml?: string;
-          metadataUrl?: string;
-          domains?: string[];
-          signAuthnRequests?: boolean;
-          attributeMapping?: {
-            subject?: string;
-            email?: string;
-            name?: string;
-            firstName?: string;
-            lastName?: string;
-          };
-          sp?: {
-            entityId?: string;
-            acsUrl?: string;
-            sloUrl?: string;
-            signingCert?: string | string[];
-            encryptCert?: string | string[];
-            privateKey?: string;
-            privateKeyPass?: string;
-            encPrivateKey?: string;
-            encPrivateKeyPass?: string;
-          };
-        }) => Promise<{
-          enterpriseId: any;
-          groupId: any;
-        }>;
-        metadata: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, opts: {
-          enterpriseId: string;
-          entityId?: string;
-          acsUrl?: string;
-          sloUrl?: string;
-        }) => Promise<any>;
-        /**
-         * Validate the stored SAML config for an enterprise connection.
-         *
-         * Re-parses IdP metadata, checks signing cert presence, and verifies
-         * SP metadata can be generated. Returns a structured result with
-         * per-check details rather than throwing on first failure.
-         */
-        validate: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, enterpriseId: string) => Promise<{
-          ok: boolean;
-          enterpriseId: any;
-          checks: {
-            name: string;
-            ok: boolean;
-            message?: string;
-          }[];
-        }>;
-      };
-      oidc: {
-        /**
-         * Register or update enterprise OIDC connection settings.
-         *
-         * Persists protocol config under `enterprise.config.protocols.oidc` and
-         * records an `enterprise.oidc.registered` audit event.
-         */
-        configure: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-          enterpriseId: string;
-          issuer?: string;
-          discoveryUrl?: string;
-          clientId: string;
-          clientSecret?: string;
-          scopes?: string[];
-          authorizationParams?: Record<string, string>;
-          clockToleranceSeconds?: number;
-          strictIssuer?: boolean;
-          /**
-           * Map OIDC claim names to `user.extend` field names.
-           * Example: `{ department: "department", role: "job_title" }` means
-           * the OIDC `department` claim is stored as `user.extend.department`.
-           */
-          extraFields?: Record<string, string>;
-        }) => Promise<Record<string, any>>;
-        /**
-         * Fetch the stored OIDC config for an enterprise.
-         */
-        get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<Record<string, any>>;
-        /**
-         * Resolve enterprise OIDC sign-in route from enterprise id, domain, or
-         * user email domain.
-         */
-        resolveSignIn: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, data: {
-          enterpriseId?: string;
-          email?: string;
-          domain?: string;
-          redirectTo?: string;
-        }) => Promise<{
-          enterpriseId: any;
-          providerId: string;
-          signInPath: string;
-          callbackPath: string;
-          redirectTo: string | undefined;
-        }>;
-        /**
-         * Validate the stored OIDC config for an enterprise connection.
-         *
-         * Fetches the OIDC discovery document from the configured issuer or
-         * discoveryUrl, verifies required fields are present, and checks that
-         * clientId is set. Returns a structured result with per-check details.
-         */
-        validate: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<{
-          ok: boolean;
-          enterpriseId: any;
-          checks: {
-            name: string;
-            ok: boolean;
-            message?: string;
-          }[];
-        }>;
-      };
-      scim: {
-        configure: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-          enterpriseId: string;
-          basePath?: string;
-          deprovisionMode?: "soft" | "hard";
-          status?: "draft" | "active" | "disabled";
-        }) => Promise<{
-          token: string;
-          configId: string;
-        }>;
-        get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<any>;
-        getConfigByToken: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, token: string) => Promise<any>;
-        /**
-         * Validate the stored SCIM config for an enterprise connection.
-         *
-         * Checks that a SCIM config record exists, is active, has a token
-         * hash set, and has a non-empty basePath. Returns a structured result
-         * with per-check details.
-         */
-        validate: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<{
-          ok: boolean;
-          enterpriseId: string;
-          checks: {
-            name: string;
-            ok: boolean;
-            message: string;
-          }[];
-          basePath?: undefined;
-          deprovisionMode?: undefined;
-        } | {
-          ok: boolean;
-          enterpriseId: any;
-          basePath: any;
-          deprovisionMode: any;
-          checks: {
-            name: string;
-            ok: boolean;
-            message?: string;
-          }[];
-        }>;
-        identity: {
-          get: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, data: {
-            enterpriseId: string;
-            resourceType: "user" | "group";
-            externalId: string;
-          }) => Promise<any>;
-          upsert: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-            enterpriseId: string;
-            groupId: string;
-            resourceType: "user" | "group";
-            externalId: string;
-            userId?: string;
-            mappedGroupId?: string;
-            active?: boolean;
-            raw?: Record<string, unknown>;
-          }) => Promise<string>;
-        };
-      };
-      audit: {
-        record: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-          enterpriseId: string;
-          groupId: string;
-          eventType: string;
-          actorType: "user" | "system" | "scim" | "api_key" | "webhook";
-          actorId?: string;
-          subjectType: string;
-          subjectId?: string;
-          ok: boolean;
-          requestId?: string;
-          ip?: string;
-          metadata?: Record<string, unknown>;
-        }) => Promise<string>;
-        list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, data: {
-          enterpriseId?: string;
-          groupId?: string;
-          limit?: number;
-        }) => Promise<any>;
-      };
-      webhook: {
-        endpoint: {
-          create: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-            enterpriseId: string;
-            url: string;
-            secret: string;
-            subscriptions: string[];
-            createdByUserId?: string;
-          }) => Promise<{
-            endpointId: string;
-          }>;
-          list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, enterpriseId: string) => Promise<any>;
-          disable: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, endpointId: string) => Promise<void>;
-        };
-        emit: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, data: {
-          enterpriseId: string;
-          eventType: string;
-          payload: Record<string, unknown>;
-          auditEventId?: string;
-        }) => Promise<void>;
-        delivery: {
-          list: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, data: {
-            enterpriseId: string;
-            limit?: number;
-          }) => Promise<any>;
-          listReady: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery">, limit?: number) => Promise<any>;
-          markDelivered: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, deliveryId: string, responseStatus?: number) => Promise<void>;
-          markFailed: (ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">, deliveryId: string, data: {
-            attemptCount: number;
-            responseStatus?: number;
-            error?: string;
-            retryAt?: number;
-          }) => Promise<void>;
-        };
-      };
-    };
-    /**
-     * HTTP namespace — route registration and Bearer-authenticated endpoints.
-     */
-    http: {
-      /**
-       * Register core HTTP routes for JWT verification and OAuth sign-in.
-       *
-       * ```ts
-       * import { httpRouter } from "convex/server";
-       * import { auth } from "./auth";
-       *
-       * const http = httpRouter();
-       *
-       * auth.http.add(http);
-       *
-       * export default http;
-       * ```
-       *
-       * The following routes are handled always:
-       *
-       * - `/.well-known/openid-configuration`
-       * - `/.well-known/jwks.json`
-       *
-       * The following routes are handled if OAuth is configured:
-       *
-       * - `/api/auth/signin/*`
-       * - `/api/auth/callback/*`
-       *
-       * @param http your HTTP router
-       */
-      add: (http: HttpRouter) => void;
-      /**
-       * Wrap an HTTP action handler with Bearer token authentication.
-       *
-       * Extracts the `Authorization: Bearer <key>` header, verifies the
-       * API key via `auth.key.verify()`, and injects `ctx.key` with the
-       * verified key info. Returns structured JSON error responses for
-       * missing/invalid/revoked/expired/rate-limited keys.
-       *
-       * If the handler returns a plain object, it is auto-wrapped in a
-       * `200 JSON` response. If it returns a `Response`, CORS headers
-       * are merged and the response is passed through.
-       *
-       * ```ts
-       * const handler = auth.http.action(async (ctx, request) => {
-       *   const data = await ctx.runQuery(api.data.get, { userId: ctx.key.userId });
-       *   return { data };
-       * });
-       * http.route({ path: "/api/data", method: "GET", handler });
-       * ```
-       *
-       * @param handler - Receives enriched `ctx` (with `ctx.key`) and the raw `Request`.
-       * @param options.scope - Optional scope check; returns 403 if the key lacks permission.
-       * @param options.cors - CORS config; defaults to permissive (`*`).
-       */
-      action: (handler: (ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext, request: Request) => Promise<Response | Record<string, unknown>>, options?: {
-        scope?: {
-          resource: string;
-          action: string;
-        };
-        cors?: CorsConfig;
-      }) => convex_server23.PublicHttpAction;
-      /**
-       * Register a Bearer-authenticated route **and** its OPTIONS preflight
-       * in a single call.
-       *
-       * ```ts
-       * auth.http.route(http, {
-       *   path: "/api/messages",
-       *   method: "POST",
-       *   handler: async (ctx, request) => {
-       *     const { body } = await request.json();
-       *     await ctx.runMutation(internal.messages.sendAsUser, {
-       *       userId: ctx.key.userId,
-       *       body,
-       *     });
-       *     return { success: true };
-       *   },
-       * });
-       * ```
-       *
-       * @param http - The Convex HTTP router.
-       * @param routeConfig.path - The URL path to match.
-       * @param routeConfig.method - HTTP method (GET, POST, PUT, PATCH, DELETE).
-       * @param routeConfig.handler - Receives enriched `ctx` (with `ctx.key`) and the raw `Request`.
-       * @param routeConfig.scope - Optional scope check; returns 403 if the key lacks permission.
-       * @param routeConfig.cors - CORS config; defaults to permissive (`*`).
-       */
-      route: (http: HttpRouter, routeConfig: {
-        path: string;
-        method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-        handler: (ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext, request: Request) => Promise<Response | Record<string, unknown>>;
-        scope?: {
-          resource: string;
-          action: string;
-        };
-        cors?: CorsConfig;
-      }) => void;
-    };
-  };
-  /**
-   * Action called by the client to sign the user in.
-   *
-   * Also used for refreshing the session.
-   */
-  signIn: convex_server23.RegisteredAction<"public", {
-    provider?: string | undefined;
-    verifier?: string | undefined;
-    params?: any;
-    refreshToken?: string | undefined;
-    calledBy?: string | undefined;
-  }, Promise<SignInActionResult>>;
-  /**
-   * Action called by the client to invalidate the current session.
-   */
-  signOut: convex_server23.RegisteredAction<"public", {}, Promise<void>>;
-  /**
-   * Internal mutation used by the library to read and write
-   * to the database during signin and signout.
-   */
-  store: convex_server23.RegisteredMutation<"internal", {
-    args: {
-      sessionId?: string | undefined;
-      type: "signIn";
-      userId: string;
-      generateTokens: boolean;
-    } | {
-      type: "signOut";
-    } | {
-      type: "refreshSession";
-      refreshToken: string;
-    } | {
-      provider?: string | undefined;
-      verifier?: string | undefined;
-      type: "verifyCodeAndSignIn";
-      params: any;
-      generateTokens: boolean;
-      allowExtraProviders: boolean;
-    } | {
-      type: "verifier";
-    } | {
-      type: "verifierSignature";
-      verifier: string;
-      signature: string;
-    } | {
-      accountExtend?: any;
-      type: "userOAuth";
-      provider: string;
-      providerAccountId: string;
-      signature: string;
-      profile: any;
-    } | {
-      email?: string | undefined;
-      phone?: string | undefined;
-      accountId?: string | undefined;
-      type: "createVerificationCode";
-      expirationTime: number;
-      provider: string;
-      code: string;
-      allowExtraProviders: boolean;
-    } | {
-      shouldLinkViaEmail?: boolean | undefined;
-      shouldLinkViaPhone?: boolean | undefined;
-      type: "createAccountFromCredentials";
-      provider: string;
-      profile: any;
-      account: {
-        secret?: string | undefined;
-        id: string;
-      };
-    } | {
-      type: "retrieveAccountWithCredentials";
-      provider: string;
-      account: {
-        secret?: string | undefined;
-        id: string;
-      };
-    } | {
-      type: "modifyAccount";
-      provider: string;
-      account: {
-        id: string;
-        secret: string;
-      };
-    } | {
-      except?: string[] | undefined;
-      type: "invalidateSessions";
-      userId: string;
-    };
-  }, Promise<string | void | {
-    userId: GenericId<"User">;
-    sessionId: GenericId<"Session">;
-  } | (string & {
-    __tableName: "AuthVerifier";
-  }) | SessionInfo | {
-    token: string;
-    refreshToken: string;
-  } | {
-    account: Doc<"Account">;
-    user: Doc<"User">;
-  } | {
-    account: Doc<"Account">;
-    user: Doc<"User">;
-  } | null>>;
-};
-//#endregion
-export { Auth };
-//# sourceMappingURL=implementation.d.ts.map