@integraledger/agent-guard 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# @integraledger/agent-guard
+
+## 0.9.0
+
+**First public release** — Apache-2.0, free forever, no account and no token to install.
+
+`agent-guard` is the buyer-side verify-before-sign guard for agentic purchases. It fetches the terms a
+seller advertised, recomputes their fingerprint, and halts before any signing key is invoked if the two
+disagree. It works against **any** seller, whether or not that seller uses Integra software.
+
+### The gate
+
+`evaluate` runs the Legal Context Protocol's buyer sequence and returns a decision. It never touches a
+signing key itself — `transact` enforces the decision against a guarded signer, so no caller can sign on a
+refusal by mistake.
+
+- **Fetch and retain the terms as evidence** (LCP §5.4), at every trust level, never a silent skip.
+- **Verify before sign** (LCP §5.3): recompute the fingerprint over the fetched bytes and HALT on a
+  mismatch, before the key.
+- **Policy on the typed envelope only** (LCP §12.7). The terms body is retained as evidence and never
+  reaches policy evaluation. The prompt-injection boundary is architectural rather than a filter: the
+  typed proposal cannot carry prose.
+- **Refuse rather than choose.** A coverage gap resolves by the buyer's stated disposition; nothing
+  resolves by a silent default.
+
+Outcomes are **twelve decline codes**, plus `gate/escalate` and `gate/proceed`. The codes are the
+contract — the accountable record and a buyer's escalation path both key off them — and a refusal names
+the counterparty's actual defect rather than a reason that merely happens to be true. A counterparty
+cannot make the gate throw: every failure reachable from a seller-authored document arrives as a returned
+decision.
+
+### Protocols
+
+Four commerce protocols parse into one typed `GateProposal`: **x402** and **ACP** through
+`parseProposalUniversal`, which refuses a document matching two protocols' discriminants rather than
+picking one; **AP2** and **MPP** by name, because their identity lives outside the body a caller holds.
+
+### The fetcher is an SSRF boundary
+
+It takes a counterparty-chosen URL. It is HTTPS-only, refuses redirects, re-checks that every resolved
+address is public unicast on every fetch, and caps the body while streaming. IPv6-literal hosts are
+supported. `GatePorts` is a documented trust boundary: the fetcher decides which bytes the fingerprint is
+recomputed over.
+
+**Nothing calls home** — no telemetry, no callback, no request beyond fetching the terms the seller
+pointed at.
+
+### Packaging
+
+- Apache-2.0. LICENSE and NOTICE ship in the tarball; NOTICE states the trademark reservation, names
+  Integra Ledger and AAA-ICDR as the Legal Context Protocol's co-stewards, and records that the
+  seller-side application is separately licensed and not part of this distribution.
+- The `@integraledger/lcp-*` protocol line is a **peer** dependency, so a consumer's tree holds exactly
+  one copy of it — two copies break `instanceof` across the boundary.
+- `files` ships `src` alongside `dist`, so published source maps resolve inside the tarball.
+- Runs on Node, Deno, Bun, and Workers with `nodejs_compat`. The README's runtime table states per-target
+  support exactly; the one Node-specific host lookup is lazily imported and injectable.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,15 @@
+Integra Agent Guard
+Copyright 2026 Integra Ledger
+
+This product includes software developed by Integra Ledger (https://integraledger.com).
+
+"Integra", "Integra Ledger", and the Integra logo are trademarks of Integra Ledger.
+Trademark use is not granted by the Apache License 2.0 (see Section 6).
+
+The Legal Context Protocol is co-stewarded by Integra Ledger and AAA-ICDR. This package implements the
+buyer side of that standard and is published free under the Apache License 2.0; the specification itself
+is published at https://legalcontextprotocol.org/standard and is not part of this distribution.
+
+This package verifies terms served by ANY seller, whether or not that seller uses Integra software. The
+seller-side application it is designed to interoperate with is separately licensed and is not part of
+this distribution.

package/README.md

@@ -0,0 +1,154 @@
+# @integraledger/agent-guard
+
+**Integra Agent Guard** — verify before sign, as a type and as a runtime guarantee. A paying agent fetches
+the terms the seller advertised, recomputes the fingerprint, and halts before any signing key is invoked if
+it does not match what was advertised.
+
+```bash
+npm install @integraledger/agent-guard
+```
+
+> **Free and open source (Apache-2.0). No account, no key, no token, nothing to sign up for.**
+>
+> **It works against any seller** — the check is over what a seller publicly advertises, so it is useful
+> whether or not that seller has ever heard of Integra. Nothing here calls home: no telemetry, no callback,
+> no network request other than fetching the terms the seller pointed you at.
+
+```ts
+import {
+  type BuyerPolicy,
+  type GuardedSigner,
+  makeCachingFetcher,
+  nodeDnsLookup,
+  parseProposalFromChallenge,
+  transact,
+} from "@integraledger/agent-guard";
+
+declare const challenge: unknown; // the 402 body the seller returned
+declare const policy: BuyerPolicy; // your risk posture — caps, jurisdictions, forbidden clauses
+declare const signer: GuardedSigner; // your key. Reachable only on Proceed.
+
+const now = () => new Date().toISOString();
+const fetcher = makeCachingFetcher({ httpFetch: fetch, now, lookup: nodeDnsLookup });
+
+const proposal = parseProposalFromChallenge(challenge, {
+  level: 3,
+  sellerAssurance: "domain-controlled",
+});
+const result = await transact(proposal, policy, { fetcher, now }, signer);
+// result.kind === "signed" only on Proceed; on Decline or Escalate the signer is never called.
+```
+
+Two properties do the work. The typed proposal **cannot** carry natural-language prose, so the terms body
+can never reach policy evaluation — the prompt-injection boundary is architectural rather than a matter of
+discipline. And a step's four-valued status maps totally onto a disposition: a failure always declines, and
+gaps are resolved by the buyer's stated policy, never by a silent default.
+
+The terms fetcher is HTTPS-only, refuses redirects, checks every resolved address is public unicast on every
+network fetch, and caps the body while streaming. Viem-free: the chain reader for post-settlement mechanical
+verification is injected.
+
+### Runs wherever your agent runs — with one dependency caveat
+
+**This package's own source imports no Node built-in.** The one Node-specific helper, `nodeDnsLookup`, is
+imported lazily and injected rather than sitting at the top of the graph, so a build that never calls it
+never pulls `node:dns` in. Supply your own `HostLookup` and the public-unicast check works on a runtime with
+no DNS module at all. That much is enforced by the code and is the part worth relying on.
+
+**One Node built-in does arrive transitively**, and the honest statement is that it is a dependency's, not
+ours: `@integraledger/lcp-evidence` re-exports its CAR support from its index, which pulls `multiformats`'
+Node SHA-2 build, which statically imports `node:crypto`. So:
+
+| Target | Works |
+|---|---|
+| Node | yes |
+| Deno, Bun, Workers with `nodejs_compat` | yes — `node:crypto` is polyfilled |
+| A bundler honouring `multiformats`' `browser` export condition | yes — it maps to the browser SHA-2 build |
+| A plain unbundled ESM import in a browser or service worker | **no** |
+
+The guard needs `fetch` and Web Crypto and nothing else of its own. Removing the last hop is an upstream
+change — a subpath export on `lcp-evidence` so importing one predicate does not drag CAR and `multiformats`
+into every consumer's bundle — and until it lands, the table above is the claim.
+
+### The guard is exactly as trustworthy as the ports you give it
+
+`GatePorts` is a trust boundary, not just a seam for testing. `fetcher` decides which bytes the fingerprint
+is recomputed over, so a fetcher that returns the wrong body defeats verification completely; `now` dates
+every entry in the record. This is not a weakness to fix — injection is what keeps the guard viem-free and
+runnable off Node — but it is a property worth stating rather than discovering. Use the `makeCachingFetcher`
+shipped here unless you have a specific reason not to, and hold your ports to the standard you hold the key
+they protect.
+
+## Reading any protocol's document
+
+A buyer that does not know which protocol it is on has two universal entry points, both dispatching through
+`@integraledger/lcp-placements` so that a protocol this package supports is precisely one the build can also
+place a reference into.
+
+```ts
+import {
+  detectProtocol,
+  parseProposalUniversal,
+  readAdvertisedTerms,
+} from "@integraledger/agent-guard";
+
+declare const wire: unknown; // whatever document the counterparty handed you
+
+detectProtocol(wire); // "acp" | … | undefined — never a guess
+readAdvertisedTerms("ucp", wire); // { protocol, advertisedAtrHash, legalContextUrl }
+parseProposalUniversal(wire, { level: 3, sellerAssurance: "domain-controlled" }); // the full GateProposal
+```
+
+**`readAdvertisedTerms` is universal; `parseProposalUniversal` is not, and the difference is a fact about
+the protocols.** The reference is read out of the protocol's own `PlacementManifest` — every carrier it
+declares, not the first one that answers — so all nine registered protocols work and nothing is listed here.
+A `GateProposal` additionally carries an OFFER, and an amount with its unit is protocol-native economics no
+manifest declares: x402 quotes it in `accepts[].amount`, ACP in the `totals` row typed `total`, and the
+other seven each differently again.
+
+Four protocols are parsed into a full `GateProposal` today — **x402, ACP, AP2 and MPP**. Two of the four
+are reached through `parseProposalUniversal`; **AP2 and MPP are reached by name**, because naming is what
+their documents require:
+
+```ts
+import { parseProposalFromChallenge, parseProposalFromAcpCheckout,
+         parseProposalFromAp2Envelope, parseProposalFromMppRequest } from "@integraledger/agent-guard";
+```
+
+`parseProposalFromMppRequest` reads the MPP `request` body — the payload a `WWW-Authenticate: Payment`
+challenge carries in its `request` auth-param. It takes `methodDetails.atrHash` and
+`methodDetails.legalContextUrl`, the fields `placement-mpp` declares, and the offer from `amount` and
+`currency`, which the charge intent defines as base units of a currency-or-asset identifier. It is by-name
+because MPP's own identity lives in the challenge rather than the body: an amount-and-currency pair is the
+shape of nearly every payment document, so nothing in the body says "MPP". The remaining protocols refuse by
+name and say why.
+
+Four answers are worth stating plainly, because each is a place a friendlier library would guess:
+
+- **Ambiguity refuses.** Detection collects every discriminant that fires, never the first. An AP2 envelope
+  *is* an A2A message, and a UCP checkout response shares `id`, `status`, `currency`, `totals` and
+  `line_items` with an ACP session — so those documents come back named twice, and the caller has to say
+  which protocol it is on rather than being handed a coin flip. The two overlaps differ in strength: the
+  ACP/UCP one is contingent on the document, while `ap2`'s rule is a strict subset of `a2a`'s, so **every**
+  AP2 envelope matches both and none is reachable through `parseProposalUniversal`. AP2 is a detect-and-name
+  protocol here; `parseProposalFromAp2Envelope` exists and is called by name.
+- **An unlocatable terms URL is reported, not answered.** `legalContextUrl` is a union — `read`,
+  `no-field-declared`, `declared-field-empty`, or `undeclared-at-answering-carrier` — because
+  `PlacementManifest.termsUrlField` is singular and x402's names a path inside one of its two carriers. A
+  §C.4-illustrated challenge advertising in `accepts[].extra` really does carry a terms URL, and a bare
+  `undefined` there would contradict `parseProposalFromChallenge` reading the same bytes. The fix is a
+  per-alias declaration on the manifest; until it lands the shortfall is named.
+- **Carrier disagreement refuses.** Where a protocol declares more than one carrier, all of them are read
+  and compared. Two different hashes on one document would let a seller advertise different terms to
+  different readers of it, so this is deliberately stricter than the placement adapter's own `extract`,
+  which answers with the canonical field and does not adjudicate the host's document.
+- **A located-but-unattested carrier is not a reference.** UCP's `links[type=terms_of_service]` entry is a
+  discovery carrier: it says where the terms are and attests nothing, and it is skipped rather than accepted
+  as a weaker answer.
+
+One protocol carries nothing that names it — MPP, whose document is the decoded `request` body of a charge
+challenge, an amount and a currency with no protocol marker (its identity lives in the `WWW-Authenticate`
+challenge one layer out). `detectProtocol` returns `undefined` for it and `PROTOCOL_DISCRIMINANTS` records
+why, with the citation. Naming it yourself reads it fine.
+
+Part of [Integra Agent Guard](https://github.com/IntegraLedger/integra-agent-guard).

package/dist/decision.d.ts

@@ -0,0 +1,26 @@
+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 declare function decideOutcome(status: StepStatus, gaps: {
+    readonly onIndeterminate: Disposition;
+    readonly onNotAttempted: Disposition;
+}): Disposition;
+/** Fold per-step dispositions into one: any decline ⇒ Decline-dominant; else any escalate ⇒ Escalate; else proceed. */
+export declare function foldDispositions(ds: readonly Disposition[]): Disposition;
+//# sourceMappingURL=decision.d.ts.map

package/dist/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AACjE,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,eAAe,CAAC;AACpB,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN;;mHAEmH;AACnH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;IACJ,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;CACtC,GACA,WAAW,CAeb;AAED,uHAAuH;AACvH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,CAIxE"}

package/dist/decision.js

@@ -0,0 +1,28 @@
+/** 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, gaps) {
+    switch (status) {
+        case "proved":
+            return "proceed";
+        case "failed":
+            return "decline";
+        case "indeterminate":
+            return gaps.onIndeterminate;
+        case "not-attempted":
+            return gaps.onNotAttempted;
+        default: {
+            const _exhaustive = status;
+            return _exhaustive;
+        }
+    }
+}
+/** Fold per-step dispositions into one: any decline ⇒ Decline-dominant; else any escalate ⇒ Escalate; else proceed. */
+export function foldDispositions(ds) {
+    if (ds.includes("decline"))
+        return "decline";
+    if (ds.includes("escalate"))
+        return "escalate";
+    return "proceed";
+}
+//# sourceMappingURL=decision.js.map

package/dist/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAsBA;;mHAEmH;AACnH,MAAM,UAAU,aAAa,CAC3B,MAAkB,EAClB,IAGC;IAED,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC;QACnB,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC;QACnB,KAAK,eAAe;YAClB,OAAO,IAAI,CAAC,eAAe,CAAC;QAC9B,KAAK,eAAe;YAClB,OAAO,IAAI,CAAC,cAAc,CAAC;QAC7B,SAAS,CAAC;YACR,MAAM,WAAW,GAAU,MAAM,CAAC;YAClC,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED,uHAAuH;AACvH,MAAM,UAAU,gBAAgB,CAAC,EAA0B;IACzD,IAAI,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,IAAI,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAC/C,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/evaluate.d.ts

@@ -0,0 +1,15 @@
+import type { GateDecision } from "./decision.js";
+import type { TermsFetcher } from "./fetch.js";
+import type { Orc4Log } from "./log.js";
+import { type BuyerPolicy } 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 declare function evaluate(proposal: GateProposal, policy: BuyerPolicy, ports: GatePorts): Promise<GateDecision>;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;kGAEkG;AAClG,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,YAAY,CAAC,CAgIvB"}

package/dist/evaluate.js

@@ -0,0 +1,112 @@
+import { parseLegalContextJson, } from "@integraledger/lcp-discovery";
+import { hashAtr } from "@integraledger/lcp-kernel";
+import { recomputeAndCompare } from "./fingerprint.js";
+import { evaluatePolicy } from "./policy.js";
+/** 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, policy, ports) {
+    const at = ports.now();
+    const decline = (haltClass, code, detail) => {
+        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;
+    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;
+    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, at, reason, ports, proposal) {
+    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 };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/evaluate.js.map

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