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

package/src/server/runtime.ts

@@ -1,5 +1,6 @@
+import { Fx } from "@robelest/fx";
+import { Cv } from "@robelest/fx/convex";
 import {
-  Auth,
   GenericActionCtx,
   GenericDataModel,
   HttpRouter,
@@ -9,10 +10,10 @@ import {
 import { v } from "convex/values";
 import { serialize as serializeCookie } from "cookie";
 
-import { createCoreDomains } from "./core";
+import { configDefaults, listAvailableProviders } from "./config";
 import { redirectToParamCookie, useRedirectToParam } from "./cookies";
-import { createEnterpriseDomain } from "./enterprise/domain";
-import { addEnterpriseHttpRuntime } from "./enterprise/http";
+import { createCoreDomains } from "./core";
+import { GetProviderOrThrowFunc } from "./crypto";
 import {
   getOidcConfig,
   getPublicOidcConfig,
@@ -20,29 +21,30 @@ import {
   upsertProtocolConfig,
   withOidcSecretState,
 } from "./enterprise/config";
-import { normalizeEnterprisePolicy, patchEnterprisePolicy } from "./enterprise/policy";
+import { createEnterpriseDomain } from "./enterprise/domain";
+import { addEnterpriseHttpRuntime } from "./enterprise/http";
+import {
+  normalizeEnterprisePolicy,
+  patchEnterprisePolicy,
+} from "./enterprise/policy";
 import {
   createServiceProviderMetadata,
   getSamlServiceProviderOptions,
   parseSamlIdpMetadata,
 } from "./enterprise/saml";
-import {
-  parseScimPath,
-} from "./enterprise/scim";
+import { parseScimPath } from "./enterprise/scim";
 import {
   enterpriseOidcProviderId,
   getEnterpriseOidcUrls,
   isEnterpriseSamlSourceActive,
   normalizeDomain,
 } from "./enterprise/shared";
-import { Fx } from "@robelest/fx";
-
-import { AuthError } from "./authError";
 import {
   addAuthRoutes,
   addOpenIdRoutes,
   convertErrorsToResponse,
   createHttpAction,
+  createHttpContext,
   createHttpRoute,
   getCookies,
 } from "./http";
@@ -58,8 +60,6 @@ import {
   storeImpl,
 } from "./mutations/index";
 import { createOAuthAuthorizationURL, handleOAuthCallback } from "./oauth";
-import { GetProviderOrThrowFunc } from "./crypto";
-import { configDefaults, listAvailableProviders } from "./config";
 import { redirectAbsoluteUrl, setURLSearchParam } from "./redirects";
 import { signInImpl } from "./signin";
 import type {
@@ -171,9 +171,11 @@ export function Auth(config_: ConvexAuthConfig) {
         `Provider \`${id}\` is not configured, ` +
         `available providers are ${listAvailableProviders(config, allowExtraProviders)}.`;
       logWithLevel(LOG_LEVELS.ERROR, detail);
-      throw new AuthError("PROVIDER_NOT_CONFIGURED", detail, {
+      throw Cv.error({
+        code: "PROVIDER_NOT_CONFIGURED",
+        message: detail,
         provider: id,
-      }).toConvexError();
+      });
     }
     return provider;
   };
@@ -231,10 +233,10 @@ export function Auth(config_: ConvexAuthConfig) {
       },
     );
     if (!enterprise) {
-      throw new AuthError(
-        "INVALID_PARAMETERS",
-        enterpriseNotFoundError,
-      ).toConvexError();
+      throw Cv.error({
+        code: "INVALID_PARAMETERS",
+        message: enterpriseNotFoundError,
+      });
     }
     return enterprise;
   };
@@ -245,10 +247,10 @@ export function Auth(config_: ConvexAuthConfig) {
   ) => {
     const enterprise = await loadEnterpriseOrThrow(ctx, enterpriseId);
     if (enterprise.status !== "active") {
-      throw new AuthError(
-        "INVALID_PARAMETERS",
-        "Enterprise connection is not active.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "INVALID_PARAMETERS",
+        message: "Enterprise connection is not active.",
+      });
     }
     return enterprise;
   };
@@ -268,17 +270,17 @@ export function Auth(config_: ConvexAuthConfig) {
       enterprise,
     };
     if (!isEnterpriseSamlSourceActive(loaded)) {
-      throw new AuthError(
-        "INVALID_PARAMETERS",
-        "Enterprise connection is not active.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "INVALID_PARAMETERS",
+        message: "Enterprise connection is not active.",
+      });
     }
     const saml = getSamlConfig(loaded.config);
     if (!saml.idp?.metadataXml) {
-      throw new AuthError(
-        "PROVIDER_NOT_CONFIGURED",
-        "SAML is not configured for this enterprise.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "PROVIDER_NOT_CONFIGURED",
+        message: "SAML is not configured for this enterprise.",
+      });
     }
     return { loaded, enterprise, saml };
   };
@@ -290,10 +292,10 @@ export function Auth(config_: ConvexAuthConfig) {
     const enterprise = await loadActiveEnterpriseOrThrow(ctx, enterpriseId);
     const oidc = await getEnterpriseOidcConfigWithSecret(ctx, enterprise);
     if (oidc.enabled !== true) {
-      throw new AuthError(
-        "PROVIDER_NOT_CONFIGURED",
-        "OIDC is not configured for this enterprise.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "PROVIDER_NOT_CONFIGURED",
+        message: "OIDC is not configured for this enterprise.",
+      });
     }
     return { enterprise, oidc };
   };
@@ -407,7 +409,10 @@ export function Auth(config_: ConvexAuthConfig) {
   ) => {
     const authHeader = request.headers.get("Authorization");
     if (!authHeader?.startsWith("Bearer ")) {
-      throw new AuthError("MISSING_BEARER_TOKEN").toConvexError();
+      throw Cv.error({
+        code: "MISSING_BEARER_TOKEN",
+        message: "Missing or malformed Authorization: Bearer header.",
+      });
     }
     const token = authHeader.slice(7);
     const scimConfig = await ctx.runQuery(
@@ -415,17 +420,17 @@ export function Auth(config_: ConvexAuthConfig) {
       { tokenHash: await sha256(token) },
     );
     if (!scimConfig || scimConfig.status !== "active") {
-      throw new AuthError(
-        "INVALID_API_KEY",
-        "Invalid SCIM token.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "INVALID_API_KEY",
+        message: "Invalid SCIM token.",
+      });
     }
     const parsedPath = parseScimPath(new URL(request.url).pathname);
     if (parsedPath.enterpriseId !== scimConfig.enterpriseId) {
-      throw new AuthError(
-        "INVALID_API_KEY",
-        "SCIM token/tenant mismatch.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "INVALID_API_KEY",
+        message: "SCIM token/tenant mismatch.",
+      });
     }
     const enterprise = await ctx.runQuery(
       config.component.public.enterpriseGet,
@@ -434,10 +439,10 @@ export function Auth(config_: ConvexAuthConfig) {
       },
     );
     if (enterprise === null) {
-      throw new AuthError(
-        "INVALID_PARAMETERS",
-        "Enterprise not found.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "INVALID_PARAMETERS",
+        message: "Enterprise not found.",
+      });
     }
     return { scimConfig, enterprise, parsedPath };
   };
@@ -488,272 +493,305 @@ export function Auth(config_: ConvexAuthConfig) {
       getPolicyFromEnterprise,
       patchEnterprisePolicy,
     }),
-    // HTTP wiring stays local to the factory because it still depends on a
-    // dense mix of OAuth, SAML, SCIM, cookie, and response helpers.
-    http: {
-      /**
-       * Register core HTTP routes for JWT verification and OAuth sign-in.
-       *
-       * ```ts
-       * import { httpRouter } from "convex/server";
-       * import { auth } from "./auth";
-       *
-       * 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) => {
-        addOpenIdRoutes(http, {
-          getIssuer: () => requireEnv("CONVEX_SITE_URL"),
-          getJwks: () => requireEnv("JWKS"),
-        });
-
-        addEnterpriseHttpRuntime({
-          http,
-          hasSSO,
-          auth,
-          config,
-          routeBase: ENTERPRISE_CONTROL_ROUTE_BASE,
-          requireEnv,
-          loadActiveEnterpriseSamlOrThrow,
-          loadEnterpriseOidcOrThrow,
-          getEnterpriseScimContext,
-          getPolicyFromEnterprise,
-          normalizeEnterprisePolicy,
-          recordEnterpriseAuditEvent,
-          emitEnterpriseWebhookDeliveries,
-          generateRandomString,
-          inviteTokenAlphabet: INVITE_TOKEN_ALPHABET,
-          callUserOAuth,
-          callVerifierSignature,
-        });
+  };
 
-        if (hasOAuth) {
-          addAuthRoutes(http, {
-            handleSignIn: convertErrorsToResponse(400, async (ctx, request) => {
-              const url = new URL(request.url);
-              const pathParts = url.pathname.split("/");
-              const providerId = pathParts.at(-1)!;
-              if (providerId === null) {
-                throw new AuthError("OAUTH_MISSING_PROVIDER").toConvexError();
-              }
-              const verifier = url.searchParams.get("code");
-              if (verifier === null) {
-                throw new AuthError("OAUTH_MISSING_VERIFIER").toConvexError();
-              }
-              const provider = getProviderOrThrow(providerId);
-
-              const oauthConfig = provider as OAuthMaterializedConfig;
-              const { redirect, cookies, signature } =
-                await createOAuthAuthorizationURL(
-                  providerId,
-                  oauthConfig.provider,
-                  oauthConfig,
-                );
-
-              await callVerifierSignature(ctx, {
-                verifier,
-                signature,
+  // HTTP wiring stays local to the factory because it still depends on a
+  // dense mix of OAuth, SAML, SCIM, cookie, and response helpers.
+  auth.http = {
+    /**
+     * Register core HTTP routes for JWT verification and OAuth sign-in.
+     *
+     * ```ts
+     * import { httpRouter } from "convex/server";
+     * import { auth } from "./auth";
+     *
+     * 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) => {
+      addOpenIdRoutes(http, {
+        getIssuer: () => requireEnv("CONVEX_SITE_URL"),
+        getJwks: () => requireEnv("JWKS"),
+      });
+
+      addEnterpriseHttpRuntime({
+        http,
+        hasSSO,
+        auth,
+        config,
+        routeBase: ENTERPRISE_CONTROL_ROUTE_BASE,
+        requireEnv,
+        loadActiveEnterpriseSamlOrThrow,
+        loadEnterpriseOidcOrThrow,
+        getEnterpriseScimContext,
+        getPolicyFromEnterprise,
+        normalizeEnterprisePolicy,
+        recordEnterpriseAuditEvent,
+        emitEnterpriseWebhookDeliveries,
+        generateRandomString,
+        inviteTokenAlphabet: INVITE_TOKEN_ALPHABET,
+        callUserOAuth,
+        callVerifierSignature,
+      });
+
+      if (hasOAuth) {
+        addAuthRoutes(http, {
+          handleSignIn: convertErrorsToResponse(400, async (ctx, request) => {
+            const url = new URL(request.url);
+            const pathParts = url.pathname.split("/");
+            const providerId = pathParts[pathParts.length - 1]!;
+            if (providerId === null) {
+              throw Cv.error({
+                code: "OAUTH_MISSING_PROVIDER",
+                message: "Missing OAuth provider ID.",
               });
+            }
+            const verifier = url.searchParams.get("code");
+            if (verifier === null) {
+              throw Cv.error({
+                code: "OAUTH_MISSING_VERIFIER",
+                message: "Missing sign-in verifier.",
+              });
+            }
+            const provider = getProviderOrThrow(providerId);
 
-              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 as any),
-                );
-              }
-
-              return new Response(null, { status: 302, headers });
-            }),
-            handleCallback: async (ctx, request) => {
-              const url = new URL(request.url);
-              const providerId = new URL(request.url).pathname
-                .split("/")
-                .at(-1);
-              if (!providerId) {
-                throw new AuthError("OAUTH_MISSING_PROVIDER").toConvexError();
-              }
-              logWithLevel(
-                LOG_LEVELS.DEBUG,
-                "Handling OAuth callback for provider:",
+            const oauthConfig = provider as OAuthMaterializedConfig;
+            const { redirect, cookies, signature } =
+              await createOAuthAuthorizationURL(
                 providerId,
+                oauthConfig.provider,
+                oauthConfig,
               );
-              const provider = getProviderOrThrow(providerId);
-
-              const cookies = getCookies(request);
 
-              const maybeRedirectTo = useRedirectToParam(provider.id, cookies);
+            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 as any),
+              );
+            }
 
-              const destinationUrl = await redirectAbsoluteUrl(config, {
-                redirectTo: maybeRedirectTo?.redirectTo,
+            return new Response(null, { status: 302, headers });
+          }),
+          handleCallback: async (ctx, request) => {
+            const url = new URL(request.url);
+            const callbackPathParts = new URL(request.url).pathname.split("/");
+            const providerId = callbackPathParts[callbackPathParts.length - 1];
+            if (!providerId) {
+              throw Cv.error({
+                code: "OAUTH_MISSING_PROVIDER",
+                message: "Missing OAuth provider ID.",
               });
-
-              const params = url.searchParams;
-
-              if (
-                request.headers.get("Content-Type") ===
-                "application/x-www-form-urlencoded"
-              ) {
-                const formData = await request.formData();
-                formData.forEach((value, key) => {
-                  if (typeof value === "string") {
-                    params.append(key, value);
-                  }
-                });
-              }
-
-              return Fx.run(
-                Fx.from({
-                  ok: async () => {
-                    const oauthConfig = provider as OAuthMaterializedConfig;
-                    const result = await Fx.run(
-                      handleOAuthCallback(
-                        providerId,
-                        oauthConfig.provider,
-                        oauthConfig,
-                        Object.fromEntries(params.entries()),
-                        cookies,
-                      ),
+            }
+            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;
+
+            if (
+              request.headers.get("Content-Type") ===
+              "application/x-www-form-urlencoded"
+            ) {
+              const formData = await request.formData();
+              formData.forEach((value, key) => {
+                if (typeof value === "string") {
+                  params.append(key, value);
+                }
+              });
+            }
+
+            return Fx.run(
+              Fx.from({
+                ok: async () => {
+                  const oauthConfig = provider as OAuthMaterializedConfig;
+                  const result = await Fx.run(
+                    handleOAuthCallback(
+                      providerId,
+                      oauthConfig.provider,
+                      oauthConfig,
+                      Object.fromEntries(params.entries()),
+                      cookies,
+                    ),
+                  );
+                  const oauthCookies = result.cookies;
+                  const { id: profileId, ...profileData } = result.profile;
+                  const { signature } = result;
+
+                  const verificationCode = await callUserOAuth(ctx, {
+                    provider: providerId,
+                    providerAccountId: profileId,
+                    profile: profileData,
+                    signature,
+                  });
+
+                  const redirUrl = setURLSearchParam(
+                    destinationUrl,
+                    "code",
+                    verificationCode,
+                  );
+                  const redirHeaders = new Headers({ Location: redirUrl });
+                  redirHeaders.set("Cache-Control", "must-revalidate");
+                  for (const { name, value, options } of [
+                    ...oauthCookies,
+                    ...(maybeRedirectTo !== null
+                      ? [maybeRedirectTo.updatedCookie]
+                      : []),
+                  ] as any) {
+                    redirHeaders.append(
+                      "Set-Cookie",
+                      serializeCookie(name, value, options),
                     );
-                    const oauthCookies = result.cookies;
-                    const { id: profileId, ...profileData } = result.profile;
-                    const { signature } = result;
-
-                    const verificationCode = await callUserOAuth(ctx, {
-                      provider: providerId,
-                      providerAccountId: profileId,
-                      profile: profileData,
-                      signature,
-                    });
-
-                    const redirUrl = setURLSearchParam(
-                      destinationUrl,
-                      "code",
-                      verificationCode,
+                  }
+                  return new Response(null, {
+                    status: 302,
+                    headers: redirHeaders,
+                  });
+                },
+                err: (error) => error,
+              }).pipe(
+                Fx.recover((error) => {
+                  logError(error);
+                  const respHeaders = new Headers({
+                    Location: destinationUrl,
+                  });
+                  for (const { name, value, options } of maybeRedirectTo !== null
+                    ? [maybeRedirectTo.updatedCookie]
+                    : []) {
+                    respHeaders.append(
+                      "Set-Cookie",
+                      serializeCookie(name, value, options),
                     );
-                    const redirHeaders = new Headers({ Location: redirUrl });
-                    redirHeaders.set("Cache-Control", "must-revalidate");
-                    for (const { name, value, options } of [
-                      ...oauthCookies,
-                      ...(maybeRedirectTo !== null
-                        ? [maybeRedirectTo.updatedCookie]
-                        : []),
-                    ] as any) {
-                      redirHeaders.append(
-                        "Set-Cookie",
-                        serializeCookie(name, value, options),
-                      );
-                    }
-                    return new Response(null, {
+                  }
+                  return Fx.succeed(
+                    new Response(null, {
                       status: 302,
-                      headers: redirHeaders,
-                    });
-                  },
-                  err: (error) => error,
-                }).pipe(
-                  Fx.recover((error) => {
-                    logError(error);
-                    const respHeaders = new Headers({
-                      Location: destinationUrl,
-                    });
-                    for (const { name, value, options } of maybeRedirectTo !==
-                    null
-                      ? [maybeRedirectTo.updatedCookie]
-                      : []) {
-                      respHeaders.append(
-                        "Set-Cookie",
-                        serializeCookie(name, value, options),
-                      );
-                    }
-                    return Fx.succeed(
-                      new Response(null, {
-                        status: 302,
-                        headers: respHeaders,
-                      }),
-                    );
-                  }),
-                ),
-              );
-            },
-          });
-        }
-      },
-
-      /**
-       * 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: createHttpAction(auth),
-
-      /**
-       * 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: createHttpRoute(createHttpAction(auth)),
+                      headers: respHeaders,
+                    }),
+                  );
+                }),
+              ),
+            );
+          },
+        });
+      }
     },
+
+    /**
+     * Resolve mixed HTTP auth for a raw `httpAction`.
+     *
+     * Checks session auth first, then falls back to `Authorization: Bearer sk_*`
+     * API keys. This is the low-level helper for endpoints that intentionally
+     * accept either browser sessions or API keys.
+     * Pass `{ optional: true }` to get a null-shaped auth object instead of a
+     * `NOT_SIGNED_IN` error.
+     *
+     * ```ts
+     * http.route({
+     *   path: "/api/data",
+     *   method: "GET",
+     *   handler: httpAction(async (ctx, request) => {
+     *     const authContext = await auth.http.context(ctx, request);
+     *     return Response.json({
+     *       userId: authContext.userId,
+     *       source: authContext.source,
+     *     });
+     *   }),
+     * });
+     * ```
+     */
+    context: createHttpContext(auth),
+
+    /**
+     * 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: createHttpAction(auth),
+
+    /**
+     * 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: createHttpRoute(createHttpAction(auth)),
   };
 
   const enrichCtx = <DataModel extends GenericDataModel>(