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

package/dist/server/implementation/index.js

@@ -1,16 +1,17 @@
 import { actionGeneric, httpActionGeneric, internalMutationGeneric, } from "convex/server";
 import { ConvexError, 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 { configDefaults, listAvailableProviders, materializeProvider, } from "../provider_utils.js";
+import { configDefaults, listAvailableProviders, materializeProvider, } from "../providers.js";
 import { requireEnv } from "../utils.js";
 import { LOG_LEVELS, TOKEN_SUB_CLAIM_DIVIDER, logError, logWithLevel, } from "./utils.js";
 import { callCreateAccountFromCredentials, callInvalidateSessions, callModifyAccount, callRetreiveAccountWithCredentials, callSignOut, callUserOAuth, callVerifierSignature, storeArgs, storeImpl, } from "./mutations/index.js";
-import { signInImpl } from "./signIn.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, oAuthConfigToInternalProvider, } from "../oauth/convexAuth.js";
+import { generateApiKey, hashApiKey, buildScopeChecker, validateScopes, checkKeyRateLimit, } from "./keys.js";
+import { getAuthorizationUrl } from "../oauth/authorization.js";
+import { defaultCookiesOptions, oAuthConfigToInternalProvider, } from "../oauth/helpers.js";
 import { handleOAuth } from "../oauth/callback.js";
 /**
  * Configure the Convex Auth library. Returns an object with
@@ -42,10 +43,10 @@ export function Auth(config_) {
     const getProviderOrThrow = (id, allowExtraProviders = false) => {
         const provider = getProvider(id, allowExtraProviders);
         if (provider === undefined) {
-            const message = `Provider \`${id}\` is not configured, ` +
+            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;
     };
@@ -54,6 +55,9 @@ export function Auth(config_) {
             /**
              * 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) => {
                 const identity = await ctx.auth.getUserIdentity();
@@ -66,24 +70,35 @@ export function Auth(config_) {
             /**
              * 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) => {
                 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;
             },
             /**
              * 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, userId) => {
                 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) => {
                 const userId = await auth.user.current(ctx);
@@ -92,6 +107,19 @@ export function Auth(config_) {
                 }
                 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, userId, data) => {
+                await ctx.runMutation(config.component.public.userPatch, {
+                    userId,
+                    data,
+                });
+            },
             /**
              * Query a user's group memberships.
              */
@@ -117,6 +145,9 @@ export function Auth(config_) {
             /**
              * 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) => {
                 const identity = await ctx.auth.getUserIdentity();
@@ -128,6 +159,10 @@ export function Auth(config_) {
             },
             /**
              * 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 (ctx, args) => {
                 const actionCtx = ctx;
@@ -137,6 +172,10 @@ export function Auth(config_) {
         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 (ctx, args) => {
                 const actionCtx = ctx;
@@ -144,17 +183,25 @@ export function Auth(config_) {
             },
             /**
              * 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 (ctx, args) => {
                 const actionCtx = ctx;
                 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 (ctx, args) => {
                 const actionCtx = ctx;
@@ -164,9 +211,16 @@ export function Auth(config_) {
         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 (ctx, provider, args) => {
-                const result = await signInImpl(enrichCtx(ctx), materializeProvider(provider), args, {
+                const result = await signInImpl(enrichCtx(ctx), materializeProvider(provider), 
+                // params type widened: Record<string, unknown> → Record<string, any>
+                args, {
                     generateTokens: false,
                     allowExtraProviders: true,
                 });
@@ -211,6 +265,7 @@ export function Auth(config_) {
              */
             list: async (ctx, opts) => {
                 return await ctx.runQuery(config.component.public.groupList, {
+                    type: opts?.type,
                     parentGroupId: opts?.parentGroupId,
                 });
             },
@@ -338,15 +393,17 @@ export function Auth(config_) {
              * 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);
@@ -373,10 +430,10 @@ export function Auth(config_) {
             /**
              * 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.
+             * @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, inviteId) => {
                 await ctx.runMutation(config.component.public.inviteRevoke, { inviteId });
@@ -482,7 +539,7 @@ export function Auth(config_) {
                 // 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, {
+                const keyId = (await ctx.runMutation(config.component.public.keyInsert, {
                     userId: opts.userId,
                     prefix: displayPrefix,
                     hashedKey,
@@ -490,8 +547,8 @@ export function Auth(config_) {
                     scopes: opts.scopes,
                     rateLimit: opts.rateLimit ?? config.apiKeys?.defaultRateLimit,
                     expiresAt: opts.expiresAt,
-                });
-                return { keyId: keyId, raw };
+                }));
+                return { keyId, raw };
             },
             /**
              * Verify a raw API key string. Returns the userId and a scope checker
@@ -503,22 +560,22 @@ export function Auth(config_) {
              */
             verify: async (ctx, rawKey) => {
                 const hashedKey = await hashApiKey(rawKey);
-                const key = await ctx.runQuery(config.component.public.keyGetByHashedKey, { hashedKey });
+                const key = (await ctx.runQuery(config.component.public.keyGetByHashedKey, { hashedKey }));
                 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 = { lastUsedAt: Date.now() };
                 if (key.rateLimit) {
                     const { limited, newState } = checkKeyRateLimit(key.rateLimit, key.rateLimitState ?? undefined);
                     if (limited) {
-                        throw new Error("API key rate limit exceeded");
+                        throwAuthError("API_KEY_RATE_LIMITED");
                     }
                     patchData.rateLimitState = newState;
                 }
@@ -538,14 +595,14 @@ export function Auth(config_) {
              * Never includes the raw key — only the display prefix.
              */
             list: async (ctx, opts) => {
-                return await ctx.runQuery(config.component.public.keyListByUserId, { userId: opts.userId });
+                return (await ctx.runQuery(config.component.public.keyListByUserId, { userId: opts.userId }));
             },
             /**
              * Get a single API key by its document ID.
              * Returns `null` if not found.
              */
             get: async (ctx, keyId) => {
-                return await ctx.runQuery(config.component.public.keyGetById, { keyId: keyId });
+                return (await ctx.runQuery(config.component.public.keyGetById, { keyId }));
             },
             /**
              * Update an API key's metadata (name, scopes, rate limit).
@@ -555,7 +612,7 @@ export function Auth(config_) {
                     validateScopes(data.scopes, config.apiKeys?.scopes);
                 }
                 await ctx.runMutation(config.component.public.keyPatch, {
-                    keyId: keyId,
+                    keyId,
                     data,
                 });
             },
@@ -565,7 +622,7 @@ export function Auth(config_) {
              */
             revoke: async (ctx, keyId) => {
                 await ctx.runMutation(config.component.public.keyPatch, {
-                    keyId: keyId,
+                    keyId,
                     data: { revoked: true },
                 });
             },
@@ -574,164 +631,317 @@ export function Auth(config_) {
              */
             remove: async (ctx, keyId) => {
                 await ctx.runMutation(config.component.public.keyDelete, {
-                    keyId: keyId,
+                    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) => {
-            http.route({
-                path: "/.well-known/openid-configuration",
-                method: "GET",
-                handler: httpActionGeneric(async () => {
-                    return new Response(JSON.stringify({
-                        issuer: requireEnv("CONVEX_SITE_URL"),
-                        jwks_uri: requireEnv("CONVEX_SITE_URL") + "/.well-known/jwks.json",
-                        authorization_endpoint: requireEnv("CONVEX_SITE_URL") + "/oauth/authorize",
-                    }), {
-                        status: 200,
-                        headers: {
-                            "Content-Type": "application/json",
-                            "Cache-Control": "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400",
-                        },
-                    });
-                }),
-            });
-            http.route({
-                path: "/.well-known/jwks.json",
-                method: "GET",
-                handler: httpActionGeneric(async () => {
-                    return new Response(requireEnv("JWKS"), {
-                        status: 200,
-                        headers: {
-                            "Content-Type": "application/json",
-                            "Cache-Control": "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400",
-                        },
-                    });
-                }),
-            });
-            if (hasOAuth) {
+        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) => {
                 http.route({
-                    pathPrefix: "/api/auth/signin/",
+                    path: "/.well-known/openid-configuration",
                     method: "GET",
-                    handler: httpActionGeneric(convertErrorsToResponse(400, async (ctx, request) => {
+                    handler: httpActionGeneric(async () => {
+                        return new Response(JSON.stringify({
+                            issuer: requireEnv("CONVEX_SITE_URL"),
+                            jwks_uri: requireEnv("CONVEX_SITE_URL") + "/.well-known/jwks.json",
+                            authorization_endpoint: requireEnv("CONVEX_SITE_URL") + "/oauth/authorize",
+                        }), {
+                            status: 200,
+                            headers: {
+                                "Content-Type": "application/json",
+                                "Cache-Control": "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400",
+                            },
+                        });
+                    }),
+                });
+                http.route({
+                    path: "/.well-known/jwks.json",
+                    method: "GET",
+                    handler: httpActionGeneric(async () => {
+                        return new Response(requireEnv("JWKS"), {
+                            status: 200,
+                            headers: {
+                                "Content-Type": "application/json",
+                                "Cache-Control": "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400",
+                            },
+                        });
+                    }),
+                });
+                if (hasOAuth) {
+                    http.route({
+                        pathPrefix: "/api/auth/signin/",
+                        method: "GET",
+                        handler: httpActionGeneric(convertErrorsToResponse(400, async (ctx, request) => {
+                            const url = new URL(request.url);
+                            const pathParts = url.pathname.split("/");
+                            const providerId = pathParts.at(-1);
+                            if (providerId === null) {
+                                throwAuthError("OAUTH_MISSING_PROVIDER");
+                            }
+                            const verifier = url.searchParams.get("code");
+                            if (verifier === null) {
+                                throwAuthError("OAUTH_MISSING_VERIFIER");
+                            }
+                            const provider = getProviderOrThrow(providerId);
+                            const { redirect, cookies, signature } = await getAuthorizationUrl({
+                                provider: await oAuthConfigToInternalProvider(provider),
+                                cookies: defaultCookiesOptions(providerId),
+                            });
+                            await callVerifierSignature(ctx, {
+                                verifier,
+                                signature,
+                            });
+                            const redirectTo = url.searchParams.get("redirectTo");
+                            if (redirectTo !== null) {
+                                cookies.push(redirectToParamCookie(providerId, redirectTo));
+                            }
+                            const headers = new Headers({ Location: redirect });
+                            for (const { name, value, options } of cookies) {
+                                headers.append("Set-Cookie", serializeCookie(name, value, options));
+                            }
+                            return new Response(null, { status: 302, headers });
+                        })),
+                    });
+                    const callbackAction = httpActionGeneric(async (genericCtx, request) => {
+                        const ctx = genericCtx;
                         const url = new URL(request.url);
                         const pathParts = url.pathname.split("/");
                         const providerId = pathParts.at(-1);
-                        if (providerId === null) {
-                            throw new Error("Missing provider id");
-                        }
-                        const verifier = url.searchParams.get("code");
-                        if (verifier === null) {
-                            throw new Error("Missing sign-in verifier");
-                        }
+                        logWithLevel(LOG_LEVELS.DEBUG, "Handling OAuth callback for provider:", providerId);
                         const provider = getProviderOrThrow(providerId);
-                        const { redirect, cookies, signature } = await getAuthorizationUrl({
-                            provider: await oAuthConfigToInternalProvider(provider),
-                            cookies: defaultCookiesOptions(providerId),
-                        });
-                        await callVerifierSignature(ctx, {
-                            verifier,
-                            signature,
+                        const cookies = getCookies(request);
+                        const maybeRedirectTo = useRedirectToParam(provider.id, cookies);
+                        const destinationUrl = await redirectAbsoluteUrl(config, {
+                            redirectTo: maybeRedirectTo?.redirectTo,
                         });
-                        const redirectTo = url.searchParams.get("redirectTo");
-                        if (redirectTo !== null) {
-                            cookies.push(redirectToParamCookie(providerId, redirectTo));
+                        const params = url.searchParams;
+                        // Handle OAuth providers that use formData (such as Apple)
+                        if (request.headers.get("Content-Type") ===
+                            "application/x-www-form-urlencoded") {
+                            const formData = await request.formData();
+                            for (const [key, value] of formData.entries()) {
+                                if (typeof value === "string") {
+                                    params.append(key, value);
+                                }
+                            }
+                        }
+                        try {
+                            const { profile, tokens, signature } = await handleOAuth(Object.fromEntries(params.entries()), cookies, {
+                                provider: await oAuthConfigToInternalProvider(provider),
+                                cookies: defaultCookiesOptions(provider.id),
+                            });
+                            const { id, ...profileFromCallback } = await provider.profile(profile, tokens);
+                            if (typeof id !== "string") {
+                                throwAuthError("OAUTH_INVALID_PROFILE", `The profile method of the ${providerId} config must return a string ID`, { provider: providerId });
+                            }
+                            const verificationCode = await callUserOAuth(ctx, {
+                                provider: providerId,
+                                providerAccountId: id,
+                                profile: profileFromCallback,
+                                signature,
+                            });
+                            return new Response(null, {
+                                status: 302,
+                                headers: {
+                                    Location: setURLSearchParam(destinationUrl, "code", verificationCode),
+                                    "Cache-Control": "must-revalidate",
+                                },
+                            });
                         }
-                        const headers = new Headers({ Location: redirect });
-                        for (const { name, value, options } of cookies) {
-                            headers.append("Set-Cookie", serializeCookie(name, value, options));
+                        catch (error) {
+                            logError(error);
+                            return Response.redirect(destinationUrl);
                         }
-                        return new Response(null, { status: 302, headers });
-                    })),
+                    });
+                    http.route({
+                        pathPrefix: "/api/auth/callback/",
+                        method: "GET",
+                        handler: callbackAction,
+                    });
+                    http.route({
+                        pathPrefix: "/api/auth/callback/",
+                        method: "POST",
+                        handler: callbackAction,
+                    });
+                }
+            },
+            /**
+             * 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, options) => {
+                const corsConfig = options?.cors ?? {};
+                const corsHeaders = {
+                    "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, code, message) => new Response(JSON.stringify({ error: message, code }), {
+                    status,
+                    headers: { ...corsHeaders, "Content-Type": "application/json" },
                 });
-                const callbackAction = httpActionGeneric(async (genericCtx, request) => {
+                return httpActionGeneric(async (genericCtx, request) => {
                     const ctx = genericCtx;
-                    const url = new URL(request.url);
-                    const pathParts = url.pathname.split("/");
-                    const providerId = pathParts.at(-1);
-                    logWithLevel(LOG_LEVELS.DEBUG, "Handling OAuth callback for provider:", providerId);
-                    const provider = getProviderOrThrow(providerId);
-                    const cookies = getCookies(request);
-                    const maybeRedirectTo = useRedirectToParam(provider.id, cookies);
-                    const destinationUrl = await redirectAbsoluteUrl(config, {
-                        redirectTo: maybeRedirectTo?.redirectTo,
-                    });
-                    const params = url.searchParams;
-                    // Handle OAuth providers that use formData (such as Apple)
-                    if (request.headers.get("Content-Type") ===
-                        "application/x-www-form-urlencoded") {
-                        const formData = await request.formData();
-                        for (const [key, value] of formData.entries()) {
-                            if (typeof value === "string") {
-                                params.append(key, value);
+                    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;
+                        try {
+                            keyResult = await auth.key.verify(ctx, rawKey);
+                        }
+                        catch (error) {
+                            if (isAuthError(error)) {
+                                const { code, message } = error.data;
+                                return jsonError(403, code, message);
                             }
+                            throw error;
                         }
-                    }
-                    try {
-                        const { profile, tokens, signature } = await handleOAuth(Object.fromEntries(params.entries()), cookies, {
-                            provider: await oAuthConfigToInternalProvider(provider),
-                            cookies: defaultCookiesOptions(provider.id),
-                        });
-                        const { id, ...profileFromCallback } = await provider.profile(profile, tokens);
-                        if (typeof id !== "string") {
-                            throw new Error(`The profile method of the ${providerId} config must return a string ID`);
+                        // 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.");
+                            }
                         }
-                        const verificationCode = await callUserOAuth(ctx, {
-                            provider: providerId,
-                            providerAccountId: id,
-                            profile: profileFromCallback,
-                            signature,
-                        });
-                        return new Response(null, {
-                            status: 302,
-                            headers: {
-                                Location: setURLSearchParam(destinationUrl, "code", verificationCode),
-                                "Cache-Control": "must-revalidate",
+                        // 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) {
                         logError(error);
-                        return Response.redirect(destinationUrl);
+                        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, routeConfig) => {
+                const corsConfig = routeConfig.cors ?? {};
+                const corsHeaders = {
+                    "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({
-                    pathPrefix: "/api/auth/callback/",
-                    method: "GET",
-                    handler: callbackAction,
+                    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({
-                    pathPrefix: "/api/auth/callback/",
-                    method: "POST",
-                    handler: callbackAction,
+                    path: routeConfig.path,
+                    method: routeConfig.method,
+                    handler: auth.http.action(routeConfig.handler, {
+                        scope: routeConfig.scope,
+                        cors: routeConfig.cors,
+                    }),
                 });
-            }
+            },
         },
     };
     const enrichCtx = (ctx) => ({
@@ -789,7 +999,7 @@ export function Auth(config_) {
                         return { totpSetup: { uri: result.uri, secret: result.secret, totpId: result.totpId }, verifier: result.verifier };
                     default: {
                         const _typecheck = result;
-                        throw new Error(`Unexpected result from signIn, ${result}`);
+                        throwAuthError("INTERNAL_ERROR", `Unexpected result from signIn, ${String(result)}`);
                     }
                 }
             },
@@ -821,10 +1031,16 @@ function convertErrorsToResponse(errorStatusCode, action) {
             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 {