@robelest/convex-auth 0.0.2 → 0.0.3-preview.1

package/src/server/implementation/index.ts

@@ -9,6 +9,7 @@ import {
   internalMutationGeneric,
 } from "convex/server";
 import { ConvexError, GenericId, v } from "convex/values";
+import { throwAuthError, isAuthError } from "../errors.js";
 import { parse as parseCookies, serialize as serializeCookie } from "cookie";
 import { redirectToParamCookie, useRedirectToParam } from "../cookies.js";
 import { FunctionReferenceFromExport } from "../convex_types.js";
@@ -44,6 +45,13 @@ import {
 } from "./mutations/index.js";
 import { signInImpl } from "./signIn.js";
 import { redirectAbsoluteUrl, setURLSearchParam } from "./redirects.js";
+import {
+  generateApiKey,
+  hashApiKey,
+  buildScopeChecker,
+  validateScopes,
+  checkKeyRateLimit,
+} from "./apiKey.js";
 import { getAuthorizationUrl } from "../oauth/authorizationUrl.js";
 import {
   defaultCookiesOptions,
@@ -106,11 +114,11 @@ export function Auth(config_: ConvexAuthConfig) {
   ) => {
     const provider = getProvider(id, allowExtraProviders);
     if (provider === undefined) {
-      const message =
+      const detail =
         `Provider \`${id}\` is not configured, ` +
         `available providers are ${listAvailableProviders(config, allowExtraProviders)}.`;
-      logWithLevel(LOG_LEVELS.ERROR, message);
-      throw new Error(message);
+      logWithLevel(LOG_LEVELS.ERROR, detail);
+      throwAuthError("PROVIDER_NOT_CONFIGURED", detail, { provider: id });
     }
     return provider;
   };
@@ -139,6 +147,9 @@ export function Auth(config_: ConvexAuthConfig) {
       /**
        * Get the current user's ID from the auth context, or `null` if
        * not signed in.
+       *
+       * @param ctx - Any Convex context with an `auth` field (query, mutation, or action).
+       * @returns The user's `Id<"user">`, or `null` when unauthenticated.
        */
       current: async (ctx: { auth: Auth }) => {
         const identity = await ctx.auth.getUserIdentity();
@@ -151,24 +162,35 @@ export function Auth(config_: ConvexAuthConfig) {
       /**
        * Get the current user's ID, or throw if not signed in.
        * Use this when authentication is required.
+       *
+       * @param ctx - Any Convex context with an `auth` field.
+       * @returns The user's `Id<"user">`.
+       * @throws `ConvexError` with code `NOT_SIGNED_IN` when unauthenticated.
        */
       require: async (ctx: { auth: Auth }) => {
         const identity = await ctx.auth.getUserIdentity();
         if (identity === null) {
-          throw new Error("Not signed in");
+          throwAuthError("NOT_SIGNED_IN");
         }
         const [userId] = identity.subject.split(TOKEN_SUB_CLAIM_DIVIDER);
         return userId as GenericId<"user">;
       },
       /**
        * 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: async (ctx: ComponentReadCtx, userId: string) => {
         return await ctx.runQuery(config.component.public.userGetById, { userId });
       },
       /**
        * Get the currently signed-in user's document, or `null` if not
-       * signed in. Convenience method combining `current` + `get`.
+       * signed in. Convenience combining `current()` + `get()`.
+       *
+       * @param ctx - Convex context with `auth` and `runQuery`.
+       * @returns The user document, or `null` when unauthenticated.
        */
       viewer: async (ctx: ComponentAuthReadCtx) => {
         const userId = await auth.user.current(ctx);
@@ -177,6 +199,23 @@ export function Auth(config_: ConvexAuthConfig) {
         }
         return await ctx.runQuery(config.component.public.userGetById, { userId });
       },
+      /**
+       * 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: async (
+        ctx: ComponentCtx,
+        userId: string,
+        data: Record<string, unknown>,
+      ) => {
+        await ctx.runMutation(config.component.public.userPatch, {
+          userId,
+          data,
+        });
+      },
       /**
        * Query a user's group memberships.
        */
@@ -208,6 +247,9 @@ export function Auth(config_: ConvexAuthConfig) {
       /**
        * 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: async (ctx: { auth: Auth }) => {
         const identity = await ctx.auth.getUserIdentity();
@@ -219,6 +261,10 @@ export function Auth(config_: ConvexAuthConfig) {
       },
       /**
        * 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: async <DataModel extends GenericDataModel>(
         ctx: GenericActionCtx<DataModel>,
@@ -234,6 +280,10 @@ export function Auth(config_: ConvexAuthConfig) {
     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: async <DataModel extends GenericDataModel>(
         ctx: GenericActionCtx<DataModel>,
@@ -244,6 +294,11 @@ export function Auth(config_: ConvexAuthConfig) {
       },
       /**
        * 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: async <DataModel extends GenericDataModel>(
         ctx: GenericActionCtx<DataModel>,
@@ -252,12 +307,15 @@ export function Auth(config_: ConvexAuthConfig) {
         const actionCtx = ctx as unknown as ActionCtx;
         const result = await callRetreiveAccountWithCredentials(actionCtx, args);
         if (typeof result === "string") {
-          throw new Error(result);
+          throwAuthError("ACCOUNT_NOT_FOUND", result);
         }
         return result;
       },
       /**
-       * Update credentials for an existing account.
+       * Update credentials (secret) for an existing account.
+       *
+       * @param ctx - Convex action context.
+       * @param args - Provider ID and new account credentials (id + secret).
        */
       updateCredentials: async <DataModel extends GenericDataModel>(
         ctx: GenericActionCtx<DataModel>,
@@ -270,6 +328,11 @@ export function Auth(config_: ConvexAuthConfig) {
     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: async <DataModel extends GenericDataModel>(
         ctx: GenericActionCtx<DataModel>,
@@ -507,15 +570,17 @@ export function Auth(config_: ConvexAuthConfig) {
        * the timestamp. If the invite has a group, the caller is responsible
        * for creating the member record via `auth.group.member.add` in the
        * same Convex mutation for transactional safety.
-        *
-        * @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.
        *
+       * @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() },
+       * 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);
@@ -539,14 +604,14 @@ export function Auth(config_: ConvexAuthConfig) {
           ...(acceptedByUserId ? { acceptedByUserId } : {}),
         });
       },
-       /**
-        * Revoke a pending invitation.
-        *
-        * @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 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: async (ctx: ComponentCtx, inviteId: string) => {
         await ctx.runMutation(config.component.public.inviteRevoke, { inviteId });
       },
@@ -631,6 +696,191 @@ export function Auth(config_: ConvexAuthConfig) {
         );
       },
     },
+    /**
+     * 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: "users", actions: ["read", "list"] }],
+     * });
+     * // raw = "sk_live_abc123..." — show once, never stored
+     *
+     * const result = await auth.key.verify(ctx, rawKey);
+     * result.scopes.can("users", "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.
+       * @returns `{ keyId, raw }` where `raw` is the full key string.
+       */
+      create: async (
+        ctx: ComponentCtx,
+        opts: {
+          userId: string;
+          name: string;
+          scopes: import("../types.js").KeyScope[];
+          rateLimit?: { maxRequests: number; windowMs: number };
+          expiresAt?: number;
+        },
+      ): Promise<{ keyId: string; raw: string }> => {
+        const prefix = config.apiKeys?.prefix ?? "sk_live_";
+
+        // Validate scopes against config if defined
+        validateScopes(opts.scopes, config.apiKeys?.scopes);
+
+        const { raw, hashedKey, displayPrefix } = await generateApiKey(prefix);
+
+        const keyId = await ctx.runMutation(
+          config.component.public.keyInsert,
+          {
+            userId: opts.userId as any,
+            prefix: displayPrefix,
+            hashedKey,
+            name: opts.name,
+            scopes: opts.scopes,
+            rateLimit: opts.rateLimit ?? config.apiKeys?.defaultRateLimit,
+            expiresAt: opts.expiresAt,
+          },
+        );
+
+        return { keyId: keyId as string, raw };
+      },
+
+      /**
+       * 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: async (
+        ctx: ComponentCtx,
+        rawKey: string,
+      ): Promise<{
+        userId: string;
+        keyId: string;
+        scopes: import("../types.js").ScopeChecker;
+      }> => {
+        const hashedKey = await hashApiKey(rawKey);
+
+        const key = await ctx.runQuery(
+          config.component.public.keyGetByHashedKey,
+          { hashedKey },
+        );
+        if (!key) {
+          throwAuthError("INVALID_API_KEY");
+        }
+        if (key.revoked) {
+          throwAuthError("API_KEY_REVOKED");
+        }
+        if (key.expiresAt && key.expiresAt < Date.now()) {
+          throwAuthError("API_KEY_EXPIRED");
+        }
+
+        // Check per-key rate limit
+        const patchData: Record<string, any> = { lastUsedAt: Date.now() };
+
+        if (key.rateLimit) {
+          const { limited, newState } = checkKeyRateLimit(
+            key.rateLimit,
+            key.rateLimitState ?? undefined,
+          );
+          if (limited) {
+            throwAuthError("API_KEY_RATE_LIMITED");
+          }
+          patchData.rateLimitState = newState;
+        }
+
+        // Update lastUsedAt (and rate limit state if applicable)
+        await ctx.runMutation(config.component.public.keyPatch, {
+          keyId: key._id,
+          data: patchData,
+        });
+
+        return {
+          userId: key.userId as string,
+          keyId: key._id as string,
+          scopes: buildScopeChecker(key.scopes),
+        };
+      },
+
+      /**
+       * List all API keys for a user.
+       * Never includes the raw key — only the display prefix.
+       */
+      list: async (ctx: ComponentReadCtx, opts: { userId: string }) => {
+        return await ctx.runQuery(
+          config.component.public.keyListByUserId,
+          { userId: opts.userId as any },
+        );
+      },
+
+      /**
+       * Get a single API key by its document ID.
+       * Returns `null` if not found.
+       */
+      get: async (ctx: ComponentReadCtx, keyId: string) => {
+        return await ctx.runQuery(
+          config.component.public.keyGetById,
+          { keyId: keyId as any },
+        );
+      },
+
+      /**
+       * Update an API key's metadata (name, scopes, rate limit).
+       */
+      update: async (
+        ctx: ComponentCtx,
+        keyId: string,
+        data: {
+          name?: string;
+          scopes?: import("../types.js").KeyScope[];
+          rateLimit?: { maxRequests: number; windowMs: number };
+        },
+      ) => {
+        if (data.scopes) {
+          validateScopes(data.scopes, config.apiKeys?.scopes);
+        }
+        await ctx.runMutation(config.component.public.keyPatch, {
+          keyId: keyId as any,
+          data,
+        });
+      },
+
+      /**
+       * Revoke an API key (soft delete). The key record is preserved
+       * for audit purposes but can no longer be used for authentication.
+       */
+      revoke: async (ctx: ComponentCtx, keyId: string) => {
+        await ctx.runMutation(config.component.public.keyPatch, {
+          keyId: keyId as any,
+          data: { revoked: true },
+        });
+      },
+
+      /**
+       * Hard delete an API key record.
+       */
+      remove: async (ctx: ComponentCtx, keyId: string) => {
+        await ctx.runMutation(config.component.public.keyDelete, {
+          keyId: keyId as any,
+        });
+      },
+    },
     /**
      * Add HTTP actions for JWT verification and OAuth sign-in.
      *
@@ -707,11 +957,11 @@ export function Auth(config_: ConvexAuthConfig) {
               const pathParts = url.pathname.split("/");
               const providerId = pathParts.at(-1)!;
               if (providerId === null) {
-                throw new Error("Missing provider id");
+                throwAuthError("OAUTH_MISSING_PROVIDER");
               }
               const verifier = url.searchParams.get("code");
               if (verifier === null) {
-                throw new Error("Missing sign-in verifier");
+                throwAuthError("OAUTH_MISSING_VERIFIER");
               }
               const provider = getProviderOrThrow(
                 providerId,
@@ -800,8 +1050,10 @@ export function Auth(config_: ConvexAuthConfig) {
               );
 
               if (typeof id !== "string") {
-                throw new Error(
+                throwAuthError(
+                  "OAUTH_INVALID_PROFILE",
                   `The profile method of the ${providerId} config must return a string ID`,
+                  { provider: providerId },
                 );
               }
 
@@ -914,7 +1166,7 @@ export function Auth(config_: ConvexAuthConfig) {
             return { totpSetup: { uri: result.uri, secret: result.secret, totpId: result.totpId }, verifier: result.verifier };
           default: {
             const _typecheck: never = result;
-            throw new Error(`Unexpected result from signIn, ${result as any}`);
+            throwAuthError("INTERNAL_ERROR", `Unexpected result from signIn, ${result as any}`);
           }
         }
       },
@@ -951,10 +1203,18 @@ function convertErrorsToResponse(
     try {
       return await action(ctx, request);
     } catch (error) {
-      if (error instanceof ConvexError) {
+      if (isAuthError(error)) {
+        return new Response(
+          JSON.stringify({ code: error.data.code, message: error.data.message }),
+          {
+            status: errorStatusCode,
+            headers: { "Content-Type": "application/json" },
+          },
+        );
+      } else if (error instanceof ConvexError) {
         return new Response(null, {
           status: errorStatusCode,
-          statusText: error.data,
+          statusText: typeof error.data === "string" ? error.data : "Error",
         });
       } else {
         logError(error);

package/src/server/implementation/mutations/createAccountFromCredentials.ts

@@ -7,6 +7,7 @@ import { getAuthSessionId } from "../sessions.js";
 import { LOG_LEVELS, logWithLevel, maybeRedact } from "../utils.js";
 import { authDb } from "../db.js";
 import { AUTH_STORE_REF } from "./storeRef.js";
+import { throwAuthError } from "../../errors.js";
 
 export const createAccountFromCredentialsArgs = v.object({
   provider: v.string(),
@@ -53,7 +54,7 @@ export async function createAccountFromCredentialsImpl(
         existingAccount.secret ?? "",
       ))
     ) {
-      throw new Error(`Account ${account.id} already exists`);
+      throwAuthError("ACCOUNT_ALREADY_EXISTS", `Account ${account.id} already exists`);
     }
     return {
       account: existingAccount,

package/src/server/implementation/mutations/modifyAccount.ts

@@ -5,6 +5,7 @@ import { LOG_LEVELS, logWithLevel, maybeRedact } from "../utils.js";
 import * as Provider from "../provider.js";
 import { authDb } from "../db.js";
 import { AUTH_STORE_REF } from "./storeRef.js";
+import { throwAuthError } from "../../errors.js";
 
 export const modifyAccountArgs = v.object({
   provider: v.string(),
@@ -28,9 +29,7 @@ export async function modifyAccountImpl(
   });
   const existingAccount = await db.accounts.get(provider, account.id);
   if (existingAccount === null) {
-    throw new Error(
-      `Cannot modify account with ID ${account.id} because it does not exist`,
-    );
+    throwAuthError("ACCOUNT_NOT_FOUND", `Cannot modify account with ID ${account.id} because it does not exist`);
   }
   await db.accounts.patch(existingAccount._id, {
     secret: await hash(getProviderOrThrow(provider), account.secret),

package/src/server/implementation/mutations/userOAuth.ts

@@ -6,6 +6,7 @@ import { upsertUserAndAccount } from "../users.js";
 import { generateRandomString, logWithLevel, sha256 } from "../utils.js";
 import { authDb } from "../db.js";
 import { AUTH_STORE_REF } from "./storeRef.js";
+import { throwAuthError } from "../../errors.js";
 
 const OAUTH_SIGN_IN_EXPIRATION_MS = 1000 * 60 * 2; // 2 minutes
 
@@ -32,7 +33,7 @@ export async function userOAuthImpl(
 
   const verifier = await db.verifiers.getBySignature(signature);
   if (verifier === null) {
-    throw new Error("Invalid state");
+    throwAuthError("OAUTH_INVALID_STATE");
   }
 
   const { accountId } = await upsertUserAndAccount(

package/src/server/implementation/mutations/verifierSignature.ts

@@ -3,6 +3,7 @@ import { ActionCtx, MutationCtx } from "../types.js";
 import * as Provider from "../provider.js";
 import { authDb } from "../db.js";
 import { AUTH_STORE_REF } from "./storeRef.js";
+import { throwAuthError } from "../../errors.js";
 
 export const verifierSignatureArgs = v.object({
   verifier: v.string(),
@@ -20,7 +21,7 @@ export async function verifierSignatureImpl(
   const db = authDb(ctx, config);
   const verifierDoc = await db.verifiers.getById(verifier as GenericId<"verifier">);
   if (verifierDoc === null) {
-    throw new Error("Invalid verifier");
+    throwAuthError("INVALID_VERIFIER");
   }
   return await db.verifiers.patch(verifierDoc._id, { signature });
 }