Isolation & sandboxing

Keep untrusted code apart

Many web pages run code or show content that their own team did not write. Here are some common examples:

• analytics scripts and ads from other companies
• payment widgets, like a card form from a payment company
• HTML that customers wrote, shown in a preview
• plugins that other people write for your app
• code that learners type into a playground, like the editor on this site

We call this code untrusted: you did not write it, so you can't be sure what it will do. It may have a bug, or it may try to do harm. So don't ask "do we trust it?" Ask "what stops it from reaching the rest of the page?"

A sandbox is one way to build that separate space. The word comes from a children's sandbox: play happens inside it, and the sand stays inside it.

This lesson builds on windows and frames, messaging and structured cloning, eval, and XSS. You'll learn these tools, in this order:

• origins, the browser's basic rule for what pages may read (a short review of the CORS lesson)
• the sandbox attribute on an iframe
• safe checks for messages sent with postMessage
• the COOP and COEP headers, which turn on cross-origin isolation
• workers, ShadowRealm, and Node's vm module, and what each one can and can't keep apart

Origins and boundaries

The browser already has one basic rule that keeps pages apart. It is called the same-origin policy. An origin is made of three parts of a URL:

• the scheme, like https
• the host, like shop.example
• the port, like 8443 (for https, the port is 443 when the URL doesn't show one)

Two pages are same-origin only when all three parts match. The path, like /cart, is not part of the origin.

const page = new URL("https://shop.example/cart");
const help = new URL("https://shop.example/help");
const otherPort = new URL("https://shop.example:8443/cart");
console.log(page.origin === help.origin);
console.log(page.origin === otherPort.origin);

Line 1 makes a URL for the cart page. Line 2 keeps the same scheme, host, and port, but changes the path to /help. So line 4 prints true. Line 3 changes the port to 8443. So line 5 prints false.

What does the rule allow? Pages from the same origin can usually read each other's page content (the DOM) and storage, like localStorage. Cookies have their own extra rules: their domain and path, and the HttpOnly flag, which hides a cookie from JavaScript. Pages from different origins usually can't read each other's DOM or storage.

The CORS lesson was about reading data over the network. This lesson asks a different question: what can a frame or a script do once it is already on your page?

Code from other companies still runs in your user's browser. That is why it needs a boundary. Here is what each kind of code should not be able to do:

• A map widget should not read your CSRF token, the secret your forms send to prove a request is real.
• A preview of customer HTML should not reach your admin pages.
• A plugin should not freeze the page.
• A code editor, like the one on this site, should run examples without giving them the completefrontend.com origin.

An iframe shows one web page inside another. Add the sandbox attribute to it, with no value, and the browser takes powers away from the framed page. A bare sandbox like that blocks all of these:

• running scripts
• sending forms
• opening popups
• sending the whole browser tab to a new address (called top navigation)
• pointer lock, downloads, and dialogs like alert()
• the page's normal origin

That last one matters most. Instead of its real origin, the framed page gets an opaque origin: a special origin that matches no other origin. Message events show it as the text "null".

Then you give back only the powers the framed page needs. Each power has its own word, called a token. You list the tokens in the sandbox attribute. Common tokens are allow-scripts, allow-forms, allow-popups, and allow-same-origin.

const tokens = ["allow-scripts"];
console.log(tokens.includes("allow-scripts"));
console.log(tokens.includes("allow-forms"));

Line 1 lists one token, allow-scripts. Line 2 asks if that token is in the list, and prints true. Line 3 asks about allow-forms, and prints false. So the frame can run JavaScript, but it still can't send forms. Add allow-forms only if the frame really needs to send a form.

The allow-same-origin token needs care. It lets the framed page keep its own real origin instead of the opaque one. It does not give a page from another site your origin.

The danger comes when the framed page is from your own origin. Then allow-scripts plus allow-same-origin lets its scripts reach the iframe element in your page. They can remove the sandbox attribute and reload without it. To stay safe, do one of these:

• serve untrusted content from a different origin, or
• leave out one of the two tokens.

Popups and top navigation also need their own tokens. A popup opened from a sandboxed frame gets the same sandbox rules. The allow-popups-to-escape-sandbox token lets a popup open without them.

In the step-through below, pick a set of tokens. Then step through and watch which powers each token gives back.

1const tokens = ["allow-scripts"];Run2 3function describeSandbox(tokens, sameOriginContent) {4  const has = (name) => tokens.includes(name);5  return {6    scripts: has("allow-scripts") ? "allowed" : "blocked",7    forms: has("allow-forms") ? "allowed" : "blocked",8    popups: has("allow-popups") ? "allowed" : "blocked",9    origin: has("allow-same-origin") ? "real origin" : "opaque origin",10    topNavigation: has("allow-top-navigation") ? "allowed" : "blocked",11    canRemoveSandbox: sameOriginContent &&12      has("allow-scripts") && has("allow-same-origin"),13  };14}15 16console.log(describeSandbox(tokens, true));

The next snippet makes a real sandboxed iframe inside the lesson editor's page. It allows scripts, so the framed page can report back. It never allows allow-same-origin. Here is what happens, line by line:

• Lines 1 to 3 make the iframe, give it only allow-scripts, and put a small page inside it with srcdoc.
• Line 5 tries to read the parent page. The browser stops it with a SecurityError.
• Lines 6 to 8 try to set a cookie. That is blocked too, because an opaque origin has no cookies.
• Line 9 sends a report to the parent page with postMessage.
• Line 13 ignores any message that doesn't come from this frame.
• Lines 15 to 18 print the report. Both origins print as null.

1const frame = document.createElement("iframe");2frame.sandbox = "allow-scripts";3frame.srcdoc = `<!doctype html><script>4let parentDom = "read";5try { parent.document.body; } catch (error) { parentDom = "blocked:" + error.name; }6let cookie = "";7try { document.cookie = "lesson=1"; cookie = document.cookie || "(empty)"; }8catch (error) { cookie = "blocked:" + error.name; }9parent.postMessage({ lesson: "sandbox-probe", origin: self.origin, parentDom, cookie }, "*");10</script><p>Sandboxed child</p>`;11 12window.addEventListener("message", (event) => {13  if (event.source !== frame.contentWindow) return;14  if (!event.data || event.data.lesson !== "sandbox-probe") return;15  console.log("event.origin:", event.origin);16  console.log("child self.origin:", event.data.origin);17  console.log("parent DOM:", event.data.parentDom);18  console.log("cookie:", event.data.cookie);19});20 21document.querySelector("#sandbox-output").append(frame);

In the playground, turn tokens on and off. A real iframe reports what it can do each time.

1const tokens = ["allow-scripts"];2 3function describeSandbox(tokens, sameOriginContent) {4  const has = (name) => tokens.includes(name);5  return {6    scripts: has("allow-scripts") ? "allowed" : "blocked",7    forms: has("allow-forms") ? "allowed" : "blocked",8    popups: has("allow-popups") ? "allowed" : "blocked",9    origin: has("allow-same-origin") ? "real origin" : "opaque origin",10    topNavigation: has("allow-top-navigation") ? "allowed" : "blocked",11    canRemoveSandbox: sameOriginContent &&12      has("allow-scripts") && has("allow-same-origin"),13  };14}15 16console.log(describeSandbox(tokens, true));

The srcdoc attribute is handy for previews. It holds the HTML of the framed page right in the attribute, so you don't need a separate URL. A sandboxed srcdoc frame without allow-same-origin gets an opaque origin. Its messages show the origin as "null". Many frames can share that same "null", so you must also check which frame sent a message.

A server can apply the same rules to a whole page with the CSP sandbox header. For a frame you make in JavaScript, the sandbox attribute is the usual tool.

How this site's editor uses a sandbox

The CompleteFrontend editor runs learner code in a sandboxed preview iframe. Two files set it up: src/components/editor/EditorApp.tsx and InlineEditor.tsx. Both use the same list of tokens. It allows scripts, forms, popups, pointer lock, downloads, and dialogs. It does not allow allow-same-origin.

1const SANDBOX =2  "allow-scripts allow-modals allow-forms allow-popups " +3  "allow-popups-to-escape-sandbox allow-pointer-lock allow-downloads";4 5// CompleteFrontend deliberately does not include allow-same-origin.

A comment in public/editor-runtime.js explains why. The preview frame has an opaque origin, so learner code can't reach this site's storage or sign-in. That file then adds back safe stand-ins for what the frame lost:

• localStorage, sessionStorage, and cookies that live only in memory
• fetch() for files in your project
• workers made from files in your project
• console output, sent to the editor with postMessage

1/*2 * The frame has an opaque origin (no allow-same-origin), so learner code can't reach the3 * site's storage or sign-in. This file fills in what that origin lacks: localStorage,4 * sessionStorage, and cookies kept in memory, fetch() of project files, workers made from5 * project files, and links between project pages.6 */

An isolated frame still needs to talk to your page. It uses postMessage, which sends a copy of the data. The copy is made with the structured clone algorithm, the browser's way of deep-copying data. So the receiver gets plain data, never the sender's live object.

When you send, the second argument is the targetOrigin. It names the origin that is allowed to receive the message. Use a real origin, like "https://pay.example", for anything private. Use "*", which means "any origin", only when the receiver has an opaque origin you can't name. A sandboxed srcdoc frame is one example. Never send secrets with "*".

When you receive, check three things before you use the message:

1. Origin: is event.origin on your list of allowed origins?
2. Source: is event.source the exact frame window you saved when you made the frame?
3. Shape: does event.data have the type and fields you expect?

const paymentFrame = {};
const ready = { origin: "https://pay.example", source: paymentFrame, data: { type: "payment:ready", checkoutId: "co_42" } };
const lookalike = { ...ready, source: {} };
const accepts = (event) => event.origin === "https://pay.example" && event.source === paymentFrame &&
  event.data && !Array.isArray(event.data) && event.data.type === "payment:ready" &&
  typeof event.data.checkoutId === "string";
const cases = [ready, lookalike, { ...ready, data: [] }];
console.log(cases.map((event) => accepts(event) ? "accept" : "reject").join(", "));

This code uses plain objects that look like message events, so you can run it anywhere. Line by line:

• Line 1 stands in for the payment frame you made.
• Line 2 is a good message from that frame.
• Line 3 copies it, but changes the source to a different frame. Same origin, wrong frame.
• Lines 4 to 6 check the exact origin and the exact frame. Then they check that the data is an object (not an array), its type is "payment:ready", and its checkout ID is a string.
• Line 7 adds a third message whose data is an empty array.
• Line 8 prints accept, reject, reject.

The second message has the right origin, but it is still rejected. A matching origin alone is not enough.

Two more details about origins:

• When you send, targetOrigin also protects you if the frame has moved to another site. The browser won't deliver the message there.
• When you receive, event.origin is the sender's origin at the moment it sent the message. It does not change if that window moves later.

In the step-through below, pick an incoming message. Then watch which check stops it.

1const allowedOrigins = new Set(["https://pay.example"]);Run2const trustedSource = globalThis.paymentFrame ?? {};3const incomingEvent = globalThis.incomingEvent ?? { origin: "https://pay.example", source: trustedSource, data: { type: "payment:ready", checkoutId: "co_42" } };4function isPaymentReady(data) {5  return data && data.type === "payment:ready" &&6    typeof data.checkoutId === "string";7}8 9function onMessage(event) {10  if (!allowedOrigins.has(event.origin)) return "reject: origin";11  if (event.source !== trustedSource) return "reject: source";12  if (!isPaymentReady(event.data)) return "reject: shape";13  return "accept: " + event.data.checkoutId;14}15 16console.log(onMessage(incomingEvent));

For a longer private conversation, use a MessageChannel. It makes two connected ends, called ports. You keep one port and send the other to the frame or worker, inside your first postMessage. After that, the two ports talk only to each other, like a private phone line. Other frames can't send to it.

1const channel = new MessageChannel();2channel.port1.onmessage = (event) => {3  console.log("private reply", event.data.type);4};5 6trustedWindow.postMessage(7  { lesson: "isolation", type: "connect-port" },8  "*",9  [channel.port2],10);11 12channel.port1.postMessage({ type: "private:hello" });

Cross-origin isolation

In 2018, researchers found a kind of attack called Spectre. It measures tiny differences in how long the processor takes to do things. From those timings, a page can sometimes guess data from memory it should never see, even data from another site.

Browsers responded by turning off SharedArrayBuffer (memory that several threads can share) and some very precise timing and memory tools. A page gets them back only if it asks to be kept strictly apart from other sites. This is called cross-origin isolation. Your code can check it with self.crossOriginIsolated, which is true or false.

The table below lists the pieces. Read each row as: this piece, what it looks like, and what it does.

Three of these pieces are headers, but they go on different responses:

• Cross-Origin-Opener-Policy (COOP) is a header on your page. It cuts the link between your page and windows from other sites that opened it, or that it opens.
• Cross-Origin-Embedder-Policy (COEP) is also a header on your page. It says that every image, script, or frame your page loads must agree to be loaded.
• Cross-Origin-Resource-Policy (CORP) is a header on each of those loaded files. It is how a file agrees. A file can also agree through CORS.

One more rule can still block the powerful tools: the cross-origin-isolated setting of Permissions Policy. So always check self.crossOriginIsolated in code. Don't assume the headers worked.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

1console.log(self.crossOriginIsolated);2console.log(typeof SharedArrayBuffer);3console.log(typeof performance.measureUserAgentSpecificMemory);

Line 1 prints whether the page is cross-origin isolated. Line 2 prints the type of SharedArrayBuffer. Line 3 prints the type of a memory tool, performance.measureUserAgentSpecificMemory. On a normal page, lines 2 and 3 print undefined.

const useSharedMemory =
  self.crossOriginIsolated && typeof SharedArrayBuffer === "function";
const buffer = useSharedMemory ? new SharedArrayBuffer(16) : new ArrayBuffer(16);
console.log(buffer.constructor.name);

Lines 1 and 2 check two things: is the page isolated, and does SharedArrayBuffer exist? Line 3 makes shared memory only when both are true. Otherwise it makes an ordinary ArrayBuffer. Line 4 prints ArrayBuffer in the lesson editor, because its preview is not cross-origin isolated.

We checked this in Chrome 154 while writing this lesson. On a normal data: page, self.crossOriginIsolated was false, and both SharedArrayBuffer and performance.measureUserAgentSpecificMemory were undefined. On a page sent with COOP: same-origin and COEP: require-corp, all three were available.

Workers, ShadowRealm, and Node vm

A Web Worker runs a script in the background, on its own thread. It has its own set of global variables, and it can't touch the DOM. That makes it a good place for work that only needs data, like these:

• parsing a big file
• processing an image
• plugin code that turns data into other data

But a worker alone does not keep harmful code safe. It can still keep the processor busy, use lots of memory, make network requests that its origin allows, and send bad messages. Your page must still check what comes back.

1// main page2const worker = new Worker("plugin-worker.js", { type: "module" });3worker.postMessage({ type: "render", text: userText });4worker.onmessage = (event) => {5  preview.textContent = event.data.text;6};7 8// plugin-worker.js9self.onmessage = (event) => {10  // There is no document or DOM in a worker global scope.11  self.postMessage({ text: String(event.data.text).toUpperCase() });12};

Line 2 starts the worker. Line 3 sends it some text. Line 4 sets up a function for the worker's reply, and line 5 shows the reply as plain text. Inside the worker, line 9 receives the message. Line 10 is a reminder that there is no document here. Line 11 sends back the text in capital letters.

ShadowRealm is a proposal, an idea for a new JavaScript feature that is not finished yet. TC39, the group that designs JavaScript, is working on it. A realm is a complete set of JavaScript's built-in objects, like Array and Object, plus its own global object. A ShadowRealm would give you a fresh one. The proposed tools are:

• new ShadowRealm() to make a new realm
• realm.evaluate(sourceText) to run a string of code inside it
• realm.importValue(specifier, bindingName) to load one exported value from a module inside it

The proposal is at Stage 2.7, which means it is close to done but not final. In Chrome 154, typeof ShadowRealm is "undefined". So the example below checks first, and the lesson does not run it.

1if (typeof ShadowRealm === "function") {2  const realm = new ShadowRealm();3  const twice = await realm.importValue("./plugin.js", "twice");4  console.log(twice(21));5  console.log(realm.evaluate("Array.prototype === globalThis.Array.prototype"));6} else {7  console.log("ShadowRealm is not available in this browser yet");8}

Line 1 checks that ShadowRealm exists. Line 2 makes a realm. Line 3 loads a function called twice from a module inside it, and line 4 calls it. Line 5 runs a string of code inside the realm with evaluate. Inside the realm, Array.prototype and globalThis.Array.prototype are the same object, so it would print true. In today's Chrome, only line 7 runs.

Node's vm module has a similar trap in its name. It runs code in a separate set of global variables. The official Node.js documentation says: "The node:vm module is not a security mechanism. Do not use it to run untrusted code." When code may be harmful, use a stronger boundary:

• a separate operating-system process
• a container
• a separate service on another machine
• a carefully built system that hands code only the tools it needs

1import vm from "node:vm";2 3const context = vm.createContext({ answer: 41 });4vm.runInContext("answer += 1", context);5console.log(context.answer);6 7// Node.js docs: the node:vm module is not a security mechanism.8// Do not use it to run untrusted code.

Line 3 makes a context, a separate set of global variables, with answer set to 41. Line 4 runs code inside it that adds 1. Line 5 prints 42. Lines 7 and 8 repeat the warning from the Node docs.

SES (Secure ECMAScript), also called Hardened JavaScript, takes another path. It works in two steps:

1. lockdown() freezes JavaScript's built-in objects, so code can't change them.
2. A Compartment runs code with only the tools you pass in. Nothing else is reachable.

This can be a good base for a plugin system. But your whole app must be built around it from the start. You can't add it in one line to a page that already trusts every script.

1import "ses";2lockdown();3 4const compartment = new Compartment({ console });5compartment.evaluate("console.log(Array.prototype.map.call([1, 2], x => x * 2))");

Line 1 loads SES. Line 2 freezes the built-in objects. Line 4 makes a compartment and passes in only console. Line 5 runs code inside it, which prints the array [2, 4].

The table below compares all five tools. Read each row as: this tool, what it keeps apart, when to use it, and what it does not do.

Choosing a boundary in real apps

Pick the tool by what the code needs:

• It needs to show something on screen, like ads, comments written in HTML, previews, payment widgets, or code playgrounds: use a sandboxed iframe.
• It only needs to crunch data, with no DOM: use a worker.
• It needs SharedArrayBuffer or precise memory measurement: turn on cross-origin isolation, on that page only.
• It may be actively harmful: run it in a separate operating-system process or container, with limits on processor time and memory. Node's vm alone is not enough.

Keep the defenses from the XSS lesson too. A sandbox is an extra layer of defense. It does not clean dangerous HTML for you.

Here is what that looks like for four common jobs:

• A code playground: use sandbox="allow-scripts", and send results back with messages. Don't give the frame your origin.
• A payment widget: load it from the payment company's origin. Send to that exact targetOrigin, and check every message against a strict list of allowed shapes.
• Customer HTML: clean it first. Then preview it in a sandbox that doesn't share your origin.
• Plugin data work: start with a worker and a small set of allowed commands. Move to a separate process if the risk is higher.

Common mix-ups

Practice exercises

const tokens = ["allow-scripts"];
const origin = tokens.includes("allow-same-origin") ? "real origin" : "null";
console.log(origin);

const trustedOrigin = "https://pay.example";
const trustedSource = "frame-a";
const event = { origin: "https://pay.example", source: "frame-b", data: { type: "payment:ready", checkoutId: "co_42" } };
const shapeOK = event.data.type === "payment:ready" && typeof event.data.checkoutId === "string";
const ok = event.origin === trustedOrigin && event.source === trustedSource && shapeOK;
console.log(ok ? "accept" : "reject");

const headers = ["Cross-Origin-Opener-Policy", "Cross-Origin-Embedder-Policy"];
console.log(headers.join(" + "));

const tokens = ["allow-scripts", "allow-same-origin"];
console.log(tokens.includes("allow-scripts") && tokens.includes("allow-same-origin"));

Check your understanding

Key takeaways

• Start a sandboxed iframe with every power blocked. Then add back only the tokens it really needs.
• Never use allow-scripts plus allow-same-origin to protect your page from content from your own origin.
• Send with a real targetOrigin when you can. When you receive, check the origin, the source, and the shape.
• Cross-origin isolation is turned on with headers, for pages that need powerful memory tools. It is not a sandbox for widgets.
• Workers, ShadowRealm, Node vm, and SES each keep a different thing apart. Choose by what could go wrong.

Isolation lets untrusted code do useful work through a small, checked channel, instead of giving it your whole page.

Next in this module, Web Crypto shows the browser's built-in tools for secure randomness, hashing, and encryption, so you never write your own. The habit is the same: pick the browser tool that gives you the protection you need.