fini-proof 0.3.0

package/src/cli.mjs

@@ -0,0 +1,258 @@
+// fini-proof command line. Exit codes: 0 PASS · 1 FAIL · 2 usage · 3 NOT_MEASURED · 4 licence refused.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { check, ENGINES, EXIT, prove, scanWith, TOOL_VERSION, sha256 } from './runner.mjs'
+import { loadBaseline, listFiles, repoInfo } from './files.mjs'
+import { toSarif, toText } from './report.mjs'
+import { entitlement, verifyLicence, findLicenceKey } from './licence.mjs'
+import { exportUsage, readUsage, recordRun } from './usage.mjs'
+import { serveMcp } from './mcp.mjs'
+import { runHook } from './hooks.mjs'
+import { DEFAULT_API, gzipWanted, uploadEvidence } from './upload.mjs'
+import { readEvidenceFile, snapshotOf } from './evidence.mjs'
+import { applyStaleness, deriveStates, stateDocument, stateText } from './state.mjs'
+
+const HELP = `fini-proof ${TOOL_VERSION} — proof-based code verification
+
+  fini-proof check [--base <ref>] [--format text|json|sarif] [--fail-on high|medium|low|none]
+                   [--sarif-out <file>] [--json-out <file>] [--evidence <file>] [--engine <id>]... [--only <file>]... [--root <dir>]
+                   [--upload [--repository <owner/name>] [--upload-gzip]]   send the evidence to your Developer workspace
+                                                            (FINI_PROOF_API_KEY; FINI_PROOF_API, default ${DEFAULT_API})
+  fini-proof state [--against <evidence.json>] [--format text|json] [check options]
+                   per property: PROVEN · FAILED · NOT_MEASURED · STALE · ADVISORY. Without --against it runs the
+                   check now; with --against it runs nothing and marks STALE what changed since that evidence
+  fini-proof evidence verify <evidence.json>                      re-check an evidence file's digest (exit 1 = edited)
+  fini-proof prove --engine <id> --file <path> [--line <n>]    re-run one finding (exit 1 = still there)
+  fini-proof negctl <control-id> | --all                          show a check can fail (planted defect → caught)
+  fini-proof baseline [--reset]                                   write the skip ratchet baseline (can only go down)
+  fini-proof usage [--export <file>]                              local usage meter (runs, repos, seats)
+  fini-proof licence [status]                                     licence / trial status
+  fini-proof mcp                                                  MCP server on stdio (tools: check, explain_finding, list_rules)
+  fini-proof hook claude                                          Claude Code hook (Stop / PostToolUse): stdin JSON, exit 2 blocks
+
+Verdicts: PASS · FAIL · NOT_MEASURED (a check that could not run is never a PASS).
+Maker attestation: FINI_PROOF_MAKER_KIND (human|agent) / _ID / _MODEL / _SESSION, else the git author (kind unknown).
+gitleaks: used when on PATH (FINI_PROOF_GITLEAKS=<path> | off); never downloaded.
+Engines: ${ENGINES.map((e) => e.id).join(', ')}`
+
+function parse(argv) {
+  const o = { _: [], engine: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a.startsWith('--')) { o._.push(a); continue }
+    const [k, inline] = a.slice(2).split('=')
+    const flag = ['all', 'reset', 'help', 'version', 'upload', 'upload-gzip'].includes(k)
+    const v = flag ? true : (inline ?? argv[++i])
+    if (!flag && v === undefined) throw new Error(`--${k} needs a value`)
+    if (k === 'engine') o.engine.push(v)
+    else if (k === 'only') (o.only ||= []).push(v)
+    else o[k.replace(/-(\w)/g, (_, x) => x.toUpperCase())] = v
+  }
+  return o
+}
+
+const out = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n')
+const err = (s) => process.stderr.write(s.endsWith('\n') ? s : s + '\n')
+
+/**
+ * The one licensed check path — used by `check`, the MCP `check` tool and the Claude Code hook, so all three enforce
+ * the same licence, write the same evidence and meter the same way. Returns { rc, result?, ent?, evidencePath?, error? }.
+ */
+export function executeCheck({ root, base, failOn, engines = [], only, licence, evidence, sarifOut, jsonOut, maker }) {
+  const unknown = engines.filter((e) => !ENGINES.some((x) => x.id === e))
+  if (unknown.length) return { rc: EXIT.USAGE, error: `unknown engine(s): ${unknown.join(', ')}` }
+  const info = repoInfo(root)
+  const repoDigest = info.rootCommit ? sha256(info.rootCommit) : sha256(root)
+  const ent = entitlement(root, repoDigest, { explicit: licence })
+  if (!ent.ok) return { rc: EXIT.LICENCE, error: `VERDICT: NOT_MEASURED — licence: ${ent.reason}` }
+  let result
+  try { result = check(root, { base, failOn, engines, only, maker }) } catch (e) { return { rc: EXIT.USAGE, error: `fini-proof: ${e.message}` } }
+  result.entitlement = ent.mode === 'licence' ? { mode: 'licence', org: ent.org, seats: ent.seats, expiry: ent.expiry, licenceId: ent.licenceId } : { mode: 'trial', daysLeft: ent.daysLeft, trialEnds: ent.trialEnds }
+  const evidencePath = path.resolve(root, evidence || path.join('.fini-proof', 'runs', `${result.runId}.json`))
+  mkdirSync(path.dirname(evidencePath), { recursive: true })
+  writeFileSync(evidencePath, JSON.stringify(result, null, 2) + '\n')
+  if (sarifOut) writeFileSync(path.resolve(sarifOut), JSON.stringify(toSarif(result), null, 2) + '\n')
+  if (jsonOut) writeFileSync(path.resolve(jsonOut), JSON.stringify(result, null, 2) + '\n')
+  recordRun(result, ent)
+  return { rc: EXIT[result.verdict], result, ent, evidencePath }
+}
+
+function cmdCheck(o) {
+  const root = path.resolve(o.root || process.cwd())
+  const format = o.format || 'text'
+  if (!['text', 'json', 'sarif'].includes(format)) { err(`--format must be text|json|sarif`); return EXIT.USAGE }
+  if (o.uploadGzip && !o.upload) { err('--upload-gzip needs --upload'); return EXIT.USAGE }
+  const x = executeCheck({ root, base: o.base, failOn: o.failOn, engines: o.engine, only: o.only, licence: o.licence, evidence: o.evidence, sarifOut: o.sarifOut, jsonOut: o.jsonOut })
+  if (x.error) { err(x.error); return x.rc }
+  const { result, ent, evidencePath } = x
+  if (format === 'json') out(JSON.stringify(result, null, 2))
+  else if (format === 'sarif') out(JSON.stringify(toSarif(result), null, 2))
+  else {
+    out(toText(result, { evidencePath: path.relative(process.cwd(), evidencePath) }))
+    out(ent.mode === 'trial' ? `trial: ${ent.daysLeft} day(s) left (1 repository)` : `licensed to ${ent.org} (${ent.seats} seats, until ${ent.expiry})`)
+  }
+  if (!o.upload) return x.rc
+  // The upload never changes the verdict or the exit code: it reports on stderr and returns x.rc either way.
+  return uploadEvidence(result, { root, repository: o.repository, gzip: gzipWanted(o.uploadGzip) }).then((u) => {
+    if (u.ok) err(`uploaded to Fini Proof: run ${u.runId ?? '(id not returned)'}${u.status === 200 ? ' (already recorded)' : ''}`)
+    else err(`warning: upload failed — ${String(u.error).replace(/\.+$/, '')}. The verdict above stands; the evidence is at ${path.relative(process.cwd(), evidencePath)}.`)
+    return x.rc
+  })
+}
+
+function cmdProve(o) {
+  const root = path.resolve(o.root || process.cwd())
+  const engine = ENGINES.find((e) => e.id === o.engine[0])
+  if (!engine || !o.file) { err('usage: fini-proof prove --engine <id> --file <path> [--line <n>]'); return EXIT.USAGE }
+  const line = o.line ? Number(o.line) : null
+  const p = prove(root, engine.id, o.file, line)
+  if (p.status !== 'OK') { err(`NOT_MEASURED — ${p.reason}`); return EXIT.NOT_MEASURED }
+  const { hits, content } = p
+  const src = content.split('\n')
+  out(`proof · engine ${engine.id} ${engine.version} · ${o.file}${line ? `:${line}` : ''} · sha256 ${p.sha.slice(0, 16)}…`)
+  if (!hits.length) { out('REPRODUCED: no — the defect is not present at this location (fixed).'); return EXIT.PASS }
+  for (const f of hits) {
+    out(`\n  ${f.rule} (${f.severity}) at ${o.file}:${f.line}`)
+    for (let i = Math.max(1, f.line - 1); i <= Math.min(src.length, f.line + 3); i++) out(`   ${String(i).padStart(4)} ${i === f.line ? '>' : ' '} ${src[i - 1]}`)
+    out(`  ${f.message}`)
+  }
+  out(`\nREPRODUCED: yes — ${hits.length} finding(s). Negative controls for this engine: ${engine.negativeControls.map((c) => c.id).join(', ')}`)
+  return EXIT.FAIL
+}
+
+function cmdNegctl(o) {
+  const all = ENGINES.flatMap((e) => e.negativeControls.map((c) => ({ e, c })))
+  const pick = o.all ? all : all.filter(({ c }) => c.id === o._[1])
+  if (!pick.length) { err(`unknown control. Known: ${all.map(({ c }) => c.id).join(', ')}`); return EXIT.USAGE }
+  let failed = 0
+  let skipped = 0
+  const pre = new Map()
+  for (const { e, c } of pick) {
+    // An orchestrated engine whose binary is absent is SKIPPED (not caught, not missed); the count says so.
+    if (e.precondition && !pre.has(e.id)) pre.set(e.id, e.precondition())
+    const pc = pre.get(e.id) || {}
+    if (pc.notApplicable || pc.unmeasured) { skipped++; out(`SKIPPED ${c.id}  ${e.id} is ${pc.notApplicable ? 'not applicable' : 'NOT_MEASURED'}: ${pc.notApplicable || pc.unmeasured}`); continue }
+    let findings = []
+    let error = null
+    try { ({ findings } = scanWith(e, [{ rel: c.file, content: c.content }], { root: process.cwd(), baseline: {}, ...(c.ctx || {}) })) } catch (x) { error = x.message }
+    const caught = !error && findings.some((f) => f.rule === c.expect)
+    if (!caught) failed++
+    out(`${caught ? 'CAUGHT ' : 'MISSED '} ${c.id}  planted ${c.expect} in ${c.file}${error ? ` (engine error: ${error})` : ''}${o.all ? '' : `\n---\n${c.content}---\ngot: [${findings.map((f) => `${f.rule}@${f.line}`).join(', ')}]`}`)
+  }
+  const ran = pick.length - skipped
+  const skipNote = skipped ? `; ${skipped} skipped (engine not available here — skipped is not caught)` : ''
+  out(failed ? `${failed} negative control(s) MISSED — those checks cannot fail${skipNote}` : `${ran}/${ran} negative control(s) caught — each check is shown able to fail${skipNote}`)
+  if (!failed && ran === 0) return EXIT.NOT_MEASURED
+  return failed ? EXIT.FAIL : EXIT.PASS
+}
+
+function cmdState(o) {
+  const root = path.resolve(o.root || process.cwd())
+  const format = o.format || 'text'
+  if (!['text', 'json'].includes(format)) { err('--format must be text|json'); return EXIT.USAGE }
+  let doc
+  let evidencePath
+  let mode
+  if (o.against) {
+    // Read-time derivation (SSOT PART 5): nothing is run; the file must verify before a single state is derived from it.
+    evidencePath = path.resolve(o.against)
+    const r = readEvidenceFile(evidencePath)
+    if (!r.ok) { err(`NOT_MEASURED — ${o.against}: ${r.reason}`); return EXIT.NOT_MEASURED }
+    doc = r.doc
+    mode = 'against'
+  } else {
+    const x = executeCheck({ root, base: o.base, failOn: o.failOn, engines: o.engine, only: o.only, licence: o.licence, evidence: o.evidence })
+    if (x.error) { err(x.error); return x.rc }
+    doc = x.result
+    evidencePath = x.evidencePath
+    mode = 'run'
+  }
+  const rows = deriveStates(doc)
+  if (mode === 'against') applyStaleness(rows, doc, root)
+  const sd = stateDocument(doc, rows, { mode, evidencePath, root })
+  out(format === 'json' ? JSON.stringify(sd, null, 2) : stateText(sd))
+  return EXIT.PASS
+}
+
+function cmdEvidence(o) {
+  const file = o._[2]
+  if (o._[1] !== 'verify' || !file) { err('usage: fini-proof evidence verify <evidence.json>'); return EXIT.USAGE }
+  const r = readEvidenceFile(path.resolve(file))
+  if (!r.ok) { out(`INVALID ${file}: ${r.reason}${r.code ? ` (${r.code})` : ''}`); return r.code === 'UNREADABLE' || r.code === 'NOT_EVIDENCE' ? EXIT.USAGE : EXIT.FAIL }
+  const d = r.doc
+  const snap = snapshotOf(d)
+  const m = d.attestation?.maker
+  out(`VALID ${file}: ${d.schema} · run ${d.runId} · verdict ${d.verdict} · sha256 ${d.evidenceDigest.slice(0, 16)}…`)
+  out(`  tree ${snap.tree_hash || `(none: ${snap.reason})`} · maker ${m ? `${m.kind}:${m.id}${m.model ? ` (${m.model})` : ''} [${m.source}]` : '(not recorded in @1)'}`)
+  return EXIT.PASS
+}
+
+function cmdBaseline(o) {
+  const root = path.resolve(o.root || process.cwd())
+  const engine = ENGINES.find((e) => e.id === 'skip-ratchet')
+  const listed = listFiles(root)
+  if (listed.unmeasured) { err(`NOT_MEASURED — ${listed.unmeasured}`); return EXIT.NOT_MEASURED }
+  const files = listed.files.filter((f) => engine.appliesTo(f) && !f.startsWith('.fini-proof/')).map((rel) => ({ rel, content: readFileSync(path.join(root, rel), 'utf8') }))
+  const { findings } = scanWith(engine, files, { root, baseline: {} })
+  const now = {}
+  for (const f of findings) if (f.rule === 'SKIP_RATCHET') now[f.file] = (now[f.file] || 0) + 1
+  const prev = loadBaseline(root)['skip-ratchet'] || {}
+  const next = {}
+  const raised = []
+  for (const [f, n] of Object.entries(now)) {
+    if (!o.reset && f in prev && n > prev[f]) raised.push(`${f} ${prev[f]}→${n}`)
+    next[f] = o.reset || !(f in prev) ? n : Math.min(n, prev[f])
+  }
+  // migrations already applied at adoption (path → sha256): history, not a change under review
+  const mig = ENGINES.find((e) => e.id === 'migrations')
+  const applied = Object.fromEntries(listed.files.filter((f) => mig.appliesTo(f) && !f.startsWith('.fini-proof/')).sort()
+    .map((rel) => [rel, sha256(readFileSync(path.join(root, rel), 'utf8'))]))
+  const p = path.join(root, '.fini-proof', 'baseline.json')
+  mkdirSync(path.dirname(p), { recursive: true })
+  writeFileSync(p, JSON.stringify({ ...loadBaseline(root), 'skip-ratchet': next, migrations: { applied } }, null, 2) + '\n')
+  out(`wrote ${path.relative(process.cwd(), p)} — ${Object.values(next).reduce((a, b) => a + b, 0)} tolerated skip(s) in ${Object.keys(next).length} file(s); ${Object.keys(applied).length} applied migration(s) recorded`)
+  if (raised.length) out(`NOT raised (the ratchet only goes down; use --reset with a reviewed commit): ${raised.join(', ')}`)
+  return EXIT.PASS
+}
+
+function cmdUsage(o) {
+  const found = findLicenceKey(process.cwd(), o.licence)
+  const lic = found ? verifyLicence(found.key) : null
+  const s = exportUsage(o.export ? path.resolve(o.export) : null, lic?.ok ? lic.payload.seats : null)
+  out(`runs ${s.runs} · repos ${s.repos} · distinct authors ${s.distinctAuthors}${s.seats ? ` / ${s.seats} seats${s.overSeats ? ' (OVER)' : ''}` : ''} · rows ${readUsage().length}`)
+  for (const [m, v] of Object.entries(s.months)) out(`  ${m}: ${v.runs} run(s), ${v.repos} repo(s), ${v.distinctAuthors} author(s) ${JSON.stringify(v.verdicts)}`)
+  if (o.export) out(`exported ${o.export} (digest ${s.digest.slice(0, 16)}…)`)
+  return EXIT.PASS
+}
+
+function cmdLicence(o) {
+  const root = path.resolve(o.root || process.cwd())
+  const found = findLicenceKey(root, o.licence)
+  if (!found) { out('no licence key found — trial mode (1 repository, 14 days). Set FINI_PROOF_LICENCE or put the key in .fini-proof/licence.key'); return EXIT.PASS }
+  const v = verifyLicence(found.key)
+  if (!v.ok) { out(`licence from ${found.source}: REFUSED — ${v.reason}`); return EXIT.LICENCE }
+  out(`licence from ${found.source}: VALID — ${v.payload.org}, ${v.payload.seats} seats, until ${v.payload.expiry}`)
+  return EXIT.PASS
+}
+
+export function main(argv) {
+  let o
+  try { o = parse(argv) } catch (e) { err(e.message); return EXIT.USAGE }
+  const cmd = o._[0]
+  if (o.version || cmd === 'version') { out(TOOL_VERSION); return 0 }
+  if (!cmd || o.help || cmd === 'help') { out(HELP); return cmd ? 0 : EXIT.USAGE }
+  switch (cmd) {
+    case 'check': return cmdCheck(o)
+    case 'prove': return cmdProve(o)
+    case 'state': return cmdState(o)
+    case 'evidence': return cmdEvidence(o)
+    case 'negctl': return cmdNegctl(o)
+    case 'baseline': return cmdBaseline(o)
+    case 'usage': return cmdUsage(o)
+    case 'licence': case 'license': return cmdLicence(o)
+    case 'mcp': return serveMcp()
+    case 'hook': return runHook(o._[1])
+    default: err(`unknown command "${cmd}"\n\n${HELP}`); return EXIT.USAGE
+  }
+}
+

package/src/engines/fail-open.mjs

@@ -0,0 +1,133 @@
+// fini-proof engine: fail-open — CI steps and scripts that report success when they failed.
+// RAW_ENTRYPOINT_GUARD reuses the ported Finipe detector (./vendor/entrypoint-guard-core.mjs, provenance there).
+// The CI/shell/catch rules are NEW in fini-proof: in Finipe this class is enforced by several repo-specific gates
+// (exit-code discipline in scripts/ci/ci-local.mjs, NOT_MEASURED exit 3 convention, the $? checks in
+// scripts/ci/runner/*.sh); here it is generalised into one text rule set for any repo.
+import { rawGuards } from './vendor/entrypoint-guard-core.mjs'
+import { maskStringsAndComments } from './vendor/vacuous-spec-core.mjs'
+
+const CI_FILE_RE = /(^|\/)(\.github\/workflows\/[^/]+\.ya?ml|\.gitlab-ci\.yml|bitbucket-pipelines\.yml|Jenkinsfile|azure-pipelines\.yml|\.circleci\/config\.yml|Makefile)$/
+const SHELL_RE = /\.(sh|bash)$/
+const SCRIPT_DIR_RE = /(^|\/)(scripts?|ci|tools|bin|\.github)\//
+const JS_RE = /\.(mjs|cjs|js|ts)$/
+const PY_RE = /\.py$/
+
+function lineOf(src, idx) { return src.slice(0, idx).split('\n').length }
+
+function shellRules(content) {
+  const out = []
+  content.split('\n').forEach((l, i) => {
+    const code = l.replace(/(^|\s)#.*$/, '')
+    if (/\|\|\s*(true|:|exit\s+0)\b/.test(code)) out.push({ line: i + 1, rule: 'OR_TRUE', severity: 'high', message: 'a failing command is forced to success (`|| true` / `|| exit 0`) — the step stays green when it broke. FIX: let it fail, or handle the specific expected error and fail on everything else.' })
+    if (/^\s*set\s+\+e\b/.test(code)) out.push({ line: i + 1, rule: 'SET_PLUS_E', severity: 'medium', message: '`set +e` turns off fail-on-error for everything after it. FIX: keep `set -e`; capture an expected non-zero exit explicitly (`cmd || rc=$?`) and act on rc.' })
+    if (/^\s*continue-on-error\s*:\s*true\b/.test(code)) out.push({ line: i + 1, rule: 'CONTINUE_ON_ERROR', severity: 'medium', message: '`continue-on-error: true` — a red step does not fail the job. FIX: remove it, or scope it to a step whose failure is recorded elsewhere.' })
+    if (/^\s*allow_failure\s*:\s*true\b/.test(code)) out.push({ line: i + 1, rule: 'ALLOW_FAILURE', severity: 'medium', message: '`allow_failure: true` — the pipeline passes when this job fails. FIX: remove it or document the owner and expiry.' })
+  })
+  return out
+}
+
+function packageJsonRules(content) {
+  const out = []
+  let pkg
+  try { pkg = JSON.parse(content) } catch { return out }
+  for (const [name, cmd] of Object.entries(pkg.scripts || {})) {
+    if (/\|\|\s*(true|:|exit\s+0)\b/.test(cmd) || /--passWithNoTests\b/.test(cmd)) {
+      const idx = content.indexOf(JSON.stringify(name))
+      out.push({ line: idx >= 0 ? lineOf(content, idx) : 1, rule: 'OR_TRUE', severity: 'high', message: `npm script "${name}" cannot fail (\`|| true\` / \`--passWithNoTests\`). FIX: let the command's exit code through.` })
+    }
+  }
+  return out
+}
+
+/** Find `catch (e) { … }` / `.catch(() => …)` bodies in masked JS and flag the fail-open shapes. */
+function jsCatchRules(src) {
+  const out = []
+  const masked = maskStringsAndComments(src)
+  const re = /\bcatch\s*(\([^)]*\))?\s*\{/g
+  let m
+  while ((m = re.exec(masked)) !== null) {
+    const open = m.index + m[0].length - 1
+    let depth = 0, close = -1
+    for (let i = open; i < masked.length; i++) {
+      if (masked[i] === '{') depth++
+      else if (masked[i] === '}' && --depth === 0) { close = i; break }
+    }
+    if (close < 0) continue
+    const body = masked.slice(open + 1, close)
+    const line = lineOf(src, m.index)
+    if (/process\.exit\s*\(\s*0?\s*\)/.test(body)) out.push({ line, rule: 'CATCH_EXIT_ZERO', severity: 'high', message: 'the error handler exits 0 — the script reports success exactly when it failed. FIX: exit non-zero (or rethrow) in the catch.' })
+    else if (body.trim() === '') out.push({ line, rule: 'EMPTY_CATCH', severity: 'medium', message: 'an empty catch swallows the error — the script carries on as if it succeeded. FIX: rethrow, or log and exit non-zero.' })
+  }
+  const pc = /\.catch\s*\(\s*(?:\([^)]*\)|[A-Za-z_$][\w$]*)?\s*=>\s*(\{\s*\}|null|undefined|void 0|\(\s*\)|false|true)\s*\)/g
+  while ((m = pc.exec(masked)) !== null) out.push({ line: lineOf(src, m.index), rule: 'EMPTY_CATCH', severity: 'medium', message: '`.catch(() => {})` swallows the rejection — the script carries on as if it succeeded. FIX: let it reject, or log and exit non-zero.' })
+  return out
+}
+
+function jsGuardRules(src) {
+  const lines = src.split('\n')
+  return rawGuards(src)
+    // generalisation for customer repos: a guard realpath'd on both sides is correct, not fail-open
+    .filter((g) => !/realpath/i.test(lines.slice(Math.max(0, g.line - 3), g.line + 2).join('\n')))
+    .map((g) => ({ line: g.line, rule: 'RAW_ENTRYPOINT_GUARD', severity: 'medium', message: `entrypoint guard compares process.argv[1] with the module path without realpath on both sides (\`${g.text}\`). Run through a symlink (macOS /tmp, a symlinked checkout, npx bin links) main() never runs and the process exits 0 silently. FIX: compare realpathSync(process.argv[1]) with realpathSync(fileURLToPath(import.meta.url)).` }))
+}
+
+function pyRules(content) {
+  const out = []
+  const lines = content.split('\n')
+  lines.forEach((l, i) => {
+    if (!/^\s*except\b[^:]*:\s*(#.*)?$/.test(l)) return
+    const next = (lines.slice(i + 1).find((x) => x.trim() && !/^\s*#/.test(x)) || '').trim()
+    if (/^(pass|sys\.exit\(\s*0?\s*\)|exit\(\s*0?\s*\)|return\s+0)$/.test(next)) out.push({ line: i + 1, rule: 'EXCEPT_PASS', severity: next === 'pass' ? 'medium' : 'high', message: `the exception handler does \`${next}\` — the script reports success when it failed. FIX: re-raise, or exit non-zero.` })
+  })
+  return out
+}
+
+export default {
+  id: 'fail-open',
+  version: '0.1.0',
+  title: 'Fail-open CI steps and scripts',
+  provenance: 'finipe scripts/ci/check-entrypoint-guard.mjs rawGuards() @ 4ac53b367; CI/catch rules new',
+  appliesTo: (rel) => CI_FILE_RE.test(rel) || SHELL_RE.test(rel) || /(^|\/)package\.json$/.test(rel)
+    || ((JS_RE.test(rel) || PY_RE.test(rel)) && SCRIPT_DIR_RE.test(rel))
+    || /\.(mjs)$/.test(rel),
+  scanFile(rel, content) {
+    if (/(^|\/)package\.json$/.test(rel)) return packageJsonRules(content)
+    if (CI_FILE_RE.test(rel) || SHELL_RE.test(rel)) return shellRules(content)
+    if (PY_RE.test(rel)) return pyRules(content)
+    const out = jsGuardRules(content)
+    if (SCRIPT_DIR_RE.test(rel)) out.push(...jsCatchRules(content))
+    return out
+  },
+  rules: {
+    OR_TRUE: { severity: 'high', summary: 'a failing command is forced to success (`|| true`, `|| exit 0`, `--passWithNoTests`)', fix: 'let it fail, or handle the one expected error' },
+    SET_PLUS_E: { severity: 'medium', summary: '`set +e` turns off fail-on-error for the rest of the script', fix: 'keep set -e; capture an expected exit code explicitly' },
+    CONTINUE_ON_ERROR: { severity: 'medium', summary: '`continue-on-error: true` — a red step does not fail the job', fix: 'remove it' },
+    ALLOW_FAILURE: { severity: 'medium', summary: '`allow_failure: true` — the pipeline passes when this job fails', fix: 'remove it or document owner + expiry' },
+    CATCH_EXIT_ZERO: { severity: 'high', summary: 'the error handler exits 0 — success is reported exactly when it failed', fix: 'exit non-zero or rethrow' },
+    EMPTY_CATCH: { severity: 'medium', summary: 'an empty catch swallows the error', fix: 'rethrow, or log and exit non-zero' },
+    EXCEPT_PASS: { severity: 'medium', summary: 'a Python except does pass / exit(0)', fix: 're-raise or exit non-zero' },
+    RAW_ENTRYPOINT_GUARD: { severity: 'medium', summary: 'ESM entry-point guard without realpath — main() silently never runs through a symlink', fix: 'compare realpathSync on both sides' },
+  },
+  negativeControls: [
+    { id: 'fail-open/NC-1', file: '.github/workflows/ci.yml', expect: 'OR_TRUE', content: 'jobs:\n  t:\n    steps:\n      - run: npm test || true\n' },
+    { id: 'fail-open/NC-2', file: 'scripts/deploy.mjs', expect: 'CATCH_EXIT_ZERO', content: "try {\n  await deploy()\n} catch (e) {\n  console.error(e)\n  process.exit(0)\n}\n" },
+    { id: 'fail-open/NC-3', file: 'scripts/check.mjs', expect: 'RAW_ENTRYPOINT_GUARD', content: "import { fileURLToPath } from 'node:url'\nif (" + 'process.argv' + "[1] === fileURLToPath(import.meta.url)) main()\n" }, // concatenated: no raw guard in this file
+    { id: 'fail-open/NC-4', file: 'scripts/migrate.py', expect: 'EXCEPT_PASS', content: 'try:\n    migrate()\nexcept Exception:\n    sys.exit(0)\n' },
+    { id: 'fail-open/NC-5', file: 'package.json', expect: 'OR_TRUE', content: '{\n  "scripts": {\n    "test": "jest || true"\n  }\n}\n' },
+    { id: 'fail-open/NC-6', file: 'scripts/release.sh', expect: 'SET_PLUS_E', content: '#!/bin/sh\nset +e\nnpm test\nnpm publish\n' },
+    { id: 'fail-open/NC-7', file: '.github/workflows/test.yml', expect: 'CONTINUE_ON_ERROR', content: 'jobs:\n  t:\n    steps:\n      - run: npm test\n        continue-on-error: true\n' },
+    { id: 'fail-open/NC-8', file: '.gitlab-ci.yml', expect: 'ALLOW_FAILURE', content: 'test:\n  script: npm test\n  allow_failure: true\n' },
+    { id: 'fail-open/NC-9', file: 'scripts/sync.mjs', expect: 'EMPTY_CATCH', content: 'try {\n  await sync()\n} catch (e) {}\nconsole.log("synced")\n' },
+  ],
+  // Positive controls: `rule` names the rule each is the nearest clean look-alike for.
+  positiveControls: [
+    { id: 'fail-open/PC-1', rule: 'OR_TRUE', file: '.github/workflows/ci.yml', content: 'jobs:\n  t:\n    steps:\n      - run: npm test\n      - run: npm run lint  # never add || true here\n' },
+    { id: 'fail-open/PC-2', rule: 'RAW_ENTRYPOINT_GUARD', file: 'scripts/check.mjs', content: "import { realpathSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\nconst isMain = realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))\ntry { run() } catch (e) { console.error(e); process.exit(1) }\n" },
+    { id: 'fail-open/PC-3', rule: 'SET_PLUS_E', file: 'scripts/release.sh', content: '#!/bin/sh\nset -e\nrc=0\nnpm test || rc=$?\nif [ "$rc" -ne 0 ]; then echo "tests failed" >&2; exit "$rc"; fi\n' },
+    { id: 'fail-open/PC-4', rule: 'CONTINUE_ON_ERROR', file: '.github/workflows/test.yml', content: 'jobs:\n  t:\n    steps:\n      - run: npm test\n        continue-on-error: false\n' },
+    { id: 'fail-open/PC-5', rule: 'ALLOW_FAILURE', file: '.gitlab-ci.yml', content: 'test:\n  script: npm test\n  allow_failure: false\n' },
+    { id: 'fail-open/PC-6', rule: 'EMPTY_CATCH', file: 'scripts/sync.mjs', content: 'try {\n  await sync()\n} catch (e) {\n  console.error(e)\n  throw e\n}\n' },
+    { id: 'fail-open/PC-7', rule: 'CATCH_EXIT_ZERO', file: 'scripts/deploy.mjs', content: "try {\n  await deploy()\n} catch (e) {\n  console.error(e)\n  process.exit(1)\n}\n" },
+    { id: 'fail-open/PC-8', rule: 'EXCEPT_PASS', file: 'scripts/migrate.py', content: 'try:\n    migrate()\nexcept Exception:\n    log.exception("migrate failed")\n    sys.exit(1)\n' },
+  ],
+}

package/src/engines/gitleaks.mjs

@@ -0,0 +1,143 @@
+// fini-proof adapter: gitleaks — the first engine run through the ORCHESTRATION CONTRACT (SSOT PART 9, action 5).
+//
+// The contract is the ordinary engine module shape (id, version, appliesTo, rules, negativeControls,
+// positiveControls) plus three optional members the runner understands:
+//   precondition()        → { identity } | { notApplicable } | { unmeasured }   checked BEFORE the controls run
+//   scanRepo(files, ctx)  → findings for a set of { rel, content } at once (an external tool scans a directory,
+//                           not one string); used by the runner instead of scanFile for the controls AND the scan
+//   replaces: '<id>'      → when this engine is MEASURED in a run, the named built-in engine is NOT_APPLICABLE there
+//                           (it is the fallback, SSOT PART 2 "secrets: MERGE under orchestration")
+// Why new members instead of a separate adapter runner: the SSOT requires third-party engines to meet the SAME
+// standard as ours (controls first, NOT_MEASURED on a miss), so they go through the same check() loop, the same
+// evidence fields and the same readers. Nothing here forks the runner.
+//
+// What this adapter does:
+//   - uses a gitleaks binary that is ALREADY on PATH (or FINI_PROOF_GITLEAKS=<path>); it never downloads one.
+//     Absent → NOT_APPLICABLE with the reason, and the built-in `secrets` engine stays primary.
+//     FINI_PROOF_GITLEAKS=off → NOT_APPLICABLE (disabled). An explicit path that is not executable → NOT_MEASURED.
+//   - copies exactly the in-scope bytes the runner hashed into a temp directory and runs
+//     `gitleaks detect --no-git --source <copy> --report-format json --report-path <file> --redact --exit-code 0`,
+//     so the scanned bytes are the bytes in inputs.perFile (ignore globs, --base and --only apply unchanged).
+//   - plants its OWN negative controls (known-shaped secrets, one temp copy per control) before judging the repo;
+//     a missed control, a non-zero exit, a timeout or an unparseable report → NOT_MEASURED, never PASS.
+//   - never puts the secret (or gitleaks' redacted match) in a finding message.
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { accessSync, constants, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import secrets from './secrets.mjs'
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000
+
+function isExecutableFile(p) {
+  try { return statSync(p).isFile() && (accessSync(p, constants.X_OK), true) } catch { return false }
+}
+
+/** Where gitleaks is: { path, source } | { off } | { absent } | { error }. Pure over `env` (tests inject PATH). */
+export function locateGitleaks(env = process.env) {
+  const o = env.FINI_PROOF_GITLEAKS
+  if (o === 'off') return { off: true }
+  if (o) return isExecutableFile(o) ? { path: o, source: 'FINI_PROOF_GITLEAKS' } : { error: `FINI_PROOF_GITLEAKS=${o} is not an executable file` }
+  for (const dir of (env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    const p = path.join(dir, process.platform === 'win32' ? 'gitleaks.exe' : 'gitleaks')
+    if (isExecutableFile(p)) return { path: p, source: 'PATH' }
+  }
+  return { absent: true }
+}
+
+const timeoutMs = (env = process.env) => Number(env.FINI_PROOF_ADAPTER_TIMEOUT_MS) > 0 ? Number(env.FINI_PROOF_ADAPTER_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS
+const tail = (s) => String(s || '').trim().split('\n').slice(-3).join(' | ').slice(0, 300)
+export const ruleOf = (gitleaksRuleId) => `GITLEAKS_${String(gitleaksRuleId || 'UNKNOWN').toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`
+
+function precondition(env = process.env) {
+  const loc = locateGitleaks(env)
+  if (loc.off) return { notApplicable: 'disabled by FINI_PROOF_GITLEAKS=off; the built-in secrets engine is primary' }
+  if (loc.absent) return { notApplicable: 'gitleaks is not on PATH, so the built-in secrets engine is primary (Fini Proof never downloads a scanner; install gitleaks to orchestrate it)' }
+  if (loc.error) return { unmeasured: loc.error }
+  const v = spawnSync(loc.path, ['version'], { encoding: 'utf8', timeout: 30_000 })
+  if (v.error || v.status !== 0) return { unmeasured: `\`gitleaks version\` failed (${v.error ? v.error.code || v.error.message : `exit ${v.status}`}: ${tail(v.stderr)}) — a scanner that cannot identify itself is not run` }
+  let binSha
+  try { binSha = createHash('sha256').update(readFileSync(loc.path)).digest('hex') } catch (e) { return { unmeasured: `cannot read the gitleaks binary to fingerprint it: ${e.code || e.message}` } }
+  return { identity: { tool: 'gitleaks', path: loc.path, source: loc.source, version: tail(v.stdout) || 'unknown', sha256: binSha } }
+}
+
+/** Run gitleaks over an in-memory file set. Throws on any failure (the runner turns a throw into NOT_MEASURED). */
+function scanRepo(files, _ctx, env = process.env) {
+  const loc = locateGitleaks(env)
+  if (!loc.path) throw new Error(loc.error || 'gitleaks is not available')
+  const src = mkdtempSync(path.join(os.tmpdir(), 'fini-proof-gitleaks-src-'))
+  const out = mkdtempSync(path.join(os.tmpdir(), 'fini-proof-gitleaks-out-'))
+  try {
+    for (const { rel, content } of files) {
+      const dest = path.resolve(src, rel)
+      if (!dest.startsWith(src + path.sep)) throw new Error(`refusing to copy a path outside the scan copy: ${rel}`)
+      mkdirSync(path.dirname(dest), { recursive: true })
+      writeFileSync(dest, content)
+    }
+    const report = path.join(out, 'report.json')
+    const r = spawnSync(loc.path, ['detect', '--no-git', '--source', src, '--report-format', 'json', '--report-path', report, '--redact', '--exit-code', '0', '--no-banner'],
+      { encoding: 'utf8', timeout: timeoutMs(env), maxBuffer: 64 * 1024 * 1024 })
+    if (r.error) throw new Error(`gitleaks did not finish: ${r.error.code === 'ETIMEDOUT' ? `timed out after ${timeoutMs(env)} ms` : r.error.code || r.error.message}`)
+    if (r.status !== 0) throw new Error(`gitleaks exited ${r.status}${r.signal ? ` (${r.signal})` : ''}: ${tail(r.stderr)}`)
+    let items
+    try { items = JSON.parse(readFileSync(report, 'utf8')) } catch (e) { throw new Error(`gitleaks report is missing or not JSON (${e.code || e.message})`) }
+    if (!Array.isArray(items)) throw new Error('gitleaks report is not a JSON array')
+    return items.map((it) => {
+      const abs = path.resolve(src, String(it.File ?? ''))
+      const rel = path.relative(src, abs).split(path.sep).join('/')
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) throw new Error(`gitleaks reported a file outside the scan copy: ${it.File}`)
+      const line = Number.isInteger(it.StartLine) && it.StartLine > 0 ? it.StartLine : 1
+      const what = String(it.Description || it.RuleID || 'secret').replace(/[\x00-\x1f]/g, ' ').slice(0, 120)
+      return {
+        file: rel,
+        line,
+        rule: ruleOf(it.RuleID),
+        severity: 'high',
+        message: `${what} committed to the repository (gitleaks rule ${String(it.RuleID).slice(0, 80)}). Anyone with read access has it. FIX: rotate it now, then load it from the environment or a secret manager.`,
+      }
+    })
+  } finally {
+    rmSync(src, { recursive: true, force: true })
+    rmSync(out, { recursive: true, force: true })
+  }
+}
+
+// Planted material is assembled at runtime so this source file never contains a secret-shaped literal.
+// The AWS control reuses the built-in engine's planted key; the others are gitleaks-specific shapes (gitleaks'
+// github-pat rule has an entropy floor and its private-key rule needs a full BEGIN … END block).
+const awsNc = secrets.negativeControls.find((c) => c.id === 'secrets/NC-1')
+const pemBody = ['MIIEowIBAAKCAQEAu1SU1LfVLPHCozMxH2Mo4lgOEePzNm0tRgeLezV6ffAt0gun', 'VTLw7onLRnrq0/IzW7yWR7QkrmBL7jTKEn5u+qKhbwKfBstIs+bMY2Zkp18gnTxK']
+export const RULE_IDS = { aws: 'aws-access-token', github: 'github-pat', pem: 'private-key' }
+
+export default {
+  id: 'gitleaks',
+  version: '0.1.0',
+  title: 'Committed secrets (gitleaks, orchestrated)',
+  provenance: 'adapter over a gitleaks binary already on PATH (github.com/gitleaks/gitleaks, MIT); controls planted by Fini Proof',
+  external: true,
+  replaces: 'secrets',
+  appliesTo: secrets.appliesTo,
+  precondition,
+  scanRepo,
+  scanFile() { throw new Error('gitleaks is a whole-directory adapter; the runner calls scanRepo') },
+  rules: {
+    [ruleOf(RULE_IDS.aws)]: { severity: 'high', summary: 'AWS access key committed to the repository (gitleaks)', fix: 'rotate it now, then load it from the environment or a secret manager' },
+    [ruleOf(RULE_IDS.github)]: { severity: 'high', summary: 'GitHub personal access token committed to the repository (gitleaks)', fix: 'revoke it now, then load it from the environment or a secret manager' },
+    [ruleOf(RULE_IDS.pem)]: { severity: 'high', summary: 'private key committed to the repository (gitleaks)', fix: 'rotate the key pair now; keep private keys in a secret manager' },
+  },
+  negativeControls: [
+    { id: 'gitleaks/NC-1', file: 'nc/config.js', expect: ruleOf(RULE_IDS.aws), content: awsNc.content },
+    { id: 'gitleaks/NC-2', file: 'nc/gh.py', expect: ruleOf(RULE_IDS.github), content: `TOKEN = "${'ghp_' + 'R8mQ2vX7kL4pZ9wT' + 'c3NbY6hJ1fD5gS0aE2uK'}"\n` },
+    { id: 'gitleaks/NC-3', file: 'nc/deploy.key', expect: ruleOf(RULE_IDS.pem), content: `-----BEGIN ${'RSA PRIVATE'} KEY-----\n${pemBody.join('\n')}\n-----END ${'RSA PRIVATE'} KEY-----\n` },
+  ],
+  // Reused from the built-in engine: two general clean inputs, and per rule the nearest clean look-alike
+  // (a bare key prefix + env read, an env-read token, a PUBLIC key block).
+  positiveControls: [
+    ...secrets.positiveControls.filter((c) => ['secrets/PC-1', 'secrets/PC-2'].includes(c.id)).map(({ rule, ...c }) => ({ ...c, id: c.id.replace('secrets/', 'gitleaks/') })),
+    ...[['secrets/PC-4', RULE_IDS.aws], ['secrets/PC-6', RULE_IDS.github], ['secrets/PC-5', RULE_IDS.pem]].map(([id, gl]) => {
+      const c = secrets.positiveControls.find((x) => x.id === id)
+      return { ...c, id: id.replace('secrets/', 'gitleaks/'), rule: ruleOf(gl) }
+    }),
+  ],
+}