@tokenoftrust/storefront-runner 4.14.0 → 5.0.0

package/apps/storefront/src/config/kvTenantResolver.ts

@@ -17,7 +17,8 @@
  */
 import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
 import { withPlatformPolicy } from "@/config/tenants";
-import { TENANT_RECORD_PREFIX } from "@/config/storedTenantRecord";
+import { TENANT_RECORD_PREFIX, getStoredTenantRecord } from "@/config/storedTenantRecord";
+import { mergeStoredTenantRecord } from "@tot/public-runtime/tenant-record-merge";
 
 const DOMAIN_PREFIX = "domain:";
 const TENANT_PREFIX = TENANT_RECORD_PREFIX;
@@ -76,16 +77,25 @@ export class KvTenantResolver implements TenantResolver {
 }
 
 /**
- * Register (or update) a tenant in KV. Idempotent: writes the config blob and a
- * domain->id index entry for each claimed hostname. Pass `makeDefault` to point
- * the unknown-host fallback at this tenant. Call this from onboarding/migration.
+ * Register (or update) a tenant in KV. Idempotent: merges the config into the stored
+ * `tenant:<id>` record (provisioned keys win, stored keys the config does not carry survive;
+ * see `@tot/public-runtime/tenant-record-merge`) and writes a domain->id index entry for each
+ * claimed hostname. The stored record is read uncached. A stored record that is not a JSON
+ * object throws before any write. Pass `makeDefault` to point the unknown-host fallback at
+ * this tenant. Call this from onboarding/migration.
  */
 export async function putTenant(
   kv: KVNamespace,
   config: TenantConfig,
   opts: { makeDefault?: boolean } = {},
 ): Promise<void> {
-  await kv.put(TENANT_PREFIX + config.tenant_id, JSON.stringify(config));
+  const key = TENANT_PREFIX + config.tenant_id;
+  const record = mergeStoredTenantRecord(
+    key,
+    await getStoredTenantRecord(kv, config.tenant_id),
+    config as unknown as Record<string, unknown>,
+  );
+  await kv.put(key, record);
   for (const domain of config.domains) {
     const host = cleanHost(domain);
     if (host) await kv.put(DOMAIN_PREFIX + host, config.tenant_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.14.0",
+  "version": "5.0.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -26,6 +26,7 @@
     "./svg-sanitize": "./src/svg-sanitize.ts",
     "./incremental-sha256": "./src/incremental-sha256.ts",
     "./image-limits": "./src/image-limits.mjs",
+    "./tenant-record-merge": "./src/tenant-record-merge.mjs",
     "./image-release-gate": "./src/image-release-gate.ts",
     "./pool-asset-headers": "./src/pool-asset-headers.ts",
     "./catalog-files": "./src/catalog-files.ts",

package/packages/public-runtime/src/hosted-image-media-types.ts

@@ -14,10 +14,10 @@
  *
  * - PINNED_ASSET_*: a tenant's locally-pinned bundle asset (/_a/<sha256>.<ext>,
  *   e.g. a favicon) -- a hash-verified, already-reviewed file. Includes SVG.
- * - CAPTURABLE_RASTER_MEDIA_TYPES: what a *remote* capture (original-image-capture.ts)
- *   may fetch and rehost. Deliberately EXCLUDES svg: an externally-sourced SVG can
- *   embed <script> and is an XSS vector, so only local, already-reviewed SVGs may
- *   ever reach the pinned-asset path above.
+ * - CAPTURABLE_RASTER_MEDIA_TYPES: the raster formats capture reads by their magic
+ *   bytes. An SVG is never stored as fetched: capture and upload pass it through the
+ *   one sanitizer (`svg-sanitize.ts`) and store only its output, which is what lets a
+ *   sealed `remote` or `upload` entry carry `image/svg+xml` (`sealedMediaTypeAllowed`).
  */
 
 export const PINNED_ASSET_EXTENSION_BY_MEDIA_TYPE: Readonly<Record<string, string>> = Object.freeze({
@@ -41,20 +41,20 @@ export const CAPTURABLE_RASTER_MEDIA_TYPES = Object.freeze([
 
 export type CapturableRasterMediaType = (typeof CAPTURABLE_RASTER_MEDIA_TYPES)[number];
 
-/** Comma-joined for an HTTP `Accept` header -- derived, never a second literal. */
-export const CAPTURABLE_RASTER_ACCEPT_HEADER = CAPTURABLE_RASTER_MEDIA_TYPES.join(",");
-
 /**
- * An author upload may also be an SVG: the upload path is the one ingest that sanitizes it
- * (`svg-sanitize.ts`) before it enters the pool, so a sealed `upload` entry may carry it while a
- * captured (`local`/`remote`) entry never does.
+ * An author upload or a remote capture may also be an SVG: both pass it through the sanitizer
+ * (`svg-sanitize.ts`) and store only its output, so a sealed `upload` or `remote` entry may carry
+ * it. A `local` entry is a repo file capture reads by raster magic, never an SVG.
  */
 export const UPLOADABLE_MEDIA_TYPES = Object.freeze([...CAPTURABLE_RASTER_MEDIA_TYPES, "image/svg+xml"] as const);
 
 export type UploadableMediaType = (typeof UPLOADABLE_MEDIA_TYPES)[number];
 
+/** Comma-joined for a remote capture's HTTP `Accept` header -- derived, never a second literal. */
+export const CAPTURE_ACCEPT_HEADER = UPLOADABLE_MEDIA_TYPES.join(",");
+
 /** May a sealed original of provenance `kind` carry `mediaType`? Every reader of a manifest asks this. */
 export function sealedMediaTypeAllowed(kind: unknown, mediaType: unknown): boolean {
-  const types: readonly string[] = kind === "upload" ? UPLOADABLE_MEDIA_TYPES : CAPTURABLE_RASTER_MEDIA_TYPES;
+  const types: readonly string[] = kind === "upload" || kind === "remote" ? UPLOADABLE_MEDIA_TYPES : CAPTURABLE_RASTER_MEDIA_TYPES;
   return typeof mediaType === "string" && types.includes(mediaType);
 }

package/packages/public-runtime/src/image-release-gate.ts

@@ -145,7 +145,8 @@ function supportedPoolEntry(entry: string, facts: ReleaseImageFacts, formats: Po
   if (!Object.hasOwn(formats.mediaTypeByExtension, ext)) return false;
   if (ext !== ".svg") return true;
   const bytes = facts.heldPoolBytes(entry);
-  // A captured SVG is a sealed upload: it entered the pool only as sanitizer output (ADR 0038 §12).
+  // A captured SVG (a remote capture or an upload) entered the pool only as sanitizer output, which
+  // is a fixed point of the sanitizer (ADR 0038 §12).
   if (!bytes) return facts.captured(entry);
   const result = formats.sanitizeSvg(bytes);
   return result.ok && !result.changed;

package/packages/public-runtime/src/svg-sanitize.ts

@@ -15,11 +15,17 @@
  *   `xml:space` and `xml:lang` are removed;
  * - references (`href`, `xlink:href`, every `url()`): only a same-document fragment (`#id`), a pool
  *   object (`/_a/<sha256><ext>`) or an inline raster `data:` image. Any other reference is removed;
- * - `<style>` text with an escape, `@import`, a non-pool `url()` or a script-capable construct
- *   refuses the image rather than being half-cleaned.
+ * - CSS: `<style>` text with an escape, a comment, `@import`, a non-pool `url()` or a script- or
+ *   fetch-capable construct refuses the image rather than being half-cleaned. Every other kept
+ *   attribute whose value could hold CSS (it contains `(` or `\`, as `fill`, `cursor` or `filter`
+ *   can) passes the same CSS check or is removed. `<style>` text reads as the browser reads it:
+ *   character data entity-decoded, a CDATA section raw.
  *
  * Output is the input with the removed spans cut out, byte for byte otherwise, so an already-clean
- * SVG keeps its bytes and therefore its address. Import-free.
+ * SVG keeps its bytes and therefore its address. Cutting a span out can join its neighbours into
+ * markup neither held (a `]]>`, a tag), so the output is read again and must come back unchanged:
+ * a sanitized SVG is a fixed point of this pass, which is what lets every later reader re-check it
+ * for free. Import-free.
  */
 
 export const SVG_SANITIZER_ID = "svg-allowlist-1";
@@ -122,17 +128,22 @@ function urlTargets(css: string): string[] | null {
 }
 
 const UNSAFE_CSS = ["@import", "@font-face", "@namespace", "expression(", "javascript:", "vbscript:", "-moz-binding",
-  "behavior", "image-set(", "cross-fade(", "element(", "src("];
+  "behavior", "image-set(", "image(", "cross-fade(", "element(", "src("];
 
-/** Why `css` is unsafe, or null when it is safe to keep. */
+/**
+ * Why `css` is unsafe, or null when it is safe to keep. A comment is refused outright rather than
+ * stripped: a CSS string can hold a `/*` the browser never reads as one, so stripping by pattern
+ * would hide the text between it and the next comment closer from this check while the browser
+ * applies it.
+ */
 function unsafeCss(css: string): string | null {
   if (css.includes("\\")) return "it uses a CSS escape sequence";
-  const stripped = css.replace(/\/\*[\s\S]*?\*\//g, "");
-  if (stripped.includes("/*")) return "it has an unterminated CSS comment";
-  const lower = stripped.toLowerCase();
+  if (css.includes("/*")) return "it has a CSS comment";
+  const lower = css.toLowerCase();
   const construct = UNSAFE_CSS.find((item) => lower.includes(item));
   if (construct) return `it uses \`${construct}\``;
-  const targets = urlTargets(stripped);
+  if (/url[ \t\r\n\f]+\(/.test(lower)) return "it has a url() that cannot be read exactly";
+  const targets = urlTargets(css);
   if (!targets) return "it has a url() that cannot be read exactly";
   if (targets.some((target) => !isPoolSafeReference(target))) return "it references a url() outside this image or the pool";
   return null;
@@ -158,14 +169,36 @@ export function sanitizeSvg(bytes: Uint8Array, limits: Partial<SvgSanitizeLimits
     return refuse("not-utf8", "it is not UTF-8 text");
   }
   try {
-    return sanitizeText(source, bound);
+    const first = sanitizeText(source, bound);
+    if (!first.changed) return result(first, bytes);
+    const spliced = new Refusal("malformed", "removing its unsafe parts would form new markup");
+    let again: Pass;
+    try {
+      again = sanitizeText(first.output, bound);
+    } catch (error) {
+      if (error instanceof Refusal) throw spliced;
+      throw error;
+    }
+    if (again.changed) throw spliced;
+    return result(first, bytes);
   } catch (error) {
     if (error instanceof Refusal) return refuse(error.reason, error.detail);
     throw error;
   }
 }
 
-function sanitizeText(source: string, limits: SvgSanitizeLimits): SvgSanitizeResult {
+interface Pass { output: string; changed: boolean; removedElements: number; removedAttributes: number }
+
+/** An unchanged document is answered as the very bytes it arrived as, so its address stands. */
+function result(pass: Pass, input: Uint8Array): SvgSanitizeResult {
+  return {
+    ok: true, bytes: pass.changed ? new TextEncoder().encode(pass.output) : input,
+    changed: pass.changed, removedElements: pass.removedElements, removedAttributes: pass.removedAttributes,
+  };
+}
+
+/** One allowlist pass over `source`; throws {@link Refusal}. */
+function sanitizeText(source: string, limits: SvgSanitizeLimits): Pass {
   const out: string[] = [];
   const stack: Open[] = [];
   let i = 0;
@@ -200,6 +233,7 @@ function sanitizeText(source: string, limits: SvgSanitizeLimits): SvgSanitizeRes
       if (end === -1) throw malformed("a CDATA section is not closed");
       if (!dropped) {
         if (!open?.style) throw malformed("a CDATA section appears outside <style>");
+        // A CDATA section is raw CSS to the browser: never entity-decoded.
         open.style.css += source.slice(i + 9, end);
         out.push(source.slice(i, end + 3));
       }
@@ -223,9 +257,7 @@ function sanitizeText(source: string, limits: SvgSanitizeLimits): SvgSanitizeRes
       const top = stack.pop();
       if (!top || top.name !== match[1]) throw malformed(`</${match[1]}> does not close the open element`);
       if (top.style) {
-        const decoded = decodeEntities(top.style.css);
-        if (decoded === null) throw new Refusal("entity", "a <style> uses an undefined entity");
-        const unsafe = unsafeCss(decoded);
+        const unsafe = unsafeCss(top.style.css);
         if (unsafe) throw new Refusal("unsafe-style", `a <style> element is unsafe: ${unsafe}`);
       }
       if (!top.dropped) out.push(match[0]);
@@ -297,9 +329,11 @@ function sanitizeText(source: string, limits: SvgSanitizeLimits): SvgSanitizeRes
       out.push(text);
     } else {
       if (text.includes("]]>")) throw malformed("text contains `]]>`");
-      if (decodeEntities(text) === null) throw new Refusal("entity", "its text uses an undefined entity");
+      const decodedText = decodeEntities(text);
+      if (decodedText === null) throw new Refusal("entity", "its text uses an undefined entity");
       if (!dropped) {
-        if (open?.style) open.style.css += text;
+        // Character data is entity-decoded before the browser reads it as CSS.
+        if (open?.style) open.style.css += decodedText;
         out.push(text);
       }
     }
@@ -308,10 +342,7 @@ function sanitizeText(source: string, limits: SvgSanitizeLimits): SvgSanitizeRes
   if (!rootSeen) throw new Refusal("not-svg", "it has no root element");
   if (stack.length > 0) throw malformed(`<${stack[stack.length - 1]!.name}> is not closed`);
   const output = out.join("");
-  return {
-    ok: true, bytes: new TextEncoder().encode(output), changed: output !== source,
-    removedElements, removedAttributes,
-  };
+  return { output, changed: output !== source, removedElements, removedAttributes };
 }
 
 /** Whether a kept element keeps this attribute (its decoded value). */
@@ -322,10 +353,8 @@ function keepAttribute(name: string, value: string, isRoot: boolean): boolean {
   if (name.includes(":") && !ALLOWED_PREFIXED_ATTRIBUTES.has(name)) return false;
   if (name === "href" || name === "xlink:href") return isPoolSafeReference(value);
   if (/javascript:|vbscript:/i.test(value.replace(/[\s\u0000-\u001f]+/g, ""))) return false;
-  if (name === "style") return unsafeCss(value) === null;
-  if (/url[ \t\r\n\f]*\(/i.test(value)) {
-    const targets = urlTargets(value);
-    return !!targets && targets.every(isPoolSafeReference) && !/url[ \t\r\n\f]+\(/i.test(value);
-  }
+  // Presentation attributes (`fill`, `cursor`, `filter`, …) are CSS values too: one that could hold
+  // a function or an escape passes the same check as `style`.
+  if (name === "style" || value.includes("(") || value.includes("\\")) return unsafeCss(value) === null;
   return true;
 }

package/packages/public-runtime/src/tenant-record-merge.d.mts

@@ -0,0 +1,9 @@
+export declare function mergeTenantRecord(
+  stored: Record<string, unknown>,
+  provisioned: Record<string, unknown>,
+): Record<string, unknown>;
+export declare function mergeStoredTenantRecord(
+  key: string,
+  storedRaw: string | null | undefined,
+  provisioned: Record<string, unknown>,
+): string;

package/packages/public-runtime/src/tenant-record-merge.mjs

@@ -0,0 +1,68 @@
+/**
+ * Merge a provisioned tenant config into the `tenant:<id>` KV record already stored.
+ *
+ * Provisioners carry only the fields they own. The stored record also holds fields written by
+ * other paths (`storefront.mode`, `addOns.largeImages`), so a provisioner must read the stored
+ * record, merge, and write the result; it never replaces the record wholesale.
+ *
+ * Contract:
+ * - the provisioned config wins for every key it carries;
+ * - plain objects merge recursively; arrays and scalars from the provisioned config replace;
+ * - keys the provisioned config does not carry are preserved;
+ * - `__proto__`, `constructor` and `prototype` keys are dropped at every level;
+ * - no stored record: the provisioned config is written as given;
+ * - a stored value that is not a JSON object (unparseable, array, scalar, empty string) throws,
+ *   naming the key, and the caller writes nothing.
+ *
+ * KV has no transaction. A provisioner that reads, merges and writes while the admin add-ons
+ * switch writes the same record can still lose one of the two writes; the merge narrows that
+ * window to one read-to-write interval and cannot close it.
+ */
+
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {Record<string, unknown>} stored
+ * @param {Record<string, unknown>} provisioned
+ * @returns {Record<string, unknown>}
+ */
+export function mergeTenantRecord(stored, provisioned) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [key, value] of Object.entries(stored)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    out[key] = value;
+  }
+  for (const [key, value] of Object.entries(provisioned)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    const existing = out[key];
+    out[key] = isPlainObject(value) && isPlainObject(existing) ? mergeTenantRecord(existing, value) : value;
+  }
+  return out;
+}
+
+/**
+ * The JSON to write at `key` for `provisioned`, given the raw stored value (`null` when absent).
+ * @param {string} key
+ * @param {string | null | undefined} storedRaw
+ * @param {Record<string, unknown>} provisioned
+ * @returns {string}
+ */
+export function mergeStoredTenantRecord(key, storedRaw, provisioned) {
+  if (storedRaw === null || storedRaw === undefined) return JSON.stringify(provisioned);
+  let stored;
+  try {
+    stored = JSON.parse(storedRaw);
+  } catch {
+    throw new Error(`stored KV record ${key} is not valid JSON; refusing to overwrite it`);
+  }
+  if (!isPlainObject(stored)) {
+    throw new Error(`stored KV record ${key} is not a JSON object; refusing to overwrite it`);
+  }
+  return JSON.stringify(mergeTenantRecord(stored, provisioned));
+}

package/packages/public-runtime/tests/fixtures/malicious-svg-corpus.ts

@@ -0,0 +1,79 @@
+/**
+ * The hostile-SVG corpus every SVG intake is tested against: the sanitizer itself, remote capture
+ * and author upload. Each case is either `neutralized` (the stored bytes keep the drawing with the
+ * attack removed) or refused with the sanitizer reason named. `assertInert` is the property every
+ * stored SVG must hold.
+ */
+import type { SvgRefusalReason } from "../../src/svg-sanitize";
+
+const NS = 'xmlns="http://www.w3.org/2000/svg"';
+const XLINK = 'xmlns:xlink="http://www.w3.org/1999/xlink"';
+
+export interface MaliciousSvgCase {
+  label: string;
+  svg: string;
+  /** `neutralized`: accepted with the attack cut out; otherwise the refusal reason. */
+  expect: "neutralized" | SvgRefusalReason;
+}
+
+export const MALICIOUS_SVG_CORPUS: readonly MaliciousSvgCase[] = [
+  { label: "script element", svg: `<svg ${NS}><script>alert(1)</script><rect/></svg>`, expect: "neutralized" },
+  { label: "script with CDATA", svg: `<svg ${NS}><script><![CDATA[alert(1) && x < y]]></script></svg>`, expect: "neutralized" },
+  { label: "namespaced XHTML script", svg: `<svg ${NS}><h:script xmlns:h="http://www.w3.org/1999/xhtml">alert(1)</h:script></svg>`, expect: "neutralized" },
+  { label: "foreignObject with HTML", svg: `<svg ${NS}><foreignObject><iframe xmlns="http://www.w3.org/1999/xhtml" src="javascript:alert(1)"></iframe></foreignObject></svg>`, expect: "neutralized" },
+  { label: "onload handler", svg: `<svg ${NS} onload="alert(1)"><rect/></svg>`, expect: "neutralized" },
+  { label: "mixed-case handlers", svg: `<svg ${NS}><rect OnClick="alert(1)" onmouseover='x()'/></svg>`, expect: "neutralized" },
+  { label: "javascript: href", svg: `<svg ${NS}><a href="javascript:alert(1)"><text>x</text></a></svg>`, expect: "neutralized" },
+  { label: "entity-obfuscated javascript: xlink:href", svg: `<svg ${NS} ${XLINK}><a xlink:href="&#106;avascript:alert(1)"><rect/></a></svg>`, expect: "neutralized" },
+  { label: "vbscript: in an attribute", svg: `<svg ${NS}><rect filter="vbscript:msgbox(1)"/></svg>`, expect: "neutralized" },
+  { label: "data:text/html href", svg: `<svg ${NS}><a href="data:text/html,x"><rect/></a></svg>`, expect: "neutralized" },
+  { label: "nested SVG data URI", svg: `<svg ${NS}><image href="data:image/svg+xml;base64,PHN2Zz48L3N2Zz4="/></svg>`, expect: "neutralized" },
+  { label: "external href image", svg: `<svg ${NS}><image href="https://evil.example/track.png"/></svg>`, expect: "neutralized" },
+  { label: "external xlink:href image", svg: `<svg ${NS} ${XLINK}><image xlink:href="https://evil.example/track.png"/></svg>`, expect: "neutralized" },
+  { label: "external use sprite", svg: `<svg ${NS}><use href="https://evil.example/sprite.svg#a"/></svg>`, expect: "neutralized" },
+  { label: "set rewrites href", svg: `<svg ${NS}><a href="#x"><set attributeName="href" to="javascript:alert(1)"/><rect/></a></svg>`, expect: "neutralized" },
+  { label: "animate rewrites href", svg: `<svg ${NS}><a href="#x"><animate attributeName="href" values="javascript:alert(1)"/></a></svg>`, expect: "neutralized" },
+  { label: "external fill url", svg: `<svg ${NS}><rect fill="url(https://evil.example/p.svg#a)"/></svg>`, expect: "neutralized" },
+  { label: "external style attribute url", svg: `<svg ${NS}><rect style="fill:url('https://evil.example/x')"/></svg>`, expect: "neutralized" },
+  // Design-review CSS bypasses.
+  { label: "escaped url in a presentation attribute", svg: `<svg ${NS}><rect fill="u\\72l(https://evil.example/x)"/></svg>`, expect: "neutralized" },
+  { label: "-webkit-image-set in cursor", svg: `<svg ${NS}><rect cursor="-webkit-image-set(&quot;https://evil.example/c.png&quot; 1x), auto"/></svg>`, expect: "neutralized" },
+  { label: "image-set in a style attribute", svg: `<svg ${NS}><rect style="cursor:image-set('https://evil.example/c.png' 1x)"/></svg>`, expect: "neutralized" },
+  { label: "comment opener hidden in a CSS string", svg: `<svg ${NS}><style>.a{font-family:"/*"}.b{fill:url(https://evil.example/x)}.c{x:"*/"}</style><rect class="b"/></svg>`, expect: "unsafe-style" },
+  { label: "entity-encoded comment markers in CDATA", svg: `<svg ${NS}><style><![CDATA[&#47;&#42;]]>.b{fill:url(https://evil.example/x)}<![CDATA[&#42;&#47;]]></style><rect class="b"/></svg>`, expect: "unsafe-style" },
+  { label: "entity-encoded comment around a CDATA url", svg: `<svg ${NS}><style><![CDATA[&#47;&#42; .b{fill:url(https://evil.example/x)} &#42;&#47;]]></style></svg>`, expect: "unsafe-style" },
+  { label: "removed span splices ]]>", svg: `<svg ${NS}><text>]]<script/>></text></svg>`, expect: "malformed" },
+  { label: "style @import", svg: `<svg ${NS}><style>@import url(https://evil.example/x.css);</style></svg>`, expect: "unsafe-style" },
+  { label: "style CSS escape", svg: `<svg ${NS}><style>.a{background:\\75rl(https://evil.example/x)}</style></svg>`, expect: "unsafe-style" },
+  { label: "DOCTYPE internal subset (billion laughs)", svg: `<!DOCTYPE svg [<!ENTITY a "aaaa"><!ENTITY b "&a;&a;&a;&a;">]><svg ${NS}><text>&b;</text></svg>`, expect: "entity" },
+  { label: "external entity", svg: `<!DOCTYPE svg [<!ENTITY x SYSTEM "file:///etc/passwd">]><svg ${NS}><text>&x;</text></svg>`, expect: "entity" },
+  { label: "undefined entity", svg: `<svg ${NS}><text>&nbsp;</text></svg>`, expect: "entity" },
+  { label: "processing instruction stylesheet", svg: `<svg ${NS}><?xml-stylesheet href="https://evil.example/x.css"?></svg>`, expect: "malformed" },
+  { label: "root is HTML", svg: `<html xmlns="http://www.w3.org/1999/xhtml"><svg ${NS}/></html>`, expect: "not-svg" },
+  { label: "element-count cap", svg: `<svg ${NS}>${"<rect/>".repeat(100_001)}</svg>`, expect: "too-complex" },
+  { label: "depth cap", svg: `<svg ${NS}>${"<g>".repeat(300)}${"</g>".repeat(300)}</svg>`, expect: "too-complex" },
+];
+
+/** A clean logo as design tools export it: must round-trip byte-identical. */
+export const BENIGN_LOGO =
+  `<?xml version="1.0" encoding="UTF-8"?>\n<svg ${NS} ${XLINK} viewBox="0 0 120 40" width="120" height="40">\n` +
+  `  <title>Logo</title>\n  <defs>\n    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">` +
+  `<stop offset="0" stop-color="#ff6a00"/><stop offset="1" stop-color="#ee0979"/></linearGradient>\n` +
+  `    <clipPath id="c"><rect width="120" height="40" rx="6"/></clipPath>\n` +
+  `    <style>.wordmark{fill:url(#g);font-family:Helvetica,Arial,sans-serif;font-weight:700}</style>\n  </defs>\n` +
+  `  <g clip-path="url(#c)" transform="translate(2 2) rotate(0)">\n` +
+  `    <path d="M0 0h36v36H0z" fill="url(#g)" stroke="#000" stroke-width="0.5"/>\n` +
+  `    <use xlink:href="#c"/>\n    <text x="44" y="26" class="wordmark">Vape &amp; Co &#169;</text>\n  </g>\n</svg>\n`;
+
+/** Nothing in stored bytes can run script or reach outside the image and the pool. */
+export function inertViolations(output: string): string[] {
+  const checks: Array<[string, RegExp]> = [
+    ["script-capable element", /<script|<foreignObject|<iframe|<animate|<set[\s>/]|<handler|<listener|<h:script/i],
+    ["event handler", /\son[a-z]+\s*=/i],
+    ["script url", /javascript:|vbscript:|&#106;avascript/i],
+    ["active data url", /data:text\/html|data:image\/svg/i],
+    ["external reference", /https?:\/\/(?!www\.w3\.org\/(?:2000\/svg|1999\/xlink))|\/\/evil/i],
+    ["css escape or image-set", /\\|image-set/i],
+  ];
+  return checks.filter(([, pattern]) => pattern.test(output)).map(([name]) => name);
+}