@pablozaiden/webapp 0.5.8 → 0.6.1

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"]),
+});

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,74 @@ 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 parsePublicBaseUrl(raw: string | undefined, name: string): string | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`${name} must be a valid absolute http(s) origin; received "${raw}"`);
+  }
+  if (
+    (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+    parsed.username ||
+    parsed.password ||
+    parsed.origin === "null" ||
+    parsed.pathname !== "/" ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(`${name} must be a valid absolute http(s) origin; received "${raw}"`);
+  }
+  return parsed.origin;
+}
+
+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 +146,13 @@ 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 publicBaseUrl = parsePublicBaseUrl(readEnv(envPrefix, "PUBLIC_BASE_URL"), envName(envPrefix, "PUBLIC_BASE_URL"));
+  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,
@@ -77,8 +163,9 @@ export function readRuntimeConfig(input: {
     logLevelFromEnv: Boolean(logLevelRaw),
     passkeyDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_PASSKEY")),
     sameOriginDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_SAME_ORIGIN_CHECK")),
-    publicBaseUrl: readEnv(envPrefix, "PUBLIC_BASE_URL"),
+    publicBaseUrl,
     authIssuer: readEnv(envPrefix, "AUTH_ISSUER"),
+    trustProxy,
     development: process.env["NODE_ENV"] === "production" ? false : { hmr: true, console: true },
   };
 }
@@ -96,6 +183,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 };
+}