@portll/cobolwork 0.2.75 → 0.2.117

package/lib/evidence/run.mjs

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// What a CLI run records in its journal: the command, the files it read by digest, its findings and
+// suppressions by fingerprint, what it wrote by digest, and how it ended. docs/spec/evidence.md §5.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { basename, relative, resolve, sep } from 'node:path';
+import { directoryTree } from '../kernel/source-tree.mjs';
+import { isSource, relPath } from '../sources.mjs';
+import { openJournal } from './journal.mjs';
+import { evidenceDirFrom } from './store.mjs';
+
+const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+
+// Option values that are names, refs or dates. Anything else (a reason, a path, a person) is
+// recorded as present, not as what it said.
+const SAFE_VALUE = new Set(['--format', '--only', '--base', '--head', '--target', '--keys', '--action', '--rule', '--expires', '--provenance-format', '--max-unsealed', '--ref']);
+
+export function recordedArgv(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { out.push('--', '<compiler argv>'); break; }
+    out.push(a.startsWith('-') ? a : i === 0 ? a : '<operand>');
+    if (a.startsWith('--') && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-') && VALUED.has(a)) {
+      out.push(SAFE_VALUE.has(a) ? String(argv[i + 1]) : '<value>');
+      i++;
+    }
+  }
+  return out;
+}
+
+const VALUED = new Set(['--format', '--out', '--only', '--base', '--head', '--baseline', '--reason', '--who', '--expires', '--action', '--rule', '--advisories', '--copylib', '--report', '--keys', '--target', '--cobc', '--policy', '--provenance', '--provenance-format', '--ironwork', '--evidence', '--ssh-key', '--signer', '--allowed-signers', '--anchor-git', '--ref', '--max-unsealed', '--artifact', '--equivalence', '--name', '--tsq', '--tsr', '--expect-key']);
+
+// A journal for this run, or null when no evidence directory is named.
+export function startEvidence(opts, { command, argv, roots, toolVersion, toolRevision = null, env = process.env }) {
+  const dir = evidenceDirFrom(opts, env);
+  if (!dir) return null;
+  const journal = openJournal(dir, { command, argv: recordedArgv(argv), roots: roots.map((r) => basename(r)), readRoots: roots, toolVersion, toolRevision });
+  journal.roots = roots.map((r) => resolve(r));
+  return journal;
+}
+
+export function recordInputs(journal, rootIndex, root, files = null) {
+  if (!journal) return;
+  const list = files || directoryTree(root).list().filter(isSource).sort();
+  for (const p of list) {
+    let bytes;
+    try { bytes = readFileSync(p); } catch { continue; }
+    journal.append('input', { root: rootIndex, path: relPath(root, p), sha256: sha256(bytes), bytes: bytes.length });
+  }
+}
+
+// Inputs already hashed by the caller (the build's provenance record): [{ path, sha256 }].
+export function recordHashed(journal, rootIndex, hashes) {
+  if (!journal) return;
+  for (const h of hashes || []) journal.append('input', { root: rootIndex, path: h.path, sha256: h.sha256 });
+}
+
+export function recordFindings(journal, report) {
+  if (!journal || !report) return;
+  for (const f of report.findings || []) {
+    if (!f.fingerprint) continue;
+    journal.append('finding', { fingerprint: f.fingerprint, rule: f.rule, tier: f.tier || f.sev || undefined, path: f.path || undefined, line: Number.isSafeInteger(f.line) ? f.line : undefined });
+  }
+  for (const f of report.suppressed || []) {
+    if (!f.fingerprint || !f.suppressed) continue;
+    const s = f.suppressed;
+    journal.append('suppressed', { fingerprint: f.fingerprint, by: 'baseline', who: s.who ?? null, expires: s.expires ?? null, reasonSha256: s.reason ? sha256(String(s.reason)) : null });
+  }
+}
+
+export function recordOutput(journal, name, text, path = null) {
+  if (!journal) return;
+  const bytes = Buffer.from(text, 'utf8');
+  const rel = path ? relativeName(path, journal.roots) : null;
+  journal.append('output', { name, sha256: sha256(bytes), bytes: bytes.length, ...(rel ? { path: rel } : { stdout: true }) });
+}
+
+// A written file named relative to the root it sits under, or by its base name.
+function relativeName(path, roots = []) {
+  const abs = resolve(path);
+  for (const r of roots) if (abs === r || abs.startsWith(r + sep)) return relative(r, abs).split(sep).join('/');
+  return basename(abs);
+}
+
+export function recordVerdict(journal, doc, exit) {
+  if (!journal || !doc) return;
+  const checks = doc.checks && typeof doc.checks === 'object' ? Object.fromEntries(Object.entries(doc.checks).filter(([, v]) => v === null || typeof v === 'boolean')) : undefined;
+  journal.append('verdict', { verdict: String(doc.verdict), checks, relaxed: Array.isArray(doc.relaxed) ? doc.relaxed.map(String) : undefined, exit: Number.isSafeInteger(exit) ? exit : undefined });
+}
+
+export function recordBaselineWrite(journal, { before, after, who, expires, reason, path, text }) {
+  if (!journal) return;
+  const held = new Set(before.map((e) => e.fingerprint));
+  const kept = new Set(after.map((e) => e.fingerprint));
+  journal.append('baseline-write', {
+    added: [...kept].filter((f) => !held.has(f)).sort(),
+    removed: [...held].filter((f) => !kept.has(f)).sort(),
+    who: who ?? null, expires: expires ?? null, reasonSha256: reason ? sha256(String(reason)) : null,
+    path: relativeName(path, journal.roots), sha256: sha256(Buffer.from(text, 'utf8')),
+  });
+}
+
+// Closes the journal; a ledger that could not be written is said on standard error, and the
+// command's own exit status stands.
+export function finishEvidence(journal, exit) {
+  if (!journal) return null;
+  const r = journal.close({ exit: Number.isSafeInteger(exit) ? exit : null });
+  if (r.ledger !== 'recorded') process.stderr.write(`cobolwork: evidence run ${journal.id} was not recorded in the ledger: ${r.reason}\n`);
+  return r;
+}

package/lib/evidence/seal.mjs

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Seals: an in-toto statement over the ledger's tip, in a DSSE envelope, signed by ssh-keygen or a
+// program that signs as it does, kept in seals/ and handed to witnesses. docs/spec/evidence.md §7-8.
+import { spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { canonical } from './record.mjs';
+import { dearmor, fingerprint, parseSshsig, verifySshsig } from './sshsig.mjs';
+import { EvidenceRefusal, createExclusive, prepareDir, syncClose, takeLock, writeAll } from './store.mjs';
+import { LEDGER, LOCK } from './journal.mjs';
+import { verifyChain } from './verify.mjs';
+
+export const NAMESPACE = 'cobolwork-evidence';
+export const PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+export const STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+export const SEAL_PREDICATE = 'https://github.com/Portll/cobolwork/blob/main/docs/spec/evidence.md#seal-v1';
+
+const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+
+// DSSE pre-authentication encoding.
+export function pae(type, body) {
+  const t = Buffer.from(type, 'utf8');
+  return Buffer.concat([Buffer.from(`DSSEv1 ${t.length} `), t, Buffer.from(` ${body.length} `), body]);
+}
+
+export function sealFiles(dir) {
+  const d = join(dir, 'seals');
+  if (!existsSync(d)) return [];
+  if (lstatSync(d).isSymbolicLink()) throw new EvidenceRefusal(`${d} is a symbolic link, which evidence is not read through`);
+  return readdirSync(d).map((n) => /^(\d+)\.dsse\.json$/.exec(n)).filter(Boolean)
+    .map((m) => ({ seq: Number(m[1]), name: m[0], path: join(d, m[0]) })).sort((a, b) => a.seq - b.seq);
+}
+
+const BOUNDED = { timeout: 30000, maxBuffer: 1 << 20, windowsHide: true };
+
+function sign(bytes, { sshKey, signer, env, expectKeyid }) {
+  const r = sshKey
+    ? spawnSync('ssh-keygen', ['-Y', 'sign', '-f', sshKey, '-n', NAMESPACE], { ...BOUNDED, input: bytes, env })
+    : spawnSync(signer, [NAMESPACE], { ...BOUNDED, input: bytes, env });
+  if (r.error) throw new EvidenceRefusal(`the signer could not be run: ${r.error.message}`);
+  if (r.status !== 0) throw new EvidenceRefusal(`the signer exited ${r.status}: ${String(r.stderr).trim().slice(0, 300)}`);
+  const blob = dearmor(r.stdout);
+  const sig = parseSshsig(blob);
+  const self = verifySshsig({ blob, message: bytes, namespace: NAMESPACE, allowed: [{ principals: ['signer'], keyBlob: sig.publicKey, certAuthority: false, namespaces: null }] });
+  if (self.valid === false) throw new EvidenceRefusal(`the signer's signature does not verify over what was sealed: ${self.reason}`);
+  const keyid = fingerprint(sig.publicKey);
+  if (expectKeyid && keyid !== expectKeyid) throw new EvidenceRefusal(`the signer signed with ${keyid}, not the expected ${expectKeyid}`);
+  return { keyid, sig: blob.toString('base64') };
+}
+
+// A DSSE envelope over any in-toto statement, signed as seals are.
+export function envelopeFor(payload, { sshKey = null, signer = null, expectKeyid = null, env = process.env } = {}) {
+  if (!sshKey && !signer) throw new EvidenceRefusal('signing needs --ssh-key or --signer');
+  return { payloadType: PAYLOAD_TYPE, payload: payload.toString('base64'), signatures: [sign(pae(PAYLOAD_TYPE, payload), { sshKey, signer, env, expectKeyid })] };
+}
+
+// Seals the ledger at its tip. Refuses a ledger that does not verify: a seal over a broken chain
+// would attest the break.
+export function seal(dir, { sshKey = null, signer = null, expectKeyid = null, toolVersion, now = () => new Date().toISOString(), env = process.env } = {}) {
+  const real = prepareDir(dir);
+  const held = takeLock(join(real, LOCK));
+  if (!held) throw new EvidenceRefusal('the ledger lock could not be had');
+  try {
+    const ledger = verifyChain(join(real, LEDGER), 'ledger');
+    if (ledger.broken.length) throw new EvidenceRefusal(`the ledger does not verify (${ledger.broken[0].check} at line ${ledger.broken[0].line}); nothing is sealed`);
+    if (!ledger.records.length) throw new EvidenceRefusal('the ledger is empty; nothing is sealed');
+    const tip = ledger.records[ledger.records.length - 1];
+    const seals = sealFiles(real);
+    const last = seals[seals.length - 1];
+    if (last) {
+      try {
+        const prior = JSON.parse(readFileSync(last.path, 'utf8'));
+        if (prior.payloadType !== PAYLOAD_TYPE || typeof prior.payload !== 'string') throw new Error('not a DSSE envelope');
+      } catch (e) { throw new EvidenceRefusal(`seals/${last.name} is not a seal (${e.message}); verify the directory before sealing again`); }
+    }
+    const statement = {
+      _type: STATEMENT_TYPE,
+      subject: [{ name: `ledger:${tip.chain}`, digest: { sha256: tip.hash } }],
+      predicateType: SEAL_PREDICATE,
+      predicate: {
+        ledgerLength: ledger.records.length,
+        sealedAt: now(),
+        previousSeal: last ? { sha256: sha256(readFileSync(last.path)) } : null,
+        tool: { name: 'cobolwork', version: toolVersion },
+      },
+    };
+    const payload = Buffer.from(canonical(statement), 'utf8');
+    const signatures = sshKey || signer ? [sign(pae(PAYLOAD_TYPE, payload), { sshKey, signer, env, expectKeyid })] : [];
+    const envelope = { payloadType: PAYLOAD_TYPE, payload: payload.toString('base64'), signatures };
+    const seq = last ? last.seq + 1 : 0;
+    const path = join(real, 'seals', `${seq}.dsse.json`);
+    const fd = createExclusive(path);
+    const text = `${canonical(envelope)}\n`;
+    try { writeAll(fd, text); } finally { syncClose(fd); }
+    return { seq, path, statement, envelope, digest: sha256(text), signed: signatures.length > 0 };
+  } finally { held.release(); }
+}
+
+const git = (repo, args, env) => spawnSync('git', ['-C', repo, ...args], { ...BOUNDED, env: cleanGitEnv(env) });
+
+// A git that reads this repository and no other: no inherited GIT_DIR, index or object redirection.
+export function cleanGitEnv(env = process.env) {
+  const out = {};
+  for (const [k, v] of Object.entries(env)) if (!/^GIT_/.test(k)) out[k] = v;
+  return { ...out, GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' };
+}
+
+// Copies a seal into the anchor repository and commits it there; pushes with `push`.
+export function anchorGit(sealPath, { repo, chain, seq, push = false, env = process.env }) {
+  if (!/^[0-9a-f]{32}$/.test(String(chain)) || !Number.isSafeInteger(seq) || seq < 0) throw new EvidenceRefusal(`a seal is anchored under a 32-hex ledger chain and a whole-number sequence, not ${chain}/${seq}`);
+  const rel = `${chain}/${seq}.dsse.json`;
+  const dir = join(repo, chain);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const target = join(repo, rel);
+  if (existsSync(target)) {
+    if (!readFileSync(target).equals(readFileSync(sealPath))) throw new EvidenceRefusal(`${rel} already holds a different seal in the anchor repository`);
+  } else {
+    const fd = createExclusive(target);
+    try { writeAll(fd, readFileSync(sealPath, 'utf8')); } finally { syncClose(fd); }
+  }
+  const steps = [['add', '--', rel], ['-c', 'core.hooksPath=/dev/null', 'commit', '-q', '--no-verify', '-m', `evidence seal ${rel}`, '--', rel]];
+  for (const args of steps) {
+    const r = git(repo, args, env);
+    if (r.status !== 0 && !(args.includes('commit') && /nothing to commit|no changes added/.test(String(r.stdout) + String(r.stderr)))) {
+      throw new EvidenceRefusal(`git ${args.includes('commit') ? 'commit' : args[0]} in the anchor repository: ${String(r.stderr).trim().slice(0, 300)}`);
+    }
+  }
+  const head = String(git(repo, ['rev-parse', 'HEAD'], env).stdout).trim();
+  if (!push) return { committed: head, pushed: false, path: rel };
+  const p = git(repo, ['-c', 'core.hooksPath=/dev/null', 'push', '-q', '--no-verify'], env);
+  return { committed: head, pushed: p.status === 0, path: rel, ...(p.status === 0 ? {} : { reason: p.error ? p.error.message : String(p.stderr).trim().slice(0, 300) || `exit ${p.status}` }) };
+}
+
+// A seal as the witness holds it, or a reason it cannot be read.
+export function readWitnessed(repo, ref, rel, env = process.env) {
+  const r = git(repo, ['cat-file', 'blob', `${ref}:${rel}`], env);
+  if (r.status !== 0) return { text: null, reason: `not on ${ref}` };
+  return { text: String(r.stdout) };
+}
+
+// Every seal the witness holds at `ref`, by ledger chain: Map(chain -> [seq ascending]).
+export function listWitnessed(repo, ref, env = process.env) {
+  const r = git(repo, ['ls-tree', '-r', '--name-only', ref], env);
+  const out = new Map();
+  if (r.status !== 0) return out;
+  for (const line of String(r.stdout).split('\n')) {
+    const m = /^([0-9a-f]{32})\/(\d+)\.dsse\.json$/.exec(line.trim());
+    if (!m) continue;
+    if (!out.has(m[1])) out.set(m[1], []);
+    out.get(m[1]).push(Number(m[2]));
+  }
+  for (const seqs of out.values()) seqs.sort((a, b) => a - b);
+  return out;
+}
+
+export function resolveRef(repo, ref, env = process.env) {
+  const r = git(repo, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], env);
+  return r.status === 0 ? String(r.stdout).trim() : null;
+}
+
+// A DER TimeStampReq (RFC 3161) over SHA-256 of `bytes`, with a random nonce and certReq true.
+export function timeStampRequest(bytes) {
+  const der = (tag, body) => {
+    const len = body.length < 128 ? Buffer.from([body.length]) : (() => { const b = []; let n = body.length; while (n) { b.unshift(n & 0xff); n >>= 8; } return Buffer.from([0x80 | b.length, ...b]); })();
+    return Buffer.concat([Buffer.from([tag]), len, body]);
+  };
+  const oidSha256 = Buffer.from([0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01]);
+  const algorithm = der(0x30, Buffer.concat([oidSha256, Buffer.from([0x05, 0x00])]));
+  const digest = createHash('sha256').update(bytes).digest();
+  const imprint = der(0x30, Buffer.concat([algorithm, der(0x04, digest)]));
+  let nonce = randomBytes(8);
+  nonce[0] &= 0x7f;
+  if (nonce[0] === 0) nonce[0] = 1;
+  const body = Buffer.concat([Buffer.from([0x02, 0x01, 0x01]), imprint, der(0x02, nonce), Buffer.from([0x01, 0x01, 0xff])]);
+  return { der: der(0x30, body), digest: digest.toString('hex'), nonce: nonce.toString('hex') };
+}

package/lib/evidence/slsa.mjs

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The build provenance record as an in-toto statement with the SLSA Provenance v1 predicate
+// (docs/spec/evidence.md §10). Unsigned: the platform that signs it earns any SLSA level.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { basename, relative, resolve, sep } from 'node:path';
+import { STATEMENT_TYPE } from './seal.mjs';
+
+export const SLSA_PREDICATE = 'https://slsa.dev/provenance/v1';
+export const BUILD_TYPE = 'https://github.com/Portll/cobolwork/blob/main/docs/spec/evidence.md#build-v1';
+export const LOCAL_BUILDER = 'https://github.com/Portll/cobolwork/local';
+
+const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+
+// A path under `root` by its relative name, anything else by its base name.
+function named(path, root) {
+  const abs = resolve(path);
+  const r = resolve(root);
+  return abs.startsWith(r + sep) ? relative(r, abs).split(sep).join('/') : basename(abs);
+}
+
+export function slsaStatement({ provenance, docBytes, root, artifacts = [], runId = null, runTip = null, builderId = null, startedOn = null, finishedOn = null }) {
+  const subject = [{ name: 'build.json', digest: { sha256: sha256(docBytes) } },
+    ...artifacts.map((p) => ({ name: named(p, root), digest: { sha256: sha256(readFileSync(p)) } }))];
+
+  const resolvedDependencies = (provenance.sources || []).map((s) => ({ uri: `file:${s.path}`, name: s.path, digest: { sha256: s.sha256 } }));
+  if (provenance.compiler && provenance.compiler.sha256) {
+    const c = provenance.compiler;
+    const name = c.tool === 'ironwork' ? 'ironwork' : basename(c.path);
+    resolvedDependencies.push({ uri: `file:${basename(c.path)}`, name, digest: { sha256: c.sha256 }, ...(c.version ? { annotations: { version: String(c.version) } } : {}) });
+  }
+  resolvedDependencies.sort(byName);
+
+  const externalParameters = {
+    revisions: provenance.revisions,
+    policy: { sha256: provenance.policy.sha256, setBy: provenance.policy.setBy },
+    ...(provenance.copylibs && provenance.copylibs.length ? { copylibs: provenance.copylibs.map((d) => basename(d)) } : {}),
+    ...(provenance.compiler && provenance.compiler.argv ? { compilerArguments: provenance.compiler.argv } : {}),
+  };
+  const internalParameters = {
+    tool: 'cobolwork', toolVersion: provenance.toolVersion, flowModel: provenance.flowModel,
+    ...(provenance.toolRevision ? { toolRevision: provenance.toolRevision } : {}),
+    verdict: provenance.verdict, relaxed: provenance.relaxed,
+  };
+  const metadata = {
+    ...(runId ? { invocationId: runId } : {}),
+    ...(startedOn ? { startedOn } : {}),
+    ...(finishedOn ? { finishedOn } : {}),
+  };
+  return {
+    _type: STATEMENT_TYPE,
+    subject,
+    predicateType: SLSA_PREDICATE,
+    predicate: {
+      buildDefinition: { buildType: BUILD_TYPE, externalParameters, internalParameters, resolvedDependencies },
+      runDetails: {
+        builder: { id: builderId || LOCAL_BUILDER },
+        metadata,
+        byproducts: runTip ? [{ name: `evidence:run:${runId}`, digest: { sha256: runTip } }] : [],
+      },
+    },
+  };
+}

package/lib/evidence/sshsig.mjs

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// SSHSIG signatures (OpenSSH PROTOCOL.sshsig) checked with node:crypto against an allowed_signers
+// file, for ssh-ed25519 and ecdsa-sha2-nistp256 keys. Anything else is reported, not guessed at.
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+
+const MAGIC = Buffer.from('SSHSIG');
+const VERIFIED_TYPES = new Set(['ssh-ed25519', 'ecdsa-sha2-nistp256']);
+const KEY_TYPE = /^(?:ssh-(?:ed25519|rsa|dss)|ecdsa-sha2-nistp(?:256|384|521)|sk-(?:ssh-ed25519|ecdsa-sha2-nistp256)@openssh\.com|[a-z0-9-]+-cert-v01@openssh\.com)$/;
+
+class Reader {
+  constructor(buf) { this.buf = buf; this.at = 0; }
+  u32() {
+    if (this.at + 4 > this.buf.length) throw new Error('truncated');
+    const v = this.buf.readUInt32BE(this.at);
+    this.at += 4;
+    return v;
+  }
+  bytes(n) {
+    if (this.at + n > this.buf.length) throw new Error('truncated');
+    const out = this.buf.subarray(this.at, this.at + n);
+    this.at += n;
+    return out;
+  }
+  string() { return this.bytes(this.u32()); }
+  text() { return this.string().toString('utf8'); }
+  get done() { return this.at === this.buf.length; }
+}
+
+const sshString = (b) => {
+  const buf = Buffer.isBuffer(b) ? b : Buffer.from(b, 'utf8');
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(buf.length);
+  return Buffer.concat([len, buf]);
+};
+
+export const fingerprint = (keyBlob) => `SHA256:${createHash('sha256').update(keyBlob).digest('base64').replace(/=+$/, '')}`;
+
+export function dearmor(text) {
+  const m = /-----BEGIN SSH SIGNATURE-----([\s\S]*?)-----END SSH SIGNATURE-----/.exec(String(text));
+  if (!m) throw new Error('no SSH SIGNATURE armour');
+  const text64 = m[1].replace(/\s+/g, '');
+  const blob = Buffer.from(text64, 'base64');
+  if (blob.toString('base64') !== text64) throw new Error('the SSH SIGNATURE armour is not canonical base64');
+  return blob;
+}
+
+export function parseSshsig(blob) {
+  const r = new Reader(blob);
+  if (!r.bytes(6).equals(MAGIC)) throw new Error('not an SSHSIG blob');
+  const version = r.u32();
+  if (version !== 1) throw new Error(`SSHSIG version ${version}`);
+  const publicKey = Buffer.from(r.string());
+  const namespace = r.text();
+  r.string();
+  const hashAlg = r.text();
+  const signature = Buffer.from(r.string());
+  if (!r.done) throw new Error('trailing bytes after the SSHSIG signature');
+  return { publicKey, namespace, hashAlg, signature };
+}
+
+// What the signer signed: the preamble, the namespace, the hash algorithm and H(message).
+export function signedData(namespace, hashAlg, message) {
+  if (hashAlg !== 'sha256' && hashAlg !== 'sha512') throw new Error(`SSHSIG hash ${hashAlg}`);
+  const digest = createHash(hashAlg).update(message).digest();
+  return Buffer.concat([MAGIC, sshString(namespace), sshString(''), sshString(hashAlg), sshString(digest)]);
+}
+
+const b64url = (b) => Buffer.from(b).toString('base64url');
+
+function publicKeyOf(blob) {
+  const r = new Reader(blob);
+  const type = r.text();
+  if (type === 'ssh-ed25519') {
+    const pk = r.string();
+    if (pk.length !== 32 || !r.done) throw new Error('malformed ssh-ed25519 key');
+    return { type, key: createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: b64url(pk) }, format: 'jwk' }) };
+  }
+  if (type === 'ecdsa-sha2-nistp256') {
+    if (r.text() !== 'nistp256') throw new Error('malformed ecdsa-sha2-nistp256 key');
+    const q = r.string();
+    if (q.length !== 65 || q[0] !== 4 || !r.done) throw new Error('malformed ecdsa-sha2-nistp256 point');
+    return { type, key: createPublicKey({ key: { kty: 'EC', crv: 'P-256', x: b64url(q.subarray(1, 33)), y: b64url(q.subarray(33)) }, format: 'jwk' }) };
+  }
+  return { type, key: null };
+}
+
+// An SSH mpint to a fixed-width unsigned big-endian integer.
+function unsignedFixed(mpint, width) {
+  let b = mpint;
+  if (b.length && (b[0] & 0x80)) throw new Error('ECDSA component is negative');
+  while (b.length > 1 && b[0] === 0) b = b.subarray(1);
+  if (b.length > width) throw new Error('ECDSA component too wide');
+  return Buffer.concat([Buffer.alloc(width - b.length), b]);
+}
+
+function checkSignature(type, key, sigBlob, data) {
+  const r = new Reader(sigBlob);
+  const sigType = r.text();
+  const sig = r.string();
+  if (!r.done) return false;
+  if (type === 'ssh-ed25519') return sigType === 'ssh-ed25519' && sig.length === 64 && cryptoVerify(null, data, key, sig);
+  if (type === 'ecdsa-sha2-nistp256') {
+    if (sigType !== 'ecdsa-sha2-nistp256') return false;
+    const rs = new Reader(sig);
+    const p1363 = Buffer.concat([unsignedFixed(rs.string(), 32), unsignedFixed(rs.string(), 32)]);
+    if (!rs.done) return false;
+    return cryptoVerify('sha256', data, { key, dsaEncoding: 'ieee-p1363' }, p1363);
+  }
+  return false;
+}
+
+// Splits an allowed_signers line on blanks outside double quotes.
+function fields(line) {
+  const out = [];
+  let cur = '';
+  let quoted = false;
+  for (const ch of line) {
+    if (ch === '"') { quoted = !quoted; cur += ch; } else if (!quoted && (ch === ' ' || ch === '\t')) { if (cur) { out.push(cur); cur = ''; } } else cur += ch;
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+export function parseAllowedSigners(text) {
+  const entries = [];
+  for (const raw of String(text).split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const f = fields(line);
+    if (f.length < 3) continue;
+    const principals = f[0].split(',');
+    let i = 1;
+    const optionFields = [];
+    while (i < f.length && !KEY_TYPE.test(f[i])) optionFields.push(f[i++]);
+    const options = optionFields.join(',');
+    const keyType = f[i];
+    let keyBlob;
+    try { keyBlob = Buffer.from(f[i + 1] || '', 'base64'); } catch { continue; }
+    if (!keyType || !keyBlob.length) continue;
+    const opts = new Map();
+    for (const o of fields(options.replace(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/g, ' '))) {
+      const eq = o.indexOf('=');
+      opts.set((eq < 0 ? o : o.slice(0, eq)).toLowerCase(), eq < 0 ? true : o.slice(eq + 1).replace(/^"|"$/g, ''));
+    }
+    entries.push({
+      principals,
+      keyType,
+      keyBlob,
+      certAuthority: opts.has('cert-authority'),
+      namespaces: typeof opts.get('namespaces') === 'string' ? opts.get('namespaces').split(',') : null,
+    });
+  }
+  return entries;
+}
+
+// { valid: true|false|null, reason, keyType, keyid, principals } for one SSHSIG blob over `message`.
+export function verifySshsig({ blob, message, namespace, allowed }) {
+  let sig;
+  try { sig = parseSshsig(blob); } catch (e) { return { valid: false, reason: `not a signature: ${e.message}` }; }
+  const keyid = fingerprint(sig.publicKey);
+  let pk;
+  try { pk = publicKeyOf(sig.publicKey); } catch (e) { return { valid: false, keyid, reason: e.message }; }
+  const base = { keyType: pk.type, keyid };
+  if (sig.namespace !== namespace) return { ...base, valid: false, reason: `signed for namespace ${sig.namespace}, not ${namespace}` };
+  const matches = (allowed || []).filter((a) => !a.certAuthority && a.keyBlob.equals(sig.publicKey) && (!a.namespaces || a.namespaces.includes(namespace)));
+  if (!matches.length) return { ...base, valid: false, reason: 'the signing key is not in allowed signers for this namespace' };
+  const principals = matches.flatMap((m) => m.principals);
+  if (!VERIFIED_TYPES.has(pk.type) || !pk.key) return { ...base, principals, valid: null, reason: `${pk.type} signatures are not verified here` };
+  let ok = false;
+  try { ok = checkSignature(pk.type, pk.key, sig.signature, signedData(namespace, sig.hashAlg, message)); } catch (e) { return { ...base, principals, valid: false, reason: e.message }; }
+  return { ...base, principals, valid: ok, reason: ok ? null : 'the signature does not match the signed bytes' };
+}