@integraledger/terms 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,7 +4,7 @@ The buyer gate for agents that pay: before your wallet signs anything, it confir
4
4
  hashes to the value the payment will carry, and builds the payment with that hash.
5
5
 
6
6
  ```sh
7
- npm install @integraledger/terms@0.3.0 @integraledger/lcp@0.4.0
7
+ npm install @integraledger/terms@0.3.1 @integraledger/lcp@0.4.2
8
8
  ```
9
9
 
10
10
  ## What it is
@@ -47,15 +47,15 @@ agent approved, to the agreement URL.
47
47
  ## Install
48
48
 
49
49
  ```sh
50
- npm install @integraledger/terms@0.3.0 @integraledger/lcp@0.4.0
50
+ npm install @integraledger/terms@0.3.1 @integraledger/lcp@0.4.2
51
51
  ```
52
52
 
53
53
  - Node.js `>=26.11.1`. ESM only.
54
- - `@integraledger/lcp` is a peer dependency of this package (`~0.4.0`): install it beside it, so your application and
54
+ - `@integraledger/lcp` is a peer dependency of this package (`~0.4.2`): install it beside it, so your application and
55
55
  the gate share one copy, and import from it the bindings you pass in.
56
56
  - Chain libraries are optional peers of `@integraledger/lcp`: `@mysten/sui`, `@solana/kit`, `@stellar/stellar-sdk`,
57
- `@ton/core`, `algosdk`, `borsh`, `near-api-js` and `ripple-binary-codec`, at the versions `@integraledger/lcp`
58
- names. Install the ones the pairings you pay use.
57
+ `@ton/core`, `algosdk`, `borsh` and `ripple-binary-codec`, at the versions `@integraledger/lcp` names. Install the
58
+ ones the pairings you pay use.
59
59
 
60
60
  ## Quickstart
61
61
 
@@ -397,9 +397,11 @@ names another channel or another H, and signs one with no legal context under th
397
397
 
398
398
  ### Confirm a payment later: `check`
399
399
 
400
- `check(bytes, presented, binding)` confirms that the ATR hash the pairing reads from a payment you hold is the SHA-256
401
- of the bytes you kept. A payment from which the pairing reads no ATR hash is declined `signed-not-bound`. Where `finish`
402
- or `transact` returned `landed`, put it back into the payment as `landed` first.
400
+ `check(bytes, presented, binding, landed?)` confirms that the ATR hash the pairing reads from a payment you hold is the
401
+ SHA-256 of the bytes you kept. A payment from which the pairing reads no ATR hash is declined `signed-not-bound`. Where
402
+ `finish` or `transact` returned `landed`, pass it as `landed`, beside the payment: a `landed` member written into the
403
+ payment is not read. The caller passes as `landed` only the receipt its own reader read for the payment, as `finish` or
404
+ `transact` returned it, never a value another party sent.
403
405
 
404
406
  ### Declines and `moved`
405
407
 
@@ -458,7 +460,7 @@ Everything below is exported from `@integraledger/terms`.
458
460
  | `AgreementPayment` | The agreement payment to approve: `{ url, option, required }`. |
459
461
  | `ToApprove` | `{ approve: AgreementPayment; bytes; h }`. |
460
462
  | `AgreementReceipt` | `{ atrHash, agreed: true, network, transaction }`. |
461
- | `ChannelHold` | `{ pairing, network, channel, h, atr, opening, charged, signedMax }`, all JSON. |
463
+ | `ChannelHold` | `{ pairing, network, channel, h, atr, opening, landed?, charged, signedMax }`, all JSON. |
462
464
  | `Declined` | `{ decline: Reason; moved?: { signed, bytes, h } }`. |
463
465
  | `Reason` | `{ code: DeclineCode; detail: string }`. |
464
466
  | `DeclineCode` | The twelve codes in the table above. |
@@ -18,10 +18,17 @@ export interface ChannelHold {
18
18
  /** Padded standard base64 of the ATR bytes the opening compared, in its canonical form (RFC 4648 sections 3.5, 4). */
19
19
  atr: string;
20
20
  /**
21
- * The signed opening payment as the gate returned it, written as plain JSON, with the landed receipt given beside it
22
- * as its `landed` member, where one is given.
21
+ * The signed opening payment as the gate returned it, written as plain JSON: its own members, as signed. A member of
22
+ * its own, `landed` or any other, is never read as the read made for the opening.
23
23
  */
24
24
  opening: Json;
25
+ /**
26
+ * The read made for the opening, as a JSON object: the `landed` receipt `openChannel` took, else the read the opening
27
+ * held under its own `FETCHED` member (`@integraledger/lcp`'s symbol, which no wire form carries), each bigint as its
28
+ * decimal string. Absent when there is neither. `within` holds it under the opening's own `FETCHED` member, as
29
+ * `bound` reads it.
30
+ */
31
+ landed?: Json;
25
32
  /** The server's cumulative charge last recorded, decimal; "0" at the opening. */
26
33
  charged: string;
27
34
  /** The largest `maxClaimableAmount` signed in this channel, decimal. */
@@ -29,9 +36,13 @@ export interface ChannelHold {
29
36
  }
30
37
  /**
31
38
  * Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
32
- * `transact` returned beside the opening, where it returned one. The opening, with that receipt, must be of kind `open`,
33
- * the pairing must read the hash of these bytes from it, and it must name its channel; the hold keeps all three
34
- * together.
39
+ * `transact` returned beside the opening, where it returned one. The caller passes as `landed` only the receipt its own
40
+ * reader read for the opening, as `transact` returned it, never a value another party sent. The opening, with that
41
+ * receipt held under its own `FETCHED` member, must be of kind `open`, the pairing must read the hash of these bytes
42
+ * from it, and it must name its channel; the hold keeps all three together. Without `landed`, an opening that holds its
43
+ * read under its own `FETCHED` member, as `@integraledger/lcp`'s `fetchPresented` returns it, is read with that read,
44
+ * and the hold keeps it. The hold keeps the opening as signed, and the read as its own `landed` member; a member of the
45
+ * opening's own, `landed` or any other, is never read as the read.
35
46
  */
36
47
  export declare function openChannel(bytes: Uint8Array, opened: Presented, binding: Binding, landed?: unknown): Promise<ChannelHold | Declined>;
37
48
  /**
package/dist/channels.js CHANGED
@@ -10,7 +10,7 @@
10
10
  import { fromBase64, fromLcpString, hash, hashEquals, parseJson, toBase64, toBase64Url, } from "@integraledger/lcp/core";
11
11
  import { network as mppNetwork, sessionResume } from "@integraledger/lcp/mpp";
12
12
  import { decodeObject, offers, requestOf } from "./pairings/mpp.js";
13
- import { isRefusal, refuse, withPaymentIdentifier } from "./pairings/common.js";
13
+ import { fetchedOf, held, isRefusal, jsonSafe, refuse, withPaymentIdentifier } from "./pairings/common.js";
14
14
  import { KEY } from "./pairings/x402-batch-settlement-solana.js";
15
15
  import { MAX_ATR_BYTES, } from "./types.js";
16
16
  const DECIMAL = /^[0-9]{1,78}$/;
@@ -79,7 +79,8 @@ function isHold(v) {
79
79
  HOLD_KEYS.every((k) => typeof v[k] === "string") &&
80
80
  DECIMAL.test(v["charged"]) &&
81
81
  DECIMAL.test(v["signedMax"]) &&
82
- isObject(v["opening"]));
82
+ isObject(v["opening"]) &&
83
+ (!Object.hasOwn(v, "landed") || isObject(v["landed"])));
83
84
  }
84
85
  /**
85
86
  * The channel an in-channel build's payment would name, read by the binding's `channel.ref` from the build completed
@@ -152,11 +153,22 @@ function openingMax(signed) {
152
153
  const max = isObject(voucher) ? voucher["maxClaimableAmount"] : undefined;
153
154
  return typeof max === "string" && DECIMAL.test(max) ? max : "0";
154
155
  }
156
+ /**
157
+ * A hold's opening as the binding reads it: the opening as signed, with the hold's `landed`, where it has one, held
158
+ * under the opening's own `FETCHED` member. A member of the opening's own, `landed` or any other, is not read.
159
+ */
160
+ function heldOpening(hold) {
161
+ return (hold.landed === undefined ? hold.opening : held(hold.opening, hold.landed));
162
+ }
155
163
  /**
156
164
  * Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
157
- * `transact` returned beside the opening, where it returned one. The opening, with that receipt, must be of kind `open`,
158
- * the pairing must read the hash of these bytes from it, and it must name its channel; the hold keeps all three
159
- * together.
165
+ * `transact` returned beside the opening, where it returned one. The caller passes as `landed` only the receipt its own
166
+ * reader read for the opening, as `transact` returned it, never a value another party sent. The opening, with that
167
+ * receipt held under its own `FETCHED` member, must be of kind `open`, the pairing must read the hash of these bytes
168
+ * from it, and it must name its channel; the hold keeps all three together. Without `landed`, an opening that holds its
169
+ * read under its own `FETCHED` member, as `@integraledger/lcp`'s `fetchPresented` returns it, is read with that read,
170
+ * and the hold keeps it. The hold keeps the opening as signed, and the read as its own `landed` member; a member of the
171
+ * opening's own, `landed` or any other, is never read as the read.
160
172
  */
161
173
  export async function openChannel(bytes, opened, binding, landed) {
162
174
  const b = stepsOf(binding);
@@ -166,7 +178,7 @@ export async function openChannel(bytes, opened, binding, landed) {
166
178
  if (landed !== undefined && (!isObject(landed) || !isObject(opened))) {
167
179
  return declined("signed-not-bound", "The landed receipt is not a JSON object beside the opening.");
168
180
  }
169
- const signed = (landed === undefined ? opened : { ...opened, landed });
181
+ const signed = (landed === undefined ? opened : held(opened, landed));
170
182
  if (!(bytes instanceof Uint8Array))
171
183
  return declined("signed-not-bound", "The ATR bytes are missing.");
172
184
  if (bytes.length > MAX_ATR_BYTES)
@@ -183,9 +195,14 @@ export async function openChannel(bytes, opened, binding, landed) {
183
195
  const ref = await guarded(() => channel.ref(signed));
184
196
  if (isRefusal(ref))
185
197
  return declined("signed-not-bound", ref.code);
186
- const opening = asJson(signed);
198
+ const opening = asJson(opened);
187
199
  if (!isObject(opening))
188
200
  return declined("signed-not-bound", "The opening is not plain JSON.");
201
+ const fetched = landed === undefined ? fetchedOf(opened) : undefined;
202
+ const read = landed !== undefined ? asJson(landed) : fetched !== undefined ? asJson(jsonSafe(fetched)) : undefined;
203
+ if ((landed !== undefined || fetched !== undefined) && !isObject(read)) {
204
+ return declined("signed-not-bound", "The read held for the opening is not plain JSON.");
205
+ }
189
206
  return {
190
207
  pairing: b.id,
191
208
  network: ref.network,
@@ -193,6 +210,7 @@ export async function openChannel(bytes, opened, binding, landed) {
193
210
  h,
194
211
  atr: toBase64(bytes),
195
212
  opening,
213
+ ...(read === undefined ? {} : { landed: read }),
196
214
  charged: "0",
197
215
  signedMax: openingMax(signed),
198
216
  };
@@ -248,11 +266,12 @@ export async function within(doc, hold, binding, signer, refund, inputs = {}) {
248
266
  const h = await hash(bytes);
249
267
  if (!hashEquals(hold.h, h))
250
268
  return declined("hash-mismatch", "The held ATR does not hash to the held hash.");
251
- const opened = await guarded(() => b.bound(hold.opening));
269
+ const opening = heldOpening(hold);
270
+ const opened = await guarded(() => b.bound(opening));
252
271
  if (isRefusal(opened) || !hashEquals(opened, h)) {
253
272
  return declined("signed-not-bound", "The pairing does not read the held ATR's hash from the held opening.");
254
273
  }
255
- const openedRef = await guarded(() => channel.ref(hold.opening));
274
+ const openedRef = await guarded(() => channel.ref(opening));
256
275
  if (isRefusal(openedRef) || openedRef.network !== hold.network || openedRef.channel !== hold.channel) {
257
276
  return declined("signed-not-bound", "The held opening does not name the held channel.");
258
277
  }
@@ -385,7 +404,8 @@ async function sessionWithin(b, doc, hold, h, signer, refund) {
385
404
  return declined("offer-unreadable", "mpp/request-malformed");
386
405
  const action = refund !== undefined ? "close" : "voucher";
387
406
  const cumulativeAmount = action === "close" ? BigInt(hold.charged) : BigInt(hold.charged) + BigInt(amount);
388
- const unsigned = await guarded(() => b.buildWithin({ challenge, opening: hold.opening, cumulativeAmount, action }, h));
407
+ const opening = heldOpening(hold);
408
+ const unsigned = await guarded(() => b.buildWithin({ challenge, opening, cumulativeAmount, action }, h));
389
409
  if (isRefusal(unsigned)) {
390
410
  const code = unsigned.code.endsWith("/within-action-not-built") ? "pairing-not-supported" : "offer-unreadable";
391
411
  return declined(code, unsigned.code);
package/dist/gate.d.ts CHANGED
@@ -65,10 +65,15 @@ export declare function finish(bytes: Uint8Array, chosen: Chosen, signature: Sig
65
65
  h: AtrHash;
66
66
  } | Declined>;
67
67
  /**
68
- * Confirms that the ATR hash the pairing reads from a payment held later is the SHA-256 of the kept bytes. A payment
69
- * from which the pairing reads no ATR hash is declined `signed-not-bound`.
68
+ * Confirms that the ATR hash the pairing reads from a payment held later is the SHA-256 of the kept bytes, with the
69
+ * `landed` receipt `finish` or `transact` returned beside the payment, where it returned one, held under the payment's
70
+ * own `FETCHED` member as `bound` reads it. The caller passes as `landed` only the receipt its own reader read for the
71
+ * payment, as `finish` or `transact` returned it, never a value another party sent. A `landed` of `null` is no
72
+ * receipt: the payment is read alone, as without one. A payment from which the pairing reads no ATR hash is declined
73
+ * `signed-not-bound`, as is a `landed` receipt that is not a JSON object beside a payment that is one. A `landed`
74
+ * member of the payment's own is not read.
70
75
  */
71
- export declare function check(bytes: Uint8Array, presented: unknown, binding: Binding): Promise<{
76
+ export declare function check(bytes: Uint8Array, presented: unknown, binding: Binding, landed?: unknown): Promise<{
72
77
  h: AtrHash;
73
78
  } | Declined>;
74
79
  /**
package/dist/gate.js CHANGED
@@ -6,7 +6,7 @@
6
6
  * confirms a payment held later against kept bytes.
7
7
  */
8
8
  import { hash, hashEquals, isHttpsLink, isOtherSchemeLink, toBase64Url, } from "@integraledger/lcp/core";
9
- import { isRefusal, refuse } from "./pairings/common.js";
9
+ import { fetchedOf, held, isRefusal, jsonSafe, refuse } from "./pairings/common.js";
10
10
  import { PIECES } from "./pairings/index.js";
11
11
  import { MAX_ATR_BYTES, } from "./types.js";
12
12
  /** The binding's members, as the gate calls them. */
@@ -273,21 +273,9 @@ export async function finish(bytes, chosen, signature, binding) {
273
273
  if (!onAgreement && (isRefusal(inside) || !hashEquals(inside, h))) {
274
274
  return keep(declined("signed-not-bound", "The pairing does not read the hash of the compared bytes from the payment."), sent);
275
275
  }
276
- const landed = sent !== signed && isObject(signed) ? jsonSafe(signed.landed) : undefined;
276
+ const landed = sent !== signed ? jsonSafe(fetchedOf(signed)) : undefined;
277
277
  return landed === undefined ? { signed: sent, h } : { signed: sent, landed, h };
278
278
  }
279
- /** A value as JSON, each bigint as its decimal string; undefined when it is undefined or has no JSON form. */
280
- function jsonSafe(v) {
281
- if (v === undefined)
282
- return undefined;
283
- try {
284
- const text = JSON.stringify(v, (_k, x) => (typeof x === "bigint" ? x.toString() : x));
285
- return text === undefined ? undefined : JSON.parse(text);
286
- }
287
- catch {
288
- return undefined;
289
- }
290
- }
291
279
  /** Whether the signer, handed the build's first request, moves the payment itself. */
292
280
  function movesWith(piece, unsigned) {
293
281
  if (piece.moves === undefined)
@@ -305,14 +293,23 @@ async function boundOf(b, presented) {
305
293
  }
306
294
  }
307
295
  /**
308
- * Confirms that the ATR hash the pairing reads from a payment held later is the SHA-256 of the kept bytes. A payment
309
- * from which the pairing reads no ATR hash is declined `signed-not-bound`.
296
+ * Confirms that the ATR hash the pairing reads from a payment held later is the SHA-256 of the kept bytes, with the
297
+ * `landed` receipt `finish` or `transact` returned beside the payment, where it returned one, held under the payment's
298
+ * own `FETCHED` member as `bound` reads it. The caller passes as `landed` only the receipt its own reader read for the
299
+ * payment, as `finish` or `transact` returned it, never a value another party sent. A `landed` of `null` is no
300
+ * receipt: the payment is read alone, as without one. A payment from which the pairing reads no ATR hash is declined
301
+ * `signed-not-bound`, as is a `landed` receipt that is not a JSON object beside a payment that is one. A `landed`
302
+ * member of the payment's own is not read.
310
303
  */
311
- export async function check(bytes, presented, binding) {
304
+ export async function check(bytes, presented, binding, landed) {
312
305
  if (bytes.length > MAX_ATR_BYTES)
313
306
  return tooLarge();
307
+ const read = landed === null ? undefined : landed;
308
+ if (read !== undefined && (!isObject(read) || !isObject(presented))) {
309
+ return declined("signed-not-bound", "The landed receipt is not a JSON object beside the payment.");
310
+ }
314
311
  const h = await hash(bytes);
315
- const b = await boundOf(steps(binding), presented);
312
+ const b = await boundOf(steps(binding), read === undefined ? presented : held(presented, read));
316
313
  if (isRefusal(b) || !hashEquals(b, h)) {
317
314
  return declined("signed-not-bound", "The pairing does not read the hash of the compared bytes from the payment.");
318
315
  }
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * What the buyer pieces share: the CAIP-10 account, the first x402 option on the account's network, the payment
3
- * identifier the x402 client writes, and the JSON forms of byte strings and integers.
3
+ * identifier the x402 client writes, the read held under a payment's own `FETCHED` member, and the JSON forms of
4
+ * values, byte strings and integers.
4
5
  */
5
6
  import { type Json, type Refusal } from "@integraledger/lcp/core";
6
7
  import type { PaymentRequired, PaymentRequirements, X402Offer } from "@integraledger/lcp/x402";
@@ -14,6 +15,17 @@ export declare function refuse(code: string): Refusal;
14
15
  */
15
16
  export declare function isRefusal(v: unknown): v is Refusal;
16
17
  export declare function isObject(v: unknown): v is Record<string, unknown>;
18
+ /**
19
+ * The read held under the payment's own `FETCHED` member (`@integraledger/lcp`'s symbol, which no wire form carries),
20
+ * or undefined. A string-keyed member such as `landed` is never read.
21
+ */
22
+ export declare function fetchedOf(c: unknown): unknown;
23
+ /** The payment with `read` held under its own `FETCHED` member. */
24
+ export declare function held<T extends object>(c: T, read: unknown): T;
25
+ /** The payment without what is held under its own `FETCHED` member: its string-keyed members, as it is sent. */
26
+ export declare function withoutFetched<T extends object>(c: T): T;
27
+ /** A value as JSON, each bigint as its decimal string; undefined when it is undefined or has no JSON form. */
28
+ export declare function jsonSafe(v: unknown): Json | undefined;
17
29
  /**
18
30
  * A CAIP-10 account's namespace, its CAIP-2 network and its address, percent-decoded (CAIP-10's escape). An `eip155`
19
31
  * address is taken as written: the gate's account form for EVM is `^eip155:([0-9]+):(0x[0-9a-fA-F]{40})$`, which has no escape.
@@ -1,8 +1,10 @@
1
1
  /**
2
2
  * What the buyer pieces share: the CAIP-10 account, the first x402 option on the account's network, the payment
3
- * identifier the x402 client writes, and the JSON forms of byte strings and integers.
3
+ * identifier the x402 client writes, the read held under a payment's own `FETCHED` member, and the JSON forms of
4
+ * values, byte strings and integers.
4
5
  */
5
6
  import { isRefusal as isLcpRefusal } from "@integraledger/lcp/core";
7
+ import { FETCHED } from "@integraledger/lcp/mpp";
6
8
  const CAIP10 = /^([-a-z0-9]{3,8}):([-_a-zA-Z0-9]{1,32}):([-.%a-zA-Z0-9]{1,128})$/;
7
9
  const PAYMENT_IDENTIFIER = "payment-identifier";
8
10
  const HEX = /^0x(?:[0-9a-fA-F]{2})*$/;
@@ -26,6 +28,34 @@ export function isRefusal(v) {
26
28
  export function isObject(v) {
27
29
  return typeof v === "object" && v !== null && !Array.isArray(v);
28
30
  }
31
+ /**
32
+ * The read held under the payment's own `FETCHED` member (`@integraledger/lcp`'s symbol, which no wire form carries),
33
+ * or undefined. A string-keyed member such as `landed` is never read.
34
+ */
35
+ export function fetchedOf(c) {
36
+ return isObject(c) && Object.hasOwn(c, FETCHED) ? c[FETCHED] : undefined;
37
+ }
38
+ /** The payment with `read` held under its own `FETCHED` member. */
39
+ export function held(c, read) {
40
+ return { ...c, [FETCHED]: read };
41
+ }
42
+ /** The payment without what is held under its own `FETCHED` member: its string-keyed members, as it is sent. */
43
+ export function withoutFetched(c) {
44
+ const { [FETCHED]: _read, ...sent } = c;
45
+ return sent;
46
+ }
47
+ /** A value as JSON, each bigint as its decimal string; undefined when it is undefined or has no JSON form. */
48
+ export function jsonSafe(v) {
49
+ if (v === undefined)
50
+ return undefined;
51
+ try {
52
+ const text = JSON.stringify(v, (_k, x) => (typeof x === "bigint" ? x.toString() : x));
53
+ return text === undefined ? undefined : JSON.parse(text);
54
+ }
55
+ catch {
56
+ return undefined;
57
+ }
58
+ }
29
59
  /**
30
60
  * A CAIP-10 account's namespace, its CAIP-2 network and its address, percent-decoded (CAIP-10's escape). An `eip155`
31
61
  * address is taken as written: the gate's account form for EVM is `^eip155:([0-9]+):(0x[0-9a-fA-F]{40})$`, which has no escape.
@@ -9,7 +9,7 @@
9
9
  * - `mcp:1`: `{server, name, arguments?, meta?}`, `server` the MCP server's URI as the buyer's own configuration spells
10
10
  * it, `name` and `arguments` the `tools/call` params, `meta` its `params._meta`.
11
11
  */
12
- import { canonicalJson, hash } from "@integraledger/lcp/core";
12
+ import { canonicalJson, hash, readUrl } from "@integraledger/lcp/core";
13
13
  import { decodeBolt11, invoiceH } from "@integraledger/lcp/lightning";
14
14
  import { bytesOf, isObject, isRefusal, refuse } from "./common.js";
15
15
  const HTTP_DOMAIN = "x402:exact:lnbtc:bolt11:http:1";
@@ -43,9 +43,15 @@ async function valueHash(bytes) {
43
43
  b.set(bytes, 1);
44
44
  return sha256Hex(b);
45
45
  }
46
- /** An absolute `http` or `https` URL in ASCII syntax, with a host, and no fragment or user information. */
46
+ /**
47
+ * An absolute `http` or `https` URL in ASCII syntax, with a host, and no fragment or user information, that the WHATWG
48
+ * URL Standard's basic URL parser reads, with no base, as lcp's `readUrl` reads it.
49
+ */
47
50
  function isTargetUri(url) {
48
- return typeof url === "string" && ASCII_URI.test(url) && HTTP_TARGET.test(url) && URL.canParse(url);
51
+ if (typeof url !== "string" || !ASCII_URI.test(url) || !HTTP_TARGET.test(url))
52
+ return false;
53
+ const scheme = readUrl(url)?.scheme;
54
+ return scheme === "http" || scheme === "https";
49
55
  }
50
56
  /** Strictly ascending and without duplicates, by UTF-16 code units, which is RFC 8785's member order. */
51
57
  function ascending(names) {
@@ -117,9 +123,12 @@ async function mcpBinding(params, request) {
117
123
  }
118
124
  return { domain: MCP_DOMAIN, server, method: "tools/call", name, arguments: args, metadata: bound };
119
125
  }
120
- /** An absolute URI in ASCII syntax, with no user information and no fragment. */
126
+ /**
127
+ * An absolute URI in ASCII syntax, with no user information and no fragment, that the WHATWG URL Standard's basic URL
128
+ * parser reads, with no base, as lcp's `readUrl` reads it.
129
+ */
121
130
  function isAbsoluteUri(v) {
122
- return typeof v === "string" && ASCII_URI.test(v) && ABSOLUTE_URI.test(v) && !USERINFO.test(v) && URL.canParse(v);
131
+ return typeof v === "string" && ASCII_URI.test(v) && ABSOLUTE_URI.test(v) && !USERINFO.test(v) && readUrl(v) !== null;
123
132
  }
124
133
  /**
125
134
  * The binding object of the buyer's own `request` under a profile and its parameters, the profile being the one the
@@ -5,19 +5,21 @@
5
5
  * network.
6
6
  * - `credentialType` `hash` (push, the default when none is named): the build's request carries `broadcast: true`; the
7
7
  * signer signs and broadcasts the body and answers `{transactionId}`, which must name the body's payer and valid
8
- * start. The credential is `{challenge, payload: {type: "hash", transactionId}}`, and `landed` beside it holds the
9
- * network and the body's memo, which `bound` reads. The signer moves the payment, so a decline keeps it.
8
+ * start. The credential is `{challenge, payload: {type: "hash", transactionId}}`, with its landed read held under
9
+ * the payment's own `FETCHED` member: the network and the body's memo, which `bound` reads. The signer moves the
10
+ * payment, so a decline keeps it.
10
11
  * - `credentialType` `transaction` (pull): the signer answers `{publicKey, signature, type}`, and the credential is
11
12
  * `{challenge, payload: {type: "transaction", transaction}}`, the signed body in base64.
12
13
  */
13
14
  import type { AtrHash } from "@integraledger/lcp/core";
14
15
  import type { BuyerPiece } from "../types.js";
15
16
  /**
16
- * The binding's build, called with the chosen challenge's id and realm, its decoded request, and the payer's values,
17
- * `credentialType` among them. The body carries no hash of its own: the challenge's id derives from it, and `bound`
18
- * reads it from there.
17
+ * The binding's build, called with the chosen challenge, the payer's values, `credentialType` among them, and H. The
18
+ * binding holds the challenge as `bound` holds an echoed one, with `bound`'s code for each fault, and refuses one whose
19
+ * id does not derive from H with `mpp/id-not-ours`. The body carries no hash of its own: the challenge's id derives
20
+ * from it, and `bound` reads it from there.
19
21
  */
20
- export declare function buildHederaCharge(choice: unknown, _h: AtrHash): Promise<unknown>;
22
+ export declare function buildHederaCharge(choice: unknown, h: AtrHash): Promise<unknown>;
21
23
  export declare const mppChargeHedera: BuyerPiece & {
22
24
  build(choice: unknown, h: AtrHash): Promise<unknown>;
23
25
  };
@@ -1,5 +1,5 @@
1
1
  import { attributionMemo, chargeHedera } from "@integraledger/lcp/mpp";
2
- import { accountOf, bigintOf, broadcasts, bytesOf, choiceOf, inputsOf, isObject, isRefusal, refuse } from "./common.js";
2
+ import { accountOf, bigintOf, broadcasts, bytesOf, choiceOf, held, inputsOf, isObject, isRefusal, refuse, withoutFetched, } from "./common.js";
3
3
  import { requestOf } from "./mpp.js";
4
4
  import { mppRailPiece, railChoose } from "./mpp-rails.js";
5
5
  import { HEDERA_ENTITY } from "./x402-exact-hedera.js";
@@ -73,7 +73,7 @@ async function complete(unsigned, signature, chosen) {
73
73
  return transactionId;
74
74
  const clientId = typeof c["clientId"] === "string" ? c["clientId"] : undefined;
75
75
  const memo = attributionMemo(String(challenge["realm"]), String(challenge["id"]), clientId);
76
- return { challenge: echoed, payload: { type: "hash", transactionId }, landed: { network: c["network"], memo } };
76
+ return held({ challenge: echoed, payload: { type: "hash", transactionId } }, { network: c["network"], memo });
77
77
  }
78
78
  const a = answer(signature);
79
79
  if (isRefusal(a))
@@ -84,25 +84,26 @@ async function complete(unsigned, signature, chosen) {
84
84
  return { challenge: echoed, payload: { type: "transaction", transaction } };
85
85
  }
86
86
  /**
87
- * The binding's build, called with the chosen challenge's id and realm, its decoded request, and the payer's values,
88
- * `credentialType` among them. The body carries no hash of its own: the challenge's id derives from it, and `bound`
89
- * reads it from there.
87
+ * The binding's build, called with the chosen challenge, the payer's values, `credentialType` among them, and H. The
88
+ * binding holds the challenge as `bound` holds an echoed one, with `bound`'s code for each fault, and refuses one whose
89
+ * id does not derive from H with `mpp/id-not-ours`. The body carries no hash of its own: the challenge's id derives
90
+ * from it, and `bound` reads it from there.
90
91
  */
91
- export async function buildHederaCharge(choice, _h) {
92
+ export async function buildHederaCharge(choice, h) {
92
93
  if (isRefusal(choice))
93
94
  return choice;
94
95
  const c = choice;
95
- const request = requestOf(c.challenge);
96
- if (request === undefined || typeof c.challenge.id !== "string")
96
+ if (requestOf(c.challenge) === undefined || typeof c.challenge.id !== "string")
97
97
  return refuse("mpp/choice-malformed");
98
- return chargeHedera.build({ id: c.challenge.id, realm: c.challenge.realm }, request, {
98
+ return chargeHedera.build({
99
+ challenge: c.challenge,
99
100
  payer: c.payer,
100
101
  node: c.node,
101
102
  validStart: c.validStart,
102
103
  maxFee: c.maxFee,
103
104
  ...(c.clientId !== undefined ? { clientId: c.clientId } : {}),
104
105
  ...(c.credentialType !== undefined ? { credentialType: c.credentialType } : {}),
105
- });
106
+ }, h);
106
107
  }
107
108
  const spec = {
108
109
  pairing: PAIRING,
@@ -117,7 +118,9 @@ const spec = {
117
118
  };
118
119
  const rail = mppRailPiece(spec);
119
120
  const railChosen = railChoose(spec);
120
- /** The choice, with the account's network, which the challenge's network equals, for a push credential's `landed`. */
121
+ /**
122
+ * The choice, with the account's network, which the challenge's network equals, for a push credential's landed read.
123
+ */
121
124
  function choose(...args) {
122
125
  const chosen = railChosen(...args);
123
126
  if (isRefusal(chosen))
@@ -131,7 +134,6 @@ export const mppChargeHedera = Object.freeze({
131
134
  build: buildHederaCharge,
132
135
  moves: broadcasts,
133
136
  sent(signed) {
134
- const { landed: _landed, ...credential } = signed;
135
- return credential;
137
+ return withoutFetched(signed);
136
138
  },
137
139
  });
@@ -1,3 +1,9 @@
1
+ /**
2
+ * The buyer piece for `mpp/charge/tempo/push`: the signer broadcasts and answers the hash with its landed receipt, held
3
+ * under the payment's own `FETCHED` member, where `bound` reads it for the memo. The payment sent is the credential
4
+ * without it. The signer moves the payment, so a decline keeps it. The build is the protocol package's: with splits,
5
+ * its `tempo-calls` request holds one call per recipient.
6
+ */
1
7
  import type { Presented } from "../types.js";
2
8
  import { broadcasts } from "./common.js";
3
9
  import { mppChoice, mppRequest, pushComplete } from "./mpp.js";
@@ -1,4 +1,4 @@
1
- import { broadcasts } from "./common.js";
1
+ import { broadcasts, withoutFetched } from "./common.js";
2
2
  import { mppChoice, mppChoose, mppRequest, pushComplete } from "./mpp.js";
3
3
  export const mppChargeTempoPush = Object.freeze({
4
4
  choose: mppChoose("mpp/charge/tempo/push", { clientId: "optional-string" }),
@@ -7,7 +7,6 @@ export const mppChargeTempoPush = Object.freeze({
7
7
  complete: pushComplete,
8
8
  moves: broadcasts,
9
9
  sent(signed) {
10
- const { landed: _landed, ...credential } = signed;
11
- return credential;
10
+ return withoutFetched(signed);
12
11
  },
13
12
  });
@@ -1,4 +1,4 @@
1
- import { bigintOf, inputsOf, isObject, isRefusal, refuse } from "./common.js";
1
+ import { bigintOf, held, inputsOf, isObject, isRefusal, refuse, withoutFetched } from "./common.js";
2
2
  import { HEDERA_EVM_ADDRESS, mppRailPiece, sessionRevive } from "./mpp-rails.js";
3
3
  const PAIRING = "mpp/session/hedera";
4
4
  async function complete(unsigned, signature, _chosen) {
@@ -20,7 +20,7 @@ async function complete(unsigned, signature, _chosen) {
20
20
  const blockNumber = bigintOf(landed["blockNumber"]);
21
21
  if (blockNumber === undefined)
22
22
  return refuse("mpp/credential-malformed");
23
- return { ...credential, landed: { transaction: landed["transaction"], blockNumber, logs: landed["logs"] } };
23
+ return held(credential, { transaction: landed["transaction"], blockNumber, logs: landed["logs"] });
24
24
  }
25
25
  export const mppSessionHedera = Object.freeze({
26
26
  ...mppRailPiece({
@@ -35,7 +35,6 @@ export const mppSessionHedera = Object.freeze({
35
35
  }),
36
36
  moves: () => true,
37
37
  sent(signed) {
38
- const { landed: _landed, ...credential } = signed;
39
- return credential;
38
+ return withoutFetched(signed);
40
39
  },
41
40
  });
@@ -33,7 +33,8 @@ export declare function mppComplete(unsigned: unknown, signature: Signature): Pr
33
33
  export declare function mppChargePiece(pairing: string, spec: Spec): BuyerPiece;
34
34
  /**
35
35
  * The credential for a pushed Tempo transfer: the answer is `{hash, landed?: {transaction, blockNumber, logs}}`, the
36
- * hash the signer broadcast and, where the signer gives it, its landed receipt, which carries the memo `bound` reads.
36
+ * hash the signer broadcast and, where the signer gives it, its landed receipt, which carries the memo `bound` reads,
37
+ * held under the payment's own `FETCHED` member (`@integraledger/lcp`'s symbol, which no wire form carries).
37
38
  */
38
39
  export declare function pushComplete(unsigned: unknown, signature: Signature): Promise<Presented | Refusal>;
39
40
  export {};
@@ -1,6 +1,6 @@
1
1
  import { base64UrlBytes, canonicalJson, parseJson } from "@integraledger/lcp/core";
2
2
  import { network, pairingsOfPlaced } from "@integraledger/lcp/mpp";
3
- import { accountOf, bigintOf, broadcasts, choiceOf, inputsOf, isObject, isRefusal, refuse } from "./common.js";
3
+ import { accountOf, bigintOf, broadcasts, choiceOf, held, inputsOf, isObject, isRefusal, refuse } from "./common.js";
4
4
  const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
5
5
  const MAX_DECODED = 8192;
6
6
  const MAX_JSON_DEPTH = 16;
@@ -93,7 +93,8 @@ export function mppChargePiece(pairing, spec) {
93
93
  }
94
94
  /**
95
95
  * The credential for a pushed Tempo transfer: the answer is `{hash, landed?: {transaction, blockNumber, logs}}`, the
96
- * hash the signer broadcast and, where the signer gives it, its landed receipt, which carries the memo `bound` reads.
96
+ * hash the signer broadcast and, where the signer gives it, its landed receipt, which carries the memo `bound` reads,
97
+ * held under the payment's own `FETCHED` member (`@integraledger/lcp`'s symbol, which no wire form carries).
97
98
  */
98
99
  export async function pushComplete(unsigned, signature) {
99
100
  if (!isObject(signature) || typeof signature["hash"] !== "string")
@@ -110,8 +111,5 @@ export async function pushComplete(unsigned, signature) {
110
111
  const blockNumber = bigintOf(landed["blockNumber"]);
111
112
  if (blockNumber === undefined)
112
113
  return refuse("mpp/credential-malformed");
113
- return {
114
- ...credential,
115
- landed: { transaction: landed["transaction"], blockNumber, logs: landed["logs"] },
116
- };
114
+ return held(credential, { transaction: landed["transaction"], blockNumber, logs: landed["logs"] });
117
115
  }
@@ -1,10 +1,31 @@
1
1
  import { bigintOf, bytesOf, choiceOf, inputsOf, isObject, isRefusal, refuse, x402Chosen } from "./common.js";
2
2
  import { identified, railOption } from "./x402-account-rails.js";
3
3
  const PAIRING = "x402/exact/near";
4
- const NEAR_ACCOUNT = /^[a-z0-9._-]{2,64}$/;
4
+ /**
5
+ * True for a NEAR account id: what near-account-id 3.0.0, the version nearcore locks, reads as an `AccountId`
6
+ * (src/validation.rs: `validate`, `MIN_LEN` and `MAX_LEN`), as the delegate action's sender is read. An id is 2 to 64
7
+ * characters, each a lowercase ASCII letter, a digit, `-`, `_` or `.`; a separator (`-`, `_` or `.`) is never first,
8
+ * never last, and never follows another. The length bounds count bytes, and every character an id may hold is one
9
+ * byte, so counting UTF-16 code units gives the same answer.
10
+ */
11
+ function isNearAccountId(id) {
12
+ if (id.length < 2 || id.length > 64)
13
+ return false;
14
+ let afterSeparator = true;
15
+ for (let i = 0; i < id.length; i++) {
16
+ const c = id.charCodeAt(i);
17
+ const separator = c === 0x2d || c === 0x5f || c === 0x2e;
18
+ if (!separator && !((c >= 0x61 && c <= 0x7a) || (c >= 0x30 && c <= 0x39)))
19
+ return false;
20
+ if (separator && afterSeparator)
21
+ return false;
22
+ afterSeparator = separator;
23
+ }
24
+ return !afterSeparator;
25
+ }
5
26
  export const x402ExactNear = Object.freeze({
6
27
  choose(read, account, inputs, _now, ref) {
7
- const o = railOption(read, account, ["near"], PAIRING, (a) => NEAR_ACCOUNT.test(a));
28
+ const o = railOption(read, account, ["near"], PAIRING, isNearAccountId);
8
29
  if (isRefusal(o))
9
30
  return o;
10
31
  const given = inputsOf(inputs, PAIRING, { publicKey: "string", accessKeyNonce: "decimal", finalHeight: "decimal" });
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * The buyer pieces shared by the x402 pairings on the Solana, Stellar, XRPL, Hedera and Algorand rails: the first option
3
3
  * on the account's network, the buyer's own inputs beside it as JSON, the build's request exactly as built, and the
4
- * payment the signer's answer completes, with the payment identifier appended where the challenge advertises it.
4
+ * payment the build's `complete` gives for the signer's answer, awaited where it answers a Promise, with the payment
5
+ * identifier appended where the challenge advertises it.
5
6
  */
6
7
  import type { Json, Refusal } from "@integraledger/lcp/core";
7
8
  import type { PaymentRequirements } from "@integraledger/lcp/x402";
@@ -47,7 +47,7 @@ export function railPiece(rail) {
47
47
  if (isRefusal(answer))
48
48
  return answer;
49
49
  const c = choiceOf(chosen);
50
- const completed = unsigned.complete(answer);
50
+ const completed = await unsigned.complete(answer);
51
51
  if (isRefusal(completed))
52
52
  return completed;
53
53
  let signed;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@integraledger/terms",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Buyer gate: compare the ATR hash with the served bytes, and build the payment with that hash, before signing.",
5
5
  "keywords": [
6
6
  "agentic-commerce",
@@ -40,10 +40,10 @@
40
40
  "LICENSE"
41
41
  ],
42
42
  "peerDependencies": {
43
- "@integraledger/lcp": "~0.4.0"
43
+ "@integraledger/lcp": "~0.4.2"
44
44
  },
45
45
  "devDependencies": {
46
- "@integraledger/lcp": "0.4.0",
46
+ "@integraledger/lcp": "0.4.2",
47
47
  "@mysten/sui": "2.35.0",
48
48
  "@solana/kit": "8.4.0",
49
49
  "@stellar/stellar-sdk": "17.2.1",
@@ -51,7 +51,6 @@
51
51
  "algosdk": "3.8.0",
52
52
  "borsh": "2.0.0",
53
53
  "esbuild": "0.28.2",
54
- "near-api-js": "7.3.1",
55
54
  "ripple-binary-codec": "2.11.0",
56
55
  "viem": "2.57.4"
57
56
  },