fix(player): fail closed on runtime data delivery

Author: vanceingalls

packages/player/README.md

@@ -134,7 +134,11 @@ player.iframeElement; // HTMLIFrameElement (read-only)
 
 ## Advanced: iframe access
 
-The composition runs inside a sandboxed `<iframe>` in the player's Shadow DOM. For most use cases you don't need direct access — the JavaScript API above is enough. But if you're building an editor, recorder, or custom timeline that needs to inspect the composition's DOM or read its `__player` / `__timelines` runtime objects, use the `iframeElement` getter:
+The composition runs inside a sandboxed `<iframe>` in the player's Shadow DOM. The default sandbox includes `allow-same-origin` for editor, recorder, and custom-timeline integrations that inspect the composition DOM. That is a trusted-content mode, not an isolation boundary: same-origin composition code can reach the embedding page.
+
+For read-only or message-bridge integrations, set `sandbox-origin="opaque"`. This removes `allow-same-origin` while retaining scripts, and prevents the composition from reading unrelated parent DOM. Direct `contentDocument`, `__player`, and `__timelines` access is intentionally unavailable in that mode.
+
+If you are building a trusted editor integration that needs direct access, use the `iframeElement` getter:
 
 ```js
 const player = document.querySelector("hyperframes-player");

packages/player/src/hyperframes-player.test.ts

@@ -2497,7 +2497,54 @@ describe("HyperframesPlayer retained runtime data", () => {
     expect(player.iframeElement.referrerPolicy).toBe("no-referrer");
   });
 
+  it("supports an opaque-origin sandbox for hosts that do not need direct iframe DOM access", () => {
+    player.setAttribute("sandbox-origin", "opaque");
+    expect(player.iframeElement.sandbox.contains("allow-scripts")).toBe(true);
+    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(false);
+    expect(player.iframeElement.sandbox.contains("allow-top-navigation")).toBe(false);
+
+    player.removeAttribute("sandbox-origin");
+    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(true);
+  });
+
   it("rejects payloads that structuredClone cannot transfer", () => {
     expect(() => player.setRuntimeData("captions", () => undefined)).toThrow();
   });
+
+  it("fails closed when structuredClone is unavailable", () => {
+    const original = globalThis.structuredClone;
+    Object.defineProperty(globalThis, "structuredClone", {
+      configurable: true,
+      value: undefined,
+    });
+    try {
+      expect(() => player.setRuntimeData("captions", { words: ["unsafe"] })).toThrow(
+        /requires structuredClone support/,
+      );
+      player._onMessage(readyMessage());
+      expect(runtimeCalls()).toHaveLength(0);
+    } finally {
+      Object.defineProperty(globalThis, "structuredClone", {
+        configurable: true,
+        value: original,
+      });
+    }
+  });
+
+  it("reports postMessage delivery failures instead of silently dropping runtime data", () => {
+    player._onMessage(readyMessage());
+    postSpy.mockImplementation(() => {
+      throw new DOMException("payload cannot be cloned", "DataCloneError");
+    });
+    const errors: CustomEvent[] = [];
+    player.addEventListener("runtimedataerror", (event) => errors.push(event as CustomEvent));
+
+    player.setRuntimeData("captions", { words: ["value"] });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]?.detail).toMatchObject({
+      channel: "captions",
+      message: "payload cannot be cloned",
+    });
+  });
 });

packages/player/src/hyperframes-player.ts

@@ -29,6 +29,7 @@ import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
 // production browsers.
 const MIN_PLAYBACK_RATE = 0.1;
 const MAX_PLAYBACK_RATE = 5;
+const SANDBOX_ORIGIN_ATTR = "sandbox-origin";
 
 export type ColorGradingTarget =
   | string
@@ -70,6 +71,7 @@ class HyperframesPlayer extends HTMLElement {
       "poster",
       "playback-rate",
       "audio-src",
+      SANDBOX_ORIGIN_ATTR,
       SHADER_CAPTURE_SCALE_ATTR,
       SHADER_LOADING_ATTR,
     ];
@@ -163,6 +165,7 @@ class HyperframesPlayer extends HTMLElement {
   }
 
   connectedCallback() {
+    this._applySandboxOriginPolicy();
     this.resizeObserver.observe(this);
     window.addEventListener("message", this._onMessage);
     this.iframe.addEventListener("load", this._onIframeLoad);
@@ -218,6 +221,9 @@ class HyperframesPlayer extends HTMLElement {
         if (val !== null) this.iframe.srcdoc = prepareSrcdocForElement(this, val);
         else this.iframe.removeAttribute("srcdoc");
         break;
+      case SANDBOX_ORIGIN_ATTR:
+        this._applySandboxOriginPolicy();
+        break;
       // Reject NaN/zero/negative dimensions the same way the composition
       // probe does (a typo like width="abc" or width="0" would otherwise
       // reach scaleIframeToFit as scale(NaN) or a division by zero and
@@ -275,6 +281,15 @@ class HyperframesPlayer extends HTMLElement {
     }
   }
 
+  private _applySandboxOriginPolicy(): void {
+    const policy = this.getAttribute(SANDBOX_ORIGIN_ATTR);
+    if (policy === "opaque") {
+      this.iframe.sandbox.remove("allow-same-origin");
+      return;
+    }
+    this.iframe.sandbox.add("allow-same-origin");
+  }
+
   /**
    * The inner `<iframe>` rendering the composition. Use this when integrating
    * with tools that need `contentWindow` — `.contentWindow` on the
@@ -395,7 +410,12 @@ class HyperframesPlayer extends HTMLElement {
     if (!/^[a-z][a-z0-9-]{0,63}$/.test(channel)) {
       throw new Error(`Invalid HyperFrames runtime-data channel: ${channel}`);
     }
-    const retained = typeof structuredClone === "function" ? structuredClone(payload) : payload;
+    if (typeof structuredClone !== "function") {
+      throw new Error(
+        "HyperFrames runtime data requires structuredClone support; refusing an unverified payload",
+      );
+    }
+    const retained = structuredClone(payload);
     this._runtimeData.set(channel, retained);
     this._deliverRuntimeData(channel, retained);
   }
@@ -529,7 +549,7 @@ class HyperframesPlayer extends HTMLElement {
     else this.removeAttribute("loop");
   }
 
-  private _sendControl(action: string, extra: Record<string, unknown> = {}) {
+  private _sendControl(action: string, extra: Record<string, unknown> = {}): boolean {
     try {
       this.iframe.contentWindow?.postMessage(
         {
@@ -541,8 +561,19 @@ class HyperframesPlayer extends HTMLElement {
         },
         "*",
       );
-    } catch {
-      /* cross-origin */
+      return true;
+    } catch (error) {
+      if (action === "set-runtime-data" || action === "clear-runtime-data") {
+        this.dispatchEvent(
+          new CustomEvent("runtimedataerror", {
+            detail: {
+              channel: extra["channel"],
+              message: error instanceof Error ? error.message : String(error),
+            },
+          }),
+        );
+      }
+      return false;
     }
   }