@robelest/convex-auth 0.0.3-preview → 0.0.3-preview.3

package/src/server/implementation/index.ts

@@ -9,20 +9,28 @@ 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";
+import { FunctionReferenceFromExport } from "../types.js";
 import {
   configDefaults,
   listAvailableProviders,
   materializeProvider,
-} from "../provider_utils.js";
+} from "../providers.js";
 import {
   AuthProviderConfig,
   ConvexAuthConfig,
+  CorsConfig,
+  HttpKeyContext,
 } from "../types.js";
 import { requireEnv } from "../utils.js";
-import { ActionCtx, MutationCtx, Tokens } from "./types.js";
+import {
+  ActionCtx,
+  MutationCtx,
+  Tokens,
+  KeyDoc,
+} from "./types.js";
 export { Doc, Tokens } from "./types.js";
 import {
   LOG_LEVELS,
@@ -42,7 +50,7 @@ import {
   storeArgs,
   storeImpl,
 } from "./mutations/index.js";
-import { signInImpl } from "./signIn.js";
+import { signInImpl } from "./signin.js";
 import { redirectAbsoluteUrl, setURLSearchParam } from "./redirects.js";
 import {
   generateApiKey,
@@ -50,12 +58,12 @@ import {
   buildScopeChecker,
   validateScopes,
   checkKeyRateLimit,
-} from "./apiKey.js";
-import { getAuthorizationUrl } from "../oauth/authorizationUrl.js";
+} from "./keys.js";
+import { getAuthorizationUrl } from "../oauth/authorization.js";
 import {
   defaultCookiesOptions,
   oAuthConfigToInternalProvider,
-} from "../oauth/convexAuth.js";
+} from "../oauth/helpers.js";
 import { handleOAuth } from "../oauth/callback.js";
 
 /**
@@ -95,7 +103,7 @@ export type SignOutAction = FunctionReferenceFromExport<
  *          `convex/auth.ts` file.
  */
 export function Auth(config_: ConvexAuthConfig) {
-  const config = configDefaults(config_ as any);
+  const config = configDefaults(config_);
   const hasOAuth = config.providers.some(
     (provider) => provider.type === "oauth" || provider.type === "oidc",
   );
@@ -113,11 +121,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;
   };
@@ -146,6 +154,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();
@@ -158,24 +169,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);
@@ -184,6 +206,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.
        */
@@ -215,6 +254,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();
@@ -226,6 +268,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>,
@@ -241,16 +287,25 @@ 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>,
         args: CreateAccountArgs,
       ) => {
         const actionCtx = ctx as unknown as ActionCtx;
-        return await callCreateAccountFromCredentials(actionCtx, args as any);
+        return await callCreateAccountFromCredentials(actionCtx, args);
       },
       /**
        * 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>,
@@ -259,12 +314,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>,
@@ -277,6 +335,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>,
@@ -289,7 +352,8 @@ export function Auth(config_: ConvexAuthConfig) {
         const result = await signInImpl(
           enrichCtx(ctx),
           materializeProvider(provider),
-          args as any,
+          // params type widened: Record<string, unknown> → Record<string, any>
+          args as { accountId?: GenericId<"account">; params?: Record<string, any> },
           {
             generateTokens: false,
             allowExtraProviders: true,
@@ -326,6 +390,7 @@ export function Auth(config_: ConvexAuthConfig) {
         data: {
           name: string;
           slug?: string;
+          type?: string;
           parentGroupId?: string;
           extend?: Record<string, unknown>;
         },
@@ -345,8 +410,12 @@ export function Auth(config_: ConvexAuthConfig) {
        * List groups. When `parentGroupId` is provided, returns children of
        * that group. When omitted, returns root-level groups (no parent).
        */
-      list: async (ctx: ComponentReadCtx, opts?: { parentGroupId?: string }) => {
+      list: async (
+        ctx: ComponentReadCtx,
+        opts?: { type?: string; parentGroupId?: string },
+      ) => {
         return await ctx.runQuery(config.component.public.groupList, {
+          type: opts?.type,
           parentGroupId: opts?.parentGroupId,
         });
       },
@@ -514,15 +583,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);
@@ -546,14 +617,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 });
       },
@@ -685,10 +756,10 @@ export function Auth(config_: ConvexAuthConfig) {
 
         const { raw, hashedKey, displayPrefix } = await generateApiKey(prefix);
 
-        const keyId = await ctx.runMutation(
+        const keyId = (await ctx.runMutation(
           config.component.public.keyInsert,
           {
-            userId: opts.userId as any,
+            userId: opts.userId,
             prefix: displayPrefix,
             hashedKey,
             name: opts.name,
@@ -696,9 +767,9 @@ export function Auth(config_: ConvexAuthConfig) {
             rateLimit: opts.rateLimit ?? config.apiKeys?.defaultRateLimit,
             expiresAt: opts.expiresAt,
           },
-        );
+        )) as string;
 
-        return { keyId: keyId as string, raw };
+        return { keyId, raw };
       },
 
       /**
@@ -719,22 +790,22 @@ export function Auth(config_: ConvexAuthConfig) {
       }> => {
         const hashedKey = await hashApiKey(rawKey);
 
-        const key = await ctx.runQuery(
+        const key = (await ctx.runQuery(
           config.component.public.keyGetByHashedKey,
           { hashedKey },
-        );
+        )) as KeyDoc | null;
         if (!key) {
-          throw new Error("Invalid API key");
+          throwAuthError("INVALID_API_KEY");
         }
         if (key.revoked) {
-          throw new Error("API key has been revoked");
+          throwAuthError("API_KEY_REVOKED");
         }
         if (key.expiresAt && key.expiresAt < Date.now()) {
-          throw new Error("API key has expired");
+          throwAuthError("API_KEY_EXPIRED");
         }
 
         // Check per-key rate limit
-        const patchData: Record<string, any> = { lastUsedAt: Date.now() };
+        const patchData: Record<string, unknown> = { lastUsedAt: Date.now() };
 
         if (key.rateLimit) {
           const { limited, newState } = checkKeyRateLimit(
@@ -742,7 +813,7 @@ export function Auth(config_: ConvexAuthConfig) {
             key.rateLimitState ?? undefined,
           );
           if (limited) {
-            throw new Error("API key rate limit exceeded");
+            throwAuthError("API_KEY_RATE_LIMITED");
           }
           patchData.rateLimitState = newState;
         }
@@ -754,8 +825,8 @@ export function Auth(config_: ConvexAuthConfig) {
         });
 
         return {
-          userId: key.userId as string,
-          keyId: key._id as string,
+          userId: key.userId,
+          keyId: key._id,
           scopes: buildScopeChecker(key.scopes),
         };
       },
@@ -764,22 +835,22 @@ export function Auth(config_: ConvexAuthConfig) {
        * 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(
+      list: async (ctx: ComponentReadCtx, opts: { userId: string }): Promise<KeyDoc[]> => {
+        return (await ctx.runQuery(
           config.component.public.keyListByUserId,
-          { userId: opts.userId as any },
-        );
+          { userId: opts.userId },
+        )) as KeyDoc[];
       },
 
       /**
        * Get a single API key by its document ID.
        * Returns `null` if not found.
        */
-      get: async (ctx: ComponentReadCtx, keyId: string) => {
-        return await ctx.runQuery(
+      get: async (ctx: ComponentReadCtx, keyId: string): Promise<KeyDoc | null> => {
+        return (await ctx.runQuery(
           config.component.public.keyGetById,
-          { keyId: keyId as any },
-        );
+          { keyId },
+        )) as KeyDoc | null;
       },
 
       /**
@@ -798,7 +869,7 @@ export function Auth(config_: ConvexAuthConfig) {
           validateScopes(data.scopes, config.apiKeys?.scopes);
         }
         await ctx.runMutation(config.component.public.keyPatch, {
-          keyId: keyId as any,
+          keyId,
           data,
         });
       },
@@ -809,7 +880,7 @@ export function Auth(config_: ConvexAuthConfig) {
        */
       revoke: async (ctx: ComponentCtx, keyId: string) => {
         await ctx.runMutation(config.component.public.keyPatch, {
-          keyId: keyId as any,
+          keyId,
           data: { revoked: true },
         });
       },
@@ -819,37 +890,41 @@ export function Auth(config_: ConvexAuthConfig) {
        */
       remove: async (ctx: ComponentCtx, keyId: string) => {
         await ctx.runMutation(config.component.public.keyDelete, {
-          keyId: keyId as any,
+          keyId,
         });
       },
     },
     /**
-     * Add HTTP actions for JWT verification and OAuth sign-in.
-     *
-     * ```ts
-     * import { httpRouter } from "convex/server";
-     * import { auth } from "./auth.js";
-     *
-     * const http = httpRouter();
-     *
-     * auth.addHttpRoutes(http);
-     *
-     * export default http;
-     * ```
-     *
-     * The following routes are handled always:
-     *
-     * - `/.well-known/openid-configuration`
-     * - `/.well-known/jwks.json`
-     *
-     * The following routes are handled if OAuth is configured:
-     *
-     * - `/api/auth/signin/*`
-     * - `/api/auth/callback/*`
-     *
-     * @param http your HTTP router
+     * HTTP namespace — route registration and Bearer-authenticated endpoints.
      */
-    addHttpRoutes: (http: HttpRouter) => {
+    http: {
+      /**
+       * Register core HTTP routes for JWT verification and OAuth sign-in.
+       *
+       * ```ts
+       * import { httpRouter } from "convex/server";
+       * import { auth } from "./auth.js";
+       *
+       * const http = httpRouter();
+       *
+       * auth.http.add(http);
+       *
+       * export default http;
+       * ```
+       *
+       * The following routes are handled always:
+       *
+       * - `/.well-known/openid-configuration`
+       * - `/.well-known/jwks.json`
+       *
+       * The following routes are handled if OAuth is configured:
+       *
+       * - `/api/auth/signin/*`
+       * - `/api/auth/callback/*`
+       *
+       * @param http your HTTP router
+       */
+      add: (http: HttpRouter) => {
       http.route({
         path: "/.well-known/openid-configuration",
         method: "GET",
@@ -899,11 +974,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,
@@ -992,8 +1067,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 },
                 );
               }
 
@@ -1035,6 +1112,203 @@ export function Auth(config_: ConvexAuthConfig) {
         });
       }
     },
+
+      /**
+       * Wrap an HTTP action handler with Bearer token authentication.
+       *
+       * Extracts the `Authorization: Bearer <key>` header, verifies the
+       * API key via `auth.key.verify()`, and injects `ctx.key` with the
+       * verified key info. Returns structured JSON error responses for
+       * missing/invalid/revoked/expired/rate-limited keys.
+       *
+       * If the handler returns a plain object, it is auto-wrapped in a
+       * `200 JSON` response. If it returns a `Response`, CORS headers
+       * are merged and the response is passed through.
+       *
+       * ```ts
+       * const handler = auth.http.action(async (ctx, request) => {
+       *   const data = await ctx.runQuery(api.data.get, { userId: ctx.key.userId });
+       *   return { data };
+       * });
+       * http.route({ path: "/api/data", method: "GET", handler });
+       * ```
+       *
+       * @param handler - Receives enriched `ctx` (with `ctx.key`) and the raw `Request`.
+       * @param options.scope - Optional scope check; returns 403 if the key lacks permission.
+       * @param options.cors - CORS config; defaults to permissive (`*`).
+       */
+      action: (
+        handler: (
+          ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext,
+          request: Request,
+        ) => Promise<Response | Record<string, unknown>>,
+        options?: {
+          scope?: { resource: string; action: string };
+          cors?: CorsConfig;
+        },
+      ) => {
+        const corsConfig = options?.cors ?? {};
+        const corsHeaders: Record<string, string> = {
+          "Access-Control-Allow-Origin": corsConfig.origin ?? "*",
+          "Access-Control-Allow-Methods":
+            corsConfig.methods ?? "GET,POST,PUT,PATCH,DELETE,OPTIONS",
+          "Access-Control-Allow-Headers":
+            corsConfig.headers ?? "Content-Type,Authorization",
+        };
+
+        const jsonError = (
+          status: number,
+          code: string,
+          message: string,
+        ) =>
+          new Response(JSON.stringify({ error: message, code }), {
+            status,
+            headers: { ...corsHeaders, "Content-Type": "application/json" },
+          });
+
+        return httpActionGeneric(async (genericCtx, request) => {
+          const ctx = genericCtx as unknown as GenericActionCtx<GenericDataModel>;
+
+          try {
+            // 1. Extract Bearer token
+            const authHeader = request.headers.get("Authorization");
+            if (!authHeader?.startsWith("Bearer ")) {
+              return jsonError(
+                401,
+                "MISSING_BEARER_TOKEN",
+                "Missing or malformed Authorization: Bearer header.",
+              );
+            }
+            const rawKey = authHeader.slice(7);
+
+            // 2. Verify API key
+            let keyResult: { userId: string; keyId: string; scopes: import("../types.js").ScopeChecker };
+            try {
+              keyResult = await auth.key.verify(ctx, rawKey);
+            } catch (error: unknown) {
+              if (isAuthError(error)) {
+                const { code, message } = error.data as { code: string; message: string };
+                return jsonError(403, code, message);
+              }
+              throw error;
+            }
+
+            // 3. Optional scope check
+            if (options?.scope) {
+              if (!keyResult.scopes.can(options.scope.resource, options.scope.action)) {
+                return jsonError(
+                  403,
+                  "SCOPE_CHECK_FAILED",
+                  "This API key does not have the required permissions.",
+                );
+              }
+            }
+
+            // 4. Enrich context with key info
+            const enrichedCtx = Object.assign(ctx, {
+              key: {
+                userId: keyResult.userId,
+                keyId: keyResult.keyId,
+                scopes: keyResult.scopes,
+              },
+            });
+
+            // 5. Call handler
+            const result = await handler(enrichedCtx, request);
+
+            // 6. Auto-wrap plain objects as JSON responses
+            if (result instanceof Response) {
+              // Merge CORS headers into existing response
+              const headers = new Headers(result.headers);
+              for (const [k, val] of Object.entries(corsHeaders)) {
+                if (!headers.has(k)) headers.set(k, val);
+              }
+              return new Response(result.body, {
+                status: result.status,
+                statusText: result.statusText,
+                headers,
+              });
+            }
+
+            return new Response(JSON.stringify(result), {
+              status: 200,
+              headers: { ...corsHeaders, "Content-Type": "application/json" },
+            });
+          } catch (error: unknown) {
+            logError(error);
+            return jsonError(500, "INTERNAL_ERROR", "An unexpected error occurred.");
+          }
+        });
+      },
+
+      /**
+       * Register a Bearer-authenticated route **and** its OPTIONS preflight
+       * in a single call.
+       *
+       * ```ts
+       * auth.http.route(http, {
+       *   path: "/api/messages",
+       *   method: "POST",
+       *   handler: async (ctx, request) => {
+       *     const { body } = await request.json();
+       *     await ctx.runMutation(internal.messages.sendAsUser, {
+       *       userId: ctx.key.userId,
+       *       body,
+       *     });
+       *     return { success: true };
+       *   },
+       * });
+       * ```
+       *
+       * @param http - The Convex HTTP router.
+       * @param routeConfig.path - The URL path to match.
+       * @param routeConfig.method - HTTP method (GET, POST, PUT, PATCH, DELETE).
+       * @param routeConfig.handler - Receives enriched `ctx` (with `ctx.key`) and the raw `Request`.
+       * @param routeConfig.scope - Optional scope check; returns 403 if the key lacks permission.
+       * @param routeConfig.cors - CORS config; defaults to permissive (`*`).
+       */
+      route: (
+        http: HttpRouter,
+        routeConfig: {
+          path: string;
+          method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+          handler: (
+            ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext,
+            request: Request,
+          ) => Promise<Response | Record<string, unknown>>;
+          scope?: { resource: string; action: string };
+          cors?: CorsConfig;
+        },
+      ) => {
+        const corsConfig = routeConfig.cors ?? {};
+        const corsHeaders: Record<string, string> = {
+          "Access-Control-Allow-Origin": corsConfig.origin ?? "*",
+          "Access-Control-Allow-Methods":
+            corsConfig.methods ?? "GET,POST,PUT,PATCH,DELETE,OPTIONS",
+          "Access-Control-Allow-Headers":
+            corsConfig.headers ?? "Content-Type,Authorization",
+        };
+
+        // Register OPTIONS preflight
+        http.route({
+          path: routeConfig.path,
+          method: "OPTIONS",
+          handler: httpActionGeneric(async () => {
+            return new Response(null, { status: 204, headers: corsHeaders });
+          }),
+        });
+
+        // Register the main route with Bearer auth wrapping
+        http.route({
+          path: routeConfig.path,
+          method: routeConfig.method,
+          handler: auth.http.action(routeConfig.handler, {
+            scope: routeConfig.scope,
+            cors: routeConfig.cors,
+          }),
+        });
+      },
+    },
   };
   const enrichCtx = <DataModel extends GenericDataModel>(
     ctx: GenericActionCtx<DataModel>,
@@ -1106,7 +1380,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, ${String(result)}`);
           }
         }
       },
@@ -1143,10 +1417,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);