Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

8.2 KB
Raw Blame

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

  1. Serve a trusted bootstrap page at GET /render. Do not redirect to the main application, require app cookies, or serve previously uploaded HTML.
  2. Install a one-shot message listener, then send {type: "xagent-html-preview-ready", version: 1} to window.parent, with the exact configured app origin as targetOrigin.
  3. Accept only event.source === window.parent and the exact configured app event.origin, an object with type === "xagent-html-preview-render", version === 1, and a string html. Remove the listener before rendering that string. Do not forward it elsewhere or process later render messages.
  4. Render the supplied complete document in this sandboxed browsing context, for example using document.open(), document.write(html), and document.close() after validating the message. The context remains opaque because the embedding iframe grants only allow-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.