fini-proof 0.3.0

package/src/evidence.mjs

@@ -0,0 +1,130 @@
+// The evidence record: schema ids, digest, verification, attestation, and the @1/@2 read-compatibility layer.
+//
+// WHY THIS FILE EXISTS (reuse note): before evidence@2 the digest lived inline in runner.mjs finish() and nothing read
+// an evidence file back. `state --against`, `evidence verify` and the @1/@2 readers all need the SAME digest rule and
+// the SAME view of an old record, so it is one module here instead of a copy in each reader. runner.mjs finish() now
+// calls computeDigest() from here — the digest semantics are unchanged (sha256 of JSON.stringify of the record without
+// the post-digest fields), byte for byte, so the Developer workspace (backend fini-proof-evidence.ts) still verifies.
+//
+// evidence@2 (SSOT PART 10, action 1) adds to @1, and changes nothing that @1 had:
+//   snapshot       { tree_hash, commit, dirty, status, reason? }   git HEAD tree; NOT_MEASURED when not a git repo
+//   findings[]     .property_id = "<engine>/<rule>"
+//   engines[]      .nc_results[] = { id, expect, caught, ms }  (the negative-control runs that gate the engine)
+//                  .scope_files  = sorted paths the engine read (scan scope + schema/context files) — Proof.scope
+//   attestation    { maker: { kind: human|agent|unknown, id, model?, session?, source },
+//                    verifier: { tool, version, engine_digests, runner: { host_digest, ci } } }
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import os from 'node:os'
+
+export const EVIDENCE_SCHEMA = 'fini-proof/evidence@2'
+export const EVIDENCE_SCHEMAS = Object.freeze(['fini-proof/evidence@1', EVIDENCE_SCHEMA])
+/** Set AFTER the digest is computed (runner finish() → evidenceDigest, cli executeCheck() → entitlement). */
+export const POST_DIGEST_FIELDS = Object.freeze(['evidenceDigest', 'entitlement'])
+
+const sha256 = (s) => createHash('sha256').update(s).digest('hex')
+
+/** The evidence digest: sha256 of the record without the post-digest fields, keys in their written order. */
+export function computeDigest(doc) {
+  const rest = {}
+  for (const [k, v] of Object.entries(doc)) if (!POST_DIGEST_FIELDS.includes(k)) rest[k] = v
+  return sha256(JSON.stringify(rest))
+}
+
+/** Verify a parsed record: known schema, digest reproduces, maker is not the verifier. Returns { ok, reason?, code? }. */
+export function verifyEvidence(doc) {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return { ok: false, code: 'NOT_EVIDENCE', reason: 'not a JSON object' }
+  if (!EVIDENCE_SCHEMAS.includes(doc.schema)) return { ok: false, code: 'SCHEMA_UNKNOWN', reason: `unknown schema ${JSON.stringify(doc.schema)} (accepted: ${EVIDENCE_SCHEMAS.join(', ')})` }
+  if (typeof doc.evidenceDigest !== 'string' || !/^[0-9a-f]{64}$/.test(doc.evidenceDigest)) return { ok: false, code: 'DIGEST_MISSING', reason: 'evidenceDigest is missing or not a sha256 hex string' }
+  if (computeDigest(doc) !== doc.evidenceDigest) return { ok: false, code: 'DIGEST_MISMATCH', reason: 'evidenceDigest does not match the record: it was edited after the check ran, or was not written by fini-proof' }
+  if (makerIsVerifier(doc.attestation)) return { ok: false, code: 'MAKER_IS_VERIFIER', reason: 'the attested maker is the verifier itself — a verifier cannot attest its own change' }
+  return { ok: true, schema: doc.schema }
+}
+
+/** Read + parse + verify an evidence file. Returns { ok, doc?, reason?, code? }; never throws. */
+export function readEvidenceFile(file) {
+  let doc
+  try { doc = JSON.parse(readFileSync(file, 'utf8')) } catch (e) { return { ok: false, code: 'UNREADABLE', reason: `cannot read ${file}: ${e.code || e.message}` } }
+  const v = verifyEvidence(doc)
+  return v.ok ? { ok: true, doc } : { ...v, doc }
+}
+
+// ── @1/@2 read compatibility: every reader goes through these, never through the raw @2 field names ──
+
+export const propertyId = (f) => f.property_id || `${f.engine}/${f.rule}`
+
+/** Negative-control results of one engine record; @1 records derive them from `controls` (no timing then). */
+export function ncResults(er) {
+  if (Array.isArray(er.nc_results)) return er.nc_results
+  return (er.controls || []).filter((c) => c.kind === 'negative').map((c) => ({ id: c.id, expect: c.expect, caught: c.ok === true, ms: null }))
+}
+
+/** The files a proof of this engine covers. @1 has no per-engine scope → every hashed input (conservative). */
+export function scopeFiles(er, doc) {
+  if (Array.isArray(er.scope_files)) return { files: er.scope_files, source: 'engine' }
+  return { files: Object.keys(doc.inputs?.perFile || {}).sort(), source: 'all-inputs' }
+}
+
+export function snapshotOf(doc) {
+  if (doc.snapshot) return doc.snapshot
+  return { tree_hash: null, commit: doc.repo?.commit ?? null, dirty: doc.repo?.dirty ?? null, status: 'NOT_MEASURED', reason: `${doc.schema} records no tree hash` }
+}
+
+// ── attestation (SSOT PART 8: maker ≠ verifier) ──
+
+const MAKER_KINDS = new Set(['human', 'agent'])
+const VERIFIER_TOOL = 'fini-proof'
+const clean = (v, max = 200) => (typeof v === 'string' && v.trim() ? v.replace(/[\x00-\x1f\x7f]/g, '').trim().slice(0, max) : undefined)
+
+/**
+ * Who made the change. Precedence: an explicit maker from the caller that KNOWS it (the Claude Code hook, the MCP
+ * client's own name) → FINI_PROOF_MAKER_KIND / _ID / _MODEL / _SESSION → the git author of HEAD. The kind is never
+ * guessed: a git author may be a person or an agent using that person's identity, so it is recorded as 'unknown'.
+ */
+export function makerFrom({ explicit = null, env = process.env, gitAuthor = null } = {}) {
+  const envKind = clean(env.FINI_PROOF_MAKER_KIND)
+  const fromEnv = {
+    kind: envKind && MAKER_KINDS.has(envKind) ? envKind : undefined,
+    id: clean(env.FINI_PROOF_MAKER_ID),
+    model: clean(env.FINI_PROOF_MAKER_MODEL),
+    session: clean(env.FINI_PROOF_MAKER_SESSION),
+  }
+  const pick = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined))
+  if (explicit && clean(explicit.id)) {
+    const kind = MAKER_KINDS.has(explicit.kind) ? explicit.kind : 'unknown'
+    return pick({ kind, id: clean(explicit.id), model: clean(explicit.model) ?? fromEnv.model, session: clean(explicit.session) ?? fromEnv.session, source: clean(explicit.source) || 'caller' })
+  }
+  if (fromEnv.id || envKind) return pick({ kind: fromEnv.kind || 'unknown', id: fromEnv.id || 'unknown', model: fromEnv.model, session: fromEnv.session, source: 'env' })
+  if (clean(gitAuthor, 320)) return { kind: 'unknown', id: clean(gitAuthor, 320), source: 'git-author' }
+  return { kind: 'unknown', id: 'unknown', source: 'none' }
+}
+
+/** Which CI system and job ran the verifier (null on a workstation). */
+export function ciIdentity(env = process.env) {
+  if (env.GITHUB_ACTIONS === 'true') return { system: 'github-actions', job: [env.GITHUB_REPOSITORY, env.GITHUB_RUN_ID, env.GITHUB_RUN_ATTEMPT].filter(Boolean).join('/') || null }
+  if (env.GITLAB_CI) return { system: 'gitlab', job: env.CI_JOB_ID || null }
+  if (env.BITBUCKET_BUILD_NUMBER) return { system: 'bitbucket', job: [env.BITBUCKET_REPO_FULL_NAME, env.BITBUCKET_BUILD_NUMBER].filter(Boolean).join('/') }
+  if (env.JENKINS_URL) return { system: 'jenkins', job: env.BUILD_TAG || null }
+  if (env.CI) return { system: 'ci', job: null }
+  return null
+}
+
+/**
+ * The verifier: this tool, its version, the digest of every engine that ran, and the runner. The host name is
+ * recorded as a digest only (enough to tell two runners apart; a workstation name is not sent anywhere).
+ */
+export function verifierFrom({ version, engines, env = process.env }) {
+  return {
+    tool: VERIFIER_TOOL,
+    version,
+    engine_digests: Object.fromEntries(engines.map((e) => [e.id, e.sha256])),
+    runner: { host_digest: sha256(os.hostname()).slice(0, 16), ci: ciIdentity(env) },
+  }
+}
+
+/** A run whose maker identity equals its verifier identity is refused (backend 422 MAKER_IS_VERIFIER). */
+export function makerIsVerifier(att) {
+  if (!att || !att.maker || !att.verifier) return false
+  const id = String(att.maker.id || '').toLowerCase()
+  return id === String(att.verifier.tool || VERIFIER_TOOL).toLowerCase() || id.startsWith(`${VERIFIER_TOOL}/`) || id.startsWith(`${VERIFIER_TOOL}@`)
+}

package/src/files.mjs

@@ -0,0 +1,89 @@
+// Repository file listing, scope (--base) and ignore config. Fails closed: an unresolvable base is reported,
+// never silently widened or narrowed (same rule as finipe check-vacuous-spec.mjs resolveBase(), V2 cert note).
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+export function git(root, args) {
+  const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 })
+  return { ok: r.status === 0, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() }
+}
+
+export function isGitRepo(root) { return git(root, ['rev-parse', '--is-inside-work-tree']).out === 'true' }
+
+export function repoInfo(root) {
+  if (!isGitRepo(root)) return { git: false, commit: null, rootCommit: null, dirty: null }
+  const commit = git(root, ['rev-parse', 'HEAD'])
+  const rootCommit = git(root, ['rev-list', '--max-parents=0', 'HEAD'])
+  const status = git(root, ['status', '--porcelain'])
+  return {
+    git: true,
+    commit: commit.ok ? commit.out : null,
+    rootCommit: rootCommit.ok ? rootCommit.out.split('\n').sort()[0] : null,
+    dirty: status.ok ? status.out.length > 0 : null,
+    author: git(root, ['log', '-1', '--format=%ae']).out || null,
+  }
+}
+
+function walk(root) {
+  const acc = []
+  const rec = (d) => {
+    for (const e of readdirSync(path.join(root, d), { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name === '.git' || e.name === '.fini-proof') continue
+      const rel = d ? `${d}/${e.name}` : e.name
+      if (e.isDirectory()) rec(rel)
+      else if (e.isFile()) acc.push(rel)
+    }
+  }
+  rec('')
+  return acc
+}
+
+/** All files in scope. Returns { files } or { unmeasured: reason }. */
+export function listFiles(root, { base } = {}) {
+  if (!isGitRepo(root)) {
+    if (base) return { unmeasured: `--base ${base} given but ${root} is not a git repository` }
+    return { files: walk(root).sort(), mode: 'full-walk' }
+  }
+  const all = git(root, ['ls-files', '-co', '--exclude-standard', '-z'])
+  if (!all.ok) return { unmeasured: `git ls-files failed: ${all.err}` }
+  let files = all.out.split('\0').filter(Boolean).filter((f) => !f.split('/').includes('node_modules'))
+  if (!base) return { files: [...new Set(files)].sort(), mode: 'full' }
+  const b = git(root, ['rev-parse', '--verify', '--quiet', `${base}^{commit}`])
+  if (!b.ok) return { unmeasured: `base ref "${base}" does not resolve to a commit (fetch it: git fetch origin ${base.replace(/^origin\//, '')}) — a guessed base would silently change what is checked` }
+  const mb = git(root, ['merge-base', b.out, 'HEAD'])
+  if (!mb.ok) return { unmeasured: `no merge-base between ${base} and HEAD (shallow clone? use fetch-depth: 0)` }
+  const changed = new Set([
+    ...git(root, ['diff', '--name-only', '--diff-filter=d', `${mb.out}..HEAD`]).out.split('\n'),
+    ...git(root, ['diff', '--name-only', '--diff-filter=d']).out.split('\n'),
+    ...git(root, ['diff', '--name-only', '--diff-filter=d', '--cached']).out.split('\n'),
+    ...git(root, ['ls-files', '--others', '--exclude-standard']).out.split('\n'),
+  ].filter(Boolean))
+  files = files.filter((f) => changed.has(f))
+  return { files: [...new Set(files)].sort(), mode: 'diff', baseCommit: b.out, mergeBase: mb.out }
+}
+
+export function globToRegExp(glob) {
+  let re = ''
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === '*' && glob[i + 1] === '*') { re += '.*'; i++; if (glob[i + 1] === '/') i++ }
+    else if (c === '*') re += '[^/]*'
+    else if (c === '?') re += '[^/]'
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${re}$`)
+}
+
+export function loadConfig(root) {
+  const p = path.join(root, '.fini-proof.json')
+  if (!existsSync(p)) return { ignore: [], source: null, raw: {} }
+  const cfg = JSON.parse(readFileSync(p, 'utf8'))
+  return { ignore: Array.isArray(cfg.ignore) ? cfg.ignore : [], failOn: cfg.failOn, source: '.fini-proof.json', raw: cfg }
+}
+
+export function loadBaseline(root) {
+  const p = path.join(root, '.fini-proof', 'baseline.json')
+  if (!existsSync(p)) return {}
+  return JSON.parse(readFileSync(p, 'utf8'))
+}

package/src/hooks.mjs

@@ -0,0 +1,118 @@
+// `fini-proof hook claude` — Claude Code hook handler. Claude Code pipes one JSON object on stdin
+// ({ session_id, cwd, hook_event_name, … }) and reads the exit code: 2 = BLOCK, and stderr is fed back to Claude.
+//
+//   SessionStart          record HEAD, so Stop can check exactly what this session changed (commits included)
+//   Stop / SubagentStop   run the full licensed check on the session's changes; FAIL or NOT_MEASURED → exit 2
+//                         with the findings, so the agent cannot report "done" on unverified work
+//   PostToolUse           (Edit / Write / MultiEdit) check only the file just written; blocking finding → exit 2,
+//                         so the agent sees the problem immediately
+//
+// Loop guard: a Stop is blocked at most FINI_PROOF_HOOK_MAX_BLOCKS times (default 5) per session; after that the
+// stop is allowed but a systemMessage tells the USER the work is still unverified — never a silent pass.
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { homeDir } from './licence.mjs'
+import { sha256 } from './runner.mjs'
+
+const git = (cwd, args) => {
+  const r = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' })
+  return r.status === 0 ? r.stdout.trim() : null
+}
+
+async function readStdin(input) {
+  const chunks = []
+  for await (const c of input) chunks.push(c)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+function stateFile(sessionId) {
+  return path.join(homeDir(), 'hooks', `${sha256(String(sessionId || 'no-session')).slice(0, 24)}.json`)
+}
+function loadState(sessionId) {
+  const f = stateFile(sessionId)
+  if (!existsSync(f)) return {}
+  try { return JSON.parse(readFileSync(f, 'utf8')) } catch { return {} }
+}
+function saveState(sessionId, st) {
+  const f = stateFile(sessionId)
+  mkdirSync(path.dirname(f), { recursive: true })
+  writeFileSync(f, JSON.stringify(st))
+}
+
+/** Which changes a Stop verifies: env override → HEAD at session start → the remote default branch → uncommitted. */
+export function stopBase(root, state, env = process.env) {
+  if (env.FINI_PROOF_HOOK_BASE) return env.FINI_PROOF_HOOK_BASE
+  if (state.startHead && git(root, ['cat-file', '-e', `${state.startHead}^{commit}`]) !== null) return state.startHead
+  for (const ref of ['origin/HEAD', 'origin/main', 'origin/master']) if (git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])) return ref
+  return 'HEAD'
+}
+
+function reasonText(result, heading, max = 20) {
+  const L = [heading]
+  const blocking = result.findings.filter((f) => f.blocking)
+  for (const f of blocking.slice(0, max)) L.push(`- ${f.file}:${f.line} ${f.rule} [${f.engine}] ${f.message}\n  proof: ${f.proof}`)
+  if (blocking.length > max) L.push(`… and ${blocking.length - max} more (see the evidence file).`)
+  if (result.verdict === 'NOT_MEASURED') L.push(`- not measured: ${result.reason}`)
+  L.push('Fini Proof is an independent verifier: fix the code. Do not weaken tests, add ignore globs to .fini-proof.json, or raise the baseline to make it pass.')
+  return L.join('\n')
+}
+
+/** Returns { code, stderr, stdout } — pure enough to test without spawning. */
+export async function handleClaudeHook(payload, { env = process.env, executeCheck } = {}) {
+  const event = payload.hook_event_name
+  const cwd = payload.cwd || process.cwd()
+  const root = git(cwd, ['rev-parse', '--show-toplevel']) || cwd
+  const session = payload.session_id
+  const state = loadState(session)
+  const blockOn = (env.FINI_PROOF_HOOK_BLOCK_ON || 'FAIL,NOT_MEASURED').split(',').map((s) => s.trim())
+  // evidence@2 attestation: this hook KNOWS the maker is the Claude Code agent of this session (SSOT PART 8).
+  const maker = { kind: 'agent', id: 'claude-code', session: session ? String(session) : undefined, model: env.FINI_PROOF_MAKER_MODEL, source: 'claude-code-hook' }
+
+  if (event === 'SessionStart') {
+    const head = git(root, ['rev-parse', 'HEAD'])
+    if (head && !state.startHead) saveState(session, { ...state, startHead: head, blocks: 0 })
+    return { code: 0 }
+  }
+
+  if (event === 'PostToolUse') {
+    const file = payload.tool_input?.file_path || payload.tool_input?.notebook_path
+    if (!file) return { code: 0 }
+    // realpath both sides: macOS /var → /private/var and symlinked checkouts must not turn a repo file into "outside"
+    const real = (p) => { try { return realpathSync(p) } catch { return p } }
+    const rel = path.relative(real(root), real(path.resolve(cwd, file))).split(path.sep).join('/')
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return { code: 0 }
+    const x = executeCheck({ root, only: [rel], maker })
+    if (x.error || x.result.verdict !== 'FAIL') return { code: 0 } // per-edit feedback only; Stop is the gate
+    return { code: 2, stderr: reasonText(x.result, `Fini Proof: the edit to ${rel} introduced ${x.result.summary.blocking} blocking finding(s). Fix them now:`) }
+  }
+
+  if (event === 'Stop' || event === 'SubagentStop') {
+    const base = git(root, ['rev-parse', '--is-inside-work-tree']) === 'true' ? stopBase(root, state, env) : undefined
+    const x = executeCheck({ root, base, maker })
+    const verdict = x.error ? 'NOT_MEASURED' : x.result.verdict
+    if (!blockOn.includes(verdict)) { saveState(session, { ...state, blocks: 0 }); return { code: 0 } }
+    const max = Number(env.FINI_PROOF_HOOK_MAX_BLOCKS || 5)
+    const blocks = (state.blocks || 0) + 1
+    saveState(session, { ...state, blocks })
+    const why = x.error
+      ? `Fini Proof: VERDICT NOT_MEASURED — ${x.error.replace(/^VERDICT: NOT_MEASURED — /, '')}. The work is not verified.`
+      : reasonText(x.result, `Fini Proof: VERDICT ${verdict} on the changes since ${base || 'the start'} — ${x.result.summary.blocking} blocking finding(s). The task is NOT done.`)
+    if (blocks > max) {
+      return { code: 0, stdout: JSON.stringify({ systemMessage: `Fini Proof: verdict is still ${verdict} after ${max} attempts; the agent was allowed to stop, but this work is NOT verified. Evidence: ${x.evidencePath || 'none'}` }) }
+    }
+    return { code: 2, stderr: why }
+  }
+  return { code: 0 }
+}
+
+export async function runHook(kind, { input = process.stdin, env = process.env } = {}) {
+  if (kind !== 'claude') { process.stderr.write('usage: fini-proof hook claude   (reads the Claude Code hook JSON on stdin)\n'); return 2 }
+  let payload
+  try { payload = JSON.parse(await readStdin(input)) } catch (e) { process.stderr.write(`fini-proof hook: stdin is not the Claude Code hook JSON (${e.message})\n`); return 1 }
+  const { executeCheck } = await import('./cli.mjs')
+  const r = await handleClaudeHook(payload, { env, executeCheck })
+  if (r.stdout) process.stdout.write(r.stdout + '\n')
+  if (r.stderr) process.stderr.write(r.stderr + '\n')
+  return r.code
+}

package/src/licence.mjs

@@ -0,0 +1,85 @@
+// Offline licence: Ed25519-signed JSON { org, seats, expiry, … }. No network call, ever.
+// Without a licence the tool runs in TRIAL mode: 1 repository (identified by its root-commit digest) for 14 days,
+// recorded in $FINI_PROOF_HOME/trial.json. Every failure here is a refusal with a reason — never a silent pass.
+import { createPublicKey, verify, sign, createPrivateKey } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+// Finipe Ventures vendor public key (Ed25519, SPKI PEM). The private half never enters this repository.
+export const VENDOR_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAKeoiHBV27P3aOOXlia2/7AmbfffS96NWVHeTRCvJr8E=
+-----END PUBLIC KEY-----
+`
+export const TRIAL_DAYS = 14
+export const TRIAL_REPOS = 1
+const DAY = 86_400_000
+
+export const homeDir = () => process.env.FINI_PROOF_HOME || path.join(os.homedir(), '.fini-proof')
+
+/** Stable byte form that is signed: keys sorted, no whitespace. */
+export function canonical(obj) {
+  if (Array.isArray(obj)) return `[${obj.map(canonical).join(',')}]`
+  if (obj && typeof obj === 'object') return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(',')}}`
+  return JSON.stringify(obj)
+}
+
+export function issueLicence(payload, privateKeyPem) {
+  const p = { product: 'fini-proof', ...payload }
+  for (const k of ['org', 'seats', 'expiry']) if (p[k] === undefined) throw new Error(`licence payload needs ${k}`)
+  const signature = sign(null, Buffer.from(canonical(p)), createPrivateKey(privateKeyPem)).toString('base64')
+  return Buffer.from(JSON.stringify({ payload: p, signature })).toString('base64url')
+}
+
+/** Returns { ok, payload } or { ok:false, reason }. `now` is injectable for tests only (no env override). */
+export function verifyLicence(key, { publicKeyPem = VENDOR_PUBLIC_KEY_PEM, now = Date.now() } = {}) {
+  let doc
+  try { doc = JSON.parse(Buffer.from(String(key).trim(), 'base64url').toString('utf8')) } catch { return { ok: false, reason: 'licence key is not readable (corrupted or truncated)' } }
+  if (!doc?.payload || !doc?.signature) return { ok: false, reason: 'licence key has no payload/signature' }
+  let good = false
+  try { good = verify(null, Buffer.from(canonical(doc.payload)), createPublicKey(publicKeyPem), Buffer.from(doc.signature, 'base64')) } catch { good = false }
+  if (!good) return { ok: false, reason: 'licence signature is invalid (not issued by Finipe, or edited after issue)' }
+  const p = doc.payload
+  if (p.product !== 'fini-proof') return { ok: false, reason: `licence is for product "${p.product}"` }
+  const exp = Date.parse(p.expiry)
+  if (!Number.isFinite(exp)) return { ok: false, reason: 'licence expiry is not a date' }
+  if (now > exp) return { ok: false, reason: `licence for ${p.org} expired on ${p.expiry}` }
+  if (!Number.isInteger(p.seats) || p.seats < 1) return { ok: false, reason: 'licence seats must be a positive integer' }
+  return { ok: true, payload: p }
+}
+
+export function findLicenceKey(root, explicit) {
+  if (explicit) return { key: existsSync(explicit) ? readFileSync(explicit, 'utf8') : explicit, source: '--licence' }
+  const env = process.env.FINI_PROOF_LICENCE || process.env.FINI_PROOF_LICENSE
+  if (env) return { key: existsSync(env) ? readFileSync(env, 'utf8') : env, source: 'FINI_PROOF_LICENCE' }
+  for (const p of [path.join(root, '.fini-proof', 'licence.key'), path.join(homeDir(), 'licence.key')]) {
+    if (existsSync(p)) return { key: readFileSync(p, 'utf8'), source: p }
+  }
+  return null
+}
+
+/** Resolve the entitlement for this run: a verified licence, an active trial, or a refusal. */
+export function entitlement(root, repoDigest, { explicit, now = Date.now(), publicKeyPem } = {}) {
+  const found = findLicenceKey(root, explicit)
+  if (found) {
+    const v = verifyLicence(found.key, { now, publicKeyPem })
+    if (!v.ok) return { ok: false, mode: 'licence', reason: v.reason }
+    return { ok: true, mode: 'licence', org: v.payload.org, seats: v.payload.seats, expiry: v.payload.expiry, licenceId: v.payload.licenceId || null }
+  }
+  const dir = homeDir()
+  const file = path.join(dir, 'trial.json')
+  let trial = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null
+  if (!trial) {
+    trial = { startedAt: new Date(now).toISOString(), repos: [repoDigest] }
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(file, JSON.stringify(trial, null, 2))
+  }
+  const ends = Date.parse(trial.startedAt) + TRIAL_DAYS * DAY
+  if (now > ends) return { ok: false, mode: 'trial', reason: `the ${TRIAL_DAYS}-day trial ended on ${new Date(ends).toISOString().slice(0, 10)} — a licence key is needed (contact Finipe)` }
+  if (!trial.repos.includes(repoDigest)) {
+    if (trial.repos.length >= TRIAL_REPOS) return { ok: false, mode: 'trial', reason: `the trial covers ${TRIAL_REPOS} repository and is already bound to another one — a licence key is needed for more` }
+    trial.repos.push(repoDigest)
+    writeFileSync(file, JSON.stringify(trial, null, 2))
+  }
+  return { ok: true, mode: 'trial', org: null, daysLeft: Math.max(0, Math.ceil((ends - now) / DAY)), trialEnds: new Date(ends).toISOString() }
+}

package/src/mcp.mjs

@@ -0,0 +1,230 @@
+// `fini-proof mcp` — a Model Context Protocol server on stdio, so an AI coding agent (Claude Code, Codex, Cursor,
+// any MCP client) can ask an INDEPENDENT verifier whether its work is done. The agent cannot change the verdict:
+// the tools run the same licensed check path as the CLI (executeCheck), write the same evidence file, and a check
+// that cannot run is NOT_MEASURED, never PASS.
+//
+// Protocol: JSON-RPC 2.0, one message per line on stdin/stdout (MCP stdio transport). Implemented directly — no SDK,
+// no dependencies. Methods: initialize, notifications/initialized, ping, tools/list, tools/call.
+// Nothing but protocol messages is ever written to stdout; diagnostics go to stderr.
+import { realpathSync } from 'node:fs'
+import path from 'node:path'
+import { createInterface } from 'node:readline'
+import { ENGINES, TOOL_VERSION, prove, ruleCatalogue } from './runner.mjs'
+import { toText } from './report.mjs'
+
+export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']
+const ENGINE_IDS = ENGINES.map((e) => e.id)
+
+const TOOLS = [
+  {
+    name: 'check',
+    title: 'Verify the repository (independent of the agent)',
+    description: 'Run Fini Proof on the repository and return the verdict: PASS, FAIL or NOT_MEASURED. Every finding has file:line, rule, a proof command and a negative-control id. Call this BEFORE telling the user a task is done; if the verdict is FAIL, fix the findings (do not weaken tests, ignore globs or baselines) and call it again. Use `base` (e.g. "origin/main" or "HEAD") to check only what changed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Repository directory (default: the server working directory). Must be inside it.' },
+        base: { type: 'string', description: 'Git ref: check only files changed against it. "HEAD" = uncommitted changes only.' },
+        failOn: { type: 'string', enum: ['high', 'medium', 'low', 'none'], description: 'Lowest severity that fails the verdict (default high).' },
+        engines: { type: 'array', items: { type: 'string', enum: ENGINE_IDS }, description: 'Only these engines (default: all).' },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        verdict: { type: 'string', enum: ['PASS', 'FAIL', 'NOT_MEASURED'] },
+        exitCode: { type: 'integer' },
+        reason: { type: 'string' },
+        blocking: { type: 'integer' },
+        findings: { type: 'array', items: { type: 'object' } },
+        engines: { type: 'array', items: { type: 'object' } },
+        evidencePath: { type: 'string' },
+        evidenceDigest: { type: 'string' },
+      },
+      required: ['verdict', 'exitCode'],
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: 'explain_finding',
+    title: 'Explain a finding and re-run its proof',
+    description: 'Explain a rule (what it catches, why it matters, how to fix it), show the planted defect its negative control catches, and — when file (and line) are given — re-run the proof on that file now: REPRODUCED yes/no.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        engine: { type: 'string', enum: ENGINE_IDS },
+        rule: { type: 'string', description: 'Rule id, e.g. NO_ASSERTION or TENANT_FILTER_MISSING.' },
+        file: { type: 'string', description: 'Repository-relative file to re-check.' },
+        line: { type: 'integer', minimum: 1 },
+        path: { type: 'string', description: 'Repository directory (default: the server working directory).' },
+      },
+      required: ['engine'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'list_rules',
+    title: 'List engines and rules',
+    description: 'List every engine, its rules (severity, what it catches, fix), where it came from, and its negative controls.',
+    inputSchema: { type: 'object', properties: { engine: { type: 'string', enum: ENGINE_IDS } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+]
+
+class ToolError extends Error {}
+
+/** A tool may only look inside the server's working directory (or FINI_PROOF_MCP_ROOTS, ':'-separated). */
+function resolveRoot(p, cwd) {
+  const allowed = [cwd, ...(process.env.FINI_PROOF_MCP_ROOTS || '').split(':').filter(Boolean)].map((r) => { try { return realpathSync(r) } catch { return path.resolve(r) } })
+  let target
+  try { target = realpathSync(path.resolve(cwd, p || '.')) } catch { throw new ToolError(`path does not exist: ${p}`) }
+  if (!allowed.some((r) => target === r || target.startsWith(r + path.sep))) throw new ToolError(`path ${p} is outside the allowed roots (${allowed.join(', ')}); set FINI_PROOF_MCP_ROOTS to widen`)
+  return target
+}
+
+function toolCheck(args, { cwd, executeCheck, maker }) {
+  const root = resolveRoot(args.path, cwd)
+  if (args.failOn && !['high', 'medium', 'low', 'none'].includes(args.failOn)) throw new ToolError('failOn must be high|medium|low|none')
+  const x = executeCheck({ root, base: args.base, failOn: args.failOn, engines: args.engines || [], maker })
+  if (x.error) {
+    const verdict = 'NOT_MEASURED' // a licence refusal or a usage error: nothing was verified
+    return { isError: true, text: `VERDICT: ${verdict} — ${x.error.replace(/^VERDICT: NOT_MEASURED — /, '')}\nThe work is NOT verified.`, structured: { verdict, exitCode: x.rc, reason: x.error } }
+  }
+  const r = x.result
+  const blocking = r.findings.filter((f) => f.blocking)
+  const head = r.verdict === 'PASS'
+    ? 'VERDICT: PASS — every measured check passed. Evidence recorded.'
+    : r.verdict === 'FAIL'
+      ? `VERDICT: FAIL — ${blocking.length} blocking finding(s). The task is NOT done: fix each finding at its file:line, then call check again. Do not weaken tests, add ignore globs or raise baselines to make this pass.`
+      : `VERDICT: NOT_MEASURED — ${r.reason}. The work is NOT verified; do not report it as done.`
+  return {
+    isError: false,
+    text: `${head}\n\n${toText(r, { evidencePath: path.relative(root, x.evidencePath) })}`,
+    structured: {
+      verdict: r.verdict,
+      exitCode: x.rc,
+      ...(r.reason ? { reason: r.reason } : {}),
+      blocking: blocking.length,
+      findings: r.findings.map(({ file, line, rule, engine, severity, blocking: b, message, proof, negativeControl }) => ({ file, line, rule, engine, severity, blocking: b, message, proof, negativeControl })),
+      engines: r.engines.map((e) => ({ id: e.id, status: e.status, ...(e.reason ? { reason: e.reason } : {}), findings: e.findings || 0 })),
+      evidencePath: x.evidencePath,
+      evidenceDigest: r.evidenceDigest,
+    },
+  }
+}
+
+function toolExplain(args, { cwd }) {
+  const engine = ENGINES.find((e) => e.id === args.engine)
+  if (!engine) throw new ToolError(`unknown engine ${args.engine}`)
+  const cat = ruleCatalogue().find((c) => c.engine === engine.id)
+  const rule = args.rule ? cat.rules.find((r) => r.id === args.rule) : null
+  if (args.rule && !rule) throw new ToolError(`engine ${engine.id} has no rule ${args.rule}; known: ${cat.rules.map((r) => r.id).join(', ')}`)
+  const ctl = engine.negativeControls.find((c) => c.expect === args.rule) || engine.negativeControls[0]
+  const L = [`${engine.id} ${engine.version} — ${engine.title}`, `source: ${engine.provenance}`]
+  if (rule) L.push('', `${rule.id} (${rule.severity}): ${rule.summary}`, `fix: ${rule.fix || '-'}`)
+  L.push('', `negative control ${ctl.id} — this planted defect in ${ctl.file} must be caught (${ctl.expect}) before every run, or the engine is NOT_MEASURED:`, ctl.content.replace(/\n$/, ''))
+  const structured = { engine: engine.id, rule: rule || null, negativeControl: { id: ctl.id, file: ctl.file, expect: ctl.expect, content: ctl.content } }
+  if (args.file) {
+    const root = resolveRoot(args.path, cwd)
+    const p = prove(root, engine.id, args.file, args.line ?? null)
+    if (p.status !== 'OK') {
+      L.push('', `proof: NOT_MEASURED — ${p.reason}`)
+      structured.proof = { status: 'NOT_MEASURED', reason: p.reason }
+    } else {
+      const hits = args.rule ? p.hits.filter((h) => h.rule === args.rule) : p.hits
+      const src = p.content.split('\n')
+      L.push('', `proof · ${args.file}${args.line ? `:${args.line}` : ''} · sha256 ${p.sha.slice(0, 16)}…`)
+      for (const f of hits) {
+        L.push(`  ${f.rule} (${f.severity}) at ${args.file}:${f.line}`)
+        for (let i = Math.max(1, f.line - 1); i <= Math.min(src.length, f.line + 2); i++) L.push(`   ${String(i).padStart(4)} ${i === f.line ? '>' : ' '} ${src[i - 1]}`)
+        L.push(`  ${f.message}`)
+      }
+      L.push(hits.length ? `REPRODUCED: yes — ${hits.length} finding(s)` : 'REPRODUCED: no — the defect is not present there (fixed).')
+      structured.proof = { status: 'OK', reproduced: hits.length > 0, sha256: p.sha, hits: hits.map(({ line, rule: r, severity, message }) => ({ line, rule: r, severity, message })) }
+    }
+  }
+  return { isError: false, text: L.join('\n'), structured }
+}
+
+function toolListRules(args) {
+  const cat = ruleCatalogue().filter((c) => !args.engine || c.engine === args.engine)
+  const L = []
+  for (const c of cat) {
+    L.push(`${c.engine} ${c.version} — ${c.title}`, `  source: ${c.provenance}`)
+    for (const r of c.rules) L.push(`  ${r.id.padEnd(26)} ${r.severity.padEnd(6)} ${r.summary}`)
+    L.push(`  negative controls: ${c.negativeControls.join(', ')}`, '')
+  }
+  return { isError: false, text: L.join('\n').trimEnd(), structured: { engines: cat } }
+}
+
+const HANDLERS = { check: toolCheck, explain_finding: toolExplain, list_rules: toolListRules }
+
+/** Pure request handler (tested directly and over stdio). Returns a response object, or null for notifications. */
+export function createMcpHandler({ cwd = process.cwd(), executeCheck } = {}) {
+  let initialized = false
+  // evidence@2 attestation: the MCP client that calls `check` is the agent whose work is being verified.
+  let maker = null
+  const ok = (id, result) => ({ jsonrpc: '2.0', id, result })
+  const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } })
+  return function handle(msg) {
+    if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+      return msg && msg.id !== undefined && msg.method === undefined ? null : fail(msg?.id ?? null, -32600, 'Invalid Request')
+    }
+    const isNotification = msg.id === undefined || msg.id === null
+    if (isNotification) { if (msg.method === 'notifications/initialized') initialized = true; return null }
+    const { id, method, params = {} } = msg
+    switch (method) {
+      case 'initialize': {
+        initialized = true
+        const ci = params.clientInfo
+        if (ci && typeof ci.name === 'string' && ci.name.trim()) maker = { kind: 'agent', id: ci.name, source: 'mcp-client', ...(typeof ci.version === 'string' ? { model: undefined } : {}) }
+        const want = params.protocolVersion
+        return ok(id, {
+          protocolVersion: PROTOCOL_VERSIONS.includes(want) ? want : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'fini-proof', title: 'Fini Proof', version: TOOL_VERSION },
+          instructions: 'Fini Proof is an independent verifier. Before you tell the user a coding task is done, call `check` (base "HEAD" for uncommitted work, or the target branch). A FAIL or NOT_MEASURED verdict means the work is not done. Never make it pass by weakening tests, ignore globs, baselines or the verifier config.',
+        })
+      }
+      case 'ping': return ok(id, {})
+      case 'tools/list': return ok(id, { tools: TOOLS })
+      case 'tools/call': {
+        if (!initialized) return fail(id, -32002, 'server not initialized')
+        const h = HANDLERS[params.name]
+        if (!h) return fail(id, -32602, `Unknown tool: ${params.name}`)
+        const args = params.arguments || {}
+        if (typeof args !== 'object' || Array.isArray(args)) return fail(id, -32602, 'arguments must be an object')
+        try {
+          const r = h(args, { cwd, executeCheck, maker })
+          return ok(id, { content: [{ type: 'text', text: r.text }], structuredContent: r.structured, isError: r.isError })
+        } catch (e) {
+          // A tool-level failure is reported IN the result (the agent sees it), never as a silent success.
+          return ok(id, { content: [{ type: 'text', text: `${params.name} failed: ${e.message}` }], isError: true })
+        }
+      }
+      default: return fail(id, -32601, `Method not found: ${method}`)
+    }
+  }
+}
+
+/** Serve on stdio until stdin closes. Resolves to exit code 0. */
+export async function serveMcp({ input = process.stdin, output = process.stdout, cwd = process.cwd() } = {}) {
+  const { executeCheck } = await import('./cli.mjs')
+  const handle = createMcpHandler({ cwd, executeCheck })
+  const send = (m) => output.write(JSON.stringify(m) + '\n')
+  const rl = createInterface({ input, crlfDelay: Infinity })
+  for await (const line of rl) {
+    if (!line.trim()) continue
+    let msg
+    try { msg = JSON.parse(line) } catch { send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); continue }
+    const batch = Array.isArray(msg)
+    const replies = (batch ? msg : [msg]).map((m) => {
+      try { return handle(m) } catch (e) { return { jsonrpc: '2.0', id: m?.id ?? null, error: { code: -32603, message: `Internal error: ${e.message}` } } }
+    }).filter(Boolean)
+    if (batch && replies.length) send(replies)
+    else for (const r of replies) send(r)
+  }
+  return 0
+}