@robelest/convex-auth 0.0.4-preview.22 → 0.0.4-preview.24

package/dist/server/core.d.ts

@@ -60,39 +60,7 @@ type CoreDeps = {
 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.
+      * 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
@@ -140,9 +108,8 @@ declare function createCoreDomains(deps: CoreDeps): {
       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)`.
+      * Convenience method: resolve the current session user and fetch their
+      * full document in one call. Returns `null` if unauthenticated.
      *
      * @param ctx - Convex query or mutation context with `auth` for session lookup.
      * @returns The authenticated user's document, or `null` if unauthenticated.
@@ -162,7 +129,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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 }`.
+     * @returns `{ userId }`.
      *
      * @example
      * ```ts
@@ -173,7 +140,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     update: (ctx: ComponentCtx, userId: string, data: Record<string, unknown>) => Promise<{
-      ok: true;
       userId: string;
     }>;
     /**
@@ -184,7 +150,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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).
+     * @returns `{ userId, groupId }` confirming the active group was set (or cleared).
      *
      * @example
      * ```ts
@@ -199,11 +165,9 @@ declare function createCoreDomains(deps: CoreDeps): {
       userId: string;
       groupId: string | null;
     }) => Promise<{
-      ok: true;
       userId: string;
       groupId: null;
     } | {
-      ok: true;
       userId: string;
       groupId: string;
     }>;
@@ -236,18 +200,13 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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 }`.
+     * @returns `{ userId }`.
+     * @throws `INVALID_PARAMETERS` if `cascade` is `false` but the user has linked data.
      */
     delete: (ctx: ComponentCtx, userId: string, opts?: {
       cascade?: boolean;
     }) => Promise<{
-      ok: false;
-      code: "INVALID_PARAMETERS";
-      userId?: undefined;
-    } | {
-      ok: true;
       userId: string;
-      code?: undefined;
     }>;
   };
   session: {
@@ -289,7 +248,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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.
+     * @returns `{ userId, except }` confirming the operation.
      *
      * @example Sign out everywhere except the current session
      * ```ts
@@ -304,7 +263,6 @@ declare function createCoreDomains(deps: CoreDeps): {
       userId: GenericId<"User">;
       except?: GenericId<"Session">[];
     }) => Promise<{
-      ok: true;
       userId: GenericId<"User">;
       except: GenericId<"Session">[];
     }>;
@@ -367,7 +325,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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.
+     * @returns The created account and user information.
      *
      * @example
      * ```ts
@@ -417,7 +375,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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.
+     * @returns `{ accountId }` confirming the update.
      *
      * @example Password reset
      * ```ts
@@ -428,7 +386,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     update: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: UpdateAccountCredentialsArgs) => Promise<{
-      ok: true;
       accountId: string;
     }>;
     /**
@@ -441,30 +398,17 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @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.
+     * @returns `{ accountId }` on success.
+     * @throws `ACCOUNT_NOT_FOUND` if the account does not exist.
+     * @throws `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);
-     * }
+     * await auth.account.delete(ctx, accountId);
      * ```
      */
     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.
@@ -499,7 +443,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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.
+     * @returns `{ passkeyId }` confirming the rename.
      *
      * @example
      * ```ts
@@ -507,7 +451,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     renamePasskey: (ctx: ComponentCtx, passkeyId: string, name: string) => Promise<{
-      ok: true;
       passkeyId: string;
     }>;
     /**
@@ -519,7 +462,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @param ctx - Convex mutation context.
      * @param passkeyId - The passkey credential's document ID.
-     * @returns `{ ok: true, passkeyId }` confirming the deletion.
+     * @returns `{ passkeyId }` confirming the deletion.
      *
      * @example
      * ```ts
@@ -527,7 +470,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     deletePasskey: (ctx: ComponentCtx, passkeyId: string) => Promise<{
-      ok: true;
       passkeyId: string;
     }>;
     /**
@@ -559,7 +501,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @param ctx - Convex mutation context.
      * @param totpId - The TOTP factor's document ID.
-     * @returns `{ ok: true, totpId }` confirming the deletion.
+     * @returns `{ totpId }` confirming the deletion.
      *
      * @example
      * ```ts
@@ -567,7 +509,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     deleteTotp: (ctx: ComponentCtx, totpId: string) => Promise<{
-      ok: true;
       totpId: string;
     }>;
   };
@@ -629,7 +570,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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 }`.
+     * @returns `{ groupId }`.
      *
      * @example Root group
      * ```ts
@@ -656,7 +597,6 @@ declare function createCoreDomains(deps: CoreDeps): {
       }>;
       extend?: Record<string, unknown>;
     }) => Promise<{
-      ok: true;
       groupId: string;
     }>;
     /**
@@ -733,7 +673,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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 }`.
+     * @returns `{ groupId }`.
      *
      * @example
      * ```ts
@@ -744,7 +684,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     update: (ctx: ComponentCtx, groupId: string, data: Record<string, unknown>) => Promise<{
-      ok: true;
       groupId: string;
     }>;
     /**
@@ -753,7 +692,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @param ctx - Convex mutation context.
      * @param groupId - The group's document ID.
-     * @returns `{ ok: true, groupId }`.
+     * @returns `{ groupId }`.
      *
      * @example
      * ```ts
@@ -761,7 +700,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     delete: (ctx: ComponentCtx, groupId: string) => Promise<{
-      ok: true;
       groupId: string;
     }>;
     /**
@@ -799,7 +737,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * 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" }`.
+     * invalid IDs throw `INVALID_ROLE_IDS`.
      * Throws `DUPLICATE_MEMBERSHIP` if the user is already a member.
      *
      * @param ctx - Convex mutation context.
@@ -808,7 +746,8 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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 }`.
+     * @returns `{ memberId }`.
+     * @throws `INVALID_ROLE_IDS` if any supplied role IDs are not defined.
      *
      * @example
      * ```ts
@@ -826,15 +765,7 @@ declare function createCoreDomains(deps: CoreDeps): {
       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.
@@ -893,7 +824,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @param ctx - Convex mutation context.
      * @param memberId - The membership document ID.
-     * @returns `{ ok: true, memberId }`.
+     * @returns `{ memberId }`.
      *
      * @example
      * ```ts
@@ -901,7 +832,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     delete: (ctx: ComponentCtx, memberId: string) => Promise<{
-      ok: true;
       memberId: string;
     }>;
     /**
@@ -911,7 +841,8 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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" }`.
+     * @returns `{ memberId }`.
+     * @throws `INVALID_ROLE_IDS` if any supplied role IDs are not defined.
      *
      * @example
      * ```ts
@@ -922,15 +853,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     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
@@ -951,34 +874,41 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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.
+     * @returns `{ membership, roleIds, grants }`.
      *
      * @example Direct lookup
      * ```ts
-     * const result = await auth.member.resolve(ctx, { userId, groupId });
-     * if (!result.membership) return { ok: false, code: "NOT_A_MEMBER" };
+     * const result = await auth.member.inspect(ctx, { userId, groupId });
+     * if (!result.membership) return null;
      * ```
      *
-     * @example Check grants (no hierarchy walk)
+     * @example Check grants after inspection
      * ```ts
-     * const result = await auth.member.resolve(ctx, {
-     *   userId, groupId, grants: ["issues.create"],
+     * const result = await auth.member.inspect(ctx, {
+     *   userId, groupId,
      * });
-     * if (!result.ok) return { ok: false, code: "FORBIDDEN" };
+     * const canCreate = result.grants.includes("issues.create");
      * ```
      *
      * @example Walk hierarchy + check grants
      * ```ts
-     * const result = await auth.member.resolve(ctx, {
-     *   userId, groupId: teamId, ancestry: true, grants: ["issues.create"],
+     * const result = await auth.member.inspect(ctx, {
+     *   userId, groupId: teamId, ancestry: true,
      * });
      * ```
      */
-    resolve: (ctx: ComponentReadCtx, opts: {
+    inspect: (ctx: ComponentReadCtx, opts: {
+      userId: string;
+      groupId: string;
+      ancestry?: boolean;
+      maxDepth?: number;
+    }) => Promise<{
+      membership: any;
+      roleIds: any;
+      grants: string[];
+    }>;
+    require: (ctx: ComponentReadCtx, opts: {
       userId: string;
       groupId: string;
       ancestry?: boolean;
@@ -986,31 +916,9 @@ declare function createCoreDomains(deps: CoreDeps): {
       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: {
@@ -1025,7 +933,8 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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" }`.
+     * @returns `{ inviteId, token }`.
+     * @throws `INVALID_ROLE_IDS` if any supplied role IDs are not defined.
      *
      * @example
      * ```ts
@@ -1042,17 +951,8 @@ declare function createCoreDomains(deps: CoreDeps): {
       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.
@@ -1105,7 +1005,7 @@ declare function createCoreDomains(deps: CoreDeps): {
        * @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.
+       * @returns The created membership details.
        *
        * @example
        * ```ts
@@ -1169,7 +1069,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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 }`.
+     * @returns `{ inviteId, acceptedByUserId }`.
      *
      * @example
      * ```ts
@@ -1177,7 +1077,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     accept: (ctx: ComponentCtx, inviteId: string, acceptedByUserId?: string) => Promise<{
-      ok: true;
       inviteId: string;
       acceptedByUserId: string | null;
     }>;
@@ -1189,7 +1088,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @param ctx - Convex mutation context.
      * @param inviteId - The invite's document ID.
-     * @returns `{ ok: true, inviteId }`.
+     * @returns `{ inviteId }`.
      *
      * @example
      * ```ts
@@ -1197,7 +1096,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     revoke: (ctx: ComponentCtx, inviteId: string) => Promise<{
-      ok: true;
       inviteId: string;
     }>;
   };
@@ -1213,7 +1111,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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.
+     * @returns `{ keyId, secret }`. Store `secret` securely — it cannot be retrieved later.
      *
      * @example
      * ```ts
@@ -1235,7 +1133,6 @@ declare function createCoreDomains(deps: CoreDeps): {
       expiresAt?: number;
       metadata?: Record<string, unknown>;
     }) => Promise<{
-      ok: true;
       keyId: string;
       secret: string;
     }>;
@@ -1247,28 +1144,22 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @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.
+     * @returns `{ userId, keyId, scopes }` where `scopes.can(resource, action)` checks permissions.
+     * @throws `INVALID_API_KEY` if the key is not found.
+     * @throws `API_KEY_REVOKED` if the key was revoked.
+     * @throws `API_KEY_EXPIRED` if the key is past its `expiresAt`.
+     * @throws `API_KEY_RATE_LIMITED` if the rate limit is 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");
+     * const { userId, scopes } = await auth.key.verify(ctx, rawKey);
+     * const canRead = 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,
@@ -1312,21 +1203,16 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @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.
+     * @returns The key document, or `null` 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);
+     * const key = await auth.key.get(ctx, keyId);
+     * if (!key) throw new Error("Key not found");
+     * console.log(key.name, key.prefix);
      * ```
      */
-    get: (ctx: ComponentReadCtx, keyId: string) => Promise<{
-      ok: true;
-      key: KeyDoc;
-    } | {
-      ok: false;
-    }>;
+    get: (ctx: ComponentReadCtx, keyId: string) => Promise<KeyDoc | null>;
     /**
      * Update a key's name, scopes, or rate limit.
      *
@@ -1336,7 +1222,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      * @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 }`.
+     * @returns `{ keyId }`.
      *
      * @example
      * ```ts
@@ -1354,19 +1240,18 @@ declare function createCoreDomains(deps: CoreDeps): {
         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" }`.
+     * this key will throw `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 }`.
+     * @returns `{ keyId }`.
      *
      * @example
      * ```ts
@@ -1374,7 +1259,6 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     revoke: (ctx: ComponentCtx, keyId: string) => Promise<{
-      ok: true;
       keyId: string;
     }>;
     /**
@@ -1386,7 +1270,7 @@ declare function createCoreDomains(deps: CoreDeps): {
      *
      * @param ctx - Convex mutation context.
      * @param keyId - The API key's document ID.
-     * @returns `{ ok: true, keyId }`.
+     * @returns `{ keyId }`.
      *
      * @example
      * ```ts
@@ -1394,40 +1278,35 @@ declare function createCoreDomains(deps: CoreDeps): {
      * ```
      */
     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.
+     * Throws if the key does not exist or 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.
+     * @returns `{ keyId, secret }` with the new key.
+     * @throws `INVALID_PARAMETERS` if the key does not exist.
+     * @throws `API_KEY_REVOKED` if the key is already revoked.
      *
      * @example
      * ```ts
-     * const result = await auth.key.rotate(ctx, oldKeyId, {
+     * const { keyId, secret } = 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
-     * }
+     * // Store 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";
     }>;
   };
 };