Enterprise agent platform for building, deploying, and operating AI teammates.
HTML preview security and compatibility
Generated HTML is untrusted. Every in-app preview uses exactly
sandbox="allow-scripts", without same-origin, popup or top-navigation access.
Its document starts with a no-referrer meta policy for subresource requests;
the iframe also declares referrerPolicy="no-referrer".
HTML preprocessing uses parse5's data tree, not a browser DOM that might load
untrusted resources before the preview policy is installed.
This deliberately gives previews an opaque origin. Browser storage APIs can
throw SecurityError, and ES modules, fonts and JavaScript fetches require
their resource server to accept a null origin. Classic scripts and images
have different browser loading rules. Not all generated web applications will
work unchanged. The jsdom tests check markup contracts, not browser sandbox
enforcement or full application compatibility.
Do not restore allow-same-origin or add wildcard CORS to private file APIs to
work around these restrictions. Untrusted scripts can still make network
requests: the referrer policy is not an egress control or a replacement for CSP.
Optional separate runner: configuration and deployment boundary
The frontend supports a separately operated runner; this repository does not
ship that service or provision its DNS, TLS, headers or network isolation.
Without it, previews use the original scripts-only opaque srcdoc fallback.
This client-side integration alone does not close CASA #14.
The XAgent SaaS runner is provided by domain-config #36. Deploy and verify it before enabling this setting; its revised stage/dev names below fit the zone's wildcard certificate namespace. The previous two-label names are not generated by that deployment.
Build with NEXT_PUBLIC_XAGENT_HTML_PREVIEW_ORIGIN=https://preview.example.com.
The official PyPI wheel's frontend is built without this setting, so setting it
only at runtime widens the packaged CSP but does not enable the runner. Wheel
deployments need a custom frontend build (or a custom frontend_dist) with the
same value baked in.
Only the origin is used: /some/path?query#fragment becomes /render on that
origin. HTTPS is required except for HTTP on localhost, 127.0.0.1, or
[::1] for local development. Invalid values fall back to srcdoc.
auto maps these exact app hostnames (not arbitrary subdomains):
| App host | Runner origin |
|---|---|
| cloud.xagent.co | https://preview.xagent.co |
| stage.cloud.xagent.co | https://preview-stage.xagent.co |
| dev.cloud.xagent.co | https://preview-dev.xagent.co |
Unknown app hosts fall back. Auto mode permits only these three runner origins
in CSP. Explicit mode permits only the validated configured origin, not a
wildcard https: frame source. Both widget and ordinary page policies retain
their other restrictions.
The Next server bakes this setting into its page CSP at build time. When
FastAPI serves a static export, set the same variable at backend runtime
so its page CSP also allows that origin in frame-src. Any reverse proxy or
CDN adding another CSP must permit the same origin: multiple policies
intersect. The preview transport does not add cookies, bearer tokens, launch
tickets or parent storage. Generated widget/share HTML never contains the
guest token (?token= was retired): the public access policy signs each
absolute managed-file asset URL with a short-lived, file-bound ?ticket=
minted over the guest's Authorization header (POST /api/files/public/tickets/{file_id}). Tickets live
XAGENT_FILE_STREAM_TICKET_TTL_SECONDS (default 600) and are signed once when
the preview is prepared; assets the document requests only after that (lazy
images, in-document media, in-preview navigations) fail until the preview is
reopened. Re-signing on a timer would re-deliver the document and reset its
scroll, form and playback state each period, so it is intentionally not done. File API asset URLs are made absolute before
delivery so an empty API URL still targets the app origin, not the runner host.
Docker frontend builds accept the same named build argument. Official
publish/nightly workflows pass it from a repository variable, unset by
default. Changing a container runtime environment cannot change an existing
NEXT_PUBLIC_* browser bundle; rebuild it. Do not enable auto until all
applicable runner endpoints are deployed and verified.
Runner protocol v1
- Serve a trusted bootstrap page at
GET /render. Do not redirect to the main application, require app cookies, or serve previously uploaded HTML. - Install a one-shot
messagelistener, then send{type: "xagent-html-preview-ready", version: 1}towindow.parent, with the exact configured app origin astargetOrigin. - Accept only
event.source === window.parentand the exact configured appevent.origin, an object withtype === "xagent-html-preview-render",version === 1, and a stringhtml. Remove the listener before rendering that string. Do not forward it elsewhere or process later render messages. - Render the supplied complete document in this sandboxed browsing context,
for example using
document.open(),document.write(html), anddocument.close()after validating the message. The context remains opaque because the embedding iframe grants onlyallow-scripts.
Example bootstrap logic (serve as part of the trusted runner page):
const expectedParent = "https://cloud.xagent.co"; // configure per environment
function render(event) {
const data = event.data;
if (event.source !== window.parent || event.origin !== expectedParent
|| !data || typeof data !== "object"
|| data.type !== "xagent-html-preview-render" || data.version !== 1
|| typeof data.html !== "string") return;
window.removeEventListener("message", render);
document.open();
document.write(data.html);
document.close();
}
window.addEventListener("message", render);
window.parent.postMessage({type: "xagent-html-preview-ready", version: 1}, expectedParent);
The app checks the exact iframe window, opaque event.origin === "null",
message type and protocol version,
and sends HTML only once. Opaque sandbox origins require "*" for this
postMessage; "null" alone is not trusted, so exact source-window validation
is mandatory. A changed document gets a new iframe browsing context, avoiding
the old document's persistent WindowProxy. Empty content does not navigate.
No valid ready within 8 seconds replaces that context with the original
scripts-only srcdoc fallback. Browsers do not reliably emit iframe error
events for DNS, TLS, HTTP, CSP or X-Frame-Options failures, so this timeout is
the fallback signal. Once ready is accepted there is no trusted render
acknowledgement; a runner that fails after ready can remain blank. This is a
compatibility fallback, not proof that separate-origin isolation is active.
When the XAgent page is itself embedded (for example a customer-site widget),
the runner is skipped and srcdoc is used: CSP frame-ancestors validates the
entire ancestor chain, while the managed runner intentionally allows only the
matching XAgent app origin.
The operator must configure a runner response CSP (including HTTP
sandbox allow-scripts and an exact app frame-ancestors allowlist),
no-referrer, nosniff, no-store, no sensitive cookies/storage, and an appropriate
network policy. The SaaS runner intentionally retains generated-script/resource
compatibility rather than claiming a strict resource CSP. Custom runners must
permit their bootstrap and required assets without granting same-origin access.
Do not send X-Frame-Options: DENY or SAMEORIGIN on a cross-origin runner.
Do not weaken private APIs' CORS to make preview fetches work. After deployment,
verify in a real browser: response CSP on both serving modes, ready/render,
relative images/CSS/scripts, file switching, and offline/blocked/version-mismatch
fallback. Unit tests validate contracts, not browser-enforced isolation or a
deployed service's correctness.
Static quoted src and href values are rewritten before delivery. Generated
code that constructs relative URLs at runtime, and other URL-bearing syntaxes
such as srcset, poster, or CSS url(), must use absolute URLs or be inlined;
they otherwise resolve against the preview origin and can fail.