agent-sanitizer 2.64.2 → 2.66.0

package/README.md

@@ -227,6 +227,11 @@ guessing if the marketplace was never added. To pull a release by hand instead:
 
 `plugin/README.md` has the managed-settings form for enabling it fleet-wide.
 
+The plugin installs from this repository's `plugin-dist` branch, which CI
+builds from each release tag; `main` carries the sources only, so a checkout
+runs `pnpm install` (and `pnpm build:redactor` for the zipapp) to get a
+runnable `plugin/`.
+
 To wire them yourself instead, one entry dispatches every mode on `--hook=`:
 
 ```jsonc

package/THREAT-MODEL.md

@@ -122,8 +122,23 @@ range is preserved verbatim** (no re-serialization). Unclosed hidden markup
 extends to the end of the fragment—fail-closed for truncated input.
 
 Scripting/resource tags (`script`, `style`, `object`, `embed`, `iframe`, `svg`,
-`math`) and `data:` URI resources are **reported, not removed**: their bodies are
-page source the model may legitimately need to inspect.
+`math`, `template`) and `data:` URI resources are **reported, not removed**:
+their bodies are page source the model may legitimately need to inspect.
+
+A `<template>`'s content is a fragment the browser parses but never renders, so
+instructions placed there reach a model reading the source and no human reading
+the page. It is also where web components and client-side renderers keep their
+UI markup, so the template is reported rather than spliced, and its content is
+scanned like any other markup: a hidden element or comment inside it is
+spliced, a `<script>` inside it reported, a URL inside it read by Layer 3. A
+declarative shadow root (`shadowrootmode="open"`/`"closed"`) is reported too,
+since one the parser fails to attach (a second root on one host, say) is an
+ordinary inert template; its content is laid out in its host's box, so a flex
+host blockifies it as it would a light-DOM child. Slot assignment is not
+modelled: a hidden `<slot>` splices only itself, not the light-DOM children
+the browser renders through it. A `template` inside SVG or MathML (or an HTML
+`template.x`) is not reported: it has no template content, so its children are
+ordinary children and are scanned as such.
 
 HTML comments (`<!--…-->`, and the bogus `<!…>`/`<?…?>` forms) are spliced
 like hidden elements — a human viewing the rendered page never sees them. But
@@ -146,9 +161,12 @@ Report—never rewrite—URLs in markdown links/images/definitions, every HTML/S
 URL attribute in `src/url-attributes.mjs` (`src`, `href`, `xlink:href`,
 `srcset`/`imagesrcset`, `ping`, `poster`, `object data`, form
 `action`/`formaction`, `meta refresh`, …), CSS `url()` in `style` attributes and
-`<style>` elements, and the same again inside HTML comments, that are shaped to
-carry data off-origin. A URL's scheme is read by the WHATWG URL parser, and
-`srcset` and `meta refresh` by ports of the HTML Standard's own parsing steps:
+`<style>` elements, and the same again inside HTML comments and `<template>`
+content, that are shaped to carry data off-origin. A URL inside a comment or an
+inert template is reported as not auto-fetched: nothing there loads until a
+reader or a script acts on it. A URL's scheme is read by the WHATWG URL parser,
+and `srcset` and `meta refresh` by ports of the HTML Standard's own parsing
+steps:
 
 - suspicious query/fragment parameters (long base64/hex blobs, credential-shaped
   tokens), tuned to skip request-signing / pagination / analytics parameters
@@ -835,31 +853,49 @@ sanitizes (see `plugin/scripts/provision-hook-binary.sh`). That is the
 product's only path that fetches an executable over the network and later runs
 it, so what anchors its trust is worth stating exactly.
 
-- **The anchor is in the repo, not on the wire.** `plugin/dist/hooks/hook-binaries.sha256`
-  is committed, and the SessionStart provisioner refuses to install any download
-  that does not hash to the digest it pins for that platform. A compromised or
-  substituted release asset alone therefore cannot be installed: it fails the
-  comparison, is deleted, and the launcher keeps degrading loudly through node.
-- **What the digest is worth rests on the compile being reproducible.** The
-  committed digests are generated from the committed bundle, and the release
-  recompiles and byte-compares them (`build-hook-binaries.mjs --check` in
-  `release-hook-binaries.sh`), so binaries that do not reproduce the manifest are
-  never uploaded. The manifest is refreshed on the default branch by
-  `auto-version.yaml`, ahead of that release, so what it describes is the bundle
-  the release ships.
-- **A manifest that has fallen behind its bundle installs nothing.** Between a
-  merge and that refresh, the default branch pins binaries compiled from the
-  previous bundle. The provisioner compares its own bundle against the manifest's
-  `# bundle=` pin and refuses on a mismatch, so the window degrades to the node
-  path rather than running a binary that is not the code the install ships. A
-  binary provisioned before the window stays installed but loses its install
-  stamp, and the launcher runs a binary whose stamp does not name the shipped
-  manifest only on a host where no node is found — there an older sanitizer
-  still beats an unsanitized call.
-- **Not covered: an attacker who can write BOTH the repository and the release.**
-  There is no signature; the manifest is trusted because it arrives through the
-  same reviewed, gated path as the rest of the plugin. Rewriting it is rewriting
-  the plugin, which is outside this boundary.
+- **The anchor travels with the plugin, not on the wire.**
+  `plugin/dist/hooks/hook-binaries.sha256` ships in the installed plugin, and the
+  SessionStart provisioner refuses to install any download that does not hash
+  to the digest it pins for that platform. A compromised or substituted release
+  asset alone therefore cannot be installed: it fails the comparison, is
+  deleted, and the launcher keeps degrading loudly through node.
+- **The installed plugin is the `plugin-dist` branch, and no human reviews it.**
+  `.claude-plugin/marketplace.json` installs from `plugin-dist`, whose commits
+  `.github/workflows/plugin-dist.yaml` writes: it checks out a release tag (a
+  `main` commit that went through review and the required checks), builds the
+  bundle, the zipapp, the generated shell libs and the manifest, compiles the
+  binaries, uploads them only after `sha256sum --check` against that manifest
+  passes, and then pushes the build. The manifest and the binaries come from the
+  same run, so the digest proves the download is what that run built — not that
+  an independent rebuild agrees. What the user runs is therefore exactly as
+  trustworthy as whatever can write `plugin-dist`.
+- **Who can write `plugin-dist`.** The workflow pushes with
+  `TEMPLATE_SYNC_TOKEN_ORG` (the stock `GITHUB_TOKEN` where that secret is
+  unset), and the push is fast-forward only. Pushes are restricted to that
+  identity by a branch ruleset on `refs/heads/plugin-dist` blocking creation,
+  update, deletion and non-fast-forward for everyone but the repository's admin
+  bypass actors. That ruleset is repository configuration, not code in this
+  tree, so nothing here creates it; `plugin-dist-ruleset.yaml` only detects
+  its absence, failing daily and on any marketplace change while no active
+  `update` rule covers the branch. Without it, any collaborator with write
+  access can push the branch and ship code to every installed user. With it, the residual writers are the
+  admins and anything that can run a workflow holding that secret — a workflow
+  edited onto a branch of this repository can read it, so write access to the
+  repository still reaches `plugin-dist` through Actions, as it reaches `main`'s
+  release path.
+- **A manifest that disagrees with its bundle installs nothing.** The bake
+  refuses to stage a manifest whose `# bundle=` pin is not the bundle it built,
+  and the provisioner compares its own bundle against that pin and refuses on a
+  mismatch, so a hand-rebuilt bundle beside an older manifest degrades to the
+  node path rather than running a binary that is not the code the install ships.
+  A binary provisioned under an earlier release stays installed but loses its
+  install stamp, and the launcher runs a binary whose stamp does not name the
+  shipped manifest only on a host where no node is found — there an older
+  sanitizer still beats an unsanitized call.
+- **Not covered: an attacker who can write `plugin-dist`, or the workflow that
+  writes it.** There is no signature; the manifest is trusted because it arrives
+  in the same commit as the rest of the plugin. Rewriting it is rewriting the
+  plugin, which is outside this boundary.
 - **Not covered: re-verification at exec time.** The digest is checked once, at
   install. The launcher then execs
   `${CLAUDE_PLUGIN_DATA}/hook-binary/agent-sanitizer-hooks` on every hook
@@ -883,12 +919,12 @@ it, so what anchors its trust is worth stating exactly.
   location.** The provisioned redactor venv (`${CLAUDE_PLUGIN_DATA}/venv` and its
   `bin/`, whose daemon receives every secret-bearing payload) is handed to the
   client only when `trusted_dir` vouches for both directories; otherwise the
-  client redacts through the committed zipapp. The degraded-warning marker root
+  client redacts through the shipped zipapp. The degraded-warning marker root
   under `TMPDIR` is read only when this user owns it with owner-only write, so a
   squatted shared-temp entry cannot pre-suppress the warning that a call ran
   unsanitized.
 - **Opting out.** `AGENT_SANITIZER_HOOK_BINARY=0` never downloads and never runs
-  a binary. That leaves the node path running the committed bundle and the
+  a binary. That leaves the node path running the shipped bundle and the
   compile cache above; `AGENT_SANITIZER_COMPILE_CACHE=0` turns the cache off as
   well, and an operator's own `NODE_COMPILE_CACHE` is used unchanged.
 

package/claude-hooks/lib/knobs.mjs

@@ -25,9 +25,9 @@
  * cannot reach (it runs its no-node arm on shell builtins alone).
  *
  * THE single source of truth for the closed set. The shell shims cannot import
- * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it by
- * `scripts/gen-fail-open-lib.mjs` and committed; the round trip is asserted in
- * plugin/test/fail-open-parity.test.mjs. Everything else that spells the set
+ * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it at build time
+ * by `scripts/gen-fail-open-lib.mjs`; plugin/test/fail-open-parity.test.mjs
+ * asserts the generated lib decides as failOpenEnabled(). Everything else that spells the set
  * out by hand is an implementation that must appear in the parity table in
  * tests/test_safe_launch.py.
  */

package/claude-hooks/lib/redactor-client.mjs

@@ -115,7 +115,7 @@ export const DEFAULT_SOCKET_PATH = resolveSocketPath(process.env, currentUid());
  *    sets it to the provisioned venv's console script when one exists, and
  *    tests point it at dead paths to drive the fail-closed arm; a fallback
  *    from an explicit setting would turn those arms into silent passes).
- * 2. The committed self-contained zipapp (`plugin/dist/redactor/daemon.pyz`) —
+ * 2. The shipped self-contained zipapp (`plugin/dist/redactor/daemon.pyz`) —
  *    the guaranteed floor: it needs only a python3 on PATH, so a cold start
  *    with no venv and no network still redacts instead of failing closed on
  *    every tool call. At `_AGENT_SANITIZER_REDACTOR_PYZ` when the launcher
@@ -129,7 +129,7 @@ function daemonCommand() {
   const configured = readKnob("_AGENT_SANITIZER_REDACTOR_DAEMON");
   if (configured) return [configured];
   // Inside the built bundle import.meta.url is .../plugin/dist/hooks/<bundle>,
-  // so the committed zipapp sits one level up; from the raw sources no such
+  // so the shipped zipapp sits one level up; from the raw sources no such
   // sibling exists and the check falls through.
   const pyz =
     readKnob("_AGENT_SANITIZER_REDACTOR_PYZ") ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.64.2",
+  "version": "2.66.0",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {
@@ -249,12 +249,13 @@
     "check": "tsc --noEmit && tsc -p tsconfig.hooks.json --noEmit",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.hooks.json --noEmit",
     "build:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.build-hooks.json",
+    "build": "pnpm build:plugin && node plugin/scripts/build-redactor-pyz.mjs --if-missing",
+    "build:plugin": "node plugin/scripts/build-plugin.mjs",
+    "build:redactor": "node plugin/scripts/build-redactor-pyz.mjs",
     "gen:joining-type": "node scripts/gen-joining-type.mjs",
     "gen:unicode": "node scripts/gen-unicode.mjs",
     "gen:gfm-autolink": "node scripts/gen-gfm-autolink.mjs",
     "gen:unicode-properties": "node scripts/gen-unicode-properties.mjs",
-    "gen:fail-open-lib": "node scripts/gen-fail-open-lib.mjs",
-    "gen:node-floor-lib": "node scripts/gen-node-floor-lib.mjs",
     "gen:hook-binaries": "node plugin/scripts/build-hook-binaries.mjs",
     "lint": "eslint .",
     "test:mutation": "node scripts/mutate.mjs",

package/src/html-tree-adapter.mjs

@@ -174,8 +174,8 @@ export const MAX_HTML_DEPTH = 4096;
  * the name up to its first `#` or `.`, lowercased.
  *
  * WHY IT MATTERS — the converter then recurses into the parse5 node's `content`,
- * which only an HTML-namespace `<template>` has. A `template` inside SVG or
- * MathML, or an HTML `template.x` tag, has none, the converter throws,
+ * which only an HTML-namespace `<template>` has. An `<svg><template>`, a
+ * `<math><template>` or an HTML `<template.x>` has none, the converter throws,
  * and the whole document would be withheld over a benign element.
  */
 const CONVERTS_AS_TEMPLATE = /^template(?:[#.]|$)/i;
@@ -189,6 +189,15 @@ const CONVERTS_AS_TEMPLATE = /^template(?:[#.]|$)/i;
  * changes it (lowercasing, the SVG case map). The element then converts the way
  * any element without template content does: its children as `children`, where
  * every scan of the hast tree reads them, which is also where the DOM has them.
+ *
+ * WHY A MASK, and not an empty parse5 `content` handed to the element so the
+ * converter has a fragment to recurse into: hastscript's `h` and `s` (the
+ * converter builds every element with one of them) move the children of ANY
+ * element they name `template` into the hast node's `content` and leave its
+ * `children` empty, and the converter then overwrites that `content` with its
+ * conversion of the parse5 fragment. Handed an empty one, the element's
+ * children would vanish with no error, and every Layer 2/3 scan in
+ * `./html.mjs` would go blind to them.
  */
 const TEMPLATE_MASK = " ";
 

package/src/html.mjs

@@ -1502,7 +1502,13 @@ export function isHiddenStyle(styleStr) {
 // Scripting / resource-loading tags whose PRESENCE is reported to the model
 // but whose content is preserved: their bodies are page source the model may
 // legitimately need to inspect (how a page's scripts work, its styles, its
-// SVGs), so unlike hidden elements they are never removed.
+// SVGs), so unlike hidden elements they are never removed. An HTML `template`
+// is here because the browser parses its content into a fragment it never
+// renders — a reader of the source sees it, a reader of the page does not —
+// while that content is also where a component's UI markup legitimately lives.
+// A declarative shadow root is reported too: whether the parser attaches one
+// depends on its host's name and on the host having no earlier root, and a
+// root that fails to attach is an ordinary inert template.
 export const REPORTED_TAGS = new Set([
   "script",
   "style",
@@ -1511,8 +1517,34 @@ export const REPORTED_TAGS = new Set([
   "iframe",
   "svg",
   "math",
+  "template",
 ]);
 
+/**
+ * True for a template whose content the page never renders: every one but a
+ * declarative shadow root (`shadowrootmode` of `open` or `closed`), whose
+ * content the browser's parser attaches to the parent as a shadow tree.
+ * @param {any} node a hast element with template content (a `content` root)
+ * @returns {boolean}
+ */
+function isInertTemplate(node) {
+  const mode = String(node.properties.shadowRootMode ?? "").toLowerCase();
+  return mode !== "open" && mode !== "closed";
+}
+
+/**
+ * True when Layer 2 reports `node`'s presence (see {@link REPORTED_TAGS}).
+ * Only an HTML `template` has template content; one inside SVG or MathML, or a
+ * `template.x`, is an ordinary element whose children are scanned as children.
+ * @param {any} node a hast element
+ * @returns {boolean}
+ */
+function isReportedElement(node) {
+  return node.tagName === "template"
+    ? node.content !== undefined
+    : REPORTED_TAGS.has(node.tagName);
+}
+
 // HTML void elements: they never carry content and never emit a closing tag, so
 // a hidden one (<img hidden>, <input hidden>, …) must be spliced as a single node
 // — opening a balance region for it would run to the container's end (no close
@@ -1629,8 +1661,27 @@ function elementCascade(node) {
   return cascade;
 }
 
-// True when `node` lays out as a non-replaced INLINE box. A flex/grid `parent`
-// blockifies it; a `display:contents` parent defers to its own parent.
+// The template whose content each hast `content` root is, recorded by `walk`.
+const contentOwners = new WeakMap();
+
+// The box `parent`'s children are laid out in: a `display:contents` parent
+// defers to its own parent, and a declarative shadow root's content to the
+// template's parent, the shadow host whose box its children render in.
+/** @param {any} parent @returns {any} */
+function layoutContainer(parent) {
+  let container = parent;
+  for (;;) {
+    const template = contentOwners.get(container);
+    if (template && !isInertTemplate(template))
+      container = parents.get(template);
+    else if (elementCascade(container).textOf("display") === "contents")
+      container = parents.get(container);
+    else return container;
+  }
+}
+
+// True when `node` lays out as a non-replaced INLINE box. A flex/grid layout
+// container (see {@link layoutContainer}) blockifies it.
 /** @param {any} node @param {any} [parent] @returns {boolean} */
 function isInlineBox(node, parent) {
   if (!INLINE_ELEMENTS.has(node.tagName)) return false;
@@ -1642,10 +1693,7 @@ function isInlineBox(node, parent) {
     BLOCKIFYING_VALUES.has(textOf("float"))
   )
     return false;
-  let container = parent;
-  while (elementCascade(container).textOf("display") === "contents")
-    container = parents.get(container);
-  return !elementCascade(container)
+  return !elementCascade(layoutContainer(parent))
     .textOf("display")
     .split(" ")
     .some((token) => ITEM_BLOCKIFYING_DISPLAYS.has(token));
@@ -1893,6 +1941,13 @@ function hasDataSrc(el) {
  * the `unist-util-visit` contract, which is what the call sites here are
  * written against.
  *
+ * One addition to that contract: an HTML `template`'s content (hast keeps it
+ * as a `content` root beside the element's empty `children`) is walked after
+ * its children, with the template as its parent, and `SKIP` leaves it
+ * unvisited too. Rendered or not (see {@link isInertTemplate}), that markup is
+ * in the source a model reads, so a scan that stopped at `children` would pass
+ * any hidden element, script or URL placed in it unseen.
+ *
  * Spelled out rather than imported because `unist-util-visit` allocates a fresh
  * ancestors array and a closure per node, and on a document that is one long
  * flat sibling list — 32k `<p>` elements per megabyte of ordinary HTML — that
@@ -1921,6 +1976,12 @@ function walk(tree, test, visitor, treeParent = undefined) {
         : undefined;
     if (result === EXIT) return;
     if (result === SKIP) continue;
+    if (node.type === "element" && node.content !== undefined) {
+      contentOwners.set(node.content, node);
+      nodes.push(node.content);
+      indices.push(undefined);
+      parents.push(node);
+    }
     const children = node.children;
     if (children === undefined) continue;
     for (let i = children.length - 1; i >= 0; i--) {
@@ -2163,7 +2224,7 @@ function scanFragmentTree(html, tree) {
   const warned = newWarned();
   /** @param {any} node */
   const countElement = (node) => {
-    if (REPORTED_TAGS.has(node.tagName)) countTag(warned, node.tagName);
+    if (isReportedElement(node)) countTag(warned, node.tagName);
     if (hasDataSrc(node)) warned.dataSrc += 1;
   };
   // Subtrees still to scan, each with its parent: the tree itself, then the
@@ -2485,7 +2546,11 @@ function scanInlineChildren(node, text, ranges, warned) {
           // A raw-text open tag starts an opaque region (a self-closing `/>`
           // does not apply to these in HTML — they always open).
           if (RAW_TEXT_ELEMENTS.has(el.tagName)) rawText = el.tagName;
-          if (REPORTED_TAGS.has(el.tagName)) countTag(warned, el.tagName);
+          // `el` is one tag parsed alone, so a `<template>` inside an inline
+          // `<svg>`/`<math>` reads as HTML here and is reported, where the
+          // source branch, which sees the namespace, does not: this errs toward
+          // reporting.
+          if (isReportedElement(el)) countTag(warned, el.tagName);
           if (hasDataSrc(el)) warned.dataSrc += 1;
         }
       }
@@ -3628,20 +3693,40 @@ function documentUrls(text, parseMd, parseHtml) {
   });
   /** @type {string[]} */
   const comments = [];
-  walk(parseHtml(text), null, (/** @type {any} */ node) => {
-    if (node.type === "comment") comments.push(node.value);
-    else if (node.type === "element") urls.push(...elementUrls(node));
-  });
+  // Nodes inside an inert template's content, where nothing loads, submits or
+  // redirects until a script clones it into the page.
+  const inert = new Set();
+  walk(
+    parseHtml(text),
+    null,
+    (/** @type {any} */ node, _index, /** @type {any} */ parent) => {
+      if (
+        inert.has(parent) ||
+        (parent?.content === node && isInertTemplate(parent))
+      )
+        inert.add(node);
+      if (node.type === "comment") comments.push(node.value);
+      else if (node.type === "element")
+        for (const url of elementUrls(node))
+          urls.push(
+            inert.has(node)
+              ? { ...url, autoFetched: false, context: "resource" }
+              : url,
+          );
+    },
+  );
   return { urls, comments };
 }
 
 // Every URL a Layer-3 detector reads: markdown links/images/definitions and
-// the URL attributes of every element, also inside comments. Both detectors
-// below consume this, so a node type is in scope for all of them or for none;
-// `parseMarkdown` memoizes its tree, so back-to-back detectors share the parse.
-// A comment is invisible on the page but not to a model reading the source:
-// its text is read one level deep with its markup openers defused, and what it
-// names is not fetched and has no off-origin rule.
+// the URL attributes of every element, also inside comments and template
+// content. Both detectors below consume this, so a node type is in scope for
+// all of them or for none; `parseMarkdown` memoizes its tree, so back-to-back
+// detectors share the parse. A comment is invisible on the page but not to a
+// model reading the source: its text is read one level deep with its markup
+// openers defused, and what it names is not fetched and has no off-origin
+// rule. An inert template's content gets the same two answers: nothing in it
+// is fetched, submitted or followed until a script clones it into the page.
 /** @param {string} text @returns {CollectedUrl[]} */
 function collectUrls(text) {
   const { urls, comments } = documentUrls(text, parseMarkdown, parseFragment);

package/types/claude-hooks/lib/knobs.d.mts

@@ -45,9 +45,9 @@ export function readKnob<K extends keyof Knobs>(name: K, env?: NodeJS.ProcessEnv
  * cannot reach (it runs its no-node arm on shell builtins alone).
  *
  * THE single source of truth for the closed set. The shell shims cannot import
- * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it by
- * `scripts/gen-fail-open-lib.mjs` and committed; the round trip is asserted in
- * plugin/test/fail-open-parity.test.mjs. Everything else that spells the set
+ * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it at build time
+ * by `scripts/gen-fail-open-lib.mjs`; plugin/test/fail-open-parity.test.mjs
+ * asserts the generated lib decides as failOpenEnabled(). Everything else that spells the set
  * out by hand is an implementation that must appear in the parity table in
  * tests/test_safe_launch.py.
  */