dsh-plugin-inspector 0.2.0 → 0.2.1

package/README.md

@@ -126,7 +126,7 @@ Read the 0.2 column honestly:
   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.
 
-The gap between "readable report" and "installable gate" is what 0.3 is for.
+A readable report is not yet an installable gate.
 
 ## Usage
 
@@ -208,30 +208,137 @@ a verdict.
 
 ## What it looks for
 
-Full catalogue with detection methods in [`PLAN.md`](./PLAN.md) §6. The short version:
-
-**Tier A** — install lifecycle scripts; a patch row disabling, re-enabling, or rewriting a core row
-(with `approval`, `permission`, `sandbox`, `sandbox-policy`, `fs-sandbox`, `fs-observation-policy`,
-`subprocess`, `credentials` and friends called out by name); the `!!js` inventory, classified by
-what each expression reaches; `!!js` in a field the loader never interpolates; `!js`, which is a
-hard parse error and proves the layer has never loaded anywhere; inserted rows naming modules the
-manifest does not declare; rows that re-map a service for their subtree with `isolate` or
-`intercept`; MCP server rows; `dsh.bundle.patch` paths that climb out of the package;
-skill-root redirection; a `dsh.profile.bundles` list, which makes the package a profile that mounts
-other packages; commands installed on your PATH; non-registry dependency specifiers; and injection
-phrasing in shipped instruction markdown, which is Tier A because the shipped bytes *are* the
-prompt.
-
-**Tier B** — capability-seam replacement via `ctx.provide` / `ctx.set`; system-prompt mutation;
-credential reads; network egress; the two of those together; `node:child_process`,
-`node:worker_threads`, `node:vm`; filesystem access outside `ctx.fs`; code built at runtime **and
-called**; nested plugin mounting; injection phrasing in registered tool `description` strings,
-which code assembles and which is therefore evadable.
-
-**Tier C** — minified source; computed member access, specifiers, and names; binaries and files
-over the read caps; a patch layer whose structure hit a walk ceiling; and build output with no
-source beside it, which is the one Tier C finding that does *not* degrade the analysis — the bytes
-were read exactly as they will run, and only their provenance is unverifiable.
+### Facts — no severity, always emitted
+
+| Fact | Source |
+|---|---|
+| `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 | `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 |
+| 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 |
+| B2 | Auto-approves — a listener on `approval/request` that returns an approving verdict with no user interaction | **critical** | listener body return analysis |
+| B3 | `tools/pre-execute` listener returning `allow` | high | same |
+| B4 | Waterfall listener that never references `next` | high | The waterfall set is exactly 13 events: `agent/pre-step`, `agent/request`, `agent/request-error`, `approval/request`, `fs/edit-intent`, `fs/write-intent`, `llm/stream`, `session-telemetry/record`, `system-prompt/assemble`, `tools/code-dispatch-log`, `tools/execute`, `tools/post-execute`, `tools/pre-execute`. Per the harness's own rule, returning without calling `next()` short-circuits the chain **including the built-in behavior**, silently disabling the default for everyone downstream. Note there is **no** `fs/read-intent` — the intent family is write and edit only |
+| 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. 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.
 
 ## The ceiling
 
@@ -334,8 +441,8 @@ expressions, and its module top level all write a sentinel file, and the test as
 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 scope, catalogue, and phasing are in
-[`PLAN.md`](./PLAN.md).
+Design decisions are in [`ADR.md`](./ADR.md); the check catalogue is under
+[What it looks for](#what-it-looks-for).
 
 ## Reporting a problem
 

package/lib/files.js

@@ -23,7 +23,7 @@ export function isSourceFile(path) {
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *
- * The reach is conditional and PLAN.md §6.1 says so: a `SKILL.md` inside an npm
+ * The reach is conditional: a `SKILL.md` inside an npm
  * package is only discovered when the plugin registers it through
  * `ctx.skills`, when a patch row redirects a skill root into the package, or
  * when something copies it into the user's workspace. This predicate answers

package/lib/types/files.d.ts

@@ -13,7 +13,7 @@ export declare function isSourceFile(path: string): boolean;
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *
- * The reach is conditional and PLAN.md §6.1 says so: a `SKILL.md` inside an npm
+ * The reach is conditional: a `SKILL.md` inside an npm
  * package is only discovered when the plugin registers it through
  * `ctx.skills`, when a patch row redirects a skill root into the package, or
  * when something copies it into the user's workspace. This predicate answers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-inspector",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",