dsh-plugin-inspector 0.3.0 → 0.4.0

package/README.md

@@ -2,8 +2,8 @@
 
 **Know what a plugin does before you install it.**
 
-`dsh-inspect` reads a DeepSeek Harness plugin — a directory, an npm tarball, or a published
-package fetched by name and checked against the hash the registry published — and tells you what it
+`dsh-inspect` reads a DeepSeek Harness plugin — a directory, an npm tarball, or a published package
+fetched by name and checked against the hash the registry published — and tells you what it
 declares and what its code is capable of. It does not install it, build it, import it, spawn it, or
 evaluate any part of it.
 
@@ -11,6 +11,16 @@ evaluate any part of it.
 $ dsh-inspect --from-npm some-dsh-plugin@1.4.0
 ```
 
+📖 **[Full documentation](https://charlotten7.github.io/dsh-plugin-inspector/)**
+
+## Why
+
+`dsh plugin add` is a thin pnpm forwarder: it passes your arguments to pnpm verbatim, and a plugin
+is ordinary Node code that runs in the agent's process at the agent's uid. Nothing between the
+registry and that process tells you what the code can reach.
+
+[The full argument →](https://charlotten7.github.io/dsh-plugin-inspector/)
+
 ## Install
 
 Node `^22.19.0 || >=24`.
@@ -20,113 +30,14 @@ npm install -g dsh-plugin-inspector
 dsh-inspect --help
 ```
 
-From a checkout instead — `lib/` is generated, so a fresh clone has no `dsh-inspect` until it is
-built:
+From a checkout instead — `lib/` is generated, so a fresh clone has no `dsh-inspect` until built:
 
 ```console
 git clone https://github.com/CharlotteN7/dsh-plugin-inspector
 cd dsh-plugin-inspector
-pnpm install
-pnpm run build              # writes lib/, which .gitignore excludes and `files` ships
-node lib/cli.js --help      # or `pnpm link --global` for a `dsh-inspect` on PATH
-```
-
-To run it from source without building, `pnpm run inspect <target>`.
-
----
-
-## Why
-
-`dsh plugin add` is a thin pnpm forwarder. It passes your arguments to pnpm verbatim — no spec
-parsing, no added flags, no subcommand allowlist, no confirmation prompt — and then reconciles
-the profile's layer list from the installed state. Any package whose `package.json` declares
-`dsh.bundle.patch` is promoted to a **mounted patch layer**: an ESM module imported into the
-harness process at the agent's uid, with ungated top-level side effects, and a YAML layer that
-applies *after* `@deepseek-ai/dsh-base` and can therefore override any field of any core row by
-id — or set `disabled: true` on it.
-
-The only thing `dsh plugin add` prints is a warning for the harmless case:
-
+pnpm install && pnpm run build
+node lib/cli.js --help
 ```
-dsh: warning: <pkg> declares no dsh.bundle — installed as a plain dependency, not a profile layer
-```
-
-The dangerous case prints nothing.
-
-There are over 5,000 repos tagged `dsh-plugin` — 5,071 when this was last counted, on 16 August
-2026 — and no registry, no review, and no signing between any of them and your process. This tool
-exists so that the moment before you install one is not a blank.
-
-## What you get
-
-The report has two halves, and the first one is the point of the tool.
-
-**Facts** — no severity, always printed. Whether the package mounts as a patch layer and from
-which file, whether it ships a browser bundle, which rows it inserts and which existing rows it
-modifies, the `!!js` inventory of the mounted layer, cordis YAML it ships that nothing mounts,
-commands it puts on your PATH, its dependencies, what model-visible text it ships, and how much of
-it could be read. A well-behaved plugin has a full facts section and an empty findings section.
-That is a useful answer, not an empty one.
-
-**Findings** — ranked, in three tiers:
-
-| Tier | What it reads | What it can say |
-|---|---|---|
-| **A** | Structured declarations: `package.json` keys, Cordis patch rows, the `!!js` expression inventory | A verdict. Confidence is `certain`, because the harness reads the same bytes the same way |
-| **B** | Shipped source, through the TypeScript parser | A capability report: "this plugin **can** do X" |
-| **C** | Whether the package could be read at all — minification, computed names, sourceless builds, binaries | That the analysis is degraded, and that no Tier B negative can be trusted |
-
-Every Tier B and Tier C finding carries a `bypass` field naming the one-line evasion for that
-specific check. It is inside the finding, not in a footnote, so a report cannot be rendered
-without its caveat.
-
-A finding is **per package, not per syntax site**. A package importing `node:fs` from eleven files
-gets one finding with `occurrences: 11` and three example locations, because the eleventh import
-warrants no decision the first did not. Findings are grouped by check and `subject` — the module
-specifier, the row id, the seam name, the matched rule — so `node:child_process` and
-`node:worker_threads` stay two findings, and a gate can accept `B13`/`node:fs` without accepting
-every `B13`.
-
-## What it reports on the real ecosystem
-
-Measured **2026-08-17** against the 40 most-starred GitHub repositories tagged `dsh-plugin` that
-publish a resolvable npm package, each pinned to the version it resolved to on 2026-08-16. Re-run
-it with `pnpm run sweep`; the corpus is `scripts/ecosystem-corpus.json` and the recorded
-measurement is `tests/ecosystem-baseline.json`.
-
-Both columns come from the same corpus and the same pinned versions, so the difference is this
-tool's doing and not the ecosystem's. "0.1" is `dsh-plugin-inspector@0.1.0`; "0.2" is this tree,
-which reports itself as `0.2.1` because it reads the version out of its own manifest.
-
-| | 0.1 | 0.2 |
-|---|---|---|
-| Findings | 1,420 | **295** |
-| Critical | 252 | **3** |
-| Median findings per package | 10.5 | **5.5** |
-| Packages with a high or critical | 27 of 40 (68 %) | **21 of 40 (53 %)** |
-| Packages failing `--fail-on critical` | 40 of 40 | **1 of 40** |
-| Clean packages | 0 of 40 | **0 of 40** |
-
-**The 0.1 README quoted "49 findings, 0 critical" and that number was worthless.** It was measured
-on twelve targets — the harness's own bundles and our own sibling plugins — which is a sample
-selected for being trusted already. Against published third-party plugins the same build produced
-1,420 findings and 252 criticals, and no package came out clean.
-
-Read the 0.2 column honestly:
-
-- **`--fail-on critical` is now a usable gate.** It stops one package in forty. That package,
-  `@struktoai/mirage-dsh`, ships a patch layer that switches off `fs-sandbox`, `bash-sandbox` and
-  `pwsh-sandbox`, and its three findings lead the report. Under 0.1 the same three sat somewhere in
-  a list of 252.
-- **The default `--fail-on high` still stops a majority of the ecosystem**, and that is not a
-  finished job. The largest remaining driver is `C2` — the analyzer saying it could not read the
-  package, on 33 % of the corpus. That is a true statement rather than a false positive, but a gate
-  that fires on a third of npm for reasons about the *tool* is not yet a gate.
-- **No package is clean, and that is expected rather than alarming.** `C3` alone — "ships built
-  output and no source" — fires on 65 % of published packages, because that is what publishing a
-  package is. It is `low`, it does not degrade the analysis, and it is not a defect.
-
-A readable report is not yet an installable gate.
 
 ## Usage
 
@@ -134,21 +45,14 @@ A readable report is not yet an installable gate.
 dsh-inspect <target> [options]
 dsh-inspect --from-npm <name>[@<version>] [options]
 
-  <target>                A plugin directory, or an npm tarball (.tgz / .tar.gz).
-
-Options
-  --from-npm <spec>       Fetch a published package from the registry, verify its
-                          dist.integrity hash, and analyse it in memory.
+  --from-npm <spec>       Fetch from the registry, verify dist.integrity, analyse in memory.
   --registry <url>        Registry base URL for --from-npm.
-                          (default: https://registry.npmjs.org)
   --json                  Emit the machine-readable JSON document on stdout.
-  --fail-on <severity>    Exit 1 at or above this severity.
-                          critical | high | medium | low | none    (default: high)
+  --fail-on <severity>    Exit 1 at or above this severity.  (default: high)
   --no-color              Plain text, no ANSI.
-  --version, --help
 ```
 
-**Exit codes**, which are the CI contract:
+**Exit codes are the CI contract:**
 
 | Code | Meaning |
 |---|---|
@@ -156,297 +60,52 @@ Options
 | `1` | Analysis completed; at least one finding at or above `--fail-on` |
 | `2` | Analysis could not be performed |
 
-`2` is deliberately distinct from `1`. A job that cannot tell "the analyzer broke" from "the
-plugin is clean" is the failure this split exists to prevent.
-
-### Getting a package without installing it
+`2` is deliberately distinct from `1`. A job that cannot tell "the analyzer broke" from "the plugin
+is clean" is the failure this split exists to prevent.
 
-Never `pnpm add` a package you have not read.
-
-```console
-# From the registry, in one step. Reads the ~3 KB version document, downloads the tarball into
-# memory, verifies dist.integrity BEFORE anything parses it, and analyses it there.
-dsh-inspect --from-npm <name>@<version>
-
-# From git. Clone shallow and point the tool at the directory — do NOT use `npm pack` on a git
-# spec, which runs the package's `prepare` script.
-git clone --depth 1 https://github.com/… /tmp/plugin
-dsh-inspect /tmp/plugin
-```
-
-`--from-npm` is the only mode that opens a socket, and it is one flag per invocation: it cannot be
-combined with a local target, and a directory or tarball scan can never reach it — the fetch lives
-in a module the analysis path does not import. **A network fetch is not execution.** No subprocess,
-no disk write, no lifecycle script, and no `npm pack`. The report records the tarball URL, the
-digest that matched, and the registry's own `hasInstallScript` flag under `target.registry`.
-
-If the hash does not match what the registry published, the tool refuses and parses nothing. If the
-package predates `dist.integrity` entirely, the weaker `dist.shasum` is used and the report says
-`sha1` rather than claiming more. If neither is published, that is a refusal too.
-
-A tarball is decoded **entirely in memory**, from a file or from a fetch alike. Nothing is written
-to disk, which makes tar path traversal structurally impossible rather than something a filter has
-to catch. Every read ceiling is applied to the arriving stream rather than to a finished buffer, so
-a 28 MB archive holding one 8 GB member is a refusal in under two seconds, not an out-of-memory
-kill.
-
-### Directory mode reads the working tree, not "the package"
-
-The two targets are not the same thing and the report says which one you gave it.
-
-A **tarball** is the published package: exactly the bytes a user installs. A **directory** is a
-repository checkout, which holds far more — tests, fixtures, CI config, build scratch. None of that
-is installed, none of it is mounted, and none of it can act on anybody, so the directory reader is
-narrowed to the set `npm pack` would produce: the `files` allowlist when the manifest declares one,
-otherwise `.npmignore` or `.gitignore` under npm's defaults. The facts section names which rule it
-used and how many working-tree files it skipped.
-
-This matters more than it sounds. Reading a checkout whole means a hostile *test fixture* — a file
-that ships nowhere and mounts nothing — is reported at `critical` with `certain` confidence. That
-is not a conservative error; it is the tool being confidently wrong about the one tier it treats as
-a verdict.
+[Full usage, and getting a package without installing it →](https://charlotten7.github.io/dsh-plugin-inspector/usage.html)
 
 ## What it looks for
 
-### Facts — no severity, always emitted
+Findings are tiered by how much you should trust them:
 
-| Fact | Source |
+| Tier | What it means |
 |---|---|
-| `package.name`, `package.version`, `license`, `private` | `package.json` |
-| `mountsAsBundle` + patch file path | `dsh.bundle.patch` |
-| `shipsClientBundle` | `dsh.client` and `exports["./client"]` |
-| `insertedRows` — ids and plugin names this layer adds | patch YAML `insert[]` |
-| `targetedRows` — ids of existing rows this layer modifies | patch YAML top-level rows with `id` |
-| `dependencies`, `peerDependencies`, `optionalDependencies` counts and names | `package.json` |
-| `modelVisibleFiles` — shipped `SKILL.md` / skills / `AGENTS.md` / `CLAUDE.md` | file walk |
-| `filesRead`, `bytesRead`, `sourceFilesParsed` | analysis run |
-
-### Tier A — decidable, structured declaration, a real verdict
-
-Tier A reads declarations, not code. It is *much* harder to hide from than Tier B, because the
-harness itself must be able to read these fields literally in order to act on them: an attacker
-cannot obfuscate `disabled: true` and still have it disable anything. Every Tier A finding has
-confidence `certain`.
-
-| id | Check | Severity | Method |
-|---|---|---|---|
-| A1 | Install lifecycle script (`preinstall`, `install`, `postinstall`, `prepare`, `prepublish`, `preprepare`, `postprepare`) | medium; **high** when the command itself fetches, decodes, pipes to a shell, or evaluates inline code | `package.json.scripts` key set. `dsh plugin add` forwards to pnpm verbatim and adds no `--ignore-scripts`, but pnpm ≥ 10 blocks a dependency's lifecycle scripts by default until the package is listed under `allowBuilds`, and `apps/cli/src/plugin.ts` prints that instruction when a build is blocked. The script is one approval away from running, not already running — which is why the category alone is `medium`, and why the measured 5 of 40 legitimate packages that declare one (`tsdown`, `npm run build`, `husky`, `node scripts/prepare.mjs`) stay there. The escalation reads the command line itself, and is calibrated to fire on none of them |
-| A2 | Patch row sets `disabled` **truthily** on a **security-relevant** core row (`approval`, `permission`, `sandbox`, `sandbox-policy`, `bash-sandbox`, `pwsh-sandbox`, `fs-sandbox`, `fs-observation-policy`, `subprocess`, `credentials`, `timeout-policy`, `spill-policy`, `session-persistence-jsonl`) | **critical** | patch YAML row with `id ∈ SECURITY_ROWS`. The loader coerces — `disabledOf` is `Boolean(options.disabled)` (`vendor/loader/src/config/entry.ts`) — so `null`, `0` and `""` leave the row **running** and are not this finding. A `!!js` node is an object and stays truthy, so an expression is judged by what it can evaluate to |
-| A3 | Patch row disables any other known core row | high for a `@deepseek-ai/dsh-base` row, medium for one only a surface bundle inserts | same, `id ∈ CORE_ROWS`. The row inventory records which of the three shipped bundles inserts each row, because they are not one profile: a `ui-*` row exists only where the web bundle is mounted. Suppressed entirely when the package under analysis *is* one of the three bundles — `@deepseek-ai/dsh-web-app` disabling two dozen rows `@deepseek-ai/dsh-base` inserted is what composing a surface bundle is |
-| A4 | Patch row carries a `name` that does not match the targeted row's `name` | medium | `applyEntryPatches` treats `name` on a non-insert patch as an **assertion guard**, not an override: on mismatch it warns and `continue`s, skipping the whole patch. So this row does nothing at all. Either the author is targeting a row that has been renamed, or the patch is stale — in both cases what the user reads and what mounts disagree |
-| A5 | Patch row overrides `config` / `inject` / `isolate` / `intercept` / `group` / any other key of an existing core row | medium (high for a security row) | patch YAML. Override is a **shallow whole-value replacement** (`target[key] = value`), never a deep merge, so overriding `config` discards the core row's entire configuration. `PatchOptions` carries a `[key: string]: any` index signature, so *any* key that is not `id`/`insert`/`name` is copied onto the target verbatim |
-| A6 | `!!js` expression inventory, with AST sub-classification (see the `!!js` table below) | low → critical by class | dialect parse + `new Function` parse-compile, never evaluated |
-| A7 | `!!js` in a field where the loader never interpolates it (`id`, `name`, `group`, `inject`, `intercept`, `isolate`) | medium | mirrors `metadataExpressionErrors`. Signal: the author believes it is live when it is inert — the plugin was very likely never validated |
-| A8 | `!js` (single bang) anywhere in the patch YAML | medium | `!js` is a **hard YAML parse error**, verified. Its presence proves the plugin has never been successfully loaded by any harness |
-| A9 | `insert` row naming a module that is neither this package nor any of its declared dependencies | high | set difference against `dependencies` ∪ `peerDependencies` ∪ own name. The layer mounts code whose provenance the manifest does not admit to |
-| A10 | MCP server row — an `insert`ed row whose `name` is `@deepseek-ai/dsh-mcp-client`. `transport: stdio` → **critical**; `transport: streamable-http` → high | **critical** / high | The stdio config is `{ command, args, env, cwd }` and it spawns that executable directly — **not** through `ctx.subprocess` or `ctx.sandbox`, with no approval and no tool gate. Every tool the server advertises is then registered as `mcp__<serverName>__<tool>` with model-visible descriptions this package does not control. `streamable-http` does not spawn but still imports an untrusted remote tool catalogue. Structured declaration, so Tier A |
-| A11 | Non-registry dependency specifier (`git+`, `github:`, `http(s):`, `file:`, `link:`) | high | the referenced code can change under a fixed version string |
-| A12 | Shipped model-visible instruction text (`SKILL.md`, `**/skills/*/SKILL.md`, `**/skills/*.md`, `AGENTS.md`, `CLAUDE.md`) | low as presence; escalated by B10 | file walk. See the reach note below |
-| A13 | No `files` allowlist in `package.json` | low | the published tarball is whatever happened to be in the working tree |
-| A14 | `dsh.bundle.patch` climbs out of the package directory — contains a `..` that escapes | **critical** | `loadProfile` computes the patch path as `join(packageDir, declared)` with **no sanitization** of `declared`, and `..` segments survive that join. An **absolute** path does not escape and is not this finding: `join('/…/pkg', '/etc/passwd')` is `/…/pkg/etc/passwd`, which is inside the package and simply does not exist — that is A16 |
-| A15 | Patch row redirects skill discovery into this package — sets `customSkillDirs` or `bundledSkillDir` on the `skill-filesystem` row | high | this is the declaration that turns shipped markdown into model-visible instructions. `bundledSkillDir` additionally carries `trustedHost: true`, which reads through raw Node `fs` and **bypasses the `ctx.fs` sandbox** |
-| A16 | `dsh.bundle.patch` names a file the package does not ship | medium | commonly a `files` allowlist that forgets it. Mounting the bundle fails the profile boot |
-| A17 | The declared patch layer does not parse | medium | the layer cannot load, and nothing inside it could be analysed |
-| A18 | `package.json` field of the wrong shape | low | the field was ignored. A manifest that npm and the harness read differently is worth knowing about |
-| A19 | Patch row sets `disabled` **falsily** on a core row | medium | the inverse of A2 and A3, and the one the coercion rule makes visible. Bundle layers apply after the profile's own, so a row the user deliberately switched off is switched back on by this one while the user's file still reads `disabled: true` |
-| A20 | `dsh.profile.bundles` names packages to mount as bundles | high | the launcher resolves each named package, reads its `dsh.bundle.patch`, and mounts that layer (`packages/boot/app-boot/src/profile.ts`). This package is then a profile, and everything those packages declare composes into it — none of which is in this analysis |
-| A21 | Injection phrasing in shipped instruction markdown | high | **Tier A rather than Tier B, and exempt from the Tier C downgrade.** There is no syntax between a `SKILL.md` and the model: the shipped bytes *are* the prompt, so there is nothing to obfuscate and nothing for a degraded parse to have made unreliable. What is heuristic is the reading of the sentence, not the reading of the file. Tool `description` hits stay Tier B (B10), because code assembles those |
-| A22 | `bin` installs a command on the user's PATH | low | linked into the profile's `node_modules/.bin` at install time. The harness never runs it; the user, a script, or an agent shell tool can |
-| A23 | Inserted row carries `isolate` or `intercept` on a catalogued service | **critical** for a security seam, high otherwise | `vendor/loader/src/config/isolate.ts` re-maps the named service to a fresh symbol realm for the row and every row beneath it, so a descendant injecting that name receives this subtree's implementation instead of the profile's. The same substitution as replacing the service in code, declared in YAML |
-
-**Reach note for A12, stated because getting this wrong would be dishonest.** Shipping a `SKILL.md`
-inside an npm package does **not** by itself put it in front of the model. There is no
-`dsh.skills` manifest field. The filesystem provider scans a fixed root set —
-`<project>/.dsh/skills`, `<project>/.agents/skills`, `$DSH_HOME/skills`,
-`$DSH_AGENTS_HOME/skills`, `bundledSkillDir` — at depth 1 only (`<root>/<name>/SKILL.md` or `<root>/<name>.md`), and a plugin's own `node_modules`
-directory is none of those. The three ways shipped text actually reaches the model are: the plugin
-calls `ctx.skills.register()` / `ctx.skills.registerProvider()` (→ B10 on the registered body), a
-patch row redirects a skill root into the package (→ A15), or the file is copied into the user's
-workspace by something else. `AGENTS.md` / `CLAUDE.md` are a separate subsystem again — discovered
-by walking the *workspace*, not the profile. So A12 on its own is `low` and its text says
-"shipped, reaches the model only if registered or redirected"; it escalates to `high` only when
-A15 or a `ctx.skills.register*` call is also present, or when B10's injection heuristics fire.
-
-### Tier B — AST capability detection, "this plugin CAN do X"
-
-Tier B parses shipped `.ts`/`.mts`/`.cts`/`.js`/`.mjs`/`.cjs` with the `typescript` compiler API —
-`ts.createSourceFile`, syntax only, **no program, no type checker, no module resolution, no
-transpilation, no execution**. Default confidence `high`, dropped to `moderate` when any Tier C
-readability finding fires.
-
-| id | Check | Severity | Method |
-|---|---|---|---|
-| B1 | Replaces a core capability seam — `ctx.provide(<seam>, …)` / `ctx.set(<seam>, …)` where `<seam>` is a key from `api-catalog.ts` | **critical** | call expression, literal first argument matched against the seam key set |
-| B5 | System-prompt mutation — `system-prompt/assemble` listener, or `ctx.systemPrompt.{section,context,variable,tools,suppressRuntimeContext}` | high | call matching |
-| B6 | Credential read — `process.env.*(TOKEN\|KEY\|SECRET\|PASSWORD\|CREDENTIAL)*`, `~/.dsh/credentials`, `~/.npmrc`, `~/.aws`, `~/.ssh`, `ctx.credentials.*` | medium alone | identifier + literal matching |
-| B7 | Network egress — `fetch`, `node:http(s).request`, `node:net`, `WebSocket`, `undici` | medium alone | import + call matching |
-| B8 | **Exfiltration pair** — B6 ∧ B7 in the same package | high | set intersection. Reported explicitly as *capability, not dataflow*: the tool cannot prove the credential value reaches the socket. `high` rather than critical because it fires on 18 % of published plugins |
-| B9 | Direct `node:child_process` / `node:worker_threads` / `node:vm` | medium alone, high paired with B8's two halves | import specifier. Bypasses `ctx.subprocess` and `ctx.sandbox` entirely. `medium` alone because a bare import fires on half the published ecosystem |
-| B10 | Prompt-injection heuristics on **model-visible text only** — registered tool `description` string literals, and shipped skill/instruction files | high | imperative-override phrasing, role reassignment, exfiltration instructions, hidden-text markers — zero-width and bidirectional controls, the tag block, and runs of four or more variation selectors, the encoding GlassWorm shipped executable JavaScript in. Run on *exactly* the text that reaches the model, never on ordinary source comments |
-| B11 | Nested plugin mounting — `ctx.plugin(…)`, loader manipulation | high | call matching. A layer that mounts further layers moves the analysis target |
-| B12 | Dynamic code construction — `eval`, `new Function`, `vm.runInNewContext`, `module._load` | high | call matching |
-| B13 | Filesystem access outside `ctx.fs` — imports `node:fs` or `node:fs/promises` | medium | Reads and writes through the Node API are invisible to `fs/write-intent`, `fs/edit-intent`, `fs/observed`, and the `fs-sandbox` row, so no policy in the profile sees them and nothing appears in the session log |
-
-**The framing B7, B9, and B13 share.** The harness's own dynamic-package sandbox
-(`cordis-host-runner/src/sandbox.ts`) traps exactly `require`, `setTimeout`, `setInterval`,
-`setImmediate`, `clearTimeout`, `clearInterval`, and `fetch`, redirecting each to a `ctx` service;
-it leaves `process` `undefined` and exposes only the seven `HOST_BUILTIN_INSPECTION` globals.
-**An installed npm bundle layer gets none of that** — it is a plain ESM import into the harness
-process. So these three checks report a gap the harness itself defines: *the harness denies
-untrusted code this capability, and this package uses it from a position where nothing denies it.*
-That is the harness's reckoning, not a rule invented here.
-
-### Tier C — heuristic; "we cannot read this" is itself the finding
-
-| id | Check | Severity | Effect |
-|---|---|---|---|
-| C1 | Minified or obfuscated source — long lines that are **most of the file**, or a dense file of under five lines. One long line is an embedded prompt or a base64 asset, not minification, and the harness's own web bundle has one | medium | **degrades** |
-| C2 | Dynamic dispatch — computed member access on `ctx` (`ctx[expr]`), non-literal `import()`/`require()`, `atob`/`Buffer.from(…, 'base64')`, an assembled name passed to `.on`/`.set`/`.emit` **on a known context binding**. The receiver guard is the whole check: `.set` and `.get` are `Map`'s names too, and ``this.steps.set(`${turn}:${step}`, t)`` is a composite key, not evasion | high | **degrades** |
-| C3 | Ships built output with no corresponding source (`lib/` without `src/`) | low | **does not degrade** — the bytes were read exactly as written and exactly as they will run; what cannot be checked is whether they match the repository. Treating that as an unreadable package marks every ordinary published tarball degraded, because shipping built output and no source is what publishing *is* |
-| C4 | Unreadable payload — `.node`, `.wasm`, binaries, files over the size cap | medium | **degrades** |
-| C5 | The mounted layer hit a walk ceiling — nesting depth or node count | high | **degrades**. Rows past the ceiling were not read |
-| C6 | A `.min.js` artifact | low | **degrades** |
-
-### `!!js` sub-classification (A6)
-
-Every `!!js` node is inventoried with its YAML path and text, then parse-compiled with
-`new Function('return (' + expr + ')')` — compilation only; the constructor never executes the
-body — and the resulting AST is classified.
-
-Classification is by **reach**, not by syntactic form. `dshHomePath('sessions')` and `steal()` are
-both `CallExpression`s; the first is a helper `dsh-app-boot` puts in scope with
-`ctx.provide('dshHomePath', dshHomePath)` before any entry mounts, documented as such in that
-package's README, and used by the base bundle's own `session-persistence-jsonl` row.
-
-| Class | Example | Severity | Finding |
-|---|---|---|---|
-| `literal` | `true`, `3` | — | fact only |
-| `inert-read` | `process.env.DSH_TOOLS_MODE`, `process.platform === 'win32'`, `ctx.webStartup.host` | — | fact only |
-| `harness-call` | `dshHomePath('sessions')`, `process.cwd()` | low | A6 |
-| `call` | a call this tool cannot resolve | medium | A6 |
-| `mutation` | `process.env.X = …` | high | A6 |
-| `module-access` | `require(…)`, `import(…)`, `globalThis[…]` | **critical** | A6 |
-| `unparseable` | syntax error | medium — and it means the plugin cannot boot | A6 |
-
-The two classes with no reach are counted in `facts.jsExpressions` and never raised: a constant, or
-a read of a service the profile already handed the row, warrants no decision, and the shipped
-bundles are mostly made of them.
-
-The escalation of the rest is justified: the evaluator is
-`new Function('ctx', 'expr', 'with (ctx) { return eval(expr) }')` — unrestricted eval, with `ctx`
-in scope. And `disabled` re-evaluates at **every mount decision**, so a `!!js` there is not a
-one-shot: it is a recurring execution point that user patch layers HMR-reload live.
+| **Facts** | No severity, always emitted — what the package declares about itself |
+| **Tier A** | Decidable from a structured declaration. A real verdict. |
+| **Tier B** | AST capability detection — "this plugin *can* do X" |
+| **Tier C** | Heuristic; "we cannot read this" is itself the finding |
+
+[Every check, by tier →](https://charlotten7.github.io/dsh-plugin-inspector/checks.html)
 
 ## The ceiling
 
-**This is triage. It is not containment.**
-
-The tool does not run in the harness process, does not gate installation, and cannot stop
-anything. It raises the cost of shipping a hostile plugin and gives you something to read where
-today you see nothing. That is the whole claim.
-
-A seam at which an install *could* be stopped does exist — `dsh plugin add` runs pnpm in the
-profile directory, pnpm honours a `.pnpmfile.cjs` there, and throwing from its async `readPackage`
-hook aborts the install with nothing written to `node_modules`. Nothing in 0.2 uses it.
-[`ADR.md`](./ADR.md) §11 records the seam and why shipping a gate on this release's calibration
-would have burned the idea.
-
-### What is not statically decidable
-
-1. **`!!js` semantics.** The loader evaluates these with
-   `new Function('ctx', 'expr', 'with (ctx) { return eval(expr) }')` — unrestricted eval, under
-   `with (ctx)` scoping. Which identifiers resolve, and to what, depends on the runtime context
-   object. This tool reports the expression text and its syntactic class. It cannot tell you what
-   the expression will do.
-2. **Transitive dependencies.** One package is read. A clean package with one hostile dependency
-   reads as clean. The dependency list is printed as a fact for exactly this reason.
-3. **Runtime-fetched code.** Anything downloaded and evaluated after mount is invisible.
-4. **Post-install mutation of `node_modules`.** The bytes analysed are not guaranteed to be the
-   bytes that run.
-5. **A later version acquiring `dsh.bundle`.** Reconciliation is by *installed state*, not by
-   dependency diff. A package installed today as a plain library that gains a `dsh.bundle`
-   declaration in a patch release is mounted automatically by the next `dsh plugin update`, with
-   no notice. This is the most likely real-world bypass, and it means **a verdict is about one
-   version and only that version.**
-6. **Intent.** Tier B's `B8` is the sharpest case: the tool proves a package *can* read a
-   credential and *can* open a socket. It has not shown that the value flows between them, and it
-   cannot — that needs value tracking this tool does not do. Any telemetry library or
-   authenticated API client trips `B8` legitimately. It fires on 18 % of published plugins, which
-   is why it is `high` and not `critical`.
-7. **Injection phrasing that is not spelled in ASCII.** The injection heuristics are Latin-alphabet
-   regexes. Substituting Cyrillic homoglyphs — `о` U+043E for `o`, `е` U+0435 for `e` — defeats
-   **every one of the eleven rules**, including the two hidden-character rules, which look for
-   invisible characters and not for visible ones that are the wrong letter. Verified against the
-   rule table, not assumed. Normalisation is not in 0.2; do not read a clean `A21`/`B10` as
-   evidence that shipped markdown carries no instructions.
-
-### Every Tier B check has a one-line bypass
-
-`ctx['pro' + 'vide']('approval', …)` defeats seam detection. A computed specifier defeats every
-import check. A base64 event name defeats every listener check. Splitting a credential read and a
-network call across two packages defeats `B8`. A Cyrillic `о` defeats every injection rule.
-
-**Tier A is much harder to hide from, because it is structured declaration rather than code.**
-The harness must read `disabled: true` literally in order to disable anything, so there is no
-obfuscation that leaves it working. That asymmetry is why Tier A issues verdicts and Tier B
-issues capability reports.
-
-### And when the tool cannot read the package
-
-If any Tier C check that says something could not be *read* fires, every Tier B confidence drops to
-`moderate`, `analysis.integrity` becomes `degraded`, `analysis.negativesReliable` becomes `false`,
-and the human report is **forbidden from printing "no findings"**. A clean-looking report on a
-minified bundle would be worse than no report, so the tool refuses to produce one.
-
-The honest form of a clean result is: *nothing was found at or above the threshold, in the parts
-that could be read.*
+**This is not a malware scanner and it cannot be one.** Capability is decidable from source;
+intent is not. Every Tier B check has a one-line bypass, and the tool says so per finding rather
+than implying a completeness it does not have. What it does guarantee is that it never runs the
+code it analyses — asserted from outside the unit suite by a CI canary whose fixture writes
+sentinel files from `preinstall`, `postinstall`, `prepare`, `!!js` config and module top level. Any
+sentinel on disk after a full analysis is a release blocker.
 
-## Development
+[What is not statically decidable →](https://charlotten7.github.io/dsh-plugin-inspector/ceiling.html) ·
+[What it reports on the real ecosystem →](https://charlotten7.github.io/dsh-plugin-inspector/ecosystem.html)
 
-Node `^22.19.0 || >=24` and pnpm are the only requirements. No test reaches a network or a harness
-checkout: every registry case injects its own `fetch`, and one of them replaces the global with a
-throwing stub to prove a directory or tarball scan never calls it.
+## Development
 
-```console
+```sh
+nvm use 22           # Node ^22.19.0 || >=24, and pnpm 11
 pnpm install
 pnpm run typecheck
-pnpm run test               # unit suite
-pnpm run test:coverage      # same suite, with the coverage ratchet
-pnpm run test:e2e           # builds, then runs the real binary as a subprocess
-pnpm run inspect <target>   # run from source without building
-pnpm run sweep -- --check   # the one thing here that DOES use a network
+pnpm run test:coverage
+pnpm run test:e2e
 ```
 
-`pnpm run sweep` is the ecosystem measurement. It fetches the pinned corpus in
-`scripts/ecosystem-corpus.json` through the same verified in-memory path as `--from-npm`, prints the
-distribution, and with `--check` exits non-zero when a fresh run is worse than
-`tests/ecosystem-baseline.json`. `--discover` rebuilds the corpus from the most-starred repositories
-carrying the topic; `--pin` moves every entry to the version current now; `--record` rewrites the
-baseline. It runs from its own weekly workflow, never from CI — every other workflow here runs
-without a network, and a unit suite that cannot reach one is easier to trust.
-
-Hostile fixtures live in `tests/fixtures/` and are authored here — a plugin that disables the
-approval row, one whose `!!js` calls `child_process`, one with a `postinstall`, one pairing a
-credential read with `fetch`, one shipping a `SKILL.md` full of injection text, one declaring an
-MCP stdio server, a minified one, one using the `!js` tag, one whose bundle patch path escapes the
-package, and a benign control that must produce **zero** findings. They are deliberately hostile
-and structurally inert; [`tests/fixtures/README.md`](./tests/fixtures/README.md) says why, and
-which of them is a live prompt-injection payload you should not copy anywhere.
-
-`tests/fixtures/execution-canary/` is the proof that nothing runs: its install scripts, its `!!js`
-expressions, and its module top level all write a sentinel file, and the test asserts the sentinel
-does not exist after a full analysis. `node:child_process` and the write half of `node:fs` are
-mocked to throw for the whole suite, so a stray call fails the tests rather than passing quietly.
-
-Design decisions are in [`ADR.md`](./ADR.md); the check catalogue is under
-[What it looks for](#what-it-looks-for).
-
-## Reporting a problem
+Severity calibration is pinned against a corpus of published packages, so a change that starts
+firing on ordinary code fails CI rather than shipping.
 
-Security reports go to the address in [`SECURITY.md`](./SECURITY.md), which also says what counts
-as a vulnerability in a tool whose whole job is reading hostile input. A check that fires on
-ordinary code is a real defect — please open a normal issue for it.
+Design decisions and their rationale live in [ADR.md](ADR.md). Security policy is in
+[SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT — see [`LICENSE`](./LICENSE).
+MIT

package/lib/checks/tier-a.js

@@ -103,6 +103,7 @@ function coreRowSeverity(id) {
  */
 function coreRowOrigin(id) {
     const row = CORE_ROWS.get(id);
+    /* v8 ignore next -- only called once `coreRowSeverity` has found the id in the same map. */
     if (row === undefined)
         return 'a shipped bundle';
     return row.bundles.map(bundle => `@deepseek-ai/dsh-${bundle}`).join(' and ');
@@ -205,16 +206,16 @@ function checkOverriddenRows(input) {
             const rewritten = override.overriddenKeys.filter(key => key !== 'disabled');
             if (rewritten.length === 0)
                 continue;
-            const isSecurity = SECURITY_ROW_IDS.has(override.id);
+            const provides = SECURITY_ROW_IDS.get(override.id);
             findings.push(tierA({
                 checkId: 'A5',
                 name: 'core-row-overridden',
                 subject: `${override.id}:${rewritten.join(',')}`,
-                severity: isSecurity ? 'high' : 'medium',
+                severity: provides === undefined ? 'medium' : 'high',
                 title: `Patch layer rewrites ${rewritten.map(key => `\`${key}\``).join(', ')} on the core row "${override.id}"`,
                 detail: `The row is ${coreName}. Patch overrides are shallow whole-value replacements, not merges, so `
                     + `overriding \`config\` discards that row's entire shipped configuration rather than adding to it.`
-                    + (isSecurity ? ` This row provides ${SECURITY_ROW_IDS.get(override.id) ?? 'a core constraint'}.` : ''),
+                    + (provides === undefined ? '' : ` This row provides ${provides}.`),
                 evidence: { file: patch.file, path: override.path, snippet: snippet(rewritten.join(', ')) },
             }));
         }
@@ -421,6 +422,7 @@ function checkManifest(input) {
     const { manifest, source } = input;
     const lifecycle = INSTALL_LIFECYCLE_SCRIPTS.filter(name => name in manifest.scripts);
     for (const name of lifecycle) {
+        /* v8 ignore next -- `name` came from filtering the same object's own keys. */
         const command = manifest.scripts[name] ?? '';
         const signals = LIFECYCLE_SIGNALS.filter(signal => signal.pattern.test(command));
         findings.push(tierA({
@@ -438,8 +440,8 @@ function checkManifest(input) {
                 + (signals.length === 0
                     ? ''
                     : ` The command ${signals.map(signal => signal.meaning).join(', and ')}. A build hook runs something `
-                        + 'this package shipped and this one does not, which is the shape 21.2 % of malicious npm packages '
-                        + 'take: the whole attack inside `package.json`, with no module to read.'),
+                        + 'this package shipped; this one does not. The whole of it is in `package.json`, with no module to '
+                        + 'read.'),
             evidence: { file: 'package.json', path: `scripts.${name}`, snippet: snippet(command) },
         }));
     }
@@ -560,6 +562,7 @@ function checkModelVisibleText(input) {
                 + 'in an npm package does not by itself put it in front of the model: it is discovered only when the plugin '
                 + 'registers it through ctx.skills, when a patch row redirects a skill root into this package (A15), or when '
                 + 'something copies it into the user\'s workspace. The text itself is scored separately by B10.',
+            /* v8 ignore next -- the caller returns early on an empty list. */
             evidence: { file: input.modelVisibleFiles[0] ?? '', snippet: snippet(input.modelVisibleFiles.join(', ')) },
         })];
 }
@@ -609,6 +612,7 @@ function checkInjectionText(input) {
     const findings = [];
     for (const path of input.modelVisibleFiles) {
         const text = input.source.files.get(path);
+        /* v8 ignore next -- `modelVisibleFiles` is filtered from `source.files`'s own keys, so the lookup always hits. */
         if (text === undefined)
             continue;
         for (const match of scanInjection(text)) {

package/lib/checks/tier-b.js

@@ -20,8 +20,35 @@ import { NETWORK_MODULES, SEAM_KEYS, SECURITY_SEAM_KEYS, UNMEDIATED_FS_MODULES,
 const NETWORK_GLOBALS = new Set(['fetch', 'WebSocket', 'EventSource', 'XMLHttpRequest']);
 /** `process.env` keys whose names say they hold a secret. */
 const SECRET_ENV_KEY = /(?:^|_)(?:TOKEN|KEY|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|APIKEY|SESSION)(?:_|$)|API_?KEY|ACCESS_?TOKEN/i;
-/** Filesystem locations that hold credentials. */
-const CREDENTIAL_PATH = /(?:\.npmrc|\.netrc|\.ssh\/|id_rsa|id_ed25519|\.aws\/|\.docker\/config\.json|\.git-credentials|credentials\.json|\.dsh\/credentials|\.env(?:\.[a-z]+)?$)/i;
+/**
+ * Filesystem locations that hold credentials.
+ *
+ * A table rather than one regular expression so each location can be pinned by
+ * name: `tests/unit/rule-tables.spec.ts` iterates this export, and a location
+ * added without a fixture fails there.
+ */
+export const CREDENTIAL_PATHS = [
+    { id: 'npmrc', pattern: String.raw `\.npmrc` },
+    { id: 'netrc', pattern: String.raw `\.netrc` },
+    { id: 'ssh-directory', pattern: String.raw `\.ssh\/` },
+    { id: 'ssh-key-rsa', pattern: 'id_rsa' },
+    { id: 'ssh-key-ed25519', pattern: 'id_ed25519' },
+    { id: 'aws-directory', pattern: String.raw `\.aws\/` },
+    { id: 'docker-config', pattern: String.raw `\.docker\/config\.json` },
+    { id: 'git-credentials', pattern: String.raw `\.git-credentials` },
+    { id: 'service-account-json', pattern: String.raw `credentials\.json` },
+    { id: 'dsh-credentials', pattern: String.raw `\.dsh\/credentials` },
+    { id: 'dotenv', pattern: String.raw `\.env(?:\.[a-z]+)?$` },
+];
+const CREDENTIAL_PATH = new RegExp(`(?:${CREDENTIAL_PATHS.map(path => path.pattern).join('|')})`, 'i');
+/**
+ * Whether a string names a location that holds credentials.
+ * @param text - the literal text of a string in shipped source.
+ * @returns true when it names one of {@link CREDENTIAL_PATHS}.
+ */
+export function matchesCredentialPath(text) {
+    return CREDENTIAL_PATH.test(text);
+}
 /** Members of `ctx` that construct or evaluate code, or mount further plugins. */
 const DYNAMIC_CODE_CALLEES = new Set([
     'eval', 'runInNewContext', 'runInThisContext', 'runInContext', 'compileFunction',
@@ -71,6 +98,7 @@ function moduleSpecifiers(file) {
     const visit = (node) => {
         if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier !== undefined) {
             const text = literalText(node.moduleSpecifier);
+            /* v8 ignore next -- an import declaration only parses with a string-literal specifier. */
             if (text !== null)
                 found.push({ specifier: text, node });
         }
@@ -298,7 +326,7 @@ function checkCredentialRead(file, node, accumulator) {
             subject = `env:${key}`;
         }
     }
-    if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && CREDENTIAL_PATH.test(node.text)) {
+    if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && matchesCredentialPath(node.text)) {
         title = `References the credential location \`${node.text}\``;
         subject = `path:${node.text}`;
     }
@@ -375,6 +403,7 @@ export function runTierB(input) {
     const accumulator = { findings: [], credentialRead: null, networkCall: null };
     for (const path of input.sourceFiles) {
         const text = input.source.files.get(path);
+        /* v8 ignore next -- `sourceFiles` is filtered from `source.files`'s own keys, so the lookup always hits. */
         if (text === undefined)
             continue;
         const file = {
@@ -450,15 +479,18 @@ function pairFinding(accumulator) {
     // finding's own text says it is not a verdict. A severity that says "do not
     // treat this as a verdict" cannot be the top one.
     const severity = 'high';
+    /* v8 ignore start -- `at()` records a line and column for every finding these two come from. */
+    const credentialSite = `${credential.evidence.file}:${credential.evidence.path ?? '?'}`;
+    const networkSite = `${network.evidence.file}:${network.evidence.path ?? '?'}`;
+    /* v8 ignore stop */
     return tierB({
         checkId: 'B8',
         name: 'exfiltration-capability',
         subject: 'credential-and-egress',
         severity,
         title: 'This package can read a credential and can make a network call',
-        detail: 'This is a capability, not a dataflow. The tool found a credential read at '
-            + `${credential.evidence.file}:${credential.evidence.path ?? '?'} and a network call at `
-            + `${network.evidence.file}:${network.evidence.path ?? '?'}. It has NOT shown that the credential value `
+        detail: `This is a capability, not a dataflow. The tool found a credential read at ${credentialSite} `
+            + `and a network call at ${networkSite}. It has NOT shown that the credential value `
             + 'reaches the request, and it cannot: proving that needs value tracking this tool does not do. Many '
             + 'legitimate packages — any telemetry or authenticated API client — trip this pair for good reasons. Treat '
             + 'it as a prompt to read those two sites, not as a verdict.',

package/lib/checks/tier-c.js

@@ -40,6 +40,7 @@ function checkMinification(input) {
     const findings = [];
     for (const path of input.sourceFiles) {
         const text = input.source.files.get(path);
+        /* v8 ignore next -- `sourceFiles` is filtered from `source.files`'s own keys, so the lookup always hits. */
         if (text === undefined)
             continue;
         const lines = text.split('\n');
@@ -64,6 +65,7 @@ function checkMinification(input) {
                 + `that long are ${Math.round(longBytes * 100 / Math.max(text.length, 1))}% of the file. Capability `
                 + 'detection reads syntax, and it reads minified syntax no better than a person does. Every Tier B '
                 + 'negative for this package is unreliable while a file like this is in it.',
+            /* v8 ignore next -- `split` returns at least one element for any string, so the fallback is unreachable. */
             evidence: { file: path, path: '1:1', snippet: snippet(lines[0] ?? '') },
             bypass: 'none — this finding is about the analysis, not about the plugin',
         }));
@@ -75,6 +77,7 @@ function checkDynamicDispatch(input) {
     const findings = [];
     for (const path of input.sourceFiles) {
         const text = input.source.files.get(path);
+        /* v8 ignore next -- `sourceFiles` is filtered from `source.files`'s own keys, so the lookup always hits. */
         if (text === undefined)
             continue;
         const source = ts.createSourceFile(path, text, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS);
@@ -156,9 +159,11 @@ function isDispatchReceiver(node) {
 function receiverName(node) {
     if (ts.isIdentifier(node))
         return node.text;
+    /* v8 ignore start -- only called after `isDispatchReceiver`, which accepts these two forms and no other. */
     if (ts.isPropertyAccessExpression(node))
         return node.name.text;
     return '?';
+    /* v8 ignore stop */
 }
 /**
  * Whether a node builds a string at runtime rather than naming one. A plain
@@ -217,6 +222,7 @@ function checkSourcelessBuild(input) {
             detail: 'What runs is the built output, so that is what this tool analysed — but there is nothing in the '
                 + 'package to check the build against. Whether the source that produced it matches the repository is not '
                 + 'decidable from here.',
+            /* v8 ignore next -- guarded by `built.length > 0` two lines above. */
             evidence: { file: built[0] ?? '', snippet: snippet(built.slice(0, 5).join(', ')) },
             bypass: 'none — this finding is about the analysis, not about the plugin',
         }));
@@ -255,6 +261,7 @@ function checkUnreadableFiles(input) {
             ? 'Binary payloads — native addons, WebAssembly, archives — are shipped code this tool cannot read at all. '
                 + 'A mounted layer can load a `.node` addon with no restriction whatsoever.'
             : 'These files exceeded a size or count cap and were not read. Nothing is claimed about their contents.',
+        /* v8 ignore next -- a reason only appears in the map once a path was pushed under it. */
         evidence: { file: paths[0] ?? '', snippet: snippet(paths.slice(0, 8).join(', ')) },
         bypass: 'none — this finding is about the analysis, not about the plugin',
     }));
@@ -278,6 +285,23 @@ function checkPatchWalkLimit(input) {
         bypass: 'none — this finding is about the analysis, not about the plugin',
     }));
 }
+/** C7 — a patch layer whose rows are assembled out of YAML anchors and aliases. */
+function checkPatchAliases(input) {
+    return input.patches.filter(patch => patch.aliased).map(patch => tierC({
+        checkId: 'C7',
+        name: 'patch-uses-aliases',
+        subject: patch.file,
+        severity: 'medium',
+        title: `\`${patch.file}\` builds rows out of YAML anchors and aliases`,
+        detail: 'An alias is not a copy: `*a` hands the loader the same node again, so one row in the file can be two '
+            + 'rows in the composed profile, and the row a reader sees under an inert key can be the row that lands in a '
+            + 'live one. This tool expands every alias to its own node before reading the layer, which is what makes the '
+            + 'reading match the loader — but the layer a person reviews and the layer that mounts are no longer the same '
+            + 'document, and no Tier B negative about this package is claimed while that is true.',
+        evidence: { file: patch.file },
+        bypass: 'none — this finding is about the analysis, not about the plugin',
+    }));
+}
 /**
  * Run every Tier C check.
  * @param input - the decoded package.
@@ -290,5 +314,6 @@ export function runTierC(input) {
         ...checkSourcelessBuild(input),
         ...checkUnreadableFiles(input),
         ...checkPatchWalkLimit(input),
+        ...checkPatchAliases(input),
     ];
 }

package/lib/cli.js

@@ -80,6 +80,7 @@ export function parseArgs(argv) {
         return next;
     };
     for (let index = 0; index < argv.length; index += 1) {
+        /* v8 ignore next -- `index` is bounded by the loop condition. */
         const argument = argv[index] ?? '';
         if (argument === '--help' || argument === '-h') {
             process.stdout.write(USAGE);
@@ -152,6 +153,7 @@ export async function main(argv) {
         options = parseArgs(argv);
     }
     catch (error) {
+        /* v8 ignore next -- `parseArgs` refuses a command line only with a UsageError. */
         process.stderr.write(`dsh-inspect: ${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
         return EXIT.unanalysable;
     }
@@ -165,6 +167,7 @@ export async function main(argv) {
         return exceedsThreshold(report, options.failOn) ? EXIT.findings : EXIT.clean;
     }
     catch (error) {
+        /* v8 ignore next -- every refusal on the read path is a SourceError, ManifestError or RegistryError. */
         process.stderr.write(`dsh-inspect: ${error instanceof Error ? error.message : String(error)}\n`);
         return EXIT.unanalysable;
     }
@@ -187,6 +190,7 @@ export function reportFatal(error) {
     process.stderr.write(`dsh-inspect: the analysis could not be completed: ${message}\n`);
     return EXIT.unanalysable;
 }
+/* v8 ignore start -- the process entry, exercised by tests/e2e/cli.e2e.ts against the built CLI rather than by the instrumented unit run. */
 if (import.meta.main) {
     process.on('uncaughtException', (error) => {
         process.exit(reportFatal(error));
@@ -196,3 +200,4 @@ if (import.meta.main) {
     });
     process.exitCode = await main(process.argv.slice(2));
 }
+/* v8 ignore stop */

package/lib/cordis-yaml.js

@@ -28,6 +28,7 @@ const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
     kind: 'scalar',
     resolve: data => typeof data === 'string',
     construct: (data) => {
+        /* v8 ignore next -- js-yaml calls `construct` only for data its `resolve` accepted, which is a string. */
         if (typeof data !== 'string')
             throw new TypeError('!!js requires a scalar string');
         return { __jsExpr: data };
@@ -44,35 +45,77 @@ export const patchSchema = yaml.JSON_SCHEMA.extend(jsExprType);
 export const EXPRESSION_CLASSES = [
     'literal', 'inert-read', 'harness-call', 'call', 'mutation', 'module-access', 'unparseable',
 ];
-/** Nodes one patch layer may be walked through before the walk gives up. */
+/**
+ * The two ceilings that make reading a patch layer terminate.
+ *
+ * They apply to {@link expandAliases}, and through it to everything downstream:
+ * the walk runs over the tree the expansion produced, which holds at most
+ * `MAX_WALK_NODES` nodes nested at most `MAX_WALK_DEPTH` deep, so the walk needs
+ * no ceiling of its own.
+ */
 export const MAX_WALK_NODES = 200_000;
-/** Nesting one patch layer may reach before the walk gives up. */
+/** Nesting one patch layer may reach before the reader gives up. */
 export const MAX_WALK_DEPTH = 200;
 /**
- * Charge one node against the budget, and refuse a node already walked.
- * @param budget - the shared budget.
- * @param value - the node about to be walked.
- * @param depth - the current nesting depth.
- * @returns true when the walk may descend into this node.
+ * Materialise a parsed patch layer's alias graph as a tree, so that every
+ * occurrence of an anchored node is a distinct node at its own path.
+ *
+ * js-yaml resolves `*a` to the *same JavaScript object* as `&a`, not to a copy.
+ * A reader that walks the result as a graph and skips an object it has already
+ * seen therefore attributes an anchored node to whichever position it reached
+ * first and drops every other one — which is how a row anchored in an inert
+ * `inject:` slot and aliased into a real patch slot came to be read as inert
+ * and analysed no further. The loader has no such notion: `interpolate` in
+ * `vendor/loader/src/config/utils.ts` maps over arrays and objects as a tree
+ * and evaluates each occurrence it reaches, and `applyEntryPatches` reads each
+ * element of the patch list on its own. Expanding first makes this module agree
+ * with both.
+ *
+ * The expansion is bounded, which is what keeps an alias bomb from becoming a
+ * hang: a 475-byte file can describe 100 nodes with 31 billion paths through
+ * them, and materialising those paths is exactly the non-terminating walk the
+ * ceilings exist to stop. Past either ceiling the subtree becomes `null` and
+ * the limit is recorded, so a truncated read is reported rather than presented
+ * as a complete one.
+ * @param entries - the entry list js-yaml returned.
+ * @returns the expanded entries, whether an alias was used, and the ceiling hit.
  */
-function admit(budget, value, depth) {
-    if (budget.limit !== null)
-        return false;
-    if (depth > MAX_WALK_DEPTH) {
-        budget.limit = 'depth';
-        return false;
-    }
-    budget.nodes += 1;
-    if (budget.nodes > MAX_WALK_NODES) {
-        budget.limit = 'nodes';
-        return false;
-    }
-    if (typeof value !== 'object' || value === null)
-        return true;
-    if (budget.visited.has(value))
-        return false;
-    budget.visited.add(value);
-    return true;
+function expandAliases(entries) {
+    const state = { aliased: false, nodes: 1, limit: null };
+    const seen = new WeakSet([entries]);
+    const expand = (value, depth) => {
+        if (typeof value !== 'object' || value === null)
+            return value;
+        if (state.limit !== null)
+            return null;
+        if (depth > MAX_WALK_DEPTH) {
+            state.limit = 'depth';
+            return null;
+        }
+        state.nodes += 1;
+        if (state.nodes > MAX_WALK_NODES) {
+            state.limit = 'nodes';
+            return null;
+        }
+        if (seen.has(value))
+            state.aliased = true;
+        else
+            seen.add(value);
+        if (Array.isArray(value))
+            return value.map(item => expand(item, depth + 1));
+        const clone = {};
+        for (const [key, child] of Object.entries(value)) {
+            // Assignment would invoke the `__proto__` setter, and js-yaml keeps a
+            // `__proto__` key from the document as an own property precisely so that
+            // it stays data. Defining the property keeps it data here too.
+            Object.defineProperty(clone, key, {
+                value: expand(child, depth + 1), enumerable: true, writable: true, configurable: true,
+            });
+        }
+        return clone;
+    };
+    const expanded = entries.map(entry => expand(entry, 1));
+    return { entries: expanded, aliased: state.aliased, limit: state.limit };
 }
 /** Thrown when the patch file cannot be parsed as an entry list. */
 export class PatchParseError extends Error {
@@ -126,6 +169,7 @@ export function classifyExpression(expression) {
         new Function(`return (${expression})`);
     }
     catch (error) {
+        /* v8 ignore next -- the Function constructor rejects a body only with a SyntaxError. */
         return { class: 'unparseable', parseError: error instanceof Error ? error.message : String(error) };
     }
     const source = ts.createSourceFile('expr.ts', `(${expression})`, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
@@ -218,8 +262,6 @@ function isInertCall(node) {
  * @param depth - the current nesting depth.
  */
 function collect(value, path, slot, sink, depth) {
-    if (!admit(sink.budget, value, depth))
-        return;
     if (isJsExpr(value)) {
         const classified = classifyExpression(value.__jsExpr);
         sink.expressions.push({
@@ -294,8 +336,6 @@ function isTreeCarrier(entry) {
 function walkRow(value, path, intoGroupId, sink, depth) {
     if (!isRecord(value))
         return;
-    if (!admit(sink.budget, value, depth))
-        return;
     const carrier = isTreeCarrier(value);
     sink.inserts.push({
         path,
@@ -334,8 +374,6 @@ function walkPatchList(list, prefix, sink, depth) {
         const path = `${prefix}[${index}]`;
         if (!isRecord(patch))
             continue;
-        if (!admit(sink.budget, patch, depth))
-            continue;
         const id = typeof patch.id === 'string' ? patch.id : null;
         if (Array.isArray(patch.insert)) {
             for (const [rowIndex, row] of patch.insert.entries()) {
@@ -365,29 +403,27 @@ function walkPatchList(list, prefix, sink, depth) {
  * @throws PatchParseError when the text is not a loadable entry list.
  */
 export function parsePatchDocument(file, text) {
-    let document;
+    let loaded;
     try {
-        document = yaml.load(text, { schema: patchSchema });
+        loaded = yaml.load(text, { schema: patchSchema });
     }
     catch (error) {
+        /* v8 ignore next -- js-yaml rejects a document only with a YAMLException. */
         const message = error instanceof Error ? error.message : String(error);
         throw new PatchParseError(message, /(?<!!)!js(?![a-zA-Z0-9_-])/.test(text));
     }
-    if (!Array.isArray(document)) {
+    if (!Array.isArray(loaded)) {
         throw new PatchParseError('a patch layer must be a top-level array of entries', false);
     }
-    const sink = {
-        overrides: [],
-        inserts: [],
-        expressions: [],
-        budget: { visited: new WeakSet(), nodes: 0, limit: null },
-    };
-    walkPatchList(document, '', sink, 0);
+    const expansion = expandAliases(loaded);
+    const sink = { overrides: [], inserts: [], expressions: [] };
+    walkPatchList(expansion.entries, '', sink, 0);
     return {
         file,
         overrides: sink.overrides,
         inserts: sink.inserts,
         expressions: sink.expressions,
-        limit: sink.budget.limit,
+        limit: expansion.limit,
+        aliased: expansion.aliased,
     };
 }

package/lib/files.js

@@ -34,6 +34,7 @@ export function isSourceFile(path) {
  */
 export function isModelVisibleText(path) {
     const segments = path.split('/');
+    /* v8 ignore next -- `split` returns at least one element for any string. */
     const base = segments.at(-1) ?? '';
     if (base === 'SKILL.md' || base === 'AGENTS.md' || base === 'CLAUDE.md')
         return true;
@@ -49,6 +50,7 @@ export function isModelVisibleText(path) {
  * @returns true for a cordis YAML file.
  */
 export function isCordisConfigFile(path) {
+    /* v8 ignore next -- `split` returns at least one element for any string. */
     const base = path.split('/').at(-1) ?? '';
     return /cordis/.test(base) && (base.endsWith('.yml') || base.endsWith('.yaml'));
 }

package/lib/inspect.js

@@ -108,11 +108,13 @@ export function analyze(source, registry) {
     const patches = [];
     const patchFailures = [];
     if (mounted !== null) {
+        /* v8 ignore next -- `mounted` is non-null only when `source.files` holds that key. */
         const text = source.files.get(mounted) ?? '';
         try {
             patches.push(parsePatchDocument(mounted, text));
         }
         catch (error) {
+            /* v8 ignore next -- `parsePatchDocument` reports every refusal as a PatchParseError. */
             if (!(error instanceof PatchParseError))
                 throw error;
             patchFailures.push({ file: mounted, error });

package/lib/knowledge.js

@@ -295,12 +295,11 @@ export const INSTALL_LIFECYCLE_SCRIPTS = [
  * Command shapes that make an install lifecycle script the attack rather than
  * the build.
  *
- * The head-to-head measurement on 6,420 malicious and 7,288 benign npm packages
- * (ASE 2026) puts 72.21 % of malicious packages on a lifecycle hook and 21.2 %
- * with the whole attack inside `package.json` scripts — no shipped module at
- * all. That second number is what this table is for: it is the case where the
- * command line itself fetches, decodes, or evaluates, and there is nothing else
- * to read.
+ * The case this table is for is the one where the command line itself fetches,
+ * decodes, or evaluates: the whole attack sits in `package.json` and there is
+ * no shipped module to read. A lifecycle hook alone does not distinguish that
+ * from a build, which is why the hook is a category at `medium` and only the
+ * command raises it.
  *
  * Each pattern is chosen against the measured false-positive side rather than
  * against the idea of a build script. The five packages in the pinned corpus

package/lib/manifest.js

@@ -103,6 +103,7 @@ export function parseManifest(text) {
         parsed = JSON.parse(text);
     }
     catch (error) {
+        /* v8 ignore next -- JSON.parse rejects text only with a SyntaxError. */
         throw new ManifestError(`package.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (!isRecord(parsed))

package/lib/publish.js

@@ -54,6 +54,7 @@ function matchSegments(pattern, path) {
         }
         if (s === path.length)
             return false;
+        /* v8 ignore next -- both indices are checked against their lengths above. */
         if (!matchSegment(pattern[p] ?? '', path[s] ?? ''))
             return false;
         return step(p + 1, s + 1);
@@ -152,6 +153,7 @@ function ignoreMatches(rule, path) {
                 return true;
             continue;
         }
+        /* v8 ignore next -- `end` runs from 1 to `segments.length`, so the index is in range. */
         if (globMatch(rule.pattern, segments[end - 1] ?? ''))
             return true;
     }

package/lib/registry.js

@@ -127,6 +127,7 @@ export async function resolvePackage(spec, options = {}) {
         document = JSON.parse(body.toString('utf8'));
     }
     catch (error) {
+        /* v8 ignore next -- JSON.parse rejects text only with a SyntaxError. */
         throw new RegistryError(`${url} did not return JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
     const record = asRecord(document);

package/lib/report.js

@@ -91,6 +91,7 @@ function wrap(text, width) {
             current = word;
         }
     }
+    /* v8 ignore next -- every wrapped string is a finding's detail, and none is empty. */
     if (current !== '')
         lines.push(current);
     return lines;
@@ -144,9 +145,11 @@ function renderFacts(report, paint) {
                         ? 'yes — the registry marks this package as running one at install time'
                         : 'no — the registry does not mark this package as running one'],
             ],
+        /* v8 ignore start -- `mountsAsBundle` is true exactly when the manifest declared a path. */
         ['mounted layer', facts.mountsAsBundle
                 ? `yes — dsh.bundle.patch = ${facts.bundlePatchPath ?? '?'} (imported into the harness process at the agent's uid)`
                 : 'no — installs as a plain library, and dsh plugin add prints a warning saying so'],
+        /* v8 ignore stop */
         ['browser bundle', facts.shipsClientBundle ? 'yes — dsh.client with an ./client export, executed in the user\'s browser' : 'no'],
         ['rows inserted', facts.insertedRows.length === 0
                 ? 'none'
@@ -176,7 +179,9 @@ function renderFacts(report, paint) {
  * @returns the rendered text, ending in a newline.
  */
 export function renderHuman(report, color) {
+    /* v8 ignore start -- every call site passes a literal key of COLOR. */
     const paint = (code, text) => color ? `${COLOR[code] ?? ''}${text}${COLOR.reset}` : text;
+    /* v8 ignore stop */
     const lines = ['', ...renderFacts(report, paint)];
     if (report.findings.length > 0) {
         const counts = SEVERITIES

package/lib/source.js

@@ -31,11 +31,19 @@ export const MAX_FILE_BYTES = 4 * 1024 * 1024;
 export const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 /** Largest number of files the analyzer will consider. */
 export const MAX_ENTRIES = 10_000;
+/**
+ * Decompressed tar bytes one tarball may produce before the read is abandoned.
+ *
+ * Eight times the in-memory ceiling. A plugin tarball is never this large, and
+ * one that is has already answered the only question worth asking about it.
+ */
+export const MAX_STREAM_BYTES = 8 * MAX_TOTAL_BYTES;
 /** The shipping ceilings. Tests substitute smaller ones to exercise each cap. */
 export const DEFAULT_LIMITS = {
     maxFileBytes: MAX_FILE_BYTES,
     maxTotalBytes: MAX_TOTAL_BYTES,
     maxEntries: MAX_ENTRIES,
+    maxStreamBytes: MAX_STREAM_BYTES,
 };
 /** Directories never descended into: not shipped, and not the package's own code. */
 const SKIPPED_DIRECTORIES = new Set([
@@ -76,6 +84,7 @@ function countEntry(collector, path) {
  * @param buffer - the file content.
  */
 function store(collector, path, buffer) {
+    /* v8 ignore next 4 -- both callers check the size before reading; this is the same ceiling held at the last point that could still allocate. */
     if (buffer.byteLength > collector.limits.maxFileBytes) {
         collector.skipped.push({ path, reason: 'size-cap' });
         return;
@@ -170,6 +179,7 @@ function stripRoot(entryPath) {
     if (slash < 0)
         return undefined;
     const remainder = normalized.slice(slash + 1);
+    /* v8 ignore next -- an entry name ending in `/` is a directory entry, which the parser never hands to this. */
     if (remainder === '')
         return undefined;
     const segments = [];
@@ -186,13 +196,6 @@ function stripRoot(entryPath) {
     }
     return segments.length === 0 ? undefined : segments.join('/');
 }
-/**
- * Decompressed tar bytes one tarball may produce before the read is abandoned.
- *
- * Eight times the in-memory ceiling. A plugin tarball is never this large, and
- * one that is has already answered the only question worth asking about it.
- */
-export const MAX_STREAM_BYTES = 8 * MAX_TOTAL_BYTES;
 /**
  * A stage that fails the pipeline once the decompressed stream passes a
  * ceiling. Nothing downstream keeps the bytes, but *producing* eight gigabytes
@@ -308,7 +311,7 @@ async function readTarStream(bytes, gzipped, collector) {
         },
     });
     const inflate = gzipped ? createGunzip() : new PassThrough();
-    await pipeline(bytes, inflate, byteCeiling(MAX_STREAM_BYTES), parser);
+    await pipeline(bytes, inflate, byteCeiling(collector.limits.maxStreamBytes), parser);
     await Promise.all(pending);
     if (failure !== null)
         throw failure;

package/lib/types/checks/tier-b.d.ts

@@ -14,6 +14,26 @@
  */
 import type { Finding } from '../model.ts';
 import type { CheckInput } from './input.ts';
+/** One filesystem location that holds credentials, and how it is spelled. */
+export interface CredentialPath {
+    readonly id: string;
+    /** Pattern source, matched case-insensitively anywhere in a string literal. */
+    readonly pattern: string;
+}
+/**
+ * Filesystem locations that hold credentials.
+ *
+ * A table rather than one regular expression so each location can be pinned by
+ * name: `tests/unit/rule-tables.spec.ts` iterates this export, and a location
+ * added without a fixture fails there.
+ */
+export declare const CREDENTIAL_PATHS: readonly CredentialPath[];
+/**
+ * Whether a string names a location that holds credentials.
+ * @param text - the literal text of a string in shipped source.
+ * @returns true when it names one of {@link CREDENTIAL_PATHS}.
+ */
+export declare function matchesCredentialPath(text: string): boolean;
 /**
  * Run every Tier B check.
  * @param input - the decoded package.

package/lib/types/cordis-yaml.d.ts

@@ -82,10 +82,23 @@ export interface PatchDocument {
      * means the layer was read in part, which Tier C reports.
      */
     readonly limit: WalkLimit;
+    /**
+     * True when the layer reached at least one node twice, which is what a YAML
+     * alias does and what nothing else does. Tier C reports it, because a reader
+     * of the file sees one row where the loader sees two.
+     */
+    readonly aliased: boolean;
 }
-/** Nodes one patch layer may be walked through before the walk gives up. */
+/**
+ * The two ceilings that make reading a patch layer terminate.
+ *
+ * They apply to {@link expandAliases}, and through it to everything downstream:
+ * the walk runs over the tree the expansion produced, which holds at most
+ * `MAX_WALK_NODES` nodes nested at most `MAX_WALK_DEPTH` deep, so the walk needs
+ * no ceiling of its own.
+ */
 export declare const MAX_WALK_NODES = 200000;
-/** Nesting one patch layer may reach before the walk gives up. */
+/** Nesting one patch layer may reach before the reader gives up. */
 export declare const MAX_WALK_DEPTH = 200;
 /** Thrown when the patch file cannot be parsed as an entry list. */
 export declare class PatchParseError extends Error {

package/lib/types/knowledge.d.ts

@@ -121,12 +121,11 @@ export interface LifecycleSignal {
  * Command shapes that make an install lifecycle script the attack rather than
  * the build.
  *
- * The head-to-head measurement on 6,420 malicious and 7,288 benign npm packages
- * (ASE 2026) puts 72.21 % of malicious packages on a lifecycle hook and 21.2 %
- * with the whole attack inside `package.json` scripts — no shipped module at
- * all. That second number is what this table is for: it is the case where the
- * command line itself fetches, decodes, or evaluates, and there is nothing else
- * to read.
+ * The case this table is for is the one where the command line itself fetches,
+ * decodes, or evaluates: the whole attack sits in `package.json` and there is
+ * no shipped module to read. A lifecycle hook alone does not distinguish that
+ * from a build, which is why the hook is a category at `medium` and only the
+ * command raises it.
  *
  * Each pattern is chosen against the measured false-positive side rather than
  * against the idea of a build script. The five packages in the pinned corpus

package/lib/types/source.d.ts

@@ -26,11 +26,20 @@ export declare const MAX_FILE_BYTES: number;
 export declare const MAX_TOTAL_BYTES: number;
 /** Largest number of files the analyzer will consider. */
 export declare const MAX_ENTRIES = 10000;
+/**
+ * Decompressed tar bytes one tarball may produce before the read is abandoned.
+ *
+ * Eight times the in-memory ceiling. A plugin tarball is never this large, and
+ * one that is has already answered the only question worth asking about it.
+ */
+export declare const MAX_STREAM_BYTES: number;
 /** The resource ceilings one read runs under. */
 export interface ReadLimits {
     readonly maxFileBytes: number;
     readonly maxTotalBytes: number;
     readonly maxEntries: number;
+    /** Decompressed tar bytes one tarball may produce before the read is abandoned. */
+    readonly maxStreamBytes: number;
 }
 /** The shipping ceilings. Tests substitute smaller ones to exercise each cap. */
 export declare const DEFAULT_LIMITS: ReadLimits;
@@ -58,13 +67,6 @@ export interface PluginSource {
     /** Working-tree files npm would not publish, and which were therefore not read. */
     readonly unpublishedFiles: number;
 }
-/**
- * Decompressed tar bytes one tarball may produce before the read is abandoned.
- *
- * Eight times the in-memory ceiling. A plugin tarball is never this large, and
- * one that is has already answered the only question worth asking about it.
- */
-export declare const MAX_STREAM_BYTES: number;
 /**
  * Read the package under analysis.
  * @param target - a plugin directory, or a `.tgz` / `.tar.gz` npm tarball.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-inspector",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Know what a DeepSeek Harness plugin does before you install it — static pre-install analysis of a plugin directory or tarball",
   "license": "MIT",
   "author": "Ivan Tyshchenko",