@pablozaiden/webapp 0.2.0 → 0.2.2

package/src/server/auth/passkeys.ts

@@ -227,14 +227,14 @@ export function passkeyStatus(req: Request, store: WebAppStore, config: RuntimeC
   const users = store.countUsers();
   const owner = store.getOwnerUser();
   const passkeyConfigured = store.listPasskeys().length > 0;
-  const ownerPasskeySetupRequired = users > 0 && Boolean(owner && !owner.passkeyConfigured);
+  const ownerPasskeySetupRequired = enabled && !config.passkeyDisabled && users > 0 && Boolean(owner && !owner.passkeyConfigured);
   return {
     enabled,
     passkeyConfigured,
     passkeyDisabled: config.passkeyDisabled,
     passkeyRequired: enabled && users > 0 && !config.passkeyDisabled,
-    authenticated: !enabled || Boolean(getPasskeySessionUser(req, store, config)),
-    bootstrapRequired: enabled && users === 0,
+    authenticated: !enabled || config.passkeyDisabled || Boolean(getPasskeySessionUser(req, store, config)),
+    bootstrapRequired: enabled && !config.passkeyDisabled && users === 0,
     ownerPasskeySetupRequired,
   };
 }

package/src/server/create-web-app-server.ts

@@ -1,4 +1,4 @@
-import type { Server } from "bun";
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
 import type { CurrentUser, LogLevelName, ThemePreference, WebAppConfigResponse, WebAppUserRole } from "../contracts";
 import { authenticateApiKey, assertScopes, createApiKey, deleteApiKey, listApiKeys } from "./auth/api-keys";
 import {
@@ -50,6 +50,8 @@ export interface WebAppServerConfig<TEvent = unknown> {
   version?: string;
   store?: WebAppStore;
   routes?: RouteTable<TEvent>;
+  publicRoutes?: Record<string, PublicRouteDefinition>;
+  websockets?: Record<string, Partial<WebSocketHandler<WebAppWebSocketData>>>;
   auth?: {
     passkeys?: boolean | { rpName?: string; userName?: string; userDisplayName?: string };
     apiKeys?: boolean;
@@ -58,8 +60,29 @@ export interface WebAppServerConfig<TEvent = unknown> {
   realtime?: {
     path?: string;
   };
+  logLevel?: {
+    onChange?: (level: LogLevelName) => void;
+  };
 }
 
+export const WEBAPP_SOCKET_HANDLER = "webappSocketHandler";
+
+export type WebAppWebSocketData = WebSocketData & {
+  webappSocketHandler?: string;
+  [key: string]: unknown;
+};
+
+export type PublicRouteAsset = Response | Blob | ArrayBuffer | Uint8Array | string;
+export type PublicRouteHandler = (req: Request) => PublicRouteAsset | undefined | Promise<PublicRouteAsset | undefined>;
+export type PublicRouteValue = PublicRouteAsset | PublicRouteHandler;
+export type PublicRouteDefinition =
+  | PublicRouteValue
+  | {
+      GET?: PublicRouteValue;
+      HEAD?: PublicRouteValue;
+      headers?: HeadersInit;
+    };
+
 export interface WebAppServer<TEvent = unknown> {
   config: RuntimeConfig;
   store: WebAppStore;
@@ -70,6 +93,7 @@ export interface WebAppServer<TEvent = unknown> {
 }
 
 const log = createLogger("webapp:server");
+const LOG_LEVELS = new Set<LogLevelName>(["trace", "debug", "info", "warn", "error"]);
 
 function bearerToken(req: Request): string | undefined {
   const header = req.headers.get("authorization")?.trim();
@@ -127,6 +151,20 @@ function htmlResponse(index: unknown): Response {
   return index as Response;
 }
 
+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);
+}
+
 function secureDynamicResponse(response: Response): Response {
   return response instanceof Response ? withSecurityHeaders(response) : response;
 }
@@ -143,6 +181,16 @@ function currentUser(auth: AuthenticatedRequestState): CurrentUser | undefined {
   return auth.kind === "anonymous" ? undefined : auth.user;
 }
 
+function toCurrentUserRecord(user: { id: string; username: string; role: "owner" | "admin" | "user" }): CurrentUser {
+  return {
+    id: user.id,
+    username: user.username,
+    role: user.role,
+    isOwner: user.role === "owner",
+    isAdmin: user.role === "owner" || user.role === "admin",
+  };
+}
+
 function requireUser(auth: AuthenticatedRequestState): CurrentUser {
   const user = currentUser(auth);
   if (!user) {
@@ -240,15 +288,29 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
   const store = input.store ?? sqliteWebAppStore({ dataDir: config.dataDir });
   store.initialize();
   const savedLogLevel = store.getLogLevelPreference();
-  setLogLevel(config.logLevelFromEnv ? config.logLevel : savedLogLevel ?? config.logLevel);
+  const activeLogLevel = config.logLevelFromEnv ? config.logLevel : savedLogLevel ?? config.logLevel;
+  setLogLevel(activeLogLevel);
+  input.logLevel?.onChange?.(activeLogLevel);
   const realtime = createRealtimeBus<TEvent>();
   const version = input.version ?? "0.0.0-development";
   const wsPath = input.realtime?.path ?? "/api/ws";
   const routes = input.routes ?? {};
+  const publicRoutes = input.publicRoutes ?? {};
+  const appWebsockets = input.websockets ?? {};
   const passkeysEnabled = input.auth?.passkeys !== false;
   const apiKeysEnabled = input.auth?.apiKeys ?? false;
   const deviceAuthEnabled = input.auth?.deviceAuth ?? false;
 
+  function disabledAuthOwner(): CurrentUser {
+    const existing = store.getOwnerUser();
+    if (existing) {
+      return toCurrentUserRecord(existing);
+    }
+    const owner = createUserRecord({ username: "admin", role: "owner" });
+    store.createUser(owner);
+    return toCurrentUserRecord(owner);
+  }
+
   async function authorize(req: Request, required: boolean): Promise<AuthenticatedRequestState | Response> {
     const token = bearerToken(req);
     if (token) {
@@ -278,6 +340,9 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       return errorResponse(401, "invalid_token", "Bearer token is invalid");
     }
     if (passkeysEnabled) {
+      if (config.passkeyDisabled) {
+        return { kind: "passkey", user: disabledAuthOwner() };
+      }
       const user = getPasskeySessionUser(req, store, config);
       if (user) {
         return { kind: "passkey", user };
@@ -291,11 +356,16 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         }) : { kind: "anonymous" };
       }
     }
+    if (required && passkeysEnabled && !config.passkeyDisabled && store.countUsers() === 0) {
+      return errorResponse(401, "authentication_required", "Passkey authentication is required", undefined, {
+        headers: { "x-webapp-passkey-required": "true" },
+      });
+    }
     return { kind: "anonymous" };
   }
 
   function configResponse(req: Request): WebAppConfigResponse {
-    const user = passkeysEnabled ? getPasskeySessionUser(req, store, config) : undefined;
+    const user = passkeysEnabled && config.passkeyDisabled ? disabledAuthOwner() : passkeysEnabled ? getPasskeySessionUser(req, store, config) : undefined;
     return {
       appName: config.appName,
       version,
@@ -601,8 +671,12 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
           if (originFailure) return originFailure;
           if (config.logLevelFromEnv) return errorResponse(409, "log_level_from_env", "Log level is controlled by environment");
           const body = await parseJson<{ level: LogLevelName }>(req);
+          if (!LOG_LEVELS.has(body.level)) {
+            return errorResponse(400, "invalid_log_level", "Log level must be one of trace, debug, info, warn, error");
+          }
           store.setLogLevelPreference(body.level);
           setLogLevel(body.level);
+          input.logLevel?.onChange?.(body.level);
           return successResponse({ level: body.level });
         }
       }
@@ -624,78 +698,123 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     return undefined;
   }
 
-  async function handleRequest(req: Request, server?: Server<WebSocketData>): Promise<Response | undefined> {
+  async function handlePublicRoute(req: Request): Promise<Response | undefined> {
+    const url = new URL(req.url);
+    const route = publicRoutes[url.pathname];
+    if (!route) {
+      return undefined;
+    }
+    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;
+  }
+
+  async function handleMatchedRoute(req: Request, matched: NonNullable<ReturnType<typeof matchRoute<TEvent>>>, server?: Server<WebAppWebSocketData>): Promise<Response | undefined> {
+    const handler = matched.route[method(req) ?? "GET"];
+    if (!handler) {
+      return withSecurityHeaders(methodNotAllowed());
+    }
+    const routeAuth = matched.route.auth ?? "required";
+    const required = requiresAuth(routeAuth);
+    const auth = await authorize(req, required);
+    if (auth instanceof Response) {
+      return withSecurityHeaders(auth);
+    }
+    try {
+      enforceRouteAuth(routeAuth, auth);
+      if (matched.route.userParam) {
+        const paramValue = matched.params[matched.route.userParam];
+        if (!paramValue) {
+          throw new AuthError("route_misconfigured", `Route userParam "${matched.route.userParam}" is missing from matched params`, 500);
+        }
+        assertUser(auth, paramValue);
+      }
+      if (routeAuth !== "public" && (auth.kind === "api-key" || auth.kind === "bearer")) {
+        assertScopes(auth.kind === "api-key" ? auth.scopes : scopesFromBearer(auth.claims), matched.route.scopes ?? []);
+      }
+    } catch (error) {
+      return withSecurityHeaders(authErrorResponse(error));
+    }
+    const current = () => requireUser(auth);
+    const userRealtime = {
+      publishChanged: (resource, options = {}) => realtime.publishChanged(resource, { ...options, target: { ...options.target, userId: current().id } }),
+      publishEntityChanged: (resource, id, options = {}) => realtime.publishEntityChanged(resource, id, { ...options, target: { ...options.target, userId: current().id } }),
+      publishDeleted: (resource, id, options = {}) => realtime.publishDeleted(resource, id, { ...options, target: { ...options.target, userId: current().id } }),
+      publishSettingsChanged: (options = {}) => realtime.publishSettingsChanged({ ...options, target: { ...options.target, userId: current().id } }),
+    } satisfies UserScopedRealtimePublisher<TEvent>;
+    const originFailure = checkSameOrigin(req, config, auth, matched.route.sameOrigin ?? "mutations");
+    if (originFailure) {
+      return withSecurityHeaders(originFailure);
+    }
+    try {
+      const response = await handler(req, {
+        params: matched.params,
+        auth,
+        user: currentUser(auth),
+        requireUser: () => requireUser(auth),
+        requireAdmin: () => requireAdmin(auth),
+        requireOwner: () => requireOwner(auth),
+        assertUser: (userId) => assertUser(auth, userId),
+        filterOwned: createFilterOwned(auth),
+        requireOwned: createRequireOwned(auth),
+        realtime,
+        userRealtime,
+        server,
+      });
+      return response ? withSecurityHeaders(response) : undefined;
+    } catch (error) {
+      return withSecurityHeaders(routeHandlerErrorResponse(error));
+    }
+  }
+
+  async function handleRequest(req: Request, server?: Server<WebAppWebSocketData>): Promise<Response | undefined> {
     const url = new URL(req.url);
+    const publicRoute = await handlePublicRoute(req);
+    if (publicRoute) {
+      return publicRoute;
+    }
+    const matched = matchRoute(routes, url.pathname);
     if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/.well-known/") || url.pathname === "/device") {
       const builtIn = await handleBuiltIn(req, server);
       if (builtIn) {
         return secureDynamicResponse(builtIn);
       }
-      const matched = matchRoute(routes, url.pathname);
       if (!matched) {
         return withSecurityHeaders(notFound());
       }
-      const handler = matched.route[method(req) ?? "GET"];
-      if (!handler) {
-        return withSecurityHeaders(methodNotAllowed());
-      }
-      const routeAuth = matched.route.auth ?? "required";
-      const required = requiresAuth(routeAuth);
-      const auth = await authorize(req, required);
-      if (auth instanceof Response) {
-        return withSecurityHeaders(auth);
-      }
-      try {
-        enforceRouteAuth(routeAuth, auth);
-        if (matched.route.userParam) {
-          const paramValue = matched.params[matched.route.userParam];
-          if (!paramValue) {
-            throw new AuthError("route_misconfigured", `Route userParam "${matched.route.userParam}" is missing from matched params`, 500);
-          }
-          assertUser(auth, paramValue);
-        }
-        if (routeAuth !== "public" && (auth.kind === "api-key" || auth.kind === "bearer")) {
-          assertScopes(auth.kind === "api-key" ? auth.scopes : scopesFromBearer(auth.claims), matched.route.scopes ?? []);
-        }
-      } catch (error) {
-        return withSecurityHeaders(authErrorResponse(error));
-      }
-      const current = () => requireUser(auth);
-      const userRealtime = {
-        publishChanged: (resource, options = {}) => realtime.publishChanged(resource, { ...options, target: { ...options.target, userId: current().id } }),
-        publishEntityChanged: (resource, id, options = {}) => realtime.publishEntityChanged(resource, id, { ...options, target: { ...options.target, userId: current().id } }),
-        publishDeleted: (resource, id, options = {}) => realtime.publishDeleted(resource, id, { ...options, target: { ...options.target, userId: current().id } }),
-        publishSettingsChanged: (options = {}) => realtime.publishSettingsChanged({ ...options, target: { ...options.target, userId: current().id } }),
-      } satisfies UserScopedRealtimePublisher<TEvent>;
-      const originFailure = checkSameOrigin(req, config, auth, matched.route.sameOrigin ?? "mutations");
-      if (originFailure) {
-        return withSecurityHeaders(originFailure);
-      }
-      try {
-        return withSecurityHeaders(await handler(req, {
-          params: matched.params,
-          auth,
-          user: currentUser(auth),
-          requireUser: () => requireUser(auth),
-          requireAdmin: () => requireAdmin(auth),
-          requireOwner: () => requireOwner(auth),
-          assertUser: (userId) => assertUser(auth, userId),
-          filterOwned: createFilterOwned(auth),
-          requireOwned: createRequireOwned(auth),
-          realtime,
-          userRealtime,
-          server,
-        }));
-      } catch (error) {
-        return withSecurityHeaders(routeHandlerErrorResponse(error));
-      }
+      return handleMatchedRoute(req, matched, server);
+    }
+    if (matched) {
+      return handleMatchedRoute(req, matched, server);
     }
     return htmlResponse(input.index);
   }
 
-  function start(): Server<WebSocketData> {
-    const dynamicHandler = (req: Request, server: Server<WebSocketData>) => handleRequest(req, server);
-    const server = Bun.serve<WebSocketData>({
+  function customHandler(socket: ServerWebSocket<WebAppWebSocketData>): Partial<WebSocketHandler<WebAppWebSocketData>> | undefined {
+    const handlerName = socket.data.webappSocketHandler;
+    return handlerName ? appWebsockets[handlerName] : undefined;
+  }
+
+  function start(): Server<WebAppWebSocketData> {
+    const dynamicHandler = (req: Request, server: Server<WebAppWebSocketData>) => handleRequest(req, server);
+    const server = Bun.serve<WebAppWebSocketData>({
       hostname: config.host,
       port: config.port,
       routes: {
@@ -707,16 +826,34 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       },
       websocket: {
         open(socket) {
+          const handler = customHandler(socket);
+          if (handler?.open) {
+            handler.open(socket);
+            return;
+          }
           realtime.add(socket);
         },
         message(socket, message) {
+          const handler = customHandler(socket);
+          if (handler?.message) {
+            handler.message(socket, message);
+            return;
+          }
           if (message === "ping") {
             socket.send(JSON.stringify({ type: "pong" }));
           }
         },
-        close(socket) {
+        close(socket, code, reason) {
+          const handler = customHandler(socket);
+          if (handler?.close) {
+            handler.close(socket, code, reason);
+            return;
+          }
           realtime.remove(socket);
         },
+        drain(socket) {
+          customHandler(socket)?.drain?.(socket);
+        },
       },
       development: config.development,
     });

package/src/server/index.ts

@@ -1,5 +1,6 @@
 export * from "./runtime-config";
 export * from "./routes";
+export * from "./route-catalog";
 export * from "./responses";
 export * from "./create-web-app-server";
 export * from "./auth/store";

package/src/server/route-catalog.ts

@@ -0,0 +1,147 @@
+import type { HttpMethod, RouteAuth, RouteDefinition, RouteTable, SameOriginMode } from "./routes";
+
+const HTTP_METHODS: HttpMethod[] = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+export interface RouteCatalogEntry {
+  path: string;
+  cliPath: string;
+  methods: HttpMethod[];
+  auth: RouteAuth;
+  sameOrigin: SameOriginMode;
+  scopes: string[];
+  description?: string;
+  tags: string[];
+  requestSchema?: unknown;
+  querySchema?: unknown;
+  responseSchema?: unknown;
+}
+
+export interface RouteCatalogMatch {
+  entry: RouteCatalogEntry;
+  path: string;
+  params: Record<string, string>;
+}
+
+function trimSlashes(value: string): string {
+  return value.replace(/^\/+|\/+$/g, "");
+}
+
+function defaultCliPath(path: string): string {
+  return trimSlashes(path.startsWith("/api/") ? path.slice("/api/".length) : path);
+}
+
+function methodsFor(route: RouteDefinition): HttpMethod[] {
+  return HTTP_METHODS.filter((method) => typeof route[method] === "function");
+}
+
+export function createRouteCatalog<TEvent = unknown>(routes: RouteTable<TEvent>): RouteCatalogEntry[] {
+  return Object.entries(routes)
+    .filter(([, route]) => route.catalog !== false)
+    .map(([path, route]) => ({
+      path,
+      cliPath: route.cliPath ?? defaultCliPath(path),
+      methods: methodsFor(route),
+      auth: route.auth ?? "required",
+      sameOrigin: route.sameOrigin ?? "mutations",
+      scopes: route.scopes ?? [],
+      description: route.description,
+      tags: route.tags ?? [],
+      requestSchema: route.requestSchema,
+      querySchema: route.querySchema,
+      responseSchema: route.responseSchema,
+    }))
+    .filter((entry) => entry.methods.length > 0)
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function normalizeApiPath(input: string): string {
+  const [path = ""] = input.trim().split(/[?#]/);
+  if (!path) {
+    throw new Error("API endpoint is required");
+  }
+  if (path.startsWith("/api/") || path === "/api") {
+    return path;
+  }
+  if (path.startsWith("api/")) {
+    return `/${path}`;
+  }
+  if (path.startsWith("/")) {
+    return path;
+  }
+  return `/api/${path}`;
+}
+
+function normalizeCliPath(input: string): string {
+  const [path = ""] = input.trim().split(/[?#]/);
+  return trimSlashes(path.startsWith("/api/") ? path.slice("/api/".length) : path);
+}
+
+function decodePathPart(value: string): string | undefined {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function matchPattern(pattern: string, value: string): Record<string, string> | undefined {
+  const patternParts = trimSlashes(pattern).split("/").filter(Boolean);
+  const valueParts = trimSlashes(value).split("/").filter(Boolean);
+  if (patternParts.length !== valueParts.length) {
+    return undefined;
+  }
+  const params: Record<string, string> = {};
+  for (let index = 0; index < patternParts.length; index += 1) {
+    const patternPart = patternParts[index]!;
+    const valuePart = valueParts[index]!;
+    if (patternPart.startsWith(":")) {
+      const decoded = decodePathPart(valuePart);
+      if (decoded === undefined) {
+        return undefined;
+      }
+      params[patternPart.slice(1)] = decoded;
+      continue;
+    }
+    if (patternPart !== valuePart) {
+      return undefined;
+    }
+  }
+  return params;
+}
+
+function concretePath(pattern: string, params: Record<string, string>): string {
+  return trimSlashes(pattern)
+    .split("/")
+    .map((part) => part.startsWith(":") ? encodeURIComponent(params[part.slice(1)] ?? "") : part)
+    .join("/")
+    .replace(/^/, "/");
+}
+
+function specificity(entry: RouteCatalogEntry): number {
+  return entry.path.split("/").reduce((score, part) => score + (part && !part.startsWith(":") ? 2 : 1), 0);
+}
+
+export function findRouteCatalogEntry(catalog: readonly RouteCatalogEntry[], input: string): RouteCatalogMatch | undefined {
+  const apiPath = normalizeApiPath(input);
+  const cliPath = normalizeCliPath(input);
+  const sorted = [...catalog].sort((left, right) => specificity(right) - specificity(left));
+  for (const entry of sorted) {
+    if (entry.path === apiPath) {
+      return { entry, path: apiPath, params: {} };
+    }
+    if (entry.cliPath === cliPath) {
+      return { entry, path: entry.path, params: {} };
+    }
+  }
+  for (const entry of sorted) {
+    const apiParams = matchPattern(entry.path, apiPath);
+    if (apiParams) {
+      return { entry, path: apiPath, params: apiParams };
+    }
+    const cliParams = matchPattern(entry.cliPath, cliPath);
+    if (cliParams) {
+      return { entry, path: concretePath(entry.path, cliParams), params: cliParams };
+    }
+  }
+  return undefined;
+}

package/src/server/routes.ts

@@ -36,14 +36,24 @@ export interface RouteContext<TParams extends Record<string, string> = Record<st
 export type WebAppRouteHandler<TParams extends Record<string, string> = Record<string, string>, TEvent = unknown> = (
   req: Request,
   ctx: RouteContext<TParams, TEvent>,
-) => Response | Promise<Response>;
+) => Response | undefined | Promise<Response | undefined>;
+
+export interface RouteMetadata {
+  description?: string;
+  cliPath?: string;
+  tags?: string[];
+  requestSchema?: unknown;
+  querySchema?: unknown;
+  responseSchema?: unknown;
+  catalog?: boolean;
+}
 
 export type RouteDefinition<TEvent = unknown> = {
   auth?: RouteAuth;
   sameOrigin?: SameOriginMode;
   scopes?: string[];
   userParam?: string;
-} & Partial<Record<HttpMethod, WebAppRouteHandler<Record<string, string>, TEvent>>>;
+} & RouteMetadata & Partial<Record<HttpMethod, WebAppRouteHandler<Record<string, string>, TEvent>>>;
 
 export type RouteTable<TEvent = unknown> = Record<string, RouteDefinition<TEvent>>;