dsh-standards 1.1.2 → 1.2.0

package/40-checker/src/report.mjs

@@ -1,4 +1,6 @@
 import path from 'node:path'
+import remediationSpec from '../../spec/remediation.json' with { type: 'json' }
+import { DOCS_BASE, joinAdvice } from './remediation.mjs'
 
 export const PACKAGE_MANDATORY = [
   'DSC-01', 'DSC-02', 'DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09', 'DSC-11', 'DSC-12', 'DSC-13',
@@ -37,7 +39,7 @@ function allowedNa(check, scope, profile, kind) {
   return false
 }
 
-export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime' }) {
+export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true }) {
   const mandatory = mandatoryFor(scope, profile, staticOnly, entryClaim)
   const adjustedChecks = scope === 'entry' ? checks.map(item => adjustEntryCheck(item, entryClaim)) : checks
   const runtimeIds = new Set(['DSC-04', 'DSC-05', 'DSC-06', 'DSC-07', 'DSC-08', 'DSC-09'])
@@ -85,7 +87,7 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   if (warnings.length > 0) reasonParts.push(`WARN: ${warnings.map(item => item.id).join(', ')}`)
   if (advisoryWarnings.length > 0) reasonParts.push(`advisory: ${advisoryWarnings.map(item => item.id).join(', ')}`)
 
-  return {
+  const report = {
     schema: 'dsh-conformance/1',
     standard: { id: 'DS-C', version: '1.0.0' },
     subject,
@@ -120,6 +122,12 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
       reason: reasonParts.join('; '),
     },
   }
+  // Additive only: `advice` is a sibling of `checks`, never part of a check,
+  // and the verdict is computed above without reading it.
+  if (advice !== false) {
+    report.advice = joinAdvice(report, remediationSpec, DOCS_BASE)
+  }
+  return report
 }
 
 const ICON = { PASS: 'PASS', WARN: 'WARN', FAIL: 'FAIL', NA: 'NA  ', ERROR: 'ERR ' }
@@ -145,6 +153,15 @@ export function formatText(report) {
   lines.push(`coverage: mandatory=${coverage.mandatory} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun}`)
   if (conclusion.reason) lines.push(`reason: ${conclusion.reason}`)
   if (conclusion.status === 'incomplete') lines.push('NOT A DS-C PASS: at least one mandatory check did not run (see notRun).')
+  if (Array.isArray(report.advice) && report.advice.length > 0) {
+    lines.push('')
+    lines.push('advice (non-blocking):')
+    for (const item of report.advice) {
+      const missing = item.ruleMissing ? ' [ruleMissing]' : ''
+      lines.push(`  ${String(item.severity).padEnd(4)} ${String(item.key).padEnd(7)} ${item.source}${missing}: ${String(item.fix ?? item.title ?? '').replace(/\s+/g, ' ').slice(0, 160)}`)
+      if (item.docsUrl) lines.push(`          ${item.docsUrl}`)
+    }
+  }
   lines.push('')
   return `${lines.join('\n')}\n`
 }

package/40-checker/src/sandbox-env.mjs

@@ -0,0 +1,78 @@
+/**
+ * Environment policy for child processes that may load third-party plugin code.
+ *
+ * A plugin boots on first import: anything it can read from `process.env` is
+ * already exfiltratable before a single check runs. `...process.env` therefore
+ * must never be forwarded to `dsh plugin add`, a host boot, or a runtime child.
+ * The policy is an allowlist (not a denylist) so a newly named credential does
+ * not silently leak; the secret-shaped name filter stays as a second gate in
+ * case an allowlisted name is ambiguous.
+ *
+ * Callers that need isolation (temporary HOME, DSH_HOME, TMPDIR) pass those as
+ * explicit overrides. Overrides are the caller's own values, never inherited.
+ */
+
+const ALLOWED = new Set([
+  // Portable process essentials.
+  'PATH', 'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP', 'PWD', 'SHELL',
+  'USER', 'LOGNAME', 'LANG', 'LANGUAGE', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES',
+  'TZ', 'TERM', 'NO_COLOR', 'FORCE_COLOR', 'COLORTERM',
+  // Windows needs these to locate node/npm/tmp; they carry no credentials.
+  'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC', 'PATHEXT', 'OS',
+  'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE', 'PROCESSOR_ARCHITEW6432',
+  'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA', 'PROGRAMFILES',
+  'PROGRAMFILES(X86)', 'COMMONPROGRAMFILES', 'HOMEDRIVE', 'HOMEPATH',
+])
+
+const SECRET_NAME = /(TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|CREDENTIAL|AUTH|COOKIE|SESSION|_KEY$)/i
+
+export function isSecretEnvName(name) {
+  return SECRET_NAME.test(String(name ?? ''))
+}
+
+export function isAllowedEnvName(name) {
+  return ALLOWED.has(String(name)) && !isSecretEnvName(name)
+}
+
+/**
+ * Build the child environment: inherited allowlisted keys + caller overrides.
+ * Overrides are trusted call values (paths the caller just created), not
+ * inherited state, so they are not filtered.
+ */
+export function sanitizedEnv(overrides = {}) {
+  const env = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value === undefined || !isAllowedEnvName(key)) continue
+    env[key] = value
+  }
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined || value === null) continue
+    env[key] = String(value)
+  }
+  return env
+}
+
+/**
+ * In-process variant for scripts that boot a plugin in this very process
+ * (bundle smoke, runtime child). It deletes everything not allowlisted, so a
+ * direct `node script.mjs` invocation gets the same policy as a spawned one.
+ * Returns the removed key names (never values) for logging.
+ */
+export function scrubProcessEnv() {
+  const removed = []
+  for (const key of Object.keys(process.env)) {
+    if (isAllowedEnvName(key)) continue
+    removed.push(key)
+    delete process.env[key]
+  }
+  return removed
+}
+
+export function envPolicy() {
+  return {
+    mode: 'allowlist',
+    allow: [...ALLOWED].sort(),
+    denyNamePattern: SECRET_NAME.source,
+    note: 'tokens/keys/secrets/credentials are dropped even if a future allowlist entry matches',
+  }
+}

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

@@ -0,0 +1,295 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import {
+  FLOW_IDS, evidenceHash, finalizeEvidence, journeyAggregate, treeSha256, validateFlowEvidence,
+} from '../src/flow-evidence.mjs'
+import { isSecretEnvName, sanitizedEnv } from '../src/sandbox-env.mjs'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const STD = path.resolve(HERE, '..', '..')
+const AUDIT = path.join(STD, '40-checker', 'scripts', 'level-audit.mjs')
+const COLLECT = path.join(STD, '40-checker', 'bin', 'dsh-flow-collect.mjs')
+const GOOD = path.join(STD, '40-checker', 'fixtures', 'good')
+const TEMPLATE = path.join(STD, 'examples', 'plugin-template')
+const ISO = '2026-11-06T12:00:00.000Z'
+const HASH = `sha256:${'a'.repeat(64)}`
+
+function check(id, overrides = {}) {
+  return {
+    id,
+    kind: 'observed',
+    command: ['node', '-e', 'process.exit(0)'],
+    exitCode: 0,
+    startedAt: ISO,
+    endedAt: ISO,
+    stdout: { path: `logs/${id}.out.log`, sha256: HASH },
+    assertions: [{ claim: `${id} observed`, observed: true }],
+    ...overrides,
+  }
+}
+
+function evidenceDocument({ journeys = {}, subject, ...rest } = {}) {
+  const base = {
+    schema: 'dsh-flow-evidence/2',
+    generatedAt: ISO,
+    producer: { command: ['node', '40-checker/bin/dsh-flow-collect.mjs'], at: ISO, kind: 'local' },
+    subject: subject ?? {
+      name: '@dsh-fixtures/good-plugin',
+      version: '1.0.0',
+      integrity: null,
+      tarballSha256: HASH,
+      commit: null,
+      treeSha256: HASH,
+    },
+    host: { dsh: '0.2.1-rc.5', node: 'v24.22.1', platform: 'linux-x64' },
+    journeys: Object.fromEntries(FLOW_IDS.map((id) => [id, { status: 'pass', checks: [check(`${id}.run`)] }])),
+    claims: { claimLevel: 'self-attested', notClaimed: ['certification'] },
+    conclusion: 'flow-pass',
+    ...rest,
+  }
+  for (const [id, override] of Object.entries(journeys)) base.journeys[id] = override
+  return finalizeEvidence(base)
+}
+
+function writeTemp(name, value) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-flow-evidence-test-'))
+  const file = path.join(dir, name)
+  fs.writeFileSync(file, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`)
+  return { dir, file, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) }
+}
+
+function runAudit(flowFile) {
+  const run = spawnSync(process.execPath, [AUDIT, GOOD, '--format', 'json', '--flow-evidence', flowFile], {
+    encoding: 'utf8', timeout: 60_000,
+  })
+  assert.equal(run.status, 0, run.stderr)
+  return JSON.parse(run.stdout)
+}
+
+test('sandbox-env: inherited secrets are dropped and only allowlisted names survive', () => {
+  process.env.DSH_TEST_TOKEN = 'do-not-leak'
+  process.env.DSH_TEST_API_KEY = 'do-not-leak'
+  try {
+    const env = sanitizedEnv()
+    assert.equal(env.DSH_TEST_TOKEN, undefined)
+    assert.equal(env.DSH_TEST_API_KEY, undefined)
+    assert.equal(env.DSH_HOME, undefined)
+    assert.equal(env.PATH, process.env.PATH)
+    assert.equal(isSecretEnvName('GH_TOKEN'), true)
+    assert.equal(isSecretEnvName('DEEPSEEK_API_KEY'), true)
+    assert.equal(isSecretEnvName('PATH'), false)
+    assert.equal(sanitizedEnv({ DSH_HOME: '/tmp/isolated' }).DSH_HOME, '/tmp/isolated')
+  } finally {
+    delete process.env.DSH_TEST_TOKEN
+    delete process.env.DSH_TEST_API_KEY
+  }
+})
+
+test('flow-evidence: a well-formed v2 document validates and hashes consistently', () => {
+  const doc = evidenceDocument()
+  const verdict = validateFlowEvidence(doc)
+  assert.equal(verdict.kind, 'v2')
+  assert.equal(verdict.valid, true, verdict.errors.join('; '))
+  assert.equal(verdict.declaredHash, evidenceHash(doc))
+  assert.equal(verdict.journeys.J1.derived, 'pass')
+})
+
+test('level-audit: v1 journey/runtime schemas are deprecated and never a pass', () => {
+  const docs = [
+    { schema: 'dsh-flow-journey/1', package: '@dsh-fixtures/good-plugin', checks: [] },
+    { schema: 'dsh-flow-runtime/1', environment: {}, checks: [] },
+  ]
+  for (const doc of docs) {
+    const temp = writeTemp('v1.json', doc)
+    try {
+      const result = runAudit(temp.file)
+      assert.equal(result.levels.flow.state, 'deprecated')
+      assert.equal(result.levels.flow.deprecated, true)
+      assert.equal(result.levels.flow.passed, 0)
+      assert.notEqual(result.levels.flow.state, 'runtime')
+    } finally {
+      temp.cleanup()
+    }
+  }
+})
+
+test('level-audit: bare {Jx:{status:pass}} rows are deprecated and never a pass', () => {
+  const temp = writeTemp('bare.json', Object.fromEntries(FLOW_IDS.map(id => [id, { status: 'pass' }])))
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'deprecated')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.notEqual(result.levels.flow.state, 'runtime')
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: v2 with all eight journeys passing is runtime', () => {
+  const temp = writeTemp('v2-pass.json', evidenceDocument())
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'runtime')
+    assert.equal(result.levels.flow.passed, 8)
+    assert.equal(result.levels.flow.evidenceHash.ok, true)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a forged v2 pass with a non-zero exitCode is not a pass', () => {
+  // Declared pass on every journey, but J4 carries exitCode 1: the aggregate
+  // contradicts the declaration, so the document must fail validation.
+  const doc = evidenceDocument({
+    journeys: { J4: { status: 'pass', checks: [check('J4.run', { exitCode: 1 })] } },
+  })
+  const temp = writeTemp('forged.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.notEqual(result.levels.flow.state, 'runtime')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.equal(result.levels.flow.invalid, true)
+    assert.match(result.levels.flow.reason, /aggregate|exitCode|declares pass/i)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: an honest v2 with one failed journey is failed, not runtime', () => {
+  const doc = evidenceDocument({
+    journeys: { J4: { status: 'fail', checks: [check('J4.run', { exitCode: 1 })] } },
+    conclusion: 'flow-fail',
+  })
+  const temp = writeTemp('failed.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'failed')
+    assert.equal(result.levels.flow.passed, 7)
+    assert.equal(result.levels.flow.journeys.J4.status, 'fail')
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a v2 journey without checks does not count as a pass', () => {
+  const doc = evidenceDocument({ journeys: { J5: { status: 'not-run', checks: [] } } })
+  const temp = writeTemp('empty.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.notEqual(result.levels.flow.state, 'runtime')
+    assert.equal(result.levels.flow.passed, 7)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a tampered evidence hash is invalid, not runtime', () => {
+  const doc = evidenceDocument()
+  doc.chain.evidenceHash = HASH
+  const temp = writeTemp('tampered.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'invalid')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.match(result.levels.flow.reason, /evidenceHash/)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a declared blocked journey is blocked, not failed', () => {
+  const doc = evidenceDocument({
+    journeys: { J6: { status: 'blocked', reason: 'no --previous package supplied', checks: [check('J6.upgrade', { exitCode: 1 })] } },
+    conclusion: 'flow-blocked',
+  })
+  const temp = writeTemp('blocked.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'blocked')
+    assert.equal(result.levels.flow.passed, 7)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('flow-collect: static output is v2, validates, and the audit can read it', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-flow-collect-test-'))
+  try {
+    const copy = path.join(dir, 'plugin')
+    fs.cpSync(TEMPLATE, copy, { recursive: true })
+    const out = path.join(dir, 'flow.json')
+    const run = spawnSync(process.execPath, [COLLECT, '--package', copy, '--static', '--out', out], {
+      encoding: 'utf8', timeout: 120_000,
+    })
+    assert.equal(run.status, 0, `${run.stderr}\n${run.stdout}`)
+    const doc = JSON.parse(fs.readFileSync(out, 'utf8'))
+    assert.equal(doc.schema, 'dsh-flow-evidence/2')
+    const verdict = validateFlowEvidence(doc)
+    assert.equal(verdict.valid, true, verdict.errors.join('; '))
+    assert.deepEqual(Object.keys(doc.journeys), FLOW_IDS)
+    assert.equal(doc.subject.treeStable, true)
+    assert.equal(doc.subject.treeSha256, treeSha256(TEMPLATE).hash)
+    assert.equal(doc.chain.evidenceHash, evidenceHash(doc))
+    assert.equal(journeyAggregate(doc.journeys.J1.checks), 'static')
+
+    // The audit consumes the collector output without upgrading it to runtime.
+    const audit = spawnSync(process.execPath, [AUDIT, copy, '--format', 'json', '--flow-evidence', out], {
+      encoding: 'utf8', timeout: 60_000,
+    })
+    assert.equal(audit.status, 0, audit.stderr)
+    const result = JSON.parse(audit.stdout)
+    assert.equal(result.levels.flow.schema, 'dsh-flow-evidence/2')
+    assert.notEqual(result.levels.flow.state, 'runtime')
+    assert.notEqual(result.levels.flow.state, 'invalid')
+    assert.notEqual(result.levels.flow.state, 'deprecated')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.equal(result.levels.flow.evidenceHash.ok, true)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('flow-collect: a failed journey exits 1 and prints the five-element hint', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-flow-collect-fail-'))
+  try {
+    const plugin = path.join(dir, 'plugin')
+    fs.mkdirSync(plugin)
+    fs.writeFileSync(path.join(plugin, 'package.json'), `${JSON.stringify({
+      name: 'dsh-flow-bad-fixture', version: '1.0.0', type: 'module', main: './index.mjs',
+      files: ['index.mjs'], dependencies: { 'workspace-only': 'workspace:*' },
+    }, null, 2)}\n`)
+    fs.writeFileSync(path.join(plugin, 'index.mjs'), 'export function apply() {}\n')
+    const out = path.join(dir, 'flow.json')
+    const run = spawnSync(process.execPath, [COLLECT, '--package', plugin, '--static', '--out', out], {
+      encoding: 'utf8', timeout: 120_000,
+    })
+    assert.equal(run.status, 1, `${run.stderr}\n${run.stdout}`)
+    for (const marker of ['FAIL J1.install.preflight', '1) 子检查:', '2) 命令:', '3) exitCode:', '4) stderr(末20行):', '5) 日志:', '条款锚: 32#R1']) {
+      assert.ok(run.stdout.includes(marker), `missing hint marker ${marker}\n${run.stdout}`)
+    }
+    const doc = JSON.parse(fs.readFileSync(out, 'utf8'))
+    assert.equal(doc.journeys.J1.status, 'fail')
+    assert.equal(doc.conclusion, 'flow-fail')
+    assert.equal(validateFlowEvidence(doc).valid, true)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('flow-evidence: the published schema declares the validator contract', () => {
+  const schema = JSON.parse(fs.readFileSync(path.join(STD, 'spec', 'flow-evidence.schema.json'), 'utf8'))
+  assert.equal(schema.properties.schema.const, 'dsh-flow-evidence/2')
+  for (const key of ['schema', 'generatedAt', 'producer', 'subject', 'host', 'journeys', 'claims', 'chain']) {
+    assert.ok(schema.required.includes(key), `schema.required is missing ${key}`)
+  }
+  for (const id of FLOW_IDS) assert.ok(schema.properties.journeys.required.includes(id), `journeys.required is missing ${id}`)
+  for (const key of ['id', 'command', 'exitCode', 'startedAt', 'endedAt', 'stdout', 'assertions']) {
+    assert.ok(schema.$defs.check.required.includes(key), `check.required is missing ${key}`)
+  }
+  assert.ok(schema.$defs.journey.properties.checks)
+})