@coderifts/agent-guard 17.1.0 → 17.3.0

package/dist/cjs/vendor/VENDOR.sha256

@@ -1,4 +1,4 @@
-# Vendored verify core — the OFFLINE receipt verifier (1307).
+# Vendored verify core — the OFFLINE receipt verifier (1307) and the CANONICAL EVIDENCE core (1423).
 #
 # Byte copies from the public receipt-verifier, pinned. The guard used to verify over the
 # NETWORK via config.client.verifyReceipt(), which the other three enforcement points do not:
@@ -6,8 +6,33 @@
 # A verifier that needs the network fails differently from one that does not, and the sentence
 # "the same proof at all four points, offline" was false because of this one.
 #
+# 1431 ADDS THE GRANT. Measured before it was changed: the guard authenticated the receipt (this
+# verify.js) and the executor attestation (SDK verifyExecutionAttestation), and NEVER the
+# execution grant. `parseGrantFields` in the SDK DECODES a grant to cross-check jti/scope_hash
+# against the attestation, so a forged token whose payload copies those fields — with the word
+# NEM-ALAIRAS where the signature belongs — was accepted as a kernel binding and upgraded
+# ENFORCING_STRICT from authorized_not_committed to authorized_and_committed. A binding checked
+# against an unauthenticated document is not a binding.
+#
 # Do not edit these files here. Recopy from receipt-verifier and re-pin.
-# source: receipt-verifier e11d3f5d9f5444d8b2a07428c922d2040f4819ce
+# PER-FILE PROVENANCE, mixed on purpose. Collapsing this to one revision would lie: verify.js is
+# pinned at 6048195 and has NOT been recopied, because 1306's keyring-shape fix is the behaviour
+# this guard was tested against and recopying HEAD would change a verifier nobody measured again.
+# The 1423 evidence core is vendored at HEAD. test/vendor-parity.test.js checks each file against
+# ITS OWN revision, not against HEAD, so an honest mixed pin does not read as drift.
+#
+#   verify.js                   6048195c0bcf7e2594a2d78e83cfc082ea615790
+#   arity.js                    724aa9ae8171f1acf629c3c6b4879dc056575f20
+#   verify-grant.js             a472bf9073781cba25d83c7d1406b1a7c4af0b94
+#   verify-prove-transcript.js  724aa9ae8171f1acf629c3c6b4879dc056575f20
+#   verified-execution-binding.js  1e41542296551139c41e2d4b4cff2e67bc42aa06
+#   verify-evidence.js          724aa9ae8171f1acf629c3c6b4879dc056575f20
+#   keys/coderifts-keys.json    724aa9ae8171f1acf629c3c6b4879dc056575f20
 
 verify.js  363e52c72ec4b913e1f3edc8e2029848feaeacb1efa6c07960fe5e5f195c23b3
 arity.js  721fcac58b960b5e2aa1af91edb6cfc87ebe828a6da73879967ef79a1ca474e8
+verify-grant.js  127b53de3be77196862c10a8812221de0a5112cf1d3feae12d347a6021852df7
+verify-prove-transcript.js  3bb17bd4f16d5ee3cf3fbb754b4df9aa570a615ca94ff2a97b751c4fabd3bd0d
+verify-evidence.js  7ca498fad4b23e4ae8f28c42c30058bc3526a00d5cc6d6f36380335bf25d3288
+verified-execution-binding.js  e48ea29b9f8b0c5b1754187788cbaf78cdaf0b505848c05d1ae3ffebb30218f2
+keys/coderifts-keys.json  bfe0c898cda3c3a4c8141726d0adb4cdb7eb9762de6264e430eff6469b90422e

package/dist/cjs/vendor/keys/coderifts-keys.json

@@ -0,0 +1 @@
+{"keys":[{"kid":"2026-07-k1","public_key_pem":"-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAJh8xDXLaOCpQ+bBC9d2I+zG1qVsCpeCuWbtH+aGjC7A=\n-----END PUBLIC KEY-----\n","status":"active","valid_from":null,"retired_at":null}]}

package/dist/cjs/vendor/verified-execution-binding.js

@@ -0,0 +1,316 @@
+'use strict';
+
+/**
+ * verifiedExecutionBinding — the ONE predicate that answers "authorized and committed".
+ *
+ * ── WHY ONE (1459) ──────────────────────────────────────────────────────────────────────────
+ *
+ * The same question was being answered in several places with different rules, and the answers
+ * disagreed. Measured on the public agent-guard 17.2.0, with a forged-signature grant and a REAL
+ * attestation from a trusted executor bound to that grant's jti and scope:
+ *
+ *     ENFORCING_STRICT  authorized_and_committed = false
+ *     ENFORCING_ATOMIC  authorized_and_committed = true
+ *
+ * Two profiles of one product, looking at one set of bytes, reaching opposite conclusions — because
+ * the Atomic formula was `receipt_verified && committed && class === 'executor_attested'` and never
+ * asked whether the GRANT was signed by anyone. A predicate that is recomputed is a predicate that
+ * drifts; this file exists so callers QUOTE the answer instead.
+ *
+ * ── FOUR AUTHORITIES, AND ONLY THEIR INTERSECTION ───────────────────────────────────────────
+ *
+ * Each is independently true or not, and each answers a different question. None of them implies
+ * another, which is exactly why the intersection — not any one of them — is the success condition:
+ *
+ *   issuer_grant          did CodeRifts authorize THIS change?      (a signature under a pinned key)
+ *   executor_attestation  did the executor commit THAT grant?       (a signature over the grant's ids)
+ *   one_run_root          are these bytes from ONE run?             (cr.evidence.root.v1 digests)
+ *   provider_witness      did the provider record it?               (a readback — UNSIGNED by nature)
+ *
+ * ── SHORTFALLS ARE NAMED, NOT FOLDED INTO `false` ───────────────────────────────────────────
+ *
+ * "Not authorized" and "authorized but the commit is unproven" are different facts with different
+ * remedies, and a boolean loses that. Every shortfall gets a state a human can act on, and the
+ * states are ORDERED by severity so the returned one is the most serious thing that is wrong.
+ *
+ * WHAT THIS DOES NOT DO. It reaches no network and holds no keys: every input is supplied by the
+ * caller, already-verified or verifiable, and the four authorities are recomputed here from those
+ * inputs rather than taken as claims. It also cannot see a lying executor — the root closes
+ * third-party splicing, not an executor misreporting its own run.
+ */
+
+const crypto = require('node:crypto');
+
+const { verifyExecutionGrant } = require('./verify-grant.js');
+const { verifyEvidenceRootBinding } = require('./verify-evidence.js');
+
+const BINDING_V = 'cr.verified-execution-binding.v1';
+
+/**
+ * Ordered most-severe first. The returned `state` is the FIRST unmet one, so a caller that renders
+ * a single line renders the thing that most needs fixing.
+ */
+const STATE = Object.freeze({
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  COMMIT_UNPROVEN: 'COMMIT_UNPROVEN',
+  ONE_RUN_UNPROVEN: 'ONE_RUN_UNPROVEN',
+  RECORDED_UNWITNESSED: 'RECORDED_UNWITNESSED',
+  NOT_COMMITTED: 'NOT_COMMITTED',
+  AUTHORIZED_AND_COMMITTED: 'AUTHORIZED_AND_COMMITTED',
+});
+
+/** What each authority is allowed to be missing for, so a caller can choose its own strictness. */
+const AUTHORITY = Object.freeze({
+  ISSUER_GRANT: 'issuer_grant',
+  EXECUTOR_ATTESTATION: 'executor_attestation',
+  ONE_RUN_ROOT: 'one_run_root',
+  PROVIDER_WITNESS: 'provider_witness',
+});
+
+const sha256pref = (v) =>
+  `sha256:${crypto.createHash('sha256').update(String(v), 'utf8').digest('hex')}`;
+
+const b64json = (seg) => {
+  try { return JSON.parse(Buffer.from(seg, 'base64url').toString('utf8')); } catch (_) { return null; }
+};
+
+/** The four fields an attestation binds, read from its own signed preimage. */
+function attestationClaims(token) {
+  if (typeof token !== 'string') return null;
+  const seg = token.split('|');
+  if (seg.length !== 4 || !seg[2]) return null;
+  const body = b64json(seg[2]);
+  return body && typeof body === 'object' ? body : null;
+}
+
+/** The grant's identity, in one vocabulary across v1 and v2. */
+function grantClaims(token) {
+  if (typeof token !== 'string') return null;
+  const body = b64json(String(token).split('.')[0]);
+  if (!body || typeof body !== 'object') return null;
+  return {
+    v: body.v,
+    jti: body.grant_id || body.jti || null,
+    scope_hash: body.after_payload_hash || body.scope_hash || null,
+    receipt_hash: body.receipt_hash || body.receipt_digest || null,
+    operation: body.operation || null,
+    // The rest of what a grant SAYS, so the attestation can be checked against all of it rather
+    // than against the two fields that happened to be compared first.
+    target: body.target_uri || body.target_id || null,
+    tenant_id: body.tenant_id || null,
+    executor_id: body.executor_id || null,
+    adapter_id: body.adapter_id || null,
+    audience: body.audience_hash || body.audience || null,
+    policy_hash: body.policy_hash || null,
+    state_token: body.expected_state_token || body.state_nonce || null,
+  };
+}
+
+/**
+ * @param {object} o
+ * @param {{verified: boolean, token?: string}} o.receipt
+ * @param {{token: string, publicKey?, keyring?, intended?: object, now?: number}} o.grant
+ *        THE EXACT BYTES THE ISSUER SIGNED. Not a grant read back out of a tool result: a caller
+ *        that lets the executed tool hand back its own authorization has already lost.
+ * @param {{token: string, registry?: object, verify?: Function}} [o.attestation]
+ * @param {{artifact: object, executorKey}} [o.evidenceRoot]
+ * @param {{signed: boolean}} [o.providerReadback]
+ * @param {boolean} o.committed
+ * @param {string[]} [o.required]  authorities this caller demands; default: grant + attestation.
+ */
+function verifiedExecutionBinding(o = {}) {
+  const required = new Set(Array.isArray(o.required) && o.required.length
+    ? o.required
+    : [AUTHORITY.ISSUER_GRANT, AUTHORITY.EXECUTOR_ATTESTATION]);
+  const shortfalls = [];
+  const authorities = {};
+  const note = (name, ok, detail) => {
+    authorities[name] = { ok, required: required.has(name), detail };
+    if (!ok && required.has(name)) shortfalls.push(`${name}: ${detail}`);
+    return ok;
+  };
+
+  // ── 1. THE ISSUER GRANT ────────────────────────────────────────────────────────────────
+  const g = o.grant || {};
+  let grantOk = false;
+  let gClaims = null;
+  if (typeof g.token !== 'string' || g.token.length === 0) {
+    note(AUTHORITY.ISSUER_GRANT, false, 'no execution grant was supplied');
+  } else if (!g.publicKey && !g.keyring) {
+    // FAIL-CLOSED, and named as its own thing: "we had no key" is not "the signature was bad".
+    note(AUTHORITY.ISSUER_GRANT, false,
+      'no pinned issuer keyring was supplied, so the grant could not be authenticated');
+  } else {
+    const r = verifyExecutionGrant(g.token, {
+      ctx: { publicKey: g.publicKey, keyring: g.keyring, expectedKid: g.expectedKid ?? null },
+      ...(g.intended ? { intended: g.intended } : {}),
+      ...(Number.isFinite(g.now) ? { now: g.now } : {}),
+    });
+    gClaims = grantClaims(g.token);
+    grantOk = note(AUTHORITY.ISSUER_GRANT, r.valid === true,
+      `${r.status}${r.reason ? `/${r.reason}` : ''}`);
+  }
+
+  // ── 2. THE EXECUTOR ATTESTATION ────────────────────────────────────────────────────────
+  const a = o.attestation || {};
+  let attOk = false;
+  if (typeof a.token !== 'string' || a.token.length === 0) {
+    note(AUTHORITY.EXECUTOR_ATTESTATION, false, 'no executor attestation was supplied');
+  } else if (typeof a.verify !== 'function') {
+    note(AUTHORITY.EXECUTOR_ATTESTATION, false,
+      'no attestation verifier was supplied, so the commit could not be checked');
+  } else {
+    const r = a.verify(a.token, { registry: a.registry });
+    const sigOk = r && r.valid === true;
+    // BOUND TO THE VERIFIED GRANT'S OWN IDS — not to ids the caller passed alongside. This is the
+    // join that makes the two signatures one statement instead of two unrelated true things.
+    const c = attestationClaims(a.token);
+    // ── THE ATTESTATION MUST BIND THE SAME EXECUTION, NOT MERELY THE SAME NAMES (1464) ────
+    //
+    // REPRODUCED before this was written. A correctly-signed grant bound to receipt R1, and a
+    // correctly-signed attestation from a trusted executor bound to receipt R2, sharing a
+    // grant_jti and a scope_hash — R1 != R2 — read AUTHORIZED_AND_COMMITTED. Both signatures are
+    // real; the two documents describe DIFFERENT executions and the join could not tell.
+    //
+    // `jti` and `scope_hash` are the two fields an attacker controls most cheaply: they are copied
+    // FROM the grant into the attestation by whoever assembles the pair. Comparing only those is
+    // comparing a value with its own copy. What binds is the receipt each side was issued against,
+    // and — the strongest available — the sha256 of the exact grant token bytes.
+    const attReceipt = c ? String(c.receipt_digest || '') : '';
+    const grantReceipt = gClaims ? String(gClaims.receipt_hash || '') : '';
+    const mismatch = (() => {
+      if (!sigOk) return `attestation ${r ? r.status : 'unverifiable'}`;
+      if (!gClaims) return 'there is no verified grant for the attestation to bind';
+      if (String(c.grant_jti || '') !== String(gClaims.jti || '')) {
+        return 'the attestation binds a different grant id than the verified grant';
+      }
+      if (String(c.scope_hash || '') !== String(gClaims.scope_hash || '')) {
+        return 'the attestation binds a different scope than the verified grant';
+      }
+      // THE CROSS-RECEIPT CHECK. Empty on either side is a mismatch: an attestation that names no
+      // receipt cannot be shown to be about this authorization, and "unstated" must not read as
+      // "the same".
+      if (!attReceipt || !grantReceipt || attReceipt !== grantReceipt) {
+        return `the grant was issued against receipt ${grantReceipt || '(none)'} and the `
+          + `attestation commits receipt ${attReceipt || '(none)'} — two different executions`;
+      }
+      // ── WHAT cr.exec.attest.v1 CAN AND CANNOT BE ASKED ──────────────────────────────
+      //
+      // MEASURED, and it bounds this check rather than the check bounding the format: the
+      // attestation body is a CLOSED set — executor_kid, grant_jti, receipt_digest, scope_hash,
+      // committed_at, state_nonce, result_digest, meta. Any other key is refused
+      // ATTEST_MALFORMED / unknown_field by its own verifier.
+      //
+      // So target, operation, tenant, executor, adapter, audience and policy CANNOT be
+      // cross-checked here: the attestation never states them, and a comparison against a field
+      // that cannot exist is not a check — it is a line that always passes. They are named in
+      // `does_not_prove` instead, which is the honest place for a binding the format cannot carry.
+      //
+      // The same is true of the exact grant-token digest: there is no field for it. Binding the
+      // grant BYTES rather than its claims would be the tightest join available and it needs a
+      // format change (a `grant_token_digest` slot in cr.exec.attest.v2), not a check here.
+      //
+      // What the format DOES let us bind is the state nonce, and it is bound below.
+      if (gClaims.state_token != null && c.state_nonce != null
+        && String(gClaims.state_token) !== String(c.state_nonce)) {
+        return 'the grant and the attestation disagree about the state nonce';
+      }
+      return null;
+    })();
+    attOk = note(AUTHORITY.EXECUTOR_ATTESTATION, mismatch === null, mismatch || 'bound');
+  }
+
+  // ── 3. ONE RUN ─────────────────────────────────────────────────────────────────────────
+  const er = o.evidenceRoot || null;
+  if (!er || !er.artifact) {
+    note(AUTHORITY.ONE_RUN_ROOT, false,
+      'no cr.evidence.root.v1 was supplied, so these bytes are not shown to be one run');
+  } else {
+    const r = verifyEvidenceRootBinding(er.artifact, { executorKey: er.executorKey, sidecars: er.sidecars });
+    note(AUTHORITY.ONE_RUN_ROOT, r.ok === true, r.ok ? 'bound' : (r.failures[0] || 'unbound'));
+  }
+
+  // ── 4. THE PROVIDER WITNESS ────────────────────────────────────────────────────────────
+  // A readback is an UNSIGNED document by nature. It is carried, not verified, and this authority
+  // is false unless a caller states it was witnessed some stronger way — never true by default.
+  // ── A CALLER BOOLEAN IS NOT EVIDENCE (1465) ────────────────────────────────────────────
+  //
+  // REPRODUCED before this was written:
+  //
+  //   required: ['provider_witness'], receipt: {verified: true},
+  //   providerReadback: {signed: true}, committed: true, NO grant, NO attestation, NO root
+  //     → AUTHORIZED_AND_COMMITTED, shortfalls: []
+  //
+  // `signed: true` was a bare boolean the caller wrote, and this function aggregated it into a
+  // global success. Nothing was verified; a field named `signed` was believed because it was set.
+  //
+  // A witness now requires a VERIFIED witness envelope: bytes plus a verifier plus a trust anchor.
+  // No such format exists yet (phase D measured that the readback is unsigned by nature), so this
+  // authority cannot currently be satisfied at all — and saying that plainly is the honest answer.
+  // Asking for it yields RECORDED_UNWITNESSED, which is exactly what it means.
+  //
+  // NOT a breaking change for the five consumers: none of them requires `provider_witness` today
+  // (guard and contract-gate ask for issuer_grant + executor_attestation; prove and conformance for
+  // issuer_grant + one_run_root). It removes a way to LIE, not a way anyone works.
+  const pw = o.providerReadback || null;
+  const witnessVerified = !!(pw && pw.verified === true && pw.envelope && pw.verifier);
+  note(AUTHORITY.PROVIDER_WITNESS, witnessVerified,
+    pw
+      ? (pw.signed === true && !witnessVerified
+        ? 'the caller asserted `signed: true` and supplied no verifiable witness envelope — a '
+          + 'boolean is not evidence, and no signed-witness format exists yet'
+        : 'the provider readback is an unsigned document (carried, not verified)')
+      : 'no provider readback was supplied');
+
+  // ── THE INTERSECTION ───────────────────────────────────────────────────────────────────
+  const committed = o.committed === true;
+  // THE RECEIPT, and what this function can honestly say about it.
+  //
+  // `verified` is the CALLER's determination: this core is not given the receipt token or a
+  // keyring, so it cannot re-establish it. That is recorded rather than hidden — a reader of the
+  // result can see whether the receipt was verified HERE or asserted by whoever called.
+  //
+  // Left as-is deliberately: making a bare boolean insufficient would change the input shape of
+  // all five consumers at once, and that belongs with the closed-profile work (1465), not
+  // half-done in a round that would leave them broken. The gap is named, not narrowed in silence.
+  const receiptOk = !!(o.receipt && o.receipt.verified === true);
+  const receiptAsserted = receiptOk && !(o.receipt.token && (o.receipt.keyring || o.receipt.publicKey));
+  if (!receiptOk) shortfalls.unshift('receipt: the decision receipt did not verify');
+
+  let state = STATE.AUTHORIZED_AND_COMMITTED;
+  if (!receiptOk || (required.has(AUTHORITY.ISSUER_GRANT) && !grantOk)) state = STATE.UNAUTHORIZED;
+  else if (required.has(AUTHORITY.EXECUTOR_ATTESTATION) && !attOk) state = STATE.COMMIT_UNPROVEN;
+  else if (required.has(AUTHORITY.ONE_RUN_ROOT) && !authorities[AUTHORITY.ONE_RUN_ROOT].ok) {
+    state = STATE.ONE_RUN_UNPROVEN;
+  } else if (required.has(AUTHORITY.PROVIDER_WITNESS) && !authorities[AUTHORITY.PROVIDER_WITNESS].ok) {
+    state = STATE.RECORDED_UNWITNESSED;
+  } else if (!committed) state = STATE.NOT_COMMITTED;
+
+  return {
+    v: BINDING_V,
+    authorized_and_committed: state === STATE.AUTHORIZED_AND_COMMITTED,
+    state,
+    authorities,
+    shortfalls,
+    /** True when `receipt.verified` was taken on the caller's word rather than established here. */
+    receipt_caller_asserted: receiptAsserted,
+    // Said out loud so a caller cannot read success as more than it is.
+    does_not_prove: [
+      'that the executor told the truth about its own run — the evidence root closes third-party '
+      + 'splicing, not an executor misreporting itself',
+      'that a provider merged anything; `provider_witness` is an unsigned readback unless a caller '
+      + 'states otherwise',
+      'that the grant and the attestation agree about target, operation, tenant, executor, adapter, '
+      + 'audience or policy — cr.exec.attest.v1 is a closed field set that states none of them, so '
+      + 'those are UNCHECKED here rather than checked and equal (1464)',
+      'that the attestation commits the exact grant BYTES — the format carries no grant-token '
+      + 'digest, so the join is over the grant id, scope, receipt and state nonce',
+      ...(receiptAsserted
+        ? ['that the decision receipt verifies — `receipt.verified` was asserted by the caller and '
+          + 'not established here; this core is given no receipt token or keyring to check it with']
+        : []),
+    ],
+  };
+}
+
+module.exports = { verifiedExecutionBinding, STATE, AUTHORITY, BINDING_V, grantClaims, attestationClaims };

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,
+};