@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.
- package/README.md +135 -65
- package/dist/agreement.d.ts +21 -17
- package/dist/agreement.js +279 -85
- package/dist/channels.d.ts +35 -12
- package/dist/channels.js +152 -70
- package/dist/gate.d.ts +41 -18
- package/dist/gate.js +81 -47
- package/dist/index.d.ts +1 -1
- package/dist/pairings/batch.d.ts +2 -5
- package/dist/pairings/batch.js +3 -13
- package/dist/pairings/card.js +0 -2
- package/dist/pairings/common.d.ts +7 -1
- package/dist/pairings/common.js +17 -2
- package/dist/pairings/evm-x402.js +3 -3
- package/dist/pairings/lightning.js +1 -1
- package/dist/pairings/lnbtc-request.d.ts +1 -1
- package/dist/pairings/lnbtc-request.js +1 -1
- package/dist/pairings/mpp-charge-hedera.d.ts +7 -7
- package/dist/pairings/mpp-charge-hedera.js +1 -1
- package/dist/pairings/mpp-charge-stellar.js +1 -1
- package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
- package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
- package/dist/pairings/mpp-charge-tempo-push.d.ts +0 -1
- package/dist/pairings/mpp-charge-tempo-push.js +2 -10
- package/dist/pairings/mpp-charge-xrpl.js +3 -3
- package/dist/pairings/mpp-rails.d.ts +1 -1
- package/dist/pairings/mpp-session-solana.js +2 -2
- package/dist/pairings/mpp-session-xrpl.js +3 -4
- package/dist/pairings/mpp-session.js +1 -1
- package/dist/pairings/mpp.d.ts +12 -16
- package/dist/pairings/mpp.js +32 -109
- package/dist/pairings/protocol-groups.d.ts +1 -1
- package/dist/pairings/x402-account-rails.d.ts +1 -1
- package/dist/pairings/x402-batch-settlement-eip155.js +1 -1
- package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-solana.js +3 -2
- package/dist/pairings/x402-exact-casper.js +3 -3
- package/dist/pairings/x402-exact-ccd.js +3 -3
- package/dist/pairings/x402-exact-hedera.d.ts +4 -1
- package/dist/pairings/x402-exact-hedera.js +5 -2
- package/dist/pairings/x402-exact-solana.d.ts +4 -4
- package/dist/pairings/x402-exact-solana.js +3 -2
- package/dist/pairings/x402-exact-stellar.js +1 -1
- package/dist/pairings/x402-exact-sui.js +3 -1
- package/dist/pairings/x402-exact-tvm.js +10 -2
- package/dist/pairings/x402-exact-xrpl.js +2 -4
- package/dist/pairings/x402-rail.d.ts +1 -1
- package/dist/transact.d.ts +14 -9
- package/dist/transact.js +30 -24
- package/dist/types.d.ts +43 -18
- 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,
|
|
5
|
-
* the
|
|
6
|
-
* MPP's sessions
|
|
7
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
|
75
|
-
*
|
|
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 (
|
|
108
|
+
if (recentBlockhash !== undefined) {
|
|
109
|
+
if (typeof recentBlockhash !== "string" || !KEY.test(recentBlockhash))
|
|
110
|
+
return undefined;
|
|
81
111
|
out.recentBlockhash = recentBlockhash;
|
|
82
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
|
146
|
-
*
|
|
147
|
-
*
|
|
148
|
-
* the
|
|
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 ===
|
|
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
|
|
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
|
-
...(
|
|
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,
|
|
255
|
-
*
|
|
256
|
-
* cumulative amount is the recorded charge plus the challenge's amount, and the
|
|
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
|
|
292
|
-
return declined("offer-unreadable",
|
|
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
|
|
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 =
|
|
356
|
-
if (
|
|
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
|
-
|
|
362
|
-
return named ?? "malformed";
|
|
449
|
+
return fromLcpString(lc) ?? refuse("mpp/legal-context-malformed");
|
|
363
450
|
}
|
|
364
|
-
/**
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
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
|
|
5
|
-
* whose proof is the agreement payment, completes it without that reading. `check`
|
|
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
|
|
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.
|
|
23
|
-
*
|
|
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
|
|
34
|
-
*
|
|
35
|
-
* no signed place for the hash, the proof is the agreement payment, and the
|
|
36
|
-
* Where the signer moved the payment itself, a decline keeps it as `moved`.
|
|
37
|
-
* receipt `bound` reads and the payment sent leaves it out, `landed` is
|
|
38
|
-
* a decimal string, so `check` and `openChannel` can later read the
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
54
|
-
*
|
|
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,
|
|
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;
|