Sandbox
Description
An iframe that renders untrusted HTML or external URLs in a locked-down context
Sandbox wraps an <iframe> and configures it so that content it renders cannot access the host page, its cookies, or browser storage. By default, the frame is loaded via srcdoc with sandbox="allow-scripts allow-forms" — allow-same-origin is intentionally omitted, which means the sandboxed document runs under an opaque origin and has no access to the host origin.
A strict Content-Security-Policy meta tag (default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:;) is injected as the first element in the document head so that network exfiltration is blocked even if the sandbox flags are relaxed. Both the CSP and the sandbox attribute string are fully configurable.
A small bootstrap script is injected into the document alongside the CSP tag. It sets up a MessageChannel-based communication channel between the host page and the frame. Uncaught errors, unhandled promise rejections, and CSP violations raised inside the frame are captured by the bootstrap and posted back to the host where they surface through the OnError callback. Arbitrary messages can be exchanged in both directions via OnMessage / PostMessage.
The frame height can optionally track its content: when FitHeightToContent is enabled, the bootstrap script posts height measurements (on load and via ResizeObserver) which the component uses to resize the iframe.
Use UI.Sandbox(html) for inline HTML content and UI.SandboxUrl(url) for external URLs. CSP injection and bootstrap messaging only apply to srcdoc content; cross-origin src documents are not modified.
AllowSameOrigin weakens isolation
Setting .AllowSameOrigin() lets the framed document share the host origin, which allows the host to read contentDocument and contentWindow. Only use it with content you trust, and not in combination with untrusted user-supplied HTML.
API reference
public sealed class Sandbox : ComponentBase<Sandbox, HTMLIFrameElement>, ISpecialCaseStylingA locked-down <iframe> for rendering untrusted HTML / apps. By default the frame is fully sandboxed: the content is loaded through srcdoc with sandbox="allow-scripts allow-forms" (no allow-same-origin, so the document runs in an opaque origin and cannot touch the host page, cookies or storage), and a strict Content-Security-Policy meta tag is injected as the very first thing in the document so the sandboxed code cannot exfiltrate data over the network. A small bootstrap script is injected into the document that wires up a MessageChannel based post-message flow: uncaught errors, unhandled promise rejections and CSP violations are captured inside the frame and posted back to the host where they can be surfaced through OnError. The same channel is used for arbitrary host <-> sandbox messaging via OnMessage / PostMessage.
- Namespace
- Tesserae
- Inheritance
- ComponentBase<Sandbox, HTMLIFrameElement> → Sandbox
- Implements
- ISpecialCaseStyling
Constructors
| Name | Description |
|---|---|
| Sandbox | Creates a new fully-sandboxed frame, optionally with initial HTML content. |
Properties
| Name | Description |
|---|---|
| StylingContainer | The element that receives sizing styles (the iframe itself). |
| PropagateToStackItemParent | Styling propagates up to the stack item parent. |
| IFrameElement | The underlying iframe element. Only safe to reach into when AllowSameOrigin is set. |
public HTMLElement StylingContainerThe element that receives sizing styles (the iframe itself).
public bool PropagateToStackItemParentStyling propagates up to the stack item parent.
Methods
| Name | Description |
|---|---|
| FromHtml | Sets the HTML document rendered inside the sandbox (loaded via srcdoc). |
| FromUrl | Loads an external URL into the frame (via src). CSP / bootstrap injection do not apply to cross-origin documents. |
| AllowScripts | Allows the sandboxed content to run scripts (on by default). |
| AllowForms | Allows the sandboxed content to submit forms (on by default). |
| AllowPopups | Allows popups (e.g. target="_blank", window.open) to escape the sandbox. |
| AllowModals | Allows the content to open modal dialogs (alert, confirm, prompt). |
| AllowDownloads | Allows downloads initiated from within the frame. |
| AllowSameOrigin | Lets the framed document share the host origin. This weakens the sandbox - it is only needed when the host has to reach into contentDocument / contentWindow (for example to hook events or measure layout). Do not combine with untrusted content. |
| AllowToken | Adds a raw sandbox token (e.g. "allow-pointer-lock") on top of the configured flags. |
| SandboxAttribute | Replaces the computed sandbox value with an explicit one. |
| Unsandboxed | Removes the sandbox attribute entirely - the frame is no longer sandboxed. Use with extreme care. |
| ContentSecurityPolicy | Overrides the injected Content-Security-Policy (only applied to srcdoc HTML content). |
| NoContentSecurityPolicy | Disables injecting a Content-Security-Policy meta tag into the document. |
| FitHeightToContent | Grows the frame to match its content height (driven by height messages from the bootstrap script). |
| Scrolling | Enables or disables scrolling within the frame. |
| OnLoaded | Invoked every time the frame finishes loading, with the underlying iframe element. This is the place to hook into the document - but reading contentDocument requires AllowSameOrigin. |
| OnError | Invoked when the sandboxed content reports an uncaught error, an unhandled promise rejection or a CSP violation back over the post-message channel. |
| OnMessage | Invoked with the payload of any custom message the content sends via window.tssSandbox.post(...). |
| PostMessage | Sends a message into the sandboxed document. Received inside the frame as a tss:message window event. |
| Render | Renders the component's root iframe element. |
public Sandbox FromHtml(string html)Sets the HTML document rendered inside the sandbox (loaded via srcdoc).
public Sandbox FromUrl(string url)Loads an external URL into the frame (via src). CSP / bootstrap injection do not apply to cross-origin documents.
public Sandbox AllowScripts(bool allow = true)Allows the sandboxed content to run scripts (on by default).
public Sandbox AllowForms(bool allow = true)Allows the sandboxed content to submit forms (on by default).
public Sandbox AllowPopups(bool allow = true)Allows popups (e.g. target="_blank", window.open) to escape the sandbox.
public Sandbox AllowModals(bool allow = true)Allows the content to open modal dialogs (alert, confirm, prompt).
public Sandbox AllowDownloads(bool allow = true)Allows downloads initiated from within the frame.
public Sandbox AllowSameOrigin(bool allow = true)Lets the framed document share the host origin. This weakens the sandbox - it is only needed when the host has to reach into contentDocument / contentWindow (for example to hook events or measure layout). Do not combine with untrusted content.
public Sandbox AllowToken(string token)Adds a raw sandbox token (e.g. "allow-pointer-lock") on top of the configured flags.
public Sandbox SandboxAttribute(string value)Replaces the computed sandbox value with an explicit one.
public Sandbox Unsandboxed()Removes the sandbox attribute entirely - the frame is no longer sandboxed. Use with extreme care.
public Sandbox ContentSecurityPolicy(string policy)Overrides the injected Content-Security-Policy (only applied to srcdoc HTML content).
public Sandbox NoContentSecurityPolicy()Disables injecting a Content-Security-Policy meta tag into the document.
public Sandbox FitHeightToContent(bool fit = true)Grows the frame to match its content height (driven by height messages from the bootstrap script).
public Sandbox Scrolling(bool enabled)Enables or disables scrolling within the frame.
public Sandbox OnLoaded(Action<HTMLIFrameElement> onLoaded)Invoked every time the frame finishes loading, with the underlying iframe element. This is the place to hook into the document - but reading contentDocument requires AllowSameOrigin.
public Sandbox OnError(Action<SandboxError> onError)Invoked when the sandboxed content reports an uncaught error, an unhandled promise rejection or a CSP violation back over the post-message channel.
public Sandbox OnMessage(Action<object> onMessage)Invoked with the payload of any custom message the content sends via window.tssSandbox.post(...).
public Sandbox PostMessage(object message)Sends a message into the sandboxed document. Received inside the frame as a tss:message window event.
Fields
| Name | Description |
|---|---|
| DefaultContentSecurityPolicy | The fully-locked default CSP: inline scripts and styles only, images limited to data/blob URIs, no network access. |
public const string DefaultContentSecurityPolicy = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:;"The fully-locked default CSP: inline scripts and styles only, images limited to data/blob URIs, no network access.
public sealed class SandboxErrorAn error, unhandled rejection or CSP violation reported back from a Sandbox's content.
- Namespace
- Tesserae
Properties
| Name | Description |
|---|---|
| Kind | One of error, unhandledrejection or csp. |
| Message | Human-readable error message. |
| Source | The source file the error originated from, when available. |
| Line | Line number, when available. |
| Column | Column number, when available. |
| Stack | JavaScript stack trace, when available. |
| IsContentSecurityPolicyViolation | True for a Content-Security-Policy violation report. |
public string Source { get; }The source file the error originated from, when available.
Methods
| Name | Description |
|---|---|
| ToString | Returns a single-line, human readable description of the error. |