@ggui-ai/mcp-server 0.6.2 → 0.7.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/server.d.ts

@@ -37,9 +37,10 @@
  * handlers wired up. The `Logger.warn('dev_mode_auth_enabled')` fires
  * once at boot so operators see the shape they're running.
  */
-import type { AppMetadataStore, AuditSink, AuthAdapter, AuthResult, BlueprintIndex, BlueprintProvider, BlueprintSearch, BlueprintSelector, BlueprintStore, CodeStore, EmbeddingProvider, GeneratorRegistry, KeyValueStore, PairingService, PendingEventConsumer, ProviderKeyStore, RateLimiter, GguiSessionStore, GguiSessionStreamBuffer, ShortCodeIndex, TelemetrySink, ThreadStore, VectorStore } from "@ggui-ai/mcp-server-core";
+import type { AppMetadataStore, AuditSink, AuthAdapter, AuthResult, BlueprintIndex, BlueprintProvider, BlueprintSearch, BlueprintSelector, BlueprintStore, CodeStore, EmbeddingProvider, GeneratorRegistry, KeyValueStore, PairingService, PendingEventConsumer, ProviderKeyStore, RateLimiter, RenderIdentityStore, GguiSessionStore, GguiSessionStreamBuffer, ShortCodeIndex, TelemetrySink, ThreadStore, VectorStore } from "@ggui-ai/mcp-server-core";
 import type { SharedHandler } from "@ggui-ai/mcp-server-handlers";
 import { type ThemeCatalogEntry } from "@ggui-ai/mcp-server-handlers/app-discovery";
+import type { BlueprintDurabilityDeps } from "@ggui-ai/mcp-server-handlers/renders";
 import type { OperatorConfig, ThemeConfig } from "@ggui-ai/project-config";
 import type { DiscoveredPrimitiveCatalog, LoadedTheme } from "@ggui-ai/project-config/node";
 import type { Blueprint } from "@ggui-ai/protocol";
@@ -148,6 +149,12 @@ export declare function defaultHandlers(deps: {
     };
     readonly render?: {
         readonly renderStore: GguiSessionStore;
+        /**
+         * Render-row retention window in ms. Forwarded as-is to
+         * `createGguiRenderHandler`'s `renderTtlMs` dep. Absent = the
+         * handler's own `DEFAULT_RENDER_TTL_MS` (1h) fallback.
+         */
+        readonly renderTtlMs?: number;
         /**
          * Optional bootstrap-credential minter. When present, `ggui_render`
          * (the renamed render-commit tool) results carry the
@@ -215,6 +222,15 @@ export declare function defaultHandlers(deps: {
          * enabled.
          */
         readonly shortCodeIndex?: ShortCodeIndex;
+        /**
+         * Optional durable render-identity side store. When present, every
+         * `ggui_render` commit also records the identity a
+         * `ui://ggui/render/{sessionId}/{blueprintKey}` locator needs to
+         * re-create the render after the render row is gone. Writes are
+         * best-effort — they never block or fail a render. Absent = the
+         * deployment's render rows are themselves durable enough.
+         */
+        readonly renderIdentityStore?: RenderIdentityStore;
         /**
          * Optional provisional-preview wiring. When present, `ggui_render`
          * kicks off the configured emitter on every qualifying render (the
@@ -343,6 +359,12 @@ export declare function defaultHandlers(deps: {
      */
     readonly update?: {
         readonly renderStore: GguiSessionStore;
+        /**
+         * Durable render-identity side store — the same instance `render`
+         * writes to. When present, a successful patch refreshes the
+         * existing record off the re-committed row. Absent = no refresh.
+         */
+        readonly renderIdentityStore?: RenderIdentityStore;
         /**
          * Optional live-subscriber `props_update` notifier — typically a
          * thin closure over `GguiSessionChannelServer.sendPropsUpdate`.
@@ -1003,6 +1025,32 @@ export interface CreateGguiServerOptions {
      * when they land.
      */
     readonly renderStore?: GguiSessionStore;
+    /**
+     * Render-row retention window in ms. Operators align this with
+     * chat-history lifetime so rehydration-by-refetch (re-reading the
+     * `ui://ggui/render/*` resource after the agent's original render
+     * call) finds the row instead of a reaped one.
+     *
+     * One knob, three consumers, all of them lifecycle decisions about a
+     * render row: `ggui_render` stamps new renders with it, a re-mint
+     * commits its reconstructed row with it, and a read of a row that is
+     * present but past its expiry gives the row this lifetime again so
+     * the live-channel token minted in the same read cannot outlive it.
+     *
+     * Defaults to 1h when unset — the pre-existing memory-hygiene
+     * default for in-process stores, and the same value each consumer
+     * falls back to independently.
+     */
+    readonly renderTtlMs?: number;
+    /**
+     * #457 — total-lifetime bound on render-row RESURRECTION: the
+     * expired-read extension and the re-mint commit never advance
+     * `expiresAt` past `createdAt + maxRenderLifetimeMs`. Unset =
+     * unbounded (today's behavior). Live-row heartbeats are not capped —
+     * active use is legitimate lease renewal; this bounds how long an
+     * evicted-but-in-grace row can be kept warm by polling alone.
+     */
+    readonly maxRenderLifetimeMs?: number;
     /**
      * Outbound stream replay buffer for the live-channel endpoint. Defaults
      * to a fresh `InMemoryGguiSessionStreamBuffer` — fine for OSS zero-config
@@ -1097,6 +1145,43 @@ export interface CreateGguiServerOptions {
      * Only consulted when `renderChannel` is enabled.
      */
     readonly versionPolicy?: "advisory" | "reject";
+    /**
+     * Live-channel WS caps (ggui#444). Three of the four bound only what
+     * a NOT-YET-SUBSCRIBED (unauthenticated / unregistered) WebSocket can
+     * consume; a socket that has completed a valid subscribe is a
+     * legitimate long-lived subscriber and is exempt from those three.
+     * The fourth, `wsMaxPayloadBytes`, is the exception: a global backstop
+     * applied to EVERY frame on EVERY socket, subscribed or not. Every
+     * cap is disable-able with `0`; the three pre-subscribe caps ship
+     * generous defaults so the zero-config quickstart + e2e journeys
+     * never trip. Forwarded verbatim to `createGguiSessionChannelServer`;
+     * only consulted when `renderChannel` is enabled.
+     *
+     *   - `wsMaxPayloadBytes` — coarse ws-level `maxPayload` memory
+     *     backstop for EVERY frame on EVERY socket, INCLUDING subscribed
+     *     ones (default 1 MiB — a 100x reduction from the `ws` library's
+     *     own ~100 MiB default). `ActionEnvelope` has no protocol-level
+     *     max size, so this is a deliberately generous-but-finite
+     *     backstop, not a guarantee it never clips a legitimate frame;
+     *     raise it if legitimate `action` frames exceed the default. See
+     *     `GguiSessionChannelOptions.maxPayloadBytes`.
+     *   - `wsMaxPreSubscribePayloadBytes` — tight per-frame ceiling for
+     *     pre-subscribe frames only (default 64 KiB). See
+     *     `GguiSessionChannelOptions.maxPreSubscribePayloadBytes`.
+     *   - `wsPreSubscribeIdleMs` — grace window to complete a valid
+     *     subscribe before the socket is closed (default 30 s). See
+     *     `GguiSessionChannelOptions.preSubscribeIdleMs`.
+     *   - `wsMaxPreSubscribeConnections` — concurrent pending-socket
+     *     ceiling (default 1024). See
+     *     `GguiSessionChannelOptions.maxPreSubscribeConnections`.
+     *
+     * Cap-driven closures/refusals are counted on `/ggui/health` under
+     * `channel.caps.preSubscribeRejections`.
+     */
+    readonly wsMaxPayloadBytes?: number;
+    readonly wsMaxPreSubscribePayloadBytes?: number;
+    readonly wsPreSubscribeIdleMs?: number;
+    readonly wsMaxPreSubscribeConnections?: number;
     /**
      * Policy for the schema compat check. Checks that every
      * `actionSpec[name]` tool ref points at a tool whose
@@ -1244,6 +1329,36 @@ export interface CreateGguiServerOptions {
      * Ignored entirely when MCP Apps is disabled.
      */
     readonly wsTokenSecret?: string;
+    /**
+     * Bind host `listen()` will use, declared up front so boot-time
+     * wiring — the Origin/Host validation policy (ggui#438a) — sees the
+     * address the server will actually bind. `listen(port, host)`
+     * defaults its host argument to this value; passing a DIFFERENT
+     * host to `listen()` is a misuse (the validation policy would
+     * describe the wrong bind). Embedders who mount `.app` under their
+     * own HTTP server and never call `listen()` should set this to the
+     * host they bind. Default: `"127.0.0.1"`.
+     */
+    readonly host?: string;
+    /**
+     * Page origins permitted to reach the MCP wire from a browser.
+     *
+     * ONE list drives BOTH layers, deliberately: the Origin/Host
+     * validation gate (`./origin-validation.ts`) and the CORS response
+     * headers (`./browser-cors.ts`). Two lists would let an operator
+     * CORS-allow an origin that validation still 403s — a debugging trap
+     * with no upside.
+     *
+     * Loopback origins (`http://localhost:*`, `http://127.0.0.1:*`,
+     * `http://[::1]:*`), same-origin requests, and the `publicBaseUrl`
+     * origin are always allowed and need no entry, so the zero-config
+     * quickstart and tunnel deployments work untouched.
+     *
+     * This is NOT authentication: an allowlisted origin still presents a
+     * bearer. It controls which PAGES a browser lets talk to this
+     * server; non-browser clients ignore it entirely.
+     */
+    readonly browserOrigins?: ReadonlyArray<string>;
     /**
      * Enable the pairing transport. Adds `POST /pair` (public, completes a
      * pairing handshake) and by default `POST /admin/pair/init` (builder-
@@ -1323,6 +1438,13 @@ export interface CreateGguiServerOptions {
          * Embedded hosts that supply a custom `store` also supply the
          * right durability claim; the server doesn't inspect the store
          * instance to guess.
+         *
+         * Deliberately BINDING-SITE-level, unlike the substrate stores'
+         * port-level `durability` member (#457): this one is a
+         * health-report fact the operator asserts for display, while the
+         * substrate declaration backs a WIRE promise (NOT_FOUND ⇒
+         * restorable) — the higher bar lives on the implementation, where
+         * the knowledge is.
          */
         readonly durability?: "durable" | "ephemeral";
     };
@@ -1654,6 +1776,24 @@ export interface CreateGguiServerOptions {
      * See `defaultHandlers` for the wiring seam.
      */
     readonly shortCodeIndex?: ShortCodeIndex;
+    /**
+     * Durable side record of what each render WAS — its `blueprintId`,
+     * `contractKey`, `variantKey`, props, and event sequence at the last
+     * commit. `ggui_render` writes it at every commit; the record is what
+     * lets a `ui://ggui/render/{sessionId}/{blueprintKey}` locator
+     * re-create the render once the render row itself has aged out. The
+     * record's field is `contractKey` and the locator's segment is
+     * `blueprintKey`: one value, named for the record on one side and for
+     * its domain on the other.
+     *
+     * Optional, and inert until something reads it: writes are
+     * best-effort (a rejecting store logs and the render proceeds), and
+     * with no store bound nothing is written and every read path behaves
+     * exactly as before. Deployments whose GguiSessionStore is already
+     * durable enough to outlive the renders it holds do not need one —
+     * the row still carries everything.
+     */
+    readonly renderIdentityStore?: RenderIdentityStore;
     /**
      * Content-addressable code blob storage. When wired, this server
      * mounts `GET /code/<hash>.js` for the iframe runtime to fetch
@@ -1661,9 +1801,11 @@ export interface CreateGguiServerOptions {
      * to the store before emitting `codeUrl` on the `ai.ggui/render`
      * slice.
      *
-     * Defaults: when omitted the route is NOT mounted; the render
-     * handler falls back to inline base64 `componentCode` on the
-     * `ai.ggui/render` slice (legacy delivery channel).
+     * Defaults: when omitted the route is NOT mounted and the
+     * `ai.ggui/render` slice carries no `codeUrl` — there is no second
+     * static channel behind it. Such a deployment delivers renders
+     * through the live trio (`wsUrl` + `wsToken`); one that wires
+     * neither cannot mount a static component at all.
      *
      * OSS dev wires `FileSystemCodeStore` (rooted at `~/.ggui/code-cache/`)
      * via `ggui-cli/buildMcpServerBackend`. Tests wire
@@ -1673,6 +1815,24 @@ export interface CreateGguiServerOptions {
      * across deployments — only the storage adapter changes.
      */
     readonly codeStore?: CodeStore;
+    /**
+     * Durable write-through for freshly registered blueprints (#430
+     * slice 2). When wired, a registration that mints a new row also
+     * persists it — metadata to the `BlueprintStore`, the compiled body
+     * to the `CodeStore` — so the blueprint stays resolvable by id after
+     * the capped in-process registry has evicted it or the process has
+     * restarted.
+     *
+     * Separate from {@link codeStore} on purpose: that one backs the
+     * `GET /code/<hash>.js` delivery route and binding it changes what
+     * the render slice emits. This one is retention, and a deployment
+     * may reasonably want one without the other.
+     *
+     * Defaults: omitted ⇒ no write-through, no events, and the registry
+     * remains a blueprint's only home. Best-effort when present — a
+     * failing store logs a named event and registration still succeeds.
+     */
+    readonly durableBlueprints?: BlueprintDurabilityDeps;
     /**
      * Provisional A2UI preview wiring for `ggui_render`. When the config
      * flag is on, every qualifying component render kicks off the