@pablozaiden/webapp 0.5.7 → 0.6.0

package/src/server/framework-endpoints.ts

@@ -0,0 +1,451 @@
+import type { Server } from "bun";
+import type { CurrentUser, LogLevelName, WebAppConfigResponse } from "../contracts";
+import {
+  createApiKey,
+  deleteApiKey,
+  listApiKeys,
+} from "./auth/api-keys";
+import {
+  approveDevice,
+  createDeviceAuthorization,
+  denyDevice,
+  discovery,
+  exchangeDeviceCode,
+  exchangeRefreshToken,
+  getDeviceVerificationDetails,
+  jwks,
+  listAuthSessions,
+  revokeAuthSession,
+  revokeRefreshToken,
+} from "./auth/device-auth";
+import {
+  beginAuthentication,
+  beginBootstrapRegistration,
+  beginOwnerPasskeySetup,
+  beginSetupRegistration,
+  completeAuthentication,
+  completeBootstrapRegistration,
+  completeOwnerPasskeySetup,
+  completeSetupRegistration,
+  deletePasskey,
+  getSetupDetails,
+  isPasskeyAuthRequired,
+  logoutHeaders,
+  passkeyStatus,
+} from "./auth/passkeys";
+import { audit, assertValidUsername, createSetupLinkRecord, createUserRecord, summarizeUser } from "./auth/users";
+import { nowIso, randomToken } from "./auth/crypto";
+import type { WebAppStore } from "./auth/store";
+import { getRequestBaseUrl } from "./auth/request-origin";
+import type { Authentication } from "./authentication";
+import { authErrorResponse, tokenError } from "./authentication";
+import { checkSameOrigin } from "./same-origin";
+import type { WebAppServerConfig } from "./server-types";
+import { htmlResponse, type WebDocument } from "./web-document";
+import {
+  authenticationResponseSchema,
+  createApiKeyRequestSchema,
+  createUserRequestSchema,
+  deviceAuthorizationRequestSchema,
+  deviceCodeActionRequestSchema,
+  logLevelPreferenceRequestSchema,
+  passkeyBootstrapOptionsSchema,
+  refreshTokenRequestSchema,
+  registrationResponseSchema,
+  revokeRefreshTokenRequestSchema,
+  setupOptionsSchema,
+  setupVerificationSchema,
+  themePreferenceRequestSchema,
+  tokenRequestSchema,
+  userRoleRequestSchema,
+} from "./request-schemas";
+import type { RuntimeConfig } from "./runtime-config";
+import { setLogLevel } from "./logger";
+import { errorResponse, jsonResponse, notFound, parseJson, successResponse } from "./responses";
+import type { WebSocketData } from "./realtime/bus";
+
+export interface FrameworkEndpointDependencies {
+  config: RuntimeConfig;
+  store: WebAppStore;
+  authentication: Authentication;
+  version: string;
+  wsPath: string;
+  passkeysEnabled: boolean;
+  apiKeysEnabled: boolean;
+  deviceAuthEnabled: boolean;
+  configResponse?: WebAppServerConfig["configResponse"];
+  onLogLevelChange?: (level: LogLevelName) => void;
+  ensureWebDocument: () => Promise<WebDocument>;
+}
+
+function addHeaders(response: Response, headers: Headers): Response {
+  for (const [name, value] of headers) {
+    response.headers.append(name, value);
+  }
+  return response;
+}
+
+export function createFrameworkEndpointHandler(dependencies: FrameworkEndpointDependencies) {
+  const {
+    config,
+    store,
+    authentication,
+    version,
+    wsPath,
+    passkeysEnabled,
+    apiKeysEnabled,
+    deviceAuthEnabled,
+    configResponse: extendConfigResponse,
+    onLogLevelChange,
+    ensureWebDocument,
+  } = dependencies;
+
+  function configResponse(req: Request): WebAppConfigResponse & Record<string, unknown> {
+    const user = authentication.configUser(req);
+    const base = {
+      appName: config.appName,
+      version,
+      currentUser: user,
+      passkeyAuth: passkeyStatus(req, store, config, passkeysEnabled),
+      userManagement: {
+        enabled: passkeysEnabled,
+        canManageUsers: Boolean(user?.isAdmin),
+      },
+      logLevel: {
+        level: (config.logLevelFromEnv ? config.logLevel : store.getLogLevelPreference() ?? config.logLevel) as LogLevelName,
+        fromEnv: config.logLevelFromEnv,
+      },
+      apiKeys: { enabled: Boolean(apiKeysEnabled) },
+      deviceAuth: { enabled: Boolean(deviceAuthEnabled) },
+    } satisfies WebAppConfigResponse;
+    return { ...(extendConfigResponse?.(req, base) ?? {}), ...base };
+  }
+
+  function setupUrl(req: Request, token: string): string {
+    const url = new URL(`${getRequestBaseUrl(req, config)}/setup`);
+    url.search = `?token=${encodeURIComponent(token)}`;
+    url.hash = "";
+    return url.toString();
+  }
+
+  function createSetupLink(req: Request, userId: string, kind: "invite" | "reset" | "owner-reset", actorUserId?: string) {
+    const token = randomToken(32);
+    const record = createSetupLinkRecord({ userId, token, kind, createdByUserId: actorUserId });
+    store.createSetupLink(record);
+    return { url: setupUrl(req, token), expiresAt: record.expiresAt };
+  }
+
+  function ensureAdmin(auth: Parameters<Authentication["currentUser"]>[0]): CurrentUser {
+    return authentication.requireAdmin(auth);
+  }
+
+  async function handleBuiltIn(req: Request, server?: Server<WebSocketData>): Promise<Response | undefined> {
+    const url = new URL(req.url);
+    const path = url.pathname;
+    try {
+      if (path === "/api/health" && req.method === "GET") {
+        return successResponse({ ok: true, version });
+      }
+      if (path === "/api/config" && req.method === "GET") {
+        return jsonResponse(configResponse(req));
+      }
+      if (path === wsPath) {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const originFailure = checkSameOrigin(req, config, auth, "always");
+        if (originFailure) return originFailure;
+        if (!server) return errorResponse(400, "websocket_unavailable", "WebSocket server is unavailable");
+        const filters = Object.fromEntries(url.searchParams.entries());
+        const upgraded = server.upgrade(req, { data: { filters, userId: authentication.currentUser(auth)?.id } });
+        return upgraded ? undefined : errorResponse(400, "websocket_upgrade_failed", "WebSocket upgrade failed");
+      }
+      if (path === "/api/auth/status" && req.method === "GET") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const user = authentication.currentUser(auth);
+        return jsonResponse({
+          authenticated: auth.kind !== "anonymous",
+          authKind: auth.kind,
+          subject: user?.id ?? null,
+          clientId: auth.kind === "bearer" ? auth.claims.clientId : null,
+          scope: auth.kind === "bearer" ? auth.claims.scope : null,
+        });
+      }
+      if (path === "/api/passkey-auth/status" && req.method === "GET") {
+        return jsonResponse(passkeyStatus(req, store, config, passkeysEnabled));
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/bootstrap/options" && req.method === "POST") {
+        const body = await parseJson(req, passkeyBootstrapOptionsSchema);
+        const result = await beginBootstrapRegistration(req, store, config, body.username ?? "");
+        return addHeaders(jsonResponse(result.options), result.headers);
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/bootstrap/verify" && req.method === "POST") {
+        const headers = await completeBootstrapRegistration(req, store, config, await parseJson(req, registrationResponseSchema));
+        return addHeaders(successResponse(), headers);
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/owner-setup/options" && req.method === "POST") {
+        const result = await beginOwnerPasskeySetup(req, store, config);
+        return addHeaders(jsonResponse(result.options), result.headers);
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/owner-setup/verify" && req.method === "POST") {
+        const headers = await completeOwnerPasskeySetup(req, store, config, await parseJson(req, registrationResponseSchema));
+        return addHeaders(successResponse(), headers);
+      }
+      if (passkeysEnabled && path === "/api/user-setup" && req.method === "GET") {
+        const token = url.searchParams.get("token") ?? "";
+        return jsonResponse(getSetupDetails(store, token));
+      }
+      if (passkeysEnabled && path === "/api/user-setup/options" && req.method === "POST") {
+        const body = await parseJson(req, setupOptionsSchema);
+        const result = await beginSetupRegistration(req, store, config, body.token ?? "");
+        return addHeaders(jsonResponse(result.options), result.headers);
+      }
+      if (passkeysEnabled && path === "/api/user-setup/verify" && req.method === "POST") {
+        const body = await parseJson(req, setupVerificationSchema);
+        const headers = await completeSetupRegistration(req, store, config, body.token, body.response);
+        return addHeaders(successResponse(), headers);
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/authentication/options" && req.method === "POST") {
+        const result = await beginAuthentication(req, store, config);
+        return addHeaders(jsonResponse(result.options), result.headers);
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/authentication/verify" && req.method === "POST") {
+        const headers = await completeAuthentication(req, store, config, await parseJson(req, authenticationResponseSchema));
+        return addHeaders(successResponse(), headers);
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/logout" && req.method === "POST") {
+        return addHeaders(successResponse(), logoutHeaders(req, config));
+      }
+      if (passkeysEnabled && path === "/api/passkey-auth/passkey" && req.method === "DELETE") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        return addHeaders(successResponse(), deletePasskey(req, store, config, authentication.requireUser(auth).id));
+      }
+      if (apiKeysEnabled && path === "/api/api-keys" && req.method === "GET") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        return jsonResponse(listApiKeys(store, authentication.requireUser(auth).id));
+      }
+      if (apiKeysEnabled && path === "/api/api-keys" && req.method === "POST") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        return jsonResponse(createApiKey(store, authentication.requireUser(auth), await parseJson(req, createApiKeyRequestSchema)));
+      }
+      const apiKeyDelete = /^\/api\/api-keys\/([^/]+)$/.exec(path);
+      if (apiKeysEnabled && apiKeyDelete && req.method === "DELETE") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        deleteApiKey(store, authentication.requireUser(auth).id, decodeURIComponent(apiKeyDelete[1]!));
+        return successResponse();
+      }
+      if (deviceAuthEnabled && path === "/api/auth/device" && req.method === "POST") {
+        const body = await parseJson(req, deviceAuthorizationRequestSchema);
+        return jsonResponse(createDeviceAuthorization(req, store, config, body));
+      }
+      if (deviceAuthEnabled && path === "/api/auth/device/verification" && req.method === "GET") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const userCode = url.searchParams.get("user_code")?.trim();
+        if (!userCode) return errorResponse(400, "invalid_user_code", "user_code is required");
+        return jsonResponse(getDeviceVerificationDetails(store, userCode, passkeysEnabled && isPasskeyAuthRequired(store, config)));
+      }
+      if (deviceAuthEnabled && path === "/api/auth/device/approve" && req.method === "POST") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        const body = await parseJson(req, deviceCodeActionRequestSchema);
+        return jsonResponse(approveDevice(store, body.userCode, authentication.requireUser(auth).id));
+      }
+      if (deviceAuthEnabled && path === "/api/auth/device/deny" && req.method === "POST") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        const body = await parseJson(req, deviceCodeActionRequestSchema);
+        return jsonResponse(denyDevice(store, body.userCode));
+      }
+      if (deviceAuthEnabled && path === "/api/auth/refresh" && req.method === "POST") {
+        const body = await parseJson(req, refreshTokenRequestSchema);
+        try {
+          return jsonResponse(await exchangeRefreshToken(store, config, body.refresh_token, body.client_id));
+        } catch (error) {
+          return tokenError(error);
+        }
+      }
+      if (deviceAuthEnabled && path === "/api/auth/token" && req.method === "POST") {
+        const body = await parseJson(req, tokenRequestSchema);
+        try {
+          if (body.grant_type === "urn:ietf:params:oauth:grant-type:device_code" || body.device_code) {
+            return jsonResponse(await exchangeDeviceCode(store, config, body.device_code ?? "", body.client_id));
+          }
+          return jsonResponse(await exchangeRefreshToken(store, config, body.refresh_token ?? "", body.client_id));
+        } catch (error) {
+          return tokenError(error);
+        }
+      }
+      if (deviceAuthEnabled && path === "/api/auth/revoke" && req.method === "POST") {
+        const body = await parseJson(req, revokeRefreshTokenRequestSchema);
+        revokeRefreshToken(store, body.refreshToken);
+        return successResponse();
+      }
+      if (deviceAuthEnabled && path === "/api/auth/sessions" && req.method === "GET") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        return jsonResponse(listAuthSessions(store, authentication.requireUser(auth).id));
+      }
+      const sessionDelete = /^\/api\/auth\/sessions\/([^/]+)$/.exec(path);
+      if (deviceAuthEnabled && sessionDelete && req.method === "DELETE") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        return revokeAuthSession(store, authentication.requireUser(auth).id, decodeURIComponent(sessionDelete[1]!)) ? successResponse() : notFound();
+      }
+      if (deviceAuthEnabled && path === "/.well-known/jwks.json" && req.method === "GET") {
+        return jsonResponse(await jwks(store));
+      }
+      if (deviceAuthEnabled && path === "/.well-known/openid-configuration" && req.method === "GET") {
+        return jsonResponse(discovery(req, config));
+      }
+      if (passkeysEnabled && path === "/api/users" && req.method === "GET") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        ensureAdmin(auth);
+        return jsonResponse(store.listUsers().map(summarizeUser));
+      }
+      if (passkeysEnabled && path === "/api/users" && req.method === "POST") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const actor = ensureAdmin(auth);
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        const body = await parseJson(req, createUserRequestSchema);
+        const username = assertValidUsername(body.username ?? "");
+        if (store.getUserByUsername(username)) {
+          return errorResponse(409, "username_exists", "Username already exists");
+        }
+        const user = createUserRecord({ username, role: body.role ?? "user" });
+        store.createUser(user);
+        const setupLink = createSetupLink(req, user.id, "invite", actor.id);
+        audit(store, { eventType: "user_created", actorUserId: actor.id, targetUserId: user.id, metadata: { role: user.role } });
+        return jsonResponse({ user: summarizeUser(store.getUserById(user.id) ?? user), setupLink }, { status: 201 });
+      }
+      const userRolePatch = /^\/api\/users\/([^/]+)\/role$/.exec(path);
+      if (passkeysEnabled && userRolePatch && req.method === "PATCH") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const actor = ensureAdmin(auth);
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        const userId = decodeURIComponent(userRolePatch[1]!);
+        const target = store.getUserById(userId);
+        if (!target) return notFound();
+        if (target.role === "owner") return errorResponse(409, "owner_immutable", "Owner role cannot be changed");
+        const body = await parseJson(req, userRoleRequestSchema);
+        const role = body.role;
+        store.setUserRole(userId, role, nowIso());
+        audit(store, { eventType: "user_role_changed", actorUserId: actor.id, targetUserId: userId, metadata: { role } });
+        return jsonResponse(summarizeUser(store.getUserById(userId) ?? target));
+      }
+      const userReset = /^\/api\/users\/([^/]+)\/reset$/.exec(path);
+      if (passkeysEnabled && userReset && req.method === "POST") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const actor = ensureAdmin(auth);
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        const userId = decodeURIComponent(userReset[1]!);
+        const target = store.getUserById(userId);
+        if (!target) return notFound();
+        if (target.role === "owner") return errorResponse(409, "owner_immutable", "Owner cannot be reset");
+        const timestamp = nowIso();
+        store.deletePendingSetupLinksForUser(userId, timestamp);
+        store.deletePasskeysForUser(userId);
+        store.deleteApiKeysForUser(userId);
+        store.revokeRefreshSessionsForUser(userId, timestamp);
+        store.incrementUserAuthVersion(userId, timestamp);
+        const setupLink = createSetupLink(req, userId, "reset", actor.id);
+        audit(store, { eventType: "user_reset", actorUserId: actor.id, targetUserId: userId });
+        return jsonResponse({ user: summarizeUser(store.getUserById(userId) ?? target), setupLink });
+      }
+      const userDelete = /^\/api\/users\/([^/]+)$/.exec(path);
+      if (passkeysEnabled && userDelete && req.method === "DELETE") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const actor = ensureAdmin(auth);
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        const userId = decodeURIComponent(userDelete[1]!);
+        const target = store.getUserById(userId);
+        if (!target) return notFound();
+        if (target.role === "owner") return errorResponse(409, "owner_immutable", "Owner cannot be deleted");
+        if (!store.deleteUser(userId)) return notFound();
+        audit(store, { eventType: "user_deleted", actorUserId: actor.id, metadata: { deletedUserId: userId, username: target.username } });
+        return successResponse();
+      }
+      if (passkeysEnabled && path === "/api/audit-events" && req.method === "GET") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        ensureAdmin(auth);
+        return jsonResponse(store.listAuditEvents(100));
+      }
+      if (path === "/api/preferences/theme") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        const user = authentication.requireUser(auth);
+        if (req.method === "GET") {
+          return jsonResponse({ theme: store.getThemePreference(user.id) ?? "system" });
+        }
+        if (req.method === "PUT") {
+          const originFailure = checkSameOrigin(req, config, auth, "mutations");
+          if (originFailure) return originFailure;
+          const body = await parseJson(req, themePreferenceRequestSchema);
+          store.setThemePreference(body.theme, user.id);
+          return successResponse({ theme: body.theme });
+        }
+      }
+      if (path === "/api/preferences/log-level") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        ensureAdmin(auth);
+        if (req.method === "GET") {
+          return jsonResponse({ level: store.getLogLevelPreference() ?? config.logLevel, fromEnv: config.logLevelFromEnv });
+        }
+        if (req.method === "PUT") {
+          const originFailure = checkSameOrigin(req, config, auth, "mutations");
+          if (originFailure) return originFailure;
+          if (config.logLevelFromEnv) return errorResponse(409, "log_level_from_env", "Log level is controlled by environment");
+          const body = await parseJson(req, logLevelPreferenceRequestSchema);
+          store.setLogLevelPreference(body.level);
+          setLogLevel(body.level);
+          onLogLevelChange?.(body.level);
+          return successResponse({ level: body.level });
+        }
+      }
+      if (path === "/api/server/kill" && req.method === "POST") {
+        const auth = await authentication.authorize(req, true);
+        if (auth instanceof Response) return auth;
+        ensureAdmin(auth);
+        const originFailure = checkSameOrigin(req, config, auth, "mutations");
+        if (originFailure) return originFailure;
+        setTimeout(() => process.exit(0), 100);
+        return successResponse({ success: true, message: "Server is shutting down" });
+      }
+      if (deviceAuthEnabled && path === "/device" && req.method === "GET") {
+        return htmlResponse(await ensureWebDocument(), req);
+      }
+    } catch (error) {
+      return authErrorResponse(error);
+    }
+    return undefined;
+  }
+
+  return { handleBuiltIn };
+}

package/src/server/public-route-dispatch.ts

@@ -0,0 +1,85 @@
+import type {
+  PublicRouteAsset,
+  PublicRouteDefinition,
+  PublicRouteValue,
+} from "./server-types";
+import type { WebDocument } from "./web-document";
+import { methodNotAllowed, notFound, withSecurityHeaders } from "./responses";
+
+export interface PublicRouteDispatcherDependencies {
+  publicRoutes: Readonly<Record<string, PublicRouteDefinition>>;
+  generatedRoutePaths: ReadonlySet<string>;
+  ensureWebDocument: () => Promise<WebDocument>;
+}
+
+function hasOwnPublicRoute(publicRoutes: Readonly<Record<string, PublicRouteDefinition>>, path: string): boolean {
+  return Object.prototype.hasOwnProperty.call(publicRoutes, path);
+}
+
+function publicAssetResponse(asset: PublicRouteAsset, extraHeaders?: HeadersInit): Response {
+  const response = asset instanceof Response
+    ? asset
+    : typeof asset === "string"
+      ? new Response(asset, { headers: { "content-type": "text/plain; charset=utf-8" } })
+      : new Response(asset as BodyInit);
+  if (extraHeaders) {
+    for (const [name, value] of new Headers(extraHeaders)) {
+      response.headers.set(name, value);
+    }
+  }
+  return withSecurityHeaders(response);
+}
+
+async function handlePublicRouteValue(req: Request, route: PublicRouteDefinition): Promise<Response> {
+  const methodName = req.method === "HEAD" ? "HEAD" : req.method === "GET" ? "GET" : undefined;
+  if (!methodName) {
+    return withSecurityHeaders(methodNotAllowed());
+  }
+  const definition = typeof route === "object"
+    && route !== null
+    && !(route instanceof Response)
+    && !(route instanceof Blob)
+    && !(route instanceof ArrayBuffer)
+    && !(route instanceof Uint8Array)
+    && ("GET" in route || "HEAD" in route || "headers" in route)
+    ? route
+    : undefined;
+  const value = definition
+    ? definition[methodName] ?? (methodName === "HEAD" ? definition.GET : undefined)
+    : route as PublicRouteValue;
+  if (!value) {
+    return withSecurityHeaders(methodNotAllowed());
+  }
+  const asset = typeof value === "function" ? await value(req) : value;
+  if (!asset) {
+    return withSecurityHeaders(notFound());
+  }
+  const response = publicAssetResponse(asset, definition?.headers);
+  if (req.method === "HEAD") {
+    return new Response(null, { status: response.status, statusText: response.statusText, headers: response.headers });
+  }
+  return response;
+}
+
+export function createPublicRouteDispatcher(dependencies: PublicRouteDispatcherDependencies): (req: Request) => Promise<Response | undefined> {
+  const { publicRoutes, generatedRoutePaths, ensureWebDocument } = dependencies;
+
+  return async function dispatchPublicRoute(req: Request): Promise<Response | undefined> {
+    const url = new URL(req.url);
+    if (generatedRoutePaths.has(url.pathname)) {
+      const webDocument = await ensureWebDocument();
+      const generatedRoute = webDocument.generatedPublicRoutes[url.pathname];
+      if (generatedRoute) {
+        return handlePublicRouteValue(req, generatedRoute);
+      }
+    }
+    if (!hasOwnPublicRoute(publicRoutes, url.pathname)) {
+      return undefined;
+    }
+    const route = publicRoutes[url.pathname];
+    if (!route) {
+      return undefined;
+    }
+    return handlePublicRouteValue(req, route);
+  };
+}

package/src/server/request-schemas.ts

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import type { AuthenticationResponseJSON, RegistrationResponseJSON } from "@simplewebauthn/server";
+
+const nonEmptyString = z.string().min(1);
+const optionalClientId = z.string().max(200).optional();
+const authenticatorTransport = z.enum(["ble", "cable", "hybrid", "internal", "nfc", "smart-card", "usb"]);
+const clientExtensionResults = z.object({
+  appid: z.boolean().optional(),
+  credProps: z.object({ rk: z.boolean().optional() }).optional(),
+  hmacCreateSecret: z.boolean().optional(),
+});
+
+export const registrationResponseSchema: z.ZodType<RegistrationResponseJSON> = z.object({
+  id: nonEmptyString,
+  rawId: nonEmptyString,
+  response: z.object({
+    clientDataJSON: nonEmptyString,
+    attestationObject: nonEmptyString,
+    authenticatorData: nonEmptyString.optional(),
+    transports: z.array(authenticatorTransport).optional(),
+    publicKeyAlgorithm: z.number().optional(),
+    publicKey: nonEmptyString.optional(),
+  }),
+  authenticatorAttachment: z.enum(["cross-platform", "platform"]).optional(),
+  clientExtensionResults,
+  type: z.literal("public-key"),
+});
+
+export const authenticationResponseSchema: z.ZodType<AuthenticationResponseJSON> = z.object({
+  id: nonEmptyString,
+  rawId: nonEmptyString,
+  response: z.object({
+    clientDataJSON: nonEmptyString,
+    authenticatorData: nonEmptyString,
+    signature: nonEmptyString,
+    userHandle: nonEmptyString.optional(),
+  }),
+  authenticatorAttachment: z.enum(["cross-platform", "platform"]).optional(),
+  clientExtensionResults,
+  type: z.literal("public-key"),
+});
+
+export const passkeyBootstrapOptionsSchema = z.object({
+  username: z.string().max(32).optional(),
+});
+
+export const setupOptionsSchema = z.object({
+  token: z.string().max(512).optional(),
+});
+
+export const setupVerificationSchema = z.object({
+  token: nonEmptyString,
+  response: registrationResponseSchema,
+});
+
+export const createApiKeyRequestSchema = z.object({
+  name: z.string().max(200).optional(),
+  scopes: z.array(nonEmptyString).optional(),
+  prefix: z.string().min(1).max(32).regex(/^[A-Za-z0-9_-]+$/).optional(),
+  expiresAt: z.string().refine((value) => Number.isFinite(Date.parse(value)), "expiresAt must be a valid date").optional(),
+});
+
+export const deviceAuthorizationRequestSchema = z.object({
+  client_id: optionalClientId,
+  clientId: optionalClientId,
+  scope: z.string().max(512).optional(),
+}).superRefine((value, context) => {
+  if (value.client_id !== undefined && value.clientId !== undefined && value.client_id !== value.clientId) {
+    context.addIssue({ code: "custom", path: ["clientId"], message: "client_id and clientId must match when both are provided" });
+  }
+}).transform(({ client_id, clientId, scope }) => ({
+  clientId: clientId ?? client_id,
+  scope,
+}));
+
+const deviceCodeActionInput = z.object({
+  userCode: nonEmptyString.optional(),
+  user_code: nonEmptyString.optional(),
+}).superRefine((value, context) => {
+  if (value.userCode === undefined && value.user_code === undefined) {
+    context.addIssue({ code: "custom", path: ["userCode"], message: "userCode is required" });
+  } else if (value.userCode !== undefined && value.user_code !== undefined && value.userCode !== value.user_code) {
+    context.addIssue({ code: "custom", path: ["userCode"], message: "user_code and userCode must match when both are provided" });
+  }
+});
+
+export const deviceCodeActionRequestSchema = deviceCodeActionInput.transform(({ userCode, user_code }) => ({
+  userCode: userCode ?? user_code!,
+}));
+
+const tokenRequestFields = {
+  grant_type: z.enum(["refresh_token", "urn:ietf:params:oauth:grant-type:device_code"]).optional(),
+  device_code: nonEmptyString.optional(),
+  refresh_token: nonEmptyString.optional(),
+  client_id: optionalClientId,
+};
+
+export const tokenRequestSchema = z.object(tokenRequestFields).superRefine((value, context) => {
+  if (value.grant_type === "urn:ietf:params:oauth:grant-type:device_code" && value.device_code === undefined) {
+    context.addIssue({ code: "custom", path: ["device_code"], message: "device_code is required for device-code grants" });
+  }
+  if (value.grant_type === "refresh_token" && value.refresh_token === undefined) {
+    context.addIssue({ code: "custom", path: ["refresh_token"], message: "refresh_token is required for refresh grants" });
+  }
+  if (value.grant_type === undefined && value.device_code === undefined && value.refresh_token === undefined) {
+    context.addIssue({ code: "custom", path: ["grant_type"], message: "A device_code or refresh_token is required" });
+  }
+});
+
+export const refreshTokenRequestSchema = z.object({
+  grant_type: z.literal("refresh_token").optional(),
+  refresh_token: nonEmptyString,
+  client_id: optionalClientId,
+});
+
+export const revokeRefreshTokenRequestSchema = z.object({
+  refreshToken: nonEmptyString.optional(),
+  refresh_token: nonEmptyString.optional(),
+}).superRefine((value, context) => {
+  if (value.refreshToken === undefined && value.refresh_token === undefined) {
+    context.addIssue({ code: "custom", path: ["refreshToken"], message: "refresh_token is required" });
+  } else if (value.refreshToken !== undefined && value.refresh_token !== undefined && value.refreshToken !== value.refresh_token) {
+    context.addIssue({ code: "custom", path: ["refreshToken"], message: "refresh_token and refreshToken must match when both are provided" });
+  }
+}).transform(({ refreshToken, refresh_token }) => ({
+  refreshToken: refreshToken ?? refresh_token!,
+}));
+
+export const createUserRequestSchema = z.object({
+  username: z.string().max(32).optional(),
+  role: z.enum(["admin", "user"]).optional(),
+});
+
+export const userRoleRequestSchema = z.object({
+  role: z.enum(["admin", "user"]),
+});
+
+export const themePreferenceRequestSchema = z.object({
+  theme: z.enum(["system", "light", "dark"]),
+});
+
+export const logLevelPreferenceRequestSchema = z.object({
+  level: z.enum(["trace", "debug", "info", "warn", "error"]),
+});