@coderifts/agent-guard 15.0.0 → 16.0.0

package/dist/esm/unguarded-mutation.js

@@ -0,0 +1,97 @@
+/**
+ * 1356 — the host is the FIRST gate in the inescapability order (host → model → registry → CI),
+ * and until now it was the only one of the four that let a mutating call through by default.
+ *
+ * ── WHAT WAS ALREADY FAIL-CLOSED, MEASURED 2026-09-04 ───────────────────────────────────────
+ *
+ * Three of the four cases in the brief were ALREADY blocked by default, and the flip must not be
+ * described as if it closed them:
+ *
+ *   contract call + NO receipt        UNAVAILABLE / RECEIPT_MISSING       guard.ts:981,1067
+ *   contract call + unknown key       UNAVAILABLE / RECEIPT_UNVERIFIED    guard.ts:813
+ *   contract call + STOP              BLOCK                               guard.ts:854
+ *
+ * `enforceable = receiptVerified && …` (guard.ts:981) is the invariant that does it: the guard
+ * never runs the factory as enforced without a bound receipt. `requireReceipt: 'fail-closed'`
+ * (1307) fires earlier on the same fact; it is not what stood between a stranger and execution.
+ *
+ * ── THE GAP THAT WAS REAL ───────────────────────────────────────────────────────────────────
+ *
+ * All three depend on the DETECTOR having triggered. The detector fires on contract artifacts —
+ * OpenAPI, GraphQL, protobuf, MCP manifests. A call it does not recognise takes the SKIPPED path
+ * (guard.ts:600) and executes with `preflighted:false, enforced:false`. Measured, by default:
+ *
+ *   Read   README.md                                  SKIPPED → executed   (correct)
+ *   Edit   src/app.py       old_string/new_string     SKIPPED → executed   ← mutation, unguarded
+ *   Write  deploy.sh        content: 'rm -rf /'       SKIPPED → executed   ← mutation, unguarded
+ *
+ * "Not a contract change" is a true statement about the ARTIFACT and it was being used as a
+ * decision about the ACTION. The host wrapped the tool, the guard saw the call, and the write
+ * happened anyway with nothing signed.
+ *
+ * ── THE FLIP ────────────────────────────────────────────────────────────────────────────────
+ *
+ * A mutating call that reaches the end of the guard with no verified receipt is BLOCKED by
+ * default. Advisory remains available and is now a NAMED choice — `CODERIFTS_ADVISORY=1`, or
+ * `requireGuardedMutation: 'advisory'` — and it WARNS every time. `verify_ssl=false` is the
+ * comparison: a real option, spelled out loud, never the silent default.
+ *
+ * ── WHAT THIS DELIBERATELY DOES NOT DO ──────────────────────────────────────────────────────
+ *
+ * It does not widen `isMutatingCall` (freshness.ts:433). That predicate is shared with the
+ * conditional-write policy (guard.ts:495), so widening it here would silently change a second,
+ * unrelated gate. The consequence is a MEASURED RESIDUAL, and it should be read as a limit of
+ * this change rather than a property of it: `Bash { command: 'kubectl apply -f prod.yaml' }` is
+ * NOT classified mutating — the predicate reads contents/content/new_string/old_string/patch/
+ * edits, and `command` is not among them. A shell command that mutates production still takes the
+ * SKIPPED path. Closing that needs the predicate widened WITH the conditional-write blast radius
+ * measured, which is a separate change.
+ *
+ * An explicit `requireGuardedMutation: 'fail-closed'` is NOT overridable by the environment. An
+ * escape hatch that can undo a decision the host wrote down is not an escape hatch, it is a
+ * bypass, and anyone who can set an environment variable would hold it.
+ */
+/** The named opt-out. Compared against exactly these, so `CODERIFTS_ADVISORY=0` is not advisory. */
+const ADVISORY_TRUE = new Set(['1', 'true', 'yes', 'on']);
+export const ADVISORY_ENV_VAR = 'CODERIFTS_ADVISORY';
+const RISK = 'A mutating tool call reached the guard with no verified receipt: the detector did not '
+    + 'recognise a contract artifact, so nothing was preflighted and nothing was signed. "Not a '
+    + 'contract change" describes the artifact, not the action — the write still happens.';
+/**
+ * @param mutating   isMutatingCall() over the REDACTED descriptor — never the raw one.
+ * @param policy     host configuration; undefined means the new default.
+ * @param env        process.env, injected so this stays a pure function and is testable.
+ */
+export function decideUnguardedMutation(mutating, policy, env) {
+    // Read tools are the whole reason this is gated on mutation rather than on "was it preflighted".
+    if (!mutating)
+        return { stop: false };
+    if (policy === 'advisory') {
+        return {
+            stop: false,
+            source: 'config',
+            detail: RISK,
+            warn: 'CodeRifts: ADVISORY — executing an unguarded mutating tool call. '
+                + 'requireGuardedMutation is set to \'advisory\', so the guard is reporting rather than '
+                + 'enforcing. ' + RISK,
+        };
+    }
+    // An explicit fail-closed outranks the environment. Checked BEFORE reading env on purpose.
+    if (policy !== 'fail-closed' && ADVISORY_TRUE.has(String(env[ADVISORY_ENV_VAR] ?? '').toLowerCase())) {
+        return {
+            stop: false,
+            source: 'environment',
+            detail: RISK,
+            warn: `CodeRifts: ADVISORY — executing an unguarded mutating tool call because `
+                + `${ADVISORY_ENV_VAR} is set. This is the documented opt-out and it is not the default. `
+                + RISK,
+        };
+    }
+    return {
+        stop: true,
+        detail: RISK + ' Blocked by default. To proceed without a receipt, choose it explicitly: set '
+            + `${ADVISORY_ENV_VAR}=1 or requireGuardedMutation: 'advisory'. To proceed WITH one, send `
+            + 'the change through preflight so there is something to verify.',
+    };
+}
+//# sourceMappingURL=unguarded-mutation.js.map

package/dist/esm/unguarded-mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unguarded-mutation.js","sourceRoot":"","sources":["../../src/unguarded-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAQH,oGAAoG;AACpG,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAE1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAarD,MAAM,IAAI,GACR,wFAAwF;MACtF,2FAA2F;MAC3F,oFAAoF,CAAC;AAEzF;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAiB,EACjB,MAAyC,EACzC,GAAuC;IAEvC,iGAAiG;IACjG,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAEtC,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,OAAO;YACL,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,IAAI;YACZ,IAAI,EACF,mEAAmE;kBACjE,uFAAuF;kBACvF,aAAa,GAAG,IAAI;SACzB,CAAC;IACJ,CAAC;IAED,2FAA2F;IAC3F,IAAI,MAAM,KAAK,aAAa,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACrG,OAAO;YACL,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,IAAI;YACZ,IAAI,EACF,0EAA0E;kBACxE,GAAG,gBAAgB,qEAAqE;kBACxF,IAAI;SACT,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,IAAI;QACV,MAAM,EACJ,IAAI,GAAG,+EAA+E;cACpF,GAAG,gBAAgB,sEAAsE;cACzF,+DAA+D;KACpE,CAAC;AACJ,CAAC"}

package/dist/esm/vendor/VENDOR.sha256

@@ -0,0 +1,13 @@
+# Vendored verify core — the OFFLINE receipt verifier (1307).
+#
+# 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:
+# contract-gate, k8s-admission and gateway-verifier all verify offline against a pinned keyring.
+# 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.
+#
+# Do not edit these files here. Recopy from receipt-verifier and re-pin.
+# source: receipt-verifier e11d3f5d9f5444d8b2a07428c922d2040f4819ce
+
+verify.js  363e52c72ec4b913e1f3edc8e2029848feaeacb1efa6c07960fe5e5f195c23b3
+arity.js  721fcac58b960b5e2aa1af91edb6cfc87ebe828a6da73879967ef79a1ca474e8

package/dist/esm/vendor/arity.js

@@ -0,0 +1,53 @@
+'use strict';
+
+/**
+ * 1129 — unified (token, opts) with opts.ctx / opts.intended.
+ * 3-ary (token, ctx, opts) wrappers warn once and forward.
+ * 2-ary verifiers keep the 1128 throw on a third argument.
+ */
+const warned = new Set();
+
+function warnOnce(name) {
+  if (warned.has(name)) return;
+  warned.add(name);
+  const msg = `DEPRECATION: ${name}(token, ctx, opts) is deprecated; use ${name}(token, { ctx, intended }). This warning is emitted once.`;
+  if (typeof process !== 'undefined' && typeof process.emitWarning === 'function') {
+    process.emitWarning(msg, 'DeprecationWarning');
+  } else {
+    console.warn(msg);
+  }
+}
+
+function throw1128(name, n, consequence) {
+  throw new Error(
+    `${name}(token, opts) — pass intended via opts.intended. `
+    + `Received ${n} arguments; the third would be ignored and the cross-check `
+    + `would silently not run, grading a mismatched artifact ${consequence}.`,
+  );
+}
+
+function looksUnified(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  // perSlot is the bundle-dispatch unified shape: verifyBundle(bundle, { ctx, perSlot }).
+  // Without it, `{ perSlot }` was treated as a bare ctx and opts.perSlot vanished.
+  return obj.ctx != null || obj.intended != null || obj.envelope != null || obj.perSlot != null;
+}
+
+function split3ary(name, nArgs, second, third) {
+  if (nArgs > 3) throw1128(name, nArgs, 'VALID');
+  if (nArgs === 3) {
+    warnOnce(name);
+    return { ctx: second || {}, opts: third && typeof third === 'object' ? third : {} };
+  }
+  const o = second && typeof second === 'object' ? second : {};
+  if (looksUnified(o)) {
+    return { ctx: o.ctx || {}, opts: o };
+  }
+  return { ctx: o, opts: {} };
+}
+
+function _resetWarnedForTest() {
+  warned.clear();
+}
+
+module.exports = { warnOnce, throw1128, split3ary, looksUnified, _resetWarnedForTest };

package/dist/esm/vendor/verify.js

@@ -0,0 +1,454 @@
+'use strict';
+
+/*
+ * CodeRifts chain-receipt verifier — PURE LIBRARY. Node >= 20, zero dependencies (node:crypto only).
+ *
+ * Verify the receipt yourself — offline, no live CodeRifts API call needed.
+ * The reference format is frozen in ./RECEIPT_FORMAT.md.
+ *
+ * THE SPLIT (1282-A'). This file used to be both the library and the command. The command half
+ * carried the parts a library must not have: a shebang, a `require.main` block, argument parsing,
+ * and `fetchKeyInfo` — a network call whose LEGACY single-key branch returns a key document with
+ * no status field, so a receipt signed by a key that was later revoked verified as current. Four
+ * repositories vendor this file as `src/verify.js`; every one of them was carrying that command,
+ * and none of them could ever run it.
+ *
+ * The command now lives in ./cli.js. `node cli.js <receipt> …` is the same CLI it always was.
+ * Library behaviour is BYTE-IDENTICAL: the cross-language corpus and the envelope-step vectors
+ * pass unmodified, which is the proof that this was a move and not a rewrite.
+ *
+ * WHAT STAYED, and why it is not an inconsistency: `loadKeyring` reads a registry from a URL **or
+ * a local file**, and three of the four vendoring repos call it with a FILE path — it is part of
+ * the library surface they depend on. `fetchKeyInfo` has no file branch and no consumer outside
+ * the command, so it left.
+ *
+ * CLI usage now:
+ *   node cli.js <receipt> [--key pub.pem | --keys <url|file>] [--kid <kid>] [--fetch <url>]
+ *   node cli.js --chain receipts.txt [--key pub.pem | --keys <url|file>] [--kid <kid>] [--fetch <url>]
+ *
+ * Key discovery: with no --key/--keys, keys are fetched from
+ *   https://app.coderifts.com/.well-known/coderifts-keys.json  (override with --fetch <url>).
+ * The fetch-and-resolve path accepts BOTH the registry array (active + retired)
+ * and the legacy single-key body from /api/v1/attestation/public-key.
+ * --keys resolves each receipt's key by kid from a registry
+ *   ({ keys: [{ kid, public_key_pem, status, valid_from, retired_at }] }); accepts a URL or file.
+ *
+ * Output: JSON { valid, reason?, payload?, chain? } to stdout.
+ * Exit codes: 0 valid, 1 invalid, 2 usage error.
+ *
+ * Verification order (matches the reference taxonomy exactly):
+ *   structure -> json -> kid -> signature
+ * Reasons: malformed_structure | bad_json | unknown_kid | signature_error | signature_mismatch
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const { split3ary } = require('./arity');
+
+const DEFAULT_FETCH_URL = 'https://app.coderifts.com/.well-known/coderifts-keys.json';
+const SIGNING_PREFIX = 'crchain.v1';
+const MAX_SUPPORTED_V = 4;
+/** ID104 — verification expiry leeway (ms). `exp + leeway < now` → VERIFIED_EXPIRED. */
+const CLOCK_SKEW_LEEWAY_MS = 30_000;
+
+/**
+ * 0s grace only when context DECLARES destructive AND production.
+ * Public verifier has `--environment` / envelope.environment; no `destructive`
+ * / `operation_class` field — never guess from operation labels.
+ */
+function expiryLeewayMs(_context) {
+  return CLOCK_SKEW_LEEWAY_MS;
+}
+
+function isExpiredAt(expiresAtMs, nowMs, context) {
+  if (!Number.isFinite(expiresAtMs) || !Number.isFinite(nowMs)) return false;
+  return (expiresAtMs + expiryLeewayMs(context)) < nowMs;
+}
+
+// Signed fields per the max version — the anti-downgrade delimiter guard rejects any that contain '|'.
+const SIGNED_FIELDS = ['kid', 'fp', 'prev', 'caller', 'ts', 'reg', 'ir', 'expires_at', 'bh'];
+
+function sha256hex(str) {
+  return crypto.createHash('sha256').update(String(str), 'utf8').digest('hex');
+}
+
+/**
+ * RFC 8785 (JCS) canonical JSON for our data domain — MUST match the issuer's src/canonical-json.js
+ * and verify.py's canonical_json byte-for-byte (ASCII keys, JSON.stringify scalars, sorted keys, no
+ * whitespace, reject NaN/Infinity/undefined). Used to recompute decision_body_hash from --envelope.
+ */
+function canonicalJson(value) {
+  if (value === null) return 'null';
+  const t = typeof value;
+  if (t === 'boolean' || t === 'string') return JSON.stringify(value);
+  if (t === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError('canonicalJson: non-finite number');
+    return JSON.stringify(value);
+  }
+  if (t === 'undefined') throw new TypeError('canonicalJson: undefined');
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (t === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  }
+  throw new TypeError(`canonicalJson: unsupported type ${t}`);
+}
+
+/**
+ * Reconstruct the exact signed bytes from a parsed receipt body.
+ *   v1 (v absent or 1): the base string.
+ *   v2 (v === 2):       base + '|' + reg.
+ *   v3 (v === 3):       base + '|' + reg + '|' + ir.
+ *   v4 (v === 4):       base + '|' + reg + '|' + ir + '|' + expires_at + '|' + bh.
+ * Field order matches the CodeRifts issuer exactly (chain-attestation.js signingInputV4).
+ * This string must be byte-identical to the Python implementation.
+ */
+function reconstructSignedInput(payload) {
+  const base = `${SIGNING_PREFIX}|${payload.kid}|${payload.fp}|${payload.prev}|${payload.caller}|${payload.ts}`;
+  if (payload.v === 4) return `${base}|${payload.reg}|${payload.ir}|${payload.expires_at}|${payload.bh}`;
+  if (payload.v === 3) return `${base}|${payload.reg}|${payload.ir}`;
+  if (payload.v === 2) return `${base}|${payload.reg}`;
+  return base;
+}
+
+/**
+ * Resolve the verification key for a parsed payload.
+ * Two modes:
+ *   - keyring (from --keys): pick the entry whose kid matches payload.kid; an
+ *     unlisted kid resolves to null (=> unknown_kid). A retired key still verifies
+ *     so receipts issued before a rotation stay checkable.
+ *   - single key (default): the one loaded key, gated by expectedKid when known.
+ * Returns a KeyObject, or null when the kid is not accepted.
+ */
+/**
+ * 1306(a) — accept the SERVED registry shape, not only a Map.
+ *
+ * MEASURED black-box 2026-09-02. `https://app.coderifts.com/.well-known/coderifts-keys.json`
+ * serves `{keys:[{kid, public_key_pem, status, ...}]}`. Passing that document straight into
+ * `verifyReceipt(token, {ctx:{keyring}})` threw `TypeError: ctx.keyring.get is not a function` —
+ * the library path rejected the exact bytes this project publishes for it, while the CLI's
+ * `--keys <url>` worked because it converts first.
+ *
+ * The fix is here rather than in a caller: every consumer that fetches the public registry would
+ * otherwise have to know to convert, and the ones that do not find out with a TypeError rather
+ * than a verdict. `expectedKid` is a separate trap on the same path and is NOT papered over —
+ * `{keyring}` with no `expectedKid` still resolves to null by design (see resolveEntry), because
+ * silently defaulting a kid gate is a different and worse behaviour than a clear TypeError.
+ */
+function coerceKeyring(k, source) {
+  if (!k) return k;
+  if (typeof k.get === 'function') return k;                 // already a Map
+  if (Array.isArray(k.keys) || Array.isArray(k)) {
+    return keyringFromDocument(Array.isArray(k) ? { keys: k } : k, source || 'ctx.keyring');
+  }
+  return k;
+}
+
+function resolveEntry(ctx, payload) {
+  if (ctx.keyring) {
+    const entry = ctx.keyring.get(payload.kid);
+    if (!entry) return null;
+    if (ctx.expectedKid !== null && payload.kid !== ctx.expectedKid) return null;
+    return entry; // { publicKey, status, retired_at }
+  }
+  if (ctx.expectedKid !== null && payload.kid !== ctx.expectedKid) return null;
+  return { publicKey: ctx.publicKey, status: null, retired_at: null, revoked_at: null, compromised_at: null };
+}
+
+/**
+ * Derive the 12-status taxonomy verdict for an already-signature-valid receipt.
+ *   RETIRED_KEY_VALID_AT_ISSUE — retired key, receipt ts predates retired_at (else INVALID_SIGNATURE).
+ *   UNSUPPORTED_VERSION        — payload.v beyond MAX_SUPPORTED_V.
+ *   VERIFIED_EXPIRED           — v4 receipt whose signed expires_at + 30s leeway is in the past.
+ *   VERIFIED_WRONG_AUDIENCE / _WRONG_ENVIRONMENT — dormant: only when --envelope carries the field
+ *                                AND a check input (--audience/--environment) is supplied.
+ *   VERIFIED_SUPERSEDED / _SCOPE_MISMATCH — dormant: no check input defined this round.
+ *   VERIFIED_CURRENT           — otherwise.
+ */
+function deriveStatus(payload, entry, opts) {
+  if (typeof payload.v === 'number' && payload.v > MAX_SUPPORTED_V) return 'UNSUPPORTED_VERSION';
+  // FAIL CLOSED ON A STATUS WE DO NOT UNDERSTAND.
+  //
+  // MEASURED 2026-08-26: a registry entry with status "revoked" returned
+  // { valid: true, status: "VERIFIED_CURRENT" } here — the status was read for 'retired' and
+  // otherwise ignored, so anything else fell through to the healthy path. An operator who marked a
+  // stolen key revoked would have believed they had acted while this verifier kept accepting it.
+  // The app kernel and verify-attest/verify-toolset already reject an unknown status; these two
+  // did not, so the fleet disagreed about the same registry.
+  //
+  // This is a bug fix, not revocation: the revocation RULE (compromised_at, REVOKED_KEY /
+  // REVOKED_KEY_UNDECIDABLE) is a separate, larger change across eight verifiers. What lands here
+  // is only the direction of the unknown case. Safe by measurement: the live registry publishes
+  // 'active' only, so no real consumer changes behaviour.
+  const KNOWN_STATUSES = new Set(['active', 'retired', 'revoked', null, undefined]);
+  if (!KNOWN_STATUSES.has(entry.status)) {
+    return 'UNKNOWN_KEY_STATUS';
+  }
+  // 1079 B — OPTIONAL timestamps, additive. Absent both fields → this function continues
+  // exactly as before. Signing time is payload.ts (receipts have no iat).
+  // revoked_at = compromise: EVERY receipt under the key is invalid, including those
+  // whose ts predates revoked_at (the attacker chooses ts).
+  // retired_at = planned rotation: ts < retired_at stays on the existing path;
+  // ts >= retired_at is KEY_RETIRED_AFTER_SIGNING.
+  if (typeof entry.revoked_at === 'string' && entry.revoked_at.length > 0) {
+    return 'KEY_REVOKED';
+  }
+  if (typeof entry.retired_at === 'string' && entry.retired_at.length > 0 && payload.ts) {
+    const issued = Date.parse(payload.ts);
+    const retired = Date.parse(entry.retired_at);
+    if (Number.isFinite(issued) && Number.isFinite(retired) && issued >= retired) {
+      return 'KEY_RETIRED_AFTER_SIGNING';
+    }
+  }
+  // REVOKED — RECEIPT_FORMAT.md §7.1 (normative). The attacker chooses ts, so no timestamp may
+  // rehabilitate a revoked key's signature: BOTH outcomes are valid:false. UNDECIDABLE is not a
+  // softer valid; it reports that we cannot tell a legitimate pre-compromise receipt from a
+  // backdated forgery. A missing compromised_at means the whole key history is suspect.
+  if (entry.status === 'revoked') {
+    const at = entry.compromised_at;
+    if (typeof at !== 'string' || at.length === 0) return 'REVOKED_KEY_UNDECIDABLE';
+    const boundary = Date.parse(at);
+    const issued = Date.parse(payload.ts);
+    if (!Number.isFinite(boundary) || !Number.isFinite(issued)) return 'REVOKED_KEY_UNDECIDABLE';
+    return issued >= boundary ? 'REVOKED_KEY' : 'REVOKED_KEY_UNDECIDABLE';
+  }
+  if (entry.status === 'retired') {
+    if (entry.retired_at && payload.ts
+      && Date.parse(payload.ts) < Date.parse(entry.retired_at)) {
+      return 'RETIRED_KEY_VALID_AT_ISSUE';
+    }
+    return 'INVALID_SIGNATURE'; // signed by a key already retired at issue -> reject
+  }
+  const now = opts.now != null ? opts.now : Date.now();
+  if (payload.v === 4 && typeof payload.expires_at === 'string') {
+    const exp = Date.parse(payload.expires_at);
+    const context = opts.envelope || { environment: opts.expectedEnvironment };
+    if (isExpiredAt(exp, now, context)) return 'VERIFIED_EXPIRED';
+  }
+  if (opts.envelope) {
+    const env = opts.envelope;
+    if (opts.expectedAudience != null && env.audience != null && env.audience !== opts.expectedAudience) {
+      return 'VERIFIED_WRONG_AUDIENCE';
+    }
+    if (opts.expectedEnvironment != null && env.environment != null && env.environment !== opts.expectedEnvironment) {
+      return 'VERIFIED_WRONG_ENVIRONMENT';
+    }
+  }
+  return 'VERIFIED_CURRENT';
+}
+
+/**
+ * Verify a single receipt token against a public key (or keyring) + expected kid.
+ * @param {string} token
+ * @param {{ publicKey?: import('crypto').KeyObject, keyring?: Map<string,{publicKey:import('crypto').KeyObject}>, expectedKid: (string|null) }} ctx
+ * @returns {{ valid: boolean, reason?: string, payload?: object }}
+ */
+function verifyReceiptInner(token, ctx, opts = {}) {
+  // 1. structure
+  if (typeof token !== 'string' || token.length === 0) {
+    return { valid: false, status: 'MALFORMED', reason: 'malformed_structure' };
+  }
+  const segments = token.split('.');
+  if (segments.length !== 2 || segments.some((s) => !s)) {
+    return { valid: false, status: 'MALFORMED', reason: 'malformed_structure' };
+  }
+
+  // 2. json
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(segments[0], 'base64url').toString('utf8'));
+  } catch (_) {
+    return { valid: false, status: 'MALFORMED', reason: 'bad_json' };
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { valid: false, status: 'MALFORMED', reason: 'bad_json' };
+  }
+
+  // 3. kid -- resolve the entry by kid (keyring) or gate the single key by expectedKid.
+  // 1306(a): a served `{keys:[...]}` document is accepted here as well as a Map.
+  const entry = resolveEntry(
+    ctx.keyring ? { ...ctx, keyring: coerceKeyring(ctx.keyring, 'ctx.keyring') } : ctx,
+    payload,
+  );
+  if (!entry) {
+    return { valid: false, status: 'UNKNOWN_KEY', reason: 'unknown_kid', payload };
+  }
+
+  // 4. signature (raw Ed25519 over the reconstructed UTF-8 bytes)
+  const sig = Buffer.from(segments[1], 'base64url');
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(reconstructSignedInput(payload), 'utf8'), entry.publicKey, sig);
+  } catch (_) {
+    return { valid: false, status: 'INVALID_SIGNATURE', reason: 'signature_error', payload };
+  }
+  if (!ok) return { valid: false, status: 'INVALID_SIGNATURE', reason: 'signature_mismatch', payload };
+
+  // 5. anti-downgrade delimiter guard — a signed field containing '|' could re-split into a lower
+  // version whose reconstructed bytes collide with these. Legitimate fields never contain '|'.
+  for (const k of SIGNED_FIELDS) {
+    if (typeof payload[k] === 'string' && payload[k].includes('|')) {
+      return { valid: false, status: 'INVALID_SIGNATURE', reason: 'delimiter_in_field', payload };
+    }
+  }
+
+  // 6. envelope binding (v4): a supplied envelope's canonical body_hash MUST equal payload.bh.
+  if (opts.envelope && payload.v === 4) {
+    const rest = { ...opts.envelope };
+    delete rest.receipt;
+    delete rest.decision_body_hash;
+    const recomputed = 'sha256:' + sha256hex(canonicalJson(rest));
+    if (recomputed !== payload.bh) {
+      return { valid: false, status: 'INVALID_SIGNATURE', reason: 'body_hash_mismatch', payload };
+    }
+  }
+
+  // 7. taxonomy status (freshness / retirement / dormant field checks).
+  const status = deriveStatus(payload, entry, opts);
+  if (status === 'KEY_REVOKED') {
+    return { valid: false, status, reason: 'KEY_REVOKED', payload };
+  }
+  if (status === 'KEY_RETIRED_AFTER_SIGNING') {
+    return { valid: false, status, reason: 'KEY_RETIRED_AFTER_SIGNING', payload };
+  }
+  if (status === 'INVALID_SIGNATURE') {
+    return { valid: false, status, reason: 'retired_key_after_issue', payload };
+  }
+  const valid = status === 'VERIFIED_CURRENT' || status === 'RETIRED_KEY_VALID_AT_ISSUE';
+  // UNKNOWN_KEY_STATUS is deliberately absent from the valid set — see deriveStatus.
+  return { valid, status, payload };
+}
+
+/**
+ * Verify a chain of tokens (oldest first): every signature valid AND every non-genesis
+ * link's prev == 'sha256:' + sha256hex(previous token string).
+ */
+function verifyChainInner(tokens, ctx, opts = {}) {
+  const links = [];
+  let allValid = true;
+  let first = null;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const res = verifyReceiptInner(token, ctx, opts);
+    const link = { index: i, signature_valid: res.valid };
+    if (!res.valid) link.reason = res.reason;
+    const prev = res.payload ? res.payload.prev : undefined;
+    if (res.payload) link.prev = prev;
+
+    if (i === 0) {
+      first = prev === 'null' ? 'genesis' : 'continuation';
+      link.role = first;
+      // A genesis needs prev === 'null'; a continuation links to a token we do not hold.
+      link.prev_ok = prev === 'null' ? true : null;
+    } else {
+      const expected = `sha256:${sha256hex(tokens[i - 1])}`;
+      link.expected_prev = expected;
+      link.prev_ok = prev === expected;
+      if (!link.prev_ok) allValid = false;
+    }
+
+    if (!res.valid) allValid = false;
+    links.push(link);
+  }
+
+  return { valid: allValid, chain: { length: tokens.length, first, links } };
+}
+
+// ---------------------------------------------------------------------------
+// Key loading
+// ---------------------------------------------------------------------------
+
+function keyFromPem(pem) {
+  return crypto.createPublicKey(pem);
+}
+
+/**
+ * Build a kid -> key map from a registry document
+ * ({ keys: [{ kid, public_key_pem, status, valid_from, retired_at }] }).
+ * Returns null when `keys` is missing/empty so the caller can try the legacy
+ * single-key body. --keys still requires a non-empty keys[] (throws).
+ */
+function keyringFromDocument(doc, source) {
+  const keys = doc && Array.isArray(doc.keys) ? doc.keys : null;
+  if (!keys || keys.length === 0) return null;
+  const keyring = new Map();
+  for (const k of keys) {
+    if (!k || !k.kid || !k.public_key_pem) throw new Error(`registry entry missing kid/public_key_pem in ${source}`);
+    // compromised_at MUST be carried through: deriveStatus reads it for the revoked rule
+    // (RECEIPT_FORMAT.md 7.1). Dropping it here made the rule inert — every revoked key
+    // returned UNDECIDABLE regardless of ts, which looks implemented and decides nothing.
+    keyring.set(k.kid, {
+      publicKey: keyFromPem(k.public_key_pem),
+      status: k.status || null,
+      retired_at: k.retired_at || null,
+      revoked_at: k.revoked_at || null,
+      compromised_at: k.compromised_at || null,
+    });
+  }
+  return keyring;
+}
+
+function pickActiveFromKeyring(keyring) {
+  for (const [kid, entry] of keyring) {
+    if (entry.status === 'active') return { kid, entry };
+  }
+  const first = keyring.entries().next().value;
+  return first ? { kid: first[0], entry: first[1] } : null;
+}
+
+/**
+ * Build a kid -> key map from a CodeRifts key registry
+ * ({ keys: [{ kid, public_key_pem, status, valid_from, retired_at }] }). A --keys source may be
+ * an http(s) URL or a local file path. Both active and retired keys are loaded.
+ */
+async function loadKeyring(source) {
+  let text;
+  if (/^https?:\/\//i.test(source)) {
+    const res = await fetch(source, { headers: { Accept: 'application/json' } });
+    if (!res.ok) throw new Error(`fetch ${source} -> HTTP ${res.status}`);
+    text = await res.text();
+  } else {
+    text = fs.readFileSync(source, 'utf8');
+  }
+  const doc = JSON.parse(text);
+  const keyring = keyringFromDocument(doc, source);
+  if (!keyring) throw new Error(`no keys[] in registry ${source}`);
+  return keyring;
+}
+
+function verifyReceipt(token, second, third) {
+  const { ctx, opts } = split3ary('verifyReceipt', arguments.length, second, third);
+  return verifyReceiptInner(token, ctx, opts);
+}
+
+function verifyChain(tokens, second, third) {
+  const { ctx, opts } = split3ary('verifyChain', arguments.length, second, third);
+  return verifyChainInner(tokens, ctx, opts);
+}
+
+// Reusable API — require('./verify') imports the pure verify logic WITHOUT running the CLI. The
+// GitHub Action + other embedders use these directly (verifyReceipt/verifyChain/deriveStatus/…);
+// the receipt format + taxonomy are frozen in RECEIPT_FORMAT.md.
+module.exports = {
+  verifyReceipt,
+  verifyChain,
+  deriveStatus,
+  resolveEntry,
+  reconstructSignedInput,
+  canonicalJson,
+  loadKeyring,
+  keyFromPem,
+  keyringFromDocument,
+  // Pure keyring helper. Exported for the command (cli.js fetchKeyInfo) after the split —
+  // it takes a keyring and returns the active entry; it performs no I/O.
+  pickActiveFromKeyring,
+  sha256hex,
+  DEFAULT_FETCH_URL,
+  SIGNING_PREFIX,
+  MAX_SUPPORTED_V,
+  SIGNED_FIELDS,
+  CLOCK_SKEW_LEEWAY_MS,
+  expiryLeewayMs,
+  isExpiredAt,
+};

package/dist/esm/with-coderifts.d.ts

@@ -418,6 +418,27 @@ export type ReceiptThreadHandle = {
      */
     lastSkipReason: () => ReceiptCursorSkipReason | null;
 };
+/**
+ * The unversioned spelling still resolves to `_V1`, and always will — see the type doc above:
+ * re-pointing it at a future `_V2` would silently move every existing caller, which is the
+ * migration this design refuses.
+ *
+ * SO THIS NOTICE PROMISES NOTHING. It does not say deprecated, it does not name a removal
+ * version, and it must not: the alias is permanent by design, and a notice announcing a removal
+ * that will never happen is a false statement shipped to every consumer on the alias. What it
+ * does is point at the name that carries the version, so a caller who wants the guarantee the
+ * suffix gives can ask for it by name.
+ *
+ * ONCE PER PROCESS, and the flag is module-level for the same reason `policy.ts` uses one: a
+ * per-call notice on a construction path that a host may run per request is noise, and noise is
+ * how a line stops being read.
+ *
+ * The wire value is untouched. `GUARD_PROFILE_WIRE_VALUE` stays the suffix-less string that four
+ * downstream modules compare against; this observes the spelling, it does not rewrite it.
+ */
+export declare const UNVERSIONED_PROFILE_NOTICE = "ENFORCING_STRICT is the unversioned spelling of ENFORCING_STRICT_V1; prefer the versioned name.";
+/** Test-only reset. Exported so a test can assert the once-per-process behaviour more than once. */
+export declare function _resetUnversionedProfileNoticeForTest(): void;
 /**
  * Wrap guardToolRegistry with a mandatory operation and a separately-computed composition assurance.
  * Fails at CONSTRUCTION (never at first tool call) for a missing client, a missing/empty operation, an