@integraledger/terms 0.1.0 → 0.3.0

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 (51) hide show
  1. package/README.md +135 -65
  2. package/dist/agreement.d.ts +21 -17
  3. package/dist/agreement.js +279 -85
  4. package/dist/channels.d.ts +35 -12
  5. package/dist/channels.js +152 -70
  6. package/dist/gate.d.ts +41 -18
  7. package/dist/gate.js +81 -47
  8. package/dist/index.d.ts +1 -1
  9. package/dist/pairings/batch.d.ts +2 -5
  10. package/dist/pairings/batch.js +3 -13
  11. package/dist/pairings/card.js +0 -2
  12. package/dist/pairings/common.d.ts +7 -1
  13. package/dist/pairings/common.js +17 -2
  14. package/dist/pairings/evm-x402.js +3 -3
  15. package/dist/pairings/lightning.js +1 -1
  16. package/dist/pairings/lnbtc-request.d.ts +1 -1
  17. package/dist/pairings/lnbtc-request.js +1 -1
  18. package/dist/pairings/mpp-charge-hedera.d.ts +7 -7
  19. package/dist/pairings/mpp-charge-hedera.js +1 -1
  20. package/dist/pairings/mpp-charge-stellar.js +1 -1
  21. package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
  22. package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
  23. package/dist/pairings/mpp-charge-tempo-push.d.ts +0 -1
  24. package/dist/pairings/mpp-charge-tempo-push.js +2 -10
  25. package/dist/pairings/mpp-charge-xrpl.js +3 -3
  26. package/dist/pairings/mpp-rails.d.ts +1 -1
  27. package/dist/pairings/mpp-session-solana.js +2 -2
  28. package/dist/pairings/mpp-session-xrpl.js +3 -4
  29. package/dist/pairings/mpp-session.js +1 -1
  30. package/dist/pairings/mpp.d.ts +12 -16
  31. package/dist/pairings/mpp.js +32 -109
  32. package/dist/pairings/protocol-groups.d.ts +1 -1
  33. package/dist/pairings/x402-account-rails.d.ts +1 -1
  34. package/dist/pairings/x402-batch-settlement-eip155.js +1 -1
  35. package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
  36. package/dist/pairings/x402-batch-settlement-solana.js +3 -2
  37. package/dist/pairings/x402-exact-casper.js +3 -3
  38. package/dist/pairings/x402-exact-ccd.js +3 -3
  39. package/dist/pairings/x402-exact-hedera.d.ts +4 -1
  40. package/dist/pairings/x402-exact-hedera.js +5 -2
  41. package/dist/pairings/x402-exact-solana.d.ts +4 -4
  42. package/dist/pairings/x402-exact-solana.js +3 -2
  43. package/dist/pairings/x402-exact-stellar.js +1 -1
  44. package/dist/pairings/x402-exact-sui.js +3 -1
  45. package/dist/pairings/x402-exact-tvm.js +10 -2
  46. package/dist/pairings/x402-exact-xrpl.js +2 -4
  47. package/dist/pairings/x402-rail.d.ts +1 -1
  48. package/dist/transact.d.ts +14 -9
  49. package/dist/transact.js +30 -24
  50. package/dist/types.d.ts +43 -18
  51. package/package.json +11 -12
package/dist/channels.js CHANGED
@@ -1,30 +1,47 @@
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 { withPaymentIdentifier } from "./pairings/common.js";
12
+ import { decodeObject, offers, requestOf } from "./pairings/mpp.js";
13
+ import { isRefusal, 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"];
32
+ /**
33
+ * For each request kind an in-channel build returns, an answer of the form that kind takes, of zero bytes: 65 bytes in
34
+ * `0x` hex for `eip712`, 64 bytes in base58 for `ed25519-raw` and `solana-message`. It completes a build without a
35
+ * signature, so that the channel its payment names can be read before the signer is called.
36
+ */
37
+ const UNSIGNED_ANSWER = Object.freeze({
38
+ eip712: `0x${"00".repeat(65)}`,
39
+ "ed25519-raw": "1".repeat(64),
40
+ "solana-message": "1".repeat(64),
41
+ });
22
42
  function declined(code, detail) {
23
43
  return { decline: { code, detail } };
24
44
  }
25
- function isRefusal(v) {
26
- return typeof v === "object" && v !== null && v.refused === true;
27
- }
28
45
  function isObject(v) {
29
46
  return typeof v === "object" && v !== null && !Array.isArray(v);
30
47
  }
@@ -35,29 +52,23 @@ async function guarded(run) {
35
52
  return await run();
36
53
  }
37
54
  catch {
38
- return { refused: true, code: "member-failed" };
39
- }
40
- }
41
- function toBase64(bytes) {
42
- let s = "";
43
- for (let i = 0; i < bytes.length; i += 0x8000)
44
- s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
45
- return btoa(s);
46
- }
47
- function fromBase64(s) {
48
- try {
49
- const binary = atob(s);
50
- return Uint8Array.from(binary, (c) => c.charCodeAt(0));
51
- }
52
- catch {
53
- return undefined;
55
+ return refuse("member-failed");
54
56
  }
55
57
  }
56
- /** 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
+ */
57
63
  function asJson(v) {
58
64
  try {
59
- const text = JSON.stringify(v);
60
- 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);
61
72
  }
62
73
  catch {
63
74
  return undefined;
@@ -71,23 +82,68 @@ function isHold(v) {
71
82
  isObject(v["opening"]));
72
83
  }
73
84
  /**
74
- * The buyer's own chain values a refund's build takes: a Solana `request_close` needs a recent blockhash when the option
75
- * names none, and may take the Compute Budget values.
85
+ * The channel an in-channel build's payment would name, read by the binding's `channel.ref` from the build completed
86
+ * with `UNSIGNED_ANSWER`s, before anything is signed.
87
+ */
88
+ async function wouldBeChannel(batch, channel) {
89
+ const answers = batch.requests.map((r) => (Object.hasOwn(UNSIGNED_ANSWER, r.kind) ? UNSIGNED_ANSWER[r.kind] : undefined));
90
+ if (!answers.every((a) => a !== undefined)) {
91
+ return declined("offer-unreadable", "The in-channel payment's channel cannot be read before it is signed.");
92
+ }
93
+ const completed = await guarded(() => batch.complete(answers));
94
+ if (isRefusal(completed))
95
+ return declined("offer-unreadable", completed.code);
96
+ const ref = await guarded(() => channel.ref(completed));
97
+ return isRefusal(ref) ? declined("offer-unreadable", ref.code) : ref;
98
+ }
99
+ /**
100
+ * The buyer's own chain values a Solana refund's `request_close` takes, each optional: `recentBlockhash`, a base58
101
+ * blockhash; `computeUnitLimit`, a u32; and `computeUnitPrice`, a u64 as a decimal string. Undefined when one is given
102
+ * in another form. Only the refund taken again after the seller answers `BINDING_UNAVAILABLE` carries a
103
+ * `request_close`, and it needs the blockhash; the refund before it is the voucher alone, and takes none of these.
76
104
  */
77
105
  function refundInputs(inputs) {
78
106
  const out = {};
79
107
  const { recentBlockhash, computeUnitLimit, computeUnitPrice } = inputs;
80
- if (typeof recentBlockhash === "string")
108
+ if (recentBlockhash !== undefined) {
109
+ if (typeof recentBlockhash !== "string" || !KEY.test(recentBlockhash))
110
+ return undefined;
81
111
  out.recentBlockhash = recentBlockhash;
82
- if (typeof computeUnitLimit === "number" && Number.isSafeInteger(computeUnitLimit))
112
+ }
113
+ if (computeUnitLimit !== undefined) {
114
+ if (typeof computeUnitLimit !== "number" || !Number.isInteger(computeUnitLimit))
115
+ return undefined;
116
+ if (computeUnitLimit < 0 || computeUnitLimit > U32_MAX)
117
+ return undefined;
83
118
  out.computeUnitLimit = computeUnitLimit;
84
- if (typeof computeUnitPrice === "string" && DECIMAL.test(computeUnitPrice))
119
+ }
120
+ if (computeUnitPrice !== undefined) {
121
+ if (typeof computeUnitPrice !== "string" || !DECIMAL.test(computeUnitPrice))
122
+ return undefined;
123
+ if (BigInt(computeUnitPrice) >= U64_LIMIT)
124
+ return undefined;
85
125
  out.computeUnitPrice = BigInt(computeUnitPrice);
126
+ }
86
127
  return out;
87
128
  }
129
+ /**
130
+ * Whether a Solana refund is taken again after the receiver's binding is unavailable, as x402's reference client
131
+ * decides it: the `errorReason` of `refund.paymentResponse`, the settle failure's decoded `PAYMENT-RESPONSE`, read
132
+ * first, or else the payment request's `error`, is `BINDING_UNAVAILABLE`. Undefined when `paymentResponse` is given
133
+ * and is not an object, or its `errorReason` is given and is not a string.
134
+ */
135
+ function takenAgain(refund, required) {
136
+ const response = refund.paymentResponse;
137
+ if (response !== undefined && !isObject(response))
138
+ return undefined;
139
+ const settled = isObject(response) ? response["errorReason"] : undefined;
140
+ if (settled !== undefined && settled !== null && typeof settled !== "string")
141
+ return undefined;
142
+ return (settled ?? (isObject(required) ? required["error"] : undefined)) === BINDING_UNAVAILABLE;
143
+ }
88
144
  /** 24 random bytes as unpadded base64url: 32 characters from `[A-Za-z0-9_-]`. */
89
145
  function newRef() {
90
- return toBase64(crypto.getRandomValues(new Uint8Array(REF_BYTES))).replace(/\+/g, "-").replace(/\//g, "_");
146
+ return toBase64Url(crypto.getRandomValues(new Uint8Array(REF_BYTES)));
91
147
  }
92
148
  /** The opening voucher's `maxClaimableAmount`, where the payment carries one, else "0". */
93
149
  function openingMax(signed) {
@@ -99,7 +155,8 @@ function openingMax(signed) {
99
155
  /**
100
156
  * Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
101
157
  * `transact` returned beside the opening, where it returned one. The opening, with that receipt, must be of kind `open`,
102
- * carry the hash of these bytes, and name its channel; the hold keeps all three together.
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.
103
160
  */
104
161
  export async function openChannel(bytes, opened, binding, landed) {
105
162
  const b = stepsOf(binding);
@@ -121,7 +178,7 @@ export async function openChannel(bytes, opened, binding, landed) {
121
178
  const h = await hash(bytes);
122
179
  const inside = await guarded(() => b.bound(signed));
123
180
  if (isRefusal(inside) || !hashEquals(inside, h)) {
124
- return declined("signed-not-bound", "The opening does not carry the hash of these bytes.");
181
+ return declined("signed-not-bound", "The pairing does not read the hash of the compared bytes from the opening.");
125
182
  }
126
183
  const ref = await guarded(() => channel.ref(signed));
127
184
  if (isRefusal(ref))
@@ -142,10 +199,25 @@ export async function openChannel(bytes, opened, binding, landed) {
142
199
  }
143
200
  /**
144
201
  * Signs one later voucher, or a refund, in a held channel. The ATR bytes, the opening's hash and the opening's
145
- * channel are re-derived from the hold, and the challenge must advertise the held hash. A voucher's
146
- * `maxClaimableAmount` is the recorded charge plus the option's amount; a refund's is the recorded charge. `inputs`
147
- * are the buyer's own chain values a refund's build takes. What was signed must be of the expected kind and belong to
148
- * the held channel, or it is dropped.
202
+ * channel are re-derived from the hold. An x402 challenge must advertise the held hash. An MPP session's challenge
203
+ * that names another channel or another hash is declined, and one with no legal context is signed under the held
204
+ * hash. A voucher's `maxClaimableAmount` is the recorded charge plus the option's amount; a refund's is the recorded
205
+ * charge. `inputs` are the buyer's own chain values a refund's build takes; `inputs` that is not an object is declined
206
+ * `no-payable-option` with `<namespace>/input-malformed`.
207
+ *
208
+ * A Solana refund is the voucher alone. Taken again after the receiver's binding is unavailable, it also carries the
209
+ * payer-signed `request_close`, built with the `recentBlockhash`, `computeUnitLimit` and `computeUnitPrice` of
210
+ * `inputs`: when the `errorReason` of `refund.paymentResponse`, the settle failure's decoded `PAYMENT-RESPONSE`, read
211
+ * first, or else the challenge's `error`, is `invalid_batch_settlement_svm_receiver_binding_unavailable`. A Solana
212
+ * refund value given in another form, or a `paymentResponse` that is not an object or whose `errorReason` is not a
213
+ * string, is declined `no-payable-option` with `x402/input-malformed`, and the refund taken again without a
214
+ * `recentBlockhash` with `x402/input-missing`. No other pairing's refund reads these values or this code.
215
+ *
216
+ * On x402's batch channels, the channel the built payment would name must be the held one before the signer is called.
217
+ * On MPP's sessions, a channel the challenge names must be the held one and a legal context, where present, must name
218
+ * the held hash, before the signer is called, and the voucher is built from the held opening. In both, the signed
219
+ * payment must then be of the expected kind, commit to the held hash where the pairing's voucher carries one, and
220
+ * name the held channel, or it is dropped.
149
221
  */
150
222
  export async function within(doc, hold, binding, signer, refund, inputs = {}) {
151
223
  const b = stepsOf(binding);
@@ -167,16 +239,18 @@ export async function within(doc, hold, binding, signer, refund, inputs = {}) {
167
239
  }
168
240
  refundAmount = refund.amount === undefined ? undefined : BigInt(refund.amount);
169
241
  }
242
+ if (!isObject(inputs))
243
+ return declined("no-payable-option", `${ns}/input-malformed`);
170
244
  const channel = b.channel;
171
245
  const bytes = fromBase64(hold.atr);
172
- if (bytes === undefined || bytes.length > MAX_ATR_BYTES)
246
+ if (bytes === null || bytes.length > MAX_ATR_BYTES)
173
247
  return declined("signed-not-bound", "The held ATR is unreadable.");
174
248
  const h = await hash(bytes);
175
249
  if (!hashEquals(hold.h, h))
176
250
  return declined("hash-mismatch", "The held ATR does not hash to the held hash.");
177
251
  const opened = await guarded(() => b.bound(hold.opening));
178
252
  if (isRefusal(opened) || !hashEquals(opened, h)) {
179
- return declined("signed-not-bound", "The held opening does not carry the held ATR's hash.");
253
+ return declined("signed-not-bound", "The pairing does not read the held ATR's hash from the held opening.");
180
254
  }
181
255
  const openedRef = await guarded(() => channel.ref(hold.opening));
182
256
  if (isRefusal(openedRef) || openedRef.network !== hold.network || openedRef.channel !== hold.channel) {
@@ -202,17 +276,30 @@ export async function within(doc, hold, binding, signer, refund, inputs = {}) {
202
276
  const payload = hold.opening["payload"];
203
277
  const channelConfig = isObject(payload) ? payload["channelConfig"] : undefined;
204
278
  const required = isObject(offer) ? offer["required"] : undefined;
279
+ const solanaRefund = refund !== undefined && b.id === SOLANA_BATCH;
280
+ const values = solanaRefund ? refundInputs(inputs) : {};
281
+ const retry = solanaRefund ? takenAgain(refund, required) : false;
282
+ if (values === undefined || retry === undefined)
283
+ return declined("no-payable-option", `${ns}/input-malformed`);
284
+ if (retry && values.recentBlockhash === undefined)
285
+ return declined("no-payable-option", `${ns}/input-missing`);
205
286
  const unsigned = await guarded(() => b.buildWithin({
206
287
  required,
207
288
  accepted,
208
289
  channelConfig,
209
290
  maxClaimableAmount,
210
291
  ...(refund !== undefined ? { refund: refundAmount === undefined ? {} : { amount: refundAmount } } : {}),
211
- ...(refund !== undefined ? refundInputs(isObject(inputs) ? inputs : {}) : {}),
292
+ ...(retry ? values : {}),
212
293
  }, h));
213
294
  if (isRefusal(unsigned))
214
295
  return declined("offer-unreadable", unsigned.code);
215
296
  const batch = unsigned;
297
+ const wouldBe = await wouldBeChannel(batch, channel);
298
+ if ("decline" in wouldBe)
299
+ return wouldBe;
300
+ if (wouldBe.network !== hold.network || wouldBe.channel !== hold.channel) {
301
+ return declined("no-payable-option", "The challenge asks for a payment in a channel this hold did not open.");
302
+ }
216
303
  const request = {
217
304
  kind: "batch",
218
305
  requests: batch.requests,
@@ -251,10 +338,10 @@ export async function within(doc, hold, binding, signer, refund, inputs = {}) {
251
338
  /**
252
339
  * One voucher, or the close, in a held MPP session. The within challenge is the first of the document that either
253
340
  * offers the pairing on the held network, or names a channel of the pairing on the held network, as `sessionResume`
254
- * reads it for the pairing's method. A named channel must be the held one, and a legal context in
255
- * the challenge's `opaque` must name the held hash; either is checked before the signer is called. The voucher's
256
- * cumulative amount is the recorded charge plus the challenge's amount, and the close's is the recorded charge. Every
257
- * channel value comes from the held opening, through the binding's `buildWithin`.
341
+ * reads it for the pairing's method. A named channel must be the held one, the challenge's `opaque`, where present,
342
+ * must be MPP's flat string-to-string map, and a legal context in it must name the held hash; each is checked before
343
+ * the signer is called. The voucher's cumulative amount is the recorded charge plus the challenge's amount, and the
344
+ * close's is the recorded charge. Every channel value comes from the held opening, through the binding's `buildWithin`.
258
345
  */
259
346
  async function sessionWithin(b, doc, hold, h, signer, refund) {
260
347
  if (refund !== undefined && refund.amount !== undefined) {
@@ -288,8 +375,8 @@ async function sessionWithin(b, doc, hold, h, signer, refund) {
288
375
  if (challenge === undefined)
289
376
  return declined("no-payable-option", "mpp/no-payable-option");
290
377
  const named = legalContextOf(challenge);
291
- if (named === "malformed")
292
- return declined("offer-unreadable", "mpp/legal-context-malformed");
378
+ if (isRefusal(named))
379
+ return declined("offer-unreadable", named.code);
293
380
  if (named !== undefined && !hashEquals(named, h)) {
294
381
  return declined("hash-mismatch", "The challenge names another ATR's hash than the one this channel opened for.");
295
382
  }
@@ -347,32 +434,27 @@ function namedChannel(c, pairing) {
347
434
  }
348
435
  /**
349
436
  * The hash a challenge's `opaque` names as its legal context: undefined when there is no `opaque` or it has no
350
- * `legalContext` member, "malformed" when either cannot be read.
437
+ * `legalContext` member; `mpp/opaque-malformed` when the `opaque` is not a flat string-to-string map (`opaqueMap`);
438
+ * `mpp/legal-context-malformed` when its `legalContext` is not an LCP string.
351
439
  */
352
440
  function legalContextOf(c) {
353
441
  if (c.opaque === undefined)
354
442
  return undefined;
355
- const map = typeof c.opaque === "string" ? base64UrlJson(c.opaque) : undefined;
356
- if (!isObject(map))
357
- return "malformed";
443
+ const map = opaqueMap(c.opaque);
444
+ if (map === undefined)
445
+ return refuse("mpp/opaque-malformed");
358
446
  const lc = map["legalContext"];
359
447
  if (lc === undefined)
360
448
  return undefined;
361
- const named = typeof lc === "string" ? fromLcpString(lc) : null;
362
- return named ?? "malformed";
449
+ return fromLcpString(lc) ?? refuse("mpp/legal-context-malformed");
363
450
  }
364
- /** A base64url string's bytes read as one JSON value, or undefined. */
365
- function base64UrlJson(s) {
366
- if (s.length > MAX_OPAQUE || !/^[A-Za-z0-9_-]*$/.test(s))
367
- return undefined;
368
- try {
369
- const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
370
- const binary = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
371
- return parseJson(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(binary, (ch) => ch.charCodeAt(0))));
372
- }
373
- catch {
374
- return undefined;
375
- }
451
+ /**
452
+ * An `opaque` read as MPP's flat string-to-string map: an object `decodeObject` reads, whose members are all strings.
453
+ * Undefined for anything else.
454
+ */
455
+ function opaqueMap(s) {
456
+ const v = decodeObject(s);
457
+ return v !== undefined && Object.values(v).every((m) => typeof m === "string") ? v : undefined;
376
458
  }
377
459
  /**
378
460
  * 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";
9
- import { type Binding, type BuyerPiece, type Chosen, type DeclineCode, type Declined, type Fetch, type Inputs, type Presented, type Read, type Signature, type Signer, type SigningRequest } from "./types.js";
8
+ import { type AtrHash } from "@integraledger/lcp/core";
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;
@@ -17,25 +19,42 @@ export declare function unsupported(binding: Binding): Declined;
17
19
  export declare function newRef(): string;
18
20
  /** Whether an answer to a `redirect: "manual"` request is a redirect: a 3xx status, or the opaque form a browser gives. */
19
21
  export declare function redirected(response: Response): boolean;
22
+ /** The request header that asks for the body with no content coding, so the bytes hashed are the bytes sent. */
23
+ export declare const IDENTITY: {
24
+ readonly "Accept-Encoding": "identity";
25
+ };
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
+ */
35
+ export declare function isIdentity(contentEncoding: string | null): boolean;
20
36
  /**
21
37
  * Reads the offer, chooses the option, fetches the ATR and compares its SHA-256 with the advertised hash. Only on a
22
- * match does it build, with the hash it computed. A pairing whose build has nothing for the buyer to sign returns
23
- * `request: null`: the comparison is the whole of the buyer's step.
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.
24
43
  */
25
44
  export declare function confirm(doc: unknown, binding: Binding, account: string, fetch: Fetch, inputs?: Inputs): Promise<{
26
45
  chosen: Chosen;
27
46
  request: SigningRequest | null;
28
47
  bytes: Uint8Array;
29
48
  h: AtrHash;
30
- agreement?: string;
31
49
  } | Declined>;
32
50
  /**
33
- * Rebuilds the payment from `chosen` and the bytes, joins the signer's answer, and returns the payment only when what
34
- * was signed carries the hash of these bytes. For a pairing whose payment is not a public proof and whose `bound` finds
35
- * no signed place for the hash, the proof is the agreement payment, and the completed payment is returned as it is.
36
- * Where the signer moved the payment itself, a decline keeps it as `moved`. Where the completion carried the landed
37
- * receipt `bound` reads and the payment sent leaves it out, `landed` is returned beside the payment as JSON, each integer
38
- * 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.
39
58
  */
40
59
  export declare function finish(bytes: Uint8Array, chosen: Chosen, signature: Signature, binding: Binding): Promise<{
41
60
  signed: Presented;
@@ -45,15 +64,19 @@ export declare function finish(bytes: Uint8Array, chosen: Chosen, signature: Sig
45
64
  next: SigningRequest;
46
65
  h: AtrHash;
47
66
  } | Declined>;
48
- /** Confirms that a payment held later carries, inside what was signed, the hash of the kept bytes. */
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`.
70
+ */
49
71
  export declare function check(bytes: Uint8Array, presented: unknown, binding: Binding): Promise<{
50
72
  h: AtrHash;
51
73
  } | Declined>;
52
74
  /**
53
- * Chooses, builds and signs one payment for a read the caller has already compared: the signer is called once, or,
54
- * for a pairing signed in steps, once per step in order, and the payment is returned only through `finish`.
75
+ * Builds and signs the payment `chosen` names, with the hash of `bytes`: the signer is called once, or, for a pairing
76
+ * signed in steps, once per step in order, and the payment is returned only through `finish`. `signed` is null where the
77
+ * pairing has nothing for the buyer to sign.
55
78
  */
56
- export declare function pay(binding: Binding, read: Read, doc: unknown, signer: Signer, inputs: Inputs, bytes: Uint8Array): Promise<{
79
+ export declare function pay(binding: Binding, chosen: Chosen, signer: Signer, bytes: Uint8Array): Promise<{
57
80
  signed: Presented | null;
58
81
  landed?: unknown;
59
82
  h: AtrHash;