Skip to content

Commit 4233b5c

Browse files
authored
fix(core): contain generated HTML CSS and script contexts (#3800)
* fix(core): escape generator metadata attributes * fix(parsers): retain decoded metadata while assigning ids * fix(parsers): preserve runtime html parser semantics * fix(parsers): canonicalize HTML attribute names for stable IDs * fix(parsers): normalize SVG attribute hashes across HTML parsers * fix(core): escape public resolution attribute values * fix(core): contain generated HTML CSS and script contexts * fix(core): preserve empty captions and document authored code trust
1 parent 41ba820 commit 4233b5c

11 files changed

Lines changed: 705 additions & 266 deletions

File tree

‎docs/packages/core.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,19 @@ const html = generateHyperframesHtml(elements, 6, {
7575
The second argument is the requested duration in seconds. Pass a stable
7676
`compositionId` when output must be reproducible.
7777

78+
Composition generators require trusted authors for code-bearing inputs. `styles` and
79+
`generateHyperframesStyles` preserve authored CSS, which can load external resources.
80+
`animations` may contain `__raw:` values that are emitted as JavaScript;
81+
`includeScripts: true` includes executable timeline code. `serializeGsapAnimations`
82+
also accepts raw `preamble`, `postamble`, and a code-bearing `timelineVar`. Never fill
83+
these inputs with untrusted data. Attribute encoding and closing-tag containment
84+
are not a sandbox; render untrusted compositions in an appropriately isolated
85+
execution environment and never serve them on a privileged origin.
86+
87+
Text content retains the supported inline-formatting sanitizer contract. The clip
88+
parser intentionally flattens inner formatting to text, so parse/generate is not
89+
a lossless replacement for editing the source HTML.
90+
7891
## Read and validate variables
7992

8093
Inside a composition script, `getVariables()` reads declared defaults plus the

‎packages/core/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,21 @@ npm install @hyperframes/core
2222
| **Runtime** | IIFE script injected into the browser — manages seek, media playback, and the `window.__hf` protocol |
2323
| **Frame Adapters** | Pluggable animation drivers (GSAP, Lottie, CSS, or custom) |
2424

25+
## Generated composition trust
26+
27+
Composition generators require trusted authors for code-bearing inputs. `styles` and
28+
`generateHyperframesStyles` preserve authored CSS, which can load external resources.
29+
`animations` may contain `__raw:` values that are emitted as JavaScript;
30+
`includeScripts: true` includes executable timeline code. `serializeGsapAnimations`
31+
also accepts raw `preamble`, `postamble`, and a code-bearing `timelineVar`. Never fill
32+
these inputs with untrusted data. Attribute encoding and closing-tag containment
33+
are not a sandbox; render untrusted compositions in an appropriately isolated
34+
execution environment and never serve them on a privileged origin.
35+
36+
Text content retains the supported inline-formatting sanitizer contract. The clip
37+
parser intentionally flattens inner formatting to text, so parse/generate is not
38+
a lossless replacement for editing the source HTML.
39+
2540
## Frame Adapters
2641

2742
A frame adapter tells the engine how to seek your animation to a specific frame:

‎packages/core/src/generators/hyperframes.test.ts‎

Lines changed: 184 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,13 @@ import {
77
generateGsapTimelineScript,
88
generateHyperframesStyles,
99
} from "./hyperframes.js";
10+
import { parseHtml } from "@hyperframes/parsers";
1011
import { GSAP_CDN } from "../templates/constants.js";
11-
import type { TimelineTextElement, TimelineMediaElement } from "../core.types";
12+
import type {
13+
TimelineTextElement,
14+
TimelineMediaElement,
15+
TimelineCompositionElement,
16+
} from "../core.types";
1217

1318
function makeTextElement(overrides: Partial<TimelineTextElement> = {}): TimelineTextElement {
1419
return {
@@ -37,6 +42,172 @@ function makeVideoElement(overrides: Partial<TimelineMediaElement> = {}): Timeli
3742
}
3843

3944
describe("generateHyperframesHtml", () => {
45+
it("contains mixed-case style closing tags in authored CSS", () => {
46+
const styles = '.label::after { content: "</StYlE><script>bad()</script>"; }';
47+
const doc = new DOMParser().parseFromString(
48+
generateHyperframesHtml([], 1, { styles, includeStyles: true }),
49+
"text/html",
50+
);
51+
expect(doc.querySelectorAll("style")).toHaveLength(2);
52+
expect(doc.querySelector("script")).toBeNull();
53+
expect(doc.querySelector("style[data-hf-custom]")?.textContent).toContain("StYlE");
54+
});
55+
56+
it("contains script closing tags while retaining JS string values and raw expressions", () => {
57+
const targetSelector = '#x"</ScRiPt><script>bad()</script>';
58+
const position = 'label"; bad(); //';
59+
const doc = new DOMParser().parseFromString(
60+
generateHyperframesHtml([], 1, {
61+
includeScripts: true,
62+
animations: [
63+
{ targetSelector, method: "to", position, properties: { x: "__raw:1 < 2 ? 3 : 4" } },
64+
],
65+
}),
66+
"text/html",
67+
);
68+
expect(doc.querySelectorAll("script")).toHaveLength(2);
69+
const script = doc.querySelector("script:not([src])")?.textContent ?? "";
70+
const calls: unknown[][] = [];
71+
const gsap = { timeline: () => ({ to: (...args: unknown[]) => calls.push(args) }) };
72+
new Function("gsap", script)(gsap);
73+
expect(calls).toEqual([[targetSelector, { x: 3 }, position]]);
74+
});
75+
76+
it("round-trips element attribute values without creating event handlers", () => {
77+
const marker = `x" onmouseover="bad()&quot;<`;
78+
const element = makeVideoElement({ id: marker, name: marker, src: marker });
79+
const doc = new DOMParser().parseFromString(generateHyperframesHtml([element], 1), "text/html");
80+
const video = doc.querySelector("video");
81+
for (const name of ["id", "data-hf-id", "data-name", "src"])
82+
expect(video?.getAttribute(name)).toBe(marker);
83+
expect(video?.hasAttribute("onmouseover")).toBe(false);
84+
expect(doc.querySelector("script")).toBeNull();
85+
});
86+
87+
it("keeps special IDs targeted by generated visibility animations", () => {
88+
const element = makeTextElement({ id: '9 title"[x],#other', name: "Title" });
89+
const doc = new DOMParser().parseFromString(generateHyperframesHtml([element], 1), "text/html");
90+
const targets: string[] = [];
91+
const gsap = { timeline: () => ({ set: (selector: string) => targets.push(selector) }) };
92+
new Function("gsap", generateGsapTimelineScript([element], 1))(gsap);
93+
expect(targets.length).toBeGreaterThan(0);
94+
for (const selector of targets) expect(doc.querySelector(selector)?.id).toBe(element.id);
95+
});
96+
97+
it("preserves supported rich text while removing executable markup", () => {
98+
const content =
99+
'<strong>A<span style="font-size: 32px; color: red" onclick="bad()">B</span></strong><br><sup>C</sup><script>bad()</script><svg onload="bad()"></svg><span style="background-color: url(evil)">D</span>';
100+
const html = generateHyperframesHtml([makeTextElement({ content })], 1);
101+
const doc = new DOMParser().parseFromString(html, "text/html");
102+
expect(doc.querySelector("strong span")?.getAttribute("style")).toContain("font-size: 32px");
103+
expect(doc.querySelector("strong span")?.hasAttribute("onclick")).toBe(false);
104+
expect(doc.querySelector("br")).not.toBeNull();
105+
expect(doc.querySelector("script,svg,sup,[onclick]")).toBeNull();
106+
expect(doc.querySelector("#text-1")?.textContent).toBe("ABCD");
107+
expect(html).not.toContain("url(evil)");
108+
expect(parseHtml(html).elements[0]).toMatchObject({ content: "ABCD" });
109+
});
110+
111+
it.each(["", "&amp;quot; &amp;#39; &amp;lt;"])(
112+
"preserves empty and entity-looking caption content: %s",
113+
(content) => {
114+
const html = generateHyperframesHtml([makeTextElement({ content })], 1);
115+
const doc = new DOMParser().parseFromString(html, "text/html");
116+
expect(doc.querySelector("#text-1")?.textContent).toBe(content ? "&quot; &#39; &lt;" : "");
117+
expect(parseHtml(html).elements[0]).toMatchObject({
118+
content: content ? "&quot; &#39; &lt;" : "",
119+
});
120+
},
121+
);
122+
123+
it.each([
124+
"javascript:bad()",
125+
"java\nscript:bad()",
126+
"vbscript:bad()",
127+
"data:text/html,<script>bad()</script>",
128+
])("rejects executable source URLs: %s", (src) => {
129+
expect(() => generateHyperframesHtml([makeVideoElement({ src })], 1)).toThrow(
130+
"Unsafe media or composition source URL",
131+
);
132+
});
133+
134+
it("rejects JavaScript supplied through a numeric element field", () => {
135+
const element = { ...makeTextElement(), startTime: "0); bad(); //" };
136+
expect(() => Reflect.apply(generateGsapTimelineScript, undefined, [[element], 1])).toThrow(
137+
"finite generator numeric value",
138+
);
139+
});
140+
141+
it("rejects declaration breakouts in generated color values", () => {
142+
expect(() =>
143+
generateHyperframesStyles(
144+
[makeTextElement({ color: "red; } body { color: blue" })],
145+
"landscape",
146+
),
147+
).toThrow("Invalid generated CSS value");
148+
});
149+
150+
it("keeps composition identifiers inside their attribute and round-trips entities", () => {
151+
const compositionId = `x" autofocus onfocus="alert(1)'><script>bad()</script>&quot;&`;
152+
const doc = new DOMParser().parseFromString(
153+
generateHyperframesHtml([], 1, { compositionId }),
154+
"text/html",
155+
);
156+
expect(doc.documentElement.getAttribute("data-composition-id")).toBe(compositionId);
157+
expect(doc.documentElement.hasAttribute("autofocus")).toBe(false);
158+
expect(doc.documentElement.hasAttribute("onfocus")).toBe(false);
159+
expect(doc.querySelector("script")).toBeNull();
160+
});
161+
162+
it("contains resolution values supplied by JavaScript callers inside their attribute", () => {
163+
const resolution = `x" autofocus onfocus="alert(1)'><script>bad()</script>&quot;&`;
164+
const html = Reflect.apply(generateHyperframesHtml, undefined, [
165+
[],
166+
1,
167+
{ resolution, includeStyles: false, includeScripts: false },
168+
]);
169+
const doc = new DOMParser().parseFromString(html, "text/html");
170+
expect(doc.documentElement.getAttribute("data-resolution")).toBe(resolution);
171+
expect(doc.documentElement.hasAttribute("autofocus")).toBe(false);
172+
expect(doc.documentElement.hasAttribute("onfocus")).toBe(false);
173+
expect(doc.querySelector("script")).toBeNull();
174+
});
175+
176+
it("round-trips entity-bearing CSS through the JSON metadata attribute", () => {
177+
const styles = `.x::after { content: "&quot; &#39; &amp; < > '"; }`;
178+
const doc = new DOMParser().parseFromString(
179+
generateHyperframesHtml([], 1, { styles }),
180+
"text/html",
181+
);
182+
expect(JSON.parse(doc.documentElement.getAttribute("data-custom-styles")!)).toBe(styles);
183+
expect(doc.querySelector("style")).toBeNull();
184+
expect(parseHtml(generateHyperframesHtml([], 1, { styles })).styles).toBe(styles);
185+
});
186+
187+
it("round-trips composition variable metadata through the public parser", () => {
188+
const variableValues = { label: `&quot; &#39; &amp; < > '`, count: 2, enabled: true };
189+
const element: TimelineCompositionElement = {
190+
id: "nested",
191+
type: "composition",
192+
name: "Nested",
193+
startTime: 0,
194+
duration: 1,
195+
zIndex: 0,
196+
src: "nested.html",
197+
compositionId: "nested-comp",
198+
variableValues,
199+
};
200+
const html = generateHyperframesHtml([element], 1);
201+
const parsed = parseHtml(html).elements[0];
202+
expect(parsed?.type).toBe("composition");
203+
if (parsed?.type !== "composition") throw new Error("Expected composition");
204+
expect(parsed.variableValues).toEqual(variableValues);
205+
const doc = new DOMParser().parseFromString(html, "text/html");
206+
expect(JSON.parse(doc.getElementById("nested")!.getAttribute("data-variable-values")!)).toEqual(
207+
variableValues,
208+
);
209+
});
210+
40211
it("generates valid HTML with proper data attributes", () => {
41212
const elements = [makeTextElement()];
42213
const html = generateHyperframesHtml(elements, 5);
@@ -153,7 +324,7 @@ describe("generateHyperframesHtml", () => {
153324
const elements = [makeTextElement({ id: "text-kf" })];
154325
const keyframes = {
155326
"text-kf": [
156-
{ id: "kf1", time: 0, properties: { opacity: 0 } },
327+
{ id: "kf1 &quot; &#39; < >", time: 0, properties: { opacity: 0 } },
157328
{ id: "kf2", time: 1, properties: { opacity: 1 } },
158329
],
159330
};
@@ -162,17 +333,27 @@ describe("generateHyperframesHtml", () => {
162333
expect(html).toContain("data-keyframes=");
163334
expect(html).toContain("kf1");
164335
expect(html).toContain("kf2");
336+
expect(parseHtml(html).keyframes["text-kf"]?.[0]?.id).toBe(keyframes["text-kf"][0]!.id);
337+
const doc = new DOMParser().parseFromString(html, "text/html");
338+
expect(JSON.parse(doc.getElementById("text-kf")!.getAttribute("data-keyframes")!)).toEqual(
339+
keyframes["text-kf"],
340+
);
165341
});
166342

167343
it("serializes zoom keyframes on zoom container", () => {
168344
const elements = [makeTextElement()];
169345
const stageZoomKeyframes = [
170-
{ id: "z1", time: 0, zoom: { scale: 1, focusX: 960, focusY: 540 } },
346+
{ id: "z1 &quot; &#39; < >", time: 0, zoom: { scale: 1, focusX: 960, focusY: 540 } },
171347
{ id: "z2", time: 5, zoom: { scale: 2, focusX: 400, focusY: 300 } },
172348
];
173349
const html = generateHyperframesHtml(elements, 10, { stageZoomKeyframes });
174350

175351
expect(html).toContain("data-zoom-keyframes=");
352+
expect(parseHtml(html).stageZoomKeyframes?.[0]?.id).toBe(stageZoomKeyframes[0]!.id);
353+
const doc = new DOMParser().parseFromString(html, "text/html");
354+
expect(
355+
JSON.parse(doc.getElementById("stage-zoom-container")!.getAttribute("data-zoom-keyframes")!),
356+
).toEqual(stageZoomKeyframes);
176357
});
177358

178359
it("includes x, y, scale data attributes for non-default values", () => {

0 commit comments

Comments
 (0)