@coderifts/agent-guard 3.0.0 → 4.0.0

package/dist/cjs/freshness.js

@@ -0,0 +1,395 @@
+"use strict";
+/**
+ * Freshness-safe prior content — PURE comparison core (TOCTOU close for the fresh-snapshot conjunct).
+ *
+ * Settled decisions (do not relitigate):
+ *   1. Freshness is CONTENT IDENTITY, not time. No TTL. Byte identity of `before` vs gate-time resolve.
+ *   2. The caller NAMES (artifact id); the gate RESOLVES prior content. A caller-supplied `before`
+ *      is a claim, not a measurement — no fallback ladder that relabels a guess as measured.
+ *   3. Four outcomes, never collapsed: TARGET_MUTATED | STALE_CONTEXT | TAMPERED | UNKNOWN_FRESHNESS.
+ *   4. STALE_CONTEXT fails closed by default; policy may opt out deliberately.
+ *   5. Tree hash is OPTIONAL in the binding. Without it, STALE_CONTEXT is skipped, TARGET_MUTATED
+ *      still runs, and the result SAYS the reduced level (never silently pretends full check ran).
+ *
+ * Merge-gate pattern generalized: recompute from current inputs; compare to what preflight bound;
+ * do not trust a claim about itself. Tree hash stays OUT of verdict_fingerprint and input_fingerprint
+ * (those preimages are frozen — their frozenness is what makes recompute meaningful).
+ *
+ * PURE: no I/O, no network, no Date.now(). Host supplies resolved content as inputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentByteIdentical = contentByteIdentical;
+exports.computePathSetTreeHash = computePathSetTreeHash;
+exports.assessFreshness = assessFreshness;
+exports.assessWriteStylePrior = assessWriteStylePrior;
+exports.freshnessAllowsEnforce = freshnessAllowsEnforce;
+exports.isWriteStyleCall = isWriteStyleCall;
+exports.artifactIdsForResolve = artifactIdsForResolve;
+exports.collectFreshnessCallContext = collectFreshnessCallContext;
+exports.buildFreshnessBasis = buildFreshnessBasis;
+const node_crypto_1 = require("node:crypto");
+// ── pure digests (tree hash OUT of frozen fingerprint preimages) ─────────────────────────────────
+function sha256hex(s) {
+    return (0, node_crypto_1.createHash)('sha256').update(s, 'utf8').digest('hex');
+}
+/** Byte identity of two content strings (freshness definition: not time, not TTL). */
+function contentByteIdentical(a, b) {
+    return a === b;
+}
+/**
+ * Optional path-set tree commitment. Additive only — never fold into input_fingerprint or
+ * verdict_fingerprint. Preimage: sorted path + sha256(content), then outer sha256.
+ * Missing content for a path is the caller's problem: pass only complete pairs.
+ */
+function computePathSetTreeHash(entries) {
+    const parts = entries
+        .slice()
+        .map((e) => ({ path: String(e.path), content: String(e.content) }))
+        .sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0))
+        .map((e) => `${e.path}\x1f${sha256hex(e.content)}`);
+    return `sha256:${sha256hex(parts.join('\x1e'))}`;
+}
+// ── assess ───────────────────────────────────────────────────────────────────────────────────────
+const MSG = {
+    FRESH_FULL: 'Prior content is fresh: gate-resolved before matches preflight (byte identity); tree commitment matches.',
+    FRESH_CONTRACT_ONLY: 'Prior content is fresh at contract level (byte identity of before). '
+        + 'Tree-hash check was not bound on this receipt — level is contract_only, not full.',
+    TARGET_MUTATED: 'TARGET_MUTATED: gate-resolved contract before differs from preflight (byte identity failed). '
+        + 'The contract itself changed under the bound artifact; re-preflight.',
+    STALE_CONTEXT: 'STALE_CONTEXT: repository path-set tree moved, but the contract before is byte-identical. '
+        + 'This is NOT tampering — neighbouring or formatting-only material changed while the analyzed '
+        + 'contract content did not. Default policy fails closed; set allowStaleContext to accept deliberately.',
+    TAMPERED: 'TAMPERED: contract before moved AND tree commitment moved. Both axes disagree with the preflight binding.',
+    UNKNOWN_BEFORE: 'UNKNOWN_FRESHNESS: artifact was named but current prior content is not measurable '
+        + '(gate could not resolve before at execution time). Not the same as a measured mismatch.',
+    UNKNOWN_TREE: 'UNKNOWN_FRESHNESS: tree hash was bound on the preflight, but current tree commitment is not measurable. '
+        + 'Not the same as STALE_CONTEXT (which requires a measured tree that differs).',
+};
+/**
+ * Assess freshness of prior content by recompute-and-compare (merge-gate pattern generalized).
+ *
+ * Pure. Does not read the filesystem; the host/adapter resolves artifact id → content and passes
+ * `resolvedBeforeNow` / optional tree hashes as inputs.
+ */
+function assessFreshness(input) {
+    const hasTreeBinding = typeof input.preflightTreeHash === 'string' && input.preflightTreeHash.length > 0;
+    const level = hasTreeBinding ? 'full' : 'contract_only';
+    // Current prior must be measurable.
+    if (input.resolvedBeforeNow === null || input.resolvedBeforeNow === undefined) {
+        return {
+            outcome: 'UNKNOWN_FRESHNESS',
+            level,
+            failClosed: true,
+            contractMatch: null,
+            treeMatch: hasTreeBinding ? null : null,
+            message: MSG.UNKNOWN_BEFORE,
+        };
+    }
+    const contractMatch = contentByteIdentical(String(input.preflightBefore), String(input.resolvedBeforeNow));
+    // Tree axis: only when bound (Decision 5).
+    let treeMatch = null;
+    if (hasTreeBinding) {
+        if (input.resolvedTreeHashNow === null || input.resolvedTreeHashNow === undefined) {
+            return {
+                outcome: 'UNKNOWN_FRESHNESS',
+                level: 'full',
+                failClosed: true,
+                contractMatch,
+                treeMatch: null,
+                message: MSG.UNKNOWN_TREE,
+            };
+        }
+        treeMatch = contentByteIdentical(String(input.preflightTreeHash), String(input.resolvedTreeHashNow));
+    }
+    // Four outcomes from the two axes (tree may be skipped).
+    if (!contractMatch && treeMatch === false) {
+        return {
+            outcome: 'TAMPERED',
+            level,
+            failClosed: true,
+            contractMatch,
+            treeMatch,
+            message: MSG.TAMPERED,
+        };
+    }
+    if (!contractMatch) {
+        return {
+            outcome: 'TARGET_MUTATED',
+            level,
+            failClosed: true,
+            contractMatch,
+            treeMatch,
+            message: MSG.TARGET_MUTATED,
+        };
+    }
+    if (contractMatch && treeMatch === false) {
+        const allow = input.allowStaleContext === true;
+        return {
+            outcome: 'STALE_CONTEXT',
+            level,
+            // Default closed; policy opt-out only for this outcome (Decision 4).
+            failClosed: !allow,
+            contractMatch,
+            treeMatch,
+            message: MSG.STALE_CONTEXT,
+        };
+    }
+    // contractMatch && (treeMatch === true || treeMatch === null)
+    return {
+        outcome: 'FRESH',
+        level,
+        failClosed: false,
+        contractMatch,
+        treeMatch,
+        message: level === 'full' ? MSG.FRESH_FULL : MSG.FRESH_CONTRACT_ONLY,
+    };
+}
+/**
+ * Write-style prior requirements (Decision 2).
+ * Caller must supply artifactId. claimedBefore is never accepted as measurement.
+ */
+function assessWriteStylePrior(input) {
+    const id = input.artifactId;
+    if (typeof id !== 'string' || id.trim().length === 0) {
+        // If they only offered a claimed before, still missing the identifier — and do not climb a ladder.
+        const claimed = typeof input.claimedBefore === 'string' && input.claimedBefore.length > 0;
+        return {
+            gateable: false,
+            reason: claimed ? 'CLAIMED_BEFORE_NOT_MEASUREMENT' : 'MISSING_ARTIFACT_ID',
+            claimedBeforeAcceptedAsMeasurement: false,
+            message: claimed
+                ? 'Write-style call supplied claimed before content without an artifact id. '
+                    + 'A caller-supplied before is a claim, not a measurement. '
+                    + 'Pass the artifact id from the preflight artifacts[] entry; the gate resolves prior content.'
+                : 'Write-style call is missing an artifact identifier. '
+                    + 'Pass the id from a prior preflight artifacts[] entry (path + new content alone is not gateable). '
+                    + 'The gate resolves prior content; do not invent a before.',
+        };
+    }
+    return {
+        gateable: true,
+        reason: 'ok',
+        claimedBeforeAcceptedAsMeasurement: false,
+        message: 'Artifact id present; gate may resolve prior content for freshness recompute.',
+    };
+}
+/**
+ * Convenience: whether enforced execution is allowed for this freshness result.
+ * Equivalent to !failClosed: FRESH always; STALE_CONTEXT only when the team opted out;
+ * TARGET_MUTATED / TAMPERED / UNKNOWN never.
+ */
+function freshnessAllowsEnforce(result) {
+    return result.failClosed === false;
+}
+/**
+ * Detect write-style: contract-relevant path present, but no both-side artifacts on the descriptor.
+ * (edits[]/old_string+new_string binders already lift both sides — those are not write-style.)
+ */
+function isWriteStyleCall(call) {
+    const arts = call.artifacts;
+    if (Array.isArray(arts) && arts.length > 0) {
+        const anyBoth = arts.some((a) => a
+            && typeof a.before === 'string'
+            && a.before.length > 0
+            && typeof a.after === 'string'
+            && a.after.length > 0);
+        if (anyBoth)
+            return false;
+    }
+    const args = call.arguments && typeof call.arguments === 'object'
+        ? call.arguments
+        : {};
+    const path = typeof args.path === 'string' && args.path.length > 0
+        ? args.path
+        : (Array.isArray(call.filesTouched) && typeof call.filesTouched[0] === 'string'
+            ? call.filesTouched[0]
+            : '');
+    if (!path)
+        return false;
+    // path + new content / contents without old_string both sides
+    const hasAfter = (typeof args.contents === 'string' && args.contents.length > 0)
+        || (typeof args.content === 'string' && args.content.length > 0)
+        || (typeof args.new_string === 'string' && args.new_string.length > 0);
+    const hasOld = typeof args.old_string === 'string' && args.old_string.length > 0;
+    if (hasAfter && !hasOld)
+        return true;
+    // path-only write-like with no artifacts
+    if (!Array.isArray(arts) || arts.length === 0) {
+        return hasAfter || typeof args.contents === 'string' || typeof args.content === 'string';
+    }
+    return false;
+}
+/** Artifact ids the runner should ask the host to resolve (from lifted artifacts or path-derived id). */
+function artifactIdsForResolve(call) {
+    const ids = [];
+    if (Array.isArray(call.artifacts)) {
+        for (const a of call.artifacts) {
+            if (a && typeof a.id === 'string' && a.id.trim())
+                ids.push(a.id);
+        }
+    }
+    if (ids.length > 0)
+        return [...new Set(ids)];
+    const args = call.arguments && typeof call.arguments === 'object'
+        ? call.arguments
+        : {};
+    if (typeof args.artifact_id === 'string' && args.artifact_id.trim())
+        return [args.artifact_id.trim()];
+    if (typeof args.artifactId === 'string' && args.artifactId.trim())
+        return [args.artifactId.trim()];
+    // path alone is not an id — host must pass artifact id from preflight; still list path-key for resolve attempts
+    if (typeof args.path === 'string' && args.path.trim()) {
+        // Prefer explicit id fields only; path is path, not artifact id (Decision 2).
+    }
+    return ids;
+}
+/**
+ * RUNNER-side collection. Invokes the host resolver (async I/O). Never call from pure assessFreshness.
+ * - no resolver → NOT_CONFIGURED (did not try)
+ * - resolver throws → DEGRADED (opted in, failed)
+ * - resolver returns empty/non-string for all ids → DEGRADED
+ * - otherwise ACTIVE with priorResolved map
+ */
+async function collectFreshnessCallContext(input) {
+    const resolver = input.resolvePriorContent;
+    if (typeof resolver !== 'function') {
+        return { wiring: 'NOT_CONFIGURED' };
+    }
+    const ids = artifactIdsForResolve(input.call);
+    const args = input.call.arguments && typeof input.call.arguments === 'object'
+        ? input.call.arguments
+        : {};
+    const path = typeof args.path === 'string' ? args.path : undefined;
+    // Resolver present but nothing to resolve on this call — still ACTIVE commitment for wiring state
+    // only if we attempted; for zero ids, we attempted zero calls → ACTIVE with empty map means
+    // "resolver is configured" but assessment may UNKNOWN. Distinguish: DEGRADED only on throw/empty return.
+    if (ids.length === 0) {
+        // Host opted in; no artifact id to resolve. Not NOT_CONFIGURED (we would have resolved if we could).
+        // Leave ACTIVE with empty priorResolved — assess path handles missing content.
+        return { wiring: 'ACTIVE', priorResolved: {} };
+    }
+    const priorResolved = {};
+    try {
+        for (const artifactId of ids) {
+            const raw = await resolver({
+                artifactId,
+                path,
+                toolName: input.call.toolName,
+            });
+            if (raw === null || raw === undefined) {
+                priorResolved[artifactId] = raw;
+                continue;
+            }
+            if (typeof raw !== 'string') {
+                return {
+                    wiring: 'DEGRADED',
+                    degrade: { reason: 'resolver_returned_non_string', detail: `artifactId=${artifactId}` },
+                    priorResolved,
+                };
+            }
+            if (raw.length === 0) {
+                priorResolved[artifactId] = raw;
+                continue;
+            }
+            priorResolved[artifactId] = raw;
+        }
+    }
+    catch (err) {
+        return {
+            wiring: 'DEGRADED',
+            degrade: {
+                reason: 'resolver_threw',
+                detail: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+    const values = ids.map((id) => priorResolved[id]);
+    const allEmpty = values.every((v) => v === null || v === undefined || v === '');
+    if (allEmpty) {
+        return {
+            wiring: 'DEGRADED',
+            degrade: { reason: 'resolver_returned_empty' },
+            priorResolved,
+        };
+    }
+    return { wiring: 'ACTIVE', priorResolved };
+}
+/**
+ * Build the per-call basis and optional enforce block reason from context + preflight artifacts.
+ * Pure once priorResolved is a value (no I/O).
+ */
+function buildFreshnessBasis(input) {
+    const require_freshness = input.requireFreshness === true;
+    const write_style = input.writeStyle === true;
+    const { ctx } = input;
+    if (ctx.wiring === 'NOT_CONFIGURED') {
+        const basis = {
+            wiring: 'NOT_CONFIGURED',
+            write_style,
+            require_freshness,
+        };
+        // Policy requires freshness on write → permission denied (API still opt-in for non-required).
+        if (write_style && require_freshness) {
+            return { basis, blockCause: 'FRESHNESS_REQUIRED' };
+        }
+        return { basis };
+    }
+    if (ctx.wiring === 'DEGRADED') {
+        const basis = {
+            wiring: 'DEGRADED',
+            write_style,
+            require_freshness,
+            degrade: ctx.degrade ?? { reason: 'resolver_returned_empty' },
+        };
+        // Opted in, then failed: never silently unprotected. Fail closed on write when required,
+        // and also when requireFreshness is false? Decision 1: permission fail when policy requires.
+        // Decision 2: DEGRADED must not drop to unprotected — for enforce path always block on DEGRADED
+        // for write-style, and for requireFreshness always block.
+        if (write_style || require_freshness) {
+            return { basis, blockCause: 'FRESHNESS_REQUIRED' };
+        }
+        return { basis };
+    }
+    // ACTIVE
+    const preflightMap = input.preflightBeforeById ?? {};
+    const ids = Object.keys(preflightMap);
+    // If we have preflight before sides, assess the first (or all — fail if any fails).
+    let assessment;
+    if (ids.length > 0) {
+        for (const id of ids) {
+            const resolved = ctx.priorResolved ? ctx.priorResolved[id] : undefined;
+            const one = assessFreshness({
+                preflightBefore: preflightMap[id],
+                resolvedBeforeNow: resolved,
+                preflightTreeHash: input.preflightTreeHash,
+                resolvedTreeHashNow: input.resolvedTreeHashNow,
+                allowStaleContext: input.allowStaleContext,
+            });
+            assessment = one;
+            if (one.failClosed)
+                break;
+        }
+    }
+    else if (write_style) {
+        // ACTIVE but no preflight before to compare — measurement incomplete.
+        assessment = assessFreshness({
+            preflightBefore: '',
+            resolvedBeforeNow: null,
+            allowStaleContext: input.allowStaleContext,
+        });
+    }
+    const basis = {
+        wiring: 'ACTIVE',
+        write_style,
+        require_freshness,
+        assessment,
+    };
+    if (assessment && assessment.failClosed) {
+        return { basis, blockCause: 'FRESHNESS_FAILED' };
+    }
+    if (write_style && require_freshness && !assessment) {
+        return { basis, blockCause: 'FRESHNESS_REQUIRED' };
+    }
+    return { basis };
+}
+//# sourceMappingURL=freshness.js.map

package/dist/cjs/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../../src/freshness.ts"],"names":[],"mappings":"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"}

package/dist/cjs/guard.d.ts

@@ -8,5 +8,11 @@
  * ALLOW/MONITOR; LKG is dormant in v1 (binding fields absent => UNUSABLE => closed). onEvent never throws.
  */
 import type { GuardConfig, GuardOutcome, ToolCallDescriptor, ExecuteFactory } from './types.js';
-export declare function guardToolCall<T>(call: ToolCallDescriptor, executeFactory: ExecuteFactory<T>, config: GuardConfig): Promise<GuardOutcome<T>>;
+import { type FreshnessCallContext } from './freshness.js';
+/**
+ * @param callContext  Runner-collected freshness values (optional). When omitted, wiring is
+ *   NOT_CONFIGURED — the pure path never invokes resolvePriorContent. The tool-registry runner
+ *   calls collectFreshnessCallContext and passes the result here.
+ */
+export declare function guardToolCall<T>(call: ToolCallDescriptor, executeFactory: ExecuteFactory<T>, config: GuardConfig, callContext?: FreshnessCallContext): Promise<GuardOutcome<T>>;
 //# sourceMappingURL=guard.d.ts.map

package/dist/cjs/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,WAAW,EAAE,YAAY,EACT,kBAAkB,EAAE,cAAc,EAEnD,MAAM,YAAY,CAAC;AAiLpB,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,kBAAkB,EACxB,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CA4L1B"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,WAAW,EAAE,YAAY,EACT,kBAAkB,EAAE,cAAc,EAEnD,MAAM,YAAY,CAAC;AAMpB,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AA8MxB;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,kBAAkB,EACxB,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,MAAM,EAAE,WAAW,EACnB,WAAW,CAAC,EAAE,oBAAoB,GACjC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAmP1B"}