dsh-plugin-guide 0.4.6 → 0.5.0

package/SKILL.md

@@ -56,3 +56,7 @@ 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`. Its checks are static and advisory,
+and runtime security needs a sandbox, not a checker.

package/docs/boost.md

@@ -90,6 +90,19 @@ 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 proposed
+`DSC-15`–`DSC-22` checks are static and advisory outside `--scope security`
+(which `dsh-standards` 1.4.x does not ship yet); 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,42 @@ 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
+2026-11 audit proposes eight security checks as a separate scope:
+
+| Check | What it looks for | Verdict in `--scope security` |
+|---|---|---|
+| `DSC-15` | `preinstall`/`install`/`postinstall`/`prepare` that download, decode, or execute | blocking |
+| `DSC-16` | `eval`, `new Function`, `vm`, `module._compile`, `process.binding` | 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 (runtime, v2) |
+| `DSC-21` | typosquat names, fake scopes, unpinned or script-bearing dependencies | blocking in listing |
+| `DSC-22` | `dist.integrity`, signatures, provenance attestations | advisory |
+
+These checks are **not released** in `dsh-standards` 1.4.x, and `--scope
+security` is a proposed flag; if your checker exits `3` for an unknown scope,
+that is expected. Outside that scope they do not run, and a security `FAIL` is
+capped at WARN, so it cannot change an ENTRY verdict. Four are mechanical and
+four only return clues — none of them proves a plugin is safe.
+
+```sh
+# proposed; not available in 1.4.x
+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
+proposed `DSC-15`–`DSC-22` are a static security scope, covered in
+[security.md](security.md), not part of the ENTRY verdict.

package/docs/flow.md

@@ -201,6 +201,23 @@ 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 proposed `DSC-15`–`DSC-22` live behind a separate
+`--scope security` that `dsh-standards` 1.4.x does not ship yet, and they never
+turn a FLOW journey into a security pass. Outside that scope a security finding
+is advisory: it is capped at WARN and cannot change the FLOW verdict.
+
+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,24 @@ 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 are proposed, not
+released: `DSC-15`–`DSC-22` sit behind a `--scope security` that
+`dsh-standards` 1.4.x does not have yet. They never change an ENTRY, FLOW, or
+BOOST verdict, and outside that scope a security `FAIL` is capped at WARN.
+
+- 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 +113,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

@@ -35,6 +35,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` (proposed, not in 1.4.x) | + 15, 16, 17, 21; 18/19/20/22 advisory; 21 listing only | security scope only; DS-C 01–14 are unchanged and the report gains an additive `security` block |
 
 <a id="table"></a>
 ## The check table
@@ -55,10 +56,25 @@ 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 (proposed) | **Blocking only under `--scope security`**; not run in the default scopes. | 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 (proposed) | **Blocking only under `--scope security`**. | 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 (proposed) | **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 (proposed) | **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 (proposed) | **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 (proposed) | **Advisory** (FLOW runtime, 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 (proposed) | **Blocking under `--scope security` in the listing profile**; non-blocking outside a listing. | 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 (proposed) | **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` are **proposed** by the 2026-11 audit and are not in
+`dsh-standards` 1.4.x. Only `--scope security` makes `15`/`16`/`17` (and `21`
+in a listing) blocking; in every other scope they are absent or capped at WARN,
+and none of them changes the existing DS-C verdict. They are static evidence:
+four can fail mechanically, 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 +105,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,385 @@
+# 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 **proposed** security checks from the 2026-11 audit. They
+are not in `dsh-standards` 1.4.x, and `--scope security` is a proposed scope, not
+a released flag. When they ship, four are mechanical (`15`, `16`, `17`, `21`)
+and four only produce clues (`18`, `19`, `20`, `22`); all eight reduce risk, and
+**none of them proves a plugin is safe**. Until then, this page is a checklist,
+not a gate.
+
+The same boundary applies to the existing scopes: outside `--scope security`,
+a security `FAIL` can land in `buckets.blocking` while `status` and the exit
+code stay `0`, because only the mandatory set decides the verdict. Read the
+scope, not the bucket.
+
+## 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; redirects are checked
+hop by hop, and a credential is never sent 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 id = randomUUID()
+const wrap = (s: string) =>
+  `<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 proposed checks that
+touch this path are `DSC-15` (lifecycle scripts), `DSC-21` (source pinning,
+typosquat), and `DSC-22` (integrity/provenance) before install; `DSC-17`/`DSC-18`
+only ever produce static clues about files and egress.
+
+**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
+```
+
+**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: read the script before approving. 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 secure 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–14 mandatory; DSC-15–22 non-mandatory if implemented | a security `FAIL` is recorded in `blocking` but cannot change `status`/exit |
+| `--scope security` (proposed, not released) | + DSC-15–22 | `15`/`16`/`17` blocking; `21` blocking in the listing profile; `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 |
+
+When the scope ships, the JSON report gets an additive top-level `security`
+block; the DS-C verdicts stay unchanged. A PASS in that block means "no known
+shape matched in this static pass", not "safe".
+
+<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.0",
   "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",