dsh-standards 1.0.3 → 1.2.0

package/40-checker/README.md

@@ -19,6 +19,8 @@ node bin/dsh-plugin-verify.mjs /path/to/plugin --format json --out report.json
 node bin/dsh-plugin-verify.mjs /path/to/plugin --format sarif --out report.sarif
 ```
 
+`buildReport()` 与 `--format json` 默认带**加性** `advice[]`（来自 `spec/remediation.json` 的 68 条规则；FAIL/WARN detail 优先，无 detail 的运行时 FAIL 用 `check.clause` 兜底）。`--no-advice` 可关闭；它不改变任何 check 的结果或 exit code。
+
 ## 2. 检查项
 
 | ID | 条款 | 层 | 说明 |
@@ -124,6 +126,19 @@ node scripts/level-audit.mjs ./my-bundle \
 - ENTRY 自动；FLOW 只读 `--flow-evidence`（J1–J8），BOOST 只读 `--boost-evidence`（LEV-1–8）。
 - 没有证据就写 `not-run` / `not-measured`，工具不会替作者升级。
 
+### FLOW 证据链 `dsh-flow-collect`
+
+```bash
+node bin/dsh-flow-collect.mjs --package ./my-plugin --out flow-evidence.json
+# 等价：node bin/dsh-levels.mjs flow collect --package ./my-plugin --out flow-evidence.json
+```
+
+- 只接受 `dsh-flow-evidence/2`（`spec/flow-evidence.schema.json`）。`level-audit --flow-evidence` 对 v1（`dsh-flow-journey/1`、`dsh-flow-runtime/1`）和裸 `{Jx:{status}}` 标 `deprecated`，不计 pass。
+- 每个 J 必须至少 1 条 `checks[]` 且全部 `exitCode === 0`、断言成立、至少一条非 `static` 观测检查，才计 pass；`static` preflight 不是 runtime，`warn`/`blocked`/`na` 都不计 8/8。
+- collector 把包复制到临时目录再跑，前后 `treeSha256` 必须一致；子进程 env 走白名单（不含 token/key/secret）；不授予 `allowBuilds`，不自动 `allow-version`。
+- 前置缺失（无 dsh、无 `--previous`、宿主兼容门禁拒绝）记 `blocked` + reason，出口码 0；真失败出口码 1，并打印五要素提示（子检查 / 命令 / exitCode / stderr 末 20 行 / 日志绝对路径 + 条款锚）。
+- 本地证据只是 `self-attested`：结构自洽 + 绑定此包 + 未过期，**不证明真跑过**，也不是沙箱、认证或安全审计。
+
 ## 4. 运行 L1–L3
 
 需要一个**已构建**的 `@deepseek-ai/cordis` 入口。检查器不修改宿主，也不从源码构建宿主：

package/40-checker/bin/dsh-flow-collect.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// FLOW collector entry point; the implementation lives in scripts/.
+import '../scripts/flow-collect.mjs'

package/40-checker/bin/dsh-levels.mjs

@@ -2,6 +2,7 @@
 /**
  * dsh-levels — one entry point for the three-level audit.
  * It forwards to level-audit.mjs so there is a single documented command.
+ * `dsh-levels flow collect ...` forwards to the FLOW evidence collector.
  */
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
@@ -9,7 +10,17 @@ import { fileURLToPath } from 'node:url'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const AUDIT = path.resolve(HERE, '..', 'scripts', 'level-audit.mjs')
+const FLOW_COLLECT = path.resolve(HERE, 'dsh-flow-collect.mjs')
 const args = process.argv.slice(2)
-if (args[0] === 'audit') args.shift()
-const run = spawnSync(process.execPath, [AUDIT, ...args], { stdio: 'inherit' })
+let target = AUDIT
+if (args[0] === 'flow' && args[1] === 'collect') {
+  args.splice(0, 2)
+  target = FLOW_COLLECT
+} else if (args[0] === 'flow') {
+  console.error('usage: dsh-levels flow collect --package <dir> [--out <file>] [--static] [--previous <dir>]')
+  process.exit(2)
+} else if (args[0] === 'audit') {
+  args.shift()
+}
+const run = spawnSync(process.execPath, [target, ...args], { stdio: 'inherit' })
 process.exitCode = run.status ?? 1

package/40-checker/fixtures/bundle-patch-only/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: fixture-bundle-server
+      name: './server.mjs'

package/40-checker/fixtures/bundle-patch-only/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@dsh-fixtures/bundle-patch-only",
+  "version": "1.0.0",
+  "license": "MIT",
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "capabilities": [],
+    "labels": []
+  }
+}

package/40-checker/fixtures/c12-command-arg/index.mjs

@@ -0,0 +1,7 @@
+import { spawnSync } from 'node:child_process'
+
+export const name = 'c12-command-arg'
+export function apply() {}
+
+// C-12.4: --add-dir is a real command-line argument here, not documentation.
+spawnSync('dsh', ['agent', '--add-dir', './docs'], { stdio: 'inherit' })

package/40-checker/fixtures/c12-command-arg/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/c12-command-arg",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/c12-comment/index.mjs

@@ -0,0 +1,3 @@
+export const name = 'c12-comment'
+export function apply() {}
+// danger-full-access belongs in a comment only

package/40-checker/fixtures/c12-comment/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/c12-comment",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/c12-compare/index.mjs

@@ -0,0 +1,3 @@
+export const name = 'c12-compare'
+export function apply() {}
+if (mode === 'danger-full-access') { /* comparison, not a grant */ }

package/40-checker/fixtures/c12-compare/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/c12-compare",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/c12-doc-string/index.mjs

@@ -0,0 +1,13 @@
+export const name = 'c12-doc-string'
+export function apply() {}
+
+// Documentation, not a grant: the literals below are labels and help text.
+const documentation = {
+  desc: 'danger-full-access',
+  description: '--add-dir',
+  help: 'danger-full-access',
+}
+
+console.log('danger-full-access')
+console.info('--add-dir')
+console.warn(`mode: ${'danger-full-access'}`)

package/40-checker/fixtures/c12-doc-string/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/c12-doc-string",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/c12-grant/index.mjs

@@ -0,0 +1,3 @@
+export const name = 'c12-grant'
+export function apply() {}
+svc.set(session, 'danger-full-access')

package/40-checker/fixtures/c12-grant/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/c12-grant",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/c12-string/index.mjs

@@ -0,0 +1,3 @@
+export const name = 'c12-string'
+export function apply() {}
+console.log('use danger-full-access for this case')

package/40-checker/fixtures/c12-string/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/c12-string",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/declaration-file/index.d.ts

@@ -0,0 +1 @@
+export declare function broken(: string

package/40-checker/fixtures/declaration-file/index.mjs

@@ -0,0 +1,9 @@
+export const name = 'fixture-declaration-file'
+export const inject = ['sessions']
+export const provide = ['declaration-file']
+
+export function apply(ctx) {
+  const sessions = ctx.sessions
+  ctx.provide('declaration-file', { hasSessions: Boolean(sessions) })
+  ctx.effect(() => () => {}, 'fixture.declaration-file.effect')
+}

package/40-checker/fixtures/declaration-file/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/declaration-file",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": ["sessions:read"], "labels": [] }
+}

package/40-checker/fixtures/import-local-side-effect/index.mjs

@@ -0,0 +1,11 @@
+import './side-effectful.mjs'
+
+export const name = 'fixture-import-local-side-effect'
+export const inject = ['sessions']
+export const provide = ['import-local-side-effect']
+
+export function apply(ctx) {
+  const sessions = ctx.sessions
+  ctx.provide('import-local-side-effect', { hasSessions: Boolean(sessions) })
+  ctx.effect(() => () => {}, 'fixture.import-local-side-effect.effect')
+}

package/40-checker/fixtures/import-local-side-effect/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@dsh-fixtures/import-local-side-effect",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "capabilities": [
+      "sessions:read"
+    ],
+    "labels": []
+  }
+}

package/40-checker/fixtures/import-local-side-effect/side-effectful.mjs

@@ -0,0 +1,5 @@
+import { writeFileSync } from 'node:fs'
+
+// C-10.3: the entry imports this module with a relative specifier, so its
+// module-scope write executes on import of the entry.
+writeFileSync('/tmp/dsh-fixture-import-local-side-effect.txt', 'x')

package/40-checker/fixtures/import-open-readonly/index.mjs

@@ -0,0 +1,14 @@
+import { openSync } from 'node:fs'
+
+export const name = 'fixture-import-open-readonly'
+export const inject = ['sessions']
+export const provide = ['import-open-readonly']
+
+export function apply(ctx) {
+  const sessions = ctx.sessions
+  ctx.provide('import-open-readonly', { hasSessions: Boolean(sessions) })
+  ctx.effect(() => () => {}, 'fixture.import-open-readonly.effect')
+}
+
+// C-10.4 is about fs *writes*; a read-only open is a different side effect.
+openSync(new URL(import.meta.url), 'r')

package/40-checker/fixtures/import-open-readonly/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dsh-fixtures/import-open-readonly",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "capabilities": ["sessions:read"],
+    "labels": []
+  }
+}

package/40-checker/fixtures/import-package-only/index.mjs

@@ -0,0 +1,11 @@
+import path from 'node:path'
+
+export const name = 'fixture-import-package-only'
+export const inject = ['sessions']
+export const provide = ['import-package-only']
+
+export function apply(ctx) {
+  const sessions = ctx.sessions
+  ctx.provide('import-package-only', { basename: path.basename('.'), hasSessions: Boolean(sessions) })
+  ctx.effect(() => () => {}, 'fixture.import-package-only.effect')
+}

package/40-checker/fixtures/import-package-only/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@dsh-fixtures/import-package-only",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "capabilities": [
+      "sessions:read"
+    ],
+    "labels": []
+  }
+}

package/40-checker/fixtures/import-parse-error/index.mjs

@@ -0,0 +1,5 @@
+export const name = 'fixture-import-parse-error'
+export function apply() {
+  // Deliberately invalid syntax: the AST check must report not-run, not PASS.
+}
+const broken = {

package/40-checker/fixtures/import-parse-error/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/import-parse-error",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/import-side-effect/index.mjs

@@ -0,0 +1,14 @@
+import { writeFileSync } from 'node:fs'
+
+export const name = 'fixture-import-side-effect'
+export const inject = ['sessions']
+export const provide = ['import-side-effect']
+
+export function apply(ctx) {
+  const sessions = ctx.sessions
+  ctx.provide('import-side-effect', { hasSessions: Boolean(sessions) })
+  ctx.effect(() => () => {}, 'fixture.import-side-effect.effect')
+}
+
+// DSC-10.4: a module-scope fs mutation, executed on import.
+writeFileSync('/tmp/dsh-fixture-import-side-effect.txt', 'x')

package/40-checker/fixtures/import-side-effect/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dsh-fixtures/import-side-effect",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "capabilities": ["sessions:read"],
+    "labels": []
+  }
+}

package/40-checker/fixtures/import-side-effect-nonentry/index.mjs

@@ -0,0 +1,9 @@
+export const name = 'fixture-import-side-effect-nonentry'
+export const inject = ['sessions']
+export const provide = ['import-side-effect-nonentry']
+
+export function apply(ctx) {
+  const sessions = ctx.sessions
+  ctx.provide('import-side-effect-nonentry', { hasSessions: Boolean(sessions) })
+  ctx.effect(() => () => {}, 'fixture.import-side-effect-nonentry.effect')
+}

package/40-checker/fixtures/import-side-effect-nonentry/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dsh-fixtures/import-side-effect-nonentry",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "capabilities": ["sessions:read"],
+    "labels": []
+  }
+}

package/40-checker/fixtures/import-side-effect-nonentry/selfcheck.mjs

@@ -0,0 +1,8 @@
+// Preflight helper shipped with the package, never imported by the entry module.
+// A module-scope fs mutation here is not an entry import-time side effect (C-10.3).
+import { mkdirSync } from 'node:fs'
+
+mkdirSync('/tmp/dsh-fixture-selfcheck', { recursive: true })
+
+// Same class of module-scope work, but still outside the entry module.
+globalThis.__dshFixtureSelfcheck = true

package/40-checker/fixtures/import-void-main/index.mjs

@@ -0,0 +1,16 @@
+export const name = 'fixture-import-void-main'
+export const inject = ['sessions']
+export const provide = ['import-void-main']
+
+export function apply(ctx) {
+  const sessions = ctx.sessions
+  ctx.provide('import-void-main', { hasSessions: Boolean(sessions) })
+  ctx.effect(() => () => {}, 'fixture.import-void-main.effect')
+}
+
+function main() {
+  return undefined
+}
+
+// C-10.2: an immediate module-scope call, expressed as `void main()`.
+void main()

package/40-checker/fixtures/import-void-main/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dsh-fixtures/import-void-main",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "capabilities": ["sessions:read"],
+    "labels": []
+  }
+}

package/40-checker/fixtures/no-source/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dsh-fixtures/no-source",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "kind": "plugin",
+    "capabilities": ["sessions:read"],
+    "labels": []
+  }
+}

package/40-checker/fixtures/parse-error-nonentry/index.mjs

@@ -0,0 +1,2 @@
+export const name = 'fixture-parse-error-nonentry'
+export function apply() {}

package/40-checker/fixtures/parse-error-nonentry/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@dsh-fixtures/parse-error-nonentry",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": { ".": "./index.mjs" },
+  "engines": { "dsh": ">=0.2.2-alpha.2 <0.3.0" },
+  "dsh": { "manifestVersion": 1, "kind": "plugin", "capabilities": [], "labels": [] }
+}

package/40-checker/fixtures/parse-error-nonentry/references/broken.js

@@ -0,0 +1 @@
+export const broken = {

package/40-checker/scripts/bundle-smoke.mjs

@@ -14,6 +14,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { scrubProcessEnv } from '../src/sandbox-env.mjs'
 
 function parse(argv) {
   const options = { package: null, host: null, base: null, web: null, bare: null, json: false, timeout: 30_000 }
@@ -42,6 +43,8 @@ function withTimeout(promise, ms, label) {
 }
 
 async function main() {
+  // Boot happens in this process: drop secrets before any plugin import.
+  scrubProcessEnv()
   const options = parse(process.argv.slice(2))
   const pkg = path.resolve(options.package)
   const manifest = JSON.parse(fs.readFileSync(path.join(pkg, 'package.json'), 'utf8'))

package/40-checker/scripts/entry18-ci.mjs

@@ -58,6 +58,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { sanitizedEnv } from '../src/sandbox-env.mjs'
 import { fileURLToPath } from 'node:url'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
@@ -153,16 +154,16 @@ function run(command, args, { cwd, timeout, env } = {}) {
     encoding: 'utf8',
     maxBuffer: 64 * 1024 * 1024,
     killSignal: 'SIGKILL',
-    env: {
-      ...process.env,
+    env: sanitizedEnv({
       NO_COLOR: '1',
       npm_config_update_notifier: 'false',
       // Bound registry waits so one unresponsive metadata request cannot wedge
       // a shard past its job timeout.
       npm_config_fetch_timeout: '60000',
       npm_config_fetch_retries: '2',
+      ...(process.env.DSH_HOME ? { DSH_HOME: process.env.DSH_HOME } : {}),
       ...env,
-    },
+    }),
   })
   return {
     command,

package/40-checker/scripts/entry18-web.mjs

@@ -17,6 +17,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { sanitizedEnv, scrubProcessEnv } from '../src/sandbox-env.mjs'
 import { fileURLToPath } from 'node:url'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
@@ -87,7 +88,7 @@ function run(command, args, { cwd, timeout, env } = {}) {
     timeout,
     encoding: 'utf8',
     maxBuffer: 64 * 1024 * 1024,
-    env: { ...process.env, NO_COLOR: '1', ...env },
+    env: sanitizedEnv({ NO_COLOR: '1', ...(process.env.DSH_HOME ? { DSH_HOME: process.env.DSH_HOME } : {}), ...env }),
   })
   return {
     status: result.status,
@@ -159,6 +160,8 @@ function targetRows(pkgDir, manifest, loadOverlayPatches, composeEntries) {
 
 async function main() {
   const options = parseArgs(process.argv.slice(2))
+  // This harness boots the sample in-process; drop secrets before any import.
+  scrubProcessEnv()
   const startedAt = new Date().toISOString()
   const work = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-entry18-web-'))
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-entry18-home-'))