@cosmicdrift/kumiko-server-runtime 0.329.0 → 0.330.0

package/dist/run-prod-app-boot-context.js

@@ -0,0 +1,198 @@
+import { AUDIT_FEATURE, createEscapeHatchAuditSink, } from "@cosmicdrift/kumiko-bundled-features/audit";
+import { makeAuthPaths, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { resolveSessionStore } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { bindMfaRevokeAllOtherSessionsFromFeature, bindRevokeAllPatTokensFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { createSmtpTransportFromEnv } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { buildEnvConfigOverrides, createConfigAccessorFactory, createConfigResolver, } from "@cosmicdrift/kumiko-bundled-features/config";
+import { collectChannels, createDeliveryService, DELIVERY_FEATURE, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { bindPatAutoRevokeOnPasswordChangeFromFeature, revokeAllPatTokensForUser, } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import { createSecretsContext, SECRETS_FEATURE_NAME, } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { bindAutoRevokeFromFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { resolveBootCrypto } from "./boot/boot-crypto.js";
+// Boot-time context helpers for runProdApp: ctx-extra-context wiring
+// (templateResolver/delivery/secrets/config-resolver), auth-mail convenience
+// normalization, and prod session-auth wiring. Split out of run-prod-app.ts
+// (#1005, Welle 2) — mechanical relocation, these are self-contained pure
+// functions, no closure over runProdApp's local boot state.
+// Shared with runDevApp (mergeConfigResolverDefault) for dev/prod parity.
+export function addConfigAccessorFactory(resolved, registry) {
+    if (!resolved.configResolver)
+        return resolved;
+    return {
+        ...resolved,
+        _configAccessorFactory: createConfigAccessorFactory(registry, resolved.configResolver),
+    };
+}
+// Framework-Default-Provider für den AppContext — gleicher Mechanismus wie
+// der tenantTierResolver-Autowire (findTierResolverUsage): deklarierter
+// Bedarf (Feature gemountet) → Default aus db/env, App überschreibt nur die
+// Ausnahme. templateResolver ist unbedingt (createTemplateResolverApi wirft nie, baut
+// nur einen db-gebundenen Accessor). secrets wird nur auto-verdrahtet wenn
+// das secrets-Feature gemountet ist UND ein KEK tatsächlich verfügbar ist
+// (masterKey-Override ODER env-KEK present) — sonst skip, damit der eager
+// KEK-Detection + Provider/Cipher-Aufbau leben in boot/boot-crypto.ts
+// (envHasMasterKek, resolveBootCrypto) — gemeinsam mit runDevApp.
+// Prod-Misconfig (secrets gemountet, kein KEK) fängt schon secretsEnvSchema
+// beim Boot; fehlt der env-Schema-Pfad, wirft requireSecretsContext beim
+// ersten ctx.secrets-Zugriff mit Wiring-Hinweis. configResolver nur im
+// Auth-Mode. Exportiert + pure für Unit-Tests; der merge mit App-Werten
+// passiert beim Caller (App gewinnt).
+// Prod/dev parity for ctx.notify: without this `_notifyFactory` is only wired
+// in tests (createDeliveryTestContext), so ctx.notify is undefined at runtime
+// and every notification silently skips. sseBroker optional (email/push don't
+// need it, in-app SSE does); no jobRunner → queued channels send inline.
+function buildDeliveryNotifyFactory(opts) {
+    const deliveryService = createDeliveryService({
+        db: opts.db,
+        registry: opts.registry,
+        channels: collectChannels(opts.registry),
+        ...(opts.sseBroker && { sseBroker: opts.sseBroker }),
+        ...(opts.escapeHatchAuditSink && { escapeHatchAuditSink: opts.escapeHatchAuditSink }),
+    });
+    return (user, tenantId) => (notificationType, options) => deliveryService.notify(notificationType, options, user, tenantId);
+}
+function resolveEscapeHatchAuditSink(features, db) {
+    const hasAuditFeature = features.some((f) => f.name === AUDIT_FEATURE);
+    return hasAuditFeature ? createEscapeHatchAuditSink({ db }) : undefined;
+}
+export function buildBootExtraContext(opts) {
+    const crypto = opts.crypto ?? resolveBootCrypto(opts.envSource, opts.masterKey);
+    const hasSecretsFeature = opts.features.some((f) => f.name === SECRETS_FEATURE_NAME);
+    const wireSecrets = hasSecretsFeature && crypto.masterKeyProvider !== undefined;
+    const hasDeliveryFeature = opts.features.some((f) => f.name === DELIVERY_FEATURE);
+    const escapeHatchAuditSink = resolveEscapeHatchAuditSink(opts.features, opts.db);
+    return {
+        templateResolver: createTemplateResolverApi(opts.db),
+        ...(opts.kms && { kms: opts.kms }),
+        ...(escapeHatchAuditSink && { _escapeHatchAuditSink: escapeHatchAuditSink }),
+        ...(hasDeliveryFeature && {
+            _notifyFactory: buildDeliveryNotifyFactory({
+                db: opts.db,
+                registry: opts.registry,
+                ...(opts.sseBroker && { sseBroker: opts.sseBroker }),
+                ...(escapeHatchAuditSink && { escapeHatchAuditSink }),
+            }),
+        }),
+        // Top-level provider so feature jobs (secrets rotate, config reencrypt)
+        // reach it via ctx — previously only test-stack wired it.
+        ...(crypto.masterKeyProvider && { masterKeyProvider: crypto.masterKeyProvider }),
+        // Encrypt/decrypt partner for `encrypted: true` config keys. Wired
+        // whenever a master key exists — NOT gated on the secrets feature,
+        // config encryption must work without mounting ctx.secrets.
+        ...(crypto.configCipher && { configEncryption: crypto.configCipher }),
+        ...(wireSecrets &&
+            crypto.masterKeyProvider && {
+            secrets: createSecretsContext({
+                db: opts.db,
+                masterKeyProvider: crypto.masterKeyProvider,
+                dekCache: crypto.dekCache,
+            }),
+        }),
+        ...(opts.hasAuth && {
+            configResolver: createConfigResolver({
+                appOverrides: buildEnvConfigOverrides(opts.registry, opts.envSource),
+                ...(crypto.configCipher && { cipher: crypto.configCipher }),
+            }),
+        }),
+    };
+}
+function buildAuthPathAppUrl(baseUrl, path) {
+    return typeof path === "function"
+        ? (locale) => `${baseUrl}${path(locale)}`
+        : `${baseUrl}${path}`;
+}
+// accountUnlock (#1266) deliberately does NOT join this convenience block —
+// unlike reset/verify/signup/invite it's only meaningful paired with
+// `accountLockout` (kumiko-framework#1627), and apps set both explicitly
+// alongside each other (same shape as `passwordReset`), so `mail` alone
+// can't silently expose a new public endpoint an app didn't ask for.
+function backfillTokenSecrets(auth, tokenSecret) {
+    return {
+        ...auth,
+        ...(auth.passwordReset && {
+            passwordReset: {
+                ...auth.passwordReset,
+                hmacSecret: auth.passwordReset.hmacSecret ?? tokenSecret,
+            },
+        }),
+        ...(auth.emailVerification && {
+            emailVerification: {
+                ...auth.emailVerification,
+                hmacSecret: auth.emailVerification.hmacSecret ?? tokenSecret,
+            },
+        }),
+    };
+}
+export function resolveAuthMail(auth, hmacSecret, envSource) {
+    // Runs before the mail/SMTP guards below so an app-supplied block without
+    // hmacSecret is backfilled even without a `mail` block; an explicit secret still wins.
+    const tokenSecret = auth.mail?.hmacSecret ?? hmacSecret;
+    const withResolvedSecrets = backfillTokenSecrets(auth, tokenSecret);
+    if (!auth.mail)
+        return withResolvedSecrets;
+    // SMTP-presence gate: ohne SMTP_HOST-env wird KEIN Flow verdrahtet (Routes
+    // blieben sonst 500). Der eigentliche Mail-Versand läuft über delivery
+    // (channel-email), nicht über diesen Transport — er ist nur der Detektor
+    // "ist Mail konfiguriert?".
+    if (!createSmtpTransportFromEnv(envSource, { fallbackFrom: auth.mail.from ?? "noreply@localhost" })) {
+        return withResolvedSecrets;
+    }
+    const paths = makeAuthPaths(auth.mail.paths);
+    // appName/locale fließen in alle vier Flow-Options (alle mailen via delivery).
+    const mailPresentation = {
+        ...(auth.mail.appName !== undefined && { appName: auth.mail.appName }),
+        ...(auth.mail.locale !== undefined && { locale: auth.mail.locale }),
+    };
+    return {
+        ...withResolvedSecrets,
+        passwordReset: withResolvedSecrets.passwordReset ?? {
+            hmacSecret: tokenSecret,
+            appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.resetPassword),
+            ...mailPresentation,
+        },
+        emailVerification: withResolvedSecrets.emailVerification ?? {
+            hmacSecret: tokenSecret,
+            appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.verifyEmail),
+            ...(auth.mail.emailVerificationMode !== undefined && {
+                mode: auth.mail.emailVerificationMode,
+            }),
+            ...mailPresentation,
+        },
+        signup: withResolvedSecrets.signup ?? {
+            appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.signupComplete),
+            ...mailPresentation,
+        },
+        invite: withResolvedSecrets.invite ?? {
+            appUrl: buildAuthPathAppUrl(auth.mail.baseUrl, paths.inviteAccept),
+            ...mailPresentation,
+        },
+    };
+}
+export async function buildProdSessionAuth(db, registry, sessionsFeature, mfaFeature, patFeature) {
+    // Resolve the sessions feature sessionStore provider (#1372).
+    const store = await resolveSessionStore({ db, registry });
+    if (sessionsFeature) {
+        bindAutoRevokeFromFeature(sessionsFeature)?.(store.massRevoker);
+    }
+    if (mfaFeature) {
+        bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(store.revokeAllOthers);
+    }
+    if (mfaFeature && patFeature) {
+        bindRevokeAllPatTokensFromFeature(mfaFeature)?.((userId) => revokeAllPatTokensForUser(db, userId));
+    }
+    return {
+        sessionCreator: store.creator,
+        sessionRevoker: store.revoker,
+        sessionChecker: store.checker,
+    };
+}
+// Password-change → PAT-revoke, independent of sessions/MFA being mounted
+// (unlike buildProdSessionAuth, which only runs when a sessionStore provider
+// is registered). Call unconditionally whenever personal-access-tokens is
+// mounted — a no-op if it isn't (bindPatAutoRevokeOnPasswordChangeFromFeature
+// returns undefined for an unmounted feature.exports shape, but callers
+// should still gate on patFeature being defined at all).
+export function wireProdPatAutoRevoke(db, patFeature) {
+    bindPatAutoRevokeOnPasswordChangeFromFeature(patFeature)?.((userId) => revokeAllPatTokensForUser(db, userId));
+}

package/dist/run-prod-app-static-files.d.ts

@@ -0,0 +1,32 @@
+import { type CachePolicy } from "@cosmicdrift/kumiko-framework/api";
+import { type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { HostDispatchFn, PageHeadResolver } from "./run-prod-app.js";
+export declare function readStaticFile(filePath: string): Promise<{
+    readonly bytes: Uint8Array;
+    readonly mime: string;
+    readonly mtimeMs: number;
+} | undefined>;
+export declare function serveDiskFile(req: Request, pathname: string, file: {
+    readonly bytes: Uint8Array;
+    readonly mime: string;
+    readonly mtimeMs: number;
+}): Response;
+export declare function mimeTypeFor(filePath: string): string;
+type QueryDispatcher = {
+    readonly query: (type: string, payload: unknown, user: SessionUser) => Promise<unknown>;
+};
+export type PageHeadOptions = {
+    readonly resolvePageHead: PageHeadResolver;
+    readonly dispatcher: QueryDispatcher;
+};
+export declare function buildStaticFallback(apiHandler: (req: Request, socketAddress?: string) => Response | Promise<Response>, staticDir: string, hostDispatch?: HostDispatchFn, pageHead?: PageHeadOptions, 
+/** Backs hostDispatch's `systemQuery` — required whenever `hostDispatch`
+ *  is set (a hostDispatch that reads `deps.systemQuery` without it would
+ *  throw). Separate from `pageHead.dispatcher` since resolvePageHead is
+ *  optional independently of hostDispatch. */
+hostDispatchDispatcher?: QueryDispatcher, 
+/** trustedProxyHops for the systemQuery request-context builds below —
+ *  1:1 with runProdApp's effective value. */
+trustedProxyHops?: number): (req: Request, socketAddress?: string) => Promise<Response>;
+export declare function staticCachePolicy(pathname: string): CachePolicy;
+export {};

package/dist/run-prod-app-static-files.js

@@ -0,0 +1,280 @@
+import { buildRequestContextDataFromRequest, cachedResponse, computeStrongEtag, computeWeakEtag, createClientIpResolver, requestContext, } from "@cosmicdrift/kumiko-framework/api";
+import { createAnonymousUser } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveAndInjectPageHead } from "@cosmicdrift/kumiko-headless/apex";
+import { ASSETS_DIR } from "./build-prod-bundle.js";
+import { stripNoRouteMatchHeader, tryHonoFirst } from "./try-hono-first.js";
+// Static-asset + SPA-fallback serving for runProdApp's HTTP handler. Split
+// out of run-prod-app.ts (#1005, Welle 2) — mechanical relocation, these
+// functions are self-contained (no closure over runProdApp's local boot
+// state), only params.
+// Static-fallback: try the Hono app first, fall back to a file in
+// staticDir if Hono returns 404. Keeps /api/* on the dispatcher and
+// everything else (HTML, JS, CSS, images) on the disk.
+//
+// Cache-Header-Strategie:
+//   /assets/*               → public, max-age=31536000, immutable
+//                             (gehashte Filenames vom Build, sicher cachebar)
+//   /index.html             → no-cache, must-revalidate
+//                             (HTML-Shell, must reload on deploy)
+//   /manifest.json, /sw.js  → no-cache
+//                             (Update-Detection-Mechanismen, müssen frisch sein)
+//   alles andere            → kein expliziter Header
+//                             (Browser-Default, public/-Files wie favicon)
+// File-reader für den static-fallback. Nutzt node:fs/promises statt
+// Bun.file damit der Pfad in vitest+node integration-tests laufen kann
+// (Bun.file ist Bun-only). Performance-cost ist marginal: die Disk-
+// Files in einem prod-staticDir sind 1-200 KB, full-buffer-Read ist
+// ein paar Mikrosekunden. Streaming via Bun.file wäre nur relevant ab
+// ~1 MB.
+export async function readStaticFile(filePath) {
+    try {
+        const { readFile, stat } = await import("node:fs/promises");
+        const [bytes, fileStat] = await Promise.all([readFile(filePath), stat(filePath)]);
+        return { bytes, mime: mimeTypeFor(filePath), mtimeMs: fileStat.mtimeMs };
+    }
+    catch (err) {
+        const code = err.code;
+        // ENOENT: no such path. EISDIR: readFile() on a directory (e.g. GET
+        // /assets where "assets" is a subfolder copied verbatim from public/).
+        // ENOTDIR: a path segment that isn't a directory is used as one (e.g.
+        // GET /index.html/x — "index.html" is a file, not a directory) — all
+        // three mean "not a servable file", so fall through to the SPA
+        // fallback instead of a 500.
+        if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR")
+            return undefined;
+        throw err;
+    }
+}
+export function serveDiskFile(req, pathname, file) {
+    return cachedResponse(req, {
+        // @cast-boundary bun-types — Response BodyInit narrowing
+        body: file.bytes,
+        etag: computeWeakEtag(file.mtimeMs, file.bytes.byteLength),
+        cache: staticCachePolicy(pathname),
+        headers: { "content-type": file.mime },
+        lastModified: new Date(file.mtimeMs),
+    });
+}
+// Minimal-Mime-Map — deckt die Files ab die kumiko-build und typische
+// public/-Inhalte produzieren. Bun.file leitet das aus dem Suffix ab,
+// im node-Pfad müssen wir es selbst tun. Default: octet-stream (Browser
+// fragt bei unbekanntem MIME nach).
+export function mimeTypeFor(filePath) {
+    const ext = filePath.toLowerCase().split(".").pop() ?? "";
+    switch (ext) {
+        case "html":
+            return "text/html; charset=utf-8";
+        case "js":
+        case "mjs":
+            return "text/javascript; charset=utf-8";
+        case "css":
+            return "text/css; charset=utf-8";
+        case "json":
+            return "application/json; charset=utf-8";
+        case "svg":
+            return "image/svg+xml";
+        case "png":
+            return "image/png";
+        case "jpg":
+        case "jpeg":
+            return "image/jpeg";
+        case "ico":
+            return "image/x-icon";
+        case "txt":
+            return "text/plain; charset=utf-8";
+        case "xml":
+            return "application/xml; charset=utf-8";
+        case "webmanifest":
+            return "application/manifest+json";
+        case "woff2":
+            return "font/woff2";
+        default:
+            return "application/octet-stream";
+    }
+}
+export function buildStaticFallback(apiHandler, staticDir, hostDispatch, pageHead, 
+/** Backs hostDispatch's `systemQuery` — required whenever `hostDispatch`
+ *  is set (a hostDispatch that reads `deps.systemQuery` without it would
+ *  throw). Separate from `pageHead.dispatcher` since resolvePageHead is
+ *  optional independently of hostDispatch. */
+hostDispatchDispatcher, 
+/** trustedProxyHops for the systemQuery request-context builds below —
+ *  1:1 with runProdApp's effective value. */
+trustedProxyHops = 0) {
+    const indexHtml = `${staticDir}/index.html`;
+    const clientIpResolver = createClientIpResolver(trustedProxyHops, "buildStaticFallback");
+    // Reads an HTML file from disk. No schema injection — createKumikoApp
+    // fetches it itself from the authenticated GET /api/schema, so the HTML
+    // is identical for every host.
+    async function readHtmlFile(path) {
+        const file = await readStaticFile(path);
+        if (!file)
+            return null;
+        return {
+            bytes: file.bytes.buffer.slice(file.bytes.byteOffset, file.bytes.byteOffset + file.bytes.byteLength),
+            mime: file.mime,
+            etag: computeWeakEtag(file.mtimeMs, file.bytes.byteLength),
+            mtimeMs: file.mtimeMs,
+        };
+    }
+    function serveHtmlFile(req, pathname, html, extraHeaders) {
+        return cachedResponse(req, {
+            body: html.bytes,
+            etag: html.etag,
+            cache: staticCachePolicy(pathname),
+            headers: { "content-type": html.mime, ...extraHeaders },
+            lastModified: new Date(html.mtimeMs),
+        });
+    }
+    // Injects resolved head metadata into an already-read HTML payload, right
+    // before it's served. Recomputes a strong etag over the final bytes so
+    // two requests with different head metadata never collide on one etag
+    // (see computeStrongEtag usage in readHtmlFile above for the same
+    // requirement on schema-injection). No resolvePageHead configured, no
+    // meta resolved, or nothing actually changed (e.g. no `</head>` to
+    // inject into) → the original html object is returned untouched.
+    //
+    // The resolve+timeout+inject itself runs through headless's
+    // resolveAndInjectPageHead — the single call site runDevApp also uses
+    // (kumiko-framework#3026), so only the systemQuery/dispatcher wiring
+    // below (Request-bound, prod-specific) and the etag recompute are local.
+    async function applyPageHead(req, html, socketAddress) {
+        if (!pageHead)
+            return html;
+        const url = new URL(req.url);
+        const host = req.headers.get("host") ?? url.host;
+        const systemQuery = (type, payload, tenantId) => requestContext.run(requestContext.get() ??
+            buildRequestContextDataFromRequest(req, { resolver: clientIpResolver, socketAddress }), () => pageHead.dispatcher.query(type, payload, createAnonymousUser(tenantId)));
+        const text = new TextDecoder().decode(html.bytes);
+        const injected = await resolveAndInjectPageHead(text, pageHead.resolvePageHead, {
+            path: url.pathname,
+            host,
+            systemQuery,
+        });
+        if (injected === text)
+            return html;
+        const encoded = new TextEncoder().encode(injected);
+        return {
+            bytes: encoded.buffer,
+            mime: html.mime,
+            etag: computeStrongEtag(encoded),
+            mtimeMs: html.mtimeMs,
+        };
+    }
+    // hostDispatch konsultieren wenn gesetzt UND der Request auf den
+    // HTML-Fallback fällt (Root oder SPA-Route). Returnt entweder die
+    // resolved Response (redirect/404/html) oder null wenn der Default-
+    // Pfad weiterlaufen soll.
+    async function tryHostDispatch(req, socketAddress) {
+        if (!hostDispatch)
+            return null;
+        const url = new URL(req.url);
+        const host = req.headers.get("host") ?? url.host;
+        const systemQuery = (type, payload, tenantId) => {
+            if (!hostDispatchDispatcher) {
+                throw new Error("hostDispatch called deps.systemQuery but buildStaticFallback got no hostDispatchDispatcher");
+            }
+            return requestContext.run(requestContext.get() ??
+                buildRequestContextDataFromRequest(req, { resolver: clientIpResolver, socketAddress }), () => hostDispatchDispatcher.query(type, payload, createAnonymousUser(tenantId)));
+        };
+        const result = await hostDispatch({ host, path: url.pathname, search: url.search }, { systemQuery });
+        if (result.kind === "not-found") {
+            return new Response("Not Found", { status: 404 });
+        }
+        if (result.kind === "redirect") {
+            return new Response(null, {
+                status: result.status ?? 302,
+                headers: { Location: result.to },
+            });
+        }
+        // result.kind === "html"
+        const filePath = `${staticDir}/${result.file}`;
+        const html = await readHtmlFile(filePath);
+        if (!html) {
+            // Author-Fehler: hostDispatch verweist auf nicht-existente Datei.
+            // Liefer 500 statt silent-404 damit der Bug schnell auffällt.
+            return new Response(`hostDispatch: file not found: ${result.file}`, { status: 500 });
+        }
+        // Per-host body (hostDispatch picks the file by host) → Vary: Host,
+        // otherwise a shared cache could serve Host A's HTML to Host B.
+        const extraHeaders = { vary: "Host" };
+        if (result.csp)
+            extraHeaders["content-security-policy"] = result.csp;
+        const withHead = await applyPageHead(req, html, socketAddress);
+        return serveHtmlFile(req, "/index.html", withHead, extraHeaders);
+    }
+    return async (req, socketAddress) => {
+        const url = new URL(req.url);
+        // /api/* and /health → always Hono (Dispatcher + Health-Probe). Bypasses
+        // tryHonoFirst entirely, so the router-miss marker must be stripped
+        // here too — otherwise an unmatched /api/* path would leak it straight
+        // to the client (see try-hono-first.ts's header-hygiene note).
+        if (url.pathname.startsWith("/api/") || url.pathname === "/health") {
+            return stripNoRouteMatchHeader(await apiHandler(req, socketAddress));
+        }
+        // Hono-First für andere Pfade: extraRoutes (z.B. /feed.xml,
+        // /sitemap.xml) UND r.httpRoute-Features (z.B. /legal/*) müssen vor
+        // dem Disk-Lookup greifen, sonst schluckt der SPA-Fallback unten
+        // unbekannte Pfade als index.html. Shared mit dev-server's
+        // createKumikoServer.handleFetch damit beide IDENTISCHE Semantik haben.
+        const honoTry = await tryHonoFirst({ fetch: apiHandler }, req, socketAddress);
+        if (honoTry.matched) {
+            return honoTry.response;
+        }
+        const honoRes = honoTry.response;
+        // Disk-/SPA-Fallback ist GET/HEAD-only. Ein non-GET ohne Hono-Match
+        // (z.B. POST auf einen falsch konfigurierten Webhook-Pfad) muss den
+        // Hono-404 durchreichen — 200 index.html würde dem Provider
+        // "delivered" signalisieren und Events gingen still verloren (#259).
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            return honoRes;
+        }
+        // Disk-Datei (Asset oder konkrete File). Asset-Pfade laufen
+        // host-unabhängig — die Bundles in /assets/* werden vom client
+        // aktiv geladen, kein Server-side Routing nötig.
+        const isIndexRequest = url.pathname === "/" || url.pathname === "/index.html";
+        if (!isIndexRequest) {
+            const relPath = url.pathname.slice(1);
+            const filePath = `${staticDir}/${relPath}`;
+            const file = await readStaticFile(filePath);
+            if (file) {
+                return serveDiskFile(req, url.pathname, file);
+            }
+        }
+        // Root or SPA route — hostDispatch applies here when set.
+        // Without hostDispatch: the old single-app path (index.html).
+        const dispatched = await tryHostDispatch(req, socketAddress);
+        if (dispatched)
+            return dispatched;
+        // Default single-app path: index.html, no schema injection.
+        const index = await readHtmlFile(indexHtml);
+        if (index) {
+            const withHead = await applyPageHead(req, index, socketAddress);
+            return serveHtmlFile(req, "/index.html", withHead);
+        }
+        // Kein Hono-Match, keine Disk-Datei, kein index.html → liefer den
+        // ursprünglichen 404 von Hono durch (statt einen neuen Roundtrip).
+        return honoRes;
+    };
+}
+// Map URL-Pfad → Cache-Policy. Hashed-Asset-Pfade (/assets/*) sind
+// unveränderlich, der Rest bleibt revalidate/no-cache damit Updates ohne
+// Hard-Reload greifen. Exported für Unit-Tests; Konsumenten gehen via
+// runProdApp.
+export function staticCachePolicy(pathname) {
+    if (pathname.startsWith(`/${ASSETS_DIR}/`)) {
+        return { kind: "immutable" };
+    }
+    if (pathname === "/" || pathname === "/index.html") {
+        return { kind: "revalidate" };
+    }
+    if (pathname === "/manifest.json" ||
+        pathname === "/sw.js" ||
+        // ponytail: build-info.json ist statisch — kein /api/version-Endpoint
+        // nötig, der Disk-Fallback serviert sie. no-cache, sonst pollt der
+        // UpdateChecker eine veraltete id.
+        pathname === "/build-info.json") {
+        return { kind: "no-cache" };
+    }
+    return { kind: "none" };
+}