fix: harden docs snippets, SVG sanitizer, lint regexes, GSAP writers and registry pins (#7512)

* fix(docs): escape catalog preview values and the install command's --vars argument

The catalog preview embeds variable values as JSON that cannot close a
script element or attribute, accepts value messages only from the page
that embeds it, and reads only declared ids with primitive values from
the link. The install command shell-quotes its --vars JSON and keeps
only variable-id keys with primitive values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): fold CSS line endings before decoding escapes in the SVG sanitizer

A browser folds CR LF, CR and form feed into one newline before it reads
CSS escapes, so the whitespace after a hex escape can be a CR LF pair.
The sanitizer now does the same, so an escaped function name split by a
line ending is checked under its real name. The media-use bundle is
regenerated from the source.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(lint): match template ids and CSS rules in linear time

A getElementById template literal is matched against document ids with
an in-order indexOf scan instead of a regex of joined wildcards, so the
time no longer grows with the number of placeholders. The CSS rule
scanners only start a match at the beginning of a brace-free run, which
finds the same rules without rescanning long brace-less text. Lint
results on every HTML file in the repository are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(parsers): keep GSAP writer output inside its script element

String literals and quoted keys the GSAP writers emit now encode a
script closer or comment opener as \u003c, so a value can no longer end
the inline script that holds the timeline. Strings without those
sequences are written exactly as before. The writers also refuse a tween
method outside set, to, from and fromTo, and a motion path whose
coordinates or curviness are not numbers, since both are emitted as code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(scripts): confine registry asset hosting to files inside the item

The asset hosting script now refuses a manifest path that leaves the
item directory or reaches its file through a symlink, before anything is
read, staged, uploaded or removed. A repository test fails when the
registry tracks a symlink or a manifest path that leaves its item.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(registry): pin the map blocks' d3 and atlas files to exact versions

The five map blocks load d3 7.9.2, the build the d3@7 range serves today,
with a subresource integrity hash, and fetch us-atlas 3.0.1 and
world-atlas 2.0.2, the files their ranges serve today. The bytes are
unchanged, so the blocks render the same. A repository test fails when a
registry item names an npm CDN package by range, tag or no version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(registry): pin map blocks to d3 7.9.0

7.9.0 has been the stable release since 2024; 7.9.1 and 7.9.2 were published days ago. Pin the
long-standing version, with its subresource integrity hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(registry): keep the map block PR source-only and formatted

Restore the generated catalog pages and payloads, which the catalog
publish job regenerates from the item sources. Name the us-atlas URL
in us-map-flow so the call fits on one line and formatting is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(scripts): check registry asset containment with one prefix test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(lint): scan simple CSS rules in linear time

The two CSS-rule scans in the gsap rules took a body that could cross
'{', so a closed style of many '{' with no '}' rescanned to its end from
every brace. A scanner now returns the same selector and body pairs and
remembers the next '}', so each scan is linear. Findings are identical
on every tracked HTML file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(core): label the form-feed sanitizer case as a guard

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michael Wang
2026-11-10 20:01:29 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 84c7d02a19
commit 24508ce2da
22 changed files with 583 additions and 93 deletions
+98 -1
View File
@@ -14,6 +14,7 @@
*/
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { dirname, join } from "node:path";
@@ -466,7 +467,11 @@ test("printing keeps two decimals and drops a negative zero", () => {
});
/** The component as a page renders it: React comes from the studio workspace, the hooks are the globals Mintlify supplies. */
async function renderDetail(slots: string[], wrapped = false): Promise<string> {
async function renderDetail(
slots: string[],
wrapped = false,
overrides: Record<string, unknown> = {},
): Promise<string> {
const requireFromStudio = createRequire(
join(dirname(fileURLToPath(import.meta.url)), "..", "packages", "studio", "package.json"),
);
@@ -510,6 +515,7 @@ async function renderDetail(slots: string[], wrapped = false): Promise<string> {
variables: [],
meta: { duration: 5, width: 1920, height: 1080 },
hasCode: true,
...overrides,
},
...children,
),
@@ -529,6 +535,97 @@ for (const wrapped of [false, true]) {
});
}
const previewValues = (() => {
const source = readFileSync(
join(dirname(fileURLToPath(import.meta.url)), "..", "docs", "snippets", "catalog-detail.jsx"),
"utf8",
);
const open = source.indexOf("// >>> preview values");
const close = source.indexOf("// <<< preview values");
assert.ok(open !== -1 && close > open, "the preview values markers are missing");
return new Function(`${source.slice(open, close)}\nreturn { scriptJson, declaredValues };`)() as {
scriptJson: (value: unknown) => string;
declaredValues: (parsed: unknown, ids: Set<string>) => Record<string, unknown>;
};
})();
test("preview values embed as JSON with no markup characters and read back unchanged", () => {
const value = { t: "</script><img src=x onerror=alert(1)>", a: "R&D", s: "\u2028\u2029", n: 2 };
const json = previewValues.scriptJson(value);
assert.ok(!/[<>&\u2028\u2029]/.test(json), json);
assert.deepEqual(JSON.parse(json), value);
assert.deepEqual(new Function(`return ${json};`)(), value);
assert.equal(previewValues.scriptJson({ a: "plain", n: 1.5 }), '{"a":"plain","n":1.5}');
});
test("a link's values keep only declared ids holding a string, finite number or boolean", () => {
const ids = new Set(["a", "b", "c", "d"]);
assert.deepEqual(
previewValues.declaredValues({ a: "x", b: 2, c: true, d: { nested: 1 }, e: "stray" }, ids),
{ a: "x", b: 2, c: true },
);
assert.deepEqual(previewValues.declaredValues(["a"], ids), {});
assert.deepEqual(previewValues.declaredValues(null, ids), {});
});
test("a link value that closes a script element stays inside the preview's bootstrap script", async () => {
const injected = "</script><script>window.hacked=1</script>";
const query = new URLSearchParams({ "vars-x": JSON.stringify({ label: injected }) });
Object.assign(globalThis, {
window: { location: { search: `?${query}` }, matchMedia: () => ({ matches: false }) },
});
try {
const html = await renderDetail(["install"], false, {
variables: [{ id: "label", type: "string", default: "hello" }],
});
const srcdoc = /srcDoc="([^"]*)"|srcdoc="([^"]*)"/.exec(html);
assert.ok(srcdoc, "the preview frame has a srcdoc");
const doc = (srcdoc[1] ?? srcdoc[2] ?? "")
.replace(/&quot;/g, '"')
.replace(/&#x27;/g, "'")
.replace(/&lt;/g, "<")
.replace(/&gt;/g, ">")
.replace(/&amp;/g, "&");
assert.equal(doc.match(/<script/gi)?.length, 2, "only the player and bootstrap scripts");
assert.ok(!doc.includes("window.hacked=1</script>"));
assert.match(doc, /var INITIAL = \{"label":"\\u003c\/script\\u003e/);
const body = /<body><script>([\s\S]*)<\/script><\/body>/.exec(doc)?.[1] ?? "";
assert.doesNotThrow(() => new Function(body), "the bootstrap script still parses");
assert.match(body, /var scriptJson = function scriptJson\(value\)/);
} finally {
Reflect.deleteProperty(globalThis, "window");
}
});
const varsArgument = (() => {
const source = readFileSync(
join(dirname(fileURLToPath(import.meta.url)), "..", "docs", "snippets", "install-command.jsx"),
"utf8",
);
const open = source.indexOf("// >>> vars argument");
const close = source.indexOf("// <<< vars argument");
assert.ok(open !== -1 && close > open, "the vars argument markers are missing");
return new Function(`${source.slice(open, close)}\nreturn varsArgument;`)() as (
raw: string | null,
) => string;
})();
test("the install command's --vars suffix is one shell argument for any link value", () => {
const hostile = { label: "a'; echo injected; echo '`$(id)`|\n", n: 3 };
const suffix = varsArgument(JSON.stringify(hostile));
const argv = execFileSync("sh", ["-c", `printf '%s\\0'${suffix}`])
.toString()
.split("\0");
assert.deepEqual(argv.slice(0, -1), ["--vars", JSON.stringify(hostile)]);
});
test("the install command keeps only variable-id keys with primitive values", () => {
assert.equal(varsArgument('{"speed":2,"on":true}'), ` --vars '{"speed":2,"on":true}'`);
assert.equal(varsArgument('{"a b":1,"nested":{"x":1},"list":[1]}'), "");
assert.equal(varsArgument('["speed"]'), "");
assert.equal(varsArgument(null), "");
});
test("the tabs are Preview, Code, Snippet, Docs with Preview selected", async () => {
const html = await renderDetail(["install"]);
const tabs = [
+63 -1
View File
@@ -1,9 +1,10 @@
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import fs from "node:fs";
import { syncBuiltinESMExports } from "node:module";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { test } from "node:test";
import { pathToFileURL } from "node:url";
@@ -69,3 +70,64 @@ test("source replacement between planning and staging aborts before manifest pub
fs.rmSync(f.root, { recursive: true, force: true });
}
});
test("a manifest path outside the item is refused before anything is staged or removed", async () => {
const f = await fixture();
try {
const outside = join(f.root, "registry/blocks/secret.png");
fs.writeFileSync(outside, "outside bytes");
fs.writeFileSync(
f.manifestPath,
JSON.stringify({ name: "test-item", files: [{ path: "../secret.png" }] }),
);
await assert.rejects(f.main(["test-item", "--no-upload"]), /outside the item/);
assert.equal(fs.readFileSync(outside, "utf8"), "outside bytes");
assert.equal(fs.existsSync(join(f.root, ".registry-assets-staging")), false);
} finally {
fs.rmSync(f.root, { recursive: true, force: true });
}
});
test("an asset that is a symlink is refused before its target is read", async () => {
const f = await fixture();
try {
const outside = join(f.root, "secret.txt");
fs.writeFileSync(outside, "outside bytes");
fs.rmSync(f.source);
fs.symlinkSync(outside, f.source);
const manifest = fs.readFileSync(f.manifestPath, "utf8");
await assert.rejects(f.main(["test-item", "--no-upload"]), /symlink/);
assert.equal(fs.readFileSync(f.manifestPath, "utf8"), manifest);
assert.equal(fs.readFileSync(outside, "utf8"), "outside bytes");
assert.equal(fs.existsSync(join(f.root, ".registry-assets-staging")), false);
} finally {
fs.rmSync(f.root, { recursive: true, force: true });
}
});
test("the registry tracks no symlinks and every manifest path stays inside its item", () => {
const listing = execFileSync("git", ["ls-files", "-s", "-z", "registry"], {
cwd: repoRoot,
encoding: "utf-8",
maxBuffer: 64 * 1024 * 1024,
});
const entries = listing.split("\0").filter(Boolean);
const symlinks = entries.filter((entry) => entry.startsWith("120000 "));
assert.deepEqual(symlinks, []);
const escaping = entries
.map((entry) => entry.slice(entry.indexOf("\t") + 1))
.filter((file) => file.endsWith("/registry-item.json") && fs.existsSync(join(repoRoot, file)))
.flatMap((file) => {
const itemDir = join(repoRoot, dirname(file));
const manifest = JSON.parse(fs.readFileSync(join(repoRoot, file), "utf8")) as {
files?: Array<{ path: string }>;
};
return (manifest.files ?? [])
.filter(({ path }) => {
const rel = relative(itemDir, resolve(itemDir, path));
return rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
})
.map(({ path }) => `${file}: ${path}`);
});
assert.deepEqual(escaping, []);
});
+17 -3
View File
@@ -41,12 +41,13 @@ import {
mkdirSync,
readdirSync,
readFileSync,
realpathSync,
rmSync,
unlinkSync,
writeFileSync,
} from "node:fs";
import { execFileSync } from "node:child_process";
import { dirname, extname, join, resolve } from "node:path";
import { dirname, extname, join, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
import { runAsCommand } from "./entrypoint.ts";
// Import from source, like every other script here: bun workspace linking does
@@ -126,10 +127,23 @@ function needsHosting(file: FileTarget): boolean {
return file.url === undefined && HOSTED_EXTENSIONS.has(extname(file.path).toLowerCase());
}
/** The declared file's path, refused unless it is inside the item and reached without a symlink. */
function itemSource(itemName: string, itemDir: string, path: string): string {
const root = realpathSync(itemDir);
const source = resolve(root, path);
if (!source.startsWith(root + sep)) {
throw new Error(`${itemName}: files[] declares "${path}", which is outside the item.`);
}
if (realpathSync(source) !== source) {
throw new Error(`${itemName}: files[] declares "${path}", which goes through a symlink.`);
}
return source;
}
/** Point one file at the CDN, and say which bytes have to get there. */
function hostFile(itemName: string, itemDir: string, file: FileTarget): Plan {
const source = resolve(itemDir, file.path);
const fd = openSync(source, constants.O_RDONLY | constants.O_NONBLOCK);
const source = itemSource(itemName, itemDir, file.path);
const fd = openSync(source, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
let digest: string;
try {
if (!fstatSync(fd).isFile()) {
+42
View File
@@ -0,0 +1,42 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import { join, resolve } from "node:path";
/** Registry items load npm packages from a CDN only at an exact version, so the bytes cannot change under them. */
const ROOT = resolve(import.meta.dirname, "..");
const NPM_CDN =
/(?:cdn\.jsdelivr\.net\/npm|unpkg\.com)\/((?:@[^/@"'`\s]+\/)?[^/@"'`\s)]+)(@[^/"'`\s)]*)?/g;
const EXACT = /^@\d+\.\d+\.\d+(?:-[\w.]+)?$/;
function floatingCdnReferences(text: string): string[] {
return [...text.matchAll(NPM_CDN)]
.filter((match) => !EXACT.test(match[2] ?? ""))
.map((match) => match[0]);
}
test("a range, tag or missing version is reported", () => {
assert.deepEqual(
floatingCdnReferences(
`<script src="https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js"></script>
fetch("https://unpkg.com/us-atlas/states-10m.json");
import x from "https://cdn.jsdelivr.net/npm/@scope/pkg@latest/+esm";
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>`,
),
["cdn.jsdelivr.net/npm/d3@7", "unpkg.com/us-atlas", "cdn.jsdelivr.net/npm/@scope/pkg@latest"],
);
});
test("every npm CDN reference in a registry item names an exact version", () => {
const files = execFileSync("git", ["ls-files", "-z", "registry"], {
cwd: ROOT,
encoding: "utf-8",
})
.split("\0")
.filter((file) => /\.(html|js|mjs|json)$/.test(file));
const floating = files.flatMap((file) =>
floatingCdnReferences(readFileSync(join(ROOT, file), "utf-8")).map((ref) => `${file}: ${ref}`),
);
assert.deepEqual(floating, []);
});