@legionworks/facet 1.9.0

package/src/validation/tier0/svg.ts

@@ -0,0 +1,321 @@
+/**
+ * Tier 0 SVG parser.
+ *
+ * Uses `fast-xml-parser` to tokenize the source as XML, then walks the
+ * tree checking structural invariants. The Tier 0 verdict never
+ * executes any SVG; it only verifies that the artifact cannot smuggle
+ * executable content past the renderer:
+ *
+ *   - `<script>` elements are rejected at any depth.
+ *   - `<foreignObject>` may not contain `<script>` either (a nested
+ *     escape vector).
+ *   - Event-handler attributes (`on*`) on every element are rejected.
+ *   - URLs in `href`/`xlink:href` must NOT reference external schemes
+ *     (http(s), file, ftp, javascript, data, blob). Inline-only.
+ *   - The root element must be `<svg>` (not, e.g., a hostile XML
+ *     payload that happens to parse as XML).
+ *   - The root must carry a `viewBox` (verifiers check `viewBoxes`).
+ *
+ * The parser does not enforce renderer-side layout (Tier 1's job); it
+ * only validates structural safety.
+ */
+
+import { XMLParser } from "fast-xml-parser";
+
+import { MAX_SVG_BYTES, MAX_SVG_ROOTS } from "../../shared/config/limits";
+import type { DiscriminativeError, VerdictObserved } from "../../shared/contracts/validation";
+
+const XML_OPTIONS = {
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  allowBooleanAttributes: true,
+  parseTagValue: false,
+  parseAttributeValue: false,
+  trimValues: true,
+  // Treat these as void so a hostile DTD/ENTITY doesn't expand.
+  processEntities: false,
+};
+
+export interface SvgParseOk {
+  readonly status: "ok";
+  readonly observed: VerdictObserved;
+  readonly viewBoxes: readonly string[];
+}
+
+export interface SvgParseFail {
+  readonly status: "error";
+  readonly observed: VerdictObserved;
+  readonly errors: readonly DiscriminativeError[];
+}
+
+export type SvgParseResult = SvgParseOk | SvgParseFail;
+
+const EVENT_HANDLER_RE = /^on[a-z]+$/i;
+const EXTERNAL_SCHEME_RE = /^(?:https?|ftp|file|javascript|data|blob|vbscript|jar):/i;
+const DANGEROUS_TAGS = new Set(["script"]);
+
+/**
+ * Recursively walk the parsed XML tree, counting the elements/attributes
+ * Tier 0 must reject. The walk does NOT execute anything; it only
+ * collects evidence for the verdict.
+ */
+function walkNode(
+  node: unknown,
+  name: string,
+  ctx: {
+    scriptElements: number;
+    eventHandlerAttributes: number;
+    externalRefAttributes: number;
+    rootSvgCount: number;
+    viewBoxes: string[];
+  },
+  isRoot: boolean,
+): void {
+  if (name === "script" || DANGEROUS_TAGS.has(name)) {
+    ctx.scriptElements += 1;
+  }
+  if (!isPlainObject(node)) return;
+  // Detect attributes on the current element.
+  for (const [key, value] of Object.entries(node)) {
+    if (!key.startsWith("@_")) continue;
+    const attrName = key.slice(2);
+    const attrValue = typeof value === "string" ? value : String(value ?? "");
+    if (EVENT_HANDLER_RE.test(attrName)) {
+      ctx.eventHandlerAttributes += 1;
+      continue;
+    }
+    if (attrName === "href" || attrName === "xlink:href") {
+      if (EXTERNAL_SCHEME_RE.test(attrValue.trim())) {
+        ctx.externalRefAttributes += 1;
+      }
+      continue;
+    }
+    if (isRoot && attrName === "viewBox") {
+      ctx.viewBoxes.push(attrValue);
+    }
+  }
+  if (isRoot && name === "svg") {
+    ctx.rootSvgCount += 1;
+  }
+  // Recurse into children (each key maps to a sub-node or array of sub-nodes).
+  for (const [key, value] of Object.entries(node)) {
+    if (key.startsWith("@_")) continue;
+    if (key === "#text") continue;
+    if (Array.isArray(value)) {
+      for (const child of value) walkNode(child, key, ctx, false);
+    } else if (value !== undefined) {
+      walkNode(value, key, ctx, false);
+    }
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parse the source bytes as SVG. The parse is structural: no DOM, no
+ * rendering, no URL fetch. A hostile source that smuggles
+ * `<script>`/handlers/external URLs is rejected at Tier 0 so it can
+ * never reach a renderer.
+ */
+export function parseSvg(bytes: Uint8Array): SvgParseResult {
+  if (bytes.byteLength > MAX_SVG_BYTES) {
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: 0,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: 1,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [
+        {
+          code: "svg_too_large",
+          message: `SVG bytes exceed MAX_SVG_BYTES (${MAX_SVG_BYTES})`,
+        },
+      ],
+    };
+  }
+
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  const parser = new XMLParser(XML_OPTIONS);
+  let parsed: unknown;
+  try {
+    parsed = parser.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: 0,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: 1,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [{ code: "svg_xml_error", message }],
+    };
+  }
+
+  // The parsed root is an object whose keys are the top-level XML
+  // elements. We walk it as if the outermost key were the document
+  // element; for an SVG document the key is "svg" and the inner
+  // children are the elements we want to scan.
+  const ctx = {
+    scriptElements: 0,
+    eventHandlerAttributes: 0,
+    externalRefAttributes: 0,
+    rootSvgCount: 0,
+    viewBoxes: [] as string[],
+  };
+  if (isPlainObject(parsed)) {
+    for (const [topName, topValue] of Object.entries(parsed)) {
+      const children = Array.isArray(topValue) ? topValue : [topValue];
+      for (const child of children) {
+        walkNode(child, topName, ctx, true);
+      }
+    }
+  }
+
+  if (ctx.rootSvgCount === 0) {
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: 0,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: 1,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [
+        {
+          code: "svg_no_root",
+          message: "Document does not contain a top-level <svg> element",
+        },
+      ],
+    };
+  }
+  if (ctx.rootSvgCount > MAX_SVG_ROOTS) {
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: ctx.rootSvgCount,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: 1,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [
+        {
+          code: "svg_too_many_roots",
+          message: `SVG contains ${ctx.rootSvgCount} top-level <svg> elements; cap is ${MAX_SVG_ROOTS}`,
+        },
+      ],
+    };
+  }
+  if (ctx.viewBoxes.length === 0) {
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: ctx.rootSvgCount,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: 1,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [
+        {
+          code: "svg_missing_viewbox",
+          message:
+            "Top-level <svg> element must declare a viewBox; Tier 0 rejects ambiguous bounds",
+        },
+      ],
+    };
+  }
+  if (ctx.scriptElements > 0) {
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: ctx.rootSvgCount,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: ctx.scriptElements,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [
+        {
+          code: "svg_script_element",
+          message: `SVG contains ${ctx.scriptElements} <script> element(s); Tier 0 rejects them`,
+        },
+      ],
+    };
+  }
+  if (ctx.eventHandlerAttributes > 0) {
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: ctx.rootSvgCount,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: ctx.eventHandlerAttributes,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [
+        {
+          code: "svg_event_handler",
+          message: `SVG contains ${ctx.eventHandlerAttributes} on*= event-handler attribute(s); Tier 0 rejects them`,
+        },
+      ],
+    };
+  }
+  if (ctx.externalRefAttributes > 0) {
+    return {
+      status: "error",
+      observed: {
+        rendererRootSvgCount: ctx.rootSvgCount,
+        graphCount: 0,
+        mermaidNodeCount: 0,
+        visibleSvgCount: 0,
+        errorCount: ctx.externalRefAttributes,
+        opaqueRegionCount: 0,
+        externalImageCount: 0,
+      },
+      errors: [
+        {
+          code: "svg_external_reference",
+          message: `SVG contains ${ctx.externalRefAttributes} external-scheme URL attribute(s); Tier 0 rejects them`,
+        },
+      ],
+    };
+  }
+
+  return {
+    status: "ok",
+    observed: {
+      rendererRootSvgCount: ctx.rootSvgCount,
+      graphCount: 0,
+      mermaidNodeCount: 0,
+      visibleSvgCount: ctx.rootSvgCount,
+      errorCount: 0,
+      opaqueRegionCount: 0,
+      externalImageCount: 0,
+    },
+    viewBoxes: ctx.viewBoxes,
+  };
+}

package/src/validation/tier0/tsx/allowlist-resolver.ts

@@ -0,0 +1,77 @@
+/**
+ * Bun build plugin that enforces the TSX module allowlist at the resolver
+ * layer.
+ *
+ * D6 of the TSX design declares a fixed vendored allowlist. The AST policy
+ * rejects non-allowlisted `import` declarations with a typed verdict, but
+ * the AST walker is one line of defense — `require()`, dynamic paths, and
+ * other indirect routes can slip past it. This plugin is the second line:
+ * it intercepts every bare module specifier and redirects non-allowlisted
+ * names to a sentinel that fails to load. A bypass of the AST layer still
+ * cannot pull a forbidden module into a bundle.
+ *
+ * Bun's `onResolve` API returns `{ path, namespace?, external? }` — there is
+ * no first-class way to emit a typed error from the resolver hook. We work
+ * around this by redirecting to a fixed sentinel path and throwing from
+ * `onLoad` when the bundler tries to load it; the resulting build log
+ * carries the violated module name. This is intentionally clunky — the
+ * AST walker produces the structured `DiscriminativeError` verdict, and
+ * this plugin exists only so a code path that bypasses the walker still
+ * cannot bundle a forbidden package.
+ *
+ * ## Limitation
+ *
+ * The plugin intercepts BARE specifiers (anything that does not start with
+ * `.`, `/`, or `\`). Relative imports are checked by the AST walker; URL
+ * imports are blocked at the AST layer; this plugin handles the node_modules
+ * path. Anything that reaches the bundler via a hook the plugin cannot see
+ * (Bun's built-in pre-resolution, native module records) is OUT OF SCOPE.
+ */
+
+import type { BunPlugin } from "bun";
+
+import { TSX_ALLOWED_MODULES } from "../../../shared/tsx/import-policy";
+
+/**
+ * Sentinel path the plugin redirects every non-allowlisted import to.
+ * Resolving or loading this path fails, and the `onLoad` hook throws a
+ * named error so the build log carries the violated module.
+ */
+const SENTINEL_PATH = "/__facet_tsx_allowlist_violation__";
+
+/**
+ * Build the allowlist resolver plugin. Pass it to `Bun.build({ plugins })`
+ * so every bare module resolution goes through the gate.
+ */
+export function tsxAllowlistResolverPlugin(): BunPlugin {
+  const violations: string[] = [];
+  return {
+    name: "facet-tsx-allowlist-resolver",
+    setup(build) {
+      build.onResolve({ filter: /^[^./\\:]/ }, (args) => {
+        // The entrypoint is passed through onResolve with kind =
+        // "entry-point-build"; we let it pass to the default resolver.
+        if (args.kind === "entry-point-build") return undefined;
+        // Transitive dependencies (imports from inside node_modules) are
+        // trusted to resolve themselves; only the user's top-level
+        // imports are gated by the allowlist.
+        if (args.importer.includes("/node_modules/")) return undefined;
+        if (TSX_ALLOWED_MODULES.has(args.path)) {
+          return undefined; // let the default resolver find it
+        }
+        violations.push(args.path);
+        return { path: SENTINEL_PATH };
+      });
+      build.onLoad({ filter: /.*/ }, (args) => {
+        if (args.path === SENTINEL_PATH) {
+          throw new Error(
+            `TSX allowlist violation: ${violations.join(", ")} ` +
+              `is not in the vendored allowlist ` +
+              `(allowed: ${[...TSX_ALLOWED_MODULES].join(", ")})`,
+          );
+        }
+        return undefined;
+      });
+    },
+  };
+}

package/src/validation/tier0/tsx/ast-policy-capabilities.ts

@@ -0,0 +1,238 @@
+import ts from "typescript";
+
+import type { DiscriminativeError } from "../../../shared/contracts/validation";
+import {
+  ALIAS_DENIED_NAMES,
+  formatArgument,
+  identifierText,
+  isDeniedGlobalEval,
+  isDeniedGlobalName,
+  push,
+  resolveStringFragments,
+  TSX_CAPABILITY_CODES,
+} from "./ast-policy-shared";
+
+type ShadowCheck = (node: ts.Identifier) => boolean;
+
+export function checkCallExpression(
+  node: ts.CallExpression,
+  errors: DiscriminativeError[],
+  sourceFile: ts.SourceFile,
+  isShadowed: ShadowCheck,
+): void {
+  if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.dynamicImport,
+      "TSX dynamic import() is not allowed",
+      node,
+      sourceFile,
+    );
+    return;
+  }
+  if (
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === "require" &&
+    !isShadowed(node.expression)
+  ) {
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.requireCall,
+      "TSX require(...) is not allowed; the vendored allowlist is ESM-only",
+      node,
+      sourceFile,
+    );
+    return;
+  }
+  const expression = node.expression;
+  if (
+    ts.isIdentifier(expression) &&
+    isDeniedGlobalName(expression.text) &&
+    !isShadowed(expression)
+  ) {
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.fetch,
+      `TSX global "${expression.text}(...)" is not allowed`,
+      node,
+      sourceFile,
+    );
+    return;
+  }
+  if (ts.isParenthesizedExpression(expression)) {
+    const inner = expression.expression;
+    if (
+      ts.isBinaryExpression(inner) &&
+      inner.operatorToken.kind === ts.SyntaxKind.CommaToken &&
+      ts.isNumericLiteral(inner.left) &&
+      ts.isIdentifier(inner.right) &&
+      isDeniedGlobalEval(inner.right.text) &&
+      !isShadowed(inner.right)
+    ) {
+      push(
+        errors,
+        TSX_CAPABILITY_CODES.evalCall,
+        'TSX indirect eval "(0, eval)(...)" is not allowed',
+        node,
+        sourceFile,
+      );
+      return;
+    }
+  }
+  if (
+    ts.isIdentifier(expression) &&
+    isDeniedGlobalEval(expression.text) &&
+    !isShadowed(expression)
+  ) {
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.evalCall,
+      `TSX global "${expression.text}(...)" is not allowed`,
+      node,
+      sourceFile,
+    );
+    return;
+  }
+  if (ts.isPropertyAccessExpression(expression)) {
+    const targetName = identifierText(expression.expression);
+    const propertyName = expression.name.text;
+    if (
+      targetName !== null &&
+      (targetName === "globalThis" ||
+        targetName === "window" ||
+        targetName === "self" ||
+        targetName === "global") &&
+      (isDeniedGlobalName(propertyName) || isDeniedGlobalEval(propertyName))
+    ) {
+      push(
+        errors,
+        propertyName === "eval" ? TSX_CAPABILITY_CODES.evalCall : TSX_CAPABILITY_CODES.fetch,
+        `TSX global "${targetName}.${propertyName}(...)" is not allowed`,
+        node,
+        sourceFile,
+      );
+    }
+  }
+}
+
+export function checkNewExpression(
+  node: ts.NewExpression,
+  errors: DiscriminativeError[],
+  sourceFile: ts.SourceFile,
+  isShadowed: ShadowCheck,
+): void {
+  const expression = node.expression;
+  if (!ts.isIdentifier(expression) || isShadowed(expression)) return;
+  const name = expression.text;
+  if (name === "Function") {
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.functionConstructor,
+      'TSX "new Function(...)" is not allowed',
+      node,
+      sourceFile,
+    );
+  } else if (name === "Worker") {
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.worker,
+      'TSX "new Worker(...)" is not allowed',
+      node,
+      sourceFile,
+    );
+  } else if (name === "SharedWorker") {
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.sharedWorker,
+      'TSX "new SharedWorker(...)" is not allowed',
+      node,
+      sourceFile,
+    );
+  }
+}
+
+export function checkVariableStatement(
+  node: ts.VariableStatement,
+  errors: DiscriminativeError[],
+  sourceFile: ts.SourceFile,
+): void {
+  for (const declaration of node.declarationList.declarations) {
+    if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined) continue;
+    if (!isDeniedAliasInitializer(declaration.initializer)) continue;
+    push(
+      errors,
+      TSX_CAPABILITY_CODES.aliasOfDeniedGlobal,
+      `TSX binding "${declaration.name.text}" aliases a denied global or constructor; this is not allowed`,
+      node,
+      sourceFile,
+    );
+  }
+}
+
+function isDeniedAliasInitializer(init: ts.Expression): boolean {
+  if (ts.isIdentifier(init)) return ALIAS_DENIED_NAMES.has(init.text);
+  if (ts.isPropertyAccessExpression(init)) {
+    const target = identifierText(init.expression);
+    if (target === null || !ALIAS_DENIED_NAMES.has(target)) return false;
+    return ALIAS_DENIED_NAMES.has(init.name.text);
+  }
+  return false;
+}
+
+export function checkPropertyAccess(
+  node: ts.PropertyAccessExpression,
+  errors: DiscriminativeError[],
+  sourceFile: ts.SourceFile,
+): void {
+  const target = identifierText(node.expression);
+  if (target === null || !["globalThis", "window", "self", "global"].includes(target)) return;
+  const property = node.name.text;
+  if (isDeniedGlobalName(property) || isDeniedGlobalEval(property)) {
+    push(
+      errors,
+      property === "eval" ? TSX_CAPABILITY_CODES.evalCall : TSX_CAPABILITY_CODES.fetch,
+      `TSX global "${target}.${property}" is not allowed`,
+      node,
+      sourceFile,
+    );
+  }
+}
+
+export function checkElementAccess(
+  node: ts.ElementAccessExpression,
+  errors: DiscriminativeError[],
+  sourceFile: ts.SourceFile,
+): void {
+  const target = identifierText(node.expression);
+  if (target === null || !["globalThis", "window", "self", "global"].includes(target)) return;
+  const resolved = resolveStringFragments(node.argumentExpression);
+  if (resolved !== null) {
+    if (isDeniedGlobalName(resolved)) {
+      push(
+        errors,
+        TSX_CAPABILITY_CODES.fetch,
+        `TSX computed global "${target}[${formatArgument(node.argumentExpression)}]" resolves to "${resolved}"`,
+        node,
+        sourceFile,
+      );
+      return;
+    }
+    if (isDeniedGlobalEval(resolved)) {
+      push(
+        errors,
+        TSX_CAPABILITY_CODES.evalCall,
+        `TSX computed global "${target}[${formatArgument(node.argumentExpression)}]" resolves to "${resolved}"`,
+        node,
+        sourceFile,
+      );
+      return;
+    }
+  }
+  push(
+    errors,
+    TSX_CAPABILITY_CODES.unsupportedComputedGlobal,
+    `TSX computed access on "${target}[...]" cannot be statically resolved; review the artifact`,
+    node,
+    sourceFile,
+  );
+}

package/src/validation/tier0/tsx/ast-policy-shared.ts

@@ -0,0 +1,71 @@
+import ts from "typescript";
+
+import type { DiscriminativeError } from "../../../shared/contracts/validation";
+
+export const TSX_CAPABILITY_CODES = {
+  fetch: "tsx_capability_fetch",
+  evalCall: "tsx_capability_eval",
+  functionConstructor: "tsx_capability_function_constructor",
+  dynamicImport: "tsx_capability_dynamic_import",
+  worker: "tsx_capability_worker",
+  sharedWorker: "tsx_capability_shared_worker",
+  unsupportedComputedGlobal: "tsx_capability_computed_global",
+  requireCall: "tsx_capability_require",
+  aliasOfDeniedGlobal: "tsx_capability_global_alias",
+} as const;
+
+export function locationFor(node: ts.Node, sourceFile: ts.SourceFile): string {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return `${line + 1}:${character + 1}`;
+}
+
+export function push(
+  errors: DiscriminativeError[],
+  code: string,
+  message: string,
+  node: ts.Node,
+  sourceFile: ts.SourceFile,
+): void {
+  errors.push({ code, message, location: locationFor(node, sourceFile) });
+}
+
+export function isDeniedGlobalName(name: string): boolean {
+  return name === "fetch";
+}
+
+export function isDeniedGlobalEval(name: string): boolean {
+  return name === "eval";
+}
+
+export const ALIAS_DENIED_NAMES = new Set([
+  "globalThis",
+  "window",
+  "self",
+  "global",
+  "Worker",
+  "SharedWorker",
+  "Function",
+  "fetch",
+  "eval",
+]);
+
+export function identifierText(node: ts.Expression): string | null {
+  if (ts.isIdentifier(node)) return node.text;
+  return null;
+}
+
+export function formatArgument(node: ts.Expression): string {
+  if (ts.isStringLiteral(node)) return JSON.stringify(node.text);
+  return "<expression>";
+}
+
+export function resolveStringFragments(node: ts.Expression): string | null {
+  if (ts.isStringLiteral(node)) return node.text;
+  if (ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const left = resolveStringFragments(node.left);
+    const right = resolveStringFragments(node.right);
+    if (left !== null && right !== null) return left + right;
+  }
+  return null;
+}