@integraledger/lcp-placement-x402 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @integraledger/lcp-placement-x402
+
+## 0.9.0
+
+First public release.
+
+`0.9.0` is deliberate: this is a release candidate for 1.0, not a preview. The implementation is complete
+against LCP v1.38 and certified by the conformance corpus, and the remaining distance to 1.0 is the
+specification's own — the standard is still moving through its steering committee, and this package will not
+claim a stability its protocol has not yet promised.
+
+Development before this release happened in a private repository and is not reproduced here; no earlier
+version was ever available to install.

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,14 @@
+Integra Protocol
+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 repository is a
+reference implementation of the standard's open layer; the specification itself is published at
+https://legalcontextprotocol.org/standard and is not part of this distribution.
+
+The vendored submodule under lib/commerce-payments is Coinbase's AuthCaptureEscrow and carries its own
+MIT licence at lib/commerce-payments/LICENSE.md. It is not covered by the Apache License above.

package/README.md

@@ -0,0 +1,207 @@
+# @integraledger/lcp-placement-x402
+
+Places an LCP reference into an [x402](https://x402.org) v2 payment challenge, and reads it back out.
+
+**This is the HTTP-layer carrier, not the x402 weld.** [`@integraledger/lcp-binding-evm-x402`](../binding-evm-x402#readme) binds `atrHash`
+into the EIP-3009 authorization nonce — that is the settlement binding, and it answers *what did the money
+commit to?* This package answers a different question — *where does the reference ride on the wire?* — and
+both are true at the same time. x402 is the proof that one protocol can need a binding **and** a placement.
+It is also the reason this package exists at all: the carrier it declares was previously only a private
+TypeScript interface inside a seller implementation, and a private convention nobody outside that codebase
+can read is not an artifact.
+
+```bash
+npm install @integraledger/lcp-placement-x402
+```
+
+| | |
+|---|---|
+| **Chain** | none here — settlement is `binding-evm-x402`'s, on whichever EVM rail the scheme selects |
+| **Pattern** | `http-advisory` (LCP §8.3.7, Tier A) |
+| **Field** | `extensions.legalContext.info` — the top-level extensions map, the carrier x402 protects |
+| **Read also** | `accepts.0.extra.atrHash` — a **bare** hash, its own encoding (integrity) |
+| **Terms URL** | `extensions.legalContext.info.legalContextUrl` — declared, never written by `place` |
+| **Carrier types** | `sha256`, `url` |
+| **Spec** | x402 v2 (`x402-foundation/x402@1fec3aa04e41`, `specs/x402-specification-v2.md`), gate discharged **2026-07-30** |
+
+## Use
+
+```ts
+import { X402_PLACEMENT, x402Placement } from "@integraledger/lcp-placement-x402";
+
+declare const challenge: unknown; // the x402 402 challenge document, as received
+
+const placed = x402Placement.place({ type: "sha256", value: "0x…" }, challenge);
+const ref = x402Placement.extract(challenge); // reads either carrier, canonical first
+```
+
+Both members are total: a refusal is a returned value, never a thrown exception. Entries **beside** our own in
+the `extensions` map are preserved on every `place`. That is narrower than x402's echo rule, which protects the
+`legalContext` entry's *contents* too — see *Known limitations*: `place` replaces our entry whole, so it is a
+seller's write verb, not a buyer's echo verb.
+
+## Specification provenance — verified against the live host, 2026-07-30
+
+Read against the live x402 v2 specification in the x402 repository (`specs/x402-specification-v2.md`, §5.1.2
+and the PaymentRequirements table), four facts were confirmed and each one decides something here:
+
+1. **`extensions` is carried on `PaymentRequired`, `PaymentPayload` and `SettlementResponse`.** A reference
+   placed there is on the **receipt**, not only the proposal — so the record can bind at execution time.
+2. **Each entry carries `info` and `schema`** — `info` is "Extension-specific data provided by the server",
+   `schema` is a "JSON Schema defining the expected structure of `info`". Nothing in the spec fetches or
+   validates `schema`; it is a pointer. That `{info, schema}` wrapper is why this is the one placement in the
+   plan that overrides the kit's `place` (see below).
+3. **The echo rule:** "The client must include at least the info received; it may append additional info but
+   cannot delete or overwrite existing info." This is the carrier the **protocol itself protects**, which is
+   why it is canonical here rather than the per-requirement object.
+4. **`extra` is "Scheme-specific additional information"** on a `PaymentRequirements` entry — the payment
+   scheme's object, whose contents that scheme defines. So `place` **never writes there**; the alias is
+   read-only, and that is a decision about whose namespace it is, not an omission.
+
+Extension identifiers are implementation-defined strings — no registry, no reverse-domain rule — so the
+`legalContext` key is available today and this placement is Tier A on the wire.
+
+### Drift from LCP v1.37 §C.4, recorded rather than absorbed
+
+The host governs: its live specification is binding and LCP's Appendix C is an illustration.
+Two differences, neither of which changes the design:
+
+- v1.37 renders the echo rule in RFC-2119 capitals ("MAY append to but **MUST NOT** delete or overwrite")
+  and states it about the extensions map. The live spec states it in lower case and about the `info` payload.
+  Same rule, weaker modality, one level lower.
+- The live spec also carries `extra` on `PaymentPayload.accepted`, which §C.4 does not mention.
+
+### Drift from a strict buyer-side reader, recorded for the same reason
+
+Buyer gates that parse this wire document already exist. The **paths and shapes** match field for field — `accepts[0].extra.atrHash`, `accepts[0].extra.legalContextUrl`,
+`extensions.legalContext.info.{type,value,legalContextUrl}`. The **resolution semantics do not**, and three
+differences are real. Recording them is the whole point of declaring the carrier: an undisclosed
+divergence between two readers of one document is the drift this package exists to end, not a smaller version
+of it.
+
+1. **Carrier precedence is inverted.** This placement answers with the **canonical `extensions` slot** when
+   both carriers are present — the manifest's declared field wins, which is `binding-core`'s rule for every
+   protocol in the set. A buyer gate may instead prefer **`accepts[].extra`**, on the ground that it is the
+   per-requirement carrier and binds to the requirement actually being paid.
+   Measured on one challenge carrying `0xaa…` in `extensions` and `0xbb…` in `extra`, this package answers
+   `0xaa…`.
+2. **Carrier disagreement is resolved here and REFUSED by a strict reader.** A buyer gate may refuse outright
+   rather than pick, because two values on one challenge would let a seller advertise different terms to
+   different readers. A placement is structural — it reads the strongest
+   declared carrier and does not adjudicate the host's document — so it answers with the canonical value and
+   says nothing. A caller that needs the commerce reader's guarantee must compare both carriers itself:
+   `readDeclaredPaths` returns the first hit, not the set.
+3. **A `url` carrier is placeable here and rejected there.** `carrierTypes` permits `sha256` and `url`;
+   a strict buyer gate refuses `extensions.legalContext.info.type !== "sha256"` outright, because it compares
+   the advertised value against a recomputed record hash and nothing but a hash can be. See
+   *Known limitations*.
+
+Reconciling 1 and 2 belongs to a universal buyer parser that reads both carriers through this manifest; a
+follow-on re-expresses the seller's private carrier interface in terms of this manifest and touches the
+**writer** only. Neither is done here.
+
+### Tier B forward work — prose only, no manifest
+
+§C.4's two forward paths are real and neither is shippable: a reference inside the **signed** Offer/Receipt
+artifact (the EIP-712 types are closed structures and any change to them is a breaking version change; under
+JWS an added claim is signed but explicitly uninterpreted), and a **registered** extension identifier with a
+published schema (a standardization step, not a protocol change). No Tier B manifest is declared for either —
+a manifest carrying a shape whose owner has not defined it is exactly the assertion this seam refuses.
+
+## The one override, and why it earns it
+
+`extract` is the kit's, unchanged: reading `extensions.legalContext.info` is an ordinary object-path read,
+and the bare-hash alias is handled by its own declared `encoding`. `place` is overridden, because x402's slot
+does not hold the reference — it holds `{ info, schema }`, a **wrapper** that no container kind models.
+Inventing an `x402-extension` container kind would put one protocol's name inside a generic enum, which is
+the abstraction leaking. One overridden member is composition; the test suite asserts `extract` still behaves
+exactly as a freshly built kit adapter does, over every accept-and-refuse path, so a later edit cannot
+quietly fork the read half too.
+
+**The override changes the shape it writes, never which documents it will write into.** `place` refuses
+exactly what a kit adapter built from this manifest alone refuses, over the same inputs and with the same
+codes, and a test pins that equality. Two rules do the work:
+
+- **Own properties only.** A challenge with zero own properties does not inherit an `extensions` map into the
+  document we emit. `extract` reports such a document as `reference-absent`, and the two halves must agree
+  about what is present — a `place` document is exactly as attacker-influenced as an `extract` one.
+- **An `extensions` that is present and is not a map REFUSES** (`x402/document-malformed`), rather than being
+  replaced. The declared field is `extensions.legalContext.info`, so `legalContext` is the field's direct
+  holder and `extensions` sits one level **above** it: `binding-core`'s malformed-container rule replaces at
+  the holder and refuses above it, because replacing an intermediate discards everything beneath. Absent is
+  still created — that is the extension point working — and our own entry, being the direct holder, is still
+  replaced.
+
+## Two carriers, and the alias has a different SHAPE
+
+x402 is the only protocol in the set whose alias is encoded differently from its canonical field. The
+canonical slot holds an LCP §8.1 `{type, value}` object; `accepts[0].extra.atrHash` holds a **bare** hash.
+Writing `lcp:sha256:0x…` into `extra.atrHash` would emit a field neither our own seller nor any x402
+counterparty parses. This is the reason a `readAlso` entry declares its own encoding at all.
+
+The alias is **index 0 only**. A locator names one path, and `accepts[0]` is what the shipped buyer parser
+reads: the reference must bind to the requirement actually being paid, and searching every requirement would
+let a seller park a second set of terms on an alternative it never expects to be chosen.
+
+Reaching that path is also the reason `binding-core`'s `readAtPath` now indexes arrays — narrowly, on a
+canonical non-negative integer segment only, so `length` and every other array property stay unreachable.
+That relaxation lives in the kit rather than in a private loop here, because a read rule nobody can find is
+the same defect as a carrier nobody can find.
+
+## Known limitations
+
+- **`place` writes the hash, never the terms URL.** `place(ref, doc)` holds one reference; the terms URL is a
+  second datum. `termsUrlField` is declared so a parser can find the URL our seller does emit, the same
+  division `placement-acp` draws with `metadata.legal_context_url`.
+- **The shipped carrier repeats the URL at `accepts[0].extra.legalContextUrl`.** A single `termsUrlField`
+  cannot express two spellings, so that one is recorded here rather than half-declared in the manifest.
+- **A `url` carrier is placeable here and no shipped x402 reader accepts one.** `carrierTypes` permits
+  `sha256` and `url` — the §8.1 integrity form and the §8.1 discovery form, the same pair `placement-acp` and
+  `placement-ucp` permit — while a strict buyer gate refuses any `info.type` but `sha256`. The permission is not
+  narrowed away here because narrowing the reference field to one type is a statement about what the slot may
+  hold across the whole set, not a fact about x402. **Related and not ours to fix in this package:**
+  `readDeclaredPaths` labels a canonical-field hit `carrierClass: "integrity"` unconditionally, so a `url`
+  read from `extensions.legalContext.info` is labelled `integrity` and passes `requireIntegrity()` (from
+  [`@integraledger/lcp-binding-core`](../binding-core#readme), like `makePlacement`). That is
+  `binding-core` behaviour that `placement-acp` and `placement-ucp` already share on `main`; this manifest
+  only adds a third reference field with the same property, and `requireIntegrity` has no production caller
+  yet.
+- **Our own `legalContext` entry is replaced whole, not merged — and the key that loses is `legalContextUrl`,
+  the one `termsUrlField` points at.** `place` writes `{info, schema}`, so nothing previously inside our entry
+  survives, and on the document sellers actually emit that is concretely the terms-URL half: measured on
+  the vector case for the long-standing shipped carrier, `termsUrlField` reads
+  `https://seller.example/.well-known/legal-context.json` before `place` and `undefined` after. This is the
+  kit's leaf-write semantics, not an override defect — `makePlacement(X402_PLACEMENT).place` drops it
+  identically — and it is why the previous bullet says `place` holds one reference: a caller that needs both
+  halves on the wire writes the URL itself.
+  **Consequence for a buyer.** Do not build a `PaymentPayload` echo with `place`. x402's rule is that the
+  client "cannot delete or overwrite existing `info`", and re-placing over a server-sent entry deletes the
+  URL the server put there. Echo the received entry verbatim and place only where no entry exists yet; the
+  reconciled read/echo path belongs to a universal buyer parser, not this package.
+  x402 defines only `info` and `schema` for an entry and the `legalContext` key is ours, so owning the entry is
+  the point for the *seller* direction; entries *beside* ours in the `extensions` map are preserved
+  unconditionally.
+- **`LEGAL_CONTEXT_SCHEMA_REF` points at a document the LCP TSC has not published yet**
+  (`https://legalcontextprotocol.org/schemas/lcp-extension.json`). It is byte-identical to what emitters
+  emits, and it is never fetched by anything in x402. Publishing it — or repointing it — is a **wire change
+  and must be made in both repos at once**; repointing it here alone would recreate the drift this package
+  exists to close.
+
+## Provenance
+
+Cut against x402 v2 (`x402-foundation/x402@1fec3aa04e41`, `specs/x402-specification-v2.md`, read 2026-07-30) and reconciled
+against LCP v1.37 §C.4 the same day. The **paths and shapes** are matched field-for-field against the shipped
+shipped seller carrier and the buyer parsers that read it; the **resolution semantics diverge from a strict
+buyer gate in three recorded ways**, and *Drift from a strict buyer-side reader*
+above states each one and who closes it. Both drift sections are the disclosure, not a to-do list — a
+divergence written down is governed; the same divergence unwritten is the undisclosed-drift defect wearing
+a new name.
+
+---
+
+**Requires Node >= 24.** Part of the
+[Legal Context Protocol open layer](https://github.com/IntegraLedger/integra-protocol) — see the
+[documentation](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/index.md)
+and the
+[package index](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/reference.md).
+Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { LEGAL_CONTEXT_SCHEMA, X402_PLACEMENT } from "./manifest.js";
+export { x402Placement } from "./placement.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { LEGAL_CONTEXT_SCHEMA, X402_PLACEMENT } from "./manifest.js";
+export { x402Placement } from "./placement.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,103 @@
+import type { PlacementManifest } from "@integraledger/lcp-binding-core";
+/**
+ * The carrier's JSON Schema, INLINED rather than referenced.
+ *
+ * x402 makes `schema` a REQUIRED member of an extension entry — "JSON Schema defining the expected
+ * structure of info" — so whatever goes here is on the wire of every challenge. A `$ref` to a URL nobody
+ * serves would be a required member no counterparty can resolve, and "x402 never fetches it" is a reason
+ * that does not break, not a reason to ship it. (`https://legalcontextprotocol.org/schemas/lcp-extension.json`
+ * returns **404**, measured 2026-08-08 — the schema is inlined instead.)
+ *
+ * **Both extensions published in the x402 repository inline a complete JSON Schema** rather than
+ * referencing an external document, and LCP v1.38 §C.4 says to do one or the other: "Because `schema` is a
+ * REQUIRED member, publish a resolvable schema or inline it." Inlining also removes a hosting dependency
+ * the deployment does not currently meet — the same dependency the UCP capability still owes.
+ *
+ * The shape is the §8.1 reference object this placement writes into `info`, and nothing more: it describes
+ * the carrier, not the terms behind it.
+ *
+ * Changing this is a WIRE change — it appears in every challenge — so it is a frozen literal rather than a
+ * value assembled at call time.
+ */
+export declare const LEGAL_CONTEXT_SCHEMA: Readonly<Record<string, unknown>>;
+/**
+ * x402 reference placement — the HTTP-layer carrier, cut against the live x402 v2 specification
+ * (`x402-foundation/x402@1fec3aa04e41`, `specs/x402-specification-v2.md`; gate discharged in the README).
+ *
+ * **THE CANONICAL REPOSITORY IS THE FOUNDATION'S, and the citation moved on 2026-08-08.** Every
+ * reference here named `coinbase/x402`, which the GitHub API reports as `"fork": true`;
+ * `x402-foundation/x402` is `"fork": false` and is what LCP v1.38 §C.4's own *Checked against* line
+ * reads. Citing a fork invites a reader to diff against a copy that may lag. The revision is pinned
+ * rather than left as a bare repo name, because "the live spec" with no commit is not a claim anyone
+ * can re-check.
+ *
+ * **This is NOT the x402 weld.** `@integraledger/lcp-binding-evm-x402` binds `atrHash` into the EIP-3009 nonce —
+ * that is the SETTLEMENT binding and it answers "what did the money commit to?". This manifest answers a
+ * different question — "where does the reference ride on the wire?" — and both are true at once. x402 is the
+ * proof that one protocol can need a binding AND a placement.
+ *
+ * **Tier A in both slots, and the canonical one is the map the protocol PROTECTS.** x402 v2 defines a
+ * per-requirement `accepts[].extra` object and a top-level `extensions` map, the latter carried on the
+ * `PaymentRequired` challenge, the `PaymentPayload` AND the `SettlementResponse` — so a reference placed
+ * there is on the receipt, not only the proposal. Each `extensions` entry carries `info` ("Extension-specific
+ * data provided by the server") and `schema` ("JSON Schema defining the expected structure of `info`"). The
+ * live spec's echo rule — "The client must include at least the info received; it may append additional info
+ * but cannot delete or overwrite existing info" — is what makes that map the more durable carrier, and it is
+ * why it is canonical here.
+ *
+ * **`pattern` is `http-advisory`, not `protocol-extension`.** §8.3.6 means the HOST protocol's own
+ * verification and settlement procedure understands the hash; no x402 facilitator does. It is also Tier B by
+ * definition, which would misdescribe a carrier that works today against stock x402 — extension identifiers
+ * are implementation-defined strings, so no registration gates this. The same determination is made for ACP
+ * and UCP. §C.4's Tier B forward paths (a reference inside the signed Offer/Receipt artifact; a registered
+ * extension identifier) are declared in the README as prose and in NO manifest — asserting a shape whose
+ * owner has not defined it is the asserting-a-shape defect.
+ *
+ * **The extension key is `legalContext`, deliberately not a reverse-domain name.** x402 imposes no namespace
+ * rule, and `legalContext` is the spelling emitters put on the wire, the spelling buyer parsers read, and the
+ * one LCP v1.38 §C.4's own illustration shows. The `com.integraledger.*` reverse-domain namespace applies to
+ * hosts that REQUIRE one — UCP does; x402 does not — and renaming this key to suit a convention x402 does not
+ * have would put a spelling on the wire that no counterparty reads.
+ *
+ * **The alias carries a DIFFERENT SHAPE, and x402 is the only protocol in the set where that is true.** The
+ * canonical slot holds a §8.1 object; `accepts[0].extra.atrHash` holds a **bare** hash — that is the form
+ * emitters write there and the form x402 integrators recognize. Writing an `lcp:` string into `extra.atrHash`
+ * would emit something no x402 counterparty parses. This is the reason an alias declares its own `encoding`
+ * at all.
+ *
+ * **The alias declares no `write`, and the live spec is the reason.** `extra` is "Scheme-specific additional
+ * information" — the payment scheme's object, whose contents that scheme defines. An `atrHash` is READ there
+ * because sellers put one there; writing into another party's namespace is not the same act. The
+ * `extensions` map is the protocol's own declared extension point and is where `place` writes.
+ *
+ * **The alias is index 0 only.** A locator names one path. `accepts[0]` is what buyer parsers read, and the
+ * reason is substantive: the reference must bind to the requirement actually being paid, and searching every
+ * requirement would let a seller park a second set of terms on an alternative it never expects to be chosen.
+ *
+ * **`termsUrlField` is DECLARED — this is the protocol whose wire carries both halves.** `binding-core`'s own
+ * contract cites x402 for exactly that: a buyer-side parser may demand the URL because x402 carries it, and
+ * emitters put `legalContextUrl` inside `info` beside `type`/`value`. Declaring the path
+ * makes that half machine-readable instead of a second private convention; `place` never writes it, because
+ * `place(ref, doc)` holds one reference and the terms URL is a different datum (the same division ACP draws
+ * with `metadata.legal_context_url`). The shipped carrier repeats the URL at `accepts[0].extra.legalContextUrl`
+ * too, which a single `termsUrlField` cannot express — recorded in the README as a known limitation rather
+ * than half-declared here.
+ *
+ * **`carrierTypes` permits `sha256` and `url`, and the two are admitted on DIFFERENT grounds** — one reason
+ * cannot cover both. `sha256` is the integrity carrier: §C.4's illustration carries one, emitters carry one,
+ * and the bare alias is fixed to it. `url` is the §8.1 discovery form, admitted because the canonical
+ * slot is a general reference-object slot and the kit puts the integrity-versus-discovery decision at the
+ * READER — `carrierClass` plus `requireIntegrity` — not in the permission list; ACP and UCP permit it for the
+ * same reason. `ipfs`/`ar` are excluded on a ground that does NOT apply to `url`: they are ALTERNATIVE
+ * integrity carriers, so admitting one adds no capability `sha256` does not already discharge while
+ * advertising a content-addressed transport no x402 counterparty resolves — a claim about the ecosystem
+ * rather than a description of it.
+ *
+ * The `url` permission is nonetheless WIDER than any shipped x402 reader: a buyer parser that requires an
+ * integrity carrier refuses `info.type !== "sha256"` outright, so a `url` placed in this slot is well-formed
+ * against this manifest and would still be rejected at read time. Recorded in the README as a limitation
+ * rather than narrowed away here, because narrowing the reference field to one type is a change to what the
+ * SLOT may hold across the set, not a fact about x402.
+ */
+export declare const X402_PLACEMENT: PlacementManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuB/D,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,eAAO,MAAM,cAAc,EAAE,iBAkB5B,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,138 @@
+/**
+ * The carrier's JSON Schema, INLINED rather than referenced.
+ *
+ * x402 makes `schema` a REQUIRED member of an extension entry — "JSON Schema defining the expected
+ * structure of info" — so whatever goes here is on the wire of every challenge. A `$ref` to a URL nobody
+ * serves would be a required member no counterparty can resolve, and "x402 never fetches it" is a reason
+ * that does not break, not a reason to ship it. (`https://legalcontextprotocol.org/schemas/lcp-extension.json`
+ * returns **404**, measured 2026-08-08 — the schema is inlined instead.)
+ *
+ * **Both extensions published in the x402 repository inline a complete JSON Schema** rather than
+ * referencing an external document, and LCP v1.38 §C.4 says to do one or the other: "Because `schema` is a
+ * REQUIRED member, publish a resolvable schema or inline it." Inlining also removes a hosting dependency
+ * the deployment does not currently meet — the same dependency the UCP capability still owes.
+ *
+ * The shape is the §8.1 reference object this placement writes into `info`, and nothing more: it describes
+ * the carrier, not the terms behind it.
+ *
+ * Changing this is a WIRE change — it appears in every challenge — so it is a frozen literal rather than a
+ * value assembled at call time.
+ */
+export const LEGAL_CONTEXT_SCHEMA = Object.freeze({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "LCP legal-context reference",
+    description: "A Legal Context Protocol reference to the terms governing this transaction. The reference identifies the exact terms document; it is not the terms.",
+    type: "object",
+    required: ["type", "value"],
+    additionalProperties: false,
+    properties: {
+        type: {
+            type: "string",
+            enum: ["sha256", "url", "ipfs", "ar"],
+            description: "Carrier type. sha256, ipfs and ar are content-addressed and bear integrity; url only locates a document.",
+        },
+        value: {
+            type: "string",
+            minLength: 1,
+            description: "The reference itself — for sha256, a 0x-prefixed lowercase 32-byte hex digest of the complete ATR file.",
+        },
+    },
+});
+/**
+ * x402 reference placement — the HTTP-layer carrier, cut against the live x402 v2 specification
+ * (`x402-foundation/x402@1fec3aa04e41`, `specs/x402-specification-v2.md`; gate discharged in the README).
+ *
+ * **THE CANONICAL REPOSITORY IS THE FOUNDATION'S, and the citation moved on 2026-08-08.** Every
+ * reference here named `coinbase/x402`, which the GitHub API reports as `"fork": true`;
+ * `x402-foundation/x402` is `"fork": false` and is what LCP v1.38 §C.4's own *Checked against* line
+ * reads. Citing a fork invites a reader to diff against a copy that may lag. The revision is pinned
+ * rather than left as a bare repo name, because "the live spec" with no commit is not a claim anyone
+ * can re-check.
+ *
+ * **This is NOT the x402 weld.** `@integraledger/lcp-binding-evm-x402` binds `atrHash` into the EIP-3009 nonce —
+ * that is the SETTLEMENT binding and it answers "what did the money commit to?". This manifest answers a
+ * different question — "where does the reference ride on the wire?" — and both are true at once. x402 is the
+ * proof that one protocol can need a binding AND a placement.
+ *
+ * **Tier A in both slots, and the canonical one is the map the protocol PROTECTS.** x402 v2 defines a
+ * per-requirement `accepts[].extra` object and a top-level `extensions` map, the latter carried on the
+ * `PaymentRequired` challenge, the `PaymentPayload` AND the `SettlementResponse` — so a reference placed
+ * there is on the receipt, not only the proposal. Each `extensions` entry carries `info` ("Extension-specific
+ * data provided by the server") and `schema` ("JSON Schema defining the expected structure of `info`"). The
+ * live spec's echo rule — "The client must include at least the info received; it may append additional info
+ * but cannot delete or overwrite existing info" — is what makes that map the more durable carrier, and it is
+ * why it is canonical here.
+ *
+ * **`pattern` is `http-advisory`, not `protocol-extension`.** §8.3.6 means the HOST protocol's own
+ * verification and settlement procedure understands the hash; no x402 facilitator does. It is also Tier B by
+ * definition, which would misdescribe a carrier that works today against stock x402 — extension identifiers
+ * are implementation-defined strings, so no registration gates this. The same determination is made for ACP
+ * and UCP. §C.4's Tier B forward paths (a reference inside the signed Offer/Receipt artifact; a registered
+ * extension identifier) are declared in the README as prose and in NO manifest — asserting a shape whose
+ * owner has not defined it is the asserting-a-shape defect.
+ *
+ * **The extension key is `legalContext`, deliberately not a reverse-domain name.** x402 imposes no namespace
+ * rule, and `legalContext` is the spelling emitters put on the wire, the spelling buyer parsers read, and the
+ * one LCP v1.38 §C.4's own illustration shows. The `com.integraledger.*` reverse-domain namespace applies to
+ * hosts that REQUIRE one — UCP does; x402 does not — and renaming this key to suit a convention x402 does not
+ * have would put a spelling on the wire that no counterparty reads.
+ *
+ * **The alias carries a DIFFERENT SHAPE, and x402 is the only protocol in the set where that is true.** The
+ * canonical slot holds a §8.1 object; `accepts[0].extra.atrHash` holds a **bare** hash — that is the form
+ * emitters write there and the form x402 integrators recognize. Writing an `lcp:` string into `extra.atrHash`
+ * would emit something no x402 counterparty parses. This is the reason an alias declares its own `encoding`
+ * at all.
+ *
+ * **The alias declares no `write`, and the live spec is the reason.** `extra` is "Scheme-specific additional
+ * information" — the payment scheme's object, whose contents that scheme defines. An `atrHash` is READ there
+ * because sellers put one there; writing into another party's namespace is not the same act. The
+ * `extensions` map is the protocol's own declared extension point and is where `place` writes.
+ *
+ * **The alias is index 0 only.** A locator names one path. `accepts[0]` is what buyer parsers read, and the
+ * reason is substantive: the reference must bind to the requirement actually being paid, and searching every
+ * requirement would let a seller park a second set of terms on an alternative it never expects to be chosen.
+ *
+ * **`termsUrlField` is DECLARED — this is the protocol whose wire carries both halves.** `binding-core`'s own
+ * contract cites x402 for exactly that: a buyer-side parser may demand the URL because x402 carries it, and
+ * emitters put `legalContextUrl` inside `info` beside `type`/`value`. Declaring the path
+ * makes that half machine-readable instead of a second private convention; `place` never writes it, because
+ * `place(ref, doc)` holds one reference and the terms URL is a different datum (the same division ACP draws
+ * with `metadata.legal_context_url`). The shipped carrier repeats the URL at `accepts[0].extra.legalContextUrl`
+ * too, which a single `termsUrlField` cannot express — recorded in the README as a known limitation rather
+ * than half-declared here.
+ *
+ * **`carrierTypes` permits `sha256` and `url`, and the two are admitted on DIFFERENT grounds** — one reason
+ * cannot cover both. `sha256` is the integrity carrier: §C.4's illustration carries one, emitters carry one,
+ * and the bare alias is fixed to it. `url` is the §8.1 discovery form, admitted because the canonical
+ * slot is a general reference-object slot and the kit puts the integrity-versus-discovery decision at the
+ * READER — `carrierClass` plus `requireIntegrity` — not in the permission list; ACP and UCP permit it for the
+ * same reason. `ipfs`/`ar` are excluded on a ground that does NOT apply to `url`: they are ALTERNATIVE
+ * integrity carriers, so admitting one adds no capability `sha256` does not already discharge while
+ * advertising a content-addressed transport no x402 counterparty resolves — a claim about the ecosystem
+ * rather than a description of it.
+ *
+ * The `url` permission is nonetheless WIDER than any shipped x402 reader: a buyer parser that requires an
+ * integrity carrier refuses `info.type !== "sha256"` outright, so a `url` placed in this slot is well-formed
+ * against this manifest and would still be rejected at read time. Recorded in the README as a limitation
+ * rather than narrowed away here, because narrowing the reference field to one type is a change to what the
+ * SLOT may hold across the set, not a fact about x402.
+ */
+export const X402_PLACEMENT = {
+    protocol: "x402",
+    pattern: "http-advisory",
+    tier: "A",
+    encoding: "reference-object",
+    container: { kind: "object-path" },
+    field: "extensions.legalContext.info",
+    readAlso: [
+        {
+            path: "accepts.0.extra.atrHash",
+            encoding: "bare-value",
+            bareType: "sha256",
+        },
+    ],
+    termsUrlField: "extensions.legalContext.info.legalContextUrl",
+    carrierTypes: ["sha256", "url"],
+    specRef: "x402 v2 (x402-foundation/x402@1fec3aa04e41 specs/x402-specification-v2.md, read 2026-07-30) — top-level extensions map carried on PaymentRequired/PaymentPayload/SettlementResponse, each entry {info, schema}; accepts[].extra is scheme-specific (gate discharged: see README)",
+};
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,MAAM,CAAC,MAAM,CAAC;IACZ,OAAO,EAAE,8CAA8C;IACvD,KAAK,EAAE,6BAA6B;IACpC,WAAW,EACT,qJAAqJ;IACvJ,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC;YACrC,WAAW,EACT,0GAA0G;SAC7G;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,CAAC;YACZ,WAAW,EACT,yGAAyG;SAC5G;KACF;CACF,CAAC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,QAAQ,EAAE,MAAM;IAChB,OAAO,EAAE,eAAe;IACxB,IAAI,EAAE,GAAG;IACT,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE;IAClC,KAAK,EAAE,8BAA8B;IACrC,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,yBAAyB;YAC/B,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,QAAQ;SACnB;KACF;IACD,aAAa,EAAE,8CAA8C;IAC7D,YAAY,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;IAC/B,OAAO,EACL,kRAAkR;CACrR,CAAC"}

package/dist/placement.d.ts

@@ -0,0 +1,16 @@
+import { type ReferencePlacementAdapter } from "@integraledger/lcp-binding-core";
+/**
+ * The x402 reference placement — the kit's `extract`, and the ONE `place` in the set that the kit cannot
+ * supply.
+ *
+ * x402's slot does not hold the reference directly: it holds `{ info, schema }`, where `info` is the §8.1
+ * reference object and `schema` is a `$ref` pointing at the carrier schema. That is a WRAPPER, and no
+ * container kind models it. Inventing an `x402-extension` container kind would put one protocol's name inside
+ * a generic enum — the abstraction leaking — so the write half is overridden here, in this package, where it
+ * is reviewed like any other code. `extract` is the kit's unchanged: reading `extensions.legalContext.info` is
+ * an ordinary object-path read, and the bare-hash alias at `accepts.0.extra.atrHash` is handled by its own
+ * declared encoding (S2/S6). One overridden member is composition; a second would mean this package had
+ * stopped using the kit, and the test suite says so.
+ */
+export declare const x402Placement: ReferencePlacementAdapter;
+//# sourceMappingURL=placement.d.ts.map

package/dist/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,yBAAyB,EAC/B,MAAM,iCAAiC,CAAC;AAgBzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,EAAE,yBA+E3B,CAAC"}

package/dist/placement.js

@@ -0,0 +1,91 @@
+import { CarrierError, encodeForField, makePlacement, } from "@integraledger/lcp-binding-core";
+import { LEGAL_CONTEXT_SCHEMA, X402_PLACEMENT } from "./manifest.js";
+const base = makePlacement(X402_PLACEMENT);
+/** Refusals namespaced from the protocol id, exactly as the kit does — so `x402/document-malformed` means the
+ *  same thing whether it came from the override or from the generic read path. */
+function refuse(code, detail) {
+    return {
+        refused: true,
+        haltClass: "verification-failure",
+        code: `x402/${code}`,
+        detail,
+    };
+}
+/**
+ * The x402 reference placement — the kit's `extract`, and the ONE `place` in the set that the kit cannot
+ * supply.
+ *
+ * x402's slot does not hold the reference directly: it holds `{ info, schema }`, where `info` is the §8.1
+ * reference object and `schema` is a `$ref` pointing at the carrier schema. That is a WRAPPER, and no
+ * container kind models it. Inventing an `x402-extension` container kind would put one protocol's name inside
+ * a generic enum — the abstraction leaking — so the write half is overridden here, in this package, where it
+ * is reviewed like any other code. `extract` is the kit's unchanged: reading `extensions.legalContext.info` is
+ * an ordinary object-path read, and the bare-hash alias at `accepts.0.extra.atrHash` is handled by its own
+ * declared encoding (S2/S6). One overridden member is composition; a second would mean this package had
+ * stopped using the kit, and the test suite says so.
+ */
+export const x402Placement = {
+    ...base,
+    place(ref, doc) {
+        if (!X402_PLACEMENT.carrierTypes.includes(ref.type))
+            return refuse("carrier-type-not-permitted", `${X402_PLACEMENT.field} permits ${X402_PLACEMENT.carrierTypes.join("/")}, got ${ref.type}`);
+        if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+            return refuse("document-malformed", "an x402 challenge is a non-null object");
+        // Rendered through the codec, never by interpolation — a value that does not meet its type's rule refuses
+        // here instead of putting an extension on the wire that a buyer's parser would reject.
+        let encoded;
+        try {
+            encoded = encodeForField(ref, X402_PLACEMENT.encoding);
+        }
+        catch (e) {
+            if (!(e instanceof CarrierError))
+                throw e; // never swallow a non-carrier bug
+            return refuse("reference-malformed", `not a valid carrier value for its type: ${ref.value}`);
+        }
+        // OWN PROPERTY ONLY. `place`'s document is exactly as attacker-influenced as `extract`'s, so a challenge
+        // with ZERO own properties must not walk into its prototype's `extensions` and put those entries on the
+        // wire — `extract` reports that document as `reference-absent`, and the two halves have to agree about
+        // what is present. binding-core's own writer states the rule and proves it for the generic path; the
+        // override is the one write path that has to restate it. The DECLARED view rather than a
+        // `Record<string, unknown>` is deliberate: reading `extensions` off an index signature is TS4111, and the
+        // bracket form biome would then ask for is the fix it classes as unsafe. The document is still spread
+        // wholesale below, so nothing is narrowed away.
+        const ext = Object.hasOwn(doc, "extensions")
+            ? doc.extensions
+            : undefined;
+        // Sibling extensions are PRESERVED: the live x402 v2 spec states a client "must include at least the info
+        // received; it may append additional info but cannot delete or overwrite existing info". That is the host
+        // protocol's rule about its own map, and a placement that pruned a sibling would make the client
+        // using it non-conformant.
+        //
+        // An `extensions` that is PRESENT but cannot be merged into REFUSES, and that is binding-core's ratified
+        // malformed-container rule read against the manifest this package PUBLISHES rather than against the
+        // granularity the override happens to write at: `field` is `extensions.legalContext.info`, so `legalContext`
+        // is the field's direct holder and `extensions` sits one level ABOVE it — replaced at the holder, refused
+        // above it, because replacing an intermediate discards everything beneath it. A stranger holding only the
+        // manifest and the kit computes that refusal for the same document, and an override that emitted a
+        // challenge instead would make the manifest a description rather than an artifact. ABSENT is still
+        // created; our own entry, being the direct holder, is still replaced.
+        const siblings = ext === undefined
+            ? {}
+            : typeof ext === "object" && ext !== null && !Array.isArray(ext)
+                ? ext
+                : undefined;
+        if (siblings === undefined)
+            return refuse("document-malformed", `extensions is present and is not a map, so ${X402_PLACEMENT.field} has no holder to write into: ${JSON.stringify(ext)}`);
+        return {
+            ok: true,
+            value: {
+                ...doc,
+                extensions: {
+                    ...siblings,
+                    legalContext: {
+                        info: encoded,
+                        schema: LEGAL_CONTEXT_SCHEMA,
+                    },
+                },
+            },
+        };
+    },
+};
+//# sourceMappingURL=placement.js.map

package/dist/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,cAAc,EAEd,aAAa,GAGd,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE,MAAM,IAAI,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;AAE3C;kFACkF;AAClF,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,OAAO;QACL,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,sBAAsB;QACjC,IAAI,EAAE,QAAQ,IAAI,EAAE;QACpB,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAA8B;IACtD,GAAG,IAAI;IAEP,KAAK,CAAC,GAAoB,EAAE,GAAY;QACtC,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YACjD,OAAO,MAAM,CACX,4BAA4B,EAC5B,GAAG,cAAc,CAAC,KAAK,YAAY,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,CAAC,IAAI,EAAE,CAC5F,CAAC;QACJ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAC/D,OAAO,MAAM,CACX,oBAAoB,EACpB,wCAAwC,CACzC,CAAC;QAEJ,0GAA0G;QAC1G,uFAAuF;QACvF,IAAI,OAAgB,CAAC;QACrB,IAAI,CAAC;YACH,OAAO,GAAG,cAAc,CAAC,GAAG,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,CAAC,CAAC,YAAY,YAAY,CAAC;gBAAE,MAAM,CAAC,CAAC,CAAC,kCAAkC;YAC7E,OAAO,MAAM,CACX,qBAAqB,EACrB,2CAA2C,GAAG,CAAC,KAAK,EAAE,CACvD,CAAC;QACJ,CAAC;QAED,yGAAyG;QACzG,wGAAwG;QACxG,uGAAuG;QACvG,qGAAqG;QACrG,yFAAyF;QACzF,0GAA0G;QAC1G,sGAAsG;QACtG,gDAAgD;QAChD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,YAAY,CAAC;YAC1C,CAAC,CAAE,GAAyC,CAAC,UAAU;YACvD,CAAC,CAAC,SAAS,CAAC;QAEd,0GAA0G;QAC1G,0GAA0G;QAC1G,iGAAiG;QACjG,2BAA2B;QAC3B,EAAE;QACF,yGAAyG;QACzG,oGAAoG;QACpG,6GAA6G;QAC7G,0GAA0G;QAC1G,0GAA0G;QAC1G,mGAAmG;QACnG,mGAAmG;QACnG,sEAAsE;QACtE,MAAM,QAAQ,GACZ,GAAG,KAAK,SAAS;YACf,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;gBAC9D,CAAC,CAAE,GAA+B;gBAClC,CAAC,CAAC,SAAS,CAAC;QAClB,IAAI,QAAQ,KAAK,SAAS;YACxB,OAAO,MAAM,CACX,oBAAoB,EACpB,8CAA8C,cAAc,CAAC,KAAK,iCAAiC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CACzH,CAAC;QAEJ,OAAO;YACL,EAAE,EAAE,IAAI;YACR,KAAK,EAAE;gBACL,GAAI,GAAc;gBAClB,UAAU,EAAE;oBACV,GAAG,QAAQ;oBACX,YAAY,EAAE;wBACZ,IAAI,EAAE,OAAO;wBACb,MAAM,EAAE,oBAAoB;qBAC7B;iBACF;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@integraledger/lcp-placement-x402",
+  "version": "0.9.0",
+  "description": "Places an LCP reference into an x402 v2 payment challenge, and reads it back.",
+  "keywords": [
+    "lcp",
+    "legal-context-protocol",
+    "legal-terms",
+    "agentic-commerce",
+    "placement",
+    "x402"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "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-protocol.git",
+    "directory": "packages/placement-x402"
+  },
+  "bugs": {
+    "url": "https://github.com/IntegraLedger/integra-protocol/issues"
+  },
+  "homepage": "https://github.com/IntegraLedger/integra-protocol/tree/main/packages/placement-x402#readme",
+  "dependencies": {
+    "@integraledger/lcp-binding-core": "0.9.0"
+  },
+  "devDependencies": {
+    "@cfworker/json-schema": "4.1.1",
+    "@types/node": "24.13.3",
+    "vitest": "4.1.10"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { LEGAL_CONTEXT_SCHEMA, X402_PLACEMENT } from "./manifest.js";
+export { x402Placement } from "./placement.js";

package/src/manifest.ts

@@ -0,0 +1,145 @@
+import type { PlacementManifest } from "@integraledger/lcp-binding-core";
+
+/**
+ * The carrier's JSON Schema, INLINED rather than referenced.
+ *
+ * x402 makes `schema` a REQUIRED member of an extension entry — "JSON Schema defining the expected
+ * structure of info" — so whatever goes here is on the wire of every challenge. A `$ref` to a URL nobody
+ * serves would be a required member no counterparty can resolve, and "x402 never fetches it" is a reason
+ * that does not break, not a reason to ship it. (`https://legalcontextprotocol.org/schemas/lcp-extension.json`
+ * returns **404**, measured 2026-08-08 — the schema is inlined instead.)
+ *
+ * **Both extensions published in the x402 repository inline a complete JSON Schema** rather than
+ * referencing an external document, and LCP v1.38 §C.4 says to do one or the other: "Because `schema` is a
+ * REQUIRED member, publish a resolvable schema or inline it." Inlining also removes a hosting dependency
+ * the deployment does not currently meet — the same dependency the UCP capability still owes.
+ *
+ * The shape is the §8.1 reference object this placement writes into `info`, and nothing more: it describes
+ * the carrier, not the terms behind it.
+ *
+ * Changing this is a WIRE change — it appears in every challenge — so it is a frozen literal rather than a
+ * value assembled at call time.
+ */
+export const LEGAL_CONTEXT_SCHEMA: Readonly<Record<string, unknown>> =
+  Object.freeze({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "LCP legal-context reference",
+    description:
+      "A Legal Context Protocol reference to the terms governing this transaction. The reference identifies the exact terms document; it is not the terms.",
+    type: "object",
+    required: ["type", "value"],
+    additionalProperties: false,
+    properties: {
+      type: {
+        type: "string",
+        enum: ["sha256", "url", "ipfs", "ar"],
+        description:
+          "Carrier type. sha256, ipfs and ar are content-addressed and bear integrity; url only locates a document.",
+      },
+      value: {
+        type: "string",
+        minLength: 1,
+        description:
+          "The reference itself — for sha256, a 0x-prefixed lowercase 32-byte hex digest of the complete ATR file.",
+      },
+    },
+  });
+
+/**
+ * x402 reference placement — the HTTP-layer carrier, cut against the live x402 v2 specification
+ * (`x402-foundation/x402@1fec3aa04e41`, `specs/x402-specification-v2.md`; gate discharged in the README).
+ *
+ * **THE CANONICAL REPOSITORY IS THE FOUNDATION'S, and the citation moved on 2026-08-08.** Every
+ * reference here named `coinbase/x402`, which the GitHub API reports as `"fork": true`;
+ * `x402-foundation/x402` is `"fork": false` and is what LCP v1.38 §C.4's own *Checked against* line
+ * reads. Citing a fork invites a reader to diff against a copy that may lag. The revision is pinned
+ * rather than left as a bare repo name, because "the live spec" with no commit is not a claim anyone
+ * can re-check.
+ *
+ * **This is NOT the x402 weld.** `@integraledger/lcp-binding-evm-x402` binds `atrHash` into the EIP-3009 nonce —
+ * that is the SETTLEMENT binding and it answers "what did the money commit to?". This manifest answers a
+ * different question — "where does the reference ride on the wire?" — and both are true at once. x402 is the
+ * proof that one protocol can need a binding AND a placement.
+ *
+ * **Tier A in both slots, and the canonical one is the map the protocol PROTECTS.** x402 v2 defines a
+ * per-requirement `accepts[].extra` object and a top-level `extensions` map, the latter carried on the
+ * `PaymentRequired` challenge, the `PaymentPayload` AND the `SettlementResponse` — so a reference placed
+ * there is on the receipt, not only the proposal. Each `extensions` entry carries `info` ("Extension-specific
+ * data provided by the server") and `schema` ("JSON Schema defining the expected structure of `info`"). The
+ * live spec's echo rule — "The client must include at least the info received; it may append additional info
+ * but cannot delete or overwrite existing info" — is what makes that map the more durable carrier, and it is
+ * why it is canonical here.
+ *
+ * **`pattern` is `http-advisory`, not `protocol-extension`.** §8.3.6 means the HOST protocol's own
+ * verification and settlement procedure understands the hash; no x402 facilitator does. It is also Tier B by
+ * definition, which would misdescribe a carrier that works today against stock x402 — extension identifiers
+ * are implementation-defined strings, so no registration gates this. The same determination is made for ACP
+ * and UCP. §C.4's Tier B forward paths (a reference inside the signed Offer/Receipt artifact; a registered
+ * extension identifier) are declared in the README as prose and in NO manifest — asserting a shape whose
+ * owner has not defined it is the asserting-a-shape defect.
+ *
+ * **The extension key is `legalContext`, deliberately not a reverse-domain name.** x402 imposes no namespace
+ * rule, and `legalContext` is the spelling emitters put on the wire, the spelling buyer parsers read, and the
+ * one LCP v1.38 §C.4's own illustration shows. The `com.integraledger.*` reverse-domain namespace applies to
+ * hosts that REQUIRE one — UCP does; x402 does not — and renaming this key to suit a convention x402 does not
+ * have would put a spelling on the wire that no counterparty reads.
+ *
+ * **The alias carries a DIFFERENT SHAPE, and x402 is the only protocol in the set where that is true.** The
+ * canonical slot holds a §8.1 object; `accepts[0].extra.atrHash` holds a **bare** hash — that is the form
+ * emitters write there and the form x402 integrators recognize. Writing an `lcp:` string into `extra.atrHash`
+ * would emit something no x402 counterparty parses. This is the reason an alias declares its own `encoding`
+ * at all.
+ *
+ * **The alias declares no `write`, and the live spec is the reason.** `extra` is "Scheme-specific additional
+ * information" — the payment scheme's object, whose contents that scheme defines. An `atrHash` is READ there
+ * because sellers put one there; writing into another party's namespace is not the same act. The
+ * `extensions` map is the protocol's own declared extension point and is where `place` writes.
+ *
+ * **The alias is index 0 only.** A locator names one path. `accepts[0]` is what buyer parsers read, and the
+ * reason is substantive: the reference must bind to the requirement actually being paid, and searching every
+ * requirement would let a seller park a second set of terms on an alternative it never expects to be chosen.
+ *
+ * **`termsUrlField` is DECLARED — this is the protocol whose wire carries both halves.** `binding-core`'s own
+ * contract cites x402 for exactly that: a buyer-side parser may demand the URL because x402 carries it, and
+ * emitters put `legalContextUrl` inside `info` beside `type`/`value`. Declaring the path
+ * makes that half machine-readable instead of a second private convention; `place` never writes it, because
+ * `place(ref, doc)` holds one reference and the terms URL is a different datum (the same division ACP draws
+ * with `metadata.legal_context_url`). The shipped carrier repeats the URL at `accepts[0].extra.legalContextUrl`
+ * too, which a single `termsUrlField` cannot express — recorded in the README as a known limitation rather
+ * than half-declared here.
+ *
+ * **`carrierTypes` permits `sha256` and `url`, and the two are admitted on DIFFERENT grounds** — one reason
+ * cannot cover both. `sha256` is the integrity carrier: §C.4's illustration carries one, emitters carry one,
+ * and the bare alias is fixed to it. `url` is the §8.1 discovery form, admitted because the canonical
+ * slot is a general reference-object slot and the kit puts the integrity-versus-discovery decision at the
+ * READER — `carrierClass` plus `requireIntegrity` — not in the permission list; ACP and UCP permit it for the
+ * same reason. `ipfs`/`ar` are excluded on a ground that does NOT apply to `url`: they are ALTERNATIVE
+ * integrity carriers, so admitting one adds no capability `sha256` does not already discharge while
+ * advertising a content-addressed transport no x402 counterparty resolves — a claim about the ecosystem
+ * rather than a description of it.
+ *
+ * The `url` permission is nonetheless WIDER than any shipped x402 reader: a buyer parser that requires an
+ * integrity carrier refuses `info.type !== "sha256"` outright, so a `url` placed in this slot is well-formed
+ * against this manifest and would still be rejected at read time. Recorded in the README as a limitation
+ * rather than narrowed away here, because narrowing the reference field to one type is a change to what the
+ * SLOT may hold across the set, not a fact about x402.
+ */
+export const X402_PLACEMENT: PlacementManifest = {
+  protocol: "x402",
+  pattern: "http-advisory",
+  tier: "A",
+  encoding: "reference-object",
+  container: { kind: "object-path" },
+  field: "extensions.legalContext.info",
+  readAlso: [
+    {
+      path: "accepts.0.extra.atrHash",
+      encoding: "bare-value",
+      bareType: "sha256",
+    },
+  ],
+  termsUrlField: "extensions.legalContext.info.legalContextUrl",
+  carrierTypes: ["sha256", "url"],
+  specRef:
+    "x402 v2 (x402-foundation/x402@1fec3aa04e41 specs/x402-specification-v2.md, read 2026-07-30) — top-level extensions map carried on PaymentRequired/PaymentPayload/SettlementResponse, each entry {info, schema}; accepts[].extra is scheme-specific (gate discharged: see README)",
+};

package/src/placement.ts

@@ -0,0 +1,116 @@
+import {
+  CarrierError,
+  encodeForField,
+  type LegalContextRef,
+  makePlacement,
+  type Outcome,
+  type ReferencePlacementAdapter,
+} from "@integraledger/lcp-binding-core";
+import { LEGAL_CONTEXT_SCHEMA, X402_PLACEMENT } from "./manifest.js";
+
+const base = makePlacement(X402_PLACEMENT);
+
+/** Refusals namespaced from the protocol id, exactly as the kit does — so `x402/document-malformed` means the
+ *  same thing whether it came from the override or from the generic read path. */
+function refuse(code: string, detail: string): Outcome<never> {
+  return {
+    refused: true,
+    haltClass: "verification-failure",
+    code: `x402/${code}`,
+    detail,
+  };
+}
+
+/**
+ * The x402 reference placement — the kit's `extract`, and the ONE `place` in the set that the kit cannot
+ * supply.
+ *
+ * x402's slot does not hold the reference directly: it holds `{ info, schema }`, where `info` is the §8.1
+ * reference object and `schema` is a `$ref` pointing at the carrier schema. That is a WRAPPER, and no
+ * container kind models it. Inventing an `x402-extension` container kind would put one protocol's name inside
+ * a generic enum — the abstraction leaking — so the write half is overridden here, in this package, where it
+ * is reviewed like any other code. `extract` is the kit's unchanged: reading `extensions.legalContext.info` is
+ * an ordinary object-path read, and the bare-hash alias at `accepts.0.extra.atrHash` is handled by its own
+ * declared encoding (S2/S6). One overridden member is composition; a second would mean this package had
+ * stopped using the kit, and the test suite says so.
+ */
+export const x402Placement: ReferencePlacementAdapter = {
+  ...base,
+
+  place(ref: LegalContextRef, doc: unknown): Outcome<unknown> {
+    if (!X402_PLACEMENT.carrierTypes.includes(ref.type))
+      return refuse(
+        "carrier-type-not-permitted",
+        `${X402_PLACEMENT.field} permits ${X402_PLACEMENT.carrierTypes.join("/")}, got ${ref.type}`,
+      );
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+      return refuse(
+        "document-malformed",
+        "an x402 challenge is a non-null object",
+      );
+
+    // Rendered through the codec, never by interpolation — a value that does not meet its type's rule refuses
+    // here instead of putting an extension on the wire that a buyer's parser would reject.
+    let encoded: unknown;
+    try {
+      encoded = encodeForField(ref, X402_PLACEMENT.encoding);
+    } catch (e) {
+      if (!(e instanceof CarrierError)) throw e; // never swallow a non-carrier bug
+      return refuse(
+        "reference-malformed",
+        `not a valid carrier value for its type: ${ref.value}`,
+      );
+    }
+
+    // OWN PROPERTY ONLY. `place`'s document is exactly as attacker-influenced as `extract`'s, so a challenge
+    // with ZERO own properties must not walk into its prototype's `extensions` and put those entries on the
+    // wire — `extract` reports that document as `reference-absent`, and the two halves have to agree about
+    // what is present. binding-core's own writer states the rule and proves it for the generic path; the
+    // override is the one write path that has to restate it. The DECLARED view rather than a
+    // `Record<string, unknown>` is deliberate: reading `extensions` off an index signature is TS4111, and the
+    // bracket form biome would then ask for is the fix it classes as unsafe. The document is still spread
+    // wholesale below, so nothing is narrowed away.
+    const ext = Object.hasOwn(doc, "extensions")
+      ? (doc as { readonly extensions?: unknown }).extensions
+      : undefined;
+
+    // Sibling extensions are PRESERVED: the live x402 v2 spec states a client "must include at least the info
+    // received; it may append additional info but cannot delete or overwrite existing info". That is the host
+    // protocol's rule about its own map, and a placement that pruned a sibling would make the client
+    // using it non-conformant.
+    //
+    // An `extensions` that is PRESENT but cannot be merged into REFUSES, and that is binding-core's ratified
+    // malformed-container rule read against the manifest this package PUBLISHES rather than against the
+    // granularity the override happens to write at: `field` is `extensions.legalContext.info`, so `legalContext`
+    // is the field's direct holder and `extensions` sits one level ABOVE it — replaced at the holder, refused
+    // above it, because replacing an intermediate discards everything beneath it. A stranger holding only the
+    // manifest and the kit computes that refusal for the same document, and an override that emitted a
+    // challenge instead would make the manifest a description rather than an artifact. ABSENT is still
+    // created; our own entry, being the direct holder, is still replaced.
+    const siblings =
+      ext === undefined
+        ? {}
+        : typeof ext === "object" && ext !== null && !Array.isArray(ext)
+          ? (ext as Record<string, unknown>)
+          : undefined;
+    if (siblings === undefined)
+      return refuse(
+        "document-malformed",
+        `extensions is present and is not a map, so ${X402_PLACEMENT.field} has no holder to write into: ${JSON.stringify(ext)}`,
+      );
+
+    return {
+      ok: true,
+      value: {
+        ...(doc as object),
+        extensions: {
+          ...siblings,
+          legalContext: {
+            info: encoded,
+            schema: LEGAL_CONTEXT_SCHEMA,
+          },
+        },
+      },
+    };
+  },
+};