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

package/dist/server/core.d.ts

@@ -0,0 +1,1436 @@
+import { AuthProviderConfig, KeyDoc, KeyScope, ScopeChecker, UserOrderBy, UserWhere } from "./types.js";
+import { Auth, GenericActionCtx, GenericDataModel } from "convex/server";
+import { GenericId } from "convex/values";
+
+//#region src/server/core.d.ts
+type ComponentCtx = Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">;
+type ComponentReadCtx = Pick<GenericActionCtx<GenericDataModel>, "runQuery">;
+type ComponentAuthReadCtx = ComponentReadCtx & {
+  auth: Auth;
+};
+type AccountCredentials = {
+  id: string;
+  secret?: string;
+};
+type CreateAccountArgs = {
+  provider: string;
+  account: AccountCredentials;
+  profile: Record<string, unknown>;
+  shouldLinkViaEmail?: boolean;
+  shouldLinkViaPhone?: boolean;
+};
+type RetrieveAccountArgs = {
+  provider: string;
+  account: AccountCredentials;
+};
+type UpdateAccountCredentialsArgs = {
+  provider: string;
+  account: {
+    id: string;
+    secret: string;
+  };
+};
+type CoreDeps = {
+  config: any;
+  getAuth: () => any;
+  callInvalidateSessions: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
+    userId: GenericId<"User">;
+    except?: GenericId<"Session">[];
+  }) => Promise<void>;
+  callCreateAccountFromCredentials: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: CreateAccountArgs) => Promise<any>;
+  callRetrieveAccountWithCredentials: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: RetrieveAccountArgs) => Promise<any>;
+  callModifyAccount: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: UpdateAccountCredentialsArgs) => Promise<void>;
+  getEnrichCtx: () => <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>) => any;
+  inviteTokenAlphabet: string;
+  inviteTokenLength: number;
+};
+/**
+ * Build the core auth domains that back the canonical app API surface.
+ *
+ * Creates the grouped `user`, `session`, `account`, `provider`, `group`,
+ * `member`, `invite`, and `key` APIs used by the higher-level auth
+ * factory. Each namespace wraps the underlying Convex component functions with
+ * application-friendly helpers, result shaping, and documentation-friendly
+ * method names.
+ *
+ * @param deps - Internal component wiring, provider config, and helper
+ *   functions needed to construct the domain API surface.
+ * @returns The core domain namespaces consumed by the auth factory.
+ */
+declare function createCoreDomains(deps: CoreDeps): {
+  user: {
+    /**
+     * Resolve the current user's ID.
+     *
+     * Checks two sources in order:
+     *
+     * 1. **Session JWT** — extracts the `userId` from `ctx.auth.getUserIdentity()`.
+     *    This is the standard path for browser sessions and costs zero DB reads.
+     * 2. **API key** — if a `request` is provided and contains a
+     *    `Bearer sk_*` Authorization header, the key is verified against the
+     *    database and the owning `userId` is returned.
+     *
+     * Returns `null` when neither source produces a valid identity.
+     *
+     * @param ctx - Convex query, mutation, or action context.
+     * @param request - Optional incoming `Request` to check for API key auth.
+     *   Only needed in HTTP actions or server-side handlers.
+     * @returns The user's document ID, or `null` if unauthenticated.
+     *
+     * @example Session auth (queries, mutations)
+     * ```ts
+     * const userId = await auth.user.id(ctx);
+     * if (!userId) return { ok: false, code: "NOT_SIGNED_IN" };
+     * ```
+     *
+     * @example API key auth (HTTP actions)
+     * ```ts
+     * const userId = await auth.user.id(ctx, request);
+     * ```
+     */
+    id: (ctx: {
+      auth: Auth;
+    } & Partial<ComponentCtx>, request?: Request) => Promise<string | null>;
+    /**
+     * Fetch a user document by ID.
+     *
+     * Results are **cached per-execution** — calling `auth.user.get(ctx, id)`
+     * multiple times within the same query or mutation handler for the same
+     * `userId` returns the cached result without an additional component read.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param userId - The user's document ID.
+     * @returns The user document, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const user = await auth.user.get(ctx, userId);
+     * const name = user?.name ?? user?.email ?? "Unknown";
+     * ```
+     */
+    get: (ctx: ComponentReadCtx, userId: string) => Promise<any>;
+    /**
+     * List users with optional filtering, pagination, and ordering.
+     *
+     * Supports filtering by `email`, `phone`, `name`, and `isAnonymous`.
+     * Results are paginated — pass `cursor` from a previous response to
+     * load the next page.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.where - Filter criteria (all optional, combined with AND).
+     * @param opts.limit - Max items per page (default 50, max 100).
+     * @param opts.cursor - Cursor from a previous `nextCursor` for pagination.
+     * @param opts.orderBy - Sort field: `"_creationTime"` (default), `"email"`, etc.
+     * @param opts.order - Sort direction: `"asc"` or `"desc"` (default `"desc"`).
+     * @returns `{ items, nextCursor }` — `nextCursor` is `null` when no more pages.
+     *
+     * @example
+     * ```ts
+     * const { items, nextCursor } = await auth.user.list(ctx, {
+     *   where: { email: "alice@example.com" },
+     *   limit: 10,
+     * });
+     * ```
+     */
+    list: (ctx: ComponentReadCtx, opts?: {
+      where?: UserWhere;
+      limit?: number;
+      cursor?: string | null;
+      orderBy?: UserOrderBy;
+      order?: "asc" | "desc";
+    }) => Promise<any>;
+    /**
+     * Convenience method: resolve the current user ID from the session
+     * and fetch their full document in one call. Returns `null` if
+     * unauthenticated. Equivalent to `auth.user.id(ctx)` then `auth.user.get(ctx, id)`.
+     *
+     * @param ctx - Convex query or mutation context with `auth` for session lookup.
+     * @returns The authenticated user's document, or `null` if unauthenticated.
+     *
+     * @example
+     * ```ts
+     * const viewer = await auth.user.viewer(ctx);
+     * if (!viewer) throw new Error("Not signed in");
+     * console.log(viewer.name, viewer.email);
+     * ```
+     */
+    viewer: (ctx: ComponentAuthReadCtx) => Promise<any>;
+    /**
+     * Patch a user document. Accepts any fields defined on the User schema
+     * (e.g. `name`, `image`, `email`, `extend`).
+     *
+     * @param ctx - Convex mutation context.
+     * @param userId - The user's document ID.
+     * @param data - Fields to merge into the user document.
+     * @returns `{ ok: true, userId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.user.update(ctx, userId, {
+     *   name: "Alice Smith",
+     *   image: "https://example.com/avatar.png",
+     * });
+     * ```
+     */
+    update: (ctx: ComponentCtx, userId: string, data: Record<string, unknown>) => Promise<{
+      ok: true;
+      userId: string;
+    }>;
+    /**
+     * Set the user's active group. Stored in `user.extend.lastActiveGroup`.
+     * Pass `groupId: null` to clear. Useful for multi-workspace apps
+     * where the UI needs to remember which workspace is selected.
+     *
+     * @param ctx - Convex mutation context.
+     * @param opts.userId - The user's document ID.
+     * @param opts.groupId - Group ID to set as active, or `null` to clear.
+     * @returns `{ ok: true, userId, groupId }` confirming the active group was set (or cleared).
+     *
+     * @example
+     * ```ts
+     * // Switch to a workspace
+     * await auth.user.setActiveGroup(ctx, { userId, groupId: workspaceId });
+     *
+     * // Clear the active workspace
+     * await auth.user.setActiveGroup(ctx, { userId, groupId: null });
+     * ```
+     */
+    setActiveGroup: (ctx: ComponentCtx, opts: {
+      userId: string;
+      groupId: string | null;
+    }) => Promise<{
+      ok: true;
+      userId: string;
+      groupId: null;
+    } | {
+      ok: true;
+      userId: string;
+      groupId: string;
+    }>;
+    /**
+     * Read the user's active group ID from `user.extend.lastActiveGroup`.
+     * Returns `null` if no active group is set.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.userId - The user's document ID.
+     * @returns The active group's document ID, or `null` if none is set.
+     *
+     * @example
+     * ```ts
+     * const activeGroupId = await auth.user.getActiveGroup(ctx, { userId });
+     * if (activeGroupId) {
+     *   const group = await auth.group.get(ctx, activeGroupId);
+     * }
+     * ```
+     */
+    getActiveGroup: (ctx: ComponentReadCtx, opts: {
+      userId: string;
+    }) => Promise<string | null>;
+    /**
+     * Delete a user and all associated data.
+     *
+     * By default (`cascade: true`) deletes the user's sessions, accounts,
+     * API keys, group memberships, passkey credentials, and TOTP factors.
+     * Pass `{ cascade: false }` to delete only the user document itself.
+     *
+     * @param ctx - Convex mutation context.
+     * @param userId - The user's document ID.
+     * @param opts.cascade - Whether to delete related records (default `true`).
+     * @returns `{ ok: true, userId }`.
+     */
+    delete: (ctx: ComponentCtx, userId: string, opts?: {
+      cascade?: boolean;
+    }) => Promise<{
+      ok: false;
+      code: "INVALID_PARAMETERS";
+      userId?: undefined;
+    } | {
+      ok: true;
+      userId: string;
+      code?: undefined;
+    }>;
+  };
+  session: {
+    /**
+     * Resolve the current session's ID from the JWT.
+     *
+     * Extracts the `sessionId` portion of the `subject` claim in the
+     * identity token returned by `ctx.auth.getUserIdentity()`. The subject
+     * is encoded as `userId<divider>sessionId`, so this splits on the
+     * divider and returns the second segment.
+     *
+     * Returns `null` when there is no authenticated identity (i.e. no
+     * valid session JWT).
+     *
+     * @param ctx - Convex query, mutation, or action context (must include `auth`).
+     * @returns The current session's document ID, or `null` if unauthenticated.
+     *
+     * @example
+     * ```ts
+     * const sessionId = await auth.session.current(ctx);
+     * if (!sessionId) throw new Error("Not signed in");
+     * ```
+     */
+    current: (ctx: {
+      auth: Auth;
+    }) => Promise<GenericId<"Session"> | null>;
+    /**
+     * Invalidate (sign out) all sessions for a given user.
+     *
+     * Marks every session belonging to `userId` as invalid so that
+     * subsequent requests using those session JWTs will fail authentication.
+     * Optionally, one or more sessions can be excluded — this is useful
+     * when you want to sign out all *other* devices while keeping the
+     * current session alive.
+     *
+     * This method delegates to the component's internal session
+     * invalidation RPC.
+     *
+     * @param ctx - Convex action context.
+     * @param args.userId - The user whose sessions should be invalidated.
+     * @param args.except - Optional array of session IDs to keep valid.
+     * @returns `{ ok: true, userId, except }` confirming the operation.
+     *
+     * @example Sign out everywhere except the current session
+     * ```ts
+     * const sessionId = await auth.session.current(ctx);
+     * await auth.session.invalidate(ctx, {
+     *   userId,
+     *   except: sessionId ? [sessionId] : [],
+     * });
+     * ```
+     */
+    invalidate: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
+      userId: GenericId<"User">;
+      except?: GenericId<"Session">[];
+    }) => Promise<{
+      ok: true;
+      userId: GenericId<"User">;
+      except: GenericId<"Session">[];
+    }>;
+    /**
+     * Fetch a session document by ID.
+     *
+     * Returns the full session document from the component database, or
+     * `null` if no session with the given ID exists. Useful for inspecting
+     * session metadata such as creation time or associated device info.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param sessionId - The session's document ID.
+     * @returns The session document, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const session = await auth.session.get(ctx, sessionId);
+     * if (!session) throw new Error("Session not found");
+     * ```
+     */
+    get: (ctx: ComponentReadCtx, sessionId: string) => Promise<any>;
+    /**
+     * List all sessions belonging to a user.
+     *
+     * Returns every session document associated with the given `userId`,
+     * including both active and expired sessions. This is useful for
+     * building "active sessions" UIs or auditing sign-in history.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.userId - The user whose sessions to list.
+     * @returns An array of session documents.
+     *
+     * @example
+     * ```ts
+     * const sessions = await auth.session.list(ctx, { userId });
+     * console.log(`User has ${sessions.length} sessions`);
+     * ```
+     */
+    list: (ctx: ComponentReadCtx, opts: {
+      userId: string;
+    }) => Promise<any>;
+  };
+  account: {
+    /**
+     * Create a new auth account linked to a user.
+     *
+     * Creates a credentials-based account record for a given provider. If
+     * the user does not yet exist, one is created from the supplied
+     * `profile`. If `shouldLinkViaEmail` or `shouldLinkViaPhone` is set,
+     * the account may be linked to an existing user whose email or phone
+     * matches the profile.
+     *
+     * The `account.secret` (e.g. a hashed password) is optional and
+     * depends on the provider type.
+     *
+     * @param ctx - Convex action context.
+     * @param args.provider - The provider ID (e.g. `"password"`, `"credentials"`).
+     * @param args.account.id - Provider-specific account identifier (e.g. email address).
+     * @param args.account.secret - Optional credential secret (e.g. hashed password).
+     * @param args.profile - Profile data used to create or update the user document.
+     * @param args.shouldLinkViaEmail - If `true`, link to an existing user by email match.
+     * @param args.shouldLinkViaPhone - If `true`, link to an existing user by phone match.
+     * @returns `{ ok: true, ...created }` with the created account and user information.
+     *
+     * @example
+     * ```ts
+     * const result = await auth.account.create(ctx, {
+     *   provider: "password",
+     *   account: { id: "alice@example.com", secret: hashedPassword },
+     *   profile: { email: "alice@example.com", name: "Alice" },
+     * });
+     * ```
+     */
+    create: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: CreateAccountArgs) => Promise<any>;
+    /**
+     * Retrieve an auth account by provider and credentials.
+     *
+     * Looks up an account matching the given provider and account ID,
+     * optionally verifying the secret (e.g. password). If the account
+     * exists and the credentials are valid, the full account document is
+     * returned. Returns `null` if no matching account is found or if the
+     * credential verification fails (indicated by a string error from the
+     * underlying RPC).
+     *
+     * @param ctx - Convex action context.
+     * @param args.provider - The provider ID (e.g. `"password"`).
+     * @param args.account.id - Provider-specific account identifier.
+     * @param args.account.secret - Optional credential secret to verify.
+     * @returns The account document, or `null` if not found or verification failed.
+     *
+     * @example
+     * ```ts
+     * const acct = await auth.account.get(ctx, {
+     *   provider: "password",
+     *   account: { id: "alice@example.com", secret: plainTextPassword },
+     * });
+     * if (!acct) throw new Error("Invalid credentials");
+     * ```
+     */
+    get: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: RetrieveAccountArgs) => Promise<any>;
+    /**
+     * Update the credentials (secret) for an existing auth account.
+     *
+     * Replaces the stored secret for the account identified by `provider`
+     * and `account.id`. This is the standard path for password changes
+     * and password resets — the new secret is typically a freshly hashed
+     * password.
+     *
+     * @param ctx - Convex action context.
+     * @param args.provider - The provider ID (e.g. `"password"`).
+     * @param args.account.id - Provider-specific account identifier.
+     * @param args.account.secret - The new credential secret to store.
+     * @returns `{ ok: true, accountId }` confirming the update.
+     *
+     * @example Password reset
+     * ```ts
+     * await auth.account.update(ctx, {
+     *   provider: "password",
+     *   account: { id: "alice@example.com", secret: newHashedPassword },
+     * });
+     * ```
+     */
+    update: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: UpdateAccountCredentialsArgs) => Promise<{
+      ok: true;
+      accountId: string;
+    }>;
+    /**
+     * Delete an auth account by ID.
+     *
+     * Removes the account record from the database. As a safety measure,
+     * deletion is **refused** if this is the user's only remaining account
+     * — the user must always have at least one linked account. If the
+     * account is not found, returns an error result instead of throwing.
+     *
+     * @param ctx - Convex mutation context.
+     * @param accountId - The account's document ID.
+     * @returns `{ ok: true, accountId }` on success, or
+     *   `{ ok: false, code: "ACCOUNT_NOT_FOUND" }` if the account does not exist, or
+     *   `{ ok: false, code: "INVALID_PARAMETERS" }` if it is the user's last account.
+     *
+     * @example
+     * ```ts
+     * const result = await auth.account.delete(ctx, accountId);
+     * if (!result.ok) {
+     *   console.error("Cannot delete account:", result.code);
+     * }
+     * ```
+     */
+    delete: (ctx: ComponentCtx, accountId: string) => Promise<{
+      ok: false;
+      code: "ACCOUNT_NOT_FOUND";
+      accountId?: undefined;
+    } | {
+      ok: false;
+      code: "INVALID_PARAMETERS";
+      accountId?: undefined;
+    } | {
+      ok: true;
+      accountId: string;
+      code?: undefined;
+    }>;
+    /**
+     * List all passkey credentials registered for a user.
+     *
+     * Returns every WebAuthn passkey credential associated with the given
+     * `userId`. Each document includes the credential's public key,
+     * metadata (such as a human-readable name), and counters used for
+     * replay protection.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.userId - The user whose passkeys to list.
+     * @returns An array of passkey credential documents.
+     *
+     * @example
+     * ```ts
+     * const passkeys = await auth.account.listPasskeys(ctx, { userId });
+     * for (const pk of passkeys) {
+     *   console.log(pk.name ?? "Unnamed passkey", pk._id);
+     * }
+     * ```
+     */
+    listPasskeys: (ctx: ComponentReadCtx, opts: {
+      userId: string;
+    }) => Promise<any>;
+    /**
+     * Rename a passkey credential.
+     *
+     * Updates the human-readable `name` metadata on a passkey document.
+     * Useful for letting users label their passkeys (e.g. "MacBook Pro",
+     * "YubiKey 5").
+     *
+     * @param ctx - Convex mutation context.
+     * @param passkeyId - The passkey credential's document ID.
+     * @param name - The new display name for the passkey.
+     * @returns `{ ok: true, passkeyId }` confirming the rename.
+     *
+     * @example
+     * ```ts
+     * await auth.account.renamePasskey(ctx, passkeyId, "Work laptop");
+     * ```
+     */
+    renamePasskey: (ctx: ComponentCtx, passkeyId: string, name: string) => Promise<{
+      ok: true;
+      passkeyId: string;
+    }>;
+    /**
+     * Delete a passkey credential.
+     *
+     * Permanently removes a WebAuthn passkey credential from the database.
+     * After deletion, the physical authenticator associated with this
+     * credential can no longer be used to sign in.
+     *
+     * @param ctx - Convex mutation context.
+     * @param passkeyId - The passkey credential's document ID.
+     * @returns `{ ok: true, passkeyId }` confirming the deletion.
+     *
+     * @example
+     * ```ts
+     * await auth.account.deletePasskey(ctx, passkeyId);
+     * ```
+     */
+    deletePasskey: (ctx: ComponentCtx, passkeyId: string) => Promise<{
+      ok: true;
+      passkeyId: string;
+    }>;
+    /**
+     * List all TOTP (time-based one-time password) factors for a user.
+     *
+     * Returns every TOTP authenticator factor registered for the given
+     * `userId`. Each document includes the secret, issuer, and verification
+     * metadata needed for two-factor authentication management UIs.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.userId - The user whose TOTP factors to list.
+     * @returns An array of TOTP factor documents.
+     *
+     * @example
+     * ```ts
+     * const totps = await auth.account.listTotps(ctx, { userId });
+     * const has2FA = totps.length > 0;
+     * ```
+     */
+    listTotps: (ctx: ComponentReadCtx, opts: {
+      userId: string;
+    }) => Promise<any>;
+    /**
+     * Delete a TOTP factor.
+     *
+     * Permanently removes a TOTP authenticator factor from the database.
+     * After deletion, codes generated by the corresponding authenticator
+     * app will no longer be accepted for two-factor authentication.
+     *
+     * @param ctx - Convex mutation context.
+     * @param totpId - The TOTP factor's document ID.
+     * @returns `{ ok: true, totpId }` confirming the deletion.
+     *
+     * @example
+     * ```ts
+     * await auth.account.deleteTotp(ctx, totpId);
+     * ```
+     */
+    deleteTotp: (ctx: ComponentCtx, totpId: string) => Promise<{
+      ok: true;
+      totpId: string;
+    }>;
+  };
+  provider: {
+    /**
+     * Sign in through a specific provider from server-side code.
+     *
+     * Materializes the supplied provider config, runs the standard sign-in
+     * flow, and returns the resulting `userId` and `sessionId` when the
+     * provider completes authentication immediately. Returns `null` for
+     * providers that require additional client-side steps (for example
+     * redirects, email verification, or other non-immediate flows).
+     *
+     * This helper is useful for trusted server flows where you already know
+     * which provider should handle the sign-in and want the same behavior as
+     * the public auth API without generating tokens for the client.
+     *
+     * @param ctx - Convex action context.
+     * @param providerConfig - Provider configuration object to materialize and use.
+     * @param args.accountId - Optional account document ID to sign in with directly.
+     * @param args.params - Optional provider-specific parameters forwarded to the sign-in flow.
+     * @returns `{ userId, sessionId }` when sign-in succeeds immediately, or `null`
+     *   when the provider does not produce an immediate signed-in result.
+     *
+     * @example
+     * ```ts
+     * const signedIn = await auth.provider.signIn(ctx, passwordProvider, {
+     *   params: { email: "alice@example.com", password: "secret" },
+     * });
+     *
+     * if (!signedIn) {
+     *   throw new Error("Provider requires another auth step");
+     * }
+     * ```
+     */
+    signIn: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, providerConfig: AuthProviderConfig, args: {
+      accountId?: GenericId<"Account">;
+      params?: Record<string, unknown>;
+    }) => Promise<{
+      userId: GenericId<"User">;
+      sessionId: GenericId<"Session">;
+    } | null>;
+  };
+  group: {
+    /**
+     * Create a new group (organization, workspace, team, etc.).
+     *
+     * Groups are hierarchical — set `parentGroupId` to nest under an existing
+     * group, or omit it to create a root-level group. Two denormalized fields
+     * are maintained automatically:
+     *
+     * - `rootGroupId` — the root ancestor (self-referencing for root groups).
+     * - `isRoot` — `true` when the group has no parent.
+     *
+     * @param ctx - Convex mutation context.
+     * @param data.name - Display name for the group.
+     * @param data.slug - URL-safe slug (optional).
+     * @param data.type - App-defined type string (e.g. `"workspace"`, `"team"`).
+     * @param data.parentGroupId - Nest under this group. Omit for a root group.
+     * @param data.tags - Faceted classification tags (normalized at write time).
+     * @param data.extend - Arbitrary app-specific metadata.
+     * @returns `{ ok: true, groupId }`.
+     *
+     * @example Root group
+     * ```ts
+     * const { groupId } = await auth.group.create(ctx, {
+     *   name: "Acme Corp", type: "workspace",
+     * });
+     * ```
+     *
+     * @example Nested team
+     * ```ts
+     * const { groupId } = await auth.group.create(ctx, {
+     *   name: "Engineering", parentGroupId: orgId, type: "team",
+     * });
+     * ```
+     */
+    create: (ctx: ComponentCtx, data: {
+      name: string;
+      slug?: string;
+      type?: string;
+      parentGroupId?: string;
+      tags?: Array<{
+        key: string;
+        value: string;
+      }>;
+      extend?: Record<string, unknown>;
+    }) => Promise<{
+      ok: true;
+      groupId: string;
+    }>;
+    /**
+     * Fetch a group document by ID.
+     *
+     * Results are **cached per-execution** — calling `auth.group.get(ctx, id)`
+     * multiple times within the same handler for the same `groupId` returns
+     * the cached result without an additional component read.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param groupId - The group's document ID.
+     * @returns The group document (including `rootGroupId`, `isRoot`), or `null`.
+     */
+    get: (ctx: ComponentReadCtx, groupId: string) => Promise<any>;
+    /**
+     * List groups with optional filtering, pagination, and ordering.
+     *
+     * Supports filtering by `slug`, `type`, `parentGroupId`, `name`,
+     * `isRoot`, and tags (`tagsAll`, `tagsAny`). The `isRoot` and
+     * `parentGroupId` filters use dedicated indexes for efficient queries.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.where - Filter criteria (all optional, combined with AND).
+     * @param opts.where.isRoot - `true` to find root groups, `false` for nested.
+     * @param opts.where.parentGroupId - List direct children of this group.
+     * @param opts.limit - Max items per page (default 50, max 100).
+     * @param opts.cursor - Cursor from a previous `nextCursor`.
+     * @param opts.orderBy - Sort field: `"_creationTime"`, `"name"`, `"slug"`, `"type"`.
+     * @param opts.order - Sort direction: `"asc"` or `"desc"`.
+     * @returns `{ items, nextCursor }`.
+     *
+     * @example List root workspaces
+     * ```ts
+     * const { items } = await auth.group.list(ctx, {
+     *   where: { isRoot: true },
+     *   orderBy: "name", order: "asc",
+     * });
+     * ```
+     *
+     * @example List children of a group
+     * ```ts
+     * const { items } = await auth.group.list(ctx, {
+     *   where: { parentGroupId: orgId },
+     * });
+     * ```
+     */
+    list: (ctx: ComponentReadCtx, 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>;
+    /**
+     * Patch a group document.
+     *
+     * If `parentGroupId` is changed, the group's `rootGroupId` and `isRoot`
+     * fields are recomputed automatically and cascaded to all descendants.
+     *
+     * @param ctx - Convex mutation context.
+     * @param groupId - The group's document ID.
+     * @param data - Fields to merge (e.g. `name`, `slug`, `tags`, `parentGroupId`).
+     * @returns `{ ok: true, groupId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.group.update(ctx, groupId, {
+     *   name: "Acme Corp (renamed)",
+     *   slug: "acme-corp",
+     * });
+     * ```
+     */
+    update: (ctx: ComponentCtx, groupId: string, data: Record<string, unknown>) => Promise<{
+      ok: true;
+      groupId: string;
+    }>;
+    /**
+     * Delete a group and recursively cascade to all descendant groups,
+     * their members, invites, and tags.
+     *
+     * @param ctx - Convex mutation context.
+     * @param groupId - The group's document ID.
+     * @returns `{ ok: true, groupId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.group.delete(ctx, groupId);
+     * ```
+     */
+    delete: (ctx: ComponentCtx, groupId: string) => Promise<{
+      ok: true;
+      groupId: string;
+    }>;
+    /**
+     * Walk up the group hierarchy from `groupId` and return all ancestor
+     * groups in order from immediate parent to root. Detects cycles and
+     * respects `maxDepth` (default 32).
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.groupId - Starting group ID.
+     * @param opts.maxDepth - Max levels to traverse (default 32).
+     * @param opts.includeSelf - Include the starting group in the result.
+     * @returns `{ ancestors, cycleDetected, maxDepthReached }`.
+     *
+     * @example
+     * ```ts
+     * const { ancestors } = await auth.group.ancestors(ctx, {
+     *   groupId: teamId,
+     *   includeSelf: true,
+     * });
+     * const rootOrg = ancestors[ancestors.length - 1];
+     * ```
+     */
+    ancestors: (ctx: ComponentReadCtx, opts: {
+      groupId: string;
+      maxDepth?: number;
+      includeSelf?: boolean;
+    }) => Promise<{
+      ancestors: any[];
+      cycleDetected: boolean;
+      maxDepthReached: boolean;
+    }>;
+  };
+  member: {
+    /**
+     * Add a user to a group with optional role IDs.
+     *
+     * Role IDs are validated against the roles defined in `defineRoles()` —
+     * invalid IDs return `{ ok: false, code: "INVALID_ROLE_IDS" }`.
+     * Throws `DUPLICATE_MEMBERSHIP` if the user is already a member.
+     *
+     * @param ctx - Convex mutation context.
+     * @param data.groupId - The group to add the user to.
+     * @param data.userId - The user's document ID.
+     * @param data.roleIds - Role IDs from `defineRoles()` (optional).
+     * @param data.status - Membership status string (optional, app-defined).
+     * @param data.extend - Arbitrary app-specific metadata.
+     * @returns `{ ok: true, memberId }` or `{ ok: false, code, invalidRoleIds }`.
+     *
+     * @example
+     * ```ts
+     * const { memberId } = await auth.member.create(ctx, {
+     *   groupId: orgId,
+     *   userId,
+     *   roleIds: [roles.orgAdmin.id],
+     * });
+     * ```
+     */
+    create: (ctx: ComponentCtx, data: {
+      groupId: string;
+      userId: string;
+      roleIds?: string[];
+      status?: string;
+      extend?: Record<string, unknown>;
+    }) => Promise<{
+      ok: false;
+      code: "INVALID_ROLE_IDS";
+      invalidRoleIds: string[];
+      memberId?: undefined;
+    } | {
+      ok: true;
+      memberId: string;
+      code?: undefined;
+      invalidRoleIds?: undefined;
+    }>;
+    /**
+     * Fetch a membership document by its document ID.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param memberId - The membership document ID.
+     * @returns The membership document, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const membership = await auth.member.get(ctx, memberId);
+     * if (!membership) throw new Error("Membership not found");
+     * console.log(membership.roleIds, membership.groupId);
+     * ```
+     */
+    get: (ctx: ComponentReadCtx, memberId: string) => Promise<any>;
+    /**
+     * List memberships with optional filtering and pagination.
+     *
+     * Supports filtering by `groupId`, `userId`, `roleId`, and `status`.
+     * When `groupId` and `status` are both provided, a compound index
+     * is used for efficient queries.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.where - Filter criteria (all optional).
+     * @param opts.limit - Max items per page (default 50, max 100).
+     * @param opts.cursor - Cursor for pagination.
+     * @param opts.orderBy - Sort field: `"_creationTime"` or `"status"`.
+     * @param opts.order - Sort direction: `"asc"` or `"desc"`.
+     * @returns `{ items, nextCursor }`.
+     *
+     * @example
+     * ```ts
+     * const { items } = await auth.member.list(ctx, {
+     *   where: { groupId: orgId },
+     *   limit: 20,
+     *   orderBy: "_creationTime",
+     *   order: "asc",
+     * });
+     * ```
+     */
+    list: (ctx: ComponentReadCtx, opts?: {
+      where?: {
+        groupId?: string;
+        userId?: string;
+        roleId?: string;
+        status?: string;
+      };
+      limit?: number;
+      cursor?: string | null;
+      orderBy?: "_creationTime" | "status";
+      order?: "asc" | "desc";
+    }) => Promise<any>;
+    /**
+     * Remove a membership by its document ID.
+     *
+     * @param ctx - Convex mutation context.
+     * @param memberId - The membership document ID.
+     * @returns `{ ok: true, memberId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.member.delete(ctx, memberId);
+     * ```
+     */
+    delete: (ctx: ComponentCtx, memberId: string) => Promise<{
+      ok: true;
+      memberId: string;
+    }>;
+    /**
+     * Patch a membership's `roleIds`, `status`, or `extend` fields.
+     * Role IDs are validated against `defineRoles()`.
+     *
+     * @param ctx - Convex mutation context.
+     * @param memberId - The membership document ID.
+     * @param data - Fields to merge. `roleIds` are validated.
+     * @returns `{ ok: true, memberId }` or `{ ok: false, code: "INVALID_ROLE_IDS" }`.
+     *
+     * @example
+     * ```ts
+     * await auth.member.update(ctx, memberId, {
+     *   roleIds: [roles.orgAdmin.id],
+     *   status: "active",
+     * });
+     * ```
+     */
+    update: (ctx: ComponentCtx, memberId: string, data: Record<string, unknown>) => Promise<{
+      ok: false;
+      code: "INVALID_ROLE_IDS";
+      invalidRoleIds: string[];
+      memberId?: undefined;
+    } | {
+      ok: true;
+      memberId: string;
+      code?: undefined;
+      invalidRoleIds?: undefined;
+    }>;
+    /**
+     * Resolve a user's membership in a group, optionally walking the
+     * hierarchy and checking grants.
+     *
+     * **Default (no flags):** Direct lookup at `groupId` only — fast,
+     * 1 component read. Replaces the old `getByUserAndGroup`.
+     *
+     * **`ancestry: true`:** Walk the group hierarchy from `groupId` up
+     * to root, returning the first matching membership. Includes
+     * `traversedGroupIds` in the result. Expensive (N reads).
+     *
+     * **`grants: [...]`:** Check if the user has all specified grants.
+     * Works at the direct level by default. Combine with
+     * `ancestry: true` to check inherited grants.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.userId - The user's document ID.
+     * @param opts.groupId - The group to check membership in.
+     * @param opts.ancestry - Walk the hierarchy (default `false`).
+     * @param opts.grants - Grant strings to check (optional).
+     * @param opts.roleIds - Role IDs to filter by (optional).
+     * @param opts.maxDepth - Max hierarchy levels (default 32, only with ancestry).
+     * @returns `{ ok, membership, roleIds, grants, missingGrants, ... }`.
+     *   `ok` is `true` when membership exists and all requested grants are satisfied.
+     *
+     * @example Direct lookup
+     * ```ts
+     * const result = await auth.member.resolve(ctx, { userId, groupId });
+     * if (!result.membership) return { ok: false, code: "NOT_A_MEMBER" };
+     * ```
+     *
+     * @example Check grants (no hierarchy walk)
+     * ```ts
+     * const result = await auth.member.resolve(ctx, {
+     *   userId, groupId, grants: ["issues.create"],
+     * });
+     * if (!result.ok) return { ok: false, code: "FORBIDDEN" };
+     * ```
+     *
+     * @example Walk hierarchy + check grants
+     * ```ts
+     * const result = await auth.member.resolve(ctx, {
+     *   userId, groupId: teamId, ancestry: true, grants: ["issues.create"],
+     * });
+     * ```
+     */
+    resolve: (ctx: ComponentReadCtx, opts: {
+      userId: string;
+      groupId: string;
+      ancestry?: boolean;
+      roleIds?: string[];
+      grants?: string[];
+      maxDepth?: number;
+    }) => Promise<{
+      ok: false;
+      membership: null;
+      matchedGroupId: null;
+      roleIds: string[];
+      grants: string[];
+      missingGrants: string[];
+      depth: null;
+      isDirect: boolean;
+      isInherited: boolean;
+      traversedGroupIds: string[];
+      code: "INVALID_ROLE_IDS";
+      invalidRoleIds: string[];
+    } | {
+      ok: boolean;
+      membership: any;
+      matchedGroupId: string | null;
+      roleIds: any;
+      grants: string[];
+      missingGrants: string[];
+      depth: number | null;
+      isDirect: boolean;
+      isInherited: boolean;
+      traversedGroupIds: string[];
+      code?: undefined;
+      invalidRoleIds?: undefined;
+    }>;
+  };
+  invite: {
+    /**
+     * Create a pending invite. Returns a one-time `token` the recipient
+     * uses to accept. Optionally scoped to a group with role IDs.
+     *
+     * @param ctx - Convex mutation context.
+     * @param data.groupId - The group to invite the user to (optional).
+     * @param data.invitedByUserId - The user who created this invite (optional).
+     * @param data.email - The invitee's email address (optional).
+     * @param data.roleIds - Role IDs from `defineRoles()` to assign on acceptance (optional).
+     * @param data.expiresTime - Expiration timestamp in ms since epoch (optional).
+     * @param data.extend - Arbitrary app-specific metadata (optional).
+     * @returns `{ ok: true, inviteId, token }` or `{ ok: false, code: "INVALID_ROLE_IDS" }`.
+     *
+     * @example
+     * ```ts
+     * const { token } = await auth.invite.create(ctx, {
+     *   groupId, email: "alice@example.com", roleIds: [roles.member.id],
+     * });
+     * ```
+     */
+    create: (ctx: ComponentCtx, data: {
+      groupId?: string;
+      invitedByUserId?: string;
+      email?: string;
+      roleIds?: string[];
+      expiresTime?: number;
+      extend?: Record<string, unknown>;
+    }) => Promise<{
+      ok: false;
+      code: "INVALID_ROLE_IDS";
+      invalidRoleIds: string[];
+      inviteId?: undefined;
+      token?: undefined;
+    } | {
+      ok: true;
+      inviteId: string;
+      token: string;
+      code?: undefined;
+      invalidRoleIds?: undefined;
+    }>;
+    /**
+     * Fetch an invite document by ID.
+     *
+     * Returns the full invite document including its status, email,
+     * group, role IDs, and token hash. Useful for displaying invite
+     * details or checking status before performing actions.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param inviteId - The invite's document ID.
+     * @returns The invite document, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const invite = await auth.invite.get(ctx, inviteId);
+     * if (invite?.status === "pending") {
+     *   // show invite details
+     * }
+     * ```
+     */
+    get: (ctx: ComponentReadCtx, inviteId: string) => Promise<any>;
+    token: {
+      /**
+       * Look up an invite by its raw token string.
+       *
+       * Hashes the raw token and queries the database for a matching
+       * invite. This is the standard path for invite-link landing pages
+       * where the token is extracted from the URL.
+       *
+       * @param ctx - Convex query or mutation context.
+       * @param token - The raw invite token string from the invite link.
+       * @returns The invite document, or `null` if no matching invite exists.
+       *
+       * @example
+       * ```ts
+       * const invite = await auth.invite.token.get(ctx, tokenFromUrl);
+       * if (!invite || invite.status !== "pending") {
+       *   throw new Error("Invalid or expired invite");
+       * }
+       * ```
+       */
+      get: (ctx: ComponentReadCtx, token: string) => Promise<any>;
+      /**
+       * Accept an invite by token. Creates a membership and marks the invite as accepted.
+       *
+       * Hashes the raw token, finds the matching invite, creates a group
+       * membership with the invite's role IDs, and transitions the invite
+       * status to `"accepted"`.
+       *
+       * @param ctx - Convex mutation context.
+       * @param args.token - The raw invite token string.
+       * @param args.acceptedByUserId - The user accepting the invite.
+       * @returns `{ ok: true, ...result }` with the created membership details.
+       *
+       * @example
+       * ```ts
+       * const result = await auth.invite.token.accept(ctx, {
+       *   token: tokenFromUrl,
+       *   acceptedByUserId: userId,
+       * });
+       * ```
+       */
+      accept: (ctx: ComponentCtx, args: {
+        token: string;
+        acceptedByUserId: string;
+      }) => Promise<any>;
+    };
+    /**
+     * List invites with optional filtering by group, status, email, etc.
+     * Results are paginated.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.where - Filter criteria (all optional).
+     * @param opts.where.status - `"pending"`, `"accepted"`, `"revoked"`, or `"expired"`.
+     * @param opts.limit - Max items per page (default 50, max 100).
+     * @param opts.cursor - Cursor from a previous `nextCursor` for pagination.
+     * @param opts.orderBy - Sort field: `"_creationTime"`, `"status"`, `"email"`,
+     *   `"expiresTime"`, or `"acceptedTime"`.
+     * @param opts.order - Sort direction: `"asc"` or `"desc"`.
+     * @returns `{ items, nextCursor }` — `nextCursor` is `null` when there are no more pages.
+     *
+     * @example
+     * ```ts
+     * const { items } = await auth.invite.list(ctx, {
+     *   where: { groupId, status: "pending" },
+     *   orderBy: "_creationTime",
+     *   order: "desc",
+     * });
+     * ```
+     */
+    list: (ctx: ComponentReadCtx, opts?: {
+      where?: {
+        tokenHash?: string;
+        groupId?: string;
+        status?: "pending" | "accepted" | "revoked" | "expired";
+        email?: string;
+        invitedByUserId?: string;
+        roleId?: string;
+        acceptedByUserId?: string;
+      };
+      limit?: number;
+      cursor?: string | null;
+      orderBy?: "_creationTime" | "status" | "email" | "expiresTime" | "acceptedTime";
+      order?: "asc" | "desc";
+    }) => Promise<any>;
+    /**
+     * Accept an invite by ID. Optionally specify who accepted it.
+     *
+     * Transitions the invite's status to `"accepted"` and optionally
+     * records the accepting user. Unlike `invite.token.accept`, this
+     * method does not automatically create a group membership — use it
+     * for admin-driven invite acceptance flows.
+     *
+     * @param ctx - Convex mutation context.
+     * @param inviteId - The invite's document ID.
+     * @param acceptedByUserId - The user who accepted the invite (optional).
+     * @returns `{ ok: true, inviteId, acceptedByUserId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.invite.accept(ctx, inviteId, userId);
+     * ```
+     */
+    accept: (ctx: ComponentCtx, inviteId: string, acceptedByUserId?: string) => Promise<{
+      ok: true;
+      inviteId: string;
+      acceptedByUserId: string | null;
+    }>;
+    /**
+     * Revoke a pending invite. Sets its status to `"revoked"`.
+     *
+     * Once revoked, the invite's token can no longer be used to accept
+     * the invitation. This is a permanent status change.
+     *
+     * @param ctx - Convex mutation context.
+     * @param inviteId - The invite's document ID.
+     * @returns `{ ok: true, inviteId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.invite.revoke(ctx, inviteId);
+     * ```
+     */
+    revoke: (ctx: ComponentCtx, inviteId: string) => Promise<{
+      ok: true;
+      inviteId: string;
+    }>;
+  };
+  key: {
+    /**
+     * Create an API key for programmatic access. The returned `secret`
+     * (prefixed `sk_`) is shown only once — it is stored as a hash.
+     *
+     * @param ctx - Convex mutation context.
+     * @param opts.userId - Owner of the key.
+     * @param opts.name - Human-readable name (e.g. `"CI Pipeline"`).
+     * @param opts.scopes - Array of `{ resource, actions }` permission scopes.
+     * @param opts.rateLimit - Optional per-key rate limit `{ maxRequests, windowMs }`.
+     * @param opts.expiresAt - Optional expiration timestamp (ms since epoch).
+     * @param opts.metadata - Arbitrary app-specific metadata.
+     * @returns `{ ok: true, keyId, secret }`. Store `secret` securely — it cannot be retrieved later.
+     *
+     * @example
+     * ```ts
+     * const { secret } = await auth.key.create(ctx, {
+     *   userId,
+     *   name: "CI Pipeline",
+     *   scopes: [{ resource: "data", actions: ["read"] }],
+     * });
+     * ```
+     */
+    create: (ctx: ComponentCtx, opts: {
+      userId: string;
+      name: string;
+      scopes: KeyScope[];
+      rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+      };
+      expiresAt?: number;
+      metadata?: Record<string, unknown>;
+    }) => Promise<{
+      ok: true;
+      keyId: string;
+      secret: string;
+    }>;
+    /**
+     * Verify an API key and return the owner's identity and scopes.
+     *
+     * Checks the key against the database, enforces expiration and rate
+     * limits, and returns a `ScopeChecker` for permission evaluation.
+     *
+     * @param ctx - Convex mutation context (updates `lastUsedAt` and rate limit state).
+     * @param rawKey - The raw `sk_*` key string.
+     * @returns On success: `{ ok: true, userId, keyId, scopes }` where `scopes.can(resource, action)` checks permissions.
+     *   On failure: `{ ok: false, code }` with one of:
+     *   - `"INVALID_API_KEY"` — key not found.
+     *   - `"API_KEY_REVOKED"` — key was revoked.
+     *   - `"API_KEY_EXPIRED"` — key past its `expiresAt`.
+     *   - `"API_KEY_RATE_LIMITED"` — rate limit exceeded.
+     *
+     * @example
+     * ```ts
+     * const result = await auth.key.verify(ctx, rawKey);
+     * if (!result.ok) return { ok: false, code: result.code };
+     * const canRead = result.scopes.can("data", "read");
+     * ```
+     */
+    verify: (ctx: ComponentCtx, rawKey: string) => Promise<{
+      ok: true;
+      userId: string;
+      keyId: string;
+      scopes: ScopeChecker;
+    } | {
+      ok: false;
+      code: "INVALID_API_KEY" | "API_KEY_REVOKED" | "API_KEY_EXPIRED" | "API_KEY_RATE_LIMITED";
+    }>;
+    /**
+     * List API keys with optional filtering by user, revocation status, name,
+     * or prefix. Results are paginated. Does not expose raw key secrets.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param opts.where - Filter criteria (all optional, combined with AND).
+     * @param opts.limit - Max items per page (default 50, max 100).
+     * @param opts.cursor - Cursor from a previous `nextCursor` for pagination.
+     * @param opts.orderBy - Sort field: `"_creationTime"`, `"name"`, `"lastUsedAt"`, `"expiresAt"`, or `"revoked"`.
+     * @param opts.order - Sort direction: `"asc"` or `"desc"`.
+     * @returns `{ items, nextCursor }` — `nextCursor` is `null` when no more pages.
+     *
+     * @example
+     * ```ts
+     * const { items } = await auth.key.list(ctx, {
+     *   where: { userId, revoked: false },
+     *   orderBy: "lastUsedAt",
+     *   order: "desc",
+     * });
+     * ```
+     */
+    list: (ctx: ComponentReadCtx, 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>;
+    /**
+     * Fetch an API key record by ID. Does not expose the raw key secret.
+     *
+     * Returns the key document including metadata, scopes, rate limit
+     * configuration, and revocation status. The raw secret is never
+     * stored or returned — only the hashed key and display prefix.
+     *
+     * @param ctx - Convex query or mutation context.
+     * @param keyId - The API key's document ID.
+     * @returns `{ ok: true, key }` with the key document, or `{ ok: false }` if not found.
+     *
+     * @example
+     * ```ts
+     * const result = await auth.key.get(ctx, keyId);
+     * if (!result.ok) throw new Error("Key not found");
+     * console.log(result.key.name, result.key.prefix);
+     * ```
+     */
+    get: (ctx: ComponentReadCtx, keyId: string) => Promise<{
+      ok: true;
+      key: KeyDoc;
+    } | {
+      ok: false;
+    }>;
+    /**
+     * Update a key's name, scopes, or rate limit.
+     *
+     * Patches the specified fields on the API key document. Only the
+     * provided fields are changed — omitted fields remain unchanged.
+     *
+     * @param ctx - Convex mutation context.
+     * @param keyId - The API key's document ID.
+     * @param data - Fields to merge into the key document.
+     * @returns `{ ok: true, keyId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.key.update(ctx, keyId, {
+     *   name: "CI Pipeline (updated)",
+     *   scopes: [{ resource: "data", actions: ["read", "write"] }],
+     * });
+     * ```
+     */
+    update: (ctx: ComponentCtx, keyId: string, data: {
+      name?: string;
+      scopes?: KeyScope[];
+      rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+      };
+    }) => Promise<{
+      ok: true;
+      keyId: string;
+    }>;
+    /**
+     * Soft-delete: set `revoked: true`. The key can no longer be verified.
+     *
+     * After revocation, any subsequent calls to `auth.key.verify` with
+     * this key will return `{ ok: false, code: "API_KEY_REVOKED" }`.
+     * The key record is preserved for audit purposes.
+     *
+     * @param ctx - Convex mutation context.
+     * @param keyId - The API key's document ID.
+     * @returns `{ ok: true, keyId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.key.revoke(ctx, keyId);
+     * ```
+     */
+    revoke: (ctx: ComponentCtx, keyId: string) => Promise<{
+      ok: true;
+      keyId: string;
+    }>;
+    /**
+     * Hard-delete: permanently remove the key record.
+     *
+     * Unlike `revoke`, this permanently removes the key document from
+     * the database. Use this when you need to fully clean up a key
+     * rather than preserving it for audit history.
+     *
+     * @param ctx - Convex mutation context.
+     * @param keyId - The API key's document ID.
+     * @returns `{ ok: true, keyId }`.
+     *
+     * @example
+     * ```ts
+     * await auth.key.delete(ctx, keyId);
+     * ```
+     */
+    delete: (ctx: ComponentCtx, keyId: string) => Promise<{
+      ok: true;
+      keyId: string;
+    }>;
+    /**
+     * Rotate a key: revokes the old key and creates a new one with the
+     * same user, scopes, and rate limit. Returns the new `keyId` and `secret`.
+     * Fails with `{ ok: false }` if the key is already revoked.
+     *
+     * @param ctx - Convex mutation context.
+     * @param keyId - The existing API key's document ID to rotate.
+     * @param opts.name - Optional new name for the rotated key (defaults to the old name).
+     * @param opts.expiresAt - Optional new expiration timestamp in ms since epoch.
+     * @returns `{ ok: true, keyId, secret }` with the new key, or `{ ok: false, code }` on failure.
+     *
+     * @example
+     * ```ts
+     * const result = await auth.key.rotate(ctx, oldKeyId, {
+     *   expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
+     * });
+     * if (result.ok) {
+     *   // Store result.secret securely — shown only once
+     * }
+     * ```
+     */
+    rotate: (ctx: ComponentCtx, keyId: string, opts?: {
+      name?: string;
+      expiresAt?: number;
+    }) => Promise<{
+      ok: true;
+      keyId: string;
+      secret: string;
+    } | {
+      ok: false;
+      code: "INVALID_PARAMETERS" | "API_KEY_REVOKED";
+    }>;
+  };
+};
+//#endregion
+export { createCoreDomains };
+//# sourceMappingURL=core.d.ts.map