@pablozaiden/webapp 0.1.0 → 0.2.1

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

@@ -1,5 +1,5 @@
-import type { Server } from "bun";
-import type { ApiKeySummary, LogLevelName, ThemePreference, WebAppConfigResponse } from "../contracts";
+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 {
   approveDevice,
@@ -17,11 +17,16 @@ import {
 } from "./auth/device-auth";
 import {
   beginAuthentication,
-  beginRegistration,
+  beginBootstrapRegistration,
+  beginOwnerPasskeySetup,
+  beginSetupRegistration,
   completeAuthentication,
-  completeRegistration,
+  completeBootstrapRegistration,
+  completeOwnerPasskeySetup,
+  completeSetupRegistration,
   deletePasskey,
-  hasPasskeySession,
+  getPasskeySessionUser,
+  getSetupDetails,
   isPasskeyAuthRequired,
   logoutHeaders,
   passkeyStatus,
@@ -29,10 +34,12 @@ import {
 import { sqliteWebAppStore } from "./auth/sqlite-store";
 import type { WebAppStore } from "./auth/store";
 import { AuthError, type AuthenticatedRequestState } from "./auth/types";
+import { audit, assertValidUsername, createSetupLinkRecord, createUserRecord, summarizeUser } from "./auth/users";
+import { nowIso, randomToken } from "./auth/crypto";
 import { createLogger, setLogLevel } from "./logger";
 import { createRealtimeBus, type RealtimeBus, type WebSocketData } from "./realtime/bus";
 import { readRuntimeConfig, safeRuntimeConfig, type RuntimeConfig } from "./runtime-config";
-import { matchRoute, type RouteTable } from "./routes";
+import { matchRoute, type RouteAuth, type RouteTable, type UserIdSelector, type UserOwnedResource, type UserScopedRealtimePublisher } from "./routes";
 import { checkSameOrigin } from "./same-origin";
 import { errorResponse, jsonResponse, methodNotAllowed, notFound, parseJson, successResponse, withSecurityHeaders } from "./responses";
 
@@ -43,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;
@@ -53,6 +62,24 @@ export interface WebAppServerConfig<TEvent = unknown> {
   };
 }
 
+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;
@@ -89,9 +116,14 @@ function authErrorResponse(error: unknown): Response {
   if (error instanceof AuthError) {
     return errorResponse(error.status, error.code, error.message);
   }
-  if (error instanceof Error) {
-    return errorResponse(400, "request_failed", error.message);
+  return errorResponse(500, "request_failed", "Request failed");
+}
+
+function routeHandlerErrorResponse(error: unknown): Response {
+  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");
 }
 
@@ -115,6 +147,24 @@ 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;
+}
+
 function canRespondWithIndex(index: unknown): boolean {
   return index instanceof Response || typeof index === "string" || index instanceof Blob;
 }
@@ -123,6 +173,102 @@ function scopesFromBearer(claims: { scope: string }): string[] {
   return claims.scope.split(/\s+/).filter(Boolean);
 }
 
+function currentUser(auth: AuthenticatedRequestState): CurrentUser | undefined {
+  return auth.kind === "anonymous" ? undefined : auth.user;
+}
+
+function requireUser(auth: AuthenticatedRequestState): CurrentUser {
+  const user = currentUser(auth);
+  if (!user) {
+    throw new AuthError("authentication_required", "Authentication is required", 401);
+  }
+  return user;
+}
+
+function requireAdmin(auth: AuthenticatedRequestState): CurrentUser {
+  const user = requireUser(auth);
+  if (!user.isAdmin) {
+    throw new AuthError("admin_required", "Admin permissions are required", 403);
+  }
+  return user;
+}
+
+function requireOwner(auth: AuthenticatedRequestState): CurrentUser {
+  const user = requireUser(auth);
+  if (!user.isOwner) {
+    throw new AuthError("owner_required", "Owner permissions are required", 403);
+  }
+  return user;
+}
+
+function assertUser(auth: AuthenticatedRequestState, userId: string): CurrentUser {
+  const user = requireUser(auth);
+  if (user.id !== userId) {
+    throw new AuthError("forbidden", "You cannot access another user's resource", 403);
+  }
+  return user;
+}
+
+function ownedUserId<TResource>(resource: TResource, getUserId?: UserIdSelector<TResource>): string | undefined {
+  if (getUserId) {
+    return getUserId(resource);
+  }
+  if (typeof resource === "object" && resource !== null && "userId" in resource && typeof resource.userId === "string") {
+    return resource.userId;
+  }
+  throw new AuthError("route_misconfigured", "Owned resource helpers require a string userId field or a getUserId selector", 500);
+}
+
+function requireOwned<TResource extends UserOwnedResource>(auth: AuthenticatedRequestState, resource: TResource | null | undefined): TResource;
+function requireOwned<TResource>(auth: AuthenticatedRequestState, resource: TResource | null | undefined, getUserId: UserIdSelector<TResource>): TResource;
+function requireOwned<TResource>(auth: AuthenticatedRequestState, resource: TResource | null | undefined, getUserId?: UserIdSelector<TResource>): TResource {
+  const user = requireUser(auth);
+  const resourceUserId = resource ? ownedUserId(resource, getUserId) : undefined;
+  if (!resource || resourceUserId !== user.id) {
+    throw new AuthError("not_found", "Resource not found", 404);
+  }
+  return resource;
+}
+
+function filterOwned<TResource extends UserOwnedResource>(auth: AuthenticatedRequestState, resources: readonly TResource[]): TResource[];
+function filterOwned<TResource>(auth: AuthenticatedRequestState, resources: readonly TResource[], getUserId: UserIdSelector<TResource>): TResource[];
+function filterOwned<TResource>(auth: AuthenticatedRequestState, resources: readonly TResource[], getUserId?: UserIdSelector<TResource>): TResource[] {
+  const user = requireUser(auth);
+  return resources.filter((resource) => ownedUserId(resource, getUserId) === user.id);
+}
+
+function createFilterOwned(auth: AuthenticatedRequestState) {
+  function contextFilterOwned<TResource extends UserOwnedResource>(resources: readonly TResource[]): TResource[];
+  function contextFilterOwned<TResource>(resources: readonly TResource[], getUserId: UserIdSelector<TResource>): TResource[];
+  function contextFilterOwned<TResource>(resources: readonly TResource[], getUserId?: UserIdSelector<TResource>): TResource[] {
+    return filterOwned(auth, resources, getUserId as UserIdSelector<TResource>);
+  }
+  return contextFilterOwned;
+}
+
+function createRequireOwned(auth: AuthenticatedRequestState) {
+  function contextRequireOwned<TResource extends UserOwnedResource>(resource: TResource | null | undefined): TResource;
+  function contextRequireOwned<TResource>(resource: TResource | null | undefined, getUserId: UserIdSelector<TResource>): TResource;
+  function contextRequireOwned<TResource>(resource: TResource | null | undefined, getUserId?: UserIdSelector<TResource>): TResource {
+    return requireOwned(auth, resource, getUserId as UserIdSelector<TResource>);
+  }
+  return contextRequireOwned;
+}
+
+function requiresAuth(routeAuth: RouteAuth): boolean {
+  return routeAuth !== "public" && routeAuth !== "optional";
+}
+
+function enforceRouteAuth(routeAuth: RouteAuth, auth: AuthenticatedRequestState): void {
+  if (routeAuth === "user") {
+    requireUser(auth);
+  } else if (routeAuth === "admin") {
+    requireAdmin(auth);
+  } else if (routeAuth === "owner") {
+    requireOwner(auth);
+  }
+}
+
 export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<TEvent>): WebAppServer<TEvent> {
   const config = readRuntimeConfig({ appName: input.appName, envPrefix: input.envPrefix });
   const store = input.store ?? sqliteWebAppStore({ dataDir: config.dataDir });
@@ -133,6 +279,8 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
   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;
@@ -143,7 +291,16 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       if (deviceAuthEnabled) {
         try {
           const claims = await verifyAccessToken(store, config, token);
-          return { kind: "bearer", claims };
+          const user = store.getUserById(claims.sub);
+          if (user) {
+            return { kind: "bearer", claims, user: {
+              id: user.id,
+              username: user.username,
+              role: user.role,
+              isOwner: user.role === "owner",
+              isAdmin: user.role === "owner" || user.role === "admin",
+            } };
+          }
         } catch {
           // Fall through to API keys. Both use Bearer by design.
         }
@@ -156,22 +313,34 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       }
       return errorResponse(401, "invalid_token", "Bearer token is invalid");
     }
+    if (passkeysEnabled) {
+      const user = getPasskeySessionUser(req, store, config);
+      if (user) {
+        return { kind: "passkey", user };
+      }
+    }
     if (passkeysEnabled && isPasskeyAuthRequired(store, config)) {
-      if (!hasPasskeySession(req, store)) {
+      const user = getPasskeySessionUser(req, store, config);
+      if (!user) {
         return required ? errorResponse(401, "authentication_required", "Passkey authentication is required", undefined, {
           headers: { "x-webapp-passkey-required": "true" },
         }) : { kind: "anonymous" };
       }
-      return { kind: "passkey" };
     }
     return { kind: "anonymous" };
   }
 
   function configResponse(req: Request): WebAppConfigResponse {
+    const user = passkeysEnabled ? getPasskeySessionUser(req, store, config) : undefined;
     return {
       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,
@@ -181,6 +350,29 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
     };
   }
 
+  function setupUrl(req: Request, token: string): string {
+    const url = new URL(req.url);
+    url.pathname = "/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: AuthenticatedRequestState): CurrentUser {
+    return requireAdmin(auth);
+  }
+
+  function sanitizeRole(role: WebAppUserRole | undefined): WebAppUserRole {
+    return role === "admin" ? "admin" : "user";
+  }
+
   async function handleBuiltIn(req: Request, server?: Server<WebSocketData>): Promise<Response | undefined> {
     const url = new URL(req.url);
     const path = url.pathname;
@@ -198,18 +390,41 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         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 } });
+        const upgraded = server.upgrade(req, { data: { filters, userId: currentUser(auth)?.id } });
         return upgraded ? undefined : errorResponse(400, "websocket_upgrade_failed", "WebSocket upgrade failed");
       }
       if (path === "/api/passkey-auth/status" && req.method === "GET") {
         return jsonResponse(passkeyStatus(req, store, config, passkeysEnabled));
       }
-      if (passkeysEnabled && path === "/api/passkey-auth/registration/options" && req.method === "POST") {
-        const result = await beginRegistration(req, store, config);
+      if (passkeysEnabled && path === "/api/passkey-auth/bootstrap/options" && req.method === "POST") {
+        const body = await parseJson<{ username?: string }>(req);
+        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));
+        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/registration/verify" && req.method === "POST") {
-        const headers = await completeRegistration(req, store, config, await parseJson(req));
+      if (passkeysEnabled && path === "/api/passkey-auth/owner-setup/verify" && req.method === "POST") {
+        const headers = await completeOwnerPasskeySetup(req, store, config, await parseJson(req));
+        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<{ token?: string }>(req);
+        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<{ token?: string; response?: unknown }>(req);
+        const headers = await completeSetupRegistration(req, store, config, body.token ?? "", body.response as never);
         return addHeaders(successResponse(), headers);
       }
       if (passkeysEnabled && path === "/api/passkey-auth/authentication/options" && req.method === "POST") {
@@ -228,19 +443,19 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         if (auth instanceof Response) return auth;
         const originFailure = checkSameOrigin(req, config, auth, "mutations");
         if (originFailure) return originFailure;
-        return addHeaders(successResponse(), deletePasskey(req, store, config));
+        return addHeaders(successResponse(), deletePasskey(req, store, config, requireUser(auth).id));
       }
       if (apiKeysEnabled && path === "/api/api-keys" && req.method === "GET") {
         const auth = await authorize(req, true);
         if (auth instanceof Response) return auth;
-        return jsonResponse(listApiKeys(store));
+        return jsonResponse(listApiKeys(store, requireUser(auth).id));
       }
       if (apiKeysEnabled && path === "/api/api-keys" && req.method === "POST") {
         const auth = await authorize(req, true);
         if (auth instanceof Response) return auth;
         const originFailure = checkSameOrigin(req, config, auth, "mutations");
         if (originFailure) return originFailure;
-        return jsonResponse(createApiKey(store, await parseJson(req)));
+        return jsonResponse(createApiKey(store, requireUser(auth), await parseJson(req)));
       }
       const apiKeyDelete = /^\/api\/api-keys\/([^/]+)$/.exec(path);
       if (apiKeysEnabled && apiKeyDelete && req.method === "DELETE") {
@@ -248,7 +463,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         if (auth instanceof Response) return auth;
         const originFailure = checkSameOrigin(req, config, auth, "mutations");
         if (originFailure) return originFailure;
-        deleteApiKey(store, decodeURIComponent(apiKeyDelete[1]!));
+        deleteApiKey(store, requireUser(auth).id, decodeURIComponent(apiKeyDelete[1]!));
         return successResponse();
       }
       if (deviceAuthEnabled && path === "/api/auth/device" && req.method === "POST") {
@@ -268,7 +483,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         const originFailure = checkSameOrigin(req, config, auth, "mutations");
         if (originFailure) return originFailure;
         const body = await parseJson<{ userCode?: string; user_code?: string }>(req);
-        return jsonResponse(approveDevice(store, body.userCode ?? body.user_code ?? ""));
+        return jsonResponse(approveDevice(store, body.userCode ?? body.user_code ?? "", requireUser(auth).id));
       }
       if (deviceAuthEnabled && path === "/api/auth/device/deny" && req.method === "POST") {
         const auth = await authorize(req, true);
@@ -297,7 +512,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       if (deviceAuthEnabled && path === "/api/auth/sessions" && req.method === "GET") {
         const auth = await authorize(req, true);
         if (auth instanceof Response) return auth;
-        return jsonResponse(listAuthSessions(store));
+        return jsonResponse(listAuthSessions(store, requireUser(auth).id));
       }
       const sessionDelete = /^\/api\/auth\/sessions\/([^/]+)$/.exec(path);
       if (deviceAuthEnabled && sessionDelete && req.method === "DELETE") {
@@ -305,7 +520,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
         if (auth instanceof Response) return auth;
         const originFailure = checkSameOrigin(req, config, auth, "mutations");
         if (originFailure) return originFailure;
-        return revokeAuthSession(store, decodeURIComponent(sessionDelete[1]!)) ? successResponse() : notFound();
+        return revokeAuthSession(store, requireUser(auth).id, decodeURIComponent(sessionDelete[1]!)) ? successResponse() : notFound();
       }
       if (deviceAuthEnabled && path === "/.well-known/jwks.json" && req.method === "GET") {
         return jsonResponse(await jwks(store));
@@ -313,23 +528,107 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       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 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 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<{ username?: string; role?: WebAppUserRole }>(req);
+        const username = assertValidUsername(body.username ?? "");
+        if (store.getUserByUsername(username)) {
+          return errorResponse(409, "username_exists", "Username already exists");
+        }
+        const user = createUserRecord({ username, role: sanitizeRole(body.role) });
+        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 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<{ role?: WebAppUserRole }>(req);
+        const role = sanitizeRole(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 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 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 authorize(req, true);
+        if (auth instanceof Response) return auth;
+        ensureAdmin(auth);
+        return jsonResponse(store.listAuditEvents(100));
+      }
       if (path === "/api/preferences/theme") {
         const auth = await authorize(req, true);
         if (auth instanceof Response) return auth;
+        const user = requireUser(auth);
         if (req.method === "GET") {
-          return jsonResponse({ theme: store.getThemePreference() ?? "system" });
+          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<{ theme: ThemePreference }>(req);
-          store.setThemePreference(body.theme);
+          store.setThemePreference(body.theme, user.id);
           return successResponse({ theme: body.theme });
         }
       }
       if (path === "/api/preferences/log-level") {
         const auth = await 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 });
         }
@@ -346,6 +645,7 @@ export function createWebAppServer<TEvent = unknown>(input: WebAppServerConfig<T
       if (path === "/api/server/kill" && req.method === "POST") {
         const auth = await 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);
@@ -360,65 +660,162 @@ 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 withSecurityHeaders(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 required = (matched.route.auth ?? "required") === "required";
-      const auth = await authorize(req, required);
-      if (auth instanceof Response) {
-        return withSecurityHeaders(auth);
-      }
-      try {
-        if ((matched.route.auth ?? "required") !== "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 originFailure = checkSameOrigin(req, config, auth, matched.route.sameOrigin ?? "mutations");
-      if (originFailure) {
-        return withSecurityHeaders(originFailure);
-      }
-      return withSecurityHeaders(await handler(req, { params: matched.params, auth, realtime, server }));
+      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: {
         "/api/*": dynamicHandler,
         "/.well-known/*": dynamicHandler,
-        "/device": dynamicHandler,
+        "/device": deviceAuthEnabled && !canRespondWithIndex(input.index) ? input.index as never : dynamicHandler,
+        "/setup": passkeysEnabled && !canRespondWithIndex(input.index) ? input.index as never : dynamicHandler,
         "/*": canRespondWithIndex(input.index) ? dynamicHandler : input.index as never,
       },
       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,
     });