dsh-standards 1.4.1 → 1.6.0

package/40-checker/src/declarations.mjs

@@ -86,7 +86,7 @@ const C10_SUBPROCESS_METHODS = new Set(['execSync', 'execFileSync', 'spawnSync',
 
 const PARSE_CACHE = new WeakMap()
 
-function parseSource(source) {
+export function parseSource(source) {
   const cached = PARSE_CACHE.get(source)
   if (cached) return cached
   const record = { ast: null, error: null }
@@ -107,21 +107,21 @@ function parseSource(source) {
   return record
 }
 
-function normalizeRelative(relative) {
+export function normalizeRelative(relative) {
   return String(relative ?? '').replace(/\\/g, '/').replace(/^\.\//, '')
 }
 
 // Declaration files have no runtime behavior; parsing them for import-time
 // side effects or execution strings only creates noise.
-function isDeclarationFile(relative) {
+export function isDeclarationFile(relative) {
   return /\.d\.[cm]?ts$/i.test(String(relative ?? ''))
 }
 
-function identifierName(node) {
+export function identifierName(node) {
   return node?.type === 'Identifier' ? node.name : null
 }
 
-function memberPropertyName(node) {
+export function memberPropertyName(node) {
   if (!node || node.type !== 'MemberExpression') return null
   if (!node.computed && node.property?.type === 'Identifier') return node.property.name
   if (node.property?.type === 'Literal' && typeof node.property.value === 'string') return node.property.value
@@ -141,7 +141,7 @@ function calledFunctionName(call) {
   return null
 }
 
-function walkAst(root, visit) {
+export function walkAst(root, visit) {
   const ancestors = []
   const walkNode = (node) => {
     if (!node || typeof node.type !== 'string') return
@@ -163,7 +163,7 @@ function walkAst(root, visit) {
 
 // Module scope means "runs while the module is evaluated". Function bodies and
 // class method bodies are skipped; top-level if/try/loop bodies are not.
-function walkModuleScope(ast, visit) {
+export function walkModuleScope(ast, visit) {
   const ancestors = []
   const walkNode = (node) => {
     if (!node || typeof node.type !== 'string') return
@@ -295,7 +295,7 @@ function classifyLiteral(node, ancestors) {
   return 'unknown'
 }
 
-function literalStringValue(node) {
+export function literalStringValue(node) {
   if (node.type === 'Literal' && typeof node.value === 'string') return node.value
   if (node.type === 'TemplateElement' && node.value) {
     if (typeof node.value.cooked === 'string') return node.value.cooked
@@ -341,7 +341,7 @@ function literalCandidates(base) {
   return candidates
 }
 
-function resolveLocalSpecifier(fromRelative, specifier, byRelative) {
+export function resolveLocalSpecifier(fromRelative, specifier, byRelative) {
   const spec = String(specifier).replace(/\\/g, '/')
   if (!(spec.startsWith('./') || spec.startsWith('../') || spec === '.' || spec === '..')) return { kind: 'package' }
   const base = path.posix.normalize(path.posix.join(path.posix.dirname(normalizeRelative(fromRelative)), spec))
@@ -352,7 +352,7 @@ function resolveLocalSpecifier(fromRelative, specifier, byRelative) {
   return { kind: 'unresolved' }
 }
 
-function collectModuleEdges(ast) {
+export function collectModuleEdges(ast) {
   const edges = []
   walkAst(ast, (node) => {
     if (node.type === 'ImportDeclaration' || node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') {

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

@@ -28,6 +28,15 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { signEvidence } from './signature.mjs'
+
+// Signing helpers live in signature.mjs; re-exported here so callers that
+// already import the evidence model do not need a second module path.
+export {
+  SIGNATURE_ALG, SIGNATURE_SCHEMA, canonicalJson as signatureCanonicalJson,
+  evidenceSigningPayload, generateEd25519KeyPair, keyIdFromPublicKey,
+  signEvidence, verifyEvidenceSignature,
+} from './signature.mjs'
 
 export const FLOW_IDS = ['J1', 'J2', 'J3', 'J4', 'J5', 'J6', 'J7', 'J8']
 export const FLOW_EVIDENCE_SCHEMA = 'dsh-flow-evidence/2'
@@ -107,6 +116,18 @@ export function evidenceHashMatches(document) {
   return declared === evidenceHash(document)
 }
 
+/**
+ * Attach an Ed25519 signature to a flow-evidence document. The signature
+ * covers canonical JSON minus `signature` (the body plus `chain`), so it binds
+ * the declared chain hash while never changing `chain.evidenceHash`; it never
+ * upgrades a claim level. Verification is `verifyEvidenceSignature()`
+ * (re-exported from signature.mjs); structural acceptance remains
+ * `validateFlowEvidence()`.
+ */
+export function attachEvidenceSignature(document, privateKey, options = {}) {
+  return signEvidence(document, privateKey, options)
+}
+
 const DEFAULT_TREE_EXCLUDE = ['.git', 'node_modules']
 const TREE_EXCLUDE_ALWAYS = new Set(['.git', 'node_modules'])
 

package/40-checker/src/index.mjs

@@ -5,7 +5,8 @@ export { checkCapabilities, checkCredentials, checkLabels, checkImportTimeAdviso
 export { readSources, readSourcesWithStats, listSourceFiles, scanSourceFiles } from './util.mjs'
 export { runRuntimeChecks } from './runtime.mjs'
 export { runStaticBundleChecks } from './bundle-static.mjs'
-export { buildReport, formatText, formatSarif, writeReport, summarizeBlocking, DECLARATION_CHECKS } from './report.mjs'
+export { runSecurityChecks, checkLifecycleScripts, checkDynamicExecution, checkSensitiveFileReads, checkEgressEndpoints, checkOpaqueArtifacts, checkPromptInjectionClues, checkSupplyChain, checkProvenance, SECURITY_IDS } from './security.mjs'
+export { buildReport, formatText, formatSarif, writeReport, summarizeBlocking, buildSecurityView, DECLARATION_CHECKS, SECURITY_CHECKS, SECURITY_MANDATORY } from './report.mjs'
 export { joinAdvice, DOCS_BASE } from './remediation.mjs'
 export { satisfies, validRange, parseVersion, compareVersions } from './semver.mjs'
 export { parseInstallSpec } from './install-spec.mjs'

package/40-checker/src/report.mjs

@@ -13,8 +13,13 @@ export const ENTRY_RUN = ['DSC-01', 'DSC-02', 'DSC-03', 'DSC-11', 'DSC-12', 'DSC
 export const ENTRY_BLOCKING = ['C-1.1', 'C-1.2', 'C-1.4', 'C-3.1', 'C-3.2', 'C-3.5']
 export const ENTRY_RUNTIME_BLOCKING = [...ENTRY_BLOCKING, 'C-2.2', 'C-2.3']
 
+/** The four security checks that block in `--scope security`; the rest are advisory. */
+export const SECURITY_MANDATORY = ['DSC-15', 'DSC-16', 'DSC-17', 'DSC-21']
+export const SECURITY_CHECKS = new Set(['DSC-15', 'DSC-16', 'DSC-17', 'DSC-18', 'DSC-19', 'DSC-20', 'DSC-21', 'DSC-22'])
+
 function mandatoryFor(scope, profile, staticOnly, entryClaim) {
   if (scope === 'mvp') return MVP_CHECKS
+  if (scope === 'security') return SECURITY_MANDATORY
   if (scope === 'entry') return ENTRY_RUN.filter(id => (entryClaim !== 'static' || id !== 'DSC-14') && (id !== 'DSC-03' || profile === 'listing' || profile === 'both'))
   if (staticOnly) return STATIC_MANDATORY
   return profile === 'listing' || profile === 'both' ? LISTING_MANDATORY : PACKAGE_MANDATORY
@@ -68,6 +73,11 @@ export function howToEnableFor(item) {
   if (id === 'DSC-14') {
     return 'pass --host <app-boot/lib/index.js> for bundle G0-G3, or --runtime <path> for a plugin; omit --no-exec and --entry-claim static'
   }
+  if (id === 'DSC-15') return 'fix package.json#scripts so install lifecycle commands are auditable; --scope security makes DSC-15 blocking'
+  if (['DSC-16', 'DSC-17', 'DSC-21'].includes(id)) return 'provide a readable entry/source tree and rerun; --scope security makes this check blocking'
+  if (id === 'DSC-19') return 'provide a readable package tree; binaries are recorded by sha256, never executed'
+  if (id === 'DSC-22') return 'supply registry metadata or an attestation/signature field; without input this check is not-run'
+  if (['DSC-18', 'DSC-20'].includes(id)) return 'this check is advisory; it never blocks and needs no extra input'
   if (['DSC-11', 'DSC-12', 'DSC-13'].includes(id)) {
     if (/manifest unavailable/.test(reason)) return 'fix package.json; these declaration checks cannot run without a manifest'
     return 'run the full profile without --no-exec; declaration checks need source files'
@@ -108,8 +118,58 @@ 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', advice = true, declarations = null }) {
+function capSecurityCheck(item) {
+  if (item.result !== 'FAIL') return item
+  return {
+    ...item,
+    result: 'WARN',
+    reason: `capped WARN (non-security scope): ${item.reason ?? ''}`.trim(),
+    details: (item.details ?? []).map(detailRow => (
+      detailRow.result === 'FAIL'
+        ? { ...detailRow, result: 'WARN', reason: `capped WARN (non-security scope): ${detailRow.reason ?? ''}`.trim() }
+        : detailRow
+    )),
+  }
+}
+
+/**
+ * The additive `security` block. In `--scope security` the eight checks keep
+ * their real verdict (and four of them are mandatory); in every other scope a
+ * FAIL is capped to WARN so the default verdict cannot change.
+ */
+export function buildSecurityView(securityChecks, scope) {
+  const input = Array.isArray(securityChecks) ? securityChecks.filter(item => SECURITY_CHECKS.has(item.id)) : []
+  const checks = scope === 'security' ? input : input.map(capSecurityCheck)
+  // Only DSC-15/16/17 may block; DSC-21 is mandatory but its findings are
+  // capped at WARN, and DSC-18/19/20/22 are advisory by definition.
+  const blocking = checks
+    .filter(item => item.result === 'FAIL' && ['DSC-15', 'DSC-16', 'DSC-17'].includes(item.id))
+    .map(item => item.id)
+  const warn = checks.filter(item => item.result === 'WARN' && item.advisory !== true).map(item => item.id)
+  const advisory = checks.filter(item => item.result === 'WARN' && item.advisory === true).map(item => item.id)
+  const notRun = checks
+    .filter(item => item.result === 'NA' || item.result === 'ERROR' || item.coverage === 'not-run')
+    .map(item => item.id)
+  const mandatoryNotRun = SECURITY_MANDATORY.some(id => !checks.some(item => item.id === id && ['PASS', 'WARN', 'FAIL'].includes(item.result)))
+  let status
+  if (blocking.length > 0) status = 'fail'
+  else if (scope === 'security' && mandatoryNotRun) status = 'incomplete'
+  else if (warn.length > 0 || advisory.length > 0 || mandatoryNotRun) status = 'warn'
+  else status = 'pass'
+  return {
+    scope: scope === 'security' ? 'security' : 'advisory',
+    status,
+    checks,
+    blocking,
+    warn,
+    advisory,
+    notRun,
+  }
+}
+
+export function buildReport({ subject, anchor, checks, g4 = null, scope, profile, kind, staticOnly = false, entryRuntime = 'require', entryClaim = 'runtime', advice = true, declarations = null, runtimeChecks = null, securityChecks = null }) {
   const mandatory = mandatoryFor(scope, profile, staticOnly, entryClaim)
+  const security = buildSecurityView(securityChecks, scope)
   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'])
   const effectiveChecks = staticOnly
@@ -123,7 +183,12 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   const missing = mandatory.filter(id => !byId.has(id))
   const failed = selected.filter(item => item.result === 'FAIL')
   const errored = selected.filter(item => item.result === 'ERROR')
-  const notRun = selected.filter(item => !allowedNa(item, scope, profile, kind) && (item.coverage === 'not-run' || item.coverage === 'partial'))
+  // A static `partial` PASS is still a PASS for the mandatory set: it is
+  // recorded in buckets.partial / coverage.partial, and "what was not run" is
+  // its own signal. Only a check that did not run at all makes the report
+  // incomplete. Otherwise every bundle would be exit 2 forever, because the
+  // static subset can never be full without executing the package.
+  const notRun = selected.filter(item => !allowedNa(item, scope, profile, kind) && item.coverage === 'not-run')
   const notRunIds = [...new Set([...missing, ...errored.map(item => item.id), ...notRun.map(item => item.id)])]
   const warnings = selected.filter(item => item.result === 'WARN')
   const pass = selected.filter(item => item.result === 'PASS')
@@ -134,7 +199,7 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   const evaluatedAll = effectiveChecks.filter(item => ['PASS', 'WARN', 'FAIL'].includes(item.result))
   const naAll = effectiveChecks.filter(item => item.result === 'NA')
   const errorAll = effectiveChecks.filter(item => item.result === 'ERROR')
-  const notRunAll = effectiveChecks.filter(item => item.result !== 'NA' && (item.coverage === 'not-run' || item.coverage === 'partial'))
+  const notRunAll = effectiveChecks.filter(item => item.result !== 'NA' && item.coverage === 'not-run')
   const notRunAllIds = [...new Set([...notRunAll.map(item => item.id), ...errorAll.map(item => item.id), ...missing])]
   const entryBlockingIds = scope === 'entry' ? (entryClaim === 'static' ? ENTRY_BLOCKING : ENTRY_RUNTIME_BLOCKING) : null
   const entryBlocking = entryBlockingIds ? summarizeBlocking(effectiveChecks, entryBlockingIds) : null
@@ -156,7 +221,7 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
     } else if (status === 'pass' || status === 'warn') {
       level = `DSH-ENTRY static${status === 'warn' ? ' (warnings)' : ''}`
     }
-  } else if (scope !== 'mvp' && (status === 'pass' || status === 'warn')) {
+  } else if (scope !== 'mvp' && scope !== 'security' && (status === 'pass' || status === 'warn')) {
     const suffix = status === 'warn' ? ', warnings' : ''
     level = staticOnly ? `DS-C static${status === 'warn' ? ' (warnings)' : ''}` : profile === 'listing' || profile === 'both' ? `DS-C (listing${suffix})` : `DS-C (package${suffix})`
   }
@@ -176,6 +241,7 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
   const hygieneBucket = effectiveChecks.filter(item => item.result === 'WARN').map(item => bucketRow(item, {
     declaration: DECLARATION_CHECKS.has(item.id),
     advisory: item.advisory === true,
+    ...(SECURITY_CHECKS.has(item.id) ? { security: true } : {}),
   }))
   const notCheckedBucket = effectiveChecks
     .filter(item => item.result === 'NA' || item.result === 'ERROR')
@@ -235,6 +301,7 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
       entryBlocking,
     },
     buckets,
+    security,
     notChecked,
     metrics,
     conclusion: {
@@ -251,6 +318,11 @@ export function buildReport({ subject, anchor, checks, g4 = null, scope, profile
       reason: reasonParts.join('; '),
     },
   }
+  // Additive only: describes what actually executed (runtime/host), the
+  // elapsed time, and the isolation it used. It is a sibling of `checks` and
+  // never changes the verdict. Kept out of the 1.0.0 schema shape and only
+  // emitted when a runtime/host run was requested.
+  if (runtimeChecks) report.runtimeChecks = runtimeChecks
   // 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) {
@@ -302,6 +374,41 @@ function renderBucket(lines, title, rows, byId) {
   }
 }
 
+/**
+ * Runtime provenance: what actually ran, for how long, and where. A failed
+ * run must say why instead of silently falling back to static rows.
+ */
+function renderRuntime(lines, runtime) {
+  if (!runtime) return
+  if (!runtime.executed) {
+    // Do not repeat six not-run rows that the partial/not-checked buckets
+    // already explain; one line is enough to say nothing executed.
+    lines.push(`Runtime checks (not executed): ${runtime.reason ?? runtime.failure ?? 'no runtime requested'}`)
+    lines.push('')
+    return
+  }
+  const modes = Array.isArray(runtime.modes) && runtime.modes.length > 0 ? runtime.modes.join('+') : 'none'
+  const elapsed = Number.isFinite(runtime.durationMs) ? `${runtime.durationMs} ms` : 'n/a'
+  const isolation = runtime.isolation?.isolatedHome ? 'temporary DSH_HOME' : 'un-isolated'
+  lines.push(`Runtime checks (${modes}, ${elapsed}, ${isolation}):`)
+  if (runtime.failure) lines.push(`  failure: ${String(runtime.failure).replace(/\s+/g, ' ').slice(0, 200)}`)
+  const rows = Array.isArray(runtime.checks) ? runtime.checks : []
+  if (rows.length === 0) {
+    lines.push('  none')
+  } else {
+    for (const row of rows) {
+      const reason = String(row.reason ?? '').replace(/\s+/g, ' ').slice(0, 140)
+      lines.push(`  ${(ICON[row.result] ?? row.result).padEnd(4)} ${String(row.id).padEnd(7)} ${String(row.coverage ?? '-').padEnd(8)} ${reason}`)
+    }
+  }
+  const entry = runtime.entry
+  if (entry) {
+    const reason = String(entry.reason ?? '').replace(/\s+/g, ' ').slice(0, 140)
+    lines.push(`  ${(ICON[entry.result] ?? entry.result).padEnd(4)} ${String(entry.id).padEnd(7)} ${String(entry.coverage ?? '-').padEnd(8)} ${reason}`)
+  }
+  lines.push('')
+}
+
 export function formatText(report) {
   const lines = []
   const { subject, anchor = {}, conclusion, coverage } = report
@@ -318,11 +425,16 @@ export function formatText(report) {
   lines.push('')
   renderBucket(lines, 'Partly checked (static subset)', report.buckets?.partial ?? [], byId)
   lines.push('')
+  renderRuntime(lines, report.runtimeChecks)
   renderBucket(lines, 'Not checked (NA / not-run / ERROR)', report.buckets?.notChecked ?? [], byId)
   lines.push('')
   const passed = (report.checks ?? []).filter(item => item.result === 'PASS')
   lines.push(`passed (${passed.length}): ${passed.map(item => item.id).join(', ') || 'none'}`)
   lines.push(`coverage: total=${coverage.total ?? report.checks.length} checked=${coverage.checked ?? coverage.pass + coverage.warn + coverage.fail} pass=${coverage.pass} warn=${coverage.warn} fail=${coverage.fail} na=${coverage.na} notRun=${coverage.notRun} partial=${coverage.partial ?? 0} error=${coverage.error} advisory=${coverage.advisory}`)
+  if (report.security) {
+    const security = report.security
+    lines.push(`security: scope=${security.scope} status=${security.status} blocking=[${(security.blocking ?? []).join(', ')}] warn=[${(security.warn ?? []).join(', ')}] advisory=[${(security.advisory ?? []).join(', ')}] notRun=[${(security.notRun ?? []).join(', ')}]`)
+  }
   if (coverage.entryBlocking) {
     const blocking = coverage.entryBlocking
     lines.push(`entryBlocking: checked=${blocking.checked?.length ?? '?'}/${blocking.required} failed=[${(blocking.failed ?? []).join(', ')}] notChecked=[${(blocking.notChecked ?? []).join(', ')}] pass=${blocking.pass}`)

package/40-checker/src/runtime-child.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Runs L1-L3 in a disposable child process so a plugin cannot block or take over
+// the checker. Input: JSON on stdin. Output: one marker line + JSON on fd 3.
+//
+// The child is *expected to be hostile*: a plugin may leave timers, sockets or
+// workers referenced after `dispose()`. Waiting for the process to exit then
+// looks like a hang even though every check finished, so the result is written
+// first and the process is terminated in the write callback. The parent also
+// resolves on the marker line, so a plugin that keeps the event loop alive
+// cannot turn a completed run into "killed after timeout".
+import fs from 'node:fs'
+import { runRuntimeChecks } from './runtime.mjs'
+import { readSources } from './util.mjs'
+import { scrubProcessEnv } from './sandbox-env.mjs'
+
+export const MARKER = '__DSH_RUNTIME_CHECKS__'
+
+const chunks = []
+for await (const chunk of process.stdin) chunks.push(chunk)
+const input = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+
+// This process imports the inspected package; keep only allowlisted env keys,
+// then apply the caller-supplied disposable HOME/DSH_HOME/TMPDIR. DSH_HOME is
+// deliberately not allowlisted: an inherited real profile must never reach a
+// plugin, while an explicit temp directory from the checker is trusted.
+scrubProcessEnv()
+const overrides = {
+  DSH_HOME: input.home,
+  HOME: input.home,
+  USERPROFILE: input.home,
+  TMPDIR: input.tmp,
+  TEMP: input.tmp,
+  TMP: input.tmp,
+  XDG_CONFIG_HOME: input.home ? `${input.home}/.config` : undefined,
+  XDG_DATA_HOME: input.home ? `${input.home}/.local/share` : undefined,
+  XDG_CACHE_HOME: input.home ? `${input.home}/.cache` : undefined,
+}
+for (const [key, value] of Object.entries(overrides)) {
+  if (typeof value === 'string' && value !== '') process.env[key] = value
+}
+
+const started = process.hrtime.bigint()
+let payload
+try {
+  let sources = []
+  try { sources = readSources(input.dir) } catch { sources = [] }
+  const checks = await runRuntimeChecks({ ...input, sources })
+  payload = { checks, durationMs: Number((process.hrtime.bigint() - started) / 1_000_000n), error: null }
+} catch (error) {
+  payload = {
+    checks: [],
+    durationMs: Number((process.hrtime.bigint() - started) / 1_000_000n),
+    error: String(error?.stack ?? error?.message ?? error).slice(0, 2000),
+  }
+}
+
+const line = `${MARKER}${JSON.stringify(payload)}\n`
+// The plugin shares stdout, so results go to a dedicated pipe (fd 3) that a
+// plugin printing logs cannot interleave with or truncate.
+const writeResult = (callback) => {
+  try { fs.writeSync(3, line) } catch {
+    // A direct `node src/runtime-child.mjs` has no fd 3: fall back to stdout.
+    process.stdout.write(line, callback)
+    return
+  }
+  callback()
+}
+writeResult(() => process.exit(0))

package/40-checker/src/runtime.mjs

@@ -193,7 +193,9 @@ export async function runRuntimeChecks(input) {
   const provideResult = declared.length === 0 ? 'NA' : worst(provideDetails.map(item => item.result))
   const provideCheck = check({
     id: 'DSC-05', clause: 'C-5', layer: 'L1', result: provideResult,
-    reason: provideDetails.filter(item => item.result !== 'PASS' && item.result !== 'NA').map(item => `${item.item}: ${item.reason}`).join(' | '),
+    // NA is a real finding too ("nothing declared"), so keep its reason; an
+    // empty reason here used to make DSC-05 look unexplained in the report.
+    reason: provideDetails.filter(item => item.result !== 'PASS').map(item => `${item.item}: ${item.reason}`).join(' | '),
     details: provideDetails,
   })