@plitzi/sdk-server 0.32.21 → 0.32.22

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @plitzi/sdk-server
 
+## 0.32.22
+
+### Patch Changes
+
+- v0.32.22
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.32.22
+  - @plitzi/sdk-schema@0.32.22
+  - @plitzi/sdk-shared@0.32.22
+
 ## 0.32.21
 
 ### Patch Changes

package/dist/core/services/mcp.js

@@ -1,3 +1,4 @@
+import { requestProxy } from "../../modules/mcp/proxy/config.js";
 import { handleMcp } from "../../modules/mcp/handler.js";
 import { createHttpPreviewClient } from "../../modules/mcp/previewClient.js";
 import { createHttpScreenshotClient } from "../../modules/mcp/screenshotClient.js";
@@ -9,7 +10,8 @@ var serveMcp = async (ctx) => {
 		preview: previewClient ? createHttpPreviewClient(previewClient) : void 0,
 		screenshot: screenshot ? createHttpScreenshotClient(screenshot) : void 0,
 		logger,
-		renderStreaming: ctx.config.mcpAi?.renderStreaming
+		renderStreaming: ctx.config.mcpAi?.renderStreaming,
+		proxy: requestProxy(ctx.config, ctx.req)
 	});
 };
 var mcpStage = async (ctx) => {

package/dist/core/services/proxy.js

@@ -0,0 +1,12 @@
+import { proxySettings } from "../../modules/mcp/proxy/config.js";
+import { handleProxyRequest } from "../../modules/mcp/proxy/handler.js";
+//#region src/core/services/proxy.ts
+var widgetProxyStage = async (ctx) => {
+	const settings = proxySettings(ctx.config);
+	if (!settings || ctx.req.path !== settings.path) return false;
+	ctx.operation = "proxy";
+	await handleProxyRequest(ctx.req, ctx.res, settings);
+	return true;
+};
+//#endregion
+export { widgetProxyStage };

package/dist/core/services/registry.js

@@ -1,6 +1,7 @@
 import { mcpOnlyStage, mcpStage } from "./mcp.js";
 import { oauthGuardStage, oauthStage } from "./oauth.js";
 import { previewStage } from "./preview.js";
+import { widgetProxyStage } from "./proxy.js";
 import { rscStage } from "./rsc.js";
 import { notFoundStage, ssrStage } from "./ssr.js";
 import { authRoutesStages } from "../http/stages/authRoutes.js";
@@ -19,7 +20,7 @@ var buildPagePipeline = (services) => {
 		...authRoutesStages,
 		configStaticStage
 	];
-	if (services.mcp) stages.push(mcpStage);
+	if (services.mcp) stages.push(widgetProxyStage, mcpStage);
 	stages.push(previewStage);
 	stages.push(middlewaresStage);
 	if (services.rsc) stages.push(rscStage);
@@ -29,6 +30,7 @@ var buildPagePipeline = (services) => {
 var buildMCPPipeline = () => [
 	healthStage,
 	configStaticStage,
+	widgetProxyStage,
 	oauthStage,
 	oauthGuardStage,
 	mcpOnlyStage

package/dist/modules/mcp/apps/shared/registerApp.js

@@ -1,18 +1,34 @@
 import { page } from "./page.js";
 import { RESOURCE_MIME_TYPE, registerAppResource } from "@modelcontextprotocol/ext-apps/server";
 //#region src/modules/mcp/apps/shared/registerApp.ts
-var DEFAULT_CSP = {
+var defaultCsp = (proxyOrigin) => ({
 	resourceDomains: [
+		...proxyOrigin ? [proxyOrigin] : [],
 		"*",
+		"https:",
+		"https://*",
 		"data:",
 		"blob:"
 	],
-	connectDomains: ["*"]
+	connectDomains: [
+		...proxyOrigin ? [proxyOrigin] : [],
+		"*",
+		"https:",
+		"https://*"
+	]
+});
+var originOf = (endpoint) => {
+	if (!endpoint) return;
+	try {
+		return new URL(endpoint).origin;
+	} catch {
+		return;
+	}
 };
 /** Serves the app as a self-contained page: no import map, no asset mounts, no cross-origin fetches, so the
 *  strictest host sandbox runs it and no deployment has to serve anything extra. */
 var registerApp = (server, app, settings) => {
-	const meta = { ui: { csp: app.csp ?? DEFAULT_CSP } };
+	const meta = { ui: { csp: app.csp ?? defaultCsp(originOf(settings.proxyEndpoint)) } };
 	registerAppResource(server, app.name, app.uri, {
 		description: app.description,
 		_meta: meta

package/dist/modules/mcp/proxy/config.js

@@ -0,0 +1,46 @@
+import { requestOrigin } from "../../../core/requestParser.js";
+import { connectionId } from "./sign.js";
+import { DEFAULT_PROXY_TOOLS } from "./types.js";
+//#region src/modules/mcp/proxy/config.ts
+var PROXY_PATH = "/__proxy";
+var MAX_BYTES = 8388608;
+var TTL_SECONDS = 604800;
+/** What this deployment serves at its widget endpoint, or undefined when it serves none. A secret is what turns it
+*  on: without one the endpoint could not tell its own widgets' URLs from anyone else's, and an unsigned fetcher
+*  on a public origin is an open proxy. */
+var proxySettings = (config) => {
+	const proxy = config.mcpAi?.proxy;
+	if (!proxy?.secret || proxy.enabled === false) return;
+	return {
+		path: proxy.path ?? "/__proxy",
+		secret: proxy.secret,
+		maxBytes: proxy.maxBytes ?? MAX_BYTES,
+		ttl: proxy.ttl ?? TTL_SECONDS,
+		tools: proxy.tools ?? DEFAULT_PROXY_TOOLS,
+		baseUrl: proxy.baseUrl
+	};
+};
+/** The endpoint as a widget must address it: absolute, because the page runs on the host's origin and a relative
+*  URL there points at the host. Falls back to the origin this request came in on, which is the right one whenever
+*  the MCP server owns its sub-domain; a deployment reached under a different public name sets `proxy.baseUrl`.
+*  The grants it mints carry the fingerprint of THIS request's credential, so they belong to this connection. */
+var requestProxy = (config, req) => {
+	const settings = proxySettings(config);
+	if (!settings) return;
+	const base = (settings.baseUrl ?? requestOrigin(req)).replace(/\/$/, "");
+	if (!base) return;
+	return {
+		endpoint: `${base}${settings.path}`,
+		secret: settings.secret,
+		identity: connectionId(req.headers.authorization, settings.secret),
+		ttl: settings.ttl,
+		tools: settings.tools
+	};
+};
+/** The proxy THIS tool may use, or undefined — the single place that decides it, so a tool cannot reach the
+*  endpoint by being wired to it later. A render authors a throwaway widget, so rewriting its URLs is invisible
+*  and lasts as long as the widget does; a tool that WRITES a space (plitzi_apply) would persist those URLs into
+*  content the user owns, which is why it is not on the list unless a deployment puts it there deliberately. */
+var proxyForTool = (proxy, tool) => proxy?.tools.includes(tool) ? proxy : void 0;
+//#endregion
+export { PROXY_PATH, proxyForTool, proxySettings, requestProxy };

package/dist/modules/mcp/proxy/fetch.js

@@ -0,0 +1,91 @@
+import { isPublicHost } from "./guard.js";
+//#region src/modules/mcp/proxy/fetch.ts
+var TIMEOUT_MS = 1e4;
+var MAX_REDIRECTS = 4;
+var ALLOWED_TYPES = {
+	asset: [
+		"image/",
+		"video/",
+		"audio/",
+		"font/",
+		"application/font",
+		"application/octet-stream"
+	],
+	data: [
+		"application/json",
+		"application/ld+json",
+		"application/xml",
+		"text/plain",
+		"text/csv",
+		"text/xml"
+	]
+};
+var REQUEST_HEADERS = {
+	asset: {
+		"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0 Safari/537.36",
+		Accept: "image/avif,image/webp,image/apng,image/*,*/*;q=0.8",
+		"Accept-Language": "en-US,en;q=0.9"
+	},
+	data: {
+		"User-Agent": "PlitziWidget/1.0 (+https://plitzi.com)",
+		Accept: "application/json,text/plain;q=0.9,*/*;q=0.8"
+	}
+};
+var failure = (status, reason) => ({
+	ok: false,
+	status,
+	reason
+});
+var parseTarget = (target) => {
+	try {
+		const url = new URL(target);
+		return url.protocol === "http:" || url.protocol === "https:" ? url : void 0;
+	} catch {
+		return;
+	}
+};
+/** Fetch a remote resource on the widget's behalf. Redirects are followed by hand rather than by fetch, because
+*  each hop is a new host that has to pass the same guard — an allowed URL that redirects into the private network
+*  would otherwise walk straight through it. (It is also what makes the redirect-based image services work at
+*  all: the sandbox loses the redirect, this does not.) */
+var fetchResource = async (target, kind, maxBytes) => {
+	let url = parseTarget(target);
+	if (!url) return failure(400, "Only http(s) URLs can be fetched.");
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+	try {
+		for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+			if (!await isPublicHost(url.hostname)) return failure(403, "That host is not reachable from here.");
+			const response = await fetch(url, {
+				headers: REQUEST_HEADERS[kind],
+				redirect: "manual",
+				signal: controller.signal
+			});
+			const location = response.headers.get("location");
+			if (response.status >= 300 && response.status < 400 && location) {
+				const next = parseTarget(new URL(location, url).toString());
+				if (!next) return failure(502, "It redirected somewhere that is not an http(s) URL.");
+				url = next;
+				continue;
+			}
+			if (!response.ok) return failure(502, `It could not be fetched (upstream ${response.status}).`);
+			const contentType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? "";
+			if (!ALLOWED_TYPES[kind].some((allowed) => contentType.startsWith(allowed))) return failure(415, `That URL answered with ${contentType || "no content type"}, which is not ${kind === "asset" ? "an image or media file" : "data"}.`);
+			const declared = Number(response.headers.get("content-length"));
+			if (Number.isFinite(declared) && declared > maxBytes) return failure(413, "That response is too large to load in a widget.");
+			return {
+				ok: true,
+				contentType,
+				contentLength: Number.isFinite(declared) && declared > 0 ? declared : void 0,
+				body: response.body
+			};
+		}
+		return failure(502, "It redirected too many times.");
+	} catch (error) {
+		return failure(504, error instanceof Error && error.name === "AbortError" ? "It timed out." : "unreachable");
+	} finally {
+		clearTimeout(timer);
+	}
+};
+//#endregion
+export { fetchResource };

package/dist/modules/mcp/proxy/grant.js

@@ -0,0 +1,65 @@
+import { sign, verify } from "./sign.js";
+//#region src/modules/mcp/proxy/grant.ts
+/** The single query parameter a proxied URL carries: `<signature>.<kind>.<expiry>.<connection>.<target>`. One
+*  parameter rather than several so the URL holds no `&` — these end up inside HTML attributes and markdown
+*  links, where an unescaped ampersand is the kind of detail that silently truncates a URL. */
+var PARAM = "i";
+var CODE = {
+	asset: "a",
+	data: "d"
+};
+var KIND = {
+	a: "asset",
+	d: "data"
+};
+var isTemplated = (target) => target.includes("{{");
+var originOf = (target) => {
+	try {
+		return new URL(target).origin;
+	} catch {
+		return;
+	}
+};
+var encodeTarget = (target) => encodeURIComponent(target).replace(/%7B/g, "{").replace(/%7D/g, "}");
+var payloadOf = (kind, expiry, identity, target) => `${CODE[kind]}.${expiry.toString(36)}.${identity}.${target}`;
+/** Mint the URL a widget will load this target from: this server's endpoint, carrying the target, the kind it was
+*  granted for, when the grant stops working and which connection minted it — all covered by one signature. */
+var grantUrl = (target, proxy, kind = "asset") => {
+	const expiry = Math.floor(Date.now() / 1e3) + proxy.ttl;
+	const scope = (isTemplated(target) ? originOf(target) : target) ?? target;
+	const signature = sign(payloadOf(kind, expiry, proxy.identity, scope), proxy.secret);
+	const payload = `${CODE[kind]}.${expiry.toString(36)}.${proxy.identity}.${encodeTarget(target)}`;
+	return `${proxy.endpoint}?${PARAM}=${signature}.${payload}`;
+};
+/** What this endpoint was asked to fetch, or undefined when the parameter is missing, malformed, expired or not
+*  signed here — which is what keeps it from being an open proxy for anyone who finds it: it serves the URLs this
+*  server rewrote, for as long as it said, and nothing else.
+*
+*  Takes the parameter as the query parser hands it over — decoded exactly once, which is the form that was
+*  signed. Decoding it again would corrupt every target that legitimately carries a percent-escape (an API URL
+*  with a nested URL in its query) and reject it as unsigned. */
+var readGrant = (param, secret) => {
+	const parts = param?.split(".") ?? [];
+	if (parts.length < 5) return;
+	const [signature = "", code = "", expiry = "", identity = ""] = parts;
+	const kind = KIND[code];
+	const target = parts.slice(4).join(".");
+	const expiresAt = parseInt(expiry, 36);
+	if (!kind || !Number.isFinite(expiresAt) || expiresAt * 1e3 < Date.now()) return;
+	const payload = payloadOf(kind, expiresAt, identity, target);
+	if (verify(payload, signature, secret)) return {
+		kind,
+		target
+	};
+	const origin = originOf(target);
+	return origin && verify(payloadOf(kind, expiresAt, identity, origin), signature, secret) ? {
+		kind,
+		target
+	} : void 0;
+};
+/** Is this URL one the widget can already reach? Absolute http(s) URLs are the ones a sandbox CSP blocks;
+*  `data:`/`blob:` carry their own bytes, and a relative URL has no origin to reach in the first place. */
+var isRemote = (url) => /^https?:\/\//i.test(url);
+var isGranted = (url, proxy) => url.startsWith(`${proxy.endpoint}?`);
+//#endregion
+export { grantUrl, isGranted, isRemote, readGrant };

package/dist/modules/mcp/proxy/guard.js

@@ -0,0 +1,38 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+//#region src/modules/mcp/proxy/guard.ts
+var isPrivateIpv4 = (address) => {
+	const parts = address.split(".").map(Number);
+	if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return true;
+	const [a = 0, b = 0] = parts;
+	return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 0 || a === 192 && b === 168 || a === 198 && (b === 18 || b === 19) || a >= 224;
+};
+var isPrivateIpv6 = (address) => {
+	const normalized = address.toLowerCase().split("%")[0] ?? "";
+	if (normalized.startsWith("::ffff:") && normalized.includes(".")) return isPrivateIpv4(normalized.slice(7));
+	return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb");
+};
+var isPrivateAddress = (address) => isIP(address) === 6 ? isPrivateIpv6(address) : isPrivateIpv4(address);
+var PRIVATE_SUFFIXES = [
+	".local",
+	".internal",
+	".localhost",
+	".home.arpa"
+];
+/** Does this hostname resolve somewhere on the public internet? The endpoint fetches URLs an agent authored, so
+*  without this it would be a way to read whatever the pod itself can reach — the cluster's services, the cloud
+*  metadata endpoint, a database on the node. Both the literal address and every address the name resolves to are
+*  checked; a name that does not resolve is refused rather than handed to fetch. */
+var isPublicHost = async (hostname) => {
+	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	if (!host || host === "localhost" || PRIVATE_SUFFIXES.some((suffix) => host.endsWith(suffix))) return false;
+	if (isIP(host)) return !isPrivateAddress(host);
+	try {
+		const addresses = await lookup(host, { all: true });
+		return addresses.length > 0 && addresses.every((entry) => !isPrivateAddress(entry.address));
+	} catch {
+		return false;
+	}
+};
+//#endregion
+export { isPrivateAddress, isPublicHost };

package/dist/modules/mcp/proxy/handler.js

@@ -0,0 +1,69 @@
+import { readGrant } from "./grant.js";
+import { fetchResource } from "./fetch.js";
+//#region src/modules/mcp/proxy/handler.ts
+var CACHE_CONTROL = {
+	asset: "public, max-age=86400, immutable",
+	data: "no-store"
+};
+var fail = (res, status, reason) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "text/plain; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	res.send(reason);
+};
+/** Serve one external resource on behalf of a widget: check the grant this server signed, fetch the target, and
+*  stream it back under this origin — the one the CSP declares. Read-only, credential-free and CORS-open, because
+*  it answers the host's sandboxed iframe: a browser that has no origin of its own and can present nothing. The
+*  grant is what stands in for a caller identity — it is unforgeable, it names one target (or one host, for a
+*  templated API URL), it names the kind, it expires, and it carries the connection that minted it. */
+var handleProxyRequest = async (req, res, settings) => {
+	res.setHeader("Access-Control-Allow-Origin", "*");
+	res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
+	if (req.method === "OPTIONS") {
+		res.setHeader("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
+		res.setHeader("Access-Control-Allow-Headers", "*");
+		res.setStatus(204);
+		res.end();
+		return;
+	}
+	if (req.method !== "GET" && req.method !== "HEAD") {
+		fail(res, 405, "Only GET is served here.");
+		return;
+	}
+	const grant = readGrant(req.query["i"], settings.secret);
+	if (!grant) {
+		fail(res, 403, "This URL is missing a grant, or the one it carries was not issued here or has expired.");
+		return;
+	}
+	const result = await fetchResource(grant.target, grant.kind, settings.maxBytes);
+	if (!result.ok) {
+		fail(res, result.status, result.reason);
+		return;
+	}
+	res.setStatus(200);
+	res.setHeader("Content-Type", result.contentType);
+	res.setHeader("Cache-Control", CACHE_CONTROL[grant.kind]);
+	if (result.contentLength) res.setHeader("Content-Length", String(result.contentLength));
+	if (req.method === "HEAD" || !result.body) {
+		res.end();
+		return;
+	}
+	const reader = result.body.getReader();
+	let written = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			written += value.byteLength;
+			if (written > settings.maxBytes) {
+				await reader.cancel();
+				break;
+			}
+			res.write(Buffer.from(value));
+		}
+	} finally {
+		res.end();
+	}
+};
+//#endregion
+export { handleProxyRequest };

package/dist/modules/mcp/proxy/rewrite.js

@@ -0,0 +1,72 @@
+import { grantUrl, isGranted, isRemote } from "./grant.js";
+//#region src/modules/mcp/proxy/rewrite.ts
+var URL_ATTRIBUTES = ["src", "poster"];
+var MARKUP_ATTRIBUTES = ["content", "html"];
+var FETCHING_TYPE = "apiContainer";
+var CSS_URL = /url\(\s*(["']?)(https?:\/\/[^"')\s]+)\1\s*\)/gi;
+var HTML_SRC = /(<[^>]+?\ssrc\s*=\s*)(["'])(https?:\/\/[^"']+)\2/gi;
+var MARKDOWN_IMAGE = /(!\[[^\]]*\]\(\s*)(https?:\/\/[^\s)]+)/gi;
+var unescapeHtml = (url) => url.replace(/&amp;/g, "&");
+var toProxy = (url, proxy) => isGranted(url, proxy) ? url : grantUrl(unescapeHtml(url), proxy);
+/** Rewrite every remote URL embedded in a string: `url(…)` in CSS, `src="…"` in markup, `![](…)` in markdown. */
+var rewriteText = (text, proxy) => text.replace(CSS_URL, (_match, quote, url) => `url(${quote}${toProxy(url, proxy)}${quote})`).replace(HTML_SRC, (_match, prefix, quote, url) => `${prefix}${quote}${toProxy(url, proxy)}${quote}`).replace(MARKDOWN_IMAGE, (_match, prefix, url) => `${prefix}${toProxy(url, proxy)}`);
+var rewriteStyleObject = (styleObject, proxy) => {
+	for (const [property, value] of Object.entries(styleObject)) if (typeof value === "string" && value.includes("url(")) styleObject[property] = rewriteText(value, proxy);
+};
+var rewriteStyleBlock = (block, proxy) => {
+	if (block.default) rewriteStyleObject(block.default, proxy);
+	for (const state of Object.values(block.states ?? {})) rewriteStyleObject(state, proxy);
+};
+/** Why a fetching element's URL was left as authored, or undefined when it can be granted. Each case is one this
+*  hop cannot reproduce faithfully, and getting it wrong silently would be worse than the request being blocked:
+*  a write sent through a GET, or an API answering 401 because its credential was dropped on the way. */
+var unproxyableFetch = (element) => {
+	const { method, headers, accessToken } = element.attributes;
+	if (typeof method === "string" && method.toLowerCase() !== "get") return `it is a ${method.toUpperCase()} request`;
+	if (typeof accessToken === "string" && accessToken !== "") return "it sends its own credentials";
+	return headers && Object.keys(headers).length > 0 ? "it sends its own headers" : void 0;
+};
+var rewriteSchema = (schema, proxy, warnings) => {
+	for (const element of Object.values(schema.flat)) {
+		const attributes = element.attributes;
+		for (const name of URL_ATTRIBUTES) {
+			const value = attributes[name];
+			if (typeof value === "string" && isRemote(value) && !isGranted(value, proxy)) attributes[name] = grantUrl(value, proxy);
+		}
+		for (const name of MARKUP_ATTRIBUTES) {
+			const value = attributes[name];
+			if (typeof value === "string" && value.includes("http")) attributes[name] = rewriteText(value, proxy);
+		}
+		const query = attributes.query;
+		if (element.definition.type !== FETCHING_TYPE || typeof query !== "string" || !isRemote(query)) continue;
+		const blocked = unproxyableFetch(element);
+		if (blocked) {
+			warnings.push(`The ${FETCHING_TYPE} "${element.idRef ?? element.id}" calls its endpoint directly because ${blocked}, so that request is subject to the network policy of the surface it renders in, and to the CORS headers of the API, and may not run. A plain GET with no headers is fetched by the widget server instead, which always works.`);
+			continue;
+		}
+		if (!isGranted(query, proxy)) attributes.query = grantUrl(query, proxy, "data");
+	}
+};
+var rewriteStyle = (style, proxy) => {
+	for (const items of Object.values(style.platform)) for (const item of Object.values(items)) {
+		for (const selector of Object.values(item.attributes)) {
+			rewriteStyleBlock(selector, proxy);
+			for (const variant of Object.values(selector.variants ?? {})) rewriteStyleBlock(variant, proxy);
+		}
+		if (item.cache.includes("url(")) item.cache = rewriteText(item.cache, proxy);
+	}
+	if (style.cache.includes("url(")) style.cache = rewriteText(style.cache, proxy);
+};
+/** Point everything an authored widget loads from outside — images, media, fonts, and the data an apiContainer
+*  fetches — at this server's endpoint, in place. The AGENT never sees this: it authors the real URL and this runs
+*  afterwards, on the throwaway space a render builds (so nothing shared is mutated) and before the global style
+*  cache is compiled (so the concatenated CSS comes out already rewritten). Returns what could not be rewritten,
+*  which is the only part the model hears about. */
+var proxifyResources = (space, proxy) => {
+	const warnings = [];
+	rewriteSchema(space.schema, proxy, warnings);
+	rewriteStyle(space.style, proxy);
+	return warnings;
+};
+//#endregion
+export { proxifyResources, rewriteText };

package/dist/modules/mcp/proxy/sign.js

@@ -0,0 +1,15 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/modules/mcp/proxy/sign.ts
+var SIGNATURE_LENGTH = 22;
+var sign = (payload, secret) => createHmac("sha256", secret).update(payload).digest("base64url").slice(0, SIGNATURE_LENGTH);
+var verify = (payload, signature, secret) => {
+	const expected = Buffer.from(sign(payload, secret));
+	const given = Buffer.from(signature);
+	return expected.length === given.length && timingSafeEqual(expected, given);
+};
+/** A short, stable fingerprint of the MCP credential a request carried — the connection a grant belongs to.
+*  Derived through the same secret, so it identifies without echoing any part of the token; a request with no
+*  credential (the public widgets surface) gets the shared anonymous identity. */
+var connectionId = (authorization, secret) => authorization ? sign(`id:${authorization}`, secret).slice(0, 10) : "anon";
+//#endregion
+export { connectionId, sign, verify };

package/dist/modules/mcp/proxy/types.js

@@ -0,0 +1,9 @@
+//#region src/modules/mcp/proxy/types.ts
+/** The tools a proxy may be handed to. `plitzi_render` alone by default, and that default is a guard, not a
+*  convenience: a render is a THROWAWAY widget, so rewriting its URLs changes nothing that outlives the call —
+*  while plitzi_apply writes to the user's real space, where a rewritten URL would be PERSISTED and the space
+*  would come to depend on this server's endpoint for content it owns. Nothing else should be added here without
+*  that being the intention. */
+var DEFAULT_PROXY_TOOLS = ["plitzi_render"];
+//#endregion
+export { DEFAULT_PROXY_TOOLS };

package/dist/modules/mcp/resources/renderGuide.js

@@ -275,6 +275,22 @@ that is not here (lists, tabs, dialogs, forms, icons…).
 base64 raster) — both render with no extra setup. For a **vector** graphic do not encode a \`data:\` URI: draw it
 inline, as below.
 
+**Anything loaded from the internet.** Write the real URL and nothing else: images, video, fonts and the endpoint
+an \`apiContainer\` reads are re-pointed at the render server after the widget is built, and it fetches them for
+the widget. That is invisible to you and there is nothing to opt into — it is what settles the redirects, the
+hotlink rules and the missing CORS headers that a widget, running in the surface's sandbox, cannot settle itself.
+What it cannot do is guess:
+
+- **Use URLs you have actually seen work.** A direct file URL, not a page about the picture, not a search result,
+  not a pattern you assembled from memory. A URL that 404s or answers with HTML instead of an image leaves a grey
+  placeholder box in the middle of an otherwise finished layout.
+- **With no URL you trust, do not invent one.** Draw that block instead: a \`linear-gradient\`, a flat colour, an
+  inline \`<svg>\` or a \`data:\` URI — none touch the network and all of them always render.
+- **A plain GET is the request that always works.** An \`apiContainer\` with a custom \`method\`, \`headers\` or
+  \`accessToken\` is called directly by the widget instead, so it is then subject to the surface's own network
+  policy and the API's CORS headers — the render warns you when that happens. \`{{tokens}}\` in the URL are fine.
+  When you are showing a shape rather than live data, \`mockData\` needs no network at all.
+
 ## Draw with inline SVG
 
 A widget can draw its own graphics, and it is often the difference between a plain block of text and something

package/dist/modules/mcp/server.js

@@ -2,6 +2,7 @@ import { registerApps } from "./apps/index.js";
 import { NoSpaceError, emptySpace, emptySpaceMessage, noSpaceError } from "./helpers/space.js";
 import { serverInstructions, widgetsOnlyInstructions } from "./helpers/guide.js";
 import { createMcpLog } from "./helpers/log.js";
+import { proxyForTool } from "./proxy/config.js";
 import { registerResources } from "./resources/register.js";
 import { tools } from "./tools/index.js";
 import { isCallToolResult } from "../ai/toolkit.js";
@@ -13,7 +14,7 @@ var asText = (data) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(data)
 }] });
-var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger, renderStreaming = true }) => {
+var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger, renderStreaming = true, proxy }) => {
 	const log = createMcpLog(logger);
 	const spaceId = await getSpaceId().catch(() => void 0);
 	const hasSpace = spaceId !== void 0;
@@ -44,28 +45,33 @@ var createMcpServer = async ({ adapters, getSpaceId, preview, screenshot, logger
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.32.21"
+		version: "0.32.22"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace);
-	registerApps(server, { streaming: renderStreaming });
-	const toolContext = async () => ({
+	registerApps(server, {
+		streaming: renderStreaming,
+		proxyEndpoint: proxy?.endpoint
+	});
+	const toolContext = async (tool) => ({
 		space: await getSpace(),
 		env: MCP_ENV,
 		persisters,
 		spaceId: requireSpaceId(),
 		preview,
-		screenshot
+		screenshot,
+		proxy: proxyForTool(proxy, tool)
 	});
-	const spacelessContext = () => ({
+	const spacelessContext = (tool) => ({
 		space: emptySpace(),
 		env: MCP_ENV,
 		persisters,
 		preview,
-		screenshot
+		screenshot,
+		proxy: proxyForTool(proxy, tool)
 	});
 	const behaviorOf = (tool) => {
-		if (tool.spaceless) return (args) => tool.execute(args, spacelessContext());
-		if (hasSpace) return async (args) => tool.execute(args, await toolContext());
+		if (tool.spaceless) return (args) => tool.execute(args, spacelessContext(tool.name));
+		if (hasSpace) return async (args) => tool.execute(args, await toolContext(tool.name));
 		return tool.executePublic ? (args) => tool.executePublic?.(args, MCP_ENV) : void 0;
 	};
 	for (const tool of tools) {

package/dist/modules/mcp/tools/render.js

@@ -1,6 +1,7 @@
 import { iconFontCss } from "../apps/render/styles.js";
 import { RENDER_APP_URI } from "../apps/render/index.js";
 import { emptySpace } from "../helpers/space.js";
+import { proxifyResources } from "../proxy/rewrite.js";
 import { operations } from "./operations/index.js";
 import { applyOperations } from "./apply/dispatch.js";
 import { expandOperations } from "./shared/expandOperations.js";
@@ -41,7 +42,7 @@ var renderShape = {
 	patch: z.boolean().optional().describe("Set true to CHANGE a widget you already rendered instead of rebuilding it: send its `renderId` and ONLY the operations that differ (patchDefinition, patchElement, deleteElement, a new repeatElement…). The widget merges them into the batch it was built from and reports back what it applied. The refs it already has (card-1, blk-2-3) are the ones to address. If that widget cannot be recovered — a surface that renders none, a host that keeps no storage — the answer says so and you re-send the whole batch."),
 	renderId: z.string().optional().describe("Handle returned by a previous render. Required with patch:true; it names the widget being changed.")
 };
-var render = (input) => {
+var render = (input, options = {}) => {
 	const space = seedSpace();
 	const expansion = expandOperations(input.operations);
 	if (expansion.errors.length > 0) return {
@@ -78,6 +79,7 @@ var render = (input) => {
 		errors: audit.errors,
 		warnings: noWarnings(warnings)
 	};
+	if (options.proxy) warnings.push(...proxifyResources(space, options.proxy));
 	space.style.cache = generateCache(space.style);
 	return {
 		rendered: true,
@@ -171,12 +173,12 @@ var toRenderResult = (res, renderId) => {
 var renderTool = defineTool({
 	name: "plitzi_render",
 	title: "Render widget",
-	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n1b. REPEATS — the moment two siblings share a shape and differ only in data (list, steps, cards, table, timeline), do NOT copy-paste them: use repeatElement { pageRef, ref (wrapper), style, template, items }. The template is written once with {{item.field}} placeholders and rendered per row; refs come out numbered (\"step-1\", \"step-2\"…). A list INSIDE each row (days with their own steps) is the same op: give the wrapping node repeat:{ items:\"{{item.<list>}}\", template:… } and put the sub-rows in the row data.\n2. STYLE — declare ALL the classes in ONE upsertDefinitions { definitions: { \"<class>\": { desktop:{ …CSS in kebab-case… } }, … } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid. Keep the call small: one class per look, not per property.\n2a. GRAPHICS — a logo, a sparkline, a badge, a decorative shape: draw it as an INLINE <svg> in a blockHtml element (props.content), keeping a viewBox with width/height \"100%\" so its class sizes it, and fill/stroke \"currentColor\" so it follows the host theme. Budget it: a handful of paths, drawn once and reused, never a data: URI and never a full illustration — a photo-real scene costs more than the whole widget, so use an https image, a flat colour or a gradient for that. Markup only: scripts and on* handlers are rejected.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Nothing carries a minimum size, so an element with no content and no size takes none — give a spacer or a rail its own height/width — while heading/paragraph do keep the margins the browser gives them (zero them, space with the parent gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nITERATING — to change a widget you already rendered, do NOT rebuild it: call again with patch:true, the `renderId` that render answered with, and ONLY the operations that differ (patchDefinition, patchElement, deleteElement…). The widget merges them and reports back what it applied; address rows by the refs you already know. Patch ONLY to modify that widget: a different subject or a different kind of widget is a fresh render, without patch — a patch is merged into the previous batch, so patching a new idea leaves you with both.\nReturns a compact summary including the renderId (the widget itself is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
+	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n1b. REPEATS — the moment two siblings share a shape and differ only in data (list, steps, cards, table, timeline), do NOT copy-paste them: use repeatElement { pageRef, ref (wrapper), style, template, items }. The template is written once with {{item.field}} placeholders and rendered per row; refs come out numbered (\"step-1\", \"step-2\"…). A list INSIDE each row (days with their own steps) is the same op: give the wrapping node repeat:{ items:\"{{item.<list>}}\", template:… } and put the sub-rows in the row data.\n2. STYLE — declare ALL the classes in ONE upsertDefinitions { definitions: { \"<class>\": { desktop:{ …CSS in kebab-case… } }, … } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid. Keep the call small: one class per look, not per property.\n2a. GRAPHICS — a logo, a sparkline, a badge, a decorative shape: draw it as an INLINE <svg> in a blockHtml element (props.content), keeping a viewBox with width/height \"100%\" so its class sizes it, and fill/stroke \"currentColor\" so it follows the host theme. Budget it: a handful of paths, drawn once and reused, never a data: URI and never a full illustration — a photo-real scene costs more than the whole widget, so use an https image, a flat colour or a gradient for that. Markup only: scripts and on* handlers are rejected.\n2b. LAYOUT — it renders in a side panel, so width is free and HEIGHT is scarce. Plain containers stack children vertically, which is the tall half-empty default to avoid: put peers (metrics, plans, options, image + text) in a wrapping row — display:flex, flex-direction:row, flex-wrap:wrap, children flex-grow:\"1\" + flex-basis:\"0%\" + min-width — or a grid with grid-template-columns:\"repeat(auto-fit, minmax(160px, 1fr))\". Keep padding 12-16px and gap 8-12px, and let the outer container fill the panel. Stack only what reads in order (heading over paragraph, forms, steps, prose). Nothing carries a minimum size, so an element with no content and no size takes none — give a spacer or a rail its own height/width — while heading/paragraph do keep the margins the browser gives them (zero them, space with the parent gap).\n2c. THEME — it is embedded in the host UI, which MAY BE DARK, so never hardcode a light palette. Take colours from the host variables with a light-dark() fallback — background-color:\"var(--color-background-secondary, light-dark(#ffffff, #1f2430))\", color:\"var(--color-text-primary, light-dark(#0f172a, #e8eaed))\", border-color:\"var(--color-border-primary, light-dark(#e2e8f0, #333a48))\" — and always set `color` wherever you set `background-color` (a brand accent states its own text colour too).\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. Write real https URLs: everything the widget loads from outside (images, media, fonts, an apiContainer endpoint) is fetched for it by the render server, so redirects and hotlink rules are handled and there is nothing to configure. It must still point at the actual file — use a URL you have seen work, and when you have none, draw the block with a gradient or an inline SVG instead of guessing one. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nITERATING — to change a widget you already rendered, do NOT rebuild it: call again with patch:true, the `renderId` that render answered with, and ONLY the operations that differ (patchDefinition, patchElement, deleteElement…). The widget merges them and reports back what it applied; address rows by the refs you already know. Patch ONLY to modify that widget: a different subject or a different kind of widget is a fresh render, without patch — a patch is merged into the previous batch, so patching a new idea leaves you with both.\nReturns a compact summary including the renderId (the widget itself is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
 	inputShape: renderShape,
 	access: "read",
 	spaceless: true,
 	ui: { resourceUri: RENDER_APP_URI },
-	run: (input) => input.patch === true ? toPatchResult(input.operations, input.renderId) : toRenderResult(render(input), input.renderId ?? newRenderId())
+	run: (input, ctx) => input.patch === true ? toPatchResult(input.operations, input.renderId) : toRenderResult(render(input, { proxy: ctx.proxy }), input.renderId ?? newRenderId())
 });
 //#endregion
 export { render, renderShape, renderTool };

package/dist/src/core/services/proxy.d.ts

@@ -0,0 +1,2 @@
+import { Stage } from '../http/types';
+export declare const widgetProxyStage: Stage;

package/dist/src/modules/mcp/handler.d.ts

@@ -1,4 +1,5 @@
 import { createMcpServer } from './server';
+import { ResourceProxy } from './proxy';
 import { PreviewClient, ScreenshotClient } from './types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SSRAdapters, SSRRequest, ServerLogger } from '@plitzi/sdk-shared';
@@ -11,6 +12,9 @@ export type McpRequestOptions = {
     logger?: ServerLogger;
     /** Deployment switch for the plitzi_render view (see `mcpAi.renderStreaming`). Defaults to true. */
     renderStreaming?: boolean;
+    /** Where a rendered widget loads everything external from (see `mcpAi.proxy`). Absent → the URLs an agent
+     *  authored travel to the host exactly as written. */
+    proxy?: ResourceProxy;
 };
 export declare const readMcpBody: (req: IncomingMessage) => Promise<unknown>;
 export declare const serveMcp: (raw: IncomingMessage, res: ServerResponse, server: McpServer) => Promise<string | undefined>;

package/dist/src/modules/mcp/proxy/config.d.ts

@@ -0,0 +1,17 @@
+import { ResourceProxy, ResourceProxySettings } from './types';
+import { SSRRequest, SSRServerConfig } from '@plitzi/sdk-shared';
+export declare const PROXY_PATH = "/__proxy";
+/** What this deployment serves at its widget endpoint, or undefined when it serves none. A secret is what turns it
+ *  on: without one the endpoint could not tell its own widgets' URLs from anyone else's, and an unsigned fetcher
+ *  on a public origin is an open proxy. */
+export declare const proxySettings: (config: SSRServerConfig) => ResourceProxySettings | undefined;
+/** The endpoint as a widget must address it: absolute, because the page runs on the host's origin and a relative
+ *  URL there points at the host. Falls back to the origin this request came in on, which is the right one whenever
+ *  the MCP server owns its sub-domain; a deployment reached under a different public name sets `proxy.baseUrl`.
+ *  The grants it mints carry the fingerprint of THIS request's credential, so they belong to this connection. */
+export declare const requestProxy: (config: SSRServerConfig, req: SSRRequest) => ResourceProxy | undefined;
+/** The proxy THIS tool may use, or undefined — the single place that decides it, so a tool cannot reach the
+ *  endpoint by being wired to it later. A render authors a throwaway widget, so rewriting its URLs is invisible
+ *  and lasts as long as the widget does; a tool that WRITES a space (plitzi_apply) would persist those URLs into
+ *  content the user owns, which is why it is not on the list unless a deployment puts it there deliberately. */
+export declare const proxyForTool: (proxy: ResourceProxy | undefined, tool: string) => ResourceProxy | undefined;

package/dist/src/modules/mcp/proxy/endpoint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/mcp/proxy/fetch.d.ts

@@ -0,0 +1,18 @@
+import { ProxyKind } from './types';
+export type FetchFailure = {
+    ok: false;
+    status: number;
+    reason: string;
+};
+export type FetchSuccess = {
+    ok: true;
+    contentType: string;
+    contentLength?: number;
+    body: Response['body'];
+};
+export type FetchResult = FetchFailure | FetchSuccess;
+/** Fetch a remote resource on the widget's behalf. Redirects are followed by hand rather than by fetch, because
+ *  each hop is a new host that has to pass the same guard — an allowed URL that redirects into the private network
+ *  would otherwise walk straight through it. (It is also what makes the redirect-based image services work at
+ *  all: the sandbox loses the redirect, this does not.) */
+export declare const fetchResource: (target: string, kind: ProxyKind, maxBytes: number) => Promise<FetchResult>;

package/dist/src/modules/mcp/proxy/grant.d.ts

@@ -0,0 +1,23 @@
+import { ProxyKind, ResourceProxy } from './types';
+/** What a widget was granted. The kind is signed in too, so a URL minted for an image cannot be replayed as an
+ *  API call (they answer with different content types, cache rules and request headers). */
+export type Grant = {
+    kind: ProxyKind;
+    target: string;
+};
+/** Mint the URL a widget will load this target from: this server's endpoint, carrying the target, the kind it was
+ *  granted for, when the grant stops working and which connection minted it — all covered by one signature. */
+export declare const grantUrl: (target: string, proxy: ResourceProxy, kind?: ProxyKind) => string;
+/** What this endpoint was asked to fetch, or undefined when the parameter is missing, malformed, expired or not
+ *  signed here — which is what keeps it from being an open proxy for anyone who finds it: it serves the URLs this
+ *  server rewrote, for as long as it said, and nothing else.
+ *
+ *  Takes the parameter as the query parser hands it over — decoded exactly once, which is the form that was
+ *  signed. Decoding it again would corrupt every target that legitimately carries a percent-escape (an API URL
+ *  with a nested URL in its query) and reject it as unsigned. */
+export declare const readGrant: (param: string | undefined, secret: string) => Grant | undefined;
+export declare const PROXY_PARAM = "i";
+/** Is this URL one the widget can already reach? Absolute http(s) URLs are the ones a sandbox CSP blocks;
+ *  `data:`/`blob:` carry their own bytes, and a relative URL has no origin to reach in the first place. */
+export declare const isRemote: (url: string) => boolean;
+export declare const isGranted: (url: string, proxy: ResourceProxy) => boolean;

package/dist/src/modules/mcp/proxy/guard.d.ts

@@ -0,0 +1,6 @@
+export declare const isPrivateAddress: (address: string) => boolean;
+/** Does this hostname resolve somewhere on the public internet? The endpoint fetches URLs an agent authored, so
+ *  without this it would be a way to read whatever the pod itself can reach — the cluster's services, the cloud
+ *  metadata endpoint, a database on the node. Both the literal address and every address the name resolves to are
+ *  checked; a name that does not resolve is refused rather than handed to fetch. */
+export declare const isPublicHost: (hostname: string) => Promise<boolean>;

package/dist/src/modules/mcp/proxy/handler.d.ts

@@ -0,0 +1,8 @@
+import { ResourceProxySettings } from './types';
+import { SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/** Serve one external resource on behalf of a widget: check the grant this server signed, fetch the target, and
+ *  stream it back under this origin — the one the CSP declares. Read-only, credential-free and CORS-open, because
+ *  it answers the host's sandboxed iframe: a browser that has no origin of its own and can present nothing. The
+ *  grant is what stands in for a caller identity — it is unforgeable, it names one target (or one host, for a
+ *  templated API URL), it names the kind, it expires, and it carries the connection that minted it. */
+export declare const handleProxyRequest: (req: SSRRequest, res: SSRResponseHelpers, settings: ResourceProxySettings) => Promise<void>;

package/dist/src/modules/mcp/proxy/index.d.ts

@@ -0,0 +1,7 @@
+export { PROXY_PATH, proxyForTool, proxySettings, requestProxy } from './config';
+export { grantUrl, isGranted, isRemote, PROXY_PARAM, readGrant } from './grant';
+export { handleProxyRequest } from './handler';
+export { proxifyResources, rewriteText } from './rewrite';
+export { connectionId, sign, verify } from './sign';
+export { DEFAULT_PROXY_TOOLS } from './types';
+export type { ProxyKind, ResourceProxy, ResourceProxySettings } from './types';

package/dist/src/modules/mcp/proxy/proxy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/mcp/proxy/rewrite.d.ts

@@ -0,0 +1,13 @@
+import { ResourceProxy } from './types';
+import { Schema, Style } from '@plitzi/sdk-shared';
+/** Rewrite every remote URL embedded in a string: `url(…)` in CSS, `src="…"` in markup, `![](…)` in markdown. */
+export declare const rewriteText: (text: string, proxy: ResourceProxy) => string;
+/** Point everything an authored widget loads from outside — images, media, fonts, and the data an apiContainer
+ *  fetches — at this server's endpoint, in place. The AGENT never sees this: it authors the real URL and this runs
+ *  afterwards, on the throwaway space a render builds (so nothing shared is mutated) and before the global style
+ *  cache is compiled (so the concatenated CSS comes out already rewritten). Returns what could not be rewritten,
+ *  which is the only part the model hears about. */
+export declare const proxifyResources: (space: {
+    schema: Schema;
+    style: Style;
+}, proxy: ResourceProxy) => string[];

package/dist/src/modules/mcp/proxy/sign.d.ts

@@ -0,0 +1,6 @@
+export declare const sign: (payload: string, secret: string) => string;
+export declare const verify: (payload: string, signature: string, secret: string) => boolean;
+/** A short, stable fingerprint of the MCP credential a request carried — the connection a grant belongs to.
+ *  Derived through the same secret, so it identifies without echoing any part of the token; a request with no
+ *  credential (the public widgets surface) gets the shared anonymous identity. */
+export declare const connectionId: (authorization: string | undefined, secret: string) => string;

package/dist/src/modules/mcp/proxy/types.d.ts

@@ -0,0 +1,45 @@
+/** What a widget is loading. Both ride the same endpoint but are not the same thing: an asset is immutable and
+ *  cached hard, data is an API answer that must never be served stale, and each accepts its own content types. */
+export type ProxyKind = 'asset' | 'data';
+/** How a widget reaches ANYTHING outside its sandbox — an image, a font, a video, an API.
+ *
+ *  An MCP App runs in an iframe on the HOST's origin under a CSP the host builds from the domains this server
+ *  declares, and that declaration belongs to the `ui://` RESOURCE: it is read (and may be cached) before any
+ *  widget exists, the spec types `csp` as `never` on the tool meta, and plitzi_render is stateless, so the origins
+ *  an agent is about to author can never be listed there. The one origin that CAN be declared up front is this
+ *  server's own, so every external URL a render authored is rewritten to point here and this server fetches the
+ *  original — which also settles the redirects, hotlink rules and missing CORS headers a null-origin sandbox
+ *  cannot. Nothing is stored: the URL carries its own signed grant, so any replica answers any request. */
+export interface ResourceProxy {
+    /** Absolute endpoint the browser fetches from, e.g. `https://mcp.plitzi.app/__proxy`. */
+    endpoint: string;
+    /** Signs the grant, so the endpoint serves what this server rewrote and not whatever a caller asks for. */
+    secret: string;
+    /** Fingerprint of the MCP credential the render was called with (see `connectionId`). It is signed into every
+     *  URL, so the grants one connection minted are distinct from another's and a widget's URLs cannot be pooled. */
+    identity: string;
+    /** How long a minted URL stays valid, in seconds. A widget outlives the call that made it (it sits in the
+     *  conversation), so this is days rather than minutes — but not forever, so a leaked URL stops working. */
+    ttl: number;
+    /** The tools allowed to rewrite through this endpoint (see {@link DEFAULT_PROXY_TOOLS}). Carried here because
+     *  the decision is made once, where each tool's context is built. */
+    tools: readonly string[];
+}
+/** The tools a proxy may be handed to. `plitzi_render` alone by default, and that default is a guard, not a
+ *  convenience: a render is a THROWAWAY widget, so rewriting its URLs changes nothing that outlives the call —
+ *  while plitzi_apply writes to the user's real space, where a rewritten URL would be PERSISTED and the space
+ *  would come to depend on this server's endpoint for content it owns. Nothing else should be added here without
+ *  that being the intention. */
+export declare const DEFAULT_PROXY_TOOLS: string[];
+/** The endpoint's own side of the same feature: where it answers and what it will carry. */
+export interface ResourceProxySettings {
+    path: string;
+    secret: string;
+    maxBytes: number;
+    ttl: number;
+    /** Which tools rewrite their URLs through the endpoint (see {@link DEFAULT_PROXY_TOOLS}). */
+    tools: readonly string[];
+    /** Absolute base to build widget URLs from. Empty → the origin each request arrived on, which is right whenever
+     *  the MCP server owns its sub-domain. */
+    baseUrl?: string;
+}

package/dist/src/modules/mcp/proxy/wiring.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/mcp/server.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ResourceProxy } from './proxy';
 import { PreviewClient, ScreenshotClient } from './types';
 import { SSRAdapters, ServerLogger } from '@plitzi/sdk-shared';
 /** The MCP service is stateless: every request resolves its own `spaceId` (from the request JWT) and reads the
@@ -22,5 +23,9 @@ export interface McpServerContext {
     /** May the plitzi_render view paint from tool arguments the host is still streaming (see `mcpAi.renderStreaming`)?
      *  Defaults to true. */
     renderStreaming?: boolean;
+    /** Where a rendered widget loads everything external from (see `mcpAi.proxy`). It reaches two places: the render
+     *  tool, which rewrites the URLs the agent authored, and the App's CSP, which declares the origin those URLs
+     *  point at. Absent → neither happens, and a widget's resources load only where the host allows their origin. */
+    proxy?: ResourceProxy;
 }
-export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger, renderStreaming }: McpServerContext) => Promise<McpServer>;
+export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger, renderStreaming, proxy }: McpServerContext) => Promise<McpServer>;

package/dist/src/modules/mcp/tools/render.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { ResourceProxy } from '../proxy';
 import { Operation } from './operations';
 import { OfflineDataRaw } from '@plitzi/sdk-shared';
 export declare const renderShape: {
@@ -470,6 +471,12 @@ export type RenderInput = {
     patch?: boolean;
     renderId?: string;
 };
+/** What the render needs from its host beyond the operations. Optional: a host that wires no resource endpoint
+ *  still renders a widget — one whose external URLs travel as authored and load only where the surface allows
+ *  their origin. */
+export type RenderOptions = {
+    proxy?: ResourceProxy;
+};
 export type RenderResponse = {
     rendered: false;
     errors: {
@@ -488,5 +495,5 @@ export type RenderResponse = {
     operations: Operation[];
     warnings?: string[];
 };
-export declare const render: (input: RenderInput) => RenderResponse;
+export declare const render: (input: RenderInput, options?: RenderOptions) => RenderResponse;
 export declare const renderTool: import('.').ToolDef;

package/dist/src/modules/mcp/tools/shared/tool.d.ts

@@ -1,5 +1,6 @@
 import { z, ZodObject, ZodRawShape } from 'zod';
 import { Space } from '../../helpers';
+import { ResourceProxy } from '../../proxy';
 import { PreviewClient, ScreenshotClient, ScreenshotImage, Env, Persisters } from '../../types';
 import { McpUiToolMeta } from '@modelcontextprotocol/ext-apps';
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
@@ -14,6 +15,10 @@ export interface ToolContext {
     spaceId?: number;
     preview?: PreviewClient;
     screenshot?: ScreenshotClient;
+    /** Where a rendered widget loads its external resources from, when the host wired one (see `mcpAi.proxy`). Only
+     *  plitzi_render uses it: a widget renders inside the host's sandbox, where an undeclared origin cannot be
+     *  reached at all. */
+    proxy?: ResourceProxy;
 }
 /** A capability a tool depends on; the host skips registering a tool whose capability it did not wire (so
  *  plitzi_screenshot simply does not appear when no browser service is configured). */

package/dist/src/modules/mcp/types/appTypes.d.ts

@@ -18,4 +18,9 @@ export interface McpApp {
 export interface McpViewSettings {
     /** May the view paint from tool arguments the host is still streaming? See `mcpAi.renderStreaming`. */
     streaming: boolean;
+    /** Absolute resource endpoint of the server that served the page, when it serves one (see `mcpAi.proxy`). It
+     *  shapes the PAGE rather than the view: its origin is what the resource CSP declares, so the URLs a render
+     *  rewrote to it are allowed to load. The view needs nothing from it — every URL is rewritten server-side,
+     *  where the signing secret is. */
+    proxyEndpoint?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.32.21",
+  "version": "0.32.22",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -30,9 +30,9 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@plitzi/plitzi-sdk": "0.32.21",
-    "@plitzi/sdk-schema": "0.32.21",
-    "@plitzi/sdk-shared": "0.32.21",
+    "@plitzi/plitzi-sdk": "0.32.22",
+    "@plitzi/sdk-schema": "0.32.22",
+    "@plitzi/sdk-shared": "0.32.22",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.1",
     "zod": "^4.4.3"