dsh-standards 1.2.2 → 1.3.0

package/40-checker/scripts/build-sidecar.mjs

@@ -0,0 +1,484 @@
+#!/usr/bin/env node
+/**
+ * build-sidecar — generate or refresh `publish/sidecar.json`
+ * (`dsh-market-sidecar/1`), the index cache the market can read without
+ * executing a plugin and without treating us as an issuer.
+ *
+ * Two modes:
+ *   fresh     read one `dsh-level-audit/1` JSON (`dsh-levels <dir> --format
+ *             json`) plus a package tarball, emit one entry keyed name@version.
+ *   lifecycle read an existing sidecar (`--prev`) and only recompute
+ *             `lifecycle` from `--today` and `publish/withdrawals.json`.
+ *
+ * Deliberately absent: advice (author view), issuer / recordHash / verifyUrl
+ * (we are not an issuer). `--today` pins the clock so CI and tests are
+ * reproducible.
+ *
+ * Usage:
+ *   node 40-checker/scripts/build-sidecar.mjs --levels audit.json \
+ *     --name dsh-security-pack --version 3.0.1 --tarball dsh-security-pack-3.0.1.tgz \
+ *     --out publish/sidecar.json --today 2026-11-06
+ *
+ *   node 40-checker/scripts/build-sidecar.mjs --prev publish/sidecar.json \
+ *     --withdrawals publish/withdrawals.json --out publish/sidecar.json \
+ *     --today 2026-11-06
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const ROOT = path.resolve(HERE, '..', '..')
+const SCHEMA = 'dsh-market-sidecar/1'
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+const HEX40 = /^[0-9a-f]{40}$/
+const HEX64 = /^[0-9a-f]{64}$/
+const LIFECYCLE = new Set(['active', 'stale', 'under-review', 'withdrawn'])
+const FORBIDDEN = new Set(['advice', 'issuer', 'recordHash', 'verifyUrl'])
+const NOT_CLAIMED = ['official', 'certification', 'security-audit', 'endorsement', 'ordering', 'comparison', 'warranty']
+
+function usage() {
+  console.log(`build-sidecar — publish/sidecar.json (${SCHEMA})
+
+Usage:
+  node 40-checker/scripts/build-sidecar.mjs --levels <audit.json> [options]
+  node 40-checker/scripts/build-sidecar.mjs --prev <sidecar.json> [options]
+
+Options:
+  --levels <file>          one dsh-level-audit/1 JSON (single package)
+  --prev <file>            existing sidecar; entries survive a lifecycle refresh
+  --withdrawals <file>     append-only withdrawal list (default: alongside --prev)
+  --out <file>             output path, default publish/sidecar.json
+  --today <YYYY-MM-DD>     fixed clock for generatedAt/checkedAt/lifecycle
+  --ttl-days <n>           validity policy, default 90 (writes "90d")
+  --name <name>            subject name; default package.json / audit.subject
+  --version <version>      subject version; default package.json / audit.subject
+  --package <dir>          package.json directory for name/version
+  --tarball <file>         package tarball; sha256 is recorded in subject
+  --tarball-sha256 <hex>   explicit tarball sha256 (checked against --tarball)
+  --evidence-url <url>     optional https evidence URL
+  --evidence-file <file>   hash this file into evidence.sha256
+  --evidence-sha256 <hex>  explicit evidence sha256
+  --checker-version <v>    default dsh-standards package.json version
+  --checker-sha <40hex>    default git HEAD when available
+  --index-url <url>        default https://awesome-dsh-plugin.com/index.json
+  --organizer              sets selfAssessed=false (default true)
+  --help                   show this help
+
+Exit codes: 0 written/unchanged; 3 invalid input.`)
+}
+
+function readJson(file, label) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`${label} is not readable JSON (${file}): ${error.message}`)
+  }
+}
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+}
+
+function normalizeDate(value, label) {
+  const match = String(value ?? '').match(/^(\d{4}-\d{2}-\d{2})(?:[T ].*)?$/)
+  if (!match) throw new Error(`${label} must be YYYY-MM-DD, got ${JSON.stringify(value)}`)
+  const day = match[1]
+  const parsed = new Date(`${day}T00:00:00.000Z`)
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== day) {
+    throw new Error(`${label} is not a real date: ${day}`)
+  }
+  return day
+}
+
+function addDays(day, count) {
+  const date = new Date(`${day}T00:00:00.000Z`)
+  date.setUTCDate(date.getUTCDate() + count)
+  return date.toISOString().slice(0, 10)
+}
+
+function todayUtc() {
+  return new Date().toISOString().slice(0, 10)
+}
+
+function parseArgs(argv) {
+  const options = {
+    levels: null, prev: null, withdrawals: null,
+    out: 'publish/sidecar.json',
+    today: null, todayProvided: false, ttlDays: 90,
+    name: null, version: null, packageDir: null,
+    tarball: null, tarballSha256: null,
+    evidenceUrl: null, evidenceFile: null, evidenceSha256: null,
+    checkerVersion: null, checkerSha: null,
+    indexUrl: 'https://awesome-dsh-plugin.com/index.json',
+    selfAssessed: true,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    const next = () => {
+      const value = argv[i + 1]
+      if (value === undefined) throw new Error(`${arg} needs a value`)
+      i += 1
+      return value
+    }
+    if (arg === '--levels') options.levels = next()
+    else if (arg === '--prev') options.prev = next()
+    else if (arg === '--withdrawals') options.withdrawals = next()
+    else if (arg === '--out') options.out = next()
+    else if (arg === '--today') { options.today = normalizeDate(next(), '--today'); options.todayProvided = true }
+    else if (arg === '--ttl-days') options.ttlDays = Number(next())
+    else if (arg === '--name') options.name = next()
+    else if (arg === '--version') options.version = next()
+    else if (arg === '--package') options.packageDir = next()
+    else if (arg === '--tarball') options.tarball = next()
+    else if (arg === '--tarball-sha256') options.tarballSha256 = next().toLowerCase()
+    else if (arg === '--evidence-url') options.evidenceUrl = next()
+    else if (arg === '--evidence-file') options.evidenceFile = next()
+    else if (arg === '--evidence-sha256') options.evidenceSha256 = next().toLowerCase()
+    else if (arg === '--checker-version') options.checkerVersion = next()
+    else if (arg === '--checker-sha') options.checkerSha = next().toLowerCase()
+    else if (arg === '--index-url') options.indexUrl = next()
+    else if (arg === '--organizer') options.selfAssessed = false
+    else if (arg === '--help' || arg === '-h') { usage(); process.exit(0) }
+    else throw new Error(`unknown option: ${arg}`)
+  }
+  if (!options.levels && !options.prev) throw new Error('one of --levels or --prev is required')
+  if (!Number.isInteger(options.ttlDays) || options.ttlDays < 1 || options.ttlDays > 3650) {
+    throw new Error('--ttl-days must be an integer between 1 and 3650')
+  }
+  return options
+}
+
+function readPackageMeta(directory) {
+  if (!directory) return {}
+  const file = path.join(directory, 'package.json')
+  if (!fs.existsSync(file)) return {}
+  try {
+    return readJson(file, 'package.json')
+  } catch {
+    return {}
+  }
+}
+
+function pickLevel(row, keys, fallback) {
+  const level = {}
+  if (row && typeof row === 'object') {
+    for (const key of keys) {
+      if (typeof row[key] === 'string' && row[key] !== '') level[key] = row[key]
+    }
+  }
+  if (!level.state) level.state = fallback
+  return level
+}
+
+function gitHead() {
+  try {
+    const sha = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: ROOT,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    return HEX40.test(sha) ? sha : null
+  } catch {
+    return null
+  }
+}
+
+function loadPrev(file) {
+  const prev = readJson(file, 'previous sidecar')
+  if (prev.schema !== SCHEMA) throw new Error(`previous sidecar schema is ${JSON.stringify(prev.schema)}, expected ${SCHEMA}`)
+  if (!prev.entries || typeof prev.entries !== 'object' || Array.isArray(prev.entries)) {
+    throw new Error('previous sidecar has no entries object')
+  }
+  if (typeof prev.generatedAt !== 'string') throw new Error('previous sidecar has no generatedAt')
+  return prev
+}
+
+function parseWithdrawals(file) {
+  const result = { exact: new Map(), names: new Map(), records: 0 }
+  if (!file) return result
+  const raw = readJson(file, 'withdrawals')
+  let rows
+  if (Array.isArray(raw)) rows = raw
+  else if (Array.isArray(raw.withdrawals)) rows = raw.withdrawals
+  else if (raw.withdrawals && typeof raw.withdrawals === 'object') {
+    rows = Object.entries(raw.withdrawals).map(([key, value]) => ({ key, ...(typeof value === 'string' ? { reason: value } : value) }))
+  } else if (raw.entries && typeof raw.entries === 'object') {
+    rows = Object.entries(raw.entries).map(([key, value]) => ({ key, ...(typeof value === 'string' ? { reason: value } : value) }))
+  } else {
+    throw new Error('withdrawals must be an array or {"withdrawals":[...]} / {"entries":{...}}')
+  }
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') throw new Error('every withdrawal record must be an object')
+    let name = row.name
+    let version = row.version
+    if (row.key) {
+      const at = String(row.key).lastIndexOf('@')
+      if (at <= 0) throw new Error(`withdrawal key must look like name@version: ${row.key}`)
+      name = String(row.key).slice(0, at)
+      version = String(row.key).slice(at + 1)
+    }
+    if (typeof name !== 'string' || name === '') throw new Error('withdrawal record needs a name')
+    const record = {}
+    const since = row.date ?? row.withdrawnAt ?? row.since
+    if (since !== undefined) record.since = normalizeDate(since, 'withdrawal date')
+    if (row.reason !== undefined) record.reason = String(row.reason)
+    result.records += 1
+    if (version !== undefined && version !== null && version !== '') {
+      result.exact.set(`${name}@${version}`, record)
+    } else {
+      result.names.set(name, record)
+    }
+  }
+  return result
+}
+
+function entryFromAudit(audit, options, levelFile) {
+  const targetDir = audit.target?.dir
+    ? path.resolve(path.dirname(levelFile), audit.target.dir)
+    : options.packageDir
+  const meta = readPackageMeta(options.packageDir ?? targetDir)
+  const name = options.name ?? audit.subject?.name ?? meta.name
+  const version = options.version ?? audit.subject?.version ?? meta.version
+  if (typeof name !== 'string' || name === '') throw new Error('cannot determine subject.name; pass --name or --package')
+  if (typeof version !== 'string' || version === '') throw new Error('cannot determine subject.version; pass --version or --package')
+
+  const auditLevels = audit.levels && typeof audit.levels === 'object' ? audit.levels : {}
+  const levels = {
+    entry: pickLevel(auditLevels.entry, ['state', 'claim'], 'not-run'),
+    flow: pickLevel(auditLevels.flow, ['state'], 'not-run'),
+    boost: pickLevel(auditLevels.boost, ['state'], 'not-measured'),
+  }
+
+  let checkedAt
+  try {
+    checkedAt = normalizeDate(audit.generatedAt, 'audit.generatedAt')
+  } catch {
+    checkedAt = options.today ?? todayUtc()
+  }
+  const expiresAt = addDays(checkedAt, options.ttlDays)
+
+  let tarballSha256 = options.tarballSha256 ?? audit.subject?.tarballSha256 ?? null
+  if (tarballSha256 !== null) tarballSha256 = String(tarballSha256).toLowerCase()
+  if (options.tarball) {
+    const computed = sha256File(options.tarball)
+    if (tarballSha256 !== null && tarballSha256 !== computed) {
+      throw new Error(`--tarball-sha256 does not match ${options.tarball}`)
+    }
+    tarballSha256 = computed
+  }
+  if (tarballSha256 !== null && !HEX64.test(tarballSha256)) throw new Error('tarball sha256 must be 64 hex chars')
+
+  let evidenceSha256 = options.evidenceSha256 ?? null
+  if (options.evidenceFile) {
+    const computed = sha256File(options.evidenceFile)
+    if (evidenceSha256 !== null && evidenceSha256 !== computed) {
+      throw new Error('--evidence-sha256 does not match --evidence-file')
+    }
+    evidenceSha256 = computed
+  }
+  if (evidenceSha256 !== null && !HEX64.test(evidenceSha256)) throw new Error('evidence sha256 must be 64 hex chars')
+
+  const evidence = {}
+  if (options.evidenceUrl) {
+    let parsed
+    try { parsed = new URL(options.evidenceUrl) } catch { throw new Error(`--evidence-url is not a URL: ${options.evidenceUrl}`) }
+    if (parsed.protocol !== 'https:') throw new Error('--evidence-url must be https')
+    evidence.url = options.evidenceUrl
+  }
+  if (evidenceSha256 !== null) evidence.sha256 = evidenceSha256
+
+  return {
+    key: `${name}@${version}`,
+    entry: {
+      subject: { name, version, tarballSha256 },
+      levels,
+      evidence,
+      validity: { checkedAt, expiresAt, policy: `${options.ttlDays}d` },
+      lifecycle: 'active',
+      selfAssessed: options.selfAssessed,
+    },
+  }
+}
+
+function withdrawalFor(key, entry, withdrawals, previous) {
+  if (withdrawals.exact.has(key)) return withdrawals.exact.get(key)
+  const byName = withdrawals.names.get(entry.subject.name)
+  if (byName) return byName
+  if (previous?.lifecycle === 'withdrawn') {
+    return previous.lifecycleDetail ?? {}
+  }
+  return null
+}
+
+function applyLifecycle(entries, previousEntries, options, withdrawals) {
+  const counts = { active: 0, stale: 0, 'under-review': 0, withdrawn: 0 }
+  for (const [key, entry] of Object.entries(entries)) {
+    const previous = previousEntries?.[key]
+    const withdrawn = withdrawalFor(key, entry, withdrawals, previous)
+    if (withdrawn) {
+      entry.lifecycle = 'withdrawn'
+      if (Object.keys(withdrawn).length > 0) entry.lifecycleDetail = withdrawn
+      else if (previous?.lifecycleDetail) entry.lifecycleDetail = previous.lifecycleDetail
+      else delete entry.lifecycleDetail
+    } else if (previous?.lifecycle === 'under-review') {
+      entry.lifecycle = 'under-review'
+      if (previous.lifecycleDetail) entry.lifecycleDetail = previous.lifecycleDetail
+    } else if (entry.validity?.expiresAt && options.today > entry.validity.expiresAt) {
+      entry.lifecycle = 'stale'
+    } else {
+      entry.lifecycle = 'active'
+    }
+    if (entry.lifecycle === 'active') delete entry.lifecycleDetail
+    else if (entry.lifecycle === 'stale') delete entry.lifecycleDetail
+    counts[entry.lifecycle] = (counts[entry.lifecycle] ?? 0) + 1
+  }
+  return counts
+}
+
+function walkKeys(value, trail, callback) {
+  if (!value || typeof value !== 'object') return
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walkKeys(item, `${trail}[${index}]`, callback))
+    return
+  }
+  for (const [key, child] of Object.entries(value)) {
+    callback(key, `${trail}.${key}`)
+    walkKeys(child, `${trail}.${key}`, callback)
+  }
+}
+
+function validateSidecar(sidecar) {
+  if (sidecar.schema !== SCHEMA) throw new Error(`sidecar schema must be ${SCHEMA}`)
+  if (typeof sidecar.generatedAt !== 'string' || Number.isNaN(Date.parse(sidecar.generatedAt))) {
+    throw new Error('sidecar.generatedAt is not an ISO timestamp')
+  }
+  if (!sidecar.index || sidecar.index.format !== 1 || typeof sidecar.index.url !== 'string') {
+    throw new Error('sidecar.index must be {url, format:1}')
+  }
+  if (!sidecar.checker || typeof sidecar.checker.name !== 'string' || typeof sidecar.checker.version !== 'string') {
+    throw new Error('sidecar.checker must name a checker version')
+  }
+  if (sidecar.checker.sha !== null && !HEX40.test(String(sidecar.checker.sha))) {
+    throw new Error('sidecar.checker.sha must be null or 40 hex chars')
+  }
+  if (!Array.isArray(sidecar.notClaimed) || sidecar.notClaimed.length !== NOT_CLAIMED.length) {
+    throw new Error('sidecar.notClaimed must list the fixed not-claimed set')
+  }
+  if (!sidecar.entries || typeof sidecar.entries !== 'object' || Array.isArray(sidecar.entries)) {
+    throw new Error('sidecar.entries must be an object')
+  }
+  for (const [key, entry] of Object.entries(sidecar.entries)) {
+    if (!entry?.subject || typeof entry.subject.name !== 'string' || typeof entry.subject.version !== 'string') {
+      throw new Error(`${key}: subject.name/subject.version are required`)
+    }
+    if (key !== `${entry.subject.name}@${entry.subject.version}`) throw new Error(`${key}: key does not match subject`)
+    if (entry.subject.tarballSha256 !== null && !HEX64.test(String(entry.subject.tarballSha256))) {
+      throw new Error(`${key}: subject.tarballSha256 must be null or 64 hex chars`)
+    }
+    if (!entry.levels || typeof entry.levels !== 'object') throw new Error(`${key}: levels are required`)
+    for (const id of ['entry', 'flow', 'boost']) {
+      if (!entry.levels[id] || typeof entry.levels[id].state !== 'string' || entry.levels[id].state === '') {
+        throw new Error(`${key}: levels.${id}.state is required`)
+      }
+    }
+    if (!entry.validity || !DATE.test(String(entry.validity.checkedAt))) throw new Error(`${key}: validity.checkedAt is required`)
+    if (!DATE.test(String(entry.validity.expiresAt))) throw new Error(`${key}: validity.expiresAt is required`)
+    if (typeof entry.validity.policy !== 'string') throw new Error(`${key}: validity.policy is required`)
+    if (!LIFECYCLE.has(entry.lifecycle)) throw new Error(`${key}: lifecycle must be one of ${[...LIFECYCLE].join(', ')}`)
+    if (typeof entry.selfAssessed !== 'boolean') throw new Error(`${key}: selfAssessed must be boolean`)
+    if (!entry.evidence || typeof entry.evidence !== 'object' || Array.isArray(entry.evidence)) {
+      throw new Error(`${key}: evidence must be an object`)
+    }
+    if (entry.evidence.url !== undefined) {
+      let url
+      try { url = new URL(entry.evidence.url) } catch { throw new Error(`${key}: evidence.url is not a URL`) }
+      if (url.protocol !== 'https:') throw new Error(`${key}: evidence.url must be https`)
+    }
+    if (entry.evidence.sha256 !== undefined && !HEX64.test(String(entry.evidence.sha256))) {
+      throw new Error(`${key}: evidence.sha256 must be 64 hex chars`)
+    }
+  }
+  walkKeys(sidecar, 'sidecar', (key, where) => {
+    if (FORBIDDEN.has(key)) throw new Error(`${where} is forbidden in a sidecar (${[...FORBIDDEN].join(', ')})`)
+  })
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const today = options.today ?? todayUtc()
+  const outFile = path.resolve(options.out)
+  const prev = options.prev ? loadPrev(path.resolve(options.prev)) : null
+  const withdrawalsFile = options.withdrawals
+    ? path.resolve(options.withdrawals)
+    : prev && options.prev
+      ? path.join(path.dirname(path.resolve(options.prev)), 'withdrawals.json')
+      : null
+  let withdrawals = { exact: new Map(), names: new Map(), records: 0 }
+  if (withdrawalsFile && fs.existsSync(withdrawalsFile)) withdrawals = parseWithdrawals(withdrawalsFile)
+  else if (options.withdrawals) throw new Error(`withdrawals file not found: ${withdrawalsFile}`)
+
+  const previousEntries = prev ? prev.entries : null
+  let entries = previousEntries ? JSON.parse(JSON.stringify(previousEntries)) : {}
+  let generatedAt = prev?.generatedAt ?? null
+  if (options.levels) {
+    const levelFile = path.resolve(options.levels)
+    const audit = readJson(levelFile, 'level audit')
+    if (!audit.levels || typeof audit.levels !== 'object') throw new Error('--levels must be a dsh-level-audit/1 JSON')
+    const built = entryFromAudit(audit, options, levelFile)
+    entries[built.key] = built.entry
+    generatedAt = options.todayProvided ? `${today}T00:00:00.000Z` : new Date().toISOString()
+  }
+  if (!generatedAt) throw new Error('no --prev and no --levels generatedAt')
+
+  const checkerPkg = readPackageMeta(ROOT)
+  const checkerVersion = options.checkerVersion ?? checkerPkg.version
+  if (typeof checkerVersion !== 'string' || checkerVersion === '') throw new Error('cannot determine checker version')
+  const checkerSha = options.checkerSha ?? gitHead()
+  if (checkerSha !== null && !HEX40.test(checkerSha)) throw new Error('--checker-sha must be 40 hex chars')
+  try {
+    const parsed = new URL(options.indexUrl)
+    if (parsed.protocol !== 'https:') throw new Error()
+  } catch {
+    throw new Error('--index-url must be https')
+  }
+
+  const counts = applyLifecycle(entries, previousEntries, { today }, withdrawals)
+  const sortedEntries = Object.fromEntries(Object.keys(entries).sort().map(key => [key, entries[key]]))
+  const sidecar = {
+    schema: SCHEMA,
+    generatedAt,
+    index: { url: options.indexUrl, format: 1 },
+    checker: { name: 'dsh-standards', version: checkerVersion, sha: checkerSha },
+    notClaimed: [...NOT_CLAIMED],
+    entries: sortedEntries,
+  }
+  validateSidecar(sidecar)
+
+  const text = `${JSON.stringify(sidecar, null, 2)}\n`
+  let written = false
+  if (!fs.existsSync(outFile) || fs.readFileSync(outFile, 'utf8') !== text) {
+    fs.mkdirSync(path.dirname(outFile), { recursive: true })
+    fs.writeFileSync(outFile, text)
+    written = true
+  }
+  console.log(JSON.stringify({
+    out: outFile,
+    schema: SCHEMA,
+    generatedAt,
+    entries: Object.keys(sortedEntries).length,
+    lifecycle: counts,
+    withdrawals: { records: withdrawals.records, file: withdrawalsFile && fs.existsSync(withdrawalsFile) ? withdrawalsFile : null },
+    written,
+    unchanged: !written,
+  }, null, 2))
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`build-sidecar: ${error.message}`)
+  process.exitCode = 3
+}

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

@@ -36,7 +36,7 @@ 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'
@@ -77,6 +77,7 @@ 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
@@ -452,6 +453,10 @@ async function main() {
         ? `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,
@@ -460,6 +465,7 @@ async function main() {
         at: generatedAt,
         kind: producerKind,
         runner: sandboxPlan ? 'flow-collect/2-sandbox' : 'flow-collect/1',
+        ...ciFields,
       },
       ...(sandbox ? { sandbox } : {}),
       subject,

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,12 +169,21 @@ 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,
@@ -185,6 +205,8 @@ 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,
@@ -205,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,
@@ -391,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) {
@@ -409,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 = {
@@ -418,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

@@ -7,14 +7,10 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const here = dirname(fileURLToPath(import.meta.url))
-const testDir = join(here, '..', 'test')
-if (!existsSync(testDir)) {
-  console.log('checker tests are not shipped in the npm package; nothing to run')
-  process.exit(0)
-}
-const files = readdirSync(testDir).filter((f) => f.endsWith('.test.mjs')).map((f) => join(testDir, f))
+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('no test files found; nothing to run')
+  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' })