@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.
- package/README.md +88 -52
- package/dist/agreement.d.ts +14 -4
- package/dist/agreement.js +139 -49
- package/dist/channels.d.ts +47 -14
- package/dist/channels.js +147 -74
- package/dist/gate.d.ts +37 -16
- package/dist/gate.js +69 -45
- package/dist/pairings/batch.d.ts +2 -5
- package/dist/pairings/batch.js +1 -11
- package/dist/pairings/card.js +0 -2
- package/dist/pairings/common.d.ts +17 -4
- package/dist/pairings/common.js +35 -4
- package/dist/pairings/lnbtc-request.d.ts +1 -1
- package/dist/pairings/lnbtc-request.js +14 -5
- package/dist/pairings/mpp-charge-hedera.d.ts +13 -11
- package/dist/pairings/mpp-charge-hedera.js +16 -14
- 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 +6 -1
- package/dist/pairings/mpp-charge-tempo-push.js +4 -13
- package/dist/pairings/mpp-charge-xrpl.js +3 -3
- package/dist/pairings/mpp-rails.d.ts +1 -1
- package/dist/pairings/mpp-session-hedera.js +3 -4
- package/dist/pairings/mpp-session-xrpl.js +3 -4
- package/dist/pairings/mpp.d.ts +14 -17
- package/dist/pairings/mpp.js +35 -114
- 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-solana.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-solana.js +2 -1
- package/dist/pairings/x402-exact-hedera.d.ts +4 -1
- package/dist/pairings/x402-exact-hedera.js +5 -2
- package/dist/pairings/x402-exact-near.js +23 -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-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 +3 -2
- package/dist/pairings/x402-rail.js +1 -1
- package/dist/transact.d.ts +3 -2
- package/dist/transact.js +9 -6
- package/dist/types.d.ts +6 -16
- 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,
|
|
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 { 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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
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
|
|
97
|
-
*
|
|
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 (
|
|
109
|
+
if (recentBlockhash !== undefined) {
|
|
110
|
+
if (typeof recentBlockhash !== "string" || !KEY.test(recentBlockhash))
|
|
111
|
+
return undefined;
|
|
103
112
|
out.recentBlockhash = recentBlockhash;
|
|
104
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
124
|
-
*
|
|
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 :
|
|
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
|
|
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(
|
|
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
|
|
168
|
-
*
|
|
169
|
-
*
|
|
170
|
-
*
|
|
171
|
-
*
|
|
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 ===
|
|
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
|
|
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
|
|
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(
|
|
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
|
-
...(
|
|
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,
|
|
284
|
-
*
|
|
285
|
-
* cumulative amount is the recorded charge plus the challenge's amount, and the
|
|
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
|
|
321
|
-
return declined("offer-unreadable",
|
|
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
|
|
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
|
|
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 =
|
|
385
|
-
if (
|
|
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
|
-
|
|
391
|
-
return named ?? "malformed";
|
|
469
|
+
return fromLcpString(lc) ?? refuse("mpp/legal-context-malformed");
|
|
392
470
|
}
|
|
393
|
-
/**
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
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
|
|
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";
|
|
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
|
-
/**
|
|
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.
|
|
29
|
-
*
|
|
30
|
-
*
|
|
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
|
|
40
|
-
*
|
|
41
|
-
* no signed place for the hash, the proof is the agreement payment, and the
|
|
42
|
-
* Where the signer moved the payment itself, a decline keeps it as `moved`.
|
|
43
|
-
* receipt `bound` reads and the payment sent leaves it out, `landed` is
|
|
44
|
-
* 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.
|
|
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
|
-
/**
|
|
55
|
-
|
|
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
|
/**
|