@keithadler/frostjs 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # frostjs
 
+[![ci](https://github.com/keithadler/frostjs/actions/workflows/ci.yml/badge.svg)](https://github.com/keithadler/frostjs/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40keithadler%2Ffrostjs)](https://www.npmjs.com/package/@keithadler/frostjs)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 **The model wrote it. Did anyone decide it could do that?**
 
 frostjs is a deny-by-default capability gate for JavaScript. You write a
@@ -141,14 +145,15 @@ flags are in [SHOWCASE.md](SHOWCASE.md).
 
 ## Status
 
-Pre-alpha, feature complete against [REQUIREMENTS.md](REQUIREMENTS.md): all
-eight capability families, frost-dialect policies, scope analysis,
-baselines, changed-lines mode, json/sarif/github output, a GitHub Action,
-an ESLint plugin, a fingerprint registry for vendored code with SRI output,
-TypeScript, JSX and inline HTML. Run on Excalidraw (656 files, a
-TypeScript and React monorepo) it finishes in under a second and
-`frostjs init` writes an 18-line policy; every finding was checked by hand.
-Not yet published to npm.
+Published as [`@keithadler/frostjs`](https://www.npmjs.com/package/@keithadler/frostjs).
+Nine capability families across JavaScript, TypeScript, JSX and HTML
+markup, frost-dialect policies, scope analysis, taint analysis (source ->
+sink, one hop across functions), baselines, changed-lines mode,
+json/sarif/github output, a GitHub Action, an ESLint plugin, a fingerprint
+registry for vendored code with SRI output, TypeScript, JSX and HTML (inline scripts and attribute surfaces: `on*`
+handlers, `javascript:` URLs, remote `<script src>`). Run on Excalidraw (656 files, a TypeScript and React monorepo) it
+finishes in under a second and `frostjs init` writes an 18-line policy;
+every finding was checked by hand.
 
 ```
 $ cat frostjs.policy
@@ -185,6 +190,78 @@ code builds at runtime is called out in a hint rather than quietly widened
 to `may use the network`. For a large codebase with debt you would rather
 pay down than grant, use `--baseline` instead (below).
 
+## Auditing a dependency before you adopt it
+
+```bash
+npx frostjs audit node_modules/some-widget
+```
+
+No policy involved. It prints, alarming things first: **untrusted input
+reaching a dangerous sink** (a URL parameter, `document.cookie`, or a
+`postMessage` payload flowing into `eval`, `innerHTML`, `importScripts`, a
+redirect - real taint analysis, see below); files where code
+generation or script injection meets a network reach (a *remote code
+path*, the shape that found three.js's bundled remote eval); code
+generation from non-constant input, every host reached, hosts merely
+named in strings (a lead, not a finding), service workers, `postMessage`
+to any origin, and the capability counts. `--format json` for tooling.
+Run it on a pull request's new dependency, or on the one you already have
+and never read.
+
+See [docs/CAPABILITIES.md](docs/CAPABILITIES.md) for the full taxonomy with
+the policy phrase for each code, or run `frostjs capabilities`.
+
+## Taint: does untrusted input reach a dangerous sink?
+
+`frostjs audit` includes a bounded taint analysis. It answers the question
+capability detection cannot: not "can this code `eval`?" but "does a value
+from the URL, a cookie, or a `postMessage` actually flow into `eval`?".
+That is the difference between a capability and a vulnerability.
+
+```js
+const route = location.hash.slice(1);
+document.getElementById("app").innerHTML = "<div>" + route + "</div>";
+//  audit: t.js:2 location.hash -> innerHTML
+```
+
+The rule that keeps it honest: **taint survives only through operations
+that provably preserve it** - string methods, URL decoding, `JSON.parse`,
+template concatenation, member access. Any other function call breaks the
+chain, so `innerHTML = DOMPurify.sanitize(x)` is not flagged while
+`innerHTML = x` is.
+
+- **Sources**: `location.search` / `.hash` / `.href` / `.pathname`,
+  `document.URL` / `.cookie` / `.referrer` / `.baseURI`, `window.name`,
+  `URLSearchParams` reads, and a `window` `message` handler's `event.data`.
+- **Sinks**: `eval`, `Function`, `innerHTML` / `outerHTML` / `srcdoc`,
+  `insertAdjacentHTML`, `document.write`, `importScripts`, `import()`,
+  `setAttribute("on*"/"srcdoc", ...)`, and `location` / `window.open`
+  redirects.
+- **One hop across functions**: a tainted argument passed to a local
+  function whose parameter reaches a sink is flagged (`setHtml(x) { el.innerHTML = x }`
+  called with `location.hash`), reported `... (via setHtml())`. A parameter
+  only counts if it reaches the sink through provably-preserving operations,
+  so a helper that sanitizes its argument is not a sink.
+- **Limit, stated plainly**: flow is followed one function hop, not a whole
+  call graph (a parameter that reaches a sink through a second function is
+  not summarized), and DOM input values (`el.value`) are not modeled as
+  sources. It finds real flows; it does not claim to find all of them.
+
+Run over 21 MB of popular packages it reports zero (mature libraries
+sanitize); on real application code it lights up the flows a reviewer
+would flag by hand.
+
+Taint is a human report in `frostjs audit` and, with `--taint`, an
+enforced gate in `frostjs check`: each flow becomes a `taint.<sink>`
+finding that fails the build and appears in the json, sarif and github
+outputs, so it lands as a code-scanning alert on the pull request.
+`--changed-since`, `--baseline` and `// frostjs: ignore[taint]` all apply
+to taint findings, so it adopts on a legacy codebase the same way the
+capability gate does. It is off by default because it is best-effort;
+the capability gate stays deterministic. Put `forbid tainted flows` in
+`frostjs.policy` to turn the gate on for everyone without the flag, so the
+committed policy expresses the whole security posture in one place.
+
 ## Policy files
 
 A policy is a `frostjs.policy` file in frost's policy dialect: one rule per
@@ -201,6 +278,7 @@ may reach "<host>", ... [in "<glob>", ...] [until YYYY-MM-DD]
 forbid [using] <capability> [in "<glob>", ...]
 forbid reaching "<host>", ... [in "<glob>", ...]
 forbid everything else                             optional, readability only
+forbid tainted flows                               gate on taint (like --taint)
 ```
 
 `<capability>` is a phrase or a code. A family name grants the whole family.
@@ -219,8 +297,10 @@ forbid everything else                             optional, readability only
 | `html injection` | `dom-escape` |
 | `identity`, `fingerprinting` | `identity` |
 | `navigation` | `navigation` |
+
 | `globals` | `globals` |
 | `workers`, `service workers` | `worker` |
+| `device access`, `file access`, `usb`, `bluetooth`, `notifications` | `device` |
 | `everything` | `*` |
 
 Rules:
@@ -251,6 +331,7 @@ all, every capability is denied and a note says so.
 
 ```
 frostjs init [paths]     write a starter frostjs.policy granting what the code does today
+frostjs audit <paths>    what the code does, no policy needed: hosts, codegen, script injection, remote code paths
 frostjs <paths...>        discover and analyze .js/.mjs/.cjs/.jsx/.ts/.tsx/.mts/.cts and inline <script> in .html under paths
 frostjs csp               print the Content-Security-Policy header the policy implies
 frostjs summary           print a plain-English reading of the policy
@@ -265,6 +346,7 @@ frostjs --min-confidence <c>  lowest confidence that fails: certain, probable (d
 frostjs --baseline <file>     denials recorded in this file do not fail the build
 frostjs --update-baseline     write every current denial into the baseline and exit 0
 frostjs --changed-since <ref> fail only on uses in lines changed since the git ref
+frostjs --taint          also fail on untrusted input reaching a dangerous sink
 frostjs --format <f>      text (default), json, sarif, or github
 frostjs --version         print the version and exit
 frostjs --help            show usage
@@ -464,6 +546,8 @@ to a reviewer; suppression is for the one-off.
 | `network.eventsource` | `EventSource` |
 | `network.beacon` | `navigator.sendBeacon` |
 | `network.import` | dynamic `import()` of an absolute URL or an expression |
+| `network.importscripts` | `importScripts(url)` in a worker (loads and runs a script) |
+| `network.resource` | `el.src = "https://..."` or `setAttribute("src", ...)` naming another host (literal or folded const only) |
 | `codegen.eval` | `eval` |
 | `codegen.function` | `Function(...)`, `new Function(...)` |
 | `codegen.timer` | `setTimeout` / `setInterval` with string code |
@@ -471,6 +555,7 @@ to a reviewer; suppression is for the one-off.
 | `dom-escape.html` | assignment to `innerHTML` / `outerHTML` / `srcdoc`, `insertAdjacentHTML`, `createContextualFragment`, JSX `dangerouslySetInnerHTML` / `srcdoc` |
 | `dom-escape.script` | `document.createElement("script")`, JSX `<script>` |
 | `dom-escape.iframe` | `document.createElement("iframe")`, JSX `<iframe>` |
+| `dom-escape.handler` | `setAttribute("onclick" / "onerror" / ..., code)` (installs a handler from a string) |
 | `identity.device` | `navigator.userAgent`, `platform`, `vendor`, `plugins`, `hardwareConcurrency`, `deviceMemory`... |
 | `identity.geolocation` | `navigator.geolocation` |
 | `identity.media` | `navigator.mediaDevices`, `getUserMedia` |
@@ -481,12 +566,17 @@ to a reviewer; suppression is for the one-off.
 | `navigation.open` | `window.open` |
 | `navigation.history` | `history.pushState` / `replaceState` / `back` / `forward` / `go` |
 | `navigation.postmessage` | `postMessage` to `parent` / `top` / `opener` / `contentWindow`, or with a string origin |
+| `navigation.message-receive` | `window.addEventListener("message", ...)` whose handler reads `event.data` but never checks `event.origin` |
 | `globals.window` | assignment to `window.*` / `globalThis.*`, `Object.defineProperty(window, ...)` |
 | `globals.prototype` | assignment to a built-in or its prototype (`Array.prototype.x = `, `Error.prepareStackTrace = `), or `Object.defineProperty` / `assign` on one |
 | `worker.dedicated` | `new Worker(url)` |
 | `worker.shared` | `new SharedWorker(url)` |
 | `worker.service` | `navigator.serviceWorker.register(url)` |
 | `worker.worklet` | `CSS.paintWorklet.addModule(url)`, `audioWorklet.addModule(url)`... |
+| `device.filesystem` | `showOpenFilePicker` / `showSaveFilePicker` / `showDirectoryPicker` (read/write the user's files) |
+| `device.usb` / `device.bluetooth` / `device.serial` / `device.hid` / `device.midi` | `navigator.usb` etc. (hardware access) |
+| `device.wakelock` | `navigator.wakeLock` |
+| `device.notification` | `Notification` |
 
 Each is recognized bare, via `window` / `globalThis` / `self`, and via a
 computed member whose name is a string literal (`window["localStorage"]`),

package/dist/audit.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `frostjs audit`: what a body of code does, with no policy involved. The
+ * question a reviewer asks of a dependency before adopting it, or of a
+ * pull request that adds one: which hosts does it reach, does it generate
+ * code from non-constant input, does it inject scripts, does it register a
+ * service worker, and do any of those meet in one file.
+ *
+ * The shape that turned up ECSY's remote eval in three.js is the last one:
+ * code generation or script injection with a non-constant argument, plus a
+ * network reach, in the same file. It is reported as a "remote code path".
+ */
+import type { CapabilityUse } from "./extract/capability.js";
+import type { TaintFinding } from "./extract/taint.js";
+export interface FileAudit {
+    file: string;
+    /** Code generation whose input is not a constant. */
+    dynamicCodegen: CapabilityUse[];
+    scriptInjection: CapabilityUse[];
+    /** Hosts the engine resolved, excluding the document's own origin. */
+    hosts: string[];
+    /** Hosts named in URL string literals anywhere in the file. A lead, not a finding. */
+    literalHosts: string[];
+    unknownDestinations: number;
+    /** The file reads the page URL: a switch such a path can be flipped with. */
+    readsUrl: boolean;
+    /** Emscripten glue, whose code generation and wasm fetch are a known benign shape. */
+    emscripten: boolean;
+}
+export interface Audit {
+    files: number;
+    uses: number;
+    /** Distinct capability codes with counts. */
+    capabilities: Map<string, number>;
+    /** Resolved hosts with use counts, excluding the document's own origin. */
+    hosts: Map<string, number>;
+    /** Hosts named in string literals but not resolved as a destination. */
+    literalHosts: string[];
+    dynamicCodegen: CapabilityUse[];
+    scriptInjection: CapabilityUse[];
+    serviceWorkers: CapabilityUse[];
+    wildcardPostMessage: CapabilityUse[];
+    /** Files where code generation or script injection meets a network reach. */
+    remoteCodePaths: FileAudit[];
+    /** Untrusted input (URL, cookie, postMessage) reaching a dangerous sink. The most serious thing here. */
+    taintFlows: TaintFinding[];
+}
+/** A codegen use whose input is not a constant: `eval(data.script)`, not `Function("return this")`. */
+export declare function isDynamicCodegen(u: CapabilityUse): boolean;
+/** Hosts at the start of URL-shaped string literals, minus documentation hosts. Comments are not strings. */
+export declare function literalHostsIn(strings: readonly string[]): string[];
+/** Emscripten output: its code generation is embind and its fetch is its own .wasm. Reported, ranked below the rest. */
+export declare const isEmscripten: (text: string) => boolean;
+export interface FileSource {
+    /** The file's text, for the reads-the-URL lead. */
+    text: string;
+    /** Its string literals, for the hosts-named-in-strings lead. */
+    strings: readonly string[];
+}
+/**
+ * Audit uses grouped by file. `sources` supplies each file's text and
+ * string literals for the two leads; a file missing from it just loses
+ * those columns.
+ */
+export declare function audit(byFile: ReadonlyMap<string, readonly CapabilityUse[]>, sources: ReadonlyMap<string, FileSource>, taintFlows?: readonly TaintFinding[]): Audit;
+/** The audit as a report a person reads top to bottom: the alarming things first. */
+export declare function formatAudit(a: Audit): string;
+/** The audit as JSON. Maps become objects; uses keep their positions. */
+export declare function auditJson(a: Audit): string;
+/** Group uses by file, for audit(). */
+export declare function groupByFile(uses: readonly CapabilityUse[]): Map<string, CapabilityUse[]>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,sEAAsE;IACtE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sFAAsF;IACtF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,2EAA2E;IAC3E,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,wEAAwE;IACxE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,mBAAmB,EAAE,aAAa,EAAE,CAAC;IACrC,6EAA6E;IAC7E,eAAe,EAAE,SAAS,EAAE,CAAC;IAC7B,yGAAyG;IACzG,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAO1D;AAMD,6GAA6G;AAC7G,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOnE;AAKD,wHAAwH;AACxH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,OAA0E,CAAC;AAEvH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC,EACrD,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EACxC,UAAU,GAAE,SAAS,YAAY,EAAO,GACvC,KAAK,CAoDP;AAID,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAyD5C;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAsC1C;AAED,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAOxF"}

package/dist/audit.js

@@ -0,0 +1,202 @@
+import { SAME_ORIGIN } from "./extract/target.js";
+/** A codegen use whose input is not a constant: `eval(data.script)`, not `Function("return this")`. */
+export function isDynamicCodegen(u) {
+    if (!u.capability.startsWith("codegen.") || u.capability === "codegen.write")
+        return false;
+    const e = u.expression.replace(/\s+/g, " ");
+    if (/^(new )?Function\s*\(\s*["'`]return this["'`]\s*\)/.test(e))
+        return false;
+    if (/^eval$/.test(e))
+        return false; // a bare reference: typeof eval, feature detection
+    const args = e.replace(/^(new )?(eval|Function|setTimeout|setInterval)\s*\(/, "");
+    return !/^\s*["'`][^"'`]*["'`]\s*(,\s*["'`][^"'`]*["'`]\s*)*\)/.test(args);
+}
+/** Hosts that appear only in documentation links inside strings and comments. */
+const DOC_HOSTS = /(^|\.)(w3\.org|mozilla\.org|github\.com|githubusercontent\.com|example\.com|wikipedia\.org|stackoverflow\.com|ietf\.org|json-schema\.org|whatwg\.org|khronos\.org|ecma-international\.org|npmjs\.com)$/i;
+/** Hosts at the start of URL-shaped string literals, minus documentation hosts. Comments are not strings. */
+export function literalHostsIn(strings) {
+    const out = new Set();
+    for (const s of strings) {
+        const m = /^\s*https?:\/\/([a-z0-9.-]+\.[a-z]{2,})(?=[/:?#\s]|$)/i.exec(s);
+        if (m && !DOC_HOSTS.test(m[1]))
+            out.add(m[1].toLowerCase());
+    }
+    return [...out].sort();
+}
+const interesting = (t) => t !== null && t !== SAME_ORIGIN && t !== "data:" && t !== "blob:" && t !== "javascript:" && t !== "*";
+/** Emscripten output: its code generation is embind and its fetch is its own .wasm. Reported, ranked below the rest. */
+export const isEmscripten = (text) => /emscripten/i.test(text) && /wasmBinary|WebAssembly/.test(text);
+/**
+ * Audit uses grouped by file. `sources` supplies each file's text and
+ * string literals for the two leads; a file missing from it just loses
+ * those columns.
+ */
+export function audit(byFile, sources, taintFlows = []) {
+    const capabilities = new Map();
+    const hosts = new Map();
+    const literal = new Set();
+    const dynamicCodegen = [];
+    const scriptInjection = [];
+    const serviceWorkers = [];
+    const wildcardPostMessage = [];
+    const remoteCodePaths = [];
+    let uses = 0;
+    for (const [file, fileUses] of byFile) {
+        uses += fileUses.length;
+        const { text, strings } = sources.get(file) ?? { text: "", strings: [] };
+        const fa = {
+            file,
+            dynamicCodegen: fileUses.filter(isDynamicCodegen),
+            scriptInjection: fileUses.filter((u) => u.capability === "dom-escape.script"),
+            hosts: [...new Set(fileUses.map((u) => u.target).filter(interesting))].sort(),
+            literalHosts: literalHostsIn(strings),
+            unknownDestinations: fileUses.filter((u) => u.capability.startsWith("network.") && u.target === null).length,
+            readsUrl: /URLSearchParams|location\.search|location\.hash/.test(text),
+            emscripten: isEmscripten(text),
+        };
+        for (const u of fileUses) {
+            capabilities.set(u.capability, (capabilities.get(u.capability) ?? 0) + 1);
+            if (interesting(u.target))
+                hosts.set(u.target, (hosts.get(u.target) ?? 0) + 1);
+            if (u.capability === "worker.service")
+                serviceWorkers.push(u);
+            if (u.capability === "navigation.postmessage" && u.target === "*")
+                wildcardPostMessage.push(u);
+        }
+        for (const h of fa.literalHosts)
+            literal.add(h);
+        dynamicCodegen.push(...fa.dynamicCodegen);
+        scriptInjection.push(...fa.scriptInjection);
+        const remoteCode = fa.dynamicCodegen.length > 0 || fa.scriptInjection.length > 0;
+        const reaches = fa.hosts.length > 0 || fa.literalHosts.length > 0 || fa.unknownDestinations > 0;
+        if (remoteCode && reaches)
+            remoteCodePaths.push(fa);
+    }
+    remoteCodePaths.sort((x, y) => Number(x.emscripten) - Number(y.emscripten));
+    const literalHosts = [...literal].filter((h) => !hosts.has(h)).sort();
+    return {
+        files: byFile.size,
+        uses,
+        capabilities,
+        hosts,
+        literalHosts,
+        dynamicCodegen,
+        scriptInjection,
+        serviceWorkers,
+        wildcardPostMessage,
+        remoteCodePaths,
+        taintFlows: [...taintFlows],
+    };
+}
+const site = (u) => `${u.file}:${u.line}: ${u.expression.replace(/\s+/g, " ").slice(0, 90)}`;
+/** The audit as a report a person reads top to bottom: the alarming things first. */
+export function formatAudit(a) {
+    const lines = [];
+    const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+    lines.push(`${plural(a.files, "file")}, ${plural(a.uses, "capability use")}`);
+    lines.push("");
+    lines.push("untrusted input reaching a dangerous sink:");
+    if (a.taintFlows.length === 0)
+        lines.push("  none");
+    for (const t of a.taintFlows)
+        lines.push(`  ${t.file}:${t.line}: ${t.source} -> ${t.sink}: ${t.expression}`);
+    lines.push("");
+    lines.push("remote code paths (code generation or script injection meets a network reach in one file):");
+    if (a.remoteCodePaths.length === 0)
+        lines.push("  none");
+    for (const f of a.remoteCodePaths) {
+        const tags = [f.readsUrl ? "reads the page URL" : "", f.emscripten ? "Emscripten glue" : ""].filter(Boolean);
+        lines.push(`  ${f.file}${tags.length ? `   [${tags.join(", ")}]` : ""}`);
+        for (const u of [...f.dynamicCodegen, ...f.scriptInjection])
+            lines.push(`    ${site(u)}`);
+        const reach = [
+            ...f.hosts,
+            ...f.literalHosts.filter((h) => !f.hosts.includes(h)).map((h) => `${h} (named in a string)`),
+        ];
+        if (reach.length)
+            lines.push(`    reaches: ${reach.join(", ")}`);
+        if (f.unknownDestinations)
+            lines.push(`    and ${plural(f.unknownDestinations, "destination")} that cannot be read`);
+    }
+    lines.push("");
+    lines.push("code generation from non-constant input:");
+    const rcFiles = new Set(a.remoteCodePaths.map((f) => f.file));
+    const cg = a.dynamicCodegen.filter((u) => !rcFiles.has(u.file));
+    if (a.dynamicCodegen.length === 0)
+        lines.push("  none");
+    else if (cg.length === 0)
+        lines.push("  only in the remote code paths above");
+    for (const u of cg)
+        lines.push(`  ${site(u)}`);
+    lines.push("");
+    lines.push("hosts reached:");
+    if (a.hosts.size === 0)
+        lines.push("  none resolved");
+    for (const [h, n] of [...a.hosts].sort((x, y) => y[1] - x[1]))
+        lines.push(`  ${h} (${plural(n, "use")})`);
+    if (a.literalHosts.length)
+        lines.push(`  named in strings, not resolved as a destination: ${a.literalHosts.join(", ")}`);
+    lines.push("");
+    if (a.serviceWorkers.length) {
+        lines.push("service workers:");
+        for (const u of a.serviceWorkers)
+            lines.push(`  ${site(u)}`);
+        lines.push("");
+    }
+    if (a.wildcardPostMessage.length) {
+        lines.push("postMessage to any origin:");
+        for (const u of a.wildcardPostMessage)
+            lines.push(`  ${site(u)}`);
+        lines.push("");
+    }
+    lines.push("capabilities:");
+    if (a.capabilities.size === 0)
+        lines.push("  none");
+    for (const [c, n] of [...a.capabilities].sort((x, y) => x[0].localeCompare(y[0])))
+        lines.push(`  ${c} (${n})`);
+    return lines.join("\n") + "\n";
+}
+/** The audit as JSON. Maps become objects; uses keep their positions. */
+export function auditJson(a) {
+    const uses = (us) => us.map((u) => ({
+        file: u.file,
+        line: u.line,
+        column: u.column,
+        capability: u.capability,
+        target: u.target,
+        expression: u.expression,
+    }));
+    return (JSON.stringify({
+        files: a.files,
+        uses: a.uses,
+        capabilities: Object.fromEntries(a.capabilities),
+        taintFlows: a.taintFlows,
+        hosts: Object.fromEntries(a.hosts),
+        literalHosts: a.literalHosts,
+        dynamicCodegen: uses(a.dynamicCodegen),
+        scriptInjection: uses(a.scriptInjection),
+        serviceWorkers: uses(a.serviceWorkers),
+        wildcardPostMessage: uses(a.wildcardPostMessage),
+        remoteCodePaths: a.remoteCodePaths.map((f) => ({
+            file: f.file,
+            readsUrl: f.readsUrl,
+            emscripten: f.emscripten,
+            hosts: f.hosts,
+            literalHosts: f.literalHosts,
+            unknownDestinations: f.unknownDestinations,
+            dynamicCodegen: uses(f.dynamicCodegen),
+            scriptInjection: uses(f.scriptInjection),
+        })),
+    }, null, 2) + "\n");
+}
+/** Group uses by file, for audit(). */
+export function groupByFile(uses) {
+    const out = new Map();
+    for (const u of uses) {
+        if (!out.has(u.file))
+            out.set(u.file, []);
+        out.get(u.file).push(u);
+    }
+    return out;
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.d.ts

@@ -0,0 +1,22 @@
+/** One line per family: what the family is about. */
+export declare const FAMILY_SUMMARY: Readonly<Record<string, string>>;
+/** What triggers each member code. Keep terse; no trailing period needed. */
+export declare const CODE_TRIGGER: Readonly<Record<string, string>>;
+export interface CapabilityDoc {
+    family: string;
+    familySummary: string;
+    members: {
+        code: string;
+        trigger: string;
+        phrases: string[];
+    }[];
+}
+/** The taxonomy grouped by family, in family order. */
+export declare function capabilityDocs(): CapabilityDoc[];
+/** `frostjs capabilities` as a plain-text listing. */
+export declare function capabilitiesText(): string;
+/** `frostjs capabilities --format json`. */
+export declare function capabilitiesJson(): string;
+/** docs/CAPABILITIES.md, generated so it never drifts from the code. */
+export declare function capabilitiesMarkdown(): string;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AASA,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU3D,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiDzD,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACjE;AAUD,uDAAuD;AACvD,wBAAgB,cAAc,IAAI,aAAa,EAAE,CAUhD;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,IAAI,MAAM,CAazC;AAED,4CAA4C;AAC5C,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,IAAI,MAAM,CA2B7C"}

package/dist/capabilities.js

@@ -0,0 +1,140 @@
+/**
+ * The canonical capability taxonomy with human descriptions. This is the
+ * single source of truth: the README table, the `frostjs capabilities`
+ * command and docs/CAPABILITIES.md are all generated from it, and a test
+ * fails if it drifts from the codes the extractor actually emits
+ * (MEMBER_CODES) or from the families (FAMILIES).
+ */
+import { FAMILIES, MEMBER_CODES, CAPABILITY_PHRASES } from "./policy/vocabulary.js";
+/** One line per family: what the family is about. */
+export const FAMILY_SUMMARY = {
+    storage: "Persisting data in the browser.",
+    network: "Reaching another host, or loading code from one.",
+    codegen: "Turning a string into running code.",
+    "dom-escape": "Turning a string into live markup, or creating an element that runs code.",
+    identity: "Reading who or where the user is.",
+    navigation: "Moving the page, or talking to another window.",
+    globals: "Mutating shared global state that every script sees.",
+    worker: "Running code off the main thread, or intercepting requests.",
+    device: "Reaching the machine: hardware, files, notifications.",
+};
+/** What triggers each member code. Keep terse; no trailing period needed. */
+export const CODE_TRIGGER = {
+    "storage.local": "localStorage",
+    "storage.session": "sessionStorage",
+    "storage.indexeddb": "indexedDB",
+    "storage.cache": "caches (the Cache API)",
+    "storage.cookie": "document.cookie",
+    "storage.navigator": "navigator.storage",
+    "network.fetch": "fetch(url)",
+    "network.xhr": "new XMLHttpRequest()",
+    "network.websocket": "new WebSocket(url)",
+    "network.eventsource": "new EventSource(url)",
+    "network.beacon": "navigator.sendBeacon(url)",
+    "network.import": "dynamic import() of an absolute URL or an unresolvable expression",
+    "network.importscripts": "importScripts(url) in a worker (loads and runs a script)",
+    "network.resource": 'el.src = "https://..." to another host',
+    "codegen.eval": "eval(...)",
+    "codegen.function": "Function(...) or new Function(...)",
+    "codegen.timer": "setTimeout / setInterval with a string first argument",
+    "codegen.write": "document.write / document.writeln",
+    "dom-escape.html": "assignment to innerHTML / outerHTML / srcdoc, insertAdjacentHTML, createContextualFragment",
+    "dom-escape.script": 'document.createElement("script"), JSX <script>',
+    "dom-escape.iframe": 'document.createElement("iframe"), JSX <iframe>',
+    "dom-escape.handler": 'setAttribute("onclick" / "onerror" / ..., code) (a handler from a string)',
+    "identity.device": "navigator.userAgent, platform, plugins, hardwareConcurrency, deviceMemory...",
+    "identity.geolocation": "navigator.geolocation",
+    "identity.media": "navigator.mediaDevices, getUserMedia",
+    "identity.clipboard": 'navigator.clipboard, document.execCommand("copy" / "paste")',
+    "identity.credentials": "navigator.credentials",
+    "identity.permissions": "navigator.permissions",
+    "navigation.location": "assignment to location / location.href, location.assign / replace / reload",
+    "navigation.open": "window.open",
+    "navigation.history": "history.pushState / replaceState / back / forward / go",
+    "navigation.postmessage": "postMessage to parent / top / opener / contentWindow, or with a string origin",
+    "navigation.message-receive": 'window.addEventListener("message", ...) whose handler reads event.data but never checks event.origin',
+    "globals.window": "assignment to window.* / globalThis.*, Object.defineProperty(window, ...)",
+    "globals.prototype": "assignment to a built-in or its prototype, or Object.defineProperty / assign on one",
+    "worker.dedicated": "new Worker(url)",
+    "worker.shared": "new SharedWorker(url)",
+    "worker.service": "navigator.serviceWorker.register(url)",
+    "worker.worklet": "CSS.paintWorklet.addModule(url), audioWorklet.addModule(url)...",
+    "device.filesystem": "showOpenFilePicker / showSaveFilePicker / showDirectoryPicker (read or write the user's files)",
+    "device.usb": "navigator.usb (WebUSB)",
+    "device.bluetooth": "navigator.bluetooth (Web Bluetooth)",
+    "device.serial": "navigator.serial (Web Serial)",
+    "device.hid": "navigator.hid (WebHID)",
+    "device.midi": "navigator.requestMIDIAccess (Web MIDI)",
+    "device.wakelock": "navigator.wakeLock",
+    "device.notification": "Notification",
+};
+/** The phrases a policy author may write for a code (from the vocabulary), sorted shortest first. */
+function phrasesFor(code) {
+    return [...CAPABILITY_PHRASES.entries()]
+        .filter(([, c]) => c === code)
+        .map(([phrase]) => phrase)
+        .sort((a, b) => a.length - b.length);
+}
+/** The taxonomy grouped by family, in family order. */
+export function capabilityDocs() {
+    return FAMILIES.map((family) => ({
+        family,
+        familySummary: FAMILY_SUMMARY[family] ?? "",
+        members: MEMBER_CODES.filter((c) => c === family || c.startsWith(`${family}.`)).map((code) => ({
+            code,
+            trigger: CODE_TRIGGER[code] ?? "",
+            phrases: phrasesFor(code),
+        })),
+    }));
+}
+/** `frostjs capabilities` as a plain-text listing. */
+export function capabilitiesText() {
+    const lines = [];
+    for (const fam of capabilityDocs()) {
+        const famPhrases = phrasesFor(fam.family);
+        lines.push(`${fam.family}${famPhrases.length ? ` (${famPhrases.join(", ")})` : ""} - ${fam.familySummary}`);
+        for (const m of fam.members)
+            lines.push(`  ${m.code.padEnd(26)} ${m.trigger}`);
+        lines.push("");
+    }
+    lines.push("A policy grants a family or a code:");
+    lines.push("  may use storage            grants every storage.* member");
+    lines.push("  may use local storage      grants storage.local");
+    lines.push('  may reach "api.example.com"  grants the network family to that host');
+    return lines.join("\n") + "\n";
+}
+/** `frostjs capabilities --format json`. */
+export function capabilitiesJson() {
+    return JSON.stringify({ families: capabilityDocs() }, null, 2) + "\n";
+}
+/** docs/CAPABILITIES.md, generated so it never drifts from the code. */
+export function capabilitiesMarkdown() {
+    const lines = [
+        "# Capabilities",
+        "",
+        "The full taxonomy frostjs recognizes. This file is generated from",
+        "`src/capabilities.ts` by `frostjs capabilities --format md`; a test fails",
+        "if it drifts. A policy grants a whole family (`may use storage`) or a",
+        'single code (`may use local storage`); `may reach "<host>"` grants the',
+        "network family to named hosts.",
+        "",
+    ];
+    for (const fam of capabilityDocs()) {
+        const famPhrases = phrasesFor(fam.family);
+        lines.push(`## ${fam.family}`);
+        lines.push("");
+        lines.push(fam.familySummary);
+        if (famPhrases.length)
+            lines.push(`\nPolicy phrase: ${famPhrases.map((p) => `\`${p}\``).join(", ")}.`);
+        lines.push("");
+        lines.push("| code | triggered by | policy phrase |");
+        lines.push("| --- | --- | --- |");
+        for (const m of fam.members) {
+            const phrase = m.phrases.length ? m.phrases.map((p) => `\`${p}\``).join(", ") : `\`${m.code}\``;
+            lines.push(`| \`${m.code}\` | ${m.trigger} | ${phrase} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=capabilities.js.map