@pablozaiden/webapp 0.5.8 → 0.6.0

package/src/server/responses.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import type { WebAppErrorResponse } from "../contracts";
 
 export function jsonResponse<T>(data: T, init: ResponseInit = {}): Response {
@@ -27,12 +28,77 @@ export function methodNotAllowed(): Response {
   return errorResponse(405, "method_not_allowed", "Method not allowed");
 }
 
-export async function parseJson<T>(req: Request): Promise<T> {
+export class InvalidJsonError extends Error {
+  readonly code = "invalid_json";
+  readonly status = 400;
+
+  constructor() {
+    super("Request body must be valid JSON");
+    this.name = "InvalidJsonError";
+  }
+}
+
+export interface RequestBodyValidationIssue {
+  path: Array<string | number>;
+  code: string;
+  message: string;
+}
+
+export class InvalidRequestBodyError extends Error {
+  readonly code = "invalid_request_body";
+  readonly status = 400;
+  readonly details: RequestBodyValidationIssue[];
+
+  constructor(error: z.ZodError) {
+    super("Request body failed validation");
+    this.name = "InvalidRequestBodyError";
+    this.details = error.issues.map((issue) => ({
+      path: issue.path.map((segment) => typeof segment === "symbol" ? String(segment) : segment),
+      code: issue.code,
+      message: issue.message,
+    }));
+  }
+}
+
+export function requestBodyErrorResponse(error: unknown): Response | undefined {
+  if (error instanceof InvalidJsonError || error instanceof InvalidRequestBodyError) {
+    return errorResponse(error.status, error.code, error.message, "details" in error ? error.details : undefined);
+  }
+  return undefined;
+}
+
+function validateJson<TSchema extends z.ZodTypeAny>(value: unknown, schema: TSchema): z.infer<TSchema> {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    throw new InvalidRequestBodyError(result.error);
+  }
+  return result.data;
+}
+
+export async function parseUnknownJson(req: Request): Promise<unknown> {
+  try {
+    return await req.json();
+  } catch {
+    throw new InvalidJsonError();
+  }
+}
+
+export async function parseJson<TSchema extends z.ZodTypeAny>(req: Request, schema: TSchema): Promise<z.infer<TSchema>> {
+  return validateJson(await parseUnknownJson(req), schema);
+}
+
+export async function parseOptionalJson<TSchema extends z.ZodTypeAny>(req: Request, schema: TSchema): Promise<z.infer<TSchema> | undefined> {
+  const text = await req.text();
+  if (text.length === 0) {
+    return undefined;
+  }
+  let value: unknown;
   try {
-    return await req.json() as T;
+    value = JSON.parse(text);
   } catch {
-    throw new Error("Request body must be valid JSON");
+    throw new InvalidJsonError();
   }
+  return validateJson(value, schema);
 }
 
 export function applySecurityHeaders(headers: Headers): Headers {

package/src/server/route-dispatch.ts

@@ -0,0 +1,109 @@
+import type { Server } from "bun";
+import { assertScopes } from "./auth/api-keys";
+import { AuthError } from "./auth/types";
+import { authErrorResponse, enforceRouteAuth, requiresAuth, scopesFromBearer, type Authentication } from "./authentication";
+import type { RuntimeConfig } from "./runtime-config";
+import { createLogger } from "./logger";
+import { checkSameOrigin } from "./same-origin";
+import type { RealtimeBus } from "./realtime/bus";
+import { matchRoute, type HttpMethod, type RouteTable, type UserScopedRealtimePublisher } from "./routes";
+import type { WebAppWebSocketData } from "./server-types";
+import { errorResponse, requestBodyErrorResponse, withSecurityHeaders, methodNotAllowed } from "./responses";
+
+export interface RouteDispatchResult {
+  matched: boolean;
+  response?: Response;
+}
+
+export interface RouteDispatcherDependencies<TEvent = unknown> {
+  config: RuntimeConfig;
+  routes: RouteTable<TEvent>;
+  authentication: Authentication;
+  realtime: RealtimeBus<TEvent>;
+}
+
+const log = createLogger("webapp:routes");
+
+function method(req: Request): HttpMethod | undefined {
+  const value = req.method.toUpperCase();
+  return value === "GET" || value === "POST" || value === "PUT" || value === "PATCH" || value === "DELETE" ? value : undefined;
+}
+
+function routeHandlerErrorResponse(error: unknown): Response {
+  const requestBodyFailure = requestBodyErrorResponse(error);
+  if (requestBodyFailure) {
+    return requestBodyFailure;
+  }
+  if (error instanceof AuthError) {
+    return errorResponse(error.status, error.code, error.message);
+  }
+  log.error("Unhandled route handler error", { error: error instanceof Error ? error.message : String(error) });
+  return errorResponse(500, "request_failed", "Request failed");
+}
+
+export function createRouteDispatcher<TEvent = unknown>(dependencies: RouteDispatcherDependencies<TEvent>) {
+  const { config, routes, authentication, realtime } = dependencies;
+
+  return {
+    async dispatch(req: Request, server?: Server<WebAppWebSocketData>): Promise<RouteDispatchResult> {
+      const matched = matchRoute(routes, new URL(req.url).pathname);
+      if (!matched) {
+        return { matched: false };
+      }
+      const handler = matched.route[method(req) ?? "GET"];
+      if (!handler) {
+        return { matched: true, response: withSecurityHeaders(methodNotAllowed()) };
+      }
+      const routeAuth = matched.route.auth ?? "required";
+      const auth = await authentication.authorize(req, requiresAuth(routeAuth));
+      if (auth instanceof Response) {
+        return { matched: true, response: withSecurityHeaders(auth) };
+      }
+      try {
+        enforceRouteAuth(routeAuth, auth, authentication);
+        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);
+          }
+          authentication.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 { matched: true, response: withSecurityHeaders(authErrorResponse(error)) };
+      }
+      const current = () => authentication.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 { matched: true, response: withSecurityHeaders(originFailure) };
+      }
+      try {
+        const response = await handler(req, {
+          params: matched.params,
+          auth,
+          user: authentication.currentUser(auth),
+          requireUser: () => authentication.requireUser(auth),
+          requireAdmin: () => authentication.requireAdmin(auth),
+          requireOwner: () => authentication.requireOwner(auth),
+          assertUser: (userId) => authentication.assertUser(auth, userId),
+          filterOwned: authentication.createFilterOwned(auth),
+          requireOwned: authentication.createRequireOwned(auth),
+          realtime,
+          userRealtime,
+          server,
+        });
+        return { matched: true, response: response ? withSecurityHeaders(response) : undefined };
+      } catch (error) {
+        return { matched: true, response: withSecurityHeaders(routeHandlerErrorResponse(error)) };
+      }
+    },
+  };
+}

package/src/server/runtime-config.ts

@@ -1,5 +1,15 @@
 import type { LogLevelName } from "../contracts";
 
+export const TRUST_PROXY_HEADERS = ["proto", "host", "prefix"] as const;
+export type TrustProxyHeader = typeof TRUST_PROXY_HEADERS[number];
+export type TrustProxyChain = "first" | "last";
+
+export interface TrustProxyConfig {
+  enabled: boolean;
+  headers: readonly TrustProxyHeader[];
+  chain: TrustProxyChain;
+}
+
 export interface RuntimeConfig {
   appName: string;
   envPrefix: string;
@@ -12,6 +22,7 @@ export interface RuntimeConfig {
   sameOriginDisabled: boolean;
   publicBaseUrl?: string;
   authIssuer?: string;
+  trustProxy: TrustProxyConfig;
   development: false | { hmr: true; console: true };
 }
 
@@ -59,6 +70,50 @@ function parseLogLevel(raw: string | undefined, fallback: LogLevelName, name: st
   return raw as LogLevelName;
 }
 
+function parseBoolean(raw: string | undefined, fallback: boolean, name: string): boolean {
+  if (raw === undefined) {
+    return fallback;
+  }
+  const normalized = raw.toLowerCase();
+  if (normalized === "true" || normalized === "1" || normalized === "yes") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0" || normalized === "no") {
+    return false;
+  }
+  throw new Error(`${name} must be true or false; received "${raw}"`);
+}
+
+function parseTrustProxyHeaders(raw: string | undefined, enabled: boolean, name: string): TrustProxyHeader[] {
+  if (raw === undefined) {
+    return enabled ? [...TRUST_PROXY_HEADERS] : [];
+  }
+  const values = raw.split(",").map((value) => value.trim().toLowerCase());
+  if (values.length === 0 || values.some((value) => !value)) {
+    throw new Error(`${name} must be a comma-separated list of proto, host, and prefix; received "${raw}"`);
+  }
+  const headers: TrustProxyHeader[] = [];
+  for (const value of values) {
+    const header = TRUST_PROXY_HEADERS.find((candidate) => candidate === value);
+    if (!header) {
+      throw new Error(`${name} must contain only proto, host, and prefix; received "${raw}"`);
+    }
+    if (headers.includes(header)) {
+      throw new Error(`${name} must not contain duplicate values; received "${raw}"`);
+    }
+    headers.push(header);
+  }
+  return headers;
+}
+
+function parseTrustProxyChain(raw: string | undefined, name: string): TrustProxyChain {
+  const value = raw?.toLowerCase() ?? "first";
+  if (value === "first" || value === "last") {
+    return value;
+  }
+  throw new Error(`${name} must be first or last; received "${raw}"`);
+}
+
 export function readRuntimeConfig(input: {
   appName: string;
   envPrefix: string;
@@ -67,6 +122,12 @@ export function readRuntimeConfig(input: {
   const envPrefix = assertEnvPrefix(input.envPrefix);
   const logLevelRaw = readEnv(envPrefix, "LOG_LEVEL");
   const logLevel = parseLogLevel(logLevelRaw, input.defaultLogLevel ?? "info", envName(envPrefix, "LOG_LEVEL"));
+  const trustProxyEnabled = parseBoolean(readEnv(envPrefix, "TRUST_PROXY"), false, envName(envPrefix, "TRUST_PROXY"));
+  const trustProxy = {
+    enabled: trustProxyEnabled,
+    headers: parseTrustProxyHeaders(readEnv(envPrefix, "TRUST_PROXY_HEADERS"), trustProxyEnabled, envName(envPrefix, "TRUST_PROXY_HEADERS")),
+    chain: parseTrustProxyChain(readEnv(envPrefix, "TRUST_PROXY_CHAIN"), envName(envPrefix, "TRUST_PROXY_CHAIN")),
+  } satisfies TrustProxyConfig;
   return {
     appName: input.appName,
     envPrefix,
@@ -79,6 +140,7 @@ export function readRuntimeConfig(input: {
     sameOriginDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_SAME_ORIGIN_CHECK")),
     publicBaseUrl: readEnv(envPrefix, "PUBLIC_BASE_URL"),
     authIssuer: readEnv(envPrefix, "AUTH_ISSUER"),
+    trustProxy,
     development: process.env["NODE_ENV"] === "production" ? false : { hmr: true, console: true },
   };
 }
@@ -96,6 +158,11 @@ export function safeRuntimeConfig(config: RuntimeConfig): Record<string, unknown
     sameOriginDisabled: config.sameOriginDisabled,
     publicBaseUrl: config.publicBaseUrl,
     authIssuer: config.authIssuer,
+    trustProxy: {
+      enabled: config.trustProxy.enabled,
+      headers: [...config.trustProxy.headers],
+      chain: config.trustProxy.chain,
+    },
     production: config.development === false,
   };
 }

package/src/server/same-origin.ts

@@ -18,7 +18,7 @@ export function checkSameOrigin(req: Request, config: RuntimeConfig, auth: Authe
   if (mode !== "always" && (auth.kind === "api-key" || auth.kind === "bearer")) {
     return undefined;
   }
-  const expectedOrigin = getRequestOriginInfo(req, config.publicBaseUrl).origin;
+  const expectedOrigin = getRequestOriginInfo(req, config).origin;
   const origin = req.headers.get("origin");
   if (origin) {
     return origin === expectedOrigin ? undefined : errorResponse(403, "same_origin_required", "Request origin is not allowed");

package/src/server/server-lifecycle.ts

@@ -0,0 +1,138 @@
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import { createLogger } from "./logger";
+import type { RealtimeBus } from "./realtime/bus";
+import type { WebAppWebSocketData, WebAppServerConfig } from "./server-types";
+import type { RuntimeConfig } from "./runtime-config";
+import { safeRuntimeConfig } from "./runtime-config";
+import type { WebDocument, WebDocumentProvider } from "./web-document";
+
+export interface ServerLifecycleDependencies<TEvent = unknown> {
+  config: RuntimeConfig;
+  version: string;
+  deviceAuthEnabled: boolean;
+  publicRoutes: Readonly<Record<string, unknown>>;
+  appWebsockets: NonNullable<WebAppServerConfig["websockets"]>;
+  realtime: RealtimeBus<TEvent>;
+  ensureWebDocument: () => Promise<WebDocument>;
+  documentProvider: WebDocumentProvider;
+  handleRequest: (req: Request, server?: Server<WebAppWebSocketData>) => Promise<Response | undefined>;
+}
+
+const log = createLogger("webapp:server");
+
+export function createServerLifecycle<TEvent = unknown>(dependencies: ServerLifecycleDependencies<TEvent>) {
+  const {
+    config,
+    version,
+    deviceAuthEnabled,
+    publicRoutes,
+    appWebsockets,
+    realtime,
+    ensureWebDocument,
+    documentProvider,
+    handleRequest,
+  } = dependencies;
+
+  function customHandler(socket: ServerWebSocket<WebAppWebSocketData>): Partial<WebSocketHandler<WebAppWebSocketData>> | undefined {
+    const handlerName = socket.data.webappSocketHandler;
+    return handlerName ? appWebsockets[handlerName] : undefined;
+  }
+
+  async function start(): Promise<Server<WebAppWebSocketData>> {
+    const webDocument = await ensureWebDocument();
+    const dynamicHandler = (req: Request, server: Server<WebAppWebSocketData>) => handleRequest(req, server);
+    const publicRouteHandlers = Object.fromEntries([
+      ...Object.keys(webDocument.generatedPublicRoutes),
+      ...Object.keys(publicRoutes),
+    ].map((path) => [path, dynamicHandler]));
+    const spaFallbackRoute = {
+      GET: dynamicHandler,
+      HEAD: dynamicHandler,
+      POST: dynamicHandler,
+      PUT: dynamicHandler,
+      PATCH: dynamicHandler,
+      DELETE: dynamicHandler,
+      OPTIONS: dynamicHandler,
+    };
+    // Bun only transforms HTMLBundle modules/HMR when the bundle is mounted directly.
+    // Wrapping it in a handler or Response, or adding route-level headers, serves
+    // untransformed module paths and breaks generated document routes.
+    const spaDocumentRoute = webDocument.bundle ? {
+      ...spaFallbackRoute,
+      GET: webDocument.bundle as never,
+      HEAD: webDocument.bundle as never,
+    } : spaFallbackRoute;
+    const entryRoute = webDocument.bundle ? { [webDocument.entryPublicPath]: webDocument.bundle as never } : {};
+    const server = Bun.serve<WebAppWebSocketData>({
+      hostname: config.host,
+      port: config.port,
+      routes: {
+        ...publicRouteHandlers,
+        ...entryRoute,
+        "/api/*": dynamicHandler,
+        "/.well-known/*": dynamicHandler,
+        "/device": deviceAuthEnabled ? spaDocumentRoute : dynamicHandler,
+        "/setup": spaDocumentRoute,
+        "/*": spaDocumentRoute,
+      },
+      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, 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,
+    });
+    const stop = server.stop.bind(server);
+    server.stop = ((closeActiveConnections?: boolean) => {
+      stop(closeActiveConnections);
+      documentProvider.dispose(webDocument);
+    }) as typeof server.stop;
+    log.info(`${config.appName} server running`, { url: String(server.url) });
+    return server;
+  }
+
+  async function runFromCli(argv = Bun.argv.slice(2)): Promise<void> {
+    const command = argv[0] ?? "serve";
+    if (command === "serve") {
+      await start();
+      return await new Promise(() => undefined);
+    }
+    if (command === "version") {
+      console.log(version);
+      return;
+    }
+    if (command === "config") {
+      console.log(JSON.stringify(safeRuntimeConfig(config), null, 2));
+      return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  return { start, runFromCli };
+}

package/src/server/server-types.ts

@@ -0,0 +1,87 @@
+import type { Server, WebSocketHandler } from "bun";
+import type { LogLevelName, WebAppConfigResponse } from "../contracts";
+import type { RealtimeBus, WebSocketData } from "./realtime/bus";
+import type { WebAppStore } from "./auth/store";
+import type { RuntimeConfig } from "./runtime-config";
+import type { RouteTable } from "./routes";
+
+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 WebAppServerConfig<TEvent = unknown> {
+  appName: string;
+  envPrefix: string;
+  web?: WebAppDocumentConfig;
+  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;
+    deviceAuth?: boolean;
+  };
+  realtime?: {
+    path?: string;
+  };
+  logLevel?: {
+    onChange?: (level: LogLevelName) => void;
+  };
+  configResponse?: (req: Request, base: Readonly<WebAppConfigResponse>) => Record<string, unknown>;
+}
+
+export interface WebAppServer<TEvent = unknown> {
+  config: RuntimeConfig;
+  store: WebAppStore;
+  realtime: RealtimeBus<TEvent>;
+  handleRequest(req: Request, server?: Server<WebSocketData>): Promise<Response | undefined>;
+  start(): Promise<Server<WebSocketData>>;
+  runFromCli(argv?: string[]): Promise<void>;
+}
+
+export interface WebAppDocumentConfig {
+  entry?: string | URL;
+  title?: string;
+  shortName?: string;
+  lang?: string;
+  pwa?: boolean | WebAppPwaConfig;
+  themeColor?: string;
+  backgroundColor?: string;
+  icons?: WebAppIconsConfig;
+}
+
+export interface WebAppPwaConfig {
+  enabled?: boolean;
+  display?: "standalone" | "fullscreen" | "minimal-ui" | "browser";
+  startUrl?: string;
+  scope?: string;
+}
+
+export interface WebAppIconConfig {
+  src: string | URL;
+  sizes?: string;
+  type?: string;
+  purpose?: string;
+}
+
+export interface WebAppIconsConfig {
+  favicon?: string | URL | WebAppIconConfig;
+  appleTouch?: string | URL | WebAppIconConfig;
+  manifest?: WebAppIconConfig[];
+}