@ggui-ai/mcp-server 0.6.3 → 0.8.0

package/dist/origin-validation.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Origin/Host validation for the MCP wire — the DNS-rebinding defense
+ * (ggui#438a).
+ *
+ * Spec (Streamable HTTP, 2025-11-25): "Servers MUST validate the Origin
+ * header on all incoming connections to prevent DNS rebinding attacks…
+ * If the Origin header is present and invalid, servers MUST respond
+ * with HTTP 403 Forbidden."
+ *
+ * WHY THIS IS NOT CORS: CORS governs whether a browser lets a page READ
+ * a cross-origin response; it never governs whether the request EXECUTES
+ * server-side. After a DNS rebind (attacker.com → 127.0.0.1) the page's
+ * requests are SAME-origin from the browser's view, so no preflight
+ * fires and no CORS header is consulted — only an inbound Host/Origin
+ * check catches it. See `./browser-cors.ts` for the (separate) CORS layer.
+ *
+ * WHY RAW HEADERS: `request-context.ts` honors `X-Forwarded-Host` when the
+ * TCP peer is loopback — and a rebinding attacker IS a loopback peer, so a
+ * check built on the derived host is bypassable with one attacker-supplied
+ * header. `Host` and `Origin` are forbidden header names for `fetch`, so
+ * page JS cannot forge them: the raw values are the trustworthy ones.
+ *
+ * WHY NOT THE SDK's enableDnsRebindingProtection: deprecated upstream in
+ * favor of external middleware, per-transport (never sees the WS upgrade
+ * ingress or non-transport routes), and runs after ggui's own pipeline.
+ * The 403 body + message wording here mirror the SDK's
+ * `createJsonErrorResponse` so clients see one rejection dialect.
+ */
+import type { RequestHandler } from "express";
+import type { Logger } from "./logger.js";
+/** Hostnames that mean "this machine". Compared without port. */
+export declare const LOOPBACK_HOSTNAMES: ReadonlyArray<string>;
+export interface OriginHostPolicy {
+    /**
+     * Allowed `Host` hostnames, port-agnostic and lowercased. `null`
+     * disables the Host check entirely — used when the server is bound to
+     * a non-loopback address, where the operator has explicitly opted into
+     * wide exposure and rebinding is not the applicable threat model.
+     * (Combined with --dev-allow-all that posture leaves a documented
+     * residual — the CLI warns loudly; see serve-command.ts.)
+     */
+    readonly allowedHosts: ReadonlyArray<string> | null;
+    /**
+     * Allowed page origins, lowercased, exact (scheme + host + port):
+     * the operator's `browserOrigins` plus the publicBaseUrl origin
+     * (the server's own tunnel-served pages POST with it). Loopback
+     * origins and same-origin requests are allowed unconditionally on
+     * top of this list — see `validateOriginHost`.
+     */
+    readonly allowedOrigins: ReadonlyArray<string>;
+}
+export interface OriginHostRejection {
+    readonly header: "host" | "origin";
+    /** The offending header value; empty string when the header was absent. */
+    readonly value: string;
+}
+/**
+ * Build the effective policy from deployment inputs.
+ *
+ * The Host check is active only for loopback binds — that is exactly the
+ * configuration the spec's rebinding warning targets (a local server
+ * reachable because the attacker's domain resolves to 127.0.0.1). A
+ * server bound to 0.0.0.0 or a routable address was deliberately exposed
+ * by its operator; rejecting its own LAN hostname would break phone/LAN
+ * testing for no security gain — auth is the gate there.
+ *
+ * `browserOrigins` contribute ONLY to allowedOrigins, never to
+ * allowedHosts: a page at https://app.guuey.com talking to a local serve
+ * sends `Host: localhost:6781`, so widening the anti-rebinding Host
+ * allowlist with page hostnames would serve no flow.
+ */
+export declare function buildOriginHostPolicy(input: {
+    readonly bindHost: string;
+    readonly publicBaseUrl?: string;
+    readonly browserOrigins?: ReadonlyArray<string>;
+}): OriginHostPolicy;
+/**
+ * The two validation postures this function serves. They share every
+ * rule except one: `"ws-upgrade"` additionally admits the opaque-origin
+ * ("null") Origin — see the `ingress` param below. This is a posture
+ * selector, not a literal "which wire did this arrive on" tag: the WS
+ * upgrade handler in server.ts passes `"ws-upgrade"` only for upgrades
+ * that declare bootstrap intent (`?wsToken=` present); every other
+ * upgrade is validated as `"http"`.
+ */
+export type OriginValidationIngress = "http" | "ws-upgrade";
+/**
+ * Validate one request's raw Host/Origin against the policy.
+ * Returns `null` when the request passes.
+ *
+ * Pure by design: the Express middleware and the WebSocket `upgrade`
+ * handler (a second ingress Express never sees) call the same function,
+ * so the two ingresses cannot drift. `ingress` is the one deliberate,
+ * documented point of difference between them — everything else is
+ * identical logic.
+ *
+ * @param ingress Defaults to `"http"`, so every existing HTTP call site
+ *   is unaffected. The WS upgrade handler passes `"ws-upgrade"` only
+ *   when the upgrade itself already declares bootstrap intent — see
+ *   {@link OriginValidationIngress}.
+ */
+export declare function validateOriginHost(rawHost: string | undefined, rawOrigin: string | undefined, policy: OriginHostPolicy, ingress?: OriginValidationIngress): OriginHostRejection | null;
+/** Message text for a rejection — mirrors the SDK's own wording. */
+export declare function rejectionMessage(rejection: OriginHostRejection): string;
+export declare function createOriginHostValidationMiddleware(opts: {
+    readonly policy: OriginHostPolicy;
+    /**
+     * Path prefixes where a present-and-disallowed Origin is 403'd — the
+     * MCP wire (universal /mcp, per-app prefix, /control, isolated
+     * services). The HOST check runs on EVERY path regardless: it is the
+     * actual rebinding defense and legitimate cross-origin consumers
+     * still send the server's own Host. Origin enforcement is scoped
+     * because several non-MCP surfaces are deliberately consumed
+     * cross-origin — the runtime-bundle and /code routes are fetched by
+     * sandboxed iframes whose Origin is literally `null`.
+     */
+    readonly enforceOriginPathPrefixes: ReadonlyArray<string>;
+    readonly logger: Logger;
+}): RequestHandler;
+//# sourceMappingURL=origin-validation.d.ts.map

package/dist/origin-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin-validation.d.ts","sourceRoot":"","sources":["../src/origin-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,MAAM,CAA8C,CAAC;AAEpG,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACpD;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AA8CD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACjD,GAAG,gBAAgB,CA2BnB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,YAAY,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,uBAAgC,GACxC,mBAAmB,GAAG,IAAI,CA8C5B;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAGvE;AAED,wBAAgB,oCAAoC,CAAC,IAAI,EAAE;IACzD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,cAAc,CA+CjB"}

package/dist/origin-validation.js

@@ -0,0 +1,199 @@
+/** Hostnames that mean "this machine". Compared without port. */
+export const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "::1", "[::1]"];
+/** Strip the port and surrounding brackets from a Host/authority value. */
+function hostnameOf(authority) {
+    const lower = authority.trim().toLowerCase();
+    if (lower.startsWith("[")) {
+        const close = lower.indexOf("]");
+        return close === -1 ? lower : lower.slice(0, close + 1);
+    }
+    // A bracket-less value with more than one colon is a bare IPv6
+    // address (`::1`), not host:port — return it whole. Slicing at the
+    // first colon would return "" and silently disable the Host check
+    // for an IPv6 loopback bind.
+    if (lower.indexOf(":") !== lower.lastIndexOf(":"))
+        return lower;
+    const colon = lower.indexOf(":");
+    return colon === -1 ? lower : lower.slice(0, colon);
+}
+function isLoopbackHostname(hostname) {
+    return LOOPBACK_HOSTNAMES.includes(hostname);
+}
+function isLoopbackOrigin(origin) {
+    try {
+        return isLoopbackHostname(hostnameOf(new URL(origin).host));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Same-origin allowance: does the Origin's authority (host:port) match
+ * the request's own Host? A page this server itself served (LAN bind,
+ * tunnel) sends exactly that on every POST and WS handshake; rejecting
+ * it would 403 the server's own console. Safe on loopback binds because
+ * a rebound page fails the HOST check before Origin is consulted.
+ */
+function originMatchesRequestHost(origin, rawHost) {
+    if (rawHost === undefined || rawHost.length === 0)
+        return false;
+    try {
+        return new URL(origin).host === rawHost.trim().toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the effective policy from deployment inputs.
+ *
+ * The Host check is active only for loopback binds — that is exactly the
+ * configuration the spec's rebinding warning targets (a local server
+ * reachable because the attacker's domain resolves to 127.0.0.1). A
+ * server bound to 0.0.0.0 or a routable address was deliberately exposed
+ * by its operator; rejecting its own LAN hostname would break phone/LAN
+ * testing for no security gain — auth is the gate there.
+ *
+ * `browserOrigins` contribute ONLY to allowedOrigins, never to
+ * allowedHosts: a page at https://app.guuey.com talking to a local serve
+ * sends `Host: localhost:6781`, so widening the anti-rebinding Host
+ * allowlist with page hostnames would serve no flow.
+ */
+export function buildOriginHostPolicy(input) {
+    const boundToLoopback = isLoopbackHostname(hostnameOf(input.bindHost));
+    const hosts = [...LOOPBACK_HOSTNAMES];
+    const origins = (input.browserOrigins ?? [])
+        .map((o) => o.trim().toLowerCase().replace(/\/$/, ""))
+        .filter((o) => o.length > 0);
+    if (input.publicBaseUrl !== undefined) {
+        try {
+            const url = new URL(input.publicBaseUrl);
+            // The tunnel/proxy host arrives on forwarded requests' Host
+            // header, and the server's OWN pages served from that origin
+            // (console, /r/<code>) POST + open WS with it as Origin. Both
+            // must validate, or a tunnel deployment 403s itself.
+            hosts.push(hostnameOf(url.host));
+            origins.push(url.origin.toLowerCase());
+        }
+        catch {
+            // A malformed publicBaseUrl is the caller's problem to report;
+            // silently contributing nothing keeps validation fail-closed.
+        }
+    }
+    return {
+        allowedHosts: boundToLoopback ? hosts : null,
+        allowedOrigins: origins,
+    };
+}
+/**
+ * Validate one request's raw Host/Origin against the policy.
+ * Returns `null` when the request passes.
+ *
+ * Pure by design: the Express middleware and the WebSocket `upgrade`
+ * handler (a second ingress Express never sees) call the same function,
+ * so the two ingresses cannot drift. `ingress` is the one deliberate,
+ * documented point of difference between them — everything else is
+ * identical logic.
+ *
+ * @param ingress Defaults to `"http"`, so every existing HTTP call site
+ *   is unaffected. The WS upgrade handler passes `"ws-upgrade"` only
+ *   when the upgrade itself already declares bootstrap intent — see
+ *   {@link OriginValidationIngress}.
+ */
+export function validateOriginHost(rawHost, rawOrigin, policy, ingress = "http") {
+    if (policy.allowedHosts !== null) {
+        if (rawHost === undefined || rawHost.length === 0) {
+            return { header: "host", value: "" };
+        }
+        if (!policy.allowedHosts.includes(hostnameOf(rawHost))) {
+            return { header: "host", value: rawHost };
+        }
+    }
+    // Absent Origin passes: every non-browser client omits it.
+    if (rawOrigin === undefined || rawOrigin.length === 0)
+        return null;
+    // A document with an OPAQUE origin (a srcdoc-mounted document,
+    // an about:-scheme page, or an equivalent sandboxed embedding) has no
+    // per-origin identity to serialize — the Origin header spec requires
+    // browsers to send the literal value "null" in that case, not an
+    // absence of the header. Passing `ingress: "ws-upgrade"` admits that
+    // value — but the caller (the WS upgrade handler in server.ts) only
+    // passes it when the upgrade URL already declares bootstrap intent
+    // (`?wsToken=` present); a bare opaque-origin socket with no
+    // bootstrap intent is validated as `"http"` and gets the ordinary
+    // rejection below.
+    //
+    // Admission here is NOT authentication. A bootstrap-intent socket
+    // still carries only an unverified placeholder identity at this
+    // point — the subscribe handler
+    // (`ggui-session-channel/subscribe.ts`) rejects it outright unless
+    // the `subscribe` message itself presents a credential that verifies.
+    // Origin-allowlisting a socket that can still do nothing until it
+    // clears that later gate adds no protection; rejecting "null"
+    // outright would instead break a spec-legitimate embedding topology
+    // that has no other way to send an Origin at all. The HTTP ingress
+    // has no equivalent post-admission gate, so it keeps rejecting
+    // "null" unconditionally.
+    if (ingress === "ws-upgrade" && rawOrigin.trim().toLowerCase() === "null")
+        return null;
+    const origin = rawOrigin.trim().toLowerCase().replace(/\/$/, "");
+    // Loopback pages are allowed unconditionally so the zero-config
+    // quickstart (sample SPA on :6890 → serve on :6781) needs no flags.
+    // Safe because loopback origins can only be opened by software already
+    // running on this machine.
+    if (isLoopbackOrigin(origin))
+        return null;
+    if (originMatchesRequestHost(origin, rawHost))
+        return null;
+    if (policy.allowedOrigins.includes(origin))
+        return null;
+    return { header: "origin", value: rawOrigin };
+}
+/** Message text for a rejection — mirrors the SDK's own wording. */
+export function rejectionMessage(rejection) {
+    const label = rejection.header === "host" ? "Host" : "Origin";
+    return `Invalid ${label} header: ${rejection.value}`;
+}
+export function createOriginHostValidationMiddleware(opts) {
+    const { policy, enforceOriginPathPrefixes, logger } = opts;
+    // Lowercased once at middleware-creation time so a caller passing a
+    // mixed-case service path (e.g. perAppRouting.pathPrefix) is still
+    // matched correctly below — see the req.path.toLowerCase() comment.
+    const lowerEnforcePrefixes = enforceOriginPathPrefixes.map((p) => p.toLowerCase());
+    // Dedupe log noise: a polling page would otherwise flood the log with
+    // one identical warning per request. Capped so attacker-minted unique
+    // header values cannot grow the set without bound; after the cap,
+    // rejections still 403 — they just stop logging.
+    const warned = new Set();
+    return (req, res, next) => {
+        // Express routes case-insensitively by default (no `case sensitive
+        // routing` setting here), so `POST /MCP` reaches the same handler as
+        // `POST /mcp`. Comparing req.path as-is would let that case variant
+        // skip Origin enforcement entirely — the Origin MUST must not be
+        // case-bypassable — so both sides are lowercased before comparison.
+        const path = req.path.toLowerCase();
+        const originEnforced = lowerEnforcePrefixes.some((p) => path === p || path.startsWith(`${p}/`));
+        const rejection = validateOriginHost(req.headers.host, originEnforced && typeof req.headers.origin === "string" ? req.headers.origin : undefined, policy);
+        if (rejection === null) {
+            next();
+            return;
+        }
+        const key = `${rejection.header}:${rejection.value}`;
+        if (!warned.has(key) && warned.size < 100) {
+            warned.add(key);
+            logger.warn("origin_host_rejected", {
+                header: rejection.header,
+                value: rejection.value,
+                path: req.path,
+                hint: rejection.header === "origin"
+                    ? "Add the page origin with `ggui serve --browser-origin <origin>` (or GGUI_BROWSER_ORIGINS)."
+                    : "Request arrived with an unexpected Host header — DNS-rebinding defense. Set --public-base-url if this is a legitimate proxy/tunnel host.",
+            });
+        }
+        res.status(403).json({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: rejectionMessage(rejection) },
+            id: null,
+        });
+    };
+}

package/dist/render-read-gate.d.ts

@@ -0,0 +1,50 @@
+import type { HandlerContext } from "@ggui-ai/mcp-server-handlers";
+/** The two row fields the read gate consults. */
+export interface RenderReadRowView {
+    readonly appId: string;
+    /**
+     * The row's SUBJECT — the end user a render belongs to, written at
+     * commit and nowhere else.
+     *
+     * `userId` rather than the richer `endUserIdentity` block, and that
+     * is the whole of #446. The gate used to read `endUserIdentity`,
+     * which no writer has populated since the repo split deleted the one
+     * that did (`f99b81c28`) — so the subject rung has been reading a
+     * field that is always absent, and passing every caller through as
+     * "row has no subject". Reading `userId` binds the rung for the
+     * first time.
+     *
+     * Absent stays a legitimate state: builder and anonymous
+     * single-tenant flows mint rows with no subject, and those still
+     * pass rung 4.
+     */
+    readonly userId?: string;
+}
+/**
+ * Per-session render-resource read gate (rehydration access control).
+ *
+ * Rungs, in order (spec §3):
+ *  1. Fail closed without a request context.
+ *  2. App boundary — the row's appId must equal the caller's.
+ *  3. Subject binding — a caller carrying an end-user identity (kind
+ *     'user', any auth source) reading a subject-bound row must BE
+ *     that subject. The row's subject is its `userId`, written at
+ *     commit; see {@link RenderReadRowView.userId} for why this rung
+ *     only starts binding now.
+ *  4. Everything else same-app passes: app credentials (tenant trust —
+ *     the app is obligated to enforce its own user-ownership before
+ *     fetching on a user's behalf), builder/anonymous single-tenant
+ *     flows, and rows with no subject.
+ *
+ * Deny is surfaced by the CALLER byte-identically to a missing row —
+ * reads must not oracle which sessionIds exist. This function only
+ * returns the boolean; making the two indistinguishable is the caller's
+ * obligation, and it is a real one, because "refused" and "never
+ * existed" travel completely different code paths to get there. The
+ * resource handler discharges it by collapsing a refusal to "absent"
+ * and letting every downstream branch run as it would for a locator
+ * that never existed, so both arrive at the same typed failure with the
+ * same bytes.
+ */
+export declare function renderReadAllowed(row: RenderReadRowView, ctx: HandlerContext | undefined): boolean;
+//# sourceMappingURL=render-read-gate.d.ts.map

package/dist/render-read-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-read-gate.d.ts","sourceRoot":"","sources":["../src/render-read-gate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,cAAc,GAAG,SAAS,GAC9B,OAAO,CAOT"}

package/dist/render-read-gate.js

@@ -0,0 +1,36 @@
+/**
+ * Per-session render-resource read gate (rehydration access control).
+ *
+ * Rungs, in order (spec §3):
+ *  1. Fail closed without a request context.
+ *  2. App boundary — the row's appId must equal the caller's.
+ *  3. Subject binding — a caller carrying an end-user identity (kind
+ *     'user', any auth source) reading a subject-bound row must BE
+ *     that subject. The row's subject is its `userId`, written at
+ *     commit; see {@link RenderReadRowView.userId} for why this rung
+ *     only starts binding now.
+ *  4. Everything else same-app passes: app credentials (tenant trust —
+ *     the app is obligated to enforce its own user-ownership before
+ *     fetching on a user's behalf), builder/anonymous single-tenant
+ *     flows, and rows with no subject.
+ *
+ * Deny is surfaced by the CALLER byte-identically to a missing row —
+ * reads must not oracle which sessionIds exist. This function only
+ * returns the boolean; making the two indistinguishable is the caller's
+ * obligation, and it is a real one, because "refused" and "never
+ * existed" travel completely different code paths to get there. The
+ * resource handler discharges it by collapsing a refusal to "absent"
+ * and letting every downstream branch run as it would for a locator
+ * that never existed, so both arrive at the same typed failure with the
+ * same bytes.
+ */
+export function renderReadAllowed(row, ctx) {
+    if (ctx === undefined)
+        return false;
+    if (ctx.appId !== row.appId)
+        return false;
+    if (row.userId !== undefined && ctx.userId !== undefined) {
+        return ctx.userId === row.userId;
+    }
+    return true;
+}

package/dist/runtime-bundle-route.d.ts

@@ -32,6 +32,21 @@ interface MountOptions {
     readonly runtimeBundleFile: string;
     /** Structured logger for the missing-bundle boot warning. */
     readonly logger: Logger;
+    /**
+     * Content-hashed twin of the mount — the LONG-CACHE production
+     * route. When present, `GET <path>` serves `source` with
+     * `Cache-Control: public, max-age=31536000, immutable`: the path
+     * embeds a hash of these exact bytes, so the response can never go
+     * stale under its own name, and a rebuild rolls clients over by
+     * changing the STAMPED URL rather than the cached content. Serving
+     * the captured bytes (not the file) is load-bearing for that
+     * guarantee — an in-place rebuild must not change what the old
+     * hash-name returns.
+     */
+    readonly hashed?: {
+        readonly path: string;
+        readonly source: Buffer;
+    };
 }
 /**
  * Mount `GET <runtimePath>` onto the express app. Returns nothing —

package/dist/runtime-bundle-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-bundle-route.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAiDhE"}
+{"version":3,"file":"runtime-bundle-route.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAiEhE"}

package/dist/runtime-bundle-route.js

@@ -29,13 +29,29 @@ import { existsSync } from "node:fs";
  */
 export function mountRuntimeBundleRoute(opts) {
     const { app, runtimePath, runtimeBundleFile, logger } = opts;
+    // Content-hashed long-cache route (#472) — registered ahead of the
+    // plain path so the two never shadow each other regardless of how a
+    // custom `runtimePath` glob might overlap.
+    if (opts.hashed !== undefined) {
+        const { path: hashedPath, source } = opts.hashed;
+        app.get(hashedPath, (_req, res) => {
+            res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+            // Immutable: the path names these exact bytes (see MountOptions
+            // .hashed). One download per client, zero revalidations; deploys
+            // roll over via a new stamped URL.
+            res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+            // Same CORS rationale as the plain route below.
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            res.send(source);
+        });
+    }
     if (existsSync(runtimeBundleFile)) {
         app.get(runtimePath, (_req, res) => {
             res.setHeader("Content-Type", "application/javascript; charset=utf-8");
-            // Short cache — operators iterating on the renderer want
-            // fresh copies after rebuild. Production hardening (etag,
-            // long-term caching with hashed filenames) is a follow-on
-            // concern; same posture console takes.
+            // Short cache — operators iterating on the renderer want fresh
+            // copies after rebuild. Production long-term caching lives on
+            // the hashed twin above; this name's content changes in place,
+            // so it must stay revalidated.
             res.setHeader("Cache-Control", "no-cache");
             // CORS: the bundle MUST be loadable from `<script type="module"
             // src=...>` inside a sandboxed `srcdoc` iframe (the