@integraledger/agent-guard 0.9.0

package/dist/transact.d.ts

@@ -0,0 +1,24 @@
+import type { GateDecision } from "./decision.js";
+import { type GatePorts } from "./evaluate.js";
+import type { BuyerPolicy } from "./policy.js";
+import type { GateProposal } from "./proposal.js";
+/** A signer the gate invokes ONLY on Proceed. The gate binds the atrHash it verified; the signer signs THROUGH
+ *  an authority artifact (the grant/acceptance) by its own contract, never a bare hash. On Decline/Escalate the
+ *  signer is never called — the key is structurally gated (the "before any signing key is invoked" guarantee). */
+export interface GuardedSigner {
+    sign(verifiedAtrHash: `0x${string}`): Promise<{
+        readonly signature: `0x${string}`;
+    }>;
+}
+export type TransactResult = {
+    readonly kind: "signed";
+    readonly signature: `0x${string}`;
+    readonly atrHash: `0x${string}`;
+} | {
+    readonly kind: "halted";
+    readonly decision: GateDecision;
+};
+/** Verify-before-sign as a type + a runtime gate: evaluate the proposal, and invoke the signing key ONLY when
+ *  the decision is Proceed. On Decline/Escalate the signer is never reached (LCP §5.3), by construction. */
+export declare function transact(proposal: GateProposal, policy: BuyerPolicy, ports: GatePorts, signer: GuardedSigner): Promise<TransactResult>;
+//# sourceMappingURL=transact.d.ts.map

package/dist/transact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transact.d.ts","sourceRoot":"","sources":["../src/transact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;kHAEkH;AAClH,MAAM,WAAW,aAAa;IAC5B,IAAI,CACF,eAAe,EAAE,KAAK,MAAM,EAAE,GAC7B,OAAO,CAAC;QAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACnD;AACD,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;CACjC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAAC;AAEjE;4GAC4G;AAC5G,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,cAAc,CAAC,CAKzB"}

package/dist/transact.js

@@ -0,0 +1,11 @@
+import { evaluate } from "./evaluate.js";
+/** Verify-before-sign as a type + a runtime gate: evaluate the proposal, and invoke the signing key ONLY when
+ *  the decision is Proceed. On Decline/Escalate the signer is never reached (LCP §5.3), by construction. */
+export async function transact(proposal, policy, ports, signer) {
+    const decision = await evaluate(proposal, policy, ports);
+    if (decision.kind !== "proceed")
+        return { kind: "halted", decision };
+    const { signature } = await signer.sign(proposal.advertisedAtrHash);
+    return { kind: "signed", signature, atrHash: proposal.advertisedAtrHash };
+}
+//# sourceMappingURL=transact.js.map

package/dist/transact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transact.js","sourceRoot":"","sources":["../src/transact.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAkB,MAAM,eAAe,CAAC;AAoBzD;4GAC4G;AAC5G,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAsB,EACtB,MAAmB,EACnB,KAAgB,EAChB,MAAqB;IAErB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACzD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACpE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,iBAAiB,EAAE,CAAC;AAC5E,CAAC"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@integraledger/agent-guard",
+  "version": "0.9.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IntegraLedger/integra-agent-guard.git",
+    "directory": "packages/agent-guard"
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@integraledger/lcp-authority": "^0.10.1",
+    "@integraledger/lcp-binding-core": "^0.10.1",
+    "@integraledger/lcp-discovery": "^0.10.1",
+    "@integraledger/lcp-evidence": "^0.10.1",
+    "@integraledger/lcp-kernel": "^0.10.1",
+    "@integraledger/lcp-placement-ack": "^0.10.1",
+    "@integraledger/lcp-placement-ap2": "^0.10.1",
+    "@integraledger/lcp-placements": "^0.10.1",
+    "@integraledger/lcp-verify": "^0.10.1"
+  },
+  "devDependencies": {
+    "@integraledger/lcp-authority": "0.10.1",
+    "@integraledger/lcp-binding-core": "0.10.1",
+    "@integraledger/lcp-discovery": "0.10.1",
+    "@integraledger/lcp-evidence": "0.10.1",
+    "@integraledger/lcp-kernel": "0.10.1",
+    "@integraledger/lcp-placement-ack": "0.10.1",
+    "@integraledger/lcp-placement-acp": "0.10.1",
+    "@integraledger/lcp-placement-ap2": "0.10.1",
+    "@integraledger/lcp-placements": "0.10.1",
+    "@integraledger/lcp-verify": "0.10.1",
+    "@types/node": "24.13.3",
+    "vitest": "4.1.10"
+  },
+  "license": "Apache-2.0",
+  "description": "Integra Agent Guard — the buyer-side verify-before-sign guard for agentic purchases. Fetches the terms a seller advertised, recomputes the fingerprint, and halts before any signing key is invoked if they disagree. Works against any seller.",
+  "keywords": [
+    "lcp",
+    "legal-context-protocol",
+    "agentic-commerce",
+    "ai-agent",
+    "x402",
+    "ap2",
+    "acp",
+    "verify-before-pay",
+    "buyer-protection",
+    "agent-guard"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "bugs": {
+    "url": "https://github.com/IntegraLedger/integra-agent-guard/issues"
+  },
+  "homepage": "https://github.com/IntegraLedger/integra-agent-guard/tree/main/packages/agent-guard#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/decision.ts

@@ -0,0 +1,54 @@
+import type { HaltClass } from "@integraledger/lcp-binding-core";
+export type StepStatus =
+  | "proved"
+  | "failed"
+  | "indeterminate"
+  | "not-attempted";
+export type Disposition = "proceed" | "decline" | "escalate";
+export type GateDecision =
+  | { readonly kind: "proceed" }
+  | {
+      readonly kind: "decline";
+      readonly haltClass: HaltClass;
+      readonly code: string;
+      readonly detail: string;
+    }
+  | {
+      readonly kind: "escalate";
+      readonly bytes: Uint8Array;
+      readonly hash: `0x${string}`;
+      readonly reason: string;
+    };
+
+/** The TOTAL map from a step's four-valued status onto a disposition. `failed` is ALWAYS decline (a policy
+ *  can never proceed past a failure). `indeterminate`/`not-attempted` are the buyer's STATED dispositions
+ *  (never silent defaults). The switch is exhaustive — the `never` default fails the build if StepStatus grows. */
+export function decideOutcome(
+  status: StepStatus,
+  gaps: {
+    readonly onIndeterminate: Disposition;
+    readonly onNotAttempted: Disposition;
+  },
+): Disposition {
+  switch (status) {
+    case "proved":
+      return "proceed";
+    case "failed":
+      return "decline";
+    case "indeterminate":
+      return gaps.onIndeterminate;
+    case "not-attempted":
+      return gaps.onNotAttempted;
+    default: {
+      const _exhaustive: never = status;
+      return _exhaustive;
+    }
+  }
+}
+
+/** Fold per-step dispositions into one: any decline ⇒ Decline-dominant; else any escalate ⇒ Escalate; else proceed. */
+export function foldDispositions(ds: readonly Disposition[]): Disposition {
+  if (ds.includes("decline")) return "decline";
+  if (ds.includes("escalate")) return "escalate";
+  return "proceed";
+}

package/src/evaluate.ts

@@ -0,0 +1,176 @@
+import type { HaltClass } from "@integraledger/lcp-binding-core";
+import {
+  type LegalContextJson,
+  parseLegalContextJson,
+} from "@integraledger/lcp-discovery";
+import { hashAtr } from "@integraledger/lcp-kernel";
+import type { GateDecision } from "./decision.js";
+import type { TermsFetcher } from "./fetch.js";
+import { recomputeAndCompare } from "./fingerprint.js";
+import type { Orc4Log } from "./log.js";
+import { type BuyerPolicy, evaluatePolicy } from "./policy.js";
+import type { GateProposal } from "./proposal.js";
+
+export interface GatePorts {
+  readonly fetcher: TermsFetcher;
+  readonly now: () => string;
+  readonly log?: Orc4Log;
+}
+
+/** The gate orchestration: fetch+retain (LCP §5.4) → level floor (LCP §4.2) → fingerprint HALT (LCP §5.3) → policy on the
+ *  TYPED envelope only (LCP §12.7) → coverage-gap disposition → assurance → Proceed. The signing key is NEVER
+ *  touched here — this returns a decision that `transact` enforces against the guarded signer. */
+export async function evaluate(
+  proposal: GateProposal,
+  policy: BuyerPolicy,
+  ports: GatePorts,
+): Promise<GateDecision> {
+  const at = ports.now();
+  const decline = (
+    haltClass: HaltClass,
+    code: string,
+    detail: string,
+  ): GateDecision => {
+    ports.log?.append({
+      timestamp: at,
+      decision: "decline",
+      haltClass,
+      code,
+      detail,
+      atrHash: proposal.advertisedAtrHash,
+      legalContextUrl: proposal.legalContextUrl,
+    });
+    return { kind: "decline", haltClass, code, detail };
+  };
+
+  // LCP §5.4: ALWAYS fetch + retain the terms as evidence, even at Level 1 (a policy decision, never a silent skip).
+  //
+  // The fetch is CAUGHT because a counterparty must not be able to make this function THROW. Every failure
+  // the shipped fetcher raises is counterparty-reachable — a 404 or a TLS error on a URL the seller chose, a
+  // body over the cap on a document the seller serves, a host the seller published that resolves to a private
+  // address and trips the SSRF guard. Each has to arrive as a value the buyer can act on: the ORC-4 log
+  // records the most common counterparty failure there is, the caller gets the `haltClass`/`code` pair every
+  // other refusal here is a value of, and the Decline taxonomy — the seam a seller's integration is measured
+  // against — names "your terms document did not serve".
+  //
+  // A throw would fail closed, since the signer is unreachable on any path that does not reach a Proceed. But
+  // failing closed is not the same as failing WELL, and this package's own SECURITY.md names that difference
+  // as a defect rather than as acceptable behaviour.
+  //
+  // `verification-failure`, not `policy-rejection`: no policy of the buyer's rejected anything. The terms
+  // could not be obtained, so the fingerprint could not be recomputed, so the guard cannot say the document
+  // is the one that was advertised — which is the same thing a mismatch says, arrived at one step earlier.
+  let fetched: Awaited<ReturnType<typeof ports.fetcher.fetch>>;
+  try {
+    fetched = await ports.fetcher.fetch(proposal.legalContextUrl);
+  } catch (cause) {
+    // The fetcher's own message names the cause precisely — the status, the cap, the resolved address that
+    // failed the unicast check — and it is the seller's defect, so it is carried through verbatim rather
+    // than flattened into "fetch failed". A buyer that cannot see WHICH failure it was cannot report it.
+    return decline(
+      "verification-failure",
+      "gate/terms-unfetchable",
+      `could not fetch the advertised terms at ${proposal.legalContextUrl}: ${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+  }
+
+  // LCP §4.2: the buyer's stated trust-level floor. Level 1 is a policy decision (requiredLevel), never a default.
+  if (proposal.level < policy.requiredLevel)
+    return decline(
+      "policy-rejection",
+      "gate/below-required-level",
+      `service level ${proposal.level} is below the buyer's required level ${policy.requiredLevel}`,
+    );
+
+  // Verify before sign (LCP §5.3): recompute the fingerprint over the fetched bytes vs the advertised atrHash — a mismatch HALTS before
+  // any signing key. Every GateProposal carries a validated advertisedAtrHash, so verification is ALWAYS run
+  // (verify-whenever-present; skipping a present, verifiable hash would be a silent fail-open).
+  const fp = await recomputeAndCompare(
+    fetched.bytes,
+    proposal.advertisedAtrHash,
+  );
+  if (fp.status === "failed")
+    return decline(
+      "verification-failure",
+      "gate/fingerprint-mismatch",
+      `recomputed fingerprint ${fp.recomputed} ≠ advertised ${fp.advertised} — HALTING before sign (LCP §5.3)`,
+    );
+
+  // The seller-assurance floor (IDN-3) is a counterparty-trust dimension INDEPENDENT of the terms FORMAT —
+  // it gates EVERY proceed path, so it is checked here, before the typed/coverage-gap branch. A buyer that
+  // tolerates non-machine-readable terms (onNotAttempted) must NOT thereby lose their assurance floor.
+  if (
+    policy.requiredAssurance !== "any" &&
+    proposal.sellerAssurance !== policy.requiredAssurance
+  )
+    return decline(
+      "policy-rejection",
+      "gate/assurance",
+      `seller assurance ${proposal.sellerAssurance} below required ${policy.requiredAssurance}`,
+    );
+
+  // Policy on the TYPED envelope only (never the prose bytes) — LCP §12.7. parseLegalContextJson takes a PARSED
+  // object and THROWS on a non-conformant record, so a non-machine-readable body is a CAUGHT coverage gap the
+  // buyer's STATED onNotAttempted disposition decides — never a silent proceed.
+  let typed: LegalContextJson | undefined;
+  try {
+    typed = parseLegalContextJson(
+      JSON.parse(new TextDecoder().decode(fetched.bytes)),
+    );
+  } catch {
+    typed = undefined;
+  }
+  if (typed === undefined) {
+    const disp = policy.onNotAttempted; // non-machine-readable record → coverage gap; buyer's STATED disposition
+    if (disp === "decline")
+      return decline(
+        "policy-rejection",
+        "gate/unparseable-terms",
+        "terms are not machine-readable legal-context JSON",
+      );
+    if (disp === "escalate")
+      return escalate(
+        fetched.bytes,
+        at,
+        "terms not machine-readable — escalating per policy",
+        ports,
+        proposal,
+      );
+    // disp === "proceed": a STATED election to proceed without a typed record (the policy's call, not a default).
+  } else {
+    const pr = evaluatePolicy(policy, typed, proposal.offer);
+    // A hard ATA-2 violation is a Decline (policy-rejection); the escalate lane is for coverage gaps, not forbidden terms.
+    if (!pr.ok) return decline("policy-rejection", pr.code, pr.detail);
+  }
+
+  ports.log?.append({
+    timestamp: at,
+    decision: "proceed",
+    code: "gate/proceed",
+    detail: "verified + in policy",
+    atrHash: proposal.advertisedAtrHash,
+    legalContextUrl: proposal.legalContextUrl,
+  });
+  return { kind: "proceed" };
+}
+
+/** Escalate binds a display-equals-signed hash: `hash === sha256(bytes)` and `bytes` are the EXACT displayed
+ *  terms an approver signs (LCP §12.7 MUST). */
+async function escalate(
+  bytes: Uint8Array,
+  at: string,
+  reason: string,
+  ports: GatePorts,
+  proposal: GateProposal,
+): Promise<GateDecision> {
+  const hash = await hashAtr(bytes);
+  ports.log?.append({
+    timestamp: at,
+    decision: "escalate",
+    code: "gate/escalate",
+    detail: reason,
+    atrHash: proposal.advertisedAtrHash,
+    legalContextUrl: proposal.legalContextUrl,
+  });
+  return { kind: "escalate", bytes, hash, reason };
+}

package/src/fetch.ts

@@ -0,0 +1,169 @@
+import { isUnicastPublic } from "@integraledger/lcp-evidence";
+
+export interface FetchedTerms {
+  readonly bytes: Uint8Array;
+  readonly format: string;
+  readonly fetchedAt: string;
+}
+export interface TermsFetcher {
+  fetch(url: string): Promise<FetchedTerms>;
+}
+
+/** One resolved address for a host. Mirrors `node:dns/promises` `lookup(host, { all: true })`. */
+export interface ResolvedAddress {
+  readonly address: string;
+  readonly family: number;
+}
+/**
+ * The host-resolution port. REQUIRED, and deliberately not defaulted: the buyer fetches a URL the SELLER
+ * chose, so this is the guard between an agent's HTTP client and the buyer's own network — a config that
+ * can omit it silently omits the guard. Node deployments pass `nodeDnsLookup`; a Workers deployment passes
+ * its own (or one that throws, stating it relies on the platform's private-range egress blocking). The
+ * port MUST return literal-IP hosts unchanged, as `node:dns` does.
+ */
+export type HostLookup = (host: string) => Promise<readonly ResolvedAddress[]>;
+
+export interface CachingFetcherConfig {
+  readonly httpFetch: typeof fetch;
+  readonly now: () => string;
+  /** Resolves a hostname to the addresses the unicast guard checks. See `HostLookup` — no default. */
+  readonly lookup: HostLookup;
+  /** LCP §2.6: clients SHOULD NOT cache beyond this; default 24h. Re-fetch after it is a MUST (enforced here). */
+  readonly maxAgeSeconds?: number;
+  /** Fail-loud byte ceiling (DoS guard); default 1 MiB. */
+  readonly maxBytes?: number;
+  /** Max distinct URLs retained (bounded memory / anti-DoS); default 256. Oldest inserted entry evicted past it. */
+  readonly maxEntries?: number;
+}
+const DAY = 86_400;
+
+/**
+ * `node:dns/promises` as a `HostLookup`. Imported lazily so the module graph stays runtime-neutral (the
+ * gate is client-side and may run where `node:dns` does not exist) — a Workers build that never calls this
+ * never pulls it in.
+ */
+export const nodeDnsLookup: HostLookup = async (host: string) => {
+  const dns = await import("node:dns/promises");
+  return dns.lookup(host, { all: true });
+};
+
+/**
+ * HTTPS-only, cached (LCP §2.6), size-capped, SSRF-guarded terms fetcher. The MUST (re-fetch after expiry) is
+ * unconditional; the SHOULD (≤24h) is the default cap.
+ *
+ * SSRF posture — this is the BUYER's exposure, because the URL comes off the seller's 402 challenge:
+ *  - HTTPS scheme required;
+ *  - `redirect: "error"`, so a redirect to a non-HTTPS or internal host fails loudly rather than being
+ *    followed silently;
+ *  - EVERY resolved address for the host must be public unicast (`evidence.isUnicastPublic` — the one
+ *    implementation of that predicate; this package does not re-derive it). The check runs on every
+ *    network fetch, not once per URL, so a cache expiry re-opens it rather than grandfathering a host.
+ *  - the byte cap is enforced while STREAMING, plus a `Content-Length` pre-check. Reading the whole body
+ *    and measuring afterwards protects the check but not the memory, and a chunked response with no
+ *    declared length is exactly the case the cap exists for.
+ *
+ * HONEST LIMITATION — DNS rebinding, carried verbatim from `evidence`'s resolver: the guard validates what
+ * `lookup` returns, but `httpFetch` performs its own resolution and nothing pins the connection to the
+ * validated address. This is real defense-in-depth (the naive name → private IP case is blocked outright),
+ * NOT a complete guarantee; closing it needs connection-level IP pinning inside the injected `httpFetch`.
+ */
+export function makeCachingFetcher(cfg: CachingFetcherConfig): TermsFetcher {
+  const maxAge = cfg.maxAgeSeconds ?? DAY;
+  const maxBytes = cfg.maxBytes ?? 1024 * 1024;
+  const maxEntries = cfg.maxEntries ?? 256;
+  const cache = new Map<string, { at: number; terms: FetchedTerms }>();
+  const secs = (iso: string): number => Math.floor(Date.parse(iso) / 1000);
+
+  async function assertPublicHost(url: URL): Promise<void> {
+    // BRACKETS ARE URL SYNTAX, NOT ADDRESS SYNTAX, and stripping them here is what lets an IPv6 literal
+    // reach the guard at all. `new URL("https://[::1]/x").hostname` is `"[::1]"`, and `node:dns` answers
+    // that with ENOTFOUND — so the request was refused for the right outcome and the WRONG REASON: the
+    // buyer's record named a DNS failure where the truth was an SSRF refusal, and that message is what a
+    // buyer would report to a seller.
+    //
+    // It also refused hosts it should allow. `isUnicastPublic` parses the bracketed form correctly, but the
+    // lookup never returned an address for it, so a seller publishing a legitimate PUBLIC IPv6 literal was
+    // refused with the same ENOTFOUND as a loopback one.
+    //
+    // Unbracketed, `node:dns` returns a literal unchanged — `::1` comes back as `{address:"::1",family:6}`,
+    // exactly as `127.0.0.1` does — which is the behaviour the `HostLookup` contract already requires of
+    // every port. Normalising here rather than inside `nodeDnsLookup` means a Workers or Deno port inherits
+    // the fix instead of having to repeat it.
+    // ONE regex rather than `startsWith("[") && endsWith("]")`, because a matching pair is ONE fact and the
+    // conjunction spelt it as two. `new URL()` cannot produce a hostname with only one bracket, so neither
+    // conjunct was individually observable — mutating either left behaviour identical, which is a survivor
+    // no test can honestly kill. Expressing the pair as a single match makes the check say what it means and
+    // leaves nothing unobservable behind it.
+    const host = /^\[(.+)\]$/.exec(url.hostname)?.[1] ?? url.hostname;
+    const addrs = await cfg.lookup(host);
+    if (addrs.length === 0)
+      throw new Error(`no address for ${url.hostname} — refused (SSRF guard)`);
+    for (const { address } of addrs)
+      if (!isUnicastPublic(address))
+        throw new Error(
+          `${url.hostname} resolves to a non-public address (${address}) — refused (SSRF guard)`,
+        );
+  }
+
+  async function readCapped(res: Response): Promise<Uint8Array> {
+    const body = res.body;
+    if (body === null) return new Uint8Array(0);
+    const reader = body.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.length;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw new Error(`terms exceed ${maxBytes} bytes (fail-loud)`);
+      }
+      chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const c of chunks) {
+      out.set(c, o);
+      o += c.length;
+    }
+    return out;
+  }
+
+  return {
+    async fetch(url: string): Promise<FetchedTerms> {
+      if (!url.startsWith("https://"))
+        throw new Error(`terms url must be HTTPS (SSRF posture): ${url}`);
+      const nowS = secs(cfg.now());
+      const hit = cache.get(url);
+      if (hit !== undefined && nowS - hit.at < maxAge) return hit.terms; // SHOULD: serve fresh from cache
+
+      // Re-validated on every network fetch — an expiring cache entry must not grandfather a host.
+      await assertPublicHost(new URL(url));
+
+      const res = await cfg.httpFetch(url, { redirect: "error" }); // MUST: re-fetch after expiry; never follow redirects
+      if (!res.ok) throw new Error(`terms fetch failed: ${res.status} ${url}`);
+      const declared = res.headers.get("content-length");
+      if (
+        declared !== null &&
+        Number.isFinite(Number(declared)) &&
+        Number(declared) > maxBytes
+      )
+        throw new Error(
+          `terms declare ${declared} bytes > ${maxBytes} (fail-loud): ${url}`,
+        );
+      const buf = await readCapped(res);
+      const terms: FetchedTerms = {
+        bytes: buf,
+        format: res.headers.get("content-type") ?? "application/octet-stream",
+        fetchedAt: cfg.now(),
+      };
+      cache.set(url, { at: nowS, terms });
+      if (cache.size > maxEntries) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined) cache.delete(oldest);
+      }
+      return terms;
+    },
+  };
+}

package/src/fingerprint.ts

@@ -0,0 +1,27 @@
+import type { HaltClass } from "@integraledger/lcp-binding-core";
+import { hashAtr } from "@integraledger/lcp-kernel";
+export type FingerprintOutcome =
+  | { readonly status: "proved"; readonly atrHash: `0x${string}` }
+  | {
+      readonly status: "failed";
+      readonly haltClass: HaltClass;
+      readonly recomputed: `0x${string}`;
+      readonly advertised: string;
+    };
+
+/** The LCP §5.3 core: recompute SHA-256 over the fetched terms bytes and compare to the advertised atrHash. A
+ *  mismatch is `failed(verification-failure)` — the caller MUST halt before invoking any signing key. */
+export async function recomputeAndCompare(
+  bytes: Uint8Array,
+  advertisedAtrHash: string,
+): Promise<FingerprintOutcome> {
+  const recomputed = await hashAtr(bytes);
+  return recomputed.toLowerCase() === advertisedAtrHash.toLowerCase()
+    ? { status: "proved", atrHash: recomputed }
+    : {
+        status: "failed",
+        haltClass: "verification-failure",
+        recomputed,
+        advertised: advertisedAtrHash,
+      };
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+export {
+  type Disposition,
+  decideOutcome,
+  foldDispositions,
+  type GateDecision,
+  type StepStatus,
+} from "./decision.js";
+export { evaluate, type GatePorts } from "./evaluate.js";
+export {
+  type CachingFetcherConfig,
+  type FetchedTerms,
+  type HostLookup,
+  makeCachingFetcher,
+  nodeDnsLookup,
+  type ResolvedAddress,
+  type TermsFetcher,
+} from "./fetch.js";
+export { type FingerprintOutcome, recomputeAndCompare } from "./fingerprint.js";
+export { InMemoryOrc4Log, type Orc4Entry, type Orc4Log } from "./log.js";
+export { type MechanicalPorts, verifySettled } from "./mechanical.js";
+export {
+  type BuyerPolicy,
+  evaluatePolicy,
+  type PolicyResult,
+} from "./policy.js";
+export {
+  type GateProposal,
+  type ProposalContext,
+  parseProposalFromChallenge,
+} from "./proposal.js";
+export {
+  ACK_DID_METHODS,
+  type AckReceiptContribution,
+  type AckReceiptFacts,
+  ackReceiptContribution,
+  parseAckReceipt,
+} from "./proposal-ack.js";
+export { parseProposalFromAcpCheckout } from "./proposal-acp.js";
+export {
+  AP2_HALT_POINT,
+  type Ap2HaltPoint,
+  type Ap2ProposalContext,
+  type Ap2Step,
+  assertBeforeAp2HaltPoint,
+  isAp2SigningStep,
+  parseProposalFromAp2Envelope,
+} from "./proposal-ap2.js";
+export { parseProposalFromMppRequest } from "./proposal-mpp.js";
+export {
+  ACP_SESSION_STATUS,
+  type AdvertisedTerms,
+  type AdvertisedTermsUrl,
+  detectProtocol,
+  matchProtocols,
+  PROPOSAL_PARSERS,
+  PROTOCOL_DISCRIMINANTS,
+  type ProposalParser,
+  type ProtocolDiscriminant,
+  parseableProtocols,
+  parseProposalUniversal,
+  readAdvertisedTerms,
+  VI_OPEN_MANDATE_VCT,
+} from "./proposal-universal.js";
+export {
+  type GuardedSigner,
+  type TransactResult,
+  transact,
+} from "./transact.js";

package/src/log.ts

@@ -0,0 +1,34 @@
+import type { HaltClass } from "@integraledger/lcp-binding-core";
+
+export interface Orc4Entry {
+  readonly timestamp: string;
+  readonly decision: "proceed" | "decline" | "escalate";
+  readonly haltClass?: HaltClass;
+  readonly code: string;
+  readonly detail: string;
+  readonly atrHash?: string;
+  /**
+   * The discovery document the proposal pointed at — the terms this decision was reached about.
+   *
+   * WITHOUT IT AN ENTRY NAMES A VERDICT AND NOT ITS SUBJECT. `atrHash` alone does not identify the
+   * document: on the decision that matters most — a fingerprint mismatch — the advertised hash is by
+   * construction NOT the hash of what was served, so a reader holding only that value cannot say which
+   * document disagreed with it. A seller told "your terms did not match" and given a hash it cannot
+   * reproduce learns nothing it can act on; given the URL, it can fetch the bytes and see.
+   *
+   * Optional for the same reason `atrHash` is: this is the sink's input type, and a producer other than
+   * `evaluate` — a mechanical verification, say — may legitimately have no document to name. `evaluate`
+   * always sets it.
+   */
+  readonly legalContextUrl?: string;
+}
+export interface Orc4Log {
+  append(e: Orc4Entry): void;
+}
+/** A real, complete in-memory ORC-4 sink (not a mock) — a deployment injects a durable one. */
+export class InMemoryOrc4Log implements Orc4Log {
+  readonly entries: Orc4Entry[] = [];
+  append(e: Orc4Entry): void {
+    this.entries.push(e);
+  }
+}