dsh-standards 1.2.1 → 1.2.2

package/40-checker/README.md

@@ -131,13 +131,18 @@ node scripts/level-audit.mjs ./my-bundle \
 ```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
+# 隔离运行（unshare 无网 + prlimit + 进程组超时杀树 + 白名单 env）：
+node bin/dsh-flow-collect.mjs --package ./my-plugin --sandbox --out flow-evidence.json
+# 等价：node bin/dsh-levels.mjs flow sandbox --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`。
+- collector 把包复制到临时目录再跑，前后 `treeSha256` 必须一致；`treeStable:false` 或 `treeSha256After` 不同直接判证据无效（invalid），不是 warn。子进程 env 走白名单（不含 token/key/secret）；不授予 `allowBuilds`，不自动 `allow-version`。
+- `--sandbox` 在临时 HOME/DSH_HOME 下跑 `dsh plugin add` + boot：先试 `unshare -n`，不行再试 `unshare -Urn`；用 `prlimit` 设 `nproc`/`as` 并从 `/proc/self/limits` 回读实际生效项；超时 SIGKILL 整个进程组（Windows `taskkill /T /F`）。硬断言 `GH_TOKEN`/`NPM_TOKEN`/`GITHUB_TOKEN` 不在子进程 env，发现即中止。
+- 只有**所有**隔离项都生效才写 `producer.kind=sandbox` / `claims.claimLevel=sandbox-attested`；任何一项缺失（`unshare-missing`、`prlimit-missing`、`env-token-present`、`home-not-isolated`）写 `sandbox-degraded` + `sandbox.degraded[]`，仍是 self-attested，`level-audit` 永不判 runtime。`--sandbox-no-network` / `--sandbox-no-limits` 用于强制验证降级路径。
 - 前置缺失（无 dsh、无 `--previous`、宿主兼容门禁拒绝）记 `blocked` + reason，出口码 0；真失败出口码 1，并打印五要素提示（子检查 / 命令 / exitCode / stderr 末 20 行 / 日志绝对路径 + 条款锚）。
-- 本地证据只是 `self-attested`：结构自洽 + 绑定此包 + 未过期，**不证明真跑过**，也不是沙箱、认证或安全审计。`level-audit` 只有见到 `claims.claimLevel=sandbox-attested` 或 `producer.kind=sandbox` 才判 `runtime`；self/ci 证据保留 `passed` 计数但记 `not-run`。
+- 本地证据默认 `self-attested`：结构自洽 + 绑定此包 + 未过期，**不证明真跑过**。即使 `--sandbox` 通过，它也只是 containment（无 seccomp/cgroup/OCI 镜像/签名），不是认证或安全审计。`level-audit` 只有见到 `claims.claimLevel=sandbox-attested` 或 `producer.kind=sandbox` 才判 `runtime`；self/ci/degraded 证据保留 `passed` 计数但记 `not-run`。
 
 ## 4. 运行 L1–L3
 

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

@@ -16,8 +16,14 @@ let target = AUDIT
 if (args[0] === 'flow' && args[1] === 'collect') {
   args.splice(0, 2)
   target = FLOW_COLLECT
+} else if (args[0] === 'flow' && args[1] === 'sandbox') {
+  // Convenience alias for `flow collect --sandbox`.
+  args.splice(0, 2)
+  args.unshift('--sandbox')
+  target = FLOW_COLLECT
 } else if (args[0] === 'flow') {
-  console.error('usage: dsh-levels flow collect --package <dir> [--out <file>] [--static] [--previous <dir>]')
+  console.error('usage: dsh-levels flow collect --package <dir> [--out <file>] [--static|--sandbox] [--previous <dir>]')
+  console.error('       dsh-levels flow sandbox --package <dir> [--out <file>]   (= flow collect --sandbox)')
   process.exit(2)
 } else if (args[0] === 'audit') {
   args.shift()

package/40-checker/scripts/flow-collect.mjs

@@ -9,9 +9,14 @@
  *   2. copy the package to a temp dir and run every journey against that copy
  *      only; the original directory is never written;
  *   3. static preflight (`journey.mjs`) for J1-J8, then the runtime probe
- *      (`journey-runtime.mjs`) for J1/J2/J4/J6 with a temp HOME/DSH_HOME and
- *      an allowlisted child env;
- *   4. re-hash the original tree and record `subject.treeStable`;
+ *      (`journey-runtime.mjs`, which runs `dsh plugin add` and boots the tree)
+ *      with a temp HOME/DSH_HOME and an allowlisted child env; with
+ *      `--sandbox` the runtime probe runs behind `unshare` (network),
+ *      `prlimit` (nproc/as), and a process-group timeout that kills the whole
+ *      tree. Any missing isolation item makes `producer.kind`
+ *      `sandbox-degraded`, which is never runtime;
+ *   4. re-hash the original tree and record `subject.treeStable`; a changed
+ *      tree invalidates the evidence;
  *   5. write the JSON, per-check logs, the chain hash, and SHA256SUMS.
  *
  * Missing prerequisites (no dsh, no --previous, host compatibility gate
@@ -22,7 +27,8 @@
  * Usage:
  *   node 40-checker/bin/dsh-flow-collect.mjs --package <dir> [--out flow-evidence.json]
  *     [--logs <dir>] [--previous <dir>] [--dsh <bin>] [--timeout <ms>]
- *     [--static] [--ci] [--json]
+ *     [--static] [--ci] [--sandbox [--sandbox-no-network] [--sandbox-no-limits]
+ *     [--sandbox-nproc <n>] [--sandbox-as <bytes>]] [--json]
  */
 import fs from 'node:fs'
 import os from 'node:os'
@@ -34,6 +40,9 @@ import {
   sha256File, sha256Value, treeSha256, validateFlowEvidence,
 } from '../src/flow-evidence.mjs'
 import { sanitizedEnv } from '../src/sandbox-env.mjs'
+import {
+  assertNoCredentialEnv, buildSandboxPlan, runInProcessTree, sandboxArgv,
+} from '../src/sandbox-run.mjs'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const STD = path.resolve(HERE, '..', '..')
@@ -68,6 +77,14 @@ Options:
   --timeout <ms>        per-command budget (default: 120000)
   --static              skip the runtime probe (J1/J2/J4/J6 become static/blocked)
   --ci                  mark producer.kind=ci, claims.claimLevel=ci-attested
+  --sandbox             run the runtime probe under unshare/prlimit/process-group
+                        timeout with an allowlisted env; producer.kind=sandbox only
+                        when every isolation item is effective (otherwise
+                        sandbox-degraded, never runtime)
+  --sandbox-no-network  force the degraded path (records unshare-missing)
+  --sandbox-no-limits   force the degraded path (records prlimit-missing)
+  --sandbox-nproc <n>   RLIMIT_NPROC (default: current task count + headroom)
+  --sandbox-as <bytes>  RLIMIT_AS (default: 4 GiB)
   --no-assert-unchanged skip the before/after tree hash comparison (not recommended)
   --json                print the evidence JSON instead of the summary
   --help                show this help
@@ -82,6 +99,8 @@ function parse(argv) {
     package: null, out: path.resolve('flow-evidence.json'), logs: null, previous: null,
     dsh: process.env.DSH_BIN || null, timeout: 120_000, static: false, ci: false,
     assertUnchanged: true, json: false,
+    sandbox: false, sandboxNoNetwork: false, sandboxNoLimits: false,
+    sandboxNproc: null, sandboxAs: 4 * 1024 ** 3,
   }
   for (let i = 0; i < argv.length; i += 1) {
     const next = () => {
@@ -99,6 +118,11 @@ function parse(argv) {
     else if (arg === '--timeout') out.timeout = Number(next())
     else if (arg === '--static' || arg === '--no-runtime') out.static = true
     else if (arg === '--ci') out.ci = true
+    else if (arg === '--sandbox') out.sandbox = true
+    else if (arg === '--sandbox-no-network' || arg === '--no-sandbox-network') out.sandboxNoNetwork = true
+    else if (arg === '--sandbox-no-limits' || arg === '--no-sandbox-limits') out.sandboxNoLimits = true
+    else if (arg === '--sandbox-nproc') out.sandboxNproc = Number(next())
+    else if (arg === '--sandbox-as') out.sandboxAs = Number(next())
     else if (arg === '--no-assert-unchanged') out.assertUnchanged = false
     else if (arg === '--json') out.json = true
     else if (arg === '--help' || arg === '-h') { usage(); process.exit(0) }
@@ -106,6 +130,10 @@ function parse(argv) {
   }
   if (!out.package) throw new Error('--package is required')
   if (!Number.isFinite(out.timeout) || out.timeout < 1000) throw new Error('--timeout must be >= 1000')
+  if (out.sandboxNproc !== null && (!Number.isFinite(out.sandboxNproc) || out.sandboxNproc < 2)) throw new Error('--sandbox-nproc must be >= 2')
+  if (!Number.isFinite(out.sandboxAs) || out.sandboxAs < 64 * 1024 * 1024) throw new Error('--sandbox-as must be >= 67108864')
+  if (out.sandbox && out.static) throw new Error('--sandbox cannot be combined with --static')
+  if (out.sandbox && out.ci) throw new Error('--sandbox cannot be combined with --ci (a sandboxed run is sandbox-attested)')
   return out
 }
 
@@ -144,7 +172,7 @@ function writeLog(logDir, name, text) {
   return { file, sha256: sha256Value(text ?? '') }
 }
 
-function main() {
+async function main() {
   const options = parse(process.argv.slice(2))
   const pkg = path.resolve(options.package)
   if (!fs.existsSync(path.join(pkg, 'package.json'))) throw new Error(`not a package directory: ${pkg}`)
@@ -162,12 +190,25 @@ function main() {
   fs.mkdirSync(tmpHome, { recursive: true })
   fs.mkdirSync(tmpCache, { recursive: true })
   const childEnv = () => sanitizedEnv({
-    HOME: tmpHome, USERPROFILE: tmpHome, TMPDIR: path.join(tmpRoot, 'tmp'), TEMP: path.join(tmpRoot, 'tmp'), TMP: path.join(tmpRoot, 'tmp'),
+    HOME: tmpHome, DSH_HOME: tmpHome, USERPROFILE: tmpHome, TMPDIR: path.join(tmpRoot, 'tmp'), TEMP: path.join(tmpRoot, 'tmp'), TMP: path.join(tmpRoot, 'tmp'),
     npm_config_cache: tmpCache, npm_config_audit: 'false', npm_config_fund: 'false', npm_config_update_notifier: 'false',
   })
+  // The sandbox is planned before any plugin code runs. `assertNoCredentialEnv`
+  // is a hard gate: a surviving token aborts collection instead of booting with it.
+  let sandboxPlan = null
 
   const warnings = []
   try {
+    if (options.sandbox) {
+      assertNoCredentialEnv(childEnv())
+      sandboxPlan = buildSandboxPlan({
+        env: childEnv(),
+        nproc: options.sandboxNproc,
+        asBytes: options.sandboxAs,
+        force: { network: options.sandboxNoNetwork, limits: options.sandboxNoLimits },
+      })
+      sandboxPlan.env = assertNoCredentialEnv(childEnv())
+    }
     // 0. Never let our own output/log dirs count as a tree change.
     const treeExclude = []
     for (const candidate of [outFile, logDir]) {
@@ -245,13 +286,59 @@ function main() {
     if (options.static) runtimeSkipped = 'runtime collection disabled (--static)'
     else if (dshVersion === null) runtimeSkipped = `dsh executable not usable: ${dshBin} (exit ${versionRun.exitCode})`
     let runtimeVerdict = null
+    let sandboxExecution = null
     if (runtimeSkipped === null) {
       const args = [JOURNEY_RUNTIME, '--package', copy, '--dsh', dshBin, '--json', '--log-dir', logDir, '--timeout', String(options.timeout)]
       if (previousCopy) args.push('--previous', previousCopy)
-      const runtimeRun = run(process.execPath, args, { env: childEnv(), timeout: options.timeout * 2 + 60_000 })
-      writeLog(logDir, 'runtime-journey.json', runtimeRun.stdoutText)
-      if (runtimeRun.stderrText) writeLog(logDir, 'runtime-journey.err.log', runtimeRun.stderrText)
-      try { runtimeVerdict = JSON.parse(runtimeRun.stdoutText) } catch { runtimeSkipped = `runtime probe produced no JSON (exit ${runtimeRun.exitCode}): ${tailLines(runtimeRun.stderrText, 5)}` }
+      let runtimeRun
+      if (sandboxPlan) {
+        // journey-runtime spawns `dsh plugin add` and the boot as its own
+        // children; they inherit this process group and network namespace.
+        const argv = sandboxArgv(sandboxPlan, process.execPath, args)
+        runtimeRun = await runInProcessTree({
+          command: argv[0],
+          args: argv.slice(1),
+          cwd: copy,
+          env: childEnv(),
+          timeoutMs: options.timeout * 2 + 60_000,
+        })
+        sandboxExecution = {
+          command: argv,
+          exitCode: runtimeRun.exitCode,
+          timedOut: runtimeRun.timedOut,
+          killed: runtimeRun.killed,
+          spawnError: runtimeRun.spawnError ?? null,
+          durationMs: runtimeRun.durationMs,
+          pid: runtimeRun.pid ?? null,
+          processTree: {
+            mechanism: runtimeRun.treeKill?.mechanism ?? sandboxPlan.processTreeKill.mechanism,
+            signalled: runtimeRun.treeKill?.signalled ?? null,
+            cleared: runtimeRun.treeKill?.cleared ?? null,
+          },
+        }
+        if (runtimeRun.spawnError) {
+          // The probe passed but the sandboxed spawn itself failed: do not keep
+          // calling this run `sandbox`.
+          sandboxPlan.degraded = [...new Set([...sandboxPlan.degraded, 'sandbox-execution-failed'])]
+          sandboxPlan.mode = 'sandbox-degraded'
+        }
+        if (runtimeRun.timedOut) {
+          runtimeSkipped = `sandboxed runtime probe timed out after ${options.timeout * 2 + 60_000} ms; whole process tree killed (${sandboxExecution.processTree.mechanism}, cleared=${sandboxExecution.processTree.cleared})`
+        }
+      } else {
+        runtimeRun = run(process.execPath, args, { env: childEnv(), timeout: options.timeout * 2 + 60_000 })
+      }
+      const stdoutText = runtimeRun.stdoutText ?? runtimeRun.stdout ?? ''
+      const stderrText = runtimeRun.stderrText ?? runtimeRun.stderr ?? ''
+      writeLog(logDir, 'runtime-journey.json', stdoutText)
+      if (stderrText) writeLog(logDir, 'runtime-journey.err.log', stderrText)
+      if (runtimeSkipped === null) {
+        try {
+          runtimeVerdict = JSON.parse(stdoutText)
+        } catch {
+          runtimeSkipped = `runtime probe produced no JSON (exit ${runtimeRun.exitCode}): ${tailLines(stderrText, 5)}`
+        }
+      }
       if (runtimeVerdict) {
         for (const check of runtimeVerdict.checks ?? []) {
           const mapped = toEvidenceCheck(check, logDir, toEvidencePath)
@@ -267,6 +354,9 @@ function main() {
         }
       }
     }
+    if (sandboxPlan) {
+      writeLog(logDir, 'sandbox-plan.json', JSON.stringify({ ...sandboxPlan, execution: sandboxExecution }, null, 2))
+    }
     if (runtimeSkipped !== null) warnings.push(`runtime probe skipped: ${runtimeSkipped}`)
 
     // 6. Journey statuses + reasons (never upgrade a skip to a pass).
@@ -342,18 +432,40 @@ function main() {
       ? 'flow-fail'
       : statuses.includes('blocked') ? 'flow-blocked' : statuses.every(status => status === 'pass') ? 'flow-pass' : 'flow-warn'
     const producerCommand = [process.execPath, path.relative(STD, fileURLToPath(import.meta.url)).split(path.sep).join('/'), ...process.argv.slice(2)]
+    const sandboxExecuted = Boolean(sandboxExecution)
+    const sandboxKind = sandboxPlan && sandboxExecuted
+      ? (sandboxPlan.degraded.length === 0 ? 'sandbox' : 'sandbox-degraded')
+      : null
+    const producerKind = sandboxKind ?? (options.ci ? 'ci' : 'local')
+    const notClaimed = [...NOT_CLAIMED]
+    if (sandboxKind === 'sandbox') {
+      const localIndex = notClaimed.findIndex(item => item.startsWith('sandbox confinement'))
+      if (localIndex >= 0) notClaimed.splice(localIndex, 1)
+      notClaimed.push('OCI/container image, seccomp, and cgroup memory/pids limits (not implemented)', 'signature (not produced)')
+    } else if (sandboxKind === 'sandbox-degraded') {
+      notClaimed.push(`sandbox confinement (degraded: ${sandboxPlan.degraded.join(', ')})`)
+    }
+    const claimLevel = sandboxKind === 'sandbox' ? 'sandbox-attested' : options.ci ? 'ci-attested' : 'self-attested'
+    const method = sandboxKind === 'sandbox'
+      ? 'sandboxed collector: allowlisted env (no tokens), temporary HOME/DSH_HOME, network+user namespace, prlimit nproc/as, process-group SIGKILL timeout'
+      : sandboxKind === 'sandbox-degraded'
+        ? `sandboxed collector DEGRADED (${sandboxPlan.degraded.join(', ')}): allowlisted env, temporary HOME/DSH_HOME, process-group SIGKILL timeout; every missing isolation item is recorded`
+        : 'local-collector: read-only copy, allowlisted child env, no allowBuilds, no exemption'
+    const sandbox = sandboxPlan ? { ...sandboxPlan, executed: sandboxExecuted, execution: sandboxExecution } : null
     const document = finalizeEvidence({
       schema: FLOW_EVIDENCE_SCHEMA,
       generatedAt,
-      producer: { command: producerCommand, at: generatedAt, kind: options.ci ? 'ci' : 'local', runner: 'flow-collect/1' },
+      producer: {
+        command: producerCommand,
+        at: generatedAt,
+        kind: producerKind,
+        runner: sandboxPlan ? 'flow-collect/2-sandbox' : 'flow-collect/1',
+      },
+      ...(sandbox ? { sandbox } : {}),
       subject,
       host,
       journeys,
-      claims: {
-        claimLevel: options.ci ? 'ci-attested' : 'self-attested',
-        notClaimed: NOT_CLAIMED,
-        method: 'local-collector: read-only copy, allowlisted child env, no allowBuilds, no exemption',
-      },
+      claims: { claimLevel, notClaimed, method },
       conclusion,
     })
     const verdict = validateFlowEvidence(document)
@@ -385,8 +497,17 @@ function main() {
         `  totals   : ${JSON.stringify(counts)}`,
         `  conclusion: ${conclusion}`,
         `  chain    : ${document.chain.evidenceHash}`,
+        ...(sandboxPlan ? [
+          `  sandbox  : ${sandboxPlan.mode}${sandboxPlan.degraded.length > 0 ? ` degraded=[${sandboxPlan.degraded.join(', ')}]` : ''}`,
+          `             env=${sandboxPlan.env.policy} tokens-absent=${sandboxPlan.env.absent} network=${sandboxPlan.network.isolated ? sandboxPlan.network.mechanism : 'off'} limits=${sandboxPlan.limits.available ? sandboxPlan.limits.applied.join('+') : 'off'} home=${sandboxPlan.home.isolated ? 'temp' : 'real'}`,
+          `             execution=${sandboxExecuted ? `exit=${sandboxExecution.exitCode} timedOut=${sandboxExecution.timedOut} killed=${sandboxExecution.killed} treeCleared=${sandboxExecution.processTree.cleared}` : 'not-run'}`,
+        ] : []),
         `  logs     : ${logDir} (+ ${path.join(outDir, 'SHA256SUMS')})`,
-        'Claims: self-attested structure + binding only; no certification, no security audit, not a sandbox.',
+        sandboxKind === 'sandbox'
+          ? 'Claims: sandbox-attested (containment only; no OCI image, seccomp, cgroup, signature); not a certification or security audit.'
+          : sandboxKind === 'sandbox-degraded'
+            ? `Claims: self-attested; sandbox DEGRADED (${sandboxPlan.degraded.join(', ')}). Degraded evidence is never FLOW runtime.`
+            : 'Claims: self-attested structure + binding only; no certification, no security audit, not a sandbox.',
       ]
       if (warnings.length > 0) {
         lines.push('Warnings:')
@@ -486,9 +607,7 @@ function collectHints(journeyId, checks, hints, outDir, logDir, toEvidencePath)
   }
 }
 
-try {
-  main()
-} catch (error) {
+main().catch(error => {
   console.error(`flow-collect: ${error.message}`)
   process.exitCode = 3
-}
+})

package/40-checker/scripts/level-audit.mjs

@@ -167,6 +167,8 @@ function classifyFlow(evidence) {
       schema: null,
       claimLevel: null,
       producerKind: null,
+      sandboxMode: null,
+      sandboxDegraded: [],
       sandboxAttested: false,
       deprecated: false,
       invalid: false,
@@ -186,6 +188,8 @@ function classifyFlow(evidence) {
     schema: verdict.schema,
     claimLevel: verdict.claimLevel ?? null,
     producerKind: verdict.producerKind ?? null,
+    sandboxMode: verdict.sandbox?.mode ?? null,
+    sandboxDegraded: verdict.sandbox?.degraded ?? [],
     sandboxAttested: verdict.sandboxAttested === true,
     deprecated: verdict.kind === 'v1-deprecated' || verdict.kind === 'legacy',
     invalid: false,
@@ -245,7 +249,11 @@ function classifyFlow(evidence) {
         ? 'runtime'
         : 'not-run'
   const reasons = []
-  if (!runtimeEligible && failed.length === 0) {
+  const degraded = Array.isArray(base.sandboxDegraded) ? base.sandboxDegraded : []
+  if (degraded.length > 0) {
+    reasons.push(`sandbox-degraded (${degraded.join(', ')}); runtime requires every isolation item effective`)
+  }
+  if (!runtimeEligible && failed.length === 0 && degraded.length === 0) {
     reasons.push(`${base.claimLevel ?? 'non-sandbox'} evidence; runtime requires sandbox-attested`)
   }
   if (failed.length > 0) reasons.push(`failed journeys: ${failed.join(', ')}`)
@@ -362,7 +370,9 @@ function nextActions(entry, flow, boost) {
   if (entry.g4 && entry.g4.hasClient && entry.g4.ok === false) actions.push(`ENTRY: fix G4 — ${entry.g4.reason}`)
   for (const warning of entry.warnings) actions.push(`ENTRY: consider ${warning.id} — ${warning.reason}`)
   if (entry.state === 'recognized') actions.push('ENTRY: run with --host to replace static recognition with a real G0-G3 boot')
-  if (flow.state === 'not-run' && flow.claimLevel && flow.sandboxAttested !== true) {
+  if (flow.sandboxDegraded?.length > 0) {
+    actions.push(`FLOW: sandbox degraded (${flow.sandboxDegraded.join(', ')}); re-run where unshare and prlimit are effective; degraded evidence is never runtime`)
+  } else if (flow.state === 'not-run' && flow.claimLevel && flow.sandboxAttested !== true) {
     actions.push(`FLOW: ${flow.claimLevel} evidence keeps ${flow.passed}/8 journey passes but is not runtime; re-run under a sandbox and set claims.claimLevel=sandbox-attested (or producer.kind=sandbox)`)
   } else if (flow.state === 'not-run') {
     actions.push('FLOW: record J1-J8 with node 40-checker/bin/dsh-flow-collect.mjs; do not claim FLOW until they run')

package/40-checker/scripts/run-tests.mjs

@@ -0,0 +1,21 @@
+// Runs the checker tests when the dev-only test tree is present. The npm package
+// does not ship 40-checker/test, so an installed copy must not fail `npm test`
+// on a missing directory.
+import { existsSync, readdirSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const testDir = join(here, '..', 'test')
+if (!existsSync(testDir)) {
+  console.log('checker tests are not shipped in the npm package; nothing to run')
+  process.exit(0)
+}
+const files = readdirSync(testDir).filter((f) => f.endsWith('.test.mjs')).map((f) => join(testDir, f))
+if (files.length === 0) {
+  console.log('no test files found; nothing to run')
+  process.exit(0)
+}
+const r = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit' })
+process.exit(r.status ?? 1)

package/40-checker/src/flow-evidence.mjs

@@ -19,6 +19,9 @@
  * `producer.kind === 'sandbox'`) may be reported as `flow.state = 'runtime'`.
  * `self-attested`/`ci-attested` documents keep their `passed` count but stay
  * `not-run`, because structural validation cannot prove where commands ran.
+ * A `sandbox-degraded` producer (any isolation item missing) is never runtime,
+ * and a document whose `subject.treeStable` is false is structurally invalid:
+ * a collector that changed the inspected tree has no trustworthy evidence.
  */
 import crypto from 'node:crypto'
 import fs from 'node:fs'
@@ -178,6 +181,11 @@ export function journeyCountsAsPass(journey) {
  */
 export function isSandboxAttested(document) {
   if (!isPlainObject(document)) return false
+  // Degradation is disqualifying even if a claim was left at sandbox-attested:
+  // the producer admits an isolation item was missing.
+  if (document.producer?.kind === 'sandbox-degraded') return false
+  if (document.sandbox?.mode === 'sandbox-degraded') return false
+  if (Array.isArray(document.sandbox?.degraded) && document.sandbox.degraded.length > 0) return false
   return document.claims?.claimLevel === 'sandbox-attested' || document.producer?.kind === 'sandbox'
 }
 
@@ -268,8 +276,8 @@ function validateV2(document) {
     if (!Array.isArray(command) || command.length === 0 || command.some(item => typeof item !== 'string')) {
       errors.push('producer.command must be a non-empty array of strings')
     }
-    if ('kind' in document.producer && document.producer.kind !== null && !['local', 'ci', 'sandbox'].includes(document.producer.kind)) {
-      errors.push('producer.kind must be local, ci, or sandbox')
+    if ('kind' in document.producer && document.producer.kind !== null && !['local', 'ci', 'sandbox', 'sandbox-degraded'].includes(document.producer.kind)) {
+      errors.push('producer.kind must be local, ci, sandbox, or sandbox-degraded')
     }
     for (const key of ['runner', 'actor', 'runUrl']) {
       if (key in document.producer && document.producer[key] !== null) requireString(document.producer[key], `producer.${key}`)
@@ -292,6 +300,12 @@ function validateV2(document) {
       }
     }
     if ('source' in subject) requireString(subject.source, 'subject.source')
+    if (subject.treeStable === false) {
+      errors.push('subject.treeStable is false: the package tree changed during collection')
+    }
+    if ('treeSha256After' in subject && subject.treeSha256After && subject.treeSha256After !== subject.treeSha256 && subject.treeStable !== false) {
+      errors.push('subject.treeSha256After differs from subject.treeSha256: the package tree changed during collection')
+    }
   }
 
   if (requireObject(document.host, 'host')) {
@@ -344,6 +358,8 @@ function validateV2(document) {
     if ('method' in claims) requireString(claims.method, 'claims.method')
   }
 
+  validateSandbox(document, errors)
+
   if (requireObject(document.chain, 'chain')) {
     requireHash(document.chain.evidenceHash, 'chain.evidenceHash')
     for (const key of Object.keys(document.chain)) if (key !== 'evidenceHash') errors.push(`chain.${key} is not allowed`)
@@ -389,9 +405,74 @@ function validateV2(document) {
     conclusion: document.conclusion ?? null,
     claimLevel: isPlainObject(document.claims) ? document.claims.claimLevel ?? null : null,
     producerKind: isPlainObject(document.producer) ? document.producer.kind ?? null : null,
+    sandbox: isPlainObject(document.sandbox)
+      ? {
+        mode: document.sandbox.mode ?? null,
+        degraded: Array.isArray(document.sandbox.degraded) ? [...document.sandbox.degraded] : [],
+      }
+      : null,
     sandboxAttested: isSandboxAttested(document),
   }
 
+  function validateSandbox(doc, errors) {
+    const kind = isPlainObject(doc.producer) ? doc.producer.kind ?? null : null
+    const declaredSandbox = 'sandbox' in doc
+    if (!declaredSandbox && kind !== 'sandbox' && kind !== 'sandbox-degraded') return
+    if (!declaredSandbox) {
+      errors.push('sandbox is required when producer.kind is sandbox or sandbox-degraded')
+      return
+    }
+    const sandbox = doc.sandbox
+    if (!isPlainObject(sandbox)) {
+      errors.push('sandbox must be an object')
+      return
+    }
+    if (!['sandbox', 'sandbox-degraded'].includes(sandbox.mode)) {
+      errors.push('sandbox.mode must be sandbox or sandbox-degraded')
+    }
+    const degraded = Array.isArray(sandbox.degraded) ? sandbox.degraded : null
+    if (!degraded || degraded.some(item => typeof item !== 'string' || item.length === 0)) {
+      errors.push('sandbox.degraded must be an array of non-empty strings')
+    }
+    const list = degraded ?? []
+    if (sandbox.mode === 'sandbox' && list.length > 0) errors.push('sandbox.mode is sandbox but sandbox.degraded is not empty')
+    if (sandbox.mode === 'sandbox-degraded' && list.length === 0) errors.push('sandbox.mode is sandbox-degraded but sandbox.degraded is empty')
+    if ('env' in sandbox) {
+      if (!isPlainObject(sandbox.env)) errors.push('sandbox.env must be an object')
+      else if (typeof sandbox.env.absent !== 'boolean') errors.push('sandbox.env.absent must be a boolean')
+    }
+    if ('network' in sandbox && (!isPlainObject(sandbox.network) || typeof sandbox.network.isolated !== 'boolean')) {
+      errors.push('sandbox.network.isolated must be a boolean')
+    }
+    if ('limits' in sandbox) {
+      if (!isPlainObject(sandbox.limits)) errors.push('sandbox.limits must be an object')
+      else {
+        if ('available' in sandbox.limits && typeof sandbox.limits.available !== 'boolean') errors.push('sandbox.limits.available must be a boolean')
+        if ('applied' in sandbox.limits && (!Array.isArray(sandbox.limits.applied) || sandbox.limits.applied.some(item => typeof item !== 'string'))) {
+          errors.push('sandbox.limits.applied must be an array of strings')
+        }
+      }
+    }
+    if ('home' in sandbox && (!isPlainObject(sandbox.home) || typeof sandbox.home.isolated !== 'boolean')) {
+      errors.push('sandbox.home.isolated must be a boolean')
+    }
+    if ('executed' in sandbox && typeof sandbox.executed !== 'boolean') errors.push('sandbox.executed must be a boolean')
+    if (kind === 'sandbox') {
+      if (sandbox.mode !== 'sandbox') errors.push('producer.kind=sandbox requires sandbox.mode=sandbox')
+      if (list.length > 0) errors.push('producer.kind=sandbox requires an empty sandbox.degraded list')
+      if (sandbox.executed !== true) errors.push('producer.kind=sandbox requires sandbox.executed=true')
+      if (sandbox.env?.absent !== true) errors.push('producer.kind=sandbox requires sandbox.env.absent=true')
+      if (sandbox.network?.isolated !== true) errors.push('producer.kind=sandbox requires sandbox.network.isolated=true')
+      if (sandbox.limits?.available !== true) errors.push('producer.kind=sandbox requires sandbox.limits.available=true')
+      if (sandbox.home?.isolated !== true) errors.push('producer.kind=sandbox requires sandbox.home.isolated=true')
+    }
+    if (kind === 'sandbox-degraded') {
+      if (sandbox.mode !== 'sandbox-degraded') errors.push('producer.kind=sandbox-degraded requires sandbox.mode=sandbox-degraded')
+      if (list.length === 0) errors.push('producer.kind=sandbox-degraded requires at least one sandbox.degraded reason')
+      if (doc.claims?.claimLevel === 'sandbox-attested') errors.push('producer.kind=sandbox-degraded cannot claim sandbox-attested')
+    }
+  }
+
   function validateCheck(check, label) {
     if (!isPlainObject(check)) {
       errors.push(`${label} must be an object`)