@coderifts/agent-guard 17.1.0 → 17.2.0

package/dist/cjs/vendor/verify-evidence.js

@@ -0,0 +1,238 @@
+'use strict';
+
+/**
+ * THE CANONICAL EVIDENCE VERIFIER — every signature in a prove envelope, not just one.
+ *
+ * ── WHAT 1423 MEASURED ──────────────────────────────────────────────────────────────────────
+ *
+ * A recorded artifact is protected by two different things, and they answer different questions:
+ *
+ *   the PIN (sha256)   are these the bytes we vendored?      → tamper-EVIDENT
+ *   the SIGNATURES     did the named issuers produce them?   → AUTHENTIC
+ *
+ * Conformance checked the pin and exactly one signature (the correlation). So an auditor could
+ * flip the last character of `issuance.execution_grant`, recompute the pin, and the profile still
+ * graded COVERED — reproduced, both mutations, before this file existed. The pin cannot catch that
+ * on its own: whoever edits the bytes also owns the file the hash is written in.
+ *
+ * capability-demo's `prove --check` already refused both mutations. That is the shape of the bug:
+ * not a missing capability anywhere, but TWO verifiers that disagreed about what checking means.
+ * So this is a shared core rather than a third implementation — one place to fix, one place to
+ * drift from, and consumers that can be tested against each other.
+ *
+ * ── WHAT IT REFUSES TO DO ───────────────────────────────────────────────────────────────────
+ *
+ * An ABSENT token is reported ABSENT and never as verified. This matters more than it sounds: a
+ * verifier that returns "ok" for an envelope carrying no grant at all would let the strongest
+ * possible tamper — deletion — read as a pass. The caller says which slots it requires
+ * (`required`), and absence of a required slot is a failure with its own reason.
+ *
+ * It authenticates SIGNATURES. It does not decide whether the run's claims are true: a correctly
+ * signed transcript of a failing run is authentic and still a failure. Callers keep grading.
+ */
+
+const crypto = require('node:crypto');
+
+const { verifyReceipt, keyringFromDocument } = require('./verify.js');
+const { verifyExecutionGrant } = require('./verify-grant.js');
+const { verifyProveTranscript } = require('./verify-prove-transcript.js');
+
+const CORRELATION_V = 'cr.exec.correlation.v1';
+const US = '\x1f';
+
+/** The slots this verifier knows how to authenticate. */
+const SLOT = Object.freeze({
+  CHAIN_RECEIPT: 'chain_receipt',
+  EXECUTION_GRANT: 'execution_grant',
+  TRANSCRIPT_TOKEN: 'transcript_token',
+  CORRELATION: 'correlation',
+  ATTESTATION: 'atomic_attestation',
+});
+
+/** Which keyring signs which slot. Stated as data so a caller can read it, not infer it. */
+const SIGNER = Object.freeze({
+  [SLOT.CHAIN_RECEIPT]: 'issuer',
+  [SLOT.EXECUTION_GRANT]: 'issuer',
+  [SLOT.TRANSCRIPT_TOKEN]: 'executor',
+  [SLOT.CORRELATION]: 'executor',
+  [SLOT.ATTESTATION]: 'executor',
+});
+
+function toKeyring(doc) {
+  if (!doc) return null;
+  if (doc instanceof Map) return doc;
+  return keyringFromDocument(doc);
+}
+
+function keyFor(keyring, kid) {
+  if (!keyring) return null;
+  const entry = keyring instanceof Map ? keyring.get(kid) : keyring[kid];
+  if (!entry) return null;
+  return entry.publicKey || entry.public_key || entry;
+}
+
+/** Rebuilt from the fields, never read back from `correlation_hash`. */
+function correlationPreimage(c) {
+  return [CORRELATION_V, c.scope_hash, c.contract_commit, c.contract_path, c.readback_commit]
+    .join(US);
+}
+
+/**
+ * The correlation is a bare Ed25519 signature over a field-joined preimage rather than a token,
+ * so it gets its own small verifier here instead of a shape it does not have.
+ */
+function verifyCorrelation(c, publicKey) {
+  if (!c || c.v !== CORRELATION_V) {
+    return { valid: false, status: 'CORRELATION_MALFORMED', reason: 'not_a_correlation' };
+  }
+  if (!publicKey) {
+    return { valid: false, status: 'CORRELATION_UNKNOWN_KEY', reason: 'unknown_kid' };
+  }
+  const preimage = correlationPreimage(c);
+  const expected = `sha256:${crypto.createHash('sha256').update(preimage, 'utf8').digest('hex')}`;
+  // The hash is checked BEFORE the signature so a mutated binding field is named as what it is —
+  // a field that no longer matches its own digest — rather than as a generic bad signature.
+  if (c.correlation_hash && c.correlation_hash !== expected) {
+    return { valid: false, status: 'CORRELATION_UNBOUND', reason: 'correlation_hash_mismatch' };
+  }
+  let ok = false;
+  try {
+    ok = crypto.verify(
+      null, Buffer.from(preimage, 'utf8'), publicKey, Buffer.from(String(c.signature), 'base64url'),
+    );
+  } catch (_) {
+    return { valid: false, status: 'CORRELATION_INVALID_SIGNATURE', reason: 'signature_error' };
+  }
+  return ok
+    ? { valid: true, status: 'CORRELATION_VALID' }
+    : { valid: false, status: 'CORRELATION_INVALID_SIGNATURE', reason: 'signature_mismatch' };
+}
+
+/** cr.atomic.execution.attestation.v1 | <kid> | b64url(preimage) | <sig> */
+function verifyAtomicAttestationToken(token, keyring) {
+  const seg = String(token).split('|');
+  if (seg.length !== 4 || seg[0] !== 'cr.atomic.execution.attestation.v1' || seg.some((s) => !s)) {
+    return { valid: false, status: 'ATTEST_MALFORMED', reason: 'malformed_structure' };
+  }
+  const publicKey = keyFor(keyring, seg[1]);
+  if (!publicKey) return { valid: false, status: 'ATTEST_UNKNOWN_KEY', reason: 'unknown_kid', kid: seg[1] };
+  let preimage;
+  try { preimage = Buffer.from(seg[2], 'base64url').toString('utf8'); } catch (_) {
+    return { valid: false, status: 'ATTEST_MALFORMED', reason: 'bad_preimage', kid: seg[1] };
+  }
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(preimage, 'utf8'), publicKey, Buffer.from(seg[3], 'base64url'));
+  } catch (_) {
+    return { valid: false, status: 'ATTEST_INVALID_SIGNATURE', reason: 'signature_error', kid: seg[1] };
+  }
+  return ok
+    ? { valid: true, status: 'ATTEST_VALID', kid: seg[1], preimage }
+    : { valid: false, status: 'ATTEST_INVALID_SIGNATURE', reason: 'signature_mismatch', kid: seg[1] };
+}
+
+/**
+ * Authenticate every signed token an artifact carries.
+ *
+ * @param {object} artifact                a cr.prove.artifact.v1 document
+ * @param {object} o
+ * @param {object|Map} [o.issuerKeys]      registry document (or Map) for the CodeRifts issuer
+ * @param {object|Map} [o.executorKeys]    registry document (or Map) for the executor
+ * @param {string[]} [o.required]          slots that MUST be present; absence is a failure
+ * @param {number} [o.now]                 clock injection; defaults to each token's own issuance
+ *                                         instant, so a recorded artifact is authenticated as of
+ *                                         when it was made rather than expiring in the vendor tree
+ * @returns {{ok: boolean, slots: object[], failures: string[]}}
+ */
+function verifyEvidenceEnvelope(artifact, o = {}) {
+  const issuer = toKeyring(o.issuerKeys);
+  const executor = toKeyring(o.executorKeys);
+  const required = new Set(Array.isArray(o.required) ? o.required : []);
+  const slots = [];
+  const failures = [];
+
+  const record = (name, present, result) => {
+    const entry = {
+      slot: name,
+      signer: SIGNER[name],
+      present,
+      verified: present ? result.valid === true : false,
+      status: present ? result.status : 'ABSENT',
+      reason: present ? (result.reason || null) : 'not_present_in_envelope',
+      kid: present ? (result.kid || null) : null,
+    };
+    slots.push(entry);
+    if (!present && required.has(name)) {
+      failures.push(`the ${name} is absent from the envelope, and this profile requires it`);
+    } else if (present && !entry.verified) {
+      failures.push(`the ${name} signature does not verify (${entry.status}${entry.reason ? `: ${entry.reason}` : ''})`);
+    }
+    return entry;
+  };
+
+  const iss = artifact && artifact.issuance ? artifact.issuance : null;
+
+  // ── issuer-signed ────────────────────────────────────────────────────────────────────────
+  const grantTok = iss && iss.execution_grant;
+  if (grantTok) {
+    // now = the grant's own not_before/iat. A RECORDED grant is short-lived by design; judging it
+    // against today's clock would report every vendored fixture as expired, which says something
+    // about the calendar and nothing about the signature.
+    const g = iss.grant || {};
+    const at = Number.isFinite(o.now) ? o.now : Date.parse(g.not_before || g.iat || artifact.started_at);
+    record(SLOT.EXECUTION_GRANT, true, verifyExecutionGrant(grantTok, {
+      ctx: { keyring: issuer, expectedKid: null },
+      now: Number.isFinite(at) ? at + 1000 : undefined,
+    }));
+  } else {
+    record(SLOT.EXECUTION_GRANT, false, {});
+  }
+
+  const receiptTok = iss && iss.chain_receipt;
+  if (receiptTok) {
+    const at = Number.isFinite(o.now) ? o.now : Date.parse(artifact.started_at);
+    record(SLOT.CHAIN_RECEIPT, true, verifyReceipt(receiptTok, {
+      ctx: { keyring: issuer, expectedKid: null },
+      now: Number.isFinite(at) ? at + 1000 : undefined,
+    }));
+  } else {
+    record(SLOT.CHAIN_RECEIPT, false, {});
+  }
+
+  // ── executor-signed ──────────────────────────────────────────────────────────────────────
+  if (artifact && artifact.transcript_token) {
+    record(SLOT.TRANSCRIPT_TOKEN, true,
+      verifyProveTranscript(artifact.transcript_token, { keyring: executor }));
+  } else {
+    record(SLOT.TRANSCRIPT_TOKEN, false, {});
+  }
+
+  if (artifact && artifact.correlation) {
+    const c = artifact.correlation;
+    const kid = executor && executor instanceof Map ? [...executor.keys()][0] : null;
+    record(SLOT.CORRELATION, true, verifyCorrelation(c, keyFor(executor, kid)));
+  } else {
+    record(SLOT.CORRELATION, false, {});
+  }
+
+  const att = artifact && artifact.atomic_execution_attestation
+    ? artifact.atomic_execution_attestation
+    : (artifact && artifact.attestation) || null;
+  if (typeof att === 'string' && att.length > 0) {
+    record(SLOT.ATTESTATION, true, verifyAtomicAttestationToken(att, executor));
+  } else {
+    record(SLOT.ATTESTATION, false, {});
+  }
+
+  return { ok: failures.length === 0, slots, failures };
+}
+
+module.exports = {
+  verifyEvidenceEnvelope,
+  verifyCorrelation,
+  verifyAtomicAttestationToken,
+  correlationPreimage,
+  SLOT,
+  SIGNER,
+  CORRELATION_V,
+};