dsh-standards 1.2.1 → 1.3.0

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'
@@ -30,10 +36,13 @@ import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import {
-  FLOW_IDS, FLOW_EVIDENCE_SCHEMA, clauseAnchor, finalizeEvidence, journeyAggregate,
+  FLOW_IDS, FLOW_EVIDENCE_SCHEMA, ciAttribution, clauseAnchor, finalizeEvidence, journeyAggregate,
   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,15 @@ 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
+                        (CI attribution is also read from GITHUB_* and stays self-declared)
+  --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 +100,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 +119,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 +131,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 +173,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 +191,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 +287,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 +355,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 +433,45 @@ 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
+    // CI attribution is display-only and self-declared. It is recorded from the
+    // runner environment even without --ci; it never upgrades the claim level.
+    const ci = ciAttribution()
+    const ciFields = ci ? Object.fromEntries(Object.entries(ci).filter(([, value]) => value !== 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',
+        ...ciFields,
+      },
+      ...(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 +503,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 +613,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

@@ -31,7 +31,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
-import { FLOW_IDS, FLOW_EVIDENCE_SCHEMA, validateFlowEvidence } from '../src/flow-evidence.mjs'
+import { FLOW_IDS, FLOW_EVIDENCE_SCHEMA, bindEvidenceSubject, validateFlowEvidence } from '../src/flow-evidence.mjs'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const STD = path.resolve(HERE, '..', '..')
@@ -52,6 +52,10 @@ Options:
   --flow-evidence <file>   dsh-flow-evidence/2 JSON from dsh-flow-collect.mjs (J1-J8 checks
                             with command/exitCode/times/stdout sha256/assertions). v1 and bare
                             {Jx:{status}} files are reported deprecated and never count as pass.
+  --dir <dir>              bind the flow evidence to this package directory: name/version,
+                            recomputed treeSha256 and npm-pack tarball hash must match the
+                            evidence subject, otherwise FLOW becomes invalid. If the positional
+                            directory is omitted, --dir is used for the ENTRY check too.
   --boost-evidence <file>  JSON: { "LEV-3": { "status": "measured|not-measured|failed", "evidenceCard": { ... } }, ... }
                             measured requires a valid evidence card; a status-only row is downgraded to not-measured
   --timeout <ms>           checker timeout, default 150000
@@ -65,7 +69,7 @@ are reported as not-run / not-measured.`)
 
 function parseArgs(argv) {
   const options = {
-    dir: null, host: null, base: null, bare: null, runtime: true,
+    dir: null, bindDir: null, host: null, base: null, bare: null, runtime: true,
     flowEvidence: null, boostEvidence: null, timeout: 150_000,
     format: 'text', out: null,
   }
@@ -82,6 +86,7 @@ function parseArgs(argv) {
     else if (arg === '--bare') options.bare = next()
     else if (arg === '--no-runtime') options.runtime = false
     else if (arg === '--flow-evidence') options.flowEvidence = next()
+    else if (arg === '--dir') options.bindDir = next()
     else if (arg === '--boost-evidence') options.boostEvidence = next()
     else if (arg === '--timeout') options.timeout = Number(next())
     else if (arg === '--format') options.format = next()
@@ -91,11 +96,17 @@ function parseArgs(argv) {
     else if (options.dir === null) options.dir = arg
     else throw new Error(`unexpected argument: ${arg}`)
   }
-  if (!options.dir) throw new Error('a plugin directory is required')
+  if (options.bindDir !== null && options.dir !== null && path.resolve(options.bindDir) !== path.resolve(options.dir)) {
+    throw new Error('the positional directory and --dir point at different packages')
+  }
+  if (!options.dir) options.dir = options.bindDir
+  if (!options.dir) throw new Error('a plugin directory is required (positional or --dir)')
   if (!['text', 'json'].includes(options.format)) throw new Error('--format must be text or json')
   if (!Number.isFinite(options.timeout) || options.timeout < 1000) throw new Error('--timeout must be >= 1000')
   options.dir = path.resolve(options.dir)
+  if (options.bindDir !== null) options.bindDir = path.resolve(options.bindDir)
   if (!fs.existsSync(path.join(options.dir, 'package.json'))) throw new Error(`not a package directory: ${options.dir}`)
+  if (options.bindDir !== null && !fs.existsSync(path.join(options.bindDir, 'package.json'))) throw new Error(`not a package directory: ${options.bindDir}`)
   return options
 }
 
@@ -158,15 +169,26 @@ function classifyEntry(report, invoked) {
   }
 }
 
-function classifyFlow(evidence) {
+function attestationOf(evidence) {
+  const producer = evidence && typeof evidence.producer === 'object' ? evidence.producer : null
+  if (producer?.kind === 'ci') return 'ci'
+  if (typeof producer?.runUrl === 'string' && producer.runUrl !== '') return 'ci'
+  return 'self-declared'
+}
+
+function classifyFlow(evidence, binding = null) {
   const ids = FLOW_IDS
   const emptyJourneys = () => Object.fromEntries(ids.map(id => [id, { status: 'not-run', declared: null, checks: 0, passes: false }]))
   if (!evidence) {
     return {
       state: 'not-run',
+      attestation: 'self-declared',
+      subject: binding,
       schema: null,
       claimLevel: null,
       producerKind: null,
+      sandboxMode: null,
+      sandboxDegraded: [],
       sandboxAttested: false,
       deprecated: false,
       invalid: false,
@@ -183,9 +205,13 @@ function classifyFlow(evidence) {
     return row?.status ?? null
   }
   const base = {
+    attestation: attestationOf(evidence),
+    subject: binding,
     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,
@@ -201,12 +227,19 @@ function classifyFlow(evidence) {
       journeys: Object.fromEntries(ids.map(id => [id, { status: 'deprecated', declared: declaredOf(id), checks: 0, passes: false }])),
     }
   }
-  if (!verdict.valid) {
+  const bindingErrors = binding && !binding.ok
+    ? [...(binding.errors ?? []), ...(binding.mismatches ?? [])].map(message => `subject binding: ${message}`)
+    : []
+  if (!verdict.valid || bindingErrors.length > 0) {
+    const errors = [...verdict.errors, ...bindingErrors]
     return {
       ...base,
       state: 'invalid',
       invalid: true,
-      reason: `${FLOW_EVIDENCE_SCHEMA} failed structural validation: ${verdict.errors.slice(0, 5).join('; ')}${verdict.errors.length > 5 ? ` (+${verdict.errors.length - 5} more)` : ''}`,
+      errors,
+      reason: bindingErrors.length > 0
+        ? `evidence subject does not match the inspected package: ${[...(binding.errors ?? []), ...(binding.mismatches ?? [])].join('; ')}`
+        : `${FLOW_EVIDENCE_SCHEMA} failed structural validation: ${verdict.errors.slice(0, 5).join('; ')}${verdict.errors.length > 5 ? ` (+${verdict.errors.length - 5} more)` : ''}`,
       evidenceHash: {
         declared: verdict.declaredHash,
         computed: verdict.computedHash,
@@ -245,7 +278,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 +399,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')
@@ -381,6 +420,7 @@ function render(result) {
     `DSH level audit — ${result.target.dir}`,
     `  ENTRY : ${result.levels.entry.state.padEnd(12)} (${result.levels.entry.checkerLevel ?? 'no level'})`,
     `  FLOW  : ${result.levels.flow.state.padEnd(12)} ${result.levels.flow.reason}`,
+    `  attest: ${result.levels.flow.attestation}${result.levels.flow.subject ? ` (subject ${result.levels.flow.subject.ok ? 'bound' : 'MISMATCH'})` : ''}`,
     `  BOOST : ${result.levels.boost.state.padEnd(12)} ${result.levels.boost.reason}`,
   ]
   if (result.nextActions.length > 0) {
@@ -399,7 +439,13 @@ function main() {
 
   const checker = runChecker(options)
   const entry = classifyEntry(checker.report, checker.invoked)
-  const flow = classifyFlow(flowEvidence)
+  // Subject binding is opt-in via --dir: it re-reads the package and re-packs
+  // it, so an evidence file can no longer vouch for a different version/hash.
+  let binding = null
+  if (flowEvidence && options.bindDir) {
+    binding = bindEvidenceSubject(flowEvidence, options.bindDir, { timeoutMs: options.timeout })
+  }
+  const flow = classifyFlow(flowEvidence, binding)
   const boost = classifyBoost(boostEvidence)
 
   const result = {
@@ -408,6 +454,8 @@ function main() {
     target: { dir: options.dir },
     levelsSpec: { schema: levels.schema, version: levels.version, status: levels.status },
     levels: { entry, flow, boost },
+    attestation: flow.attestation,
+    subject: binding,
     nextActions: nextActions(entry, flow, boost),
     notClaimed: ['official standard', 'certification', 'security audit', 'ranking', 'production baseline'],
     checker: {

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

@@ -0,0 +1,17 @@
+// 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 dirs = [join(here, '..', 'test'), join(here, '..', '..', 'test')]
+const files = dirs.filter((dir) => existsSync(dir)).flatMap((dir) => readdirSync(dir).filter((f) => f.endsWith('.test.mjs')).map((f) => join(dir, f)))
+if (files.length === 0) {
+  console.log('checker tests are not shipped in the npm package; nothing to run')
+  process.exit(0)
+}
+const r = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit' })
+process.exit(r.status ?? 1)

package/40-checker/src/author-cli.mjs

@@ -0,0 +1,139 @@
+/**
+ * `dsh-standards check [dir]` — the author-facing entry point.
+ *
+ * It shells out to the existing checker in JSON mode and only changes how the
+ * same report is presented: Markdown by default, `--json` for the raw
+ * `dsh-conformance/1` document, `--html <file>` for a single self-contained
+ * file. Exit codes are the checker's, never rewritten here.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { renderHtml, renderMarkdown } from './author-report.mjs'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const CHECKER = path.resolve(HERE, '..', 'bin', 'dsh-plugin-verify.mjs')
+const MAX_BUFFER = 64 * 1024 * 1024
+
+/** Checker flags that take a value, so `check --scope entry` is not read as a directory. */
+const VALUE_FLAGS = new Set([
+  '--scope', '--profile', '--runtime', '--runtime-version', '--cordis-version', '--commit',
+  '--install-spec', '--market-index', '--plugin-name', '--timeout', '--host', '--base',
+  '--web', '--bare', '--entry-runtime', '--entry-claim',
+])
+
+export function checkUsage() {
+  return `dsh-standards check — author-facing standards report
+
+Usage:
+  dsh-standards check [dir] [options]
+
+  dir defaults to the current directory. Output defaults to Markdown.
+
+Options:
+  --json                 print the raw dsh-conformance/1 report
+  --html <file>          write a single-file HTML report (inline CSS, no assets)
+  --help                 show this help
+
+Any other flag is forwarded to the checker, e.g.:
+  --scope entry --entry-claim static --no-exec
+  --runtime-version 0.2.2-rc.1
+  --market-index index.json --plugin-name @scope/name
+
+Exit codes (same as the checker):
+  0  completed, no FAIL (PASS or WARN)
+  1  completed, at least one FAIL
+  2  incomplete: a mandatory check did not run
+  3  usage error
+`
+}
+
+export function parseCheckArgs(argv = []) {
+  const options = { dir: null, json: false, html: null, help: false, passthrough: [] }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--help' || arg === '-h') { options.help = true; continue }
+    if (arg === '--json') { options.json = true; continue }
+    if (arg === '--html' || arg.startsWith('--html=')) {
+      const inline = arg.startsWith('--html=') ? arg.slice('--html='.length) : undefined
+      if (inline !== undefined) {
+        if (inline.trim() === '') throw new Error('--html needs a file path')
+        options.html = inline
+      } else {
+        const next = argv[index + 1]
+        if (next === undefined || next.startsWith('--')) throw new Error('--html needs a file path')
+        options.html = next
+        index += 1
+      }
+      continue
+    }
+    if (arg === '--format' || arg.startsWith('--format=')) throw new Error('`check` owns the output format; use --json or --html <file>')
+    if (arg === '--out' || arg.startsWith('--out=')) throw new Error('`check` writes to stdout or --html <file>; --out is not forwarded')
+    if (arg.startsWith('-')) {
+      options.passthrough.push(arg)
+      if (arg.includes('=')) continue
+      if (VALUE_FLAGS.has(arg)) {
+        const next = argv[index + 1]
+        if (next === undefined) throw new Error(`${arg} needs a value`)
+        options.passthrough.push(next)
+        index += 1
+      }
+      continue
+    }
+    if (options.dir !== null) throw new Error(`unexpected positional argument: ${arg}`)
+    options.dir = arg
+  }
+  if (options.json && options.html) throw new Error('--json and --html are mutually exclusive')
+  if (options.dir === null) options.dir = '.'
+  options.dir = path.resolve(options.dir)
+  return options
+}
+
+function invokeChecker(options) {
+  const args = [CHECKER, options.dir, '--format', 'json', ...options.passthrough]
+  const run = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 600_000, maxBuffer: MAX_BUFFER })
+  if (run.error) throw new Error(`could not run the checker: ${run.error.message}`)
+  let report
+  try {
+    report = JSON.parse(run.stdout)
+  } catch {
+    throw new Error(`checker produced no JSON (exit ${run.status}): ${String(run.stderr ?? '').slice(0, 400)}`)
+  }
+  return { report, status: run.status }
+}
+
+export function runCheck(argv = process.argv.slice(2)) {
+  let options
+  try {
+    options = parseCheckArgs(argv)
+  } catch (error) {
+    process.stderr.write(`dsh-standards check: ${error.message}\n`)
+    process.stderr.write(checkUsage())
+    return 3
+  }
+  if (options.help) {
+    process.stdout.write(checkUsage())
+    return 0
+  }
+  let result
+  try {
+    result = invokeChecker(options)
+  } catch (error) {
+    process.stderr.write(`dsh-standards check: ${error.message}\n`)
+    return 3
+  }
+  const { report, status } = result
+  const exitCode = Number.isInteger(report?.conclusion?.exitCode) ? report.conclusion.exitCode : (status ?? 3)
+  if (options.html) {
+    const out = path.resolve(options.html)
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    fs.writeFileSync(out, renderHtml(report))
+    process.stdout.write(`wrote ${out}\n`)
+  } else if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    process.stdout.write(renderMarkdown(report))
+  }
+  return exitCode
+}