dsh-plugin-guide 0.4.6 → 0.5.1

package/SKILL.md

@@ -56,3 +56,9 @@ It defines the three layers and the difference between a check and advice.
 This project is non-official and has no certification, accreditation, security
 audit, or market gate. It does not score or rank plugins. When in doubt, link to
 the source document and state what was not run.
+
+For plugin security — capabilities, credentials, egress, install scripts, and
+supply chain — read `docs/security.md`. The security scope is static and shipped
+in `dsh-standards` 1.6.0+; `DSC-15`/`DSC-16`/`DSC-17` can block only under
+`--scope security`, `DSC-21` is WARN-only, and runtime security needs a sandbox,
+not a checker.

package/docs/boost.md

@@ -90,6 +90,20 @@ pitfalls”), record it as a WARN or a note. Do not invent a number.
   loader/context-level fixtures.
 - BOOST is not a market gate and must not become a certification.
 
+<a id="security-boundary"></a>
+## Security boundary
+
+BOOST measures Cordis practice, not security. A reversible effect or a seam is
+good engineering, and it reduces blast radius, but it is not a sandbox: the
+plugin still shares the host process, the user, and the network. The static
+`DSC-15`–`DSC-22` checks run in a separate `--scope security` (1.6.0+); outside
+it they are capped to WARN in the separate `security` block. `DSC-15`/`16`/`17`
+can block only under that scope, and `DSC-21` is WARN-only. They never change a
+BOOST result and none of them proves a plugin safe. Runtime questions — actual
+egress, file reads, prompt corruption — require a sandbox with a network policy
+and capture, not an evidence card. Keep the security claim `not-run` instead of
+borrowing BOOST evidence for it. See [security.md](security.md#scope).
+
 ## Run the audit
 
 ```sh

package/docs/entry.md

@@ -160,6 +160,10 @@ pass.
   fs write, or subprocess spawn. Do that work in `apply()` and clean up with
   `ctx.effect()`.
 - README says how to install and what it needs.
+- No `preinstall`/`install`/`postinstall`/`prepare` script in the published
+  package; if a build is needed, run it in CI, not on the user's machine.
+- No `eval`/`new Function`/`vm`; credentials go through `ctx.credentials`, not
+  a backing file; third-party endpoints are disclosed.
 - No “official”, “certified”, “secure”, or ranking claim.
 
 ## Declaration fields
@@ -303,7 +307,46 @@ export function apply(ctx) {
 }
 ```
 
+<a id="security-checks"></a>
+## Security checks (DSC-15 to DSC-22)
+
+ENTRY is a compatibility gate; it does not answer "is this safe to install". The
+static security scope ships in `dsh-standards` 1.6.0+ and evaluates eight
+checks; with `--scope security` the report's `checks[]` carries all 22
+(`DSC-01`–`DSC-14` plus `DSC-15`–`DSC-22`).
+
+| Check | What it looks for | Verdict in `--scope security` |
+|---|---|---|
+| `DSC-15` | `preinstall`/`install`/`postinstall`/`prepare` that download, decode, or execute (command string and referenced in-package script body, ≤512 KB) | blocking |
+| `DSC-16` | `eval`, `new Function`, `vm`, `module._compile`, `process.binding`; bare `child_process` is WARN in 1.6.1 | blocking |
+| `DSC-17` | reads of `~/.ssh`, `~/.aws`, `.npmrc`, `.netrc`, or credential backing files | blocking |
+| `DSC-18` | non-https, userinfo, bare-IP, webhook/paste/tunnel egress targets | WARN (clue) |
+| `DSC-19` | minified blobs, large base64 blocks, wasm/native without source | advisory |
+| `DSC-20` | tool/web text flowing into the system prompt without a boundary | advisory (static v1 + runtime hook v2) |
+| `DSC-21` | typosquat names, fake scopes, unpinned or script-bearing dependencies | mandatory but **WARN-only, never blocking** (listing included) |
+| `DSC-22` | `dist.integrity`, signatures, provenance attestations | advisory |
+
+`--scope security` is released in 1.6.0+; 1.5.x and earlier exit `3` for the
+unknown scope. Outside that scope the eight are not in `checks[]`; a security
+`FAIL` is capped to WARN in the separate `security` block, never enters
+`buckets.blocking`, and cannot change an ENTRY verdict. Only `15`/`16`/`17` can
+block (and only under `--scope security`); `21` never blocks; `18`/`19`/`20`/`22`
+are advice. `DSC-16` subprocess FAIL is scoped to 1.6.2; 1.6.1 keeps a bare
+`child_process` import at WARN.
+
+```sh
+# 1.6.0+; exits 3 only on 1.5.x and earlier
+npx dsh-standards ./my-plugin --scope security --format json
+```
+
+The author, user, and market checklists — with copyable manifests, commands,
+and the boundary between static checks and a runtime sandbox — are in
+[security.md](security.md). ENTRY's own declaration fields are not enforcement,
+and neither is a `DSC-11` PASS.
+
 ## What ENTRY does not do
 
 It is not a security audit, sandbox, full contract audit, market gate, score, or
-ranking. Those are separate concerns; do not borrow their authority.
+ranking. Those are separate concerns; do not borrow their authority. The static
+`DSC-15`–`DSC-22` checks are a separate security scope, covered in
+[security.md](security.md), not part of the ENTRY verdict.

package/docs/flow.md

@@ -201,6 +201,26 @@ the original `command[]`, `exitCode`, the last 20 lines of stderr, and the
 absolute log path. Then attach the clause anchor the journey maps to (for
 example `J2.toggle → 32-DSH-FLOW #R2`).
 
+<a id="security-boundary"></a>
+## Security boundary
+
+J5 checks that permissions are declared consistently; it is static preflight,
+not a security test. The static `DSC-15`–`DSC-22` checks live behind a separate
+`--scope security`, shipped in `dsh-standards` 1.6.0+ (1.5.x and earlier exit
+`3`), and they never turn a FLOW journey into a security pass. Outside that
+scope a security finding is advisory: it is capped to WARN in the separate
+`security` block, never enters `buckets.blocking`, and cannot change the FLOW
+verdict. Under `--scope security` only `DSC-15`/`DSC-16`/`DSC-17` can block;
+`DSC-21` is WARN-only.
+
+Static checks also cannot observe what a plugin does at runtime — which URLs it
+reaches, which files it reads, or whether a prompt was corrupted. Those answers
+need a sandbox with a network policy plus capture, and a sandbox that only
+limits subprocess file writes is not that boundary. So do not write “FLOW
+passes, therefore it is safe”; write what was observed, and keep the security
+claim `not-run` until it was actually run. Details:
+[security.md](security.md#scope).
+
 ## Status, not a score
 
 | Status | Meaning |

package/docs/levels.md

@@ -20,6 +20,7 @@
 | an ENTRY question | [entry.md](entry.md) — package shape, runtime surface, declarations |
 | a FLOW journey to record | [flow.md](flow.md) — the `dsh-flow-evidence/2` file and J1–J8 evidence |
 | a BOOST practice to evidence | [boost.md](boost.md) — the thirteen-field evidence card |
+| a security question — what can a plugin do, is this safe to install, what must a market disclose | [security.md](security.md) — author/user/market checklists and the `DSC-15`–`DSC-22` boundary |
 
 The two reference docs exist because a report ID alone does not tell you what to
 change: [rules.md](rules.md) maps IDs to fixes, and [recipes.md](recipes.md)
@@ -73,6 +74,26 @@ Start here: [BOOST guide](boost.md) and the canonical
 The card fields are in
 [boost.md § evidence, not a badge](boost.md#thirteen-fields).
 
+## Security is not a fourth layer
+
+Security checks are a **scope**, not a level, and they ship in `dsh-standards`
+1.6.0+ (1.5.x and earlier exit `3` for the unknown scope): `DSC-15`–`DSC-22`
+sit behind `--scope security`. They never change an ENTRY, FLOW, or BOOST
+verdict. Outside that scope a security `FAIL` is capped to WARN in the separate
+`security` block and does not enter `buckets.blocking`; under it only
+`DSC-15`/`16`/`17` can block, and `DSC-21` is WARN-only.
+
+- Static checks only match known source shapes; they cannot see runtime egress,
+  file reads, or prompt corruption. Runtime security needs a sandbox with a
+  network policy and capture.
+- No security `PASS` means “safe”. It means “no known pattern matched in this
+  static pass”.
+- The three layers stay about compatibility, user journeys, and Cordis practice.
+  Do not turn them into a security certification, and do not add a “security
+  level” to the vocabulary.
+
+Read [security.md](security.md) for the author, user, and market checklists.
+
 ## Run the checks
 
 ```sh
@@ -94,5 +115,6 @@ The legacy build skill/CLI is [`dsh-primer`](https://github.com/PerryLink/dsh-pr
 - `static` ≠ `runtime`
 - `not-run` ≠ `pass`
 - `boost-evidenced` ≠ plugin grade
+- security check ≠ security audit
 - `A–D` grades (where they exist) are orthogonal to ENTRY/FLOW/BOOST
 - No official, certified, verified, audited, secure, recommended, or ranked claim

package/docs/rules.md

@@ -22,8 +22,10 @@ incomplete/not-run, `3` usage error. `WARN` is not a clean pass and
 The JSON report also carries a sibling `advice[]` array: one entry per live
 detail, with `title`, `why`, `fix`, `docsUrl`, `severity`, and `evidence`. It is
 additive and never changes the verdict (turn it off with `--no-advice`). The
-`docsUrl` follows the checker's `DOCS_BASE` (currently `v0.4.4`); if it points
-at an older page, this table is the current mapping.
+`docsUrl` follows the checker's `DOCS_BASE`: 1.6.1 pins `v0.4.6`, and the 1.6.2
+release moves it to guide `v0.5.0`. The `docs/security.md` anchors used by the
+`C-15`–`C-22` advice exist in 0.5.0; if a link points at an older page, this
+table is the current mapping.
 
 <a id="scope-matrix"></a>
 ## Which checks run in which scope
@@ -35,6 +37,7 @@ at an older page, this table is the current mapping.
 | `--scope entry --entry-claim static` | 01, 02, 11, 12, 13 (+ 03 for listing) | 04–09 are attempted and printed (usually `ERROR`/`NA`), 14 is `NA`; a `DSC-11`/`DSC-12`/`DSC-13` FAIL is downgraded to `WARN` |
 | `--scope entry --entry-claim runtime` | + 14 | 14 carries the runtime verdict, not 04–09 |
 | `--scope mvp` | 01, 02, 04–09 | the MVP subset, labelled `MVP-13` |
+| `--scope security` (1.6.0+) | + 15, 16, 17, 21; 18/19/20/22 advisory | `checks[]` becomes 22 (14 + 8); DS-C 01–14 are unchanged and the report gains an additive `security` block. `15`/`16`/`17` blocking, `21` mandatory but WARN-only |
 
 <a id="table"></a>
 ## The check table
@@ -55,10 +58,27 @@ at an older page, this table is the current mapping.
 | **DSC-12** | C-12 credentials + seams | Blocking (ds-c); `WARN` in ENTRY. | Read credentials through `ctx.credentials`, declare `credentials:list` for `listRecords()` and `credentials:provider` for a provider, and never read the backing file. | [entry.md § credentials and seams](entry.md#credentials-and-seams) |
 | **DSC-13** | C-13 labels + mirror | Blocking (ds-c); `WARN` in ENTRY, advisory as a WARN. | Use only the five labels, add the label each capability requires, point `dsh.upstream` at an https URL that is not this package **and** add `mirror`, and drop endorsement words. | [entry.md § labels and mirror](entry.md#labels-and-mirror) |
 | **DSC-14** | C-14 entry run | Blocking only for a runtime claim (`--scope entry`). | Supply the real host: `--host` for a bundle (G0–G3) or `--runtime` for a plugin (L1); a client or preset cannot claim runtime. | [entry.md § runtime surface](entry.md#runtime-surface) |
+| **DSC-15** | C-15 lifecycle scripts | **Blocking only under `--scope security`** (1.6.0+); not run in the default scopes. It reads the referenced in-package script body (≤512 KB) as well as the command string. | Ship no `preinstall`/`install`/`postinstall`/`prepare`; if one is unavoidable, no download-to-shell, `base64 -d`, or `node -e`. | [security.md § author 4](security.md#author-files) |
+| **DSC-16** | C-16 dynamic execution | **Blocking only under `--scope security`**. `eval`/`Function`/`vm`/`_compile`/`process.binding` FAIL; a bare `child_process` import is WARN in 1.6.1, and the dangerous-subprocess FAIL is 1.6.2. | Remove `eval`, `new Function`, `vm.runIn*`, `module._compile`, and `process.binding`; dynamic `import()` takes a static path only. | [security.md § author 4](security.md#author-files) |
+| **DSC-17** | C-17 sensitive files | **Blocking only under `--scope security`**. | Read credentials through `ctx.credentials`; never read `~/.ssh`, `~/.aws`, `.npmrc`, `.netrc`, or a credential backing file. | [security.md § author 2](security.md#author-credentials) |
+| **DSC-18** | C-18 egress endpoints | **WARN** under `--scope security` (clue, not blocking). | Use a constant `https` allowlist, `redirect: 'manual'`, no credentials across origins, and disclose third-party endpoints. | [security.md § author 3](security.md#author-egress) |
+| **DSC-19** | C-19 obfuscation/binary | **Advisory** under `--scope security`. | No minified blobs or binary-only code; ship wasm/native with source, build method, and `sha256`. | [security.md § author 4](security.md#author-files) |
+| **DSC-20** | C-20 prompt injection | **Advisory**: static v1 (external text into `systemPrompt`, instruction-like literals) plus a runtime hook in v2; never blocking. | Treat tool/web/file/session text as untrusted, validate `output.schema`, and wrap external text before it reaches a prompt. | [security.md § author 5](security.md#author-prompt) |
+| **DSC-21** | C-21 supply chain | **Mandatory under `--scope security`, but WARN-only and never blocking** (listing included). | Commit the lockfile, pin dependencies, reject typosquat/lookalike scopes, and treat an unpinned or script-bearing dependency as `not-run`. | [security.md § author 6](security.md#author-publish) |
+| **DSC-22** | C-22 provenance/integrity | **Advisory**, never blocking. | Publish with provenance/attestations; `dist.integrity` only binds the tarball to the registry, not the code to a source. | [security.md § author 6](security.md#author-publish) |
 
 `DSC-14` has no `C-14` in the clause text; it is the ENTRY run-set gate
 (`ENT-14` in 31-DSH-ENTRY). Treat it as "did the thing actually start".
 
+`DSC-15`–`DSC-22` shipped in `dsh-standards` 1.6.0; 1.5.x and earlier treat
+`--scope security` as an unknown scope and exit `3`. Only `--scope security`
+makes `15`/`16`/`17` blocking; `21` is mandatory but WARN-only and never blocks
+(listing included). In every other scope the eight stay out of `checks[]`; their
+FAILs are capped to WARN in the separate `security` block and never change the
+DS-C verdict. They are static evidence: three can fail mechanically, one only
+warns, four only return clues, and no PASS proves a plugin safe. The
+author/user/market checklists are in [security.md](security.md).
+
 <a id="warn"></a>
 ## Two things that look like passes but are not
 
@@ -89,6 +109,11 @@ them:
 - whether a `red-team` label was actually used for red-team work (`C-13.5`
   only asks for `dsh.usageScope`)
 - browser rendering of a client bundle (`G4` is a static shape check)
+- runtime network egress, file reads, or prompt corruption — `DSC-18`/`DSC-20`
+  are static clues; observing the behavior needs a sandbox with a network policy
+  and capture (see [security.md](security.md#scope))
+- whether a dependency's own install script ran, or whether a package is
+  malicious. `DSC-15`/`DSC-21` cover known shapes, not intent.
 
 The checker's default `--runtime-version` is `0.2.2-alpha.2`. Pass
 `--runtime-version <the host you target>` when that differs, or `DSC-02` will

package/docs/security.md

@@ -0,0 +1,427 @@
+# Security: what a plugin can do, and what the checks cannot prove
+
+> **Read this first.** A DSH plugin runs in the host's process, as the same
+> user, with the host's full permissions. The host does not sandbox a loaded
+> plugin: the sandbox only restricts file writes made by tool subprocesses, and
+> network/process visibility is outside its vocabulary. `dsh.capabilities` is a
+> declaration the host does not read or enforce. So a plugin can open and write
+> files, spawn processes, reach the network, and read the credential store
+> whether or not it declares that it does.
+
+`DSC-15`–`DSC-22` are the **static security checks** shipped in
+`dsh-standards` **1.6.0**; `--scope security` is a released flag
+from 1.6.0 on (1.5.x and earlier treat `security` as an unknown scope and exit
+`3`; 1.6.1 supports it).
+With `--scope security`, `checks[]` carries all **22** checks (`DSC-01`–`DSC-14`
+plus `DSC-15`–`DSC-22`); the default `ds-c` run still carries 14 and reports the
+eight in the additive `security` block. Three can block (`15`, `16`, `17`), one
+is mandatory but **WARN-only and never blocks** (`21`, listing included), and
+four only produce clues (`18`, `19`, `20`, `22`); all eight reduce risk, and
+**none of them proves a plugin is safe**.
+
+The `security` block is a **separate view**, not a fourth verdict. In the default
+scope a security `FAIL` is capped to `WARN` inside `security.checks[]`; it is
+listed only in `security.warn[]` (`security.blocking[]` stays empty), does not
+enter `buckets.blocking` or `conclusion.headline`, and changes neither `status`
+nor the exit code. Only `--scope security` puts `15`/`16`/`17` into `checks[]`,
+where a `FAIL` enters `buckets.blocking`, the headline, `status=fail` and exit
+`1`. `DSC-21` never FAILs, so it never blocks in either profile. Read the scope,
+and read the block's `checks[]`, not just its four arrays — see
+[Reading the `security` block](#security-block).
+
+## The trust boundary in one table
+
+| Fact | What follows |
+|---|---|
+| plugin and host share a process | `import node:fs`, `fetch`, `child_process`, and `process.env` are always reachable |
+| `dsh.capabilities` is a declaration | declaring `[]` does not remove a capability; over-declaring is a WARN, under-declaring is a static FAIL |
+| the sandbox covers tool subprocess file writes only | it is not a boundary around plugin code, and not a network policy |
+| the checker executes the plugin | `--runtime`/C-4/C-14 import it; the check path has no sandbox and inherits `HOME` |
+| static checks see known source shapes | they cannot see runtime egress, dynamic URLs, or whether a prompt was really corrupted |
+| runtime safety needs containment | a network-policy sandbox plus capture/audit is the only way to observe what code actually does |
+
+<a id="author"></a>
+## Author guide
+
+<a id="author-least-privilege"></a>
+### 1. Least privilege and the capability declaration (DSC-16, DSC-18)
+
+Declare only the closed-set IDs the plugin really touches. Every static trigger
+needs its entry (`C-11.2`), and an entry with no trigger is an over-declaration
+WARN (`C-11.5`). There are 15 IDs: `fs:read`, `fs:write`, `shell`, `subprocess`,
+`network:egress`, `network:ingress`, `credentials:read`, `credentials:list`,
+`credentials:provider`, `llm:adapter`, `sessions:read`, `system-prompt:write`,
+`tools:register`, `remote:expose`, `plugin:install`.
+
+```json
+{
+  "dsh": {
+    "capabilities": ["tools:register"]
+  },
+  "security": {
+    "status": "draft",
+    "note": "non-host disclosure only; not read, not enforced",
+    "permissions": {
+      "files": [],
+      "network": [],
+      "credentials": [],
+      "shell": false,
+      "subprocess": false
+    }
+  }
+}
+```
+
+`dsh.permissions` and `security.permissions` are **not host fields**. The
+standard is not fixed, so this guide prints a `security.permissions` block
+marked `draft`: it is disclosure for a human or a market, never enforcement.
+If you do not want to make the disclosure claim, delete the block — an absent
+field means "not declared", not "no permissions". `dsh.commitments` and
+`dsh.disclosure` are the same kind of optional disclosure: `false` means "no
+promise", absent means "not declared". Do not fill every commitment `true`; an
+unsupported claim is worse than a missing one.
+
+<a id="author-credentials"></a>
+### 2. Credentials and sensitive files (DSC-17)
+
+Resolve a reference per operation, through the seam, and never print, log,
+persist, or put a value in `argv`. `describe()` is the only shape a UI should
+see. Do not read `$DSH_HOME/.credentials.yaml`, `~/.ssh`, `~/.aws`, `~/.netrc`,
+`.npmrc`, or any other backing file, and do not enumerate unrelated records.
+
+```ts
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+
+const ref = credentialRef('MY_API_KEY')
+const resolved = await ctx.credentials.resolve(ref) // re-resolve per operation
+if (!resolved) throw new Error('MY_API_KEY is not configured') // never print resolved.value
+
+// configuration UI: presence and writability only
+const info = await ctx.credentials.describe(ref)
+```
+
+Environment scrubbing applies to `ctx.subprocess`: the child gets a scrubbed
+parent environment, and an explicit `env` entry is a deliberate opt-in. Do not
+forward a token "just in case".
+
+<a id="author-egress"></a>
+### 3. Egress endpoints (DSC-18)
+
+Use a constant allowlist of exact hostnames and `https` only. Never fetch a URL
+that came from a model, a tool result, or a user message; use
+`redirect: 'manual'` and refuse a redirect unless every `Location` hop passes the
+same allowlist (bounded), and never send a credential across an origin. Disclose
+third-party endpoints, what is retained, and whether session text is forwarded.
+
+```ts
+const ALLOW = new Set(['api.example.com'])
+
+export function checkedUrl(raw: string): URL {
+  const url = new URL(raw)
+  if (url.protocol !== 'https:' || !ALLOW.has(url.hostname)) {
+    throw new Error('blocked endpoint')
+  }
+  return url
+}
+
+const res = await fetch(checkedUrl('https://api.example.com/v1/x'), {
+  redirect: 'manual',
+})
+```
+
+The host has no egress policy and `web_fetch` can reach private addresses. This
+allowlist is the plugin's own discipline, not a sandbox. If you must call a
+third party, say so in `dsh.disclosure.endpoints` (when that field exists) and
+in the README.
+
+<a id="author-files"></a>
+### 4. Files, subprocesses, and dynamic execution (DSC-15, DSC-16, DSC-17, DSC-19)
+
+- Use `ctx.fs`: `resolve()` the target, then `contains(workspace, target)`.
+  Reject `..`, absolute paths, and symlinks (check with `lstat` first), bound the
+  size, and keep temp files at `0700`/`0600` (ACL on Windows).
+- Do not start a subprocess by default. When you must, use
+  `ctx.subprocess.spawn` with an `argv` array, an absolute executable, `cwd`
+  inside the workspace, the scrubbed environment, a timeout/abort, and bounded
+  output. Never build a shell command string.
+- Never use `eval`, `new Function`, `vm.runIn*`, `module._compile`, or
+  `process.binding`. Dynamic `import()` takes a static path only. Do not publish
+  minified blobs or binary-only code; if you ship wasm/native, ship the source,
+  the build method, and a `sha256`.
+- Lifecycle scripts are the install-time RCE surface (`DSC-15`): ship none. If a
+  build truly needs one, never pipe a download into a shell, and never hide it
+  behind `base64 -d` or `node -e`.
+
+```ts
+const workspace = await ctx.fs.resolve(process.cwd())
+const target = await ctx.fs.resolve(userPath)
+if (!ctx.fs.contains(workspace, target)) throw new Error('path escapes the workspace')
+
+const child = ctx.subprocess.spawn({
+  argv: ['/usr/bin/git', 'status'],
+  cwd: process.cwd(),
+  stdio: { stdin: 'ignore', stdout: { maxBytes: 64_000 }, stderr: { maxBytes: 64_000 } },
+  graceMs: 5_000,
+  signal,
+})
+const outcome = await child.done
+```
+
+The sandbox still only covers subprocess file writes; a plugin's own `fetch` and
+`node:fs` bypass every seam. Do not read a declaration as isolation.
+
+<a id="author-prompt"></a>
+### 5. Tool output and prompt injection (DSC-20)
+
+Tool results, web pages, files, and session text are **untrusted data**. Validate
+them against the tool's `output.schema` (a mismatch is `INVALID_TOOL_OUTPUT`),
+and wrap external text with a fixed untrusted prefix, a per-call random boundary,
+and JSON escaping before it reaches a prompt. Never put external text in the
+system prompt or turn it into instructions. Instruction hierarchy belongs in
+code: system > user > external data. Model output stays data; validate it, do
+not shell it, and do not let it choose an arbitrary URL.
+
+```ts
+import { randomUUID } from 'node:crypto'
+
+const wrap = (s: string) => {
+  const id = randomUUID() // per call, so reused wrappers get a fresh boundary
+  return `<untrusted-${id}>\n${JSON.stringify(s).replaceAll('<', '\\u003c')}\n</untrusted-${id}>`
+}
+```
+
+Rendering is part of the same boundary: use `textContent`/React escaping, never
+`innerHTML`, and escape log and error text too. Wrapping lowers the success rate
+of injection; it is not isolation.
+
+<a id="author-publish"></a>
+### 6. Dependencies, build, and publish (DSC-15, DSC-21, DSC-22)
+
+Commit the lockfile and install with `npm ci --ignore-scripts` (or
+`--frozen-lockfile`). Keep dependencies minimal and check for typosquats —
+lookalike scopes and edit-distance names around `dsh`/`@deepseek-ai/dsh`. Use a
+`files` allowlist, publish the build output, pin Node and the package manager,
+and make a tag rebuild reproducibly.
+
+```sh
+npm ci --ignore-scripts && npm test && npm pack --dry-run
+npm audit --omit=dev && npm audit signatures
+# CI only: trusted publishing, provenance, no long-lived token
+npm publish --access public --provenance
+```
+
+Publish with npm trusted publishing (OIDC) and `--provenance`; keep 2FA on,
+protect tags, require review, and never reuse a version (deprecate a bad one).
+Check that `package.json` has no `preinstall`/`install`/`postinstall`/`prepare`:
+
+```sh
+node -e "const s=require('./package.json').scripts||{}; if(s.preinstall||s.install||s.postinstall||s.prepare) process.exit(1)"
+```
+
+`dist.integrity` only proves the tarball matches the registry, and an
+attestation needs signature verification plus a bound build source. Neither is
+a code-safety proof.
+
+<a id="author-response"></a>
+### 7. Vulnerability response (process, not a DSC)
+
+Ship a `SECURITY.md` with a private channel (GitHub Security Advisories), the
+supported versions, a 7-day first response, and 90-day coordinated disclosure.
+Do not take vulnerability reports in public issues. After a fix, publish a
+patch release, an advisory, and credit; revoke and rotate leaked tokens; for a
+malicious version, deprecate it, ask the market to delist, and keep the
+evidence.
+
+```md
+# Security Policy
+
+## Supported versions
+| Version | Supported |
+|---|---|
+| 0.1.x | yes |
+
+## Reporting
+Use <repo>/security/advisories/new; do not open a public issue.
+Include the version, DSH version, impact, and a minimal repro. First response within 7 days.
+```
+
+<a id="user"></a>
+## User guide
+
+The checks tell you what a package declares; they do not tell you what it does.
+Assume a loaded plugin can do anything the user can. The static checks that
+touch this path are `DSC-15` (lifecycle scripts), `DSC-17` (credential files),
+`DSC-21` (typosquat/lookalike names, WARN-only) and `DSC-22`
+(integrity/provenance) before install; `DSC-18` only ever produces a static clue
+about egress. Under `--scope security`, `DSC-15`/`DSC-16`/`DSC-17` can block;
+outside it every security finding is capped to WARN in the separate `security`
+block.
+
+**Before installing.** Read the manifest: `dsh.capabilities`, `dsh.labels`,
+`scripts`, `files`, `engines.dsh`, and the source pin. Then look at the source
+and the publisher: an exact npm version with `dist.integrity`, or a git
+40-hex commit; how recent the release is; whether `dist.signatures` /
+`dist.attestations` exist; and whether an install script is present. An empty
+capabilities list means **not declared**, not "no capabilities". A label such as
+`prompt-modification`, `third-party-model-provider`, `remote-access`,
+`red-team`, or `mirror` is the author telling you which risk to check, not a
+clearance.
+
+```sh
+npm view pkg@1.2.3 version dsh scripts dist.integrity dist.signatures dist.attestations repository.url time.modified --json
+
+# the released static security scope (1.6.0+; does not run the plugin)
+npx dsh-standards check ./pkg --scope security --format json
+```
+
+**During install.** Start from a throwaway profile (`dsh plugin --profile lab
+...` initializes it), add `--ignore-scripts`, and understand that it stops
+install scripts only, not the code the host loads. The GUI build approval runs
+a script with your permissions, but the approval list shows only the package
+name, not the script body: inspect the referenced script first (`npm pack`, then
+read `scripts/*`). The CLI inherits your whole environment, so launch it from a
+clean shell with no tokens. A new session defaults to `workspace-write` + `ask`;
+do not switch to `danger-full-access` with `never`.
+`DSH_PERMISSION_MODE=read-only` constrains tool subprocesses, not plugins.
+
+```sh
+dsh plugin --profile lab add pkg@1.2.3 --ignore-scripts
+dsh --profile lab --dump-config
+dsh plugin --profile lab remove pkg
+```
+
+**After install.** Return to `workspace-write`, watch the install log and the
+session's tool calls, and remove the package when you no longer need it. Check
+the profile's `package.json`/lockfile and the credential records. If something
+looks wrong, disable it, keep the logs and the package hash, and report through
+its `SECURITY.md` (for a malicious npm package, also npm support). Do not
+publish the details first.
+
+<a id="market"></a>
+## Market / repository guide
+
+**Record facts before listing.** `name@version`; source (npm integrity or git
+40-hex plus subdir); `dsh.bundle.patch` (no `!!js`), `files`, `engines.dsh`, and
+whether `scripts` contains an install hook; publisher vs `repository`;
+`SECURITY.md`, 2FA, protected tags; publish time; provenance/attestations;
+capability/label validity; license (advisory). Do not install or execute the
+package to fill the row, and do not grade, score, or rank it. These facts map
+to `DSC-15`–`DSC-22`: a row records them, it does not certify them.
+
+```sh
+npm view pkg@1.2.3 --json
+mkdir -p inspect && npm pack pkg@1.2.3 --ignore-scripts --pack-destination ./inspect && tar -tzf inspect/*.tgz
+git clone --filter=blob:none --no-checkout <url> r && git -C r archive <40hex> | tar -t
+```
+
+**Show risk, not a badge.** Put capabilities in the same view as labels and mark
+them "author declaration, not enforced"; mark unknowns "not declared / not
+checked / not run". The index's only risk field is labels; capabilities must be
+read from the manifest. Missing data is never a pass. State that static checks
+cover known patterns and are not a security audit. The checker can import the
+plugin, so do not run it against an untrusted package on a host you care about.
+
+**Disputes and delisting.** Hard-reject only four cases: not a plugin /
+unparseable, source not pinnable, impersonation or infringement, and a malicious
+security hold (manual review with an appeal). List everything else with the
+finding attached. The author can withdraw at any time; a 90-day expiry removes
+only the label; a 14-day appeal window; keep history for at least two years and
+write the reason to `market-actions.jsonl`.
+
+**Wording ban.** Never write "secure", "certified", "official", "audited", or
+"100% risk-free", and never imply certification with a shield or a checkmark.
+Use the fixed disclaimer: "unofficial · not certified · not security-audited ·
+not endorsed · no warranty".
+
+<a id="template"></a>
+## Template: minimal low-risk defaults
+
+The smallest honest starting point is: no lifecycle scripts, empty
+capabilities, a permissions disclosure marked draft, and a `SECURITY.md` in the
+tarball. The `dsh-scaffold` template ships these defaults.
+
+```json
+{
+  "name": "@acme/dsh-hello",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "files": ["lib", "cordis.patch.yml", "SECURITY.md", "LICENSE"],
+  "scripts": { "test": "vitest run" },
+  "dsh": {
+    "capabilities": [],
+    "labels": []
+  },
+  "security": {
+    "status": "draft",
+    "note": "non-host disclosure only; not read, not enforced",
+    "permissions": { "files": [], "network": [], "credentials": [], "shell": false, "subprocess": false }
+  }
+}
+```
+
+`SECURITY.md` must name the private channel, the supported versions, and the
+response window — see the author section above. Verify the shape before publish:
+
+```sh
+node -e "const s=require('./package.json').scripts||{}; if(s.preinstall||s.install||s.postinstall||s.prepare) process.exit(1)"
+npm pack --dry-run   # SECURITY.md must be in the file list
+```
+
+This shape is the starting point for `DSC-15` (no lifecycle scripts), `DSC-21`
+(no typosquat dependency), and `DSC-22` (provenance publishing); it also gives
+`DSC-17` and `DSC-18` a truthful empty disclosure to read. An empty
+`capabilities` array is correct only while the plugin touches no host surface.
+Once it registers a tool or reads `ctx.fs`, add the ID; a copied template with a
+stale empty array hides the very `C-11.2` failure the check is for.
+
+<a id="scope"></a>
+## Where the security checks sit
+
+| Scope | What runs | Verdict |
+|---|---|---|
+| `--scope ds-c` (default) / `entry` / `flow` / `boost` | `DSC-01`–`DSC-14`: only the scope's mandatory subset counts (`DSC-10` is advisory; `03`/`14` can be NA/not-run). `DSC-15`–`DSC-22` run in the separate `security` block (`scope=advisory`) | a security `FAIL` is capped to `WARN` in that block; it is not in `checks[]`/`buckets.blocking` and cannot change `status`/exit |
+| `--scope security` (1.6.0+) | all 22 checks in `checks[]`: DSC-01–14 plus DSC-15–22 | `15`/`16`/`17` blocking (FAIL → exit 1); `21` mandatory **WARN-only**, never blocking (listing too); `18` WARN; `19`/`20`/`22` advisory |
+| runtime observation | sandbox with a network policy + capture | the only evidence that code actually egressed, read a file, or rewrote a prompt |
+
+`DSC-16` blocks on `eval`/`new Function`/`vm`/`module._compile`/`process.binding`.
+A bare `child_process` import is WARN in 1.6.1; the FAIL for a statically
+dangerous subprocess command is scoped to 1.6.2.
+
+The JSON report carries an additive top-level `security` block; the DS-C verdicts
+stay unchanged. A PASS in that block means "no blocking FAIL, no WARN, and the
+mandatory `15`/`16`/`17`/`21` all produced a result", not "safe".
+
+<a id="security-block"></a>
+### Reading the `security` block
+
+- `conclusion.headline`'s `blocking N` and `buckets.blocking[]` are
+  **report-level**: they only count `checks[]` FAILs. `security.blocking[]` is
+  the block's own list and can only ever hold `DSC-15`/`DSC-16`/`DSC-17`.
+- **Default scope:** the eight run in `security.checks[]` with
+  `security.scope="advisory"`. A `FAIL` is capped to `WARN` (listed in
+  `security.warn[]`), `security.blocking=[]`, no security row appears in
+  `buckets.blocking`, the headline is unchanged, and `status`/exit stay the same.
+- **`--scope security`:** the eight join `checks[]`. A `15`/`16`/`17` FAIL →
+  `security.blocking=[...]` plus `buckets.blocking=[...]`, headline `blocking N`,
+  `status=fail`, exit `1`. `DSC-21` findings are WARN-only and never block;
+  `18`/`19`/`20`/`22` are advisory. A mandatory check with no result makes
+  `security.status=incomplete`.
+- **Partial:** 1.6.1 has no `security.partial[]`. A partly-run check is
+  `security.checks[].coverage === "partial"` (and top-level `coverage.partial` /
+  `buckets.partial`); `security.notRun[]` only carries `NA`/`ERROR`/full
+  `not-run`. Do not read the four arrays as complete coverage.
+
+<a id="limits"></a>
+## What no static check can tell you
+
+- whether a URL was really fetched, or where a redirect went;
+- whether a file outside the package was read or written;
+- whether a dependency's own install script ran;
+- whether a model was actually steered by injected text;
+- whether the author is trustworthy — signatures are self-asserted evidence
+  until the key chain and build provenance are verified by a human.
+
+Runtime security needs a sandbox with an egress policy and an audit trail.
+Windows has no `unshare`, so the containment story is weaker there, and a
+sandbox that only limits writes is not a network boundary. Until you have that
+evidence, write `not-run` or `not-measured` — never "secure".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "A practical guide to DSH plugin quality: ENTRY checks, FLOW checks, and BOOST guidance. Community guide; not official, not a certification, not a ranking.",
   "type": "module",
   "main": "index.js",