dsh-standards 1.1.2 → 1.2.1

package/40-checker/src/cli.mjs

@@ -5,6 +5,7 @@ import { runManifestChecks, DEFAULT_RUNTIME_VERSION } from './manifest.mjs'
 import { checkCapabilities, checkCredentials, checkImportTimeAdvisory, checkLabels } from './declarations.mjs'
 import { runRuntimeChecks } from './runtime.mjs'
 import { spawn, spawnSync } from 'node:child_process'
+import { sanitizedEnv } from './sandbox-env.mjs'
 import { readSources } from './util.mjs'
 import { buildReport, writeReport } from './report.mjs'
 
@@ -40,6 +41,8 @@ Options:
   --web <file>               optional web-app cordis.patch.yml for bundle smoke
   --bare <dir>               optional bare-module base for bundle smoke (host farm)
   --out <file>               write the report to a file (stdout otherwise)
+  --advice                   include remediation advice in the report (default: on)
+  --no-advice                omit the additive advice[] field
   --help                     show this help
   --version                  show the checker version
 
@@ -75,6 +78,7 @@ function parseArgs(argv) {
     web: null,
     bare: null,
     out: null,
+    advice: true,
     help: false,
     version: false,
   }
@@ -117,6 +121,8 @@ function parseArgs(argv) {
       case '--base': options.base = value(); break
       case '--web': options.web = value(); break
       case '--bare': options.bare = value(); break
+      case '--advice': options.advice = inline === undefined ? true : inline !== 'false'; break
+      case '--no-advice': options.advice = false; break
       default: throw new Error(`unknown option: ${key}`)
     }
   }
@@ -152,7 +158,8 @@ function runtimeNotRun(reason) {
 function isolatedRuntimeChecks(input) {
   return new Promise((resolve) => {
     const script = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'scripts', 'runtime-child.mjs')
-    const child = spawn(process.execPath, [script], { stdio: ['pipe', 'pipe', 'pipe'] })
+    // The child imports the inspected package: never inherit the caller's env.
+    const child = spawn(process.execPath, [script], { stdio: ['pipe', 'pipe', 'pipe'], env: sanitizedEnv() })
     let out = ''
     let err = ''
     const timer = setTimeout(() => { try { child.kill('SIGKILL') } catch {} }, input.timeoutMs + 3000)
@@ -198,7 +205,7 @@ async function entryRunCheck(kind, runtimeChecks, options, dir) {
     if (options.base) args.push('--base', options.base)
     if (options.web) args.push('--web', options.web)
     if (options.bare) args.push('--bare', options.bare)
-    const run = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: options.timeoutMs + 5000, maxBuffer: 8 * 1024 * 1024 })
+    const run = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: options.timeoutMs + 5000, maxBuffer: 8 * 1024 * 1024, env: sanitizedEnv() })
     if (run.error) return { ...base, result: 'ERROR', coverage: 'not-run', reason: `bundle smoke failed to start: ${run.error.message}` }
     let smoke
     try { smoke = JSON.parse(run.stdout) } catch { return { ...base, result: 'ERROR', coverage: 'not-run', reason: `bundle smoke produced no JSON: ${(run.stderr || '').slice(0, 300)}` } }
@@ -343,6 +350,7 @@ export async function main(argv = process.argv.slice(2)) {
     staticOnly: options.staticOnly,
     entryRuntime: options.entryRuntime,
     entryClaim: options.entryClaim,
+    advice: options.advice,
   })
   const output = writeReport(report, options.format)
   if (options.out) {

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

@@ -0,0 +1,455 @@
+/**
+ * FLOW evidence chain: `dsh-flow-evidence/2` construction and validation.
+ *
+ * One module owns the shape so the collector and the audit cannot drift:
+ *   - `treeSha256` binds the package directory (read-only copy stays identical);
+ *   - `finalizeEvidence`/`evidenceHash` bind the whole document (chain);
+ *   - `validateFlowEvidence` is the structural gate `level-audit` uses. v1
+ *     (`dsh-flow-journey/1`, `dsh-flow-runtime/1`) and the bare
+ *     `{ "J1": { "status": "pass" } }` shape are recognised only so the audit
+ *     can label them `deprecated`; they never count as a pass.
+ *
+ * Pass rule (per journey, enforced from `checks[]`, never from the declared
+ * status alone): at least one check, every check has exitCode 0, at least one
+ * observed (non-static) check, and every observed check's assertions hold.
+ * A journey declared `warn`/`blocked`/`na`/`static`/`not-run` never counts.
+ *
+ * Runtime rule: passing journeys are necessary but not sufficient. Only
+ * sandbox-attested evidence (`claims.claimLevel === 'sandbox-attested'` or
+ * `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.
+ */
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const FLOW_IDS = ['J1', 'J2', 'J3', 'J4', 'J5', 'J6', 'J7', 'J8']
+export const FLOW_EVIDENCE_SCHEMA = 'dsh-flow-evidence/2'
+export const FLOW_V1_SCHEMAS = new Set(['dsh-flow-journey/1', 'dsh-flow-runtime/1'])
+export const JOURNEY_STATUSES = new Set(['pass', 'fail', 'warn', 'blocked', 'static', 'na', 'not-run'])
+export const CHECK_KINDS = new Set(['observed', 'static', 'manual'])
+
+const HASH_RE = /^sha256:[0-9a-f]{64}$/
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+const COMMIT_RE = /^[0-9a-f]{40}$/
+const INTEGRITY_RE = /^(?:sha512|sha256)-[A-Za-z0-9+/=]+$/
+
+/** Journey -> normative anchor in 32-DSH-FLOW顺畅规范.md (R1..R8). */
+export const FLOW_CLAUSE_ANCHORS = {
+  J1: '32#R1 安装/移除',
+  J2: '32#R2 启用/停用',
+  J3: '32#R3 配置',
+  J4: '32#R4 首次成功',
+  J5: '32#R5 权限',
+  J6: '32#R6 升级/回滚/卸载',
+  J7: '32#R7 可观测',
+  J8: '32#R8 client/server',
+}
+
+export function clauseAnchor(checkId) {
+  const id = String(checkId ?? '')
+  return FLOW_CLAUSE_ANCHORS[id.slice(0, 2)] ?? null
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function sha256Hex(data) {
+  return crypto.createHash('sha256').update(data).digest('hex')
+}
+
+export function sha256Value(data) {
+  return `sha256:${sha256Hex(data)}`
+}
+
+export function sha256File(file) {
+  return sha256Value(fs.readFileSync(file))
+}
+
+/** JSON with recursively sorted object keys; array order is preserved. */
+export function canonicalJson(value) {
+  const sort = (node) => {
+    if (Array.isArray(node)) return node.map(sort)
+    if (isPlainObject(node)) {
+      const out = {}
+      for (const key of Object.keys(node).sort()) out[key] = sort(node[key])
+      return out
+    }
+    return node
+  }
+  return JSON.stringify(sort(value))
+}
+
+/** Chain hash: every field except `chain` and `signature`. */
+export function evidenceHash(document) {
+  const copy = { ...document }
+  delete copy.chain
+  delete copy.signature
+  return sha256Value(canonicalJson(copy))
+}
+
+export function finalizeEvidence(document) {
+  const output = { ...document }
+  output.chain = { evidenceHash: evidenceHash(output) }
+  return output
+}
+
+export function evidenceHashMatches(document) {
+  const declared = document?.chain?.evidenceHash
+  if (typeof declared !== 'string') return false
+  return declared === evidenceHash(document)
+}
+
+const DEFAULT_TREE_EXCLUDE = ['.git', 'node_modules']
+const TREE_EXCLUDE_ALWAYS = new Set(['.git', 'node_modules'])
+
+/**
+ * Deterministic directory hash: relative path + byte length + file hash for
+ * every regular file, sorted, with `.git`/`node_modules` and `exclude` skipped.
+ * Symlinks are hashed by target string so re-linking cannot pass unnoticed.
+ * Returns `{ hash, files, bytes })` where `hash` is `sha256:<64 hex>`.
+ */
+export function treeSha256(dir, { exclude = [] } = {}) {
+  const root = path.resolve(dir)
+  const skip = new Set([...DEFAULT_TREE_EXCLUDE, ...exclude.map(item => String(item).split(path.sep).join('/'))])
+  const rows = []
+  let bytes = 0
+  const walk = (current, relative) => {
+    const entries = fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    for (const entry of entries) {
+      const rel = relative ? `${relative}/${entry.name}` : entry.name
+      const segments = rel.split('/')
+      if (segments.some(segment => TREE_EXCLUDE_ALWAYS.has(segment))) continue
+      if ([...skip].some(pattern => rel === pattern || rel.startsWith(`${pattern}/`))) continue
+      const absolute = path.join(current, entry.name)
+      if (entry.isDirectory()) {
+        walk(absolute, rel)
+      } else if (entry.isSymbolicLink()) {
+        const target = fs.readlinkSync(absolute)
+        rows.push(`${rel}\0link\0${sha256Hex(target)}`)
+      } else if (entry.isFile()) {
+        const size = fs.statSync(absolute).size
+        bytes += size
+        rows.push(`${rel}\0${size}\0${sha256Hex(fs.readFileSync(absolute))}`)
+      }
+    }
+  }
+  walk(root, '')
+  rows.sort()
+  return { hash: sha256Value(rows.join('\n')), files: rows.length, bytes }
+}
+
+export function isIsoTimestamp(value) {
+  return typeof value === 'string' && ISO_RE.test(value) && Number.isFinite(Date.parse(value))
+}
+
+/**
+ * Aggregate one journey from its checks.
+ * `pass` requires observed evidence; `static` means preflight only; `warn`
+ * means the commands succeeded but an assertion contradicts the claim.
+ */
+export function journeyAggregate(checks) {
+  if (!Array.isArray(checks) || checks.length === 0) return 'not-run'
+  if (checks.some(check => check?.exitCode !== 0)) return 'fail'
+  const observed = checks.filter(check => (check?.kind ?? 'observed') !== 'static')
+  if (observed.length === 0) return 'static'
+  const held = observed.every(check => Array.isArray(check.assertions)
+    && check.assertions.length > 0
+    && check.assertions.every(assertion => assertion?.observed === true))
+  return held ? 'pass' : 'warn'
+}
+
+/** True only when a declared journey status agrees with its checks. */
+export function journeyCountsAsPass(journey) {
+  const derived = journeyAggregate(journey?.checks)
+  const declared = journey?.status ?? null
+  if (derived !== 'pass') return false
+  return declared === null || declared === 'pass'
+}
+
+/**
+ * Runtime eligibility. A local collector run is `self-attested`
+ * (`ci-attested` with `--ci`): structurally valid, but it does not prove that
+ * commands ran, let alone in a sandbox. Only `claims.claimLevel ===
+ * 'sandbox-attested'` or the producer-side equivalent `producer.kind ===
+ * 'sandbox'` may be reported as FLOW runtime.
+ */
+export function isSandboxAttested(document) {
+  if (!isPlainObject(document)) return false
+  return document.claims?.claimLevel === 'sandbox-attested' || document.producer?.kind === 'sandbox'
+}
+
+function emptyVerdict(kind, schema, errors) {
+  return {
+    kind,
+    schema: schema ?? null,
+    valid: false,
+    errors,
+    journeys: {},
+    computedHash: null,
+    declaredHash: null,
+    subject: null,
+    host: null,
+    generatedAt: null,
+    conclusion: null,
+    claimLevel: null,
+    producerKind: null,
+    sandboxAttested: false,
+  }
+}
+
+/**
+ * Classify + structurally validate a flow evidence document.
+ * `kind`: `v2` | `v1-deprecated` | `legacy` | `invalid`.
+ */
+export function validateFlowEvidence(document) {
+  if (!isPlainObject(document)) return emptyVerdict('invalid', null, ['root must be a JSON object'])
+  const schema = typeof document.schema === 'string' ? document.schema : null
+  if (schema === FLOW_EVIDENCE_SCHEMA) return validateV2(document)
+  const legacyRows = FLOW_IDS.some(id => isPlainObject(document[id]))
+  if (schema && (FLOW_V1_SCHEMAS.has(schema) || !legacyRows)) {
+    return emptyVerdict('v1-deprecated', schema, [
+      `schema ${schema} is deprecated; only ${FLOW_EVIDENCE_SCHEMA} is accepted`,
+    ])
+  }
+  if (legacyRows || isPlainObject(document.journeys)) {
+    return emptyVerdict('legacy', schema, [
+      'bare {Jx:{status}} rows are deprecated and never count as a pass',
+    ])
+  }
+  return emptyVerdict('invalid', schema, [`unrecognised flow evidence document; expected schema ${FLOW_EVIDENCE_SCHEMA}`])
+}
+
+function validateV2(document) {
+  const errors = []
+  const requireObject = (value, label) => {
+    if (!isPlainObject(value)) {
+      errors.push(`${label} must be an object`)
+      return false
+    }
+    return true
+  }
+  const requireString = (value, label, { allowNull = false, minLength = 1, pattern = null } = {}) => {
+    if (value === null && allowNull) return
+    if (typeof value !== 'string' || value.length < minLength) {
+      errors.push(`${label} must be a non-empty string${allowNull ? ' or null' : ''}`)
+      return
+    }
+    if (pattern && !pattern.test(value)) errors.push(`${label} has an invalid format`)
+  }
+  const requireIso = (value, label) => {
+    if (!isIsoTimestamp(value)) errors.push(`${label} must be an ISO-8601 timestamp`)
+  }
+  const requireHash = (value, label, { allowNull = false } = {}) => {
+    if (value === null && allowNull) return
+    if (typeof value !== 'string' || !HASH_RE.test(value)) errors.push(`${label} must be sha256:<64 lowercase hex>${allowNull ? ' or null' : ''}`)
+  }
+  const requireLog = (value, label) => {
+    if (!requireObject(value, label)) return
+    requireString(value.path, `${label}.path`)
+    requireHash(value.sha256, `${label}.sha256`)
+    for (const key of Object.keys(value)) if (!['path', 'sha256'].includes(key)) errors.push(`${label}.${key} is not allowed`)
+  }
+
+  for (const key of ['schema', 'generatedAt', 'producer', 'subject', 'host', 'journeys', 'claims', 'chain']) {
+    if (!(key in document)) errors.push(`${key} is required`)
+  }
+  if (!errors.includes('schema is required')) {
+    if (document.schema !== FLOW_EVIDENCE_SCHEMA) errors.push(`schema must be ${FLOW_EVIDENCE_SCHEMA}`)
+  }
+  if ('generatedAt' in document) requireIso(document.generatedAt, 'generatedAt')
+  if ('evidenceId' in document) requireString(document.evidenceId, 'evidenceId')
+
+  if (requireObject(document.producer, 'producer')) {
+    requireIso(document.producer.at ?? null, 'producer.at')
+    const command = document.producer.command
+    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')
+    }
+    for (const key of ['runner', 'actor', 'runUrl']) {
+      if (key in document.producer && document.producer[key] !== null) requireString(document.producer[key], `producer.${key}`)
+    }
+  }
+
+  if (requireObject(document.subject, 'subject')) {
+    const subject = document.subject
+    requireString(subject.name, 'subject.name')
+    requireString(subject.version, 'subject.version')
+    requireFieldOrNull(errors, subject, 'integrity', value => requireString(value, 'subject.integrity', { allowNull: true, pattern: INTEGRITY_RE }))
+    requireField(errors, subject, 'tarballSha256', () => requireHash(subject.tarballSha256, 'subject.tarballSha256'))
+    requireFieldOrNull(errors, subject, 'commit', value => requireString(value, 'subject.commit', { allowNull: true, pattern: COMMIT_RE }))
+    requireField(errors, subject, 'treeSha256', () => requireHash(subject.treeSha256, 'subject.treeSha256'))
+    if ('treeSha256After' in subject) requireHash(subject.treeSha256After, 'subject.treeSha256After', { allowNull: true })
+    if ('treeStable' in subject && typeof subject.treeStable !== 'boolean') errors.push('subject.treeStable must be a boolean')
+    if ('treeExclude' in subject) {
+      if (!Array.isArray(subject.treeExclude) || subject.treeExclude.some(item => typeof item !== 'string')) {
+        errors.push('subject.treeExclude must be an array of strings')
+      }
+    }
+    if ('source' in subject) requireString(subject.source, 'subject.source')
+  }
+
+  if (requireObject(document.host, 'host')) {
+    requireString(document.host.dsh, 'host.dsh', { allowNull: true })
+    requireString(document.host.node, 'host.node')
+    requireString(document.host.platform, 'host.platform')
+    for (const key of ['dshCommit', 'cordis']) {
+      if (key in document.host && document.host[key] !== null) requireString(document.host[key], `host.${key}`)
+    }
+  }
+
+  if (requireObject(document.journeys, 'journeys')) {
+    for (const key of Object.keys(document.journeys)) {
+      if (!FLOW_IDS.includes(key)) errors.push(`journeys.${key} is not a known journey (J1-J8)`)
+    }
+    for (const id of FLOW_IDS) {
+      const journey = document.journeys[id]
+      if (!isPlainObject(journey)) {
+        errors.push(`journeys.${id} must be an object`)
+        continue
+      }
+      for (const key of Object.keys(journey)) {
+        if (!['status', 'reason', 'kind', 'checks', 'limitations'].includes(key)) errors.push(`journeys.${id}.${key} is not allowed`)
+      }
+      if ('status' in journey && journey.status !== null && !JOURNEY_STATUSES.has(journey.status)) {
+        errors.push(`journeys.${id}.status must be one of ${[...JOURNEY_STATUSES].join(', ')}`)
+      }
+      if ('reason' in journey && journey.reason !== null) requireString(journey.reason, `journeys.${id}.reason`)
+      if ('limitations' in journey) {
+        if (!Array.isArray(journey.limitations) || journey.limitations.some(item => typeof item !== 'string')) {
+          errors.push(`journeys.${id}.limitations must be an array of strings`)
+        }
+      }
+      if (!Array.isArray(journey.checks)) {
+        errors.push(`journeys.${id}.checks must be an array`)
+        continue
+      }
+      journey.checks.forEach((check, index) => validateCheck(check, `journeys.${id}.checks[${index}]`))
+    }
+  }
+
+  if (requireObject(document.claims, 'claims')) {
+    const claims = document.claims
+    if (!['self-attested', 'ci-attested', 'sandbox-attested'].includes(claims.claimLevel)) {
+      errors.push('claims.claimLevel must be self-attested, ci-attested, or sandbox-attested')
+    }
+    if ('notClaimed' in claims && (!Array.isArray(claims.notClaimed) || claims.notClaimed.some(item => typeof item !== 'string'))) {
+      errors.push('claims.notClaimed must be an array of strings')
+    }
+    if ('method' in claims) requireString(claims.method, 'claims.method')
+  }
+
+  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`)
+  }
+  if ('signature' in document && document.signature !== null && !isPlainObject(document.signature)) {
+    errors.push('signature must be null or an object')
+  }
+  if ('conclusion' in document && document.conclusion !== null && !['flow-pass', 'flow-warn', 'flow-blocked', 'flow-fail'].includes(document.conclusion)) {
+    errors.push('conclusion must be flow-pass, flow-warn, flow-blocked, or flow-fail')
+  }
+
+  // Aggregation consistency: declared pass/fail must agree with the checks.
+  const journeys = {}
+  for (const id of FLOW_IDS) {
+    const journey = isPlainObject(document.journeys?.[id]) ? document.journeys[id] : null
+    const checks = Array.isArray(journey?.checks) ? journey.checks : []
+    const derived = journeyAggregate(checks)
+    const declared = journey?.status ?? null
+    const passes = journeyCountsAsPass(journey)
+    journeys[id] = { declared, derived, checks: checks.length, passes }
+    if (declared === 'pass' && derived !== 'pass') errors.push(`journeys.${id} declares pass but its checks aggregate to ${derived}`)
+    if (declared === 'fail' && derived === 'pass') errors.push(`journeys.${id} declares fail but its checks aggregate to pass`)
+  }
+
+  // Chain integrity: recompute over every field except chain/signature.
+  const computedHash = evidenceHash(document)
+  const declaredHash = typeof document.chain?.evidenceHash === 'string' ? document.chain.evidenceHash : null
+  if (declaredHash !== computedHash) {
+    errors.push(`chain.evidenceHash does not match the document (declared ${declaredHash ?? 'missing'}, computed ${computedHash})`)
+  }
+
+  return {
+    kind: 'v2',
+    schema: FLOW_EVIDENCE_SCHEMA,
+    valid: errors.length === 0,
+    errors,
+    journeys,
+    computedHash,
+    declaredHash,
+    subject: isPlainObject(document.subject) ? document.subject : null,
+    host: isPlainObject(document.host) ? document.host : null,
+    generatedAt: document.generatedAt ?? null,
+    conclusion: document.conclusion ?? null,
+    claimLevel: isPlainObject(document.claims) ? document.claims.claimLevel ?? null : null,
+    producerKind: isPlainObject(document.producer) ? document.producer.kind ?? null : null,
+    sandboxAttested: isSandboxAttested(document),
+  }
+
+  function validateCheck(check, label) {
+    if (!isPlainObject(check)) {
+      errors.push(`${label} must be an object`)
+      return
+    }
+    for (const key of Object.keys(check)) {
+      if (!['id', 'kind', 'command', 'exitCode', 'startedAt', 'endedAt', 'stdout', 'stderr', 'assertions', 'durationMs'].includes(key)) {
+        errors.push(`${label}.${key} is not allowed`)
+      }
+    }
+    requireString(check.id, `${label}.id`, { pattern: /^J[1-8](?:\.[A-Za-z0-9._-]+)?$/ })
+    if ('kind' in check && !CHECK_KINDS.has(check.kind)) errors.push(`${label}.kind must be observed, static, or manual`)
+    if (!Array.isArray(check.command) || check.command.length === 0 || check.command.some(item => typeof item !== 'string')) {
+      errors.push(`${label}.command must be a non-empty array of strings`)
+    }
+    if (!Number.isInteger(check.exitCode) || check.exitCode < 0 || check.exitCode > 255) {
+      errors.push(`${label}.exitCode must be an integer in 0..255`)
+    }
+    requireIso(check.startedAt, `${label}.startedAt`)
+    requireIso(check.endedAt, `${label}.endedAt`)
+    if (isIsoTimestamp(check.startedAt) && isIsoTimestamp(check.endedAt) && Date.parse(check.endedAt) < Date.parse(check.startedAt)) {
+      errors.push(`${label}.endedAt is before startedAt`)
+    }
+    requireField(errors, check, 'stdout', () => requireLog(check.stdout, `${label}.stdout`))
+    if ('stderr' in check) requireLog(check.stderr, `${label}.stderr`)
+    if (!Array.isArray(check.assertions) || check.assertions.length === 0) {
+      errors.push(`${label}.assertions must be a non-empty array`)
+    } else {
+      check.assertions.forEach((assertion, index) => {
+        const alabel = `${label}.assertions[${index}]`
+        if (!isPlainObject(assertion)) {
+          errors.push(`${alabel} must be an object`)
+          return
+        }
+        for (const key of Object.keys(assertion)) if (!['claim', 'observed', 'detail'].includes(key)) errors.push(`${alabel}.${key} is not allowed`)
+        requireString(assertion.claim, `${alabel}.claim`)
+        if (typeof assertion.observed !== 'boolean') errors.push(`${alabel}.observed must be a boolean`)
+        if ('detail' in assertion && assertion.detail !== null) requireString(assertion.detail, `${alabel}.detail`)
+      })
+    }
+    if ('durationMs' in check && (typeof check.durationMs !== 'number' || check.durationMs < 0)) {
+      errors.push(`${label}.durationMs must be a non-negative number`)
+    }
+  }
+}
+
+function requireField(errors, object, key, validate) {
+  if (!(key in object)) {
+    errors.push(`${key} is required`)
+    return
+  }
+  validate()
+}
+
+function requireFieldOrNull(errors, object, key, validate) {
+  if (!(key in object)) {
+    errors.push(`${key} is required`)
+    return
+  }
+  validate(object[key])
+}

package/40-checker/src/index.mjs

@@ -4,5 +4,8 @@ export { runManifestChecks, checkMarketEntry, DEFAULT_RUNTIME_VERSION, inferKind
 export { checkCapabilities, checkCredentials, checkLabels, checkImportTimeAdvisory, CAPABILITIES, LABELS } from './declarations.mjs'
 export { runRuntimeChecks } from './runtime.mjs'
 export { buildReport, formatText, formatSarif, writeReport } from './report.mjs'
+export { joinAdvice, DOCS_BASE } from './remediation.mjs'
 export { satisfies, validRange, parseVersion, compareVersions } from './semver.mjs'
 export { parseInstallSpec } from './install-spec.mjs'
+export { FLOW_IDS, FLOW_EVIDENCE_SCHEMA, evidenceHash, finalizeEvidence, journeyAggregate, isSandboxAttested, treeSha256, validateFlowEvidence } from './flow-evidence.mjs'
+export { sanitizedEnv, scrubProcessEnv, isSecretEnvName, isAllowedEnvName, envPolicy } from './sandbox-env.mjs'

package/40-checker/src/remediation.mjs

@@ -0,0 +1,137 @@
+/**
+ * Join a dsh-conformance/1 report with the remediation rule table.
+ *
+ * This module is deliberately pure: it never reads files, never writes, and
+ * never changes the report it receives. `buildReport()` calls it at the end so
+ * every report carries additive `advice[]` entries; the checker's verdict is
+ * untouched.
+ */
+
+import packageJson from '../../package.json' with { type: 'json' }
+
+/** Release-pinned guide base. `docs` in the rule table is a relative path. */
+export const DOCS_BASE = 'https://github.com/PerryLink/dsh-plugin-guide/blob/v0.4.4/'
+
+const LIVE = new Set(['FAIL', 'WARN'])
+const SEVERITY_RANK = { FAIL: 2, WARN: 1 }
+
+function tableOf(rules) {
+  if (!rules || typeof rules !== 'object') return {}
+  // Accept either the whole spec/1 object or a bare key→rule map.
+  if (rules.rules && typeof rules.rules === 'object') return rules.rules
+  if (rules.items && typeof rules.items === 'object') return rules.items
+  return rules
+}
+
+function versionOf(rules) {
+  if (rules && typeof rules.version === 'string') return rules.version
+  return typeof packageJson.version === 'string' ? packageJson.version : null
+}
+
+function docsUrlOf(rule, docsBase) {
+  if (!rule || typeof rule.docs !== 'string' || rule.docs.trim() === '') return null
+  const base = String(docsBase ?? DOCS_BASE)
+  const prefix = base.endsWith('/') ? base : `${base}/`
+  return `${prefix}${rule.docs.replace(/^\/+/, '')}`
+}
+
+function uniqueEvidence(...lists) {
+  const seen = new Set()
+  const out = []
+  for (const list of lists) {
+    for (const value of Array.isArray(list) ? list : []) {
+      if (typeof value !== 'string' || value === '' || seen.has(value)) continue
+      seen.add(value)
+      out.push(value)
+    }
+  }
+  return out.slice(0, 10)
+}
+
+/**
+ * Build additive advice from a report.
+ *
+ * One entry is produced per (check.id, detail.item) pair with FAIL/WARN — or,
+ * for a FAIL/WARN check with no live details, one entry keyed by check.clause.
+ * `gate` is the check's final result (PASS/WARN/FAIL) after report adjustments
+ * such as the ENTRY static-claim downgrade; `severity` follows that gate, so a
+ * FAIL detail under a check downgraded to WARN yields a WARN advice entry. The
+ * detail's own reason stays in `reason` for diagnostics.
+ *
+ * Duplicate details are merged: evidence is unioned, occurrences counted, and
+ * the specific reasons are joined for diagnostics.
+ *
+ * @param {object} report dsh-conformance/1 report
+ * @param {object} rules flat key→rule map (also accepts a { rules } or { items } wrapper)
+ * @param {string} [docsBase] absolute release-pinned guide base
+ * @returns {object[]} advice entries
+ */
+export function joinAdvice(report, rules, docsBase = DOCS_BASE) {
+  const table = tableOf(rules)
+  const version = versionOf(rules)
+  const merged = new Map()
+
+  const add = (check, key, gate, reason, evidence) => {
+    if (typeof key !== 'string' || key === '' || !LIVE.has(gate)) return false
+    const id = `${check.id}|${key}`
+    const current = merged.get(id)
+    if (!current) {
+      merged.set(id, {
+        check,
+        key,
+        gate,
+        reasons: typeof reason === 'string' && reason !== '' ? [reason] : [],
+        evidence: uniqueEvidence(evidence),
+        occurrences: 1,
+      })
+      return true
+    }
+    current.occurrences += 1
+    if (typeof reason === 'string' && reason !== '' && !current.reasons.includes(reason)) current.reasons.push(reason)
+    current.evidence = uniqueEvidence(current.evidence, evidence)
+    return true
+  }
+
+  for (const check of Array.isArray(report?.checks) ? report.checks : []) {
+    const liveDetails = (Array.isArray(check.details) ? check.details : [])
+      .filter(detail => detail && LIVE.has(detail.result))
+    let added = 0
+    for (const detail of liveDetails) if (add(check, detail.item, check.result, detail.reason, detail.evidence)) added += 1
+    // A runtime FAIL (DSC-04 / DSC-14) has no details; its clause is the only
+    // joinable key. Only use the fallback when no joinable detail was produced,
+    // so a specific detail always wins over the check-level summary.
+    if (added === 0 && LIVE.has(check.result)) {
+      add(check, check.clause, check.result, check.reason, check.evidence)
+    }
+  }
+
+  const advice = []
+  for (const entry of merged.values()) {
+    const rule = table[entry.key] ?? null
+    const item = {
+      key: entry.key,
+      gate: entry.gate,
+      severity: entry.gate,
+      title: rule?.title ?? entry.key,
+      why: rule?.why ?? null,
+      fix: rule?.fix ?? null,
+      docsUrl: docsUrlOf(rule, docsBase),
+      source: entry.check.id,
+      version,
+      evidence: entry.evidence,
+      reason: entry.reasons.slice(0, 3).join(' | '),
+      occurrences: entry.occurrences,
+      advisory: entry.check.advisory === true,
+    }
+    if (!rule) item.ruleMissing = true
+    advice.push(item)
+  }
+
+  // FAIL before WARN, then key/source for deterministic output.
+  advice.sort((a, b) => (
+    (SEVERITY_RANK[b.gate] ?? 0) - (SEVERITY_RANK[a.gate] ?? 0)
+    || a.key.localeCompare(b.key)
+    || a.source.localeCompare(b.source)
+  ))
+  return advice
+}