@integraledger/terms 0.2.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.
Files changed (44) hide show
  1. package/README.md +88 -52
  2. package/dist/agreement.d.ts +14 -4
  3. package/dist/agreement.js +139 -49
  4. package/dist/channels.d.ts +47 -14
  5. package/dist/channels.js +147 -74
  6. package/dist/gate.d.ts +37 -16
  7. package/dist/gate.js +69 -45
  8. package/dist/pairings/batch.d.ts +2 -5
  9. package/dist/pairings/batch.js +1 -11
  10. package/dist/pairings/card.js +0 -2
  11. package/dist/pairings/common.d.ts +17 -4
  12. package/dist/pairings/common.js +35 -4
  13. package/dist/pairings/lnbtc-request.d.ts +1 -1
  14. package/dist/pairings/lnbtc-request.js +14 -5
  15. package/dist/pairings/mpp-charge-hedera.d.ts +13 -11
  16. package/dist/pairings/mpp-charge-hedera.js +16 -14
  17. package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
  18. package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
  19. package/dist/pairings/mpp-charge-tempo-push.d.ts +6 -1
  20. package/dist/pairings/mpp-charge-tempo-push.js +4 -13
  21. package/dist/pairings/mpp-charge-xrpl.js +3 -3
  22. package/dist/pairings/mpp-rails.d.ts +1 -1
  23. package/dist/pairings/mpp-session-hedera.js +3 -4
  24. package/dist/pairings/mpp-session-xrpl.js +3 -4
  25. package/dist/pairings/mpp.d.ts +14 -17
  26. package/dist/pairings/mpp.js +35 -114
  27. package/dist/pairings/protocol-groups.d.ts +1 -1
  28. package/dist/pairings/x402-account-rails.d.ts +1 -1
  29. package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
  30. package/dist/pairings/x402-batch-settlement-solana.js +2 -1
  31. package/dist/pairings/x402-exact-hedera.d.ts +4 -1
  32. package/dist/pairings/x402-exact-hedera.js +5 -2
  33. package/dist/pairings/x402-exact-near.js +23 -2
  34. package/dist/pairings/x402-exact-solana.d.ts +4 -4
  35. package/dist/pairings/x402-exact-solana.js +3 -2
  36. package/dist/pairings/x402-exact-sui.js +3 -1
  37. package/dist/pairings/x402-exact-tvm.js +10 -2
  38. package/dist/pairings/x402-exact-xrpl.js +2 -4
  39. package/dist/pairings/x402-rail.d.ts +3 -2
  40. package/dist/pairings/x402-rail.js +1 -1
  41. package/dist/transact.d.ts +3 -2
  42. package/dist/transact.js +9 -6
  43. package/dist/types.d.ts +6 -16
  44. package/package.json +10 -12
package/dist/channels.js CHANGED
@@ -1,21 +1,31 @@
1
1
  /**
2
2
  * The buyer's channel steps. One ATR covers a whole channel: the gate compares it once, at the opening, and the caller
3
3
  * keeps the result as a `ChannelHold`, the ATR's bytes together with the signed opening and the channel it names.
4
- * `within` signs a later voucher only for a channel held this way, re-deriving everything from the hold and never from
5
- * the new challenge, and only when that challenge advertises the held ATR's hash. It serves x402's batch channels and
6
- * MPP's sessions through the binding's `buildWithin`. `recordCharge` records the server's cumulative charge, bounded by
7
- * what was signed.
4
+ * `within` signs a later voucher only for a channel held this way: the ATR's bytes, its hash and the channel come from
5
+ * the hold, and the amount from the new challenge. On x402's batch channels that challenge must advertise the held
6
+ * ATR's hash. On MPP's sessions a challenge that names another channel or another hash is declined, and one with no
7
+ * legal context is signed under the held hash. Both are served through the binding's `buildWithin`. `recordCharge`
8
+ * records the server's cumulative charge, bounded by what was signed.
8
9
  */
9
- import { fromLcpString, hash, hashEquals, parseJson } from "@integraledger/lcp";
10
+ import { fromBase64, fromLcpString, hash, hashEquals, parseJson, toBase64, toBase64Url, } from "@integraledger/lcp/core";
10
11
  import { network as mppNetwork, sessionResume } from "@integraledger/lcp/mpp";
11
- import { offers, requestOf } from "./pairings/mpp.js";
12
- import { isRefusal, refuse, withPaymentIdentifier } from "./pairings/common.js";
12
+ import { decodeObject, offers, requestOf } from "./pairings/mpp.js";
13
+ import { fetchedOf, held, isRefusal, jsonSafe, refuse, withPaymentIdentifier } from "./pairings/common.js";
14
+ import { KEY } from "./pairings/x402-batch-settlement-solana.js";
13
15
  import { MAX_ATR_BYTES, } from "./types.js";
14
16
  const DECIMAL = /^[0-9]{1,78}$/;
17
+ const U32_MAX = 0xffff_ffff;
18
+ const U64_LIMIT = 1n << 64n;
19
+ /** The pairing whose refunds carry a payer-signed `request_close` when taken again. */
20
+ const SOLANA_BATCH = "x402/batch-settlement/solana";
21
+ /**
22
+ * The code a seller answers a Solana refund with when the receiver's binding is unavailable, as a settle failure's
23
+ * `PAYMENT-RESPONSE` `errorReason` or a payment request's `error`: x402 then takes the refund again, carrying the
24
+ * payer-signed `request_close`.
25
+ */
26
+ const BINDING_UNAVAILABLE = "invalid_batch_settlement_svm_receiver_binding_unavailable";
15
27
  /** At most this many challenges of a within document are looked at, as the MPP entry point reads a document. */
16
28
  const MAX_CHALLENGES = 32;
17
- /** An `opaque` of at most this many base64url characters, 8 KiB decoded, is read. */
18
- const MAX_OPAQUE = 10_924;
19
29
  const NOT_BOUND_WITHIN = /\/not-bound-within$/;
20
30
  const REF_BYTES = 24;
21
31
  const HOLD_KEYS = ["pairing", "network", "channel", "h", "atr", "charged", "signedMax"];
@@ -45,26 +55,20 @@ async function guarded(run) {
45
55
  return refuse("member-failed");
46
56
  }
47
57
  }
48
- function toBase64(bytes) {
49
- let s = "";
50
- for (let i = 0; i < bytes.length; i += 0x8000)
51
- s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
52
- return btoa(s);
53
- }
54
- function fromBase64(s) {
55
- try {
56
- const binary = atob(s);
57
- return Uint8Array.from(binary, (c) => c.charCodeAt(0));
58
- }
59
- catch {
60
- return undefined;
61
- }
62
- }
63
- /** A value as plain JSON, or undefined when it holds anything JSON does not carry. */
58
+ /**
59
+ * A value as the plain JSON `JSON.stringify` writes for it, without the members it leaves out (undefined, a function or
60
+ * a symbol), read back as the protocol package reads JSON, so its arrays and objects nest at most 64 levels; undefined
61
+ * when it holds a number that is not finite, nests deeper, or `JSON.stringify` writes nothing for it or throws.
62
+ */
64
63
  function asJson(v) {
65
64
  try {
66
- const text = JSON.stringify(v);
67
- return text === undefined ? undefined : JSON.parse(text);
65
+ const text = JSON.stringify(v, (_k, x) => {
66
+ const n = x instanceof Number ? x.valueOf() : x;
67
+ if (typeof n === "number" && !Number.isFinite(n))
68
+ throw new RangeError("A number that is not finite.");
69
+ return x;
70
+ });
71
+ return text === undefined ? undefined : parseJson(text);
68
72
  }
69
73
  catch {
70
74
  return undefined;
@@ -75,7 +79,8 @@ function isHold(v) {
75
79
  HOLD_KEYS.every((k) => typeof v[k] === "string") &&
76
80
  DECIMAL.test(v["charged"]) &&
77
81
  DECIMAL.test(v["signedMax"]) &&
78
- isObject(v["opening"]));
82
+ isObject(v["opening"]) &&
83
+ (!Object.hasOwn(v, "landed") || isObject(v["landed"])));
79
84
  }
80
85
  /**
81
86
  * The channel an in-channel build's payment would name, read by the binding's `channel.ref` from the build completed
@@ -93,23 +98,53 @@ async function wouldBeChannel(batch, channel) {
93
98
  return isRefusal(ref) ? declined("offer-unreadable", ref.code) : ref;
94
99
  }
95
100
  /**
96
- * The buyer's own chain values a refund's build takes: a Solana `request_close` needs a recent blockhash when the option
97
- * names none, and may take the Compute Budget values.
101
+ * The buyer's own chain values a Solana refund's `request_close` takes, each optional: `recentBlockhash`, a base58
102
+ * blockhash; `computeUnitLimit`, a u32; and `computeUnitPrice`, a u64 as a decimal string. Undefined when one is given
103
+ * in another form. Only the refund taken again after the seller answers `BINDING_UNAVAILABLE` carries a
104
+ * `request_close`, and it needs the blockhash; the refund before it is the voucher alone, and takes none of these.
98
105
  */
99
106
  function refundInputs(inputs) {
100
107
  const out = {};
101
108
  const { recentBlockhash, computeUnitLimit, computeUnitPrice } = inputs;
102
- if (typeof recentBlockhash === "string")
109
+ if (recentBlockhash !== undefined) {
110
+ if (typeof recentBlockhash !== "string" || !KEY.test(recentBlockhash))
111
+ return undefined;
103
112
  out.recentBlockhash = recentBlockhash;
104
- if (typeof computeUnitLimit === "number" && Number.isSafeInteger(computeUnitLimit))
113
+ }
114
+ if (computeUnitLimit !== undefined) {
115
+ if (typeof computeUnitLimit !== "number" || !Number.isInteger(computeUnitLimit))
116
+ return undefined;
117
+ if (computeUnitLimit < 0 || computeUnitLimit > U32_MAX)
118
+ return undefined;
105
119
  out.computeUnitLimit = computeUnitLimit;
106
- if (typeof computeUnitPrice === "string" && DECIMAL.test(computeUnitPrice))
120
+ }
121
+ if (computeUnitPrice !== undefined) {
122
+ if (typeof computeUnitPrice !== "string" || !DECIMAL.test(computeUnitPrice))
123
+ return undefined;
124
+ if (BigInt(computeUnitPrice) >= U64_LIMIT)
125
+ return undefined;
107
126
  out.computeUnitPrice = BigInt(computeUnitPrice);
127
+ }
108
128
  return out;
109
129
  }
130
+ /**
131
+ * Whether a Solana refund is taken again after the receiver's binding is unavailable, as x402's reference client
132
+ * decides it: the `errorReason` of `refund.paymentResponse`, the settle failure's decoded `PAYMENT-RESPONSE`, read
133
+ * first, or else the payment request's `error`, is `BINDING_UNAVAILABLE`. Undefined when `paymentResponse` is given
134
+ * and is not an object, or its `errorReason` is given and is not a string.
135
+ */
136
+ function takenAgain(refund, required) {
137
+ const response = refund.paymentResponse;
138
+ if (response !== undefined && !isObject(response))
139
+ return undefined;
140
+ const settled = isObject(response) ? response["errorReason"] : undefined;
141
+ if (settled !== undefined && settled !== null && typeof settled !== "string")
142
+ return undefined;
143
+ return (settled ?? (isObject(required) ? required["error"] : undefined)) === BINDING_UNAVAILABLE;
144
+ }
110
145
  /** 24 random bytes as unpadded base64url: 32 characters from `[A-Za-z0-9_-]`. */
111
146
  function newRef() {
112
- return toBase64(crypto.getRandomValues(new Uint8Array(REF_BYTES))).replace(/\+/g, "-").replace(/\//g, "_");
147
+ return toBase64Url(crypto.getRandomValues(new Uint8Array(REF_BYTES)));
113
148
  }
114
149
  /** The opening voucher's `maxClaimableAmount`, where the payment carries one, else "0". */
115
150
  function openingMax(signed) {
@@ -118,10 +153,22 @@ function openingMax(signed) {
118
153
  const max = isObject(voucher) ? voucher["maxClaimableAmount"] : undefined;
119
154
  return typeof max === "string" && DECIMAL.test(max) ? max : "0";
120
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
+ }
121
163
  /**
122
164
  * Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
123
- * `transact` returned beside the opening, where it returned one. The opening, with that receipt, must be of kind `open`,
124
- * carry the hash of these bytes, and name its channel; the hold keeps all three 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.
125
172
  */
126
173
  export async function openChannel(bytes, opened, binding, landed) {
127
174
  const b = stepsOf(binding);
@@ -131,7 +178,7 @@ export async function openChannel(bytes, opened, binding, landed) {
131
178
  if (landed !== undefined && (!isObject(landed) || !isObject(opened))) {
132
179
  return declined("signed-not-bound", "The landed receipt is not a JSON object beside the opening.");
133
180
  }
134
- const signed = (landed === undefined ? opened : { ...opened, landed });
181
+ const signed = (landed === undefined ? opened : held(opened, landed));
135
182
  if (!(bytes instanceof Uint8Array))
136
183
  return declined("signed-not-bound", "The ATR bytes are missing.");
137
184
  if (bytes.length > MAX_ATR_BYTES)
@@ -143,14 +190,19 @@ export async function openChannel(bytes, opened, binding, landed) {
143
190
  const h = await hash(bytes);
144
191
  const inside = await guarded(() => b.bound(signed));
145
192
  if (isRefusal(inside) || !hashEquals(inside, h)) {
146
- return declined("signed-not-bound", "The opening does not carry the hash of these bytes.");
193
+ return declined("signed-not-bound", "The pairing does not read the hash of the compared bytes from the opening.");
147
194
  }
148
195
  const ref = await guarded(() => channel.ref(signed));
149
196
  if (isRefusal(ref))
150
197
  return declined("signed-not-bound", ref.code);
151
- const opening = asJson(signed);
198
+ const opening = asJson(opened);
152
199
  if (!isObject(opening))
153
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
+ }
154
206
  return {
155
207
  pairing: b.id,
156
208
  network: ref.network,
@@ -158,17 +210,32 @@ export async function openChannel(bytes, opened, binding, landed) {
158
210
  h,
159
211
  atr: toBase64(bytes),
160
212
  opening,
213
+ ...(read === undefined ? {} : { landed: read }),
161
214
  charged: "0",
162
215
  signedMax: openingMax(signed),
163
216
  };
164
217
  }
165
218
  /**
166
219
  * Signs one later voucher, or a refund, in a held channel. The ATR bytes, the opening's hash and the opening's
167
- * channel are re-derived from the hold, and the challenge must advertise the held hash. A voucher's
168
- * `maxClaimableAmount` is the recorded charge plus the option's amount; a refund's is the recorded charge. `inputs`
169
- * are the buyer's own chain values a refund's build takes. Before the signer is called, the channel the built payment
170
- * would name must be the held one. What was signed must be of the expected kind and belong to the held channel, or it
171
- * is dropped.
220
+ * channel are re-derived from the hold. An x402 challenge must advertise the held hash. An MPP session's challenge
221
+ * that names another channel or another hash is declined, and one with no legal context is signed under the held
222
+ * hash. A voucher's `maxClaimableAmount` is the recorded charge plus the option's amount; a refund's is the recorded
223
+ * charge. `inputs` are the buyer's own chain values a refund's build takes; `inputs` that is not an object is declined
224
+ * `no-payable-option` with `<namespace>/input-malformed`.
225
+ *
226
+ * A Solana refund is the voucher alone. Taken again after the receiver's binding is unavailable, it also carries the
227
+ * payer-signed `request_close`, built with the `recentBlockhash`, `computeUnitLimit` and `computeUnitPrice` of
228
+ * `inputs`: when the `errorReason` of `refund.paymentResponse`, the settle failure's decoded `PAYMENT-RESPONSE`, read
229
+ * first, or else the challenge's `error`, is `invalid_batch_settlement_svm_receiver_binding_unavailable`. A Solana
230
+ * refund value given in another form, or a `paymentResponse` that is not an object or whose `errorReason` is not a
231
+ * string, is declined `no-payable-option` with `x402/input-malformed`, and the refund taken again without a
232
+ * `recentBlockhash` with `x402/input-missing`. No other pairing's refund reads these values or this code.
233
+ *
234
+ * On x402's batch channels, the channel the built payment would name must be the held one before the signer is called.
235
+ * On MPP's sessions, a channel the challenge names must be the held one and a legal context, where present, must name
236
+ * the held hash, before the signer is called, and the voucher is built from the held opening. In both, the signed
237
+ * payment must then be of the expected kind, commit to the held hash where the pairing's voucher carries one, and
238
+ * name the held channel, or it is dropped.
172
239
  */
173
240
  export async function within(doc, hold, binding, signer, refund, inputs = {}) {
174
241
  const b = stepsOf(binding);
@@ -190,18 +257,21 @@ export async function within(doc, hold, binding, signer, refund, inputs = {}) {
190
257
  }
191
258
  refundAmount = refund.amount === undefined ? undefined : BigInt(refund.amount);
192
259
  }
260
+ if (!isObject(inputs))
261
+ return declined("no-payable-option", `${ns}/input-malformed`);
193
262
  const channel = b.channel;
194
263
  const bytes = fromBase64(hold.atr);
195
- if (bytes === undefined || bytes.length > MAX_ATR_BYTES)
264
+ if (bytes === null || bytes.length > MAX_ATR_BYTES)
196
265
  return declined("signed-not-bound", "The held ATR is unreadable.");
197
266
  const h = await hash(bytes);
198
267
  if (!hashEquals(hold.h, h))
199
268
  return declined("hash-mismatch", "The held ATR does not hash to the held hash.");
200
- const opened = await guarded(() => b.bound(hold.opening));
269
+ const opening = heldOpening(hold);
270
+ const opened = await guarded(() => b.bound(opening));
201
271
  if (isRefusal(opened) || !hashEquals(opened, h)) {
202
- return declined("signed-not-bound", "The held opening does not carry the held ATR's hash.");
272
+ return declined("signed-not-bound", "The pairing does not read the held ATR's hash from the held opening.");
203
273
  }
204
- const openedRef = await guarded(() => channel.ref(hold.opening));
274
+ const openedRef = await guarded(() => channel.ref(opening));
205
275
  if (isRefusal(openedRef) || openedRef.network !== hold.network || openedRef.channel !== hold.channel) {
206
276
  return declined("signed-not-bound", "The held opening does not name the held channel.");
207
277
  }
@@ -225,13 +295,20 @@ export async function within(doc, hold, binding, signer, refund, inputs = {}) {
225
295
  const payload = hold.opening["payload"];
226
296
  const channelConfig = isObject(payload) ? payload["channelConfig"] : undefined;
227
297
  const required = isObject(offer) ? offer["required"] : undefined;
298
+ const solanaRefund = refund !== undefined && b.id === SOLANA_BATCH;
299
+ const values = solanaRefund ? refundInputs(inputs) : {};
300
+ const retry = solanaRefund ? takenAgain(refund, required) : false;
301
+ if (values === undefined || retry === undefined)
302
+ return declined("no-payable-option", `${ns}/input-malformed`);
303
+ if (retry && values.recentBlockhash === undefined)
304
+ return declined("no-payable-option", `${ns}/input-missing`);
228
305
  const unsigned = await guarded(() => b.buildWithin({
229
306
  required,
230
307
  accepted,
231
308
  channelConfig,
232
309
  maxClaimableAmount,
233
310
  ...(refund !== undefined ? { refund: refundAmount === undefined ? {} : { amount: refundAmount } } : {}),
234
- ...(refund !== undefined ? refundInputs(isObject(inputs) ? inputs : {}) : {}),
311
+ ...(retry ? values : {}),
235
312
  }, h));
236
313
  if (isRefusal(unsigned))
237
314
  return declined("offer-unreadable", unsigned.code);
@@ -280,10 +357,10 @@ export async function within(doc, hold, binding, signer, refund, inputs = {}) {
280
357
  /**
281
358
  * One voucher, or the close, in a held MPP session. The within challenge is the first of the document that either
282
359
  * offers the pairing on the held network, or names a channel of the pairing on the held network, as `sessionResume`
283
- * reads it for the pairing's method. A named channel must be the held one, and a legal context in
284
- * the challenge's `opaque` must name the held hash; either is checked before the signer is called. The voucher's
285
- * cumulative amount is the recorded charge plus the challenge's amount, and the close's is the recorded charge. Every
286
- * channel value comes from the held opening, through the binding's `buildWithin`.
360
+ * reads it for the pairing's method. A named channel must be the held one, the challenge's `opaque`, where present,
361
+ * must be MPP's flat string-to-string map, and a legal context in it must name the held hash; each is checked before
362
+ * the signer is called. The voucher's cumulative amount is the recorded charge plus the challenge's amount, and the
363
+ * close's is the recorded charge. Every channel value comes from the held opening, through the binding's `buildWithin`.
287
364
  */
288
365
  async function sessionWithin(b, doc, hold, h, signer, refund) {
289
366
  if (refund !== undefined && refund.amount !== undefined) {
@@ -317,8 +394,8 @@ async function sessionWithin(b, doc, hold, h, signer, refund) {
317
394
  if (challenge === undefined)
318
395
  return declined("no-payable-option", "mpp/no-payable-option");
319
396
  const named = legalContextOf(challenge);
320
- if (named === "malformed")
321
- return declined("offer-unreadable", "mpp/legal-context-malformed");
397
+ if (isRefusal(named))
398
+ return declined("offer-unreadable", named.code);
322
399
  if (named !== undefined && !hashEquals(named, h)) {
323
400
  return declined("hash-mismatch", "The challenge names another ATR's hash than the one this channel opened for.");
324
401
  }
@@ -327,7 +404,8 @@ async function sessionWithin(b, doc, hold, h, signer, refund) {
327
404
  return declined("offer-unreadable", "mpp/request-malformed");
328
405
  const action = refund !== undefined ? "close" : "voucher";
329
406
  const cumulativeAmount = action === "close" ? BigInt(hold.charged) : BigInt(hold.charged) + BigInt(amount);
330
- 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));
331
409
  if (isRefusal(unsigned)) {
332
410
  const code = unsigned.code.endsWith("/within-action-not-built") ? "pairing-not-supported" : "offer-unreadable";
333
411
  return declined(code, unsigned.code);
@@ -376,32 +454,27 @@ function namedChannel(c, pairing) {
376
454
  }
377
455
  /**
378
456
  * The hash a challenge's `opaque` names as its legal context: undefined when there is no `opaque` or it has no
379
- * `legalContext` member, "malformed" when either cannot be read.
457
+ * `legalContext` member; `mpp/opaque-malformed` when the `opaque` is not a flat string-to-string map (`opaqueMap`);
458
+ * `mpp/legal-context-malformed` when its `legalContext` is not an LCP string.
380
459
  */
381
460
  function legalContextOf(c) {
382
461
  if (c.opaque === undefined)
383
462
  return undefined;
384
- const map = typeof c.opaque === "string" ? base64UrlJson(c.opaque) : undefined;
385
- if (!isObject(map))
386
- return "malformed";
463
+ const map = opaqueMap(c.opaque);
464
+ if (map === undefined)
465
+ return refuse("mpp/opaque-malformed");
387
466
  const lc = map["legalContext"];
388
467
  if (lc === undefined)
389
468
  return undefined;
390
- const named = typeof lc === "string" ? fromLcpString(lc) : null;
391
- return named ?? "malformed";
469
+ return fromLcpString(lc) ?? refuse("mpp/legal-context-malformed");
392
470
  }
393
- /** A base64url string's bytes read as one JSON value, or undefined. */
394
- function base64UrlJson(s) {
395
- if (s.length > MAX_OPAQUE || !/^[A-Za-z0-9_-]*$/.test(s))
396
- return undefined;
397
- try {
398
- const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
399
- const binary = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
400
- return parseJson(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(binary, (ch) => ch.charCodeAt(0))));
401
- }
402
- catch {
403
- return undefined;
404
- }
471
+ /**
472
+ * An `opaque` read as MPP's flat string-to-string map: an object `decodeObject` reads, whose members are all strings.
473
+ * Undefined for anything else.
474
+ */
475
+ function opaqueMap(s) {
476
+ const v = decodeObject(s);
477
+ return v !== undefined && Object.values(v).every((m) => typeof m === "string") ? v : undefined;
405
478
  }
406
479
  /**
407
480
  * Records the server's cumulative charge for the channel. It must be a decimal no lower than the charge last recorded
package/dist/gate.d.ts CHANGED
@@ -1,14 +1,16 @@
1
1
  /**
2
2
  * The buyer gate. `confirm` reads the offer, fetches the ATR from the seller's link, compares its SHA-256 with the
3
3
  * advertised hash, and only on a match builds the signing request with the hash it computed. `finish` completes the
4
- * payment with the signature and returns it only when what was signed carries the hash of these bytes, or, for a pairing
5
- * whose proof is the agreement payment, completes it without that reading. `check` confirms a payment held later against
6
- * kept bytes.
4
+ * payment with the signature and returns it only when the pairing's `bound` reads the hash of these bytes from the
5
+ * completed payment, or, for a pairing whose proof is the agreement payment, completes it without that reading. `check`
6
+ * confirms a payment held later against kept bytes.
7
7
  */
8
- import { type AtrHash } from "@integraledger/lcp";
8
+ import { type AtrHash } from "@integraledger/lcp/core";
9
9
  import { type Binding, type BuyerPiece, type Chosen, type DeclineCode, type Declined, type Fetch, type Inputs, type Presented, type Signature, type Signer, type SigningRequest } from "./types.js";
10
10
  export declare function declined(code: DeclineCode, detail: string): Declined;
11
11
  export declare function isObject(v: unknown): v is Record<string, unknown>;
12
+ /** Whether a signer's `account` is a string, the form every pairing reads its payer from. */
13
+ export declare function hasAccount(signer: unknown): boolean;
12
14
  /** The pairing's namespace: its id up to the first `/`. */
13
15
  export declare function namespaceOf(binding: Binding): string;
14
16
  export declare function pieceOf(binding: Binding): BuyerPiece | undefined;
@@ -21,13 +23,23 @@ export declare function redirected(response: Response): boolean;
21
23
  export declare const IDENTITY: {
22
24
  readonly "Accept-Encoding": "identity";
23
25
  };
24
- /** Whether a `Content-Encoding` value names no coding: absent, empty, or `identity`. */
26
+ /**
27
+ * A header value without its leading and trailing HTTP whitespace, as Fetch normalizes one. Any other character stays,
28
+ * so a value it surrounds is read as written.
29
+ */
30
+ export declare function trimHttpWhitespace(value: string): string;
31
+ /**
32
+ * Whether a `Content-Encoding` value names no coding: absent, empty, or `identity`, surrounding spaces, tabs, CRs and
33
+ * LFs aside.
34
+ */
25
35
  export declare function isIdentity(contentEncoding: string | null): boolean;
26
36
  /**
27
37
  * Reads the offer, chooses the option, fetches the ATR and compares its SHA-256 with the advertised hash. Only on a
28
- * match does it build, with the hash it computed. A pairing whose build has nothing for the buyer to sign returns
29
- * `request: null`: the comparison is the whole of the buyer's step. For a pairing whose payment is not itself a public
30
- * proof, `chosen.agreement` is the agreement URL the offer names.
38
+ * match does it build, with the hash it computed. `request` is what the signer is handed, or `null` when nothing is
39
+ * handed to the signer: the pairing has nothing for the buyer to sign, or the build is itself the payment, which
40
+ * `finish` completes with no signature. For a pairing whose payment is not itself a public proof, `chosen.agreement` is
41
+ * the agreement URL the offer names. `inputs` that is not an object is declined `no-payable-option` with
42
+ * `<namespace>/input-malformed` before the offer is read.
31
43
  */
32
44
  export declare function confirm(doc: unknown, binding: Binding, account: string, fetch: Fetch, inputs?: Inputs): Promise<{
33
45
  chosen: Chosen;
@@ -36,12 +48,13 @@ export declare function confirm(doc: unknown, binding: Binding, account: string,
36
48
  h: AtrHash;
37
49
  } | Declined>;
38
50
  /**
39
- * Rebuilds the payment from `chosen` and the bytes, joins the signer's answer, and returns the payment only when what
40
- * was signed carries the hash of these bytes. For a pairing whose payment is not a public proof and whose `bound` finds
41
- * no signed place for the hash, the proof is the agreement payment, and the completed payment is returned as it is.
42
- * Where the signer moved the payment itself, a decline keeps it as `moved`. Where the completion carried the landed
43
- * receipt `bound` reads and the payment sent leaves it out, `landed` is returned beside the payment as JSON, each integer
44
- * a decimal string, so `check` and `openChannel` can later read the payment with it.
51
+ * Rebuilds the payment from `chosen` and the bytes, joins the signer's answer, and returns the payment only when the
52
+ * pairing's `bound` reads the hash of these bytes from the completed payment. For a pairing whose payment is not a
53
+ * public proof and whose `bound` finds no signed place for the hash, the proof is the agreement payment, and the
54
+ * completed payment is returned as it is. Where the signer moved the payment itself, a decline keeps it as `moved`.
55
+ * Where the completion carried the landed receipt `bound` reads and the payment sent leaves it out, `landed` is
56
+ * returned beside the payment as JSON, each integer a decimal string, so `check` and `openChannel` can later read the
57
+ * payment with it.
45
58
  */
46
59
  export declare function finish(bytes: Uint8Array, chosen: Chosen, signature: Signature, binding: Binding): Promise<{
47
60
  signed: Presented;
@@ -51,8 +64,16 @@ export declare function finish(bytes: Uint8Array, chosen: Chosen, signature: Sig
51
64
  next: SigningRequest;
52
65
  h: AtrHash;
53
66
  } | Declined>;
54
- /** Confirms that a payment held later carries, inside what was signed, the hash of the kept bytes. */
55
- export declare function check(bytes: Uint8Array, presented: unknown, binding: Binding): Promise<{
67
+ /**
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.
75
+ */
76
+ export declare function check(bytes: Uint8Array, presented: unknown, binding: Binding, landed?: unknown): Promise<{
56
77
  h: AtrHash;
57
78
  } | Declined>;
58
79
  /**