@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/render-rate-limit.js

@@ -0,0 +1,73 @@
+/**
+ * Per-shortCode rate limiter.
+ *
+ * Brute-force attempts on `/r/<code>` or `/api/bootstrap/<code>` are
+ * trivially detected at the wire by per-shortCode call counts. Even
+ * with high-entropy shortCodes and HMAC-signed render URLs, the gate
+ * still hits a real backend on every request — so DoS resistance +
+ * abuse-signal logging matter independently of entropy.
+ *
+ * **Design choice — rate-limit by shortCode, not by peer.**
+ * Cross-origin iframes (claude.ai) NAT every user through the host's
+ * outbound proxy, so per-peer limits would either rate-limit the whole
+ * host (false-positive flood) or accept every peer (no signal). Per-
+ * shortCode is the right granularity: 30 hits/minute on a single
+ * code is abuse no matter who sent them; 30 hits/minute spread across
+ * 30 unique codes is normal traffic.
+ *
+ * In-memory + per-process by default. Operator-grade deployments
+ * back this with a shared store (Redis bucket counter) — wire via the
+ * {@link RenderRateLimiter} interface; the OSS reference uses a
+ * `Map<shortCode, {windowStart, count}>` with periodic cleanup.
+ */
+/**
+ * In-memory reference implementation. Cleanup runs lazily on each
+ * call — entries past their window-end are reaped before the count is
+ * read. Worst-case heap: bounded by the number of distinct shortCodes
+ * hit within the last `windowSeconds`; pre-launch OSS workloads stay
+ * tiny enough that the periodic pass is sufficient.
+ */
+export function createInMemoryRenderRateLimiter(cfg = {}) {
+    const windowMs = (cfg.windowSeconds ?? 60) * 1000;
+    const limit = cfg.limit ?? 30;
+    const now = cfg.now ?? (() => Date.now());
+    const buckets = new Map();
+    return {
+        check(shortCode) {
+            if (!shortCode) {
+                // Empty shortCode is upstream's path-validation problem; we
+                // still return allowed:true to keep the contract uniform.
+                return { allowed: true };
+            }
+            const t = now();
+            const existing = buckets.get(shortCode);
+            if (!existing || t - existing.windowStart >= windowMs) {
+                // Window expired or never opened — start a fresh window.
+                buckets.set(shortCode, { windowStart: t, count: 1 });
+                return { allowed: true };
+            }
+            if (existing.count >= limit) {
+                const retryMs = windowMs - (t - existing.windowStart);
+                return {
+                    allowed: false,
+                    retryAfterSeconds: Math.max(1, Math.ceil(retryMs / 1000)),
+                };
+            }
+            existing.count += 1;
+            return { allowed: true };
+        },
+    };
+}
+/**
+ * Mask a shortCode for log output. The full code is the credential —
+ * log it verbatim and a leaked log line becomes a leaked URL. Show
+ * just enough (first 3 chars) to correlate within a session without
+ * giving the credential away.
+ */
+export function maskShortCode(shortCode) {
+    if (!shortCode || shortCode.length === 0)
+        return '<empty>';
+    if (shortCode.length <= 3)
+        return `${shortCode}***`;
+    return `${shortCode.slice(0, 3)}***`;
+}

package/dist/render-signing.d.ts

@@ -0,0 +1,98 @@
+/**
+ * HMAC-signed render URL helpers (capability-URL hardening).
+ *
+ * The shortCode IS the credential under the capability-URL model.
+ * Signed render URLs add three properties on top of the base model
+ * (entropy + revoke + parity gate):
+ *
+ *   1. **Time-bound.** Each minted URL carries `?exp=<unix>`. Past
+ *      that timestamp, the gate refuses even if the binding still
+ *      exists. A leaked URL stops working without operator action.
+ *   2. **Tamper-evident.** Each minted URL carries `?sig=<hmac>` over
+ *      `(shortCode, exp)`. Changing either invalidates the sig.
+ *      Attackers who learn ONE valid shortCode can't generate URLs
+ *      for shortCodes they're guessing.
+ *   3. **Nuclear revoke (operational).** Rotating the signing secret
+ *      invalidates every outstanding URL across the whole server in
+ *      one move. Useful for incident response.
+ *
+ * **Threat model — what this is NOT.** The signature does not bind
+ * the URL to a user, IP, or session. Anyone with the URL still has
+ * full access until it expires. That's the Google-Docs-share-link
+ * model. It's the only viable model when the URL must be embeddable
+ * in cross-origin iframes (claude.ai), which can't attach auth
+ * headers — see plan audit dated 2026-05-15.
+ *
+ * **Key lifecycle.** Operators set `--render-signing-secret <hex>` to
+ * pin a stable key (URLs survive restarts; rotation is opt-in). When
+ * omitted, the secret is auto-generated at boot — restart = every
+ * outstanding URL dies. Document both behaviors so operators choose
+ * deliberately.
+ *
+ * **Opt-out.** `--no-render-signing` (operator boots without a signer)
+ * disables the layer entirely. The gate skips the verify step and
+ * behavior reverts to plain (unsigned) capability URLs. Useful for
+ * legacy hosts that strip query strings or tooling that pre-records
+ * URLs.
+ */
+export type RenderSignerVerifyResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: 'invalid_signature' | 'expired' | 'malformed';
+};
+export interface RenderSigner {
+    /**
+     * Mint a `{sig, exp}` pair for `shortCode`. `expSeconds` overrides
+     * the configured TTL. The returned `exp` is a unix-epoch second
+     * timestamp so URLs stay short.
+     */
+    sign(shortCode: string, expSecondsOverride?: number): {
+        readonly sig: string;
+        readonly exp: number;
+    };
+    /**
+     * Verify a `sig` + `exp` against `shortCode`. Returns `{ok: true}`
+     * on success; tagged failure otherwise. `malformed` covers missing
+     * fields, non-numeric `exp`, sig-length mismatches — distinguishing
+     * those from `invalid_signature` keeps the audit log informative
+     * without leaking detail to the wire (the response code stays
+     * uniform).
+     */
+    verify(args: {
+        readonly shortCode: string;
+        readonly sig: string | undefined;
+        readonly exp: string | undefined;
+    }): RenderSignerVerifyResult;
+    /** Encode `{sig, exp}` as a `?sig=...&exp=...` query string suitable
+     *  for appending to a render URL. Returns the suffix WITHOUT a
+     *  leading `?` or `&` — callers join with whatever separator their
+     *  URL already has. */
+    toQuerySuffix(args: {
+        readonly sig: string;
+        readonly exp: number;
+    }): string;
+}
+export interface CreateRenderSignerInput {
+    /**
+     * 32-byte hex key. When omitted, a fresh random key is minted —
+     * stable for the lifetime of this process, lost on restart.
+     * Operators wanting URLs that survive restarts MUST pass an
+     * explicit key (typically from a sealed-secret store).
+     */
+    readonly secret?: string;
+    /**
+     * Default URL lifetime in seconds. Override per-call via
+     * {@link RenderSigner.sign}'s `expSecondsOverride`.
+     */
+    readonly ttlSeconds?: number;
+    /** Clock seam for tests. Defaults to `Date.now()`. */
+    readonly now?: () => number;
+}
+/**
+ * Build a {@link RenderSigner}. Memoize the result on the server-boot
+ * scope; the secret rotates only when the operator restarts (or sets
+ * a new explicit `--render-signing-secret`).
+ */
+export declare function createRenderSigner(input?: CreateRenderSignerInput): RenderSigner;
+//# sourceMappingURL=render-signing.d.ts.map

package/dist/render-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-signing.d.ts","sourceRoot":"","sources":["../src/render-signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAUH,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,GAAG,WAAW,CAAC;CAC9D,CAAC;AAEN,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG;QACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE;QACX,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;KAClC,GAAG,wBAAwB,CAAC;IAE7B;;;2BAGuB;IACvB,aAAa,CAAC,IAAI,EAAE;QAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,GAAG,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,GAAE,uBAA4B,GAClC,YAAY,CA0Ed"}

package/dist/render-signing.js

@@ -0,0 +1,113 @@
+/**
+ * HMAC-signed render URL helpers (capability-URL hardening).
+ *
+ * The shortCode IS the credential under the capability-URL model.
+ * Signed render URLs add three properties on top of the base model
+ * (entropy + revoke + parity gate):
+ *
+ *   1. **Time-bound.** Each minted URL carries `?exp=<unix>`. Past
+ *      that timestamp, the gate refuses even if the binding still
+ *      exists. A leaked URL stops working without operator action.
+ *   2. **Tamper-evident.** Each minted URL carries `?sig=<hmac>` over
+ *      `(shortCode, exp)`. Changing either invalidates the sig.
+ *      Attackers who learn ONE valid shortCode can't generate URLs
+ *      for shortCodes they're guessing.
+ *   3. **Nuclear revoke (operational).** Rotating the signing secret
+ *      invalidates every outstanding URL across the whole server in
+ *      one move. Useful for incident response.
+ *
+ * **Threat model — what this is NOT.** The signature does not bind
+ * the URL to a user, IP, or session. Anyone with the URL still has
+ * full access until it expires. That's the Google-Docs-share-link
+ * model. It's the only viable model when the URL must be embeddable
+ * in cross-origin iframes (claude.ai), which can't attach auth
+ * headers — see plan audit dated 2026-05-15.
+ *
+ * **Key lifecycle.** Operators set `--render-signing-secret <hex>` to
+ * pin a stable key (URLs survive restarts; rotation is opt-in). When
+ * omitted, the secret is auto-generated at boot — restart = every
+ * outstanding URL dies. Document both behaviors so operators choose
+ * deliberately.
+ *
+ * **Opt-out.** `--no-render-signing` (operator boots without a signer)
+ * disables the layer entirely. The gate skips the verify step and
+ * behavior reverts to plain (unsigned) capability URLs. Useful for
+ * legacy hosts that strip query strings or tooling that pre-records
+ * URLs.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+/** Default TTL when the operator doesn't override. 24h matches the
+ *  cloud pod's ShortCode row TTL — long enough for a back-to-the-tab
+ *  user pattern, short enough that a leaked URL doesn't outlive a
+ *  reasonable incident-response window. */
+const DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+/**
+ * Build a {@link RenderSigner}. Memoize the result on the server-boot
+ * scope; the secret rotates only when the operator restarts (or sets
+ * a new explicit `--render-signing-secret`).
+ */
+export function createRenderSigner(input = {}) {
+    const secret = input.secret !== undefined && input.secret.length > 0
+        ? input.secret
+        : randomBytes(32).toString('hex');
+    const ttl = input.ttlSeconds !== undefined && input.ttlSeconds > 0
+        ? Math.floor(input.ttlSeconds)
+        : DEFAULT_TTL_SECONDS;
+    const now = input.now ?? (() => Date.now());
+    const secretBuffer = Buffer.from(secret, 'utf8');
+    function computeSig(shortCode, exp) {
+        // HMAC-SHA256 over `<shortCode>.<exp>`. Fixed separator + numeric
+        // exp keeps the input unambiguous (no length-extension or
+        // collision risk via overloaded encoding). Hex output stays
+        // URL-safe without percent-encoding.
+        return createHmac('sha256', secretBuffer)
+            .update(`${shortCode}.${exp}`)
+            .digest('hex');
+    }
+    return {
+        sign(shortCode, expSecondsOverride) {
+            const ttlForCall = expSecondsOverride !== undefined && expSecondsOverride > 0
+                ? Math.floor(expSecondsOverride)
+                : ttl;
+            const exp = Math.floor(now() / 1000) + ttlForCall;
+            return { sig: computeSig(shortCode, exp), exp };
+        },
+        verify({ shortCode, sig, exp }) {
+            if (typeof sig !== 'string' ||
+                typeof exp !== 'string' ||
+                sig.length === 0 ||
+                exp.length === 0) {
+                return { ok: false, code: 'malformed' };
+            }
+            const expNum = Number.parseInt(exp, 10);
+            if (!Number.isFinite(expNum) || expNum <= 0) {
+                return { ok: false, code: 'malformed' };
+            }
+            // Expired? Check BEFORE the HMAC compare. Expiry is a cheap
+            // numeric compare; bailing here on stale URLs avoids the more
+            // expensive constant-time sig compare on every drive-by stale
+            // hit. Information-leak concern: an attacker can probe `exp`
+            // independently of sig — but `exp` is already in the URL and
+            // not secret.
+            const nowSeconds = Math.floor(now() / 1000);
+            if (expNum < nowSeconds) {
+                return { ok: false, code: 'expired' };
+            }
+            const expected = computeSig(shortCode, expNum);
+            // Constant-time compare. Buffer length mismatch → fail without
+            // exposing length information via `timingSafeEqual` (which
+            // throws on length mismatch).
+            const a = Buffer.from(sig, 'hex');
+            const b = Buffer.from(expected, 'hex');
+            if (a.length !== b.length || a.length === 0) {
+                return { ok: false, code: 'invalid_signature' };
+            }
+            return timingSafeEqual(a, b)
+                ? { ok: true }
+                : { ok: false, code: 'invalid_signature' };
+        },
+        toQuerySuffix({ sig, exp }) {
+            return `sig=${sig}&exp=${exp}`;
+        },
+    };
+}

package/dist/request-context.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Per-request context plumbing — AsyncLocalStorage backed.
+ *
+ * The capability-URL routes (`/r/<code>`, `/api/bootstrap/<code>`) and
+ * the push/update tool result-meta builders all want to know the
+ * absolute public base URL of THIS server as seen by THIS client.
+ * That can't come from a static config in two common dev/OSS scenarios:
+ *
+ *   1. Local dev behind cloudflared / ngrok: operator runs the MCP on
+ *      `localhost:6781`, the tunnel rewrites the public host. The
+ *      server doesn't know its tunnel host at boot; cloudflared
+ *      connects over loopback and adds `X-Forwarded-Host: <tunnel>`.
+ *   2. Co-located reverse proxy (Nginx, Caddy on the same box): same
+ *      pattern, peer is loopback, host is in `X-Forwarded-Host`.
+ *
+ * Without auto-derive, every dev hits the "Runtime bundle failed to
+ * load" trap: `_meta.ggui.bootstrap.runtimeUrl` ships the relative
+ * `/_ggui/iframe-runtime.js`, the iframe boots inside an opaque
+ * srcdoc origin (claude.ai), the relative path doesn't resolve.
+ *
+ * ## Trust model — read this BEFORE adding fields here
+ *
+ * `X-Forwarded-Host` is trivially spoofable when reachable from the
+ * public internet (anyone with curl can send arbitrary headers). The
+ * only safe trust signal is **TCP peer is loopback** (127.0.0.1, ::1,
+ * IPv4-mapped loopback). Loopback means: this header was attached by
+ * a co-located process the operator deployed (cloudflared, ngrok,
+ * Nginx). Off-machine attackers can't reach the server via loopback;
+ * a remote-bind would itself be the operator's deploy choice.
+ *
+ * Auto-derive applies ONLY to data the relevant route really should
+ * derive from the request:
+ *   - runtimeUrl on push/update bootstrap meta (this slice).
+ *
+ * Auto-derive MUST NOT apply to:
+ *   - OAuth callback URLs (operator-config'd one-time per provider;
+ *     leaking spoofed host into an OAuth flow opens redirect-attack
+ *     vectors).
+ *   - Email magic-link URLs (long-lived credentials; spoofed host
+ *     makes an attacker the "trusted" destination).
+ *   - WebSocket token base URLs.
+ *
+ * Each callsite that wants auto-derive opts in explicitly via
+ * `resolvePublicBaseUrl(configuredOrUndefined)`. Everything not opting
+ * in stays static-config-only.
+ */
+import type { NextFunction, Request, Response } from 'express';
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Inferred public-facing identity of this request. */
+export interface RequestContext {
+    /** `http` or `https` — derived from X-Forwarded-Proto when peer is
+     *  local, else from `req.protocol`. */
+    readonly proto: 'http' | 'https';
+    /** Host:port the client sees us at. Either `req.host`, or
+     *  `X-Forwarded-Host` (first entry of a comma-separated list)
+     *  when the TCP peer is loopback. */
+    readonly host: string;
+    /** True iff the TCP peer is loopback. Auto-derive logic gates on
+     *  this — see file header for the trust rationale. */
+    readonly peerIsLocal: boolean;
+    /** True iff this request carried an `X-Forwarded-Host` header AND
+     *  the peer was loopback. This is the "I am behind a proxy" signal.
+     *  Auto-derive (`resolvePublicBaseUrl` without an explicit configured
+     *  value) requires both — direct localhost browser hits don't get
+     *  their URLs rewritten, only proxy-fronted ones do. */
+    readonly forwardedHostHonored: boolean;
+}
+export declare const requestContextStore: AsyncLocalStorage<RequestContext>;
+/**
+ * Build the Express middleware that runs every request inside an ALS
+ * scope. Add this near the top of the middleware chain — before any
+ * route handler or downstream `app.use` that may call `getRequestContext()`.
+ *
+ * Reads `req.socket.remoteAddress` directly (not `req.ip`) so a
+ * prior `app.set('trust proxy', ...)` configuration doesn't widen
+ * the loopback gate behind our back.
+ */
+export declare function buildRequestContextMiddleware(): (req: Request, _res: Response, next: NextFunction) => void;
+/** Read the request context out of the ALS store. Returns undefined
+ *  when called outside any request (background workers, boot setup). */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Resolve the public base URL for a request.
+ *
+ * Order:
+ *   1. Explicit configured value wins — operators ALWAYS get the last
+ *      word. Trailing slash trimmed for join-safety.
+ *   2. If a request context exists AND its TCP peer is loopback AND
+ *      the request carries a usable host, return `<proto>://<host>`.
+ *   3. Otherwise undefined — callers must fall back to their own
+ *      default (typically a relative URL or skip auto-prefixing).
+ *
+ * Returns undefined (not an empty string) so callers can distinguish
+ * "I have a base, use it" from "I don't have a base, ship the value
+ * as-is" with a simple `if (base) ...` check.
+ */
+export declare function resolvePublicBaseUrl(configured?: string): string | undefined;
+/**
+ * Resolve `runtimeUrl` against the request. If the configured/static
+ * value is already absolute, return it verbatim. Otherwise prefix it
+ * with the public base URL
+ * derived from {@link resolvePublicBaseUrl}; if no base is available,
+ * return the raw (still-relative) value so the caller's existing
+ * fall-back paths kick in.
+ *
+ * Both `runtimeUrl` arguments tolerate `undefined` to keep callsites
+ * tidy when the dep is optional.
+ */
+export declare function resolveRuntimeUrl(args: {
+    readonly configuredPublicBaseUrl?: string;
+    readonly runtimeUrl?: string;
+}): string | undefined;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../src/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B;2CACuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC;;yCAEqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;0DACsD;IACtD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;4DAIwD;IACxD,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAED,eAAO,MAAM,mBAAmB,mCAA0C,CAAC;AAW3E;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,KACnC,KAAK,OAAO,EAAE,MAAM,QAAQ,EAAE,MAAM,YAAY,UAoCzD;AAED;wEACwE;AACxE,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,MAAM,GAAG,SAAS,CAOrB"}

package/dist/request-context.js

@@ -0,0 +1,154 @@
+/**
+ * Per-request context plumbing — AsyncLocalStorage backed.
+ *
+ * The capability-URL routes (`/r/<code>`, `/api/bootstrap/<code>`) and
+ * the push/update tool result-meta builders all want to know the
+ * absolute public base URL of THIS server as seen by THIS client.
+ * That can't come from a static config in two common dev/OSS scenarios:
+ *
+ *   1. Local dev behind cloudflared / ngrok: operator runs the MCP on
+ *      `localhost:6781`, the tunnel rewrites the public host. The
+ *      server doesn't know its tunnel host at boot; cloudflared
+ *      connects over loopback and adds `X-Forwarded-Host: <tunnel>`.
+ *   2. Co-located reverse proxy (Nginx, Caddy on the same box): same
+ *      pattern, peer is loopback, host is in `X-Forwarded-Host`.
+ *
+ * Without auto-derive, every dev hits the "Runtime bundle failed to
+ * load" trap: `_meta.ggui.bootstrap.runtimeUrl` ships the relative
+ * `/_ggui/iframe-runtime.js`, the iframe boots inside an opaque
+ * srcdoc origin (claude.ai), the relative path doesn't resolve.
+ *
+ * ## Trust model — read this BEFORE adding fields here
+ *
+ * `X-Forwarded-Host` is trivially spoofable when reachable from the
+ * public internet (anyone with curl can send arbitrary headers). The
+ * only safe trust signal is **TCP peer is loopback** (127.0.0.1, ::1,
+ * IPv4-mapped loopback). Loopback means: this header was attached by
+ * a co-located process the operator deployed (cloudflared, ngrok,
+ * Nginx). Off-machine attackers can't reach the server via loopback;
+ * a remote-bind would itself be the operator's deploy choice.
+ *
+ * Auto-derive applies ONLY to data the relevant route really should
+ * derive from the request:
+ *   - runtimeUrl on push/update bootstrap meta (this slice).
+ *
+ * Auto-derive MUST NOT apply to:
+ *   - OAuth callback URLs (operator-config'd one-time per provider;
+ *     leaking spoofed host into an OAuth flow opens redirect-attack
+ *     vectors).
+ *   - Email magic-link URLs (long-lived credentials; spoofed host
+ *     makes an attacker the "trusted" destination).
+ *   - WebSocket token base URLs.
+ *
+ * Each callsite that wants auto-derive opts in explicitly via
+ * `resolvePublicBaseUrl(configuredOrUndefined)`. Everything not opting
+ * in stays static-config-only.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const requestContextStore = new AsyncLocalStorage();
+/** Loopback TCP-peer addresses we accept as the "co-located reverse
+ *  proxy" trust signal. Includes the IPv4-mapped IPv6 form Node uses
+ *  for IPv4 connections on a dual-stack socket. */
+const LOOPBACK_PEERS = new Set([
+    '127.0.0.1',
+    '::1',
+    '::ffff:127.0.0.1',
+]);
+/**
+ * Build the Express middleware that runs every request inside an ALS
+ * scope. Add this near the top of the middleware chain — before any
+ * route handler or downstream `app.use` that may call `getRequestContext()`.
+ *
+ * Reads `req.socket.remoteAddress` directly (not `req.ip`) so a
+ * prior `app.set('trust proxy', ...)` configuration doesn't widen
+ * the loopback gate behind our back.
+ */
+export function buildRequestContextMiddleware() {
+    return (req, _res, next) => {
+        const peer = req.socket.remoteAddress ?? '';
+        const peerIsLocal = LOOPBACK_PEERS.has(peer);
+        let proto = req.protocol === 'https' ? 'https' : 'http';
+        let host = req.get('host') ?? '';
+        let forwardedHostHonored = false;
+        if (peerIsLocal) {
+            const xfHost = req.get('x-forwarded-host');
+            const xfProto = req.get('x-forwarded-proto');
+            if (typeof xfHost === 'string' && xfHost.length > 0) {
+                // X-Forwarded-Host may be a comma-separated chain; the
+                // outermost (first) entry is the public-facing host.
+                const first = xfHost.split(',')[0];
+                if (typeof first === 'string' && first.trim().length > 0) {
+                    host = first.trim();
+                    forwardedHostHonored = true;
+                }
+            }
+            if (xfProto === 'http' || xfProto === 'https') {
+                proto = xfProto;
+            }
+            else if (typeof xfProto === 'string' && xfProto.includes(',')) {
+                // Same chain semantics — first entry wins.
+                const first = xfProto.split(',')[0]?.trim();
+                if (first === 'http' || first === 'https') {
+                    proto = first;
+                }
+            }
+        }
+        requestContextStore.run({ proto, host, peerIsLocal, forwardedHostHonored }, next);
+    };
+}
+/** Read the request context out of the ALS store. Returns undefined
+ *  when called outside any request (background workers, boot setup). */
+export function getRequestContext() {
+    return requestContextStore.getStore();
+}
+/**
+ * Resolve the public base URL for a request.
+ *
+ * Order:
+ *   1. Explicit configured value wins — operators ALWAYS get the last
+ *      word. Trailing slash trimmed for join-safety.
+ *   2. If a request context exists AND its TCP peer is loopback AND
+ *      the request carries a usable host, return `<proto>://<host>`.
+ *   3. Otherwise undefined — callers must fall back to their own
+ *      default (typically a relative URL or skip auto-prefixing).
+ *
+ * Returns undefined (not an empty string) so callers can distinguish
+ * "I have a base, use it" from "I don't have a base, ship the value
+ * as-is" with a simple `if (base) ...` check.
+ */
+export function resolvePublicBaseUrl(configured) {
+    if (typeof configured === 'string' && configured.length > 0) {
+        return configured.replace(/\/$/, '');
+    }
+    const ctx = getRequestContext();
+    if (!ctx || !ctx.forwardedHostHonored || !ctx.host) {
+        // No explicit `X-Forwarded-Host` from a trusted (loopback) peer
+        // means there's no proxy signal to act on. Return undefined so
+        // callers ship their static value as-is — direct browser hits
+        // resolve relative URLs against the page origin just fine.
+        return undefined;
+    }
+    return `${ctx.proto}://${ctx.host}`;
+}
+/**
+ * Resolve `runtimeUrl` against the request. If the configured/static
+ * value is already absolute, return it verbatim. Otherwise prefix it
+ * with the public base URL
+ * derived from {@link resolvePublicBaseUrl}; if no base is available,
+ * return the raw (still-relative) value so the caller's existing
+ * fall-back paths kick in.
+ *
+ * Both `runtimeUrl` arguments tolerate `undefined` to keep callsites
+ * tidy when the dep is optional.
+ */
+export function resolveRuntimeUrl(args) {
+    const raw = args.runtimeUrl;
+    if (raw === undefined)
+        return undefined;
+    if (/^https?:\/\//i.test(raw))
+        return raw;
+    const base = resolvePublicBaseUrl(args.configuredPublicBaseUrl);
+    if (!base)
+        return raw;
+    return raw.startsWith('/') ? base + raw : `${base}/${raw}`;
+}

package/dist/reserved-validators.d.ts

@@ -0,0 +1,22 @@
+import { type ReservedChannelValidator } from '@ggui-ai/protocol';
+/**
+ * Returns a reserved-validator map binding `_ggui:preview` to the A2UI
+ * adapter. Single-entry by design — each reserved channel gets its own
+ * validator; consumers that want to compose more should call
+ * {@link mergeReservedValidators}.
+ *
+ * No parameters today. When the A2UI V1 subset widens (e.g.
+ * `updateDataModel`), the adapter follows `parseServerMessage` without
+ * touching this export.
+ */
+export declare function composePreviewReservedValidator(): ReadonlyMap<string, ReservedChannelValidator>;
+/**
+ * Merge two reserved-validator maps into one. Keys present in
+ * `override` WIN on conflict — the pattern is "server supplies
+ * defaults (A2UI), caller may replace by key".
+ *
+ * Returns a `ReadonlyMap` so the composed result has the same
+ * immutability guarantee as the individual inputs.
+ */
+export declare function mergeReservedValidators(base: ReadonlyMap<string, ReservedChannelValidator> | undefined, override: ReadonlyMap<string, ReservedChannelValidator> | undefined): ReadonlyMap<string, ReservedChannelValidator> | undefined;
+//# sourceMappingURL=reserved-validators.d.ts.map

package/dist/reserved-validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-validators.d.ts","sourceRoot":"","sources":["../src/reserved-validators.ts"],"names":[],"mappings":"AA6BA,OAAO,EAGL,KAAK,wBAAwB,EAE9B,MAAM,mBAAmB,CAAC;AA0C3B;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,IAAI,WAAW,CAC5D,MAAM,EACN,wBAAwB,CACzB,CAEA;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,EAC/D,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,GAClE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,SAAS,CAS3D"}