@coderifts/agent-guard 15.0.0 → 16.0.0

package/dist/cjs/unguarded-mutation.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+/**
+ * 'fail-closed'  default — a mutating call with no verified receipt does not execute.
+ * 'advisory'     execute anyway, and warn every time. Deliberate, named, and loud.
+ */
+export type GuardedMutationPolicy = 'fail-closed' | 'advisory';
+export declare const ADVISORY_ENV_VAR = "CODERIFTS_ADVISORY";
+export interface UnguardedMutationDecision {
+    /** Refuse to execute. */
+    readonly stop: boolean;
+    /** Executing anyway under advisory — the caller MUST surface this; silence is the failure mode. */
+    readonly warn?: string;
+    /** Why, in terms of what is at risk. */
+    readonly detail?: string;
+    /** Which input produced the advisory outcome, so a report can say who chose it. */
+    readonly source?: 'config' | 'environment';
+}
+/**
+ * @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 declare function decideUnguardedMutation(mutating: boolean, policy: GuardedMutationPolicy | undefined, env: Record<string, string | undefined>): UnguardedMutationDecision;
+//# sourceMappingURL=unguarded-mutation.d.ts.map

package/dist/cjs/unguarded-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unguarded-mutation.d.ts","sourceRoot":"","sources":["../../src/unguarded-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,UAAU,CAAC;AAK/D,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD,MAAM,WAAW,yBAAyB;IACxC,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,mGAAmG;IACnG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;CAC5C;AAOD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,qBAAqB,GAAG,SAAS,EACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,yBAAyB,CAoC3B"}

package/dist/cjs/unguarded-mutation.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADVISORY_ENV_VAR = void 0;
+exports.decideUnguardedMutation = decideUnguardedMutation;
+/** The named opt-out. Compared against exactly these, so `CODERIFTS_ADVISORY=0` is not advisory. */
+const ADVISORY_TRUE = new Set(['1', 'true', 'yes', 'on']);
+exports.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.
+ */
+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[exports.ADVISORY_ENV_VAR] ?? '').toLowerCase())) {
+        return {
+            stop: false,
+            source: 'environment',
+            detail: RISK,
+            warn: `CodeRifts: ADVISORY — executing an unguarded mutating tool call because `
+                + `${exports.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 '
+            + `${exports.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/cjs/unguarded-mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unguarded-mutation.js","sourceRoot":"","sources":["../../src/unguarded-mutation.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;;;AAkCH,0DAwCC;AAlED,oGAAoG;AACpG,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAE7C,QAAA,gBAAgB,GAAG,oBAAoB,CAAC;AAarD,MAAM,IAAI,GACR,wFAAwF;MACtF,2FAA2F;MAC3F,oFAAoF,CAAC;AAEzF;;;;GAIG;AACH,SAAgB,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,wBAAgB,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,wBAAgB,qEAAqE;kBACxF,IAAI;SACT,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,IAAI;QACV,MAAM,EACJ,IAAI,GAAG,+EAA+E;cACpF,GAAG,wBAAgB,sEAAsE;cACzF,+DAA+D;KACpE,CAAC;AACJ,CAAC"}

package/dist/cjs/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/cjs/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 };