@openlup/platform 0.0.0 → 0.16.0

package/dist/http/requestAdapter.js

@@ -0,0 +1,203 @@
+// Node request/response adaptation to the hosted-function request shape for the HttpRuntimePort.
+//
+// Owns the RAW-BODY INVARIANT: every buffered request gets the exact bytes re-exposed as an
+// async-iterable (so raw-body signature verification works for ANY route, including ones outside a
+// `/webhooks/` segment) while still setting a parsed JSON req.body; stream-first standalone
+// entrypoints keep their live stream and NO req.body.
+export const DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES = 1_048_576;
+export class NodeRequestBodyTooLargeError extends Error {
+    constructor() {
+        super("node_request_body_too_large");
+    }
+}
+export class NodeRequestAbortedError extends Error {
+    constructor() {
+        super("node_request_aborted");
+    }
+}
+/** A path is a webhook iff it contains a `/webhooks/` segment. */
+export function isWebhookPath(pathname) {
+    return pathname.includes("/webhooks/");
+}
+/**
+ * The PLATFORM's stream-first standalone entrypoints: they read the raw stream
+ * themselves, so the runtime must never pre-parse their body.
+ *
+ * A deployment's own stream-first endpoint is NOT listed here. It declares
+ * `rawStream: true` on its `HttpEntrypointRegistration` and the runtime passes that
+ * decision to `adaptRequest` directly — which is what stops this publishable list
+ * from having to name a path only that deployment owns.
+ */
+export function isRawStreamEntrypoint(pathname) {
+    return pathname === "/api/csp-report";
+}
+export function pathnameOf(req) {
+    return new URL(req.url ?? "/", "http://node.local").pathname;
+}
+function parseQuery(req) {
+    const url = new URL(req.url ?? "/", "http://node.local");
+    const query = {};
+    for (const key of url.searchParams.keys()) {
+        if (key in query)
+            continue;
+        const all = url.searchParams.getAll(key);
+        query[key] = all.length > 1 ? all : all[0];
+    }
+    return query;
+}
+function parseCookies(req) {
+    const header = req.headers.cookie;
+    if (!header)
+        return {};
+    const out = {};
+    for (const part of header.split(";")) {
+        const idx = part.indexOf("=");
+        if (idx < 0)
+            continue;
+        const key = part.slice(0, idx).trim();
+        const value = part.slice(idx + 1).trim();
+        if (key)
+            out[key] = decodeURIComponent(value);
+    }
+    return out;
+}
+/** Buffer the request stream once into a single Buffer (GET/HEAD => empty). */
+async function bufferBody(req, maxBytes) {
+    const method = (req.method ?? "GET").toUpperCase();
+    if (method === "GET" || method === "HEAD")
+        return Buffer.alloc(0);
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            req.removeListener("data", onData);
+            req.removeListener("end", onEnd);
+            req.removeListener("error", onError);
+            req.abortSignal?.removeEventListener("abort", onAbort);
+            if (result instanceof Error)
+                reject(result);
+            else
+                resolve(result);
+        };
+        const onData = (chunk) => {
+            const bytesChunk = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            bytes += bytesChunk.length;
+            if (bytes > maxBytes) {
+                finish(new NodeRequestBodyTooLargeError());
+                return;
+            }
+            chunks.push(bytesChunk);
+        };
+        const onEnd = () => finish(Buffer.concat(chunks));
+        const onError = (error) => finish(error);
+        const onAbort = () => finish(new NodeRequestAbortedError());
+        if (req.abortSignal?.aborted)
+            return onAbort();
+        req.on("data", onData);
+        req.once("end", onEnd);
+        req.once("error", onError);
+        req.abortSignal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Re-expose a fixed Buffer as the request's async-iterable so readRawBody sees the EXACT bytes. */
+function reexposeRawStream(req, raw) {
+    req[Symbol.asyncIterator] =
+        async function* () {
+            yield raw;
+        };
+}
+/** Best-effort JSON parse of a buffered body for handlers that read `req.body`. */
+function parseJsonBody(raw, contentType) {
+    if (raw.length === 0)
+        return undefined;
+    const text = raw.toString("utf8").trim();
+    if (!text)
+        return undefined;
+    if (contentType.includes("application/json") || text.startsWith("{") || text.startsWith("[")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/**
+ * Decorate a Node response with Vercel's status/json/send/redirect sugar (productionized from the
+ * dev shim's decorateResponse — identical semantics).
+ */
+export function decorateResponse(res) {
+    const vres = res;
+    vres.status = function status(code) {
+        res.statusCode = code;
+        return vres;
+    };
+    vres.json = function json(body) {
+        if (!res.hasHeader("content-type")) {
+            res.setHeader("content-type", "application/json; charset=utf-8");
+        }
+        res.end(JSON.stringify(body));
+        return vres;
+    };
+    vres.send = function send(body) {
+        if (Buffer.isBuffer(body) || typeof body === "string") {
+            res.end(body);
+            return vres;
+        }
+        if (!res.hasHeader("content-type")) {
+            res.setHeader("content-type", "application/json; charset=utf-8");
+        }
+        res.end(JSON.stringify(body));
+        return vres;
+    };
+    vres.redirect = function redirect(statusOrUrl, maybeUrl) {
+        const code = typeof statusOrUrl === "number" ? statusOrUrl : 302;
+        const location = typeof statusOrUrl === "number" ? maybeUrl ?? "/" : statusOrUrl;
+        res.statusCode = code;
+        res.setHeader("location", location);
+        res.end();
+        return vres;
+    };
+    return vres;
+}
+/**
+ * Adapt a Node IncomingMessage into the Vercel request shape, honoring the raw-body invariant:
+ *  - raw-stream entrypoints (process/csp/feedback): stream left intact, NO req.body;
+ *  - everything else: raw bytes buffered + re-exposed as async-iterable (so readRawBody sees the
+ *    EXACT bytes for any signature-verifying route, webhook-segment or not) AND req.body = parsed JSON.
+ */
+export async function adaptRequest(req, pathname, 
+/** Explicit override for a caller that knows the entrypoint's body contract (see above). */
+rawStream = isRawStreamEntrypoint(pathname), bufferedBodyLimitBytes = DEFAULT_NODE_BUFFERED_BODY_LIMIT_BYTES) {
+    const vreq = req;
+    vreq.query = parseQuery(req);
+    vreq.cookies = parseCookies(req);
+    if (rawStream) {
+        // Leave the live stream untouched; the handler reads it itself (formidable / custom readBody).
+        return vreq;
+    }
+    const raw = await bufferBody(vreq, bufferedBodyLimitBytes);
+    const contentType = String(req.headers["content-type"] ?? "");
+    // Re-expose the EXACT bytes as an async-iterable for EVERY buffered request, not only
+    // `/webhooks/` paths. Some signature-verifying routes live outside that segment — e.g.
+    // `/api/bff/communications/integrations/events` calls readRawBody for HMAC verification.
+    // readRawBody is stream-first (isAsyncIterable), so any handler that needs the raw bytes
+    // works; handlers that read req.body still get parsed JSON. The re-exposed iterator is
+    // simply never consumed for routes that don't call readRawBody, so this is a safe superset
+    // of the old `/webhooks/`-only behavior (and not dependent on a fragile path convention).
+    reexposeRawStream(req, raw);
+    vreq.body = parseJsonBody(raw, contentType);
+    return vreq;
+}
+/** Narrow a raw IncomingMessage to HttpRequest at the server boundary (query/cookies set in adapt). */
+export function decorateRequest(req) {
+    const vreq = req;
+    if (!vreq.query)
+        vreq.query = {};
+    return vreq;
+}

package/dist/http/runtime.d.ts

@@ -0,0 +1,83 @@
+import { type Server } from "node:http";
+import type { HttpRuntimePort } from "@openlup/core/platform-runtime";
+import type { EntrypointLoader } from "./types.js";
+import type { BffDispatch, RouteEntry } from "../bff/index.js";
+import { type NodeSecurityHeaderPolicy, type StaticAssetReader } from "./security.js";
+/** One deployment-specific standalone entrypoint, matched by its exact path. */
+export interface HttpEntrypointRegistration {
+    path: string;
+    rawStream?: boolean;
+    maxDurationMs?: number;
+    load: EntrypointLoader;
+}
+/**
+ * One deployment-specific entrypoint matched by a path rule. `match` returns the query values the
+ * entrypoint receives for this path, or null when the path is not its own. The body is buffered.
+ */
+export interface HttpPathEntrypoint {
+    match(pathname: string): Record<string, string> | null;
+    load: EntrypointLoader;
+    /** Request deadline; defaults to 10 seconds. */
+    maxDurationMs?: number;
+}
+export interface NodeLegacyRedirect {
+    source: string;
+    destination: string;
+    permanent: boolean;
+}
+export interface NodeCsrFallback {
+    exactPaths: readonly string[];
+    routeFamilies: readonly string[];
+}
+export interface NodeHttpRuntimeOptions {
+    /** The deployment's BFF route table. */
+    routes: readonly RouteEntry[];
+    /** The dispatcher that matches `routes` (see `createBffDispatcher`). */
+    dispatch: BffDispatch;
+    /** Validated public-route contract supplied by the host composition root. */
+    routing?: {
+        legacyRedirects: readonly NodeLegacyRedirect[];
+        ssgPaths: readonly string[];
+        csrFallback: NodeCsrFallback;
+    };
+    /** Deployment header policy, including the content security policy. */
+    security: NodeSecurityHeaderPolicy;
+    /** robots.txt body for a request host; without it `/robots.txt` is served like any other path. */
+    robotsTxt?: (host: string | undefined) => string;
+    /**
+     * Platform-path standalone handlers: the CSP report sink at `/api/csp-report` and the hosted
+     * BFF router at `/api/bff-router`. A path without a handler is treated like any other path.
+     */
+    entrypoints?: {
+        cspReport?: EntrypointLoader;
+        bffRouter?: EntrypointLoader;
+    };
+    /**
+     * Deployment exact-path handlers, checked after the CSP report entrypoint and before the BFF
+     * router; a later registration replaces an earlier one with the same path.
+     */
+    extraEntrypoints?: readonly HttpEntrypointRegistration[];
+    /** Deployment path-rule handlers checked before the BFF dispatcher, first match wins. */
+    pathEntrypoints?: readonly HttpPathEntrypoint[];
+    /** Deployment path-rule handlers checked after legacy redirects and before static documents. */
+    fallbackPathEntrypoints?: readonly HttpPathEntrypoint[];
+    /** Registry-derived allowlist; undeclared job ids must resolve null. */
+    scheduledEntrypoint?: (jobId: string) => EntrypointLoader | null;
+    /** Explicit host deadlines; missing cells use the bounded defaults below. */
+    durations?: {
+        bff?: number;
+        cspReport?: number;
+        bffRouter?: number;
+        scheduled?: (jobId: string) => number;
+    };
+    /** Static SPA reader; without one, unmatched non-API paths answer 404. */
+    staticReader?: StaticAssetReader;
+    /** Structured error sink (defaults to console.error). */
+    onError?: (context: string, error: unknown) => void;
+}
+/** Build the runtime's request handler (exported for unit tests; wraps every dispatch path). */
+export declare function createRequestHandler(options: NodeHttpRuntimeOptions): HttpRuntimePort["handle"];
+/** Create the Node HttpRuntimePort: `handle` for one request, `listen` to bind the server. */
+export declare function createNodeHttpRuntime(options: NodeHttpRuntimeOptions): HttpRuntimePort & {
+    server: Server | null;
+};

package/dist/http/runtime.js

@@ -0,0 +1,199 @@
+// Native Node adapter for manifest-driven public routing and API topology.
+//
+// The request order is fixed: trailing-slash redirect, the CSP report entrypoint, deployment
+// exact-path entrypoints, the BFF router entrypoint, deployment path entrypoints, the BFF
+// dispatcher, robots.txt, declared scheduled routes, the API 404, legacy redirects, deployment
+// fallback path entrypoints, then static documents. Every deployment value (routes, entrypoints,
+// header policy, robots policy, deadlines) is supplied by the composition root.
+import { createServer } from "node:http";
+import { adaptRequest, decorateRequest, decorateResponse, NodeRequestAbortedError, NodeRequestBodyTooLargeError, } from "./requestAdapter.js";
+import { closeInputAfterResponse, runWithHttpDeadline } from "./deadline.js";
+import { applySecurityHeaders, serveSpaStatic, } from "./security.js";
+const SCHEDULED_PREFIX = "/api/cron/";
+const ROBOTS_CONTENT_TYPE = "text/plain; charset=utf-8";
+const EMPTY_ROUTING = { legacyRedirects: [], ssgPaths: [], csrFallback: { exactPaths: [], routeFamilies: [] } };
+function requestUrl(req) {
+    return new URL(req.url ?? "/", "http://node.local");
+}
+function capturesFor(source, pathname) {
+    const sourceParts = source.split("/").slice(1);
+    const pathParts = pathname.split("/").slice(1);
+    const captures = {};
+    let cursor = 0;
+    for (const sourcePart of sourceParts) {
+        if (!sourcePart.startsWith(":")) {
+            if (pathParts[cursor++] !== sourcePart)
+                return null;
+            continue;
+        }
+        const name = sourcePart.slice(1).replace(/\*$/, "");
+        if (sourcePart.endsWith("*")) {
+            captures[name] = pathParts.slice(cursor).join("/");
+            cursor = pathParts.length;
+            break;
+        }
+        const value = pathParts[cursor++];
+        if (!value)
+            return null;
+        captures[name] = value;
+    }
+    return cursor === pathParts.length ? captures : null;
+}
+function legacyRedirect(pathname, redirects) {
+    for (const redirect of redirects) {
+        const captures = capturesFor(redirect.source, pathname);
+        if (!captures)
+            continue;
+        return redirect.destination.replace(/:([A-Za-z][A-Za-z0-9_]*)\*?/g, (_match, name) => captures[name] ?? "");
+    }
+    return null;
+}
+function isCsrFallback(pathname, csrFallback) {
+    return csrFallback.exactPaths.includes(pathname)
+        || csrFallback.routeFamilies.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+function finalize(res) {
+    if (!res.writableEnded && !res.destroyed)
+        res.end();
+}
+function matchPathEntrypoint(entrypoints, pathname) {
+    for (const entrypoint of entrypoints ?? []) {
+        const query = entrypoint.match(pathname);
+        if (query)
+            return { entrypoint, query };
+    }
+    return null;
+}
+/** Build the runtime's request handler (exported for unit tests; wraps every dispatch path). */
+export function createRequestHandler(options) {
+    const onError = options.onError ?? ((ctx, err) => console.error(`[node-http] ${ctx}`, err));
+    const staticReader = options.staticReader;
+    const routing = options.routing ?? EMPTY_ROUTING;
+    const ssgPaths = new Set(routing.ssgPaths);
+    // Built once; a deployment can deliberately replace an inherited path.
+    const extra = new Map((options.extraEntrypoints ?? []).map((entry) => [entry.path, entry]));
+    return async function handle(req, res) {
+        const url = requestUrl(req);
+        const pathname = url.pathname;
+        const host = req.headers.host;
+        const bounded = (durationMs, run) => runWithHttpDeadline({ req, res, durationMs, run, onLateError: (error) => onError(`${pathname}:late`, error) });
+        const invoke = (loader, durationMs, rawStream, query) => bounded(durationMs, async () => {
+            const [mod, vreq] = await Promise.all([loader(), adaptRequest(req, pathname, rawStream)]);
+            if (query)
+                vreq.query = { ...vreq.query, ...query };
+            await mod.default(vreq, res);
+        });
+        try {
+            applySecurityHeaders(res, pathname, host, options.security);
+            if (pathname.length > 1 && pathname.endsWith("/")) {
+                res.statusCode = 308;
+                res.setHeader("location", `${pathname.replace(/\/+$/, "")}${url.search}`);
+                return finalize(res);
+            }
+            // 1. Standalone entrypoints (filesystem-parity with api/*.ts).
+            const cspReport = options.entrypoints?.cspReport;
+            if (pathname === "/api/csp-report" && cspReport) {
+                await invoke(cspReport, options.durations?.cspReport ?? 30_000);
+                return finalize(res);
+            }
+            // 1b. Deployment entrypoints: exact path, lazy load, owner-declared body policy.
+            const registered = extra.get(pathname);
+            if (registered) {
+                await invoke(registered.load, registered.maxDurationMs ?? 30_000, registered.rawStream);
+                return finalize(res);
+            }
+            const bffRouter = options.entrypoints?.bffRouter;
+            if (pathname === "/api/bff-router" && bffRouter) {
+                await invoke(bffRouter, options.durations?.bffRouter ?? 30_000);
+                return finalize(res);
+            }
+            // 1c. Deployment path-rule entrypoints, before the BFF dispatcher.
+            const routed = matchPathEntrypoint(options.pathEntrypoints, pathname);
+            if (routed) {
+                await invoke(routed.entrypoint.load, routed.entrypoint.maxDurationMs ?? 10_000, false, routed.query);
+                return finalize(res);
+            }
+            // 2. The BFF dispatcher (same routes + dispatch as the hosted entrypoint).
+            if (pathname === "/api/bff" || pathname.startsWith("/api/bff/")) {
+                await bounded(options.durations?.bff ?? 30_000, async () => options.dispatch(options.routes, await adaptRequest(req, pathname), res));
+                return finalize(res);
+            }
+            if (pathname === "/robots.txt" && options.robotsTxt) {
+                res.statusCode = 200;
+                res.setHeader("content-type", ROBOTS_CONTENT_TYPE);
+                res.setHeader("cache-control", "public, max-age=0, s-maxage=300, stale-while-revalidate=3600");
+                res.end(options.robotsTxt(host));
+                return;
+            }
+            // 3. Scheduled routes share the scheduler's single-source allowlist.
+            if (pathname.startsWith(SCHEDULED_PREFIX)) {
+                const jobId = pathname.slice(SCHEDULED_PREFIX.length);
+                const loader = options.scheduledEntrypoint?.(jobId);
+                if (loader) {
+                    await invoke(loader, options.durations?.scheduled?.(jobId) ?? 60_000);
+                    return finalize(res);
+                }
+            }
+            // 4. Unknown /api/* => 404 JSON (never fall through to the SPA).
+            if (pathname.startsWith("/api/")) {
+                res.statusCode = 404;
+                res.setHeader("content-type", "application/json; charset=utf-8");
+                res.end(JSON.stringify({ ok: false, error: { code: "NOT_FOUND", message: "Not found" } }));
+                return;
+            }
+            const legacyLocation = legacyRedirect(pathname, routing.legacyRedirects);
+            if (legacyLocation) {
+                res.statusCode = 308;
+                res.setHeader("location", `${legacyLocation}${url.search}`);
+                return finalize(res);
+            }
+            const fallback = matchPathEntrypoint(options.fallbackPathEntrypoints, pathname);
+            if (fallback) {
+                await invoke(fallback.entrypoint.load, fallback.entrypoint.maxDurationMs ?? 10_000, false, fallback.query);
+                return finalize(res);
+            }
+            // 5. Static documents and declared CSR fallback. Unknown extensionless routes are 404.
+            if (staticReader) {
+                await serveSpaStatic(req, res, pathname, staticReader, ssgPaths.has(pathname), isCsrFallback(pathname, routing.csrFallback));
+                return;
+            }
+            // No static reader configured (pure-API smoke): respond 404 rather than hang.
+            res.statusCode = 404;
+            res.end("Not Found");
+        }
+        catch (error) {
+            if (error instanceof NodeRequestAbortedError)
+                return;
+            onError(pathname, error);
+            const tooLarge = error instanceof NodeRequestBodyTooLargeError;
+            if (tooLarge)
+                closeInputAfterResponse(req, res);
+            if (!res.headersSent && !res.destroyed) {
+                res.statusCode = tooLarge ? 413 : 500;
+                res.setHeader("content-type", "application/json; charset=utf-8");
+            }
+            if (!res.writableEnded && !res.destroyed) {
+                res.end(JSON.stringify({ ok: false, error: {
+                        code: tooLarge ? "REQUEST_BODY_TOO_LARGE" : "NODE_HTTP_ERROR",
+                        message: tooLarge ? "Request body too large" : "Internal server error",
+                    } }));
+            }
+        }
+    };
+}
+/** Create the Node HttpRuntimePort: `handle` for one request, `listen` to bind the server. */
+export function createNodeHttpRuntime(options) {
+    const handle = createRequestHandler(options);
+    let server = null;
+    return {
+        server,
+        handle,
+        async listen({ port, host }) {
+            server = createServer((req, res) => {
+                void handle(decorateRequest(req), decorateResponse(res));
+            });
+            this.server = server;
+            await new Promise((resolve) => server.listen(port, host ?? "0.0.0.0", resolve));
+        },
+    };
+}

package/dist/http/security.d.ts

@@ -0,0 +1,44 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HttpResponse } from "./types.js";
+/** Deployment-owned header policy applied to every response of the Node runtime. */
+export interface NodeSecurityHeaderPolicy {
+    /** Headers set on every response unless the handler already set them, in this order. */
+    readonly globalHeaders: ReadonlyArray<readonly [string, string]>;
+    /** Static-asset path prefixes that receive the long-lived asset Cache-Control. */
+    readonly assetCachePrefixes: readonly string[];
+    /** Path families (the path or anything below it) that receive `X-Robots-Tag: noindex, nofollow`. */
+    readonly noindexFamilies: readonly string[];
+    /** Exact paths that receive `X-Robots-Tag: noindex, nofollow`. */
+    readonly noindexExacts: readonly string[];
+    /** True for a production host; every other host receives the strict non-production X-Robots-Tag. */
+    readonly isProductionHost: (host: string | undefined) => boolean;
+}
+/** Apply the deployment's global and path-specific headers for this route. */
+export declare function applySecurityHeaders(res: ServerResponse, pathname: string, host: string | undefined, policy: NodeSecurityHeaderPolicy): void;
+/** Pluggable static reader so tests can inject an in-memory dist/ without touching the filesystem. */
+export interface StaticAssetReader {
+    /** Read a built asset (returns null if it does not exist). */
+    read(relativePath: string): Promise<{
+        body: Buffer;
+        contentType: string;
+    } | null>;
+    /** The SPA fallback document (dist/index.html). */
+    readIndex(): Promise<{
+        body: Buffer;
+        contentType: string;
+    }>;
+}
+export declare function contentTypeFor(pathname: string): string;
+/** A path "looks like" a built asset if it has a file extension (so we 404 missing assets, not SPA). */
+export declare function looksLikeAsset(pathname: string): boolean;
+/**
+ * Serve a built SPA asset if present, otherwise the document the build produced for this route,
+ * otherwise the declared CSR fallback for client routes. Missing real assets (a hashed bundle that
+ * does not exist) and unknown extensionless paths return 404 rather than the SPA shell.
+ *
+ * The middle step is not decoration. The build writes each pre-rendered route as
+ * `<route>/index.html` and writes the HOME document to `index.html`; skipping that lookup hands
+ * every pre-rendered URL the home document instead of its own. The hosted platform does the same
+ * thing declaratively, one rewrite per route, which is why this host had no equivalent code.
+ */
+export declare function serveSpaStatic(_req: IncomingMessage, res: HttpResponse, pathname: string, reader: StaticAssetReader, allowRouteDocument?: boolean, allowFallback?: boolean): Promise<void>;

package/dist/http/security.js

@@ -0,0 +1,114 @@
+// Security headers + SPA static middleware for the Node HttpRuntimePort.
+//
+// Replicates, as Node middleware, a hosted response surface whose values the deployment owns:
+// the global headers (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy,
+// Permissions-Policy, Reporting-Endpoints, the content security policy), the path-specific
+// Cache-Control and X-Robots-Tag rules, and which hosts are production. The caller supplies all of
+// them through `NodeSecurityHeaderPolicy`; this module only applies them in a fixed order.
+//
+// SPA fallback boundary: the runtime handles its API and entrypoint branches before static
+// serving, so those paths never fall through to a document.
+import { extname } from "node:path";
+const ASSET_CACHE_CONTROL = "public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800";
+function matchesNoindex(policy, pathname) {
+    if (policy.noindexExacts.includes(pathname))
+        return true;
+    return policy.noindexFamilies.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+/** Apply the deployment's global and path-specific headers for this route. */
+export function applySecurityHeaders(res, pathname, host, policy) {
+    for (const [key, value] of policy.globalHeaders) {
+        if (!res.hasHeader(key))
+            res.setHeader(key, value);
+    }
+    if (policy.assetCachePrefixes.some((p) => pathname.startsWith(p))) {
+        res.setHeader("Cache-Control", ASSET_CACHE_CONTROL);
+    }
+    if (pathname === "/.well-known/security.txt") {
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    }
+    if (pathname === "/ssg-manifest.json" || pathname === "/spa-fallback.html") {
+        res.setHeader("Cache-Control", "public, max-age=0, s-maxage=0, must-revalidate");
+    }
+    if (matchesNoindex(policy, pathname)) {
+        res.setHeader("X-Robots-Tag", "noindex, nofollow");
+    }
+    if (!policy.isProductionHost(host)) {
+        res.setHeader("X-Robots-Tag", "noindex, nofollow, noarchive, nosnippet, noimageindex");
+    }
+}
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+    ".webmanifest": "application/manifest+json",
+};
+export function contentTypeFor(pathname) {
+    return CONTENT_TYPES[extname(pathname).toLowerCase()] ?? "application/octet-stream";
+}
+/** A path "looks like" a built asset if it has a file extension (so we 404 missing assets, not SPA). */
+export function looksLikeAsset(pathname) {
+    return extname(pathname) !== "";
+}
+/**
+ * Serve a built SPA asset if present, otherwise the document the build produced for this route,
+ * otherwise the declared CSR fallback for client routes. Missing real assets (a hashed bundle that
+ * does not exist) and unknown extensionless paths return 404 rather than the SPA shell.
+ *
+ * The middle step is not decoration. The build writes each pre-rendered route as
+ * `<route>/index.html` and writes the HOME document to `index.html`; skipping that lookup hands
+ * every pre-rendered URL the home document instead of its own. The hosted platform does the same
+ * thing declaratively, one rewrite per route, which is why this host had no equivalent code.
+ */
+export async function serveSpaStatic(_req, res, pathname, reader, allowRouteDocument = false, allowFallback = false) {
+    const relative = pathname === "/" ? "/index.html" : pathname;
+    const asset = await reader.read(relative);
+    if (asset) {
+        if (!res.hasHeader("content-type"))
+            res.setHeader("content-type", asset.contentType);
+        res.statusCode = 200;
+        res.end(asset.body);
+        return;
+    }
+    if (looksLikeAsset(pathname)) {
+        // A concrete asset request that does not exist -> genuine 404 (not the SPA shell).
+        res.statusCode = 404;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+        return;
+    }
+    // A manifest-declared SSG route -> its own pre-rendered document.
+    if (allowRouteDocument) {
+        const document = await reader.read(`${pathname.replace(/\/+$/, "")}/index.html`);
+        if (document) {
+            if (!res.hasHeader("content-type"))
+                res.setHeader("content-type", document.contentType);
+            res.statusCode = 200;
+            res.end(document.body);
+            return;
+        }
+    }
+    if (!allowFallback) {
+        res.statusCode = 404;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+        return;
+    }
+    // Declared client route -> SPA fallback.
+    const index = await reader.readIndex();
+    res.statusCode = 200;
+    if (!res.hasHeader("content-type"))
+        res.setHeader("content-type", index.contentType);
+    res.end(index.body);
+}

package/dist/http/staticAssets.d.ts

@@ -0,0 +1,3 @@
+import { type StaticAssetReader } from "./security.js";
+/** Read files below `distDir` (path-traversal safe; null for a missing file or a directory). */
+export declare function createDistStaticReader(distDir: string): StaticAssetReader;