@integraledger/terms 0.1.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/LICENSE +202 -0
- package/README.md +539 -0
- package/dist/agreement.d.ts +23 -0
- package/dist/agreement.js +264 -0
- package/dist/channels.d.ts +49 -0
- package/dist/channels.js +395 -0
- package/dist/gate.d.ts +69 -0
- package/dist/gate.js +347 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +4 -0
- package/dist/pairings/ack-payment-request.d.ts +1 -0
- package/dist/pairings/ack-payment-request.js +12 -0
- package/dist/pairings/acp-checkout-delegated.d.ts +2 -0
- package/dist/pairings/acp-checkout-delegated.js +28 -0
- package/dist/pairings/acp-checkout-undelegated.d.ts +1 -0
- package/dist/pairings/acp-checkout-undelegated.js +11 -0
- package/dist/pairings/ap2-checkout-mandate.d.ts +2 -0
- package/dist/pairings/ap2-checkout-mandate.js +23 -0
- package/dist/pairings/batch.d.ts +29 -0
- package/dist/pairings/batch.js +83 -0
- package/dist/pairings/card-mastercard-vi-autonomous.d.ts +1 -0
- package/dist/pairings/card-mastercard-vi-autonomous.js +3 -0
- package/dist/pairings/card-mastercard-vi-immediate.d.ts +1 -0
- package/dist/pairings/card-mastercard-vi-immediate.js +3 -0
- package/dist/pairings/card-seller-reference.d.ts +1 -0
- package/dist/pairings/card-seller-reference.js +3 -0
- package/dist/pairings/card-visa-tap.d.ts +1 -0
- package/dist/pairings/card-visa-tap.js +3 -0
- package/dist/pairings/card.d.ts +7 -0
- package/dist/pairings/card.js +68 -0
- package/dist/pairings/common.d.ts +54 -0
- package/dist/pairings/common.js +134 -0
- package/dist/pairings/evm-x402.d.ts +3 -0
- package/dist/pairings/evm-x402.js +49 -0
- package/dist/pairings/index.d.ts +3 -0
- package/dist/pairings/index.js +134 -0
- package/dist/pairings/lightning.d.ts +17 -0
- package/dist/pairings/lightning.js +112 -0
- package/dist/pairings/lnbtc-request.d.ts +24 -0
- package/dist/pairings/lnbtc-request.js +175 -0
- package/dist/pairings/mpp-charge-card.d.ts +1 -0
- package/dist/pairings/mpp-charge-card.js +3 -0
- package/dist/pairings/mpp-charge-evm-authorization.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-authorization.js +3 -0
- package/dist/pairings/mpp-charge-evm-hash.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-hash.js +3 -0
- package/dist/pairings/mpp-charge-evm-permit2.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-permit2.js +3 -0
- package/dist/pairings/mpp-charge-evm-transaction.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-transaction.js +3 -0
- package/dist/pairings/mpp-charge-hedera.d.ts +23 -0
- package/dist/pairings/mpp-charge-hedera.js +137 -0
- package/dist/pairings/mpp-charge-nearintents.d.ts +2 -0
- package/dist/pairings/mpp-charge-nearintents.js +19 -0
- package/dist/pairings/mpp-charge-solana.d.ts +1 -0
- package/dist/pairings/mpp-charge-solana.js +25 -0
- package/dist/pairings/mpp-charge-stellar.d.ts +1 -0
- package/dist/pairings/mpp-charge-stellar.js +16 -0
- package/dist/pairings/mpp-charge-stripe.d.ts +1 -0
- package/dist/pairings/mpp-charge-stripe.js +3 -0
- package/dist/pairings/mpp-charge-tempo-memo.d.ts +9 -0
- package/dist/pairings/mpp-charge-tempo-memo.js +10 -0
- package/dist/pairings/mpp-charge-tempo-push.d.ts +12 -0
- package/dist/pairings/mpp-charge-tempo-push.js +21 -0
- package/dist/pairings/mpp-charge-usdc-evm.d.ts +1 -0
- package/dist/pairings/mpp-charge-usdc-evm.js +6 -0
- package/dist/pairings/mpp-charge-usdc-gateway.d.ts +2 -0
- package/dist/pairings/mpp-charge-usdc-gateway.js +33 -0
- package/dist/pairings/mpp-charge-usdc-solana.d.ts +1 -0
- package/dist/pairings/mpp-charge-usdc-solana.js +25 -0
- package/dist/pairings/mpp-charge-usdc-stacks.d.ts +1 -0
- package/dist/pairings/mpp-charge-usdc-stacks.js +17 -0
- package/dist/pairings/mpp-charge-xrpl.d.ts +1 -0
- package/dist/pairings/mpp-charge-xrpl.js +20 -0
- package/dist/pairings/mpp-confirm-only.d.ts +2 -0
- package/dist/pairings/mpp-confirm-only.js +21 -0
- package/dist/pairings/mpp-rails.d.ts +48 -0
- package/dist/pairings/mpp-rails.js +71 -0
- package/dist/pairings/mpp-session-evm.d.ts +1 -0
- package/dist/pairings/mpp-session-evm.js +3 -0
- package/dist/pairings/mpp-session-hedera.d.ts +2 -0
- package/dist/pairings/mpp-session-hedera.js +41 -0
- package/dist/pairings/mpp-session-solana.d.ts +1 -0
- package/dist/pairings/mpp-session-solana.js +60 -0
- package/dist/pairings/mpp-session-tempo.d.ts +1 -0
- package/dist/pairings/mpp-session-tempo.js +3 -0
- package/dist/pairings/mpp-session-xrpl.d.ts +1 -0
- package/dist/pairings/mpp-session-xrpl.js +42 -0
- package/dist/pairings/mpp-session.d.ts +5 -0
- package/dist/pairings/mpp-session.js +65 -0
- package/dist/pairings/mpp-subscription-stripe.d.ts +1 -0
- package/dist/pairings/mpp-subscription-stripe.js +6 -0
- package/dist/pairings/mpp-subscription-tempo.d.ts +2 -0
- package/dist/pairings/mpp-subscription-tempo.js +2 -0
- package/dist/pairings/mpp.d.ts +43 -0
- package/dist/pairings/mpp.js +194 -0
- package/dist/pairings/protocol-groups.d.ts +17 -0
- package/dist/pairings/protocol-groups.js +27 -0
- package/dist/pairings/ucp-booking-ap2-mandate.d.ts +1 -0
- package/dist/pairings/ucp-booking-ap2-mandate.js +3 -0
- package/dist/pairings/ucp-booking-unsigned.d.ts +1 -0
- package/dist/pairings/ucp-booking-unsigned.js +3 -0
- package/dist/pairings/ucp-checkout-ap2-mandate.d.ts +1 -0
- package/dist/pairings/ucp-checkout-ap2-mandate.js +3 -0
- package/dist/pairings/ucp-checkout-unsigned.d.ts +1 -0
- package/dist/pairings/ucp-checkout-unsigned.js +3 -0
- package/dist/pairings/ucp.d.ts +5 -0
- package/dist/pairings/ucp.js +35 -0
- package/dist/pairings/x402-account-rails.d.ts +25 -0
- package/dist/pairings/x402-account-rails.js +52 -0
- package/dist/pairings/x402-auth-capture-eip155-eip3009.d.ts +1 -0
- package/dist/pairings/x402-auth-capture-eip155-eip3009.js +3 -0
- package/dist/pairings/x402-auth-capture-eip155-permit2.d.ts +1 -0
- package/dist/pairings/x402-auth-capture-eip155-permit2.js +3 -0
- package/dist/pairings/x402-batch-settlement-cloudflare.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-cloudflare.js +21 -0
- package/dist/pairings/x402-batch-settlement-eip155.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-eip155.js +32 -0
- package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-solana.js +55 -0
- package/dist/pairings/x402-exact-algorand.d.ts +1 -0
- package/dist/pairings/x402-exact-algorand.js +37 -0
- package/dist/pairings/x402-exact-aptos.d.ts +1 -0
- package/dist/pairings/x402-exact-aptos.js +9 -0
- package/dist/pairings/x402-exact-cardano.d.ts +1 -0
- package/dist/pairings/x402-exact-cardano.js +7 -0
- package/dist/pairings/x402-exact-casper.d.ts +2 -0
- package/dist/pairings/x402-exact-casper.js +21 -0
- package/dist/pairings/x402-exact-ccd.d.ts +2 -0
- package/dist/pairings/x402-exact-ccd.js +20 -0
- package/dist/pairings/x402-exact-eip155-eip3009.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-eip3009.js +3 -0
- package/dist/pairings/x402-exact-eip155-erc7710-salt.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-erc7710-salt.js +3 -0
- package/dist/pairings/x402-exact-eip155-erc7710.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-erc7710.js +3 -0
- package/dist/pairings/x402-exact-eip155-permit2.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-permit2.js +3 -0
- package/dist/pairings/x402-exact-hedera-transfer-executor.d.ts +1 -0
- package/dist/pairings/x402-exact-hedera-transfer-executor.js +23 -0
- package/dist/pairings/x402-exact-hedera.d.ts +3 -0
- package/dist/pairings/x402-exact-hedera.js +46 -0
- package/dist/pairings/x402-exact-near.d.ts +2 -0
- package/dist/pairings/x402-exact-near.js +34 -0
- package/dist/pairings/x402-exact-polkadot-lcp-assets-remark.d.ts +2 -0
- package/dist/pairings/x402-exact-polkadot-lcp-assets-remark.js +20 -0
- package/dist/pairings/x402-exact-solana.d.ts +11 -0
- package/dist/pairings/x402-exact-solana.js +36 -0
- package/dist/pairings/x402-exact-starknet.d.ts +2 -0
- package/dist/pairings/x402-exact-starknet.js +20 -0
- package/dist/pairings/x402-exact-stellar.d.ts +1 -0
- package/dist/pairings/x402-exact-stellar.js +17 -0
- package/dist/pairings/x402-exact-sui.d.ts +1 -0
- package/dist/pairings/x402-exact-sui.js +10 -0
- package/dist/pairings/x402-exact-tron-lcp-trc20-memo.d.ts +2 -0
- package/dist/pairings/x402-exact-tron-lcp-trc20-memo.js +45 -0
- package/dist/pairings/x402-exact-tvm.d.ts +2 -0
- package/dist/pairings/x402-exact-tvm.js +35 -0
- package/dist/pairings/x402-exact-xrpl.d.ts +1 -0
- package/dist/pairings/x402-exact-xrpl.js +27 -0
- package/dist/pairings/x402-rail.d.ts +31 -0
- package/dist/pairings/x402-rail.js +65 -0
- package/dist/pairings/x402-upto-eip155-permit2.d.ts +1 -0
- package/dist/pairings/x402-upto-eip155-permit2.js +3 -0
- package/dist/pairings/x402-upto-solana.d.ts +1 -0
- package/dist/pairings/x402-upto-solana.js +42 -0
- package/dist/transact.d.ts +20 -0
- package/dist/transact.js +53 -0
- package/dist/types.d.ts +169 -0
- package/dist/types.js +2 -0
- package/package.json +64 -0
package/dist/channels.js
ADDED
|
@@ -0,0 +1,395 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The buyer's channel steps. One ATR covers a whole channel: the gate compares it once, at the opening, and the caller
|
|
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.
|
|
8
|
+
*/
|
|
9
|
+
import { fromLcpString, hash, hashEquals, parseJson } from "@integraledger/lcp";
|
|
10
|
+
import { network as mppNetwork, sessionResume } from "@integraledger/lcp/mpp";
|
|
11
|
+
import { offers, requestOf } from "./pairings/mpp.js";
|
|
12
|
+
import { withPaymentIdentifier } from "./pairings/common.js";
|
|
13
|
+
import { MAX_ATR_BYTES, } from "./types.js";
|
|
14
|
+
const DECIMAL = /^[0-9]{1,78}$/;
|
|
15
|
+
/** At most this many challenges of a within document are looked at, as the MPP entry point reads a document. */
|
|
16
|
+
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
|
+
const NOT_BOUND_WITHIN = /\/not-bound-within$/;
|
|
20
|
+
const REF_BYTES = 24;
|
|
21
|
+
const HOLD_KEYS = ["pairing", "network", "channel", "h", "atr", "charged", "signedMax"];
|
|
22
|
+
function declined(code, detail) {
|
|
23
|
+
return { decline: { code, detail } };
|
|
24
|
+
}
|
|
25
|
+
function isRefusal(v) {
|
|
26
|
+
return typeof v === "object" && v !== null && v.refused === true;
|
|
27
|
+
}
|
|
28
|
+
function isObject(v) {
|
|
29
|
+
return typeof v === "object" && v !== null && !Array.isArray(v);
|
|
30
|
+
}
|
|
31
|
+
const stepsOf = (binding) => binding;
|
|
32
|
+
/** Calls a binding member, reading a throw as a refusal. */
|
|
33
|
+
async function guarded(run) {
|
|
34
|
+
try {
|
|
35
|
+
return await run();
|
|
36
|
+
}
|
|
37
|
+
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;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
/** A value as plain JSON, or undefined when it holds anything JSON does not carry. */
|
|
57
|
+
function asJson(v) {
|
|
58
|
+
try {
|
|
59
|
+
const text = JSON.stringify(v);
|
|
60
|
+
return text === undefined ? undefined : JSON.parse(text);
|
|
61
|
+
}
|
|
62
|
+
catch {
|
|
63
|
+
return undefined;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
function isHold(v) {
|
|
67
|
+
return (isObject(v) &&
|
|
68
|
+
HOLD_KEYS.every((k) => typeof v[k] === "string") &&
|
|
69
|
+
DECIMAL.test(v["charged"]) &&
|
|
70
|
+
DECIMAL.test(v["signedMax"]) &&
|
|
71
|
+
isObject(v["opening"]));
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
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.
|
|
76
|
+
*/
|
|
77
|
+
function refundInputs(inputs) {
|
|
78
|
+
const out = {};
|
|
79
|
+
const { recentBlockhash, computeUnitLimit, computeUnitPrice } = inputs;
|
|
80
|
+
if (typeof recentBlockhash === "string")
|
|
81
|
+
out.recentBlockhash = recentBlockhash;
|
|
82
|
+
if (typeof computeUnitLimit === "number" && Number.isSafeInteger(computeUnitLimit))
|
|
83
|
+
out.computeUnitLimit = computeUnitLimit;
|
|
84
|
+
if (typeof computeUnitPrice === "string" && DECIMAL.test(computeUnitPrice))
|
|
85
|
+
out.computeUnitPrice = BigInt(computeUnitPrice);
|
|
86
|
+
return out;
|
|
87
|
+
}
|
|
88
|
+
/** 24 random bytes as unpadded base64url: 32 characters from `[A-Za-z0-9_-]`. */
|
|
89
|
+
function newRef() {
|
|
90
|
+
return toBase64(crypto.getRandomValues(new Uint8Array(REF_BYTES))).replace(/\+/g, "-").replace(/\//g, "_");
|
|
91
|
+
}
|
|
92
|
+
/** The opening voucher's `maxClaimableAmount`, where the payment carries one, else "0". */
|
|
93
|
+
function openingMax(signed) {
|
|
94
|
+
const payload = isObject(signed) ? signed["payload"] : undefined;
|
|
95
|
+
const voucher = isObject(payload) ? payload["voucher"] : undefined;
|
|
96
|
+
const max = isObject(voucher) ? voucher["maxClaimableAmount"] : undefined;
|
|
97
|
+
return typeof max === "string" && DECIMAL.test(max) ? max : "0";
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
|
|
101
|
+
* `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.
|
|
103
|
+
*/
|
|
104
|
+
export async function openChannel(bytes, opened, binding, landed) {
|
|
105
|
+
const b = stepsOf(binding);
|
|
106
|
+
if (!isObject(b) || typeof b.id !== "string" || !isObject(b.channel)) {
|
|
107
|
+
return declined("pairing-not-supported", "The pairing has no channel.");
|
|
108
|
+
}
|
|
109
|
+
if (landed !== undefined && (!isObject(landed) || !isObject(opened))) {
|
|
110
|
+
return declined("signed-not-bound", "The landed receipt is not a JSON object beside the opening.");
|
|
111
|
+
}
|
|
112
|
+
const signed = (landed === undefined ? opened : { ...opened, landed });
|
|
113
|
+
if (!(bytes instanceof Uint8Array))
|
|
114
|
+
return declined("signed-not-bound", "The ATR bytes are missing.");
|
|
115
|
+
if (bytes.length > MAX_ATR_BYTES)
|
|
116
|
+
return declined("atr-too-large", `The ATR is larger than ${MAX_ATR_BYTES} bytes.`);
|
|
117
|
+
const channel = b.channel;
|
|
118
|
+
const kind = await guarded(() => channel.kind(signed));
|
|
119
|
+
if (kind !== "open")
|
|
120
|
+
return declined("signed-not-bound", "The payment does not open a channel.");
|
|
121
|
+
const h = await hash(bytes);
|
|
122
|
+
const inside = await guarded(() => b.bound(signed));
|
|
123
|
+
if (isRefusal(inside) || !hashEquals(inside, h)) {
|
|
124
|
+
return declined("signed-not-bound", "The opening does not carry the hash of these bytes.");
|
|
125
|
+
}
|
|
126
|
+
const ref = await guarded(() => channel.ref(signed));
|
|
127
|
+
if (isRefusal(ref))
|
|
128
|
+
return declined("signed-not-bound", ref.code);
|
|
129
|
+
const opening = asJson(signed);
|
|
130
|
+
if (!isObject(opening))
|
|
131
|
+
return declined("signed-not-bound", "The opening is not plain JSON.");
|
|
132
|
+
return {
|
|
133
|
+
pairing: b.id,
|
|
134
|
+
network: ref.network,
|
|
135
|
+
channel: ref.channel,
|
|
136
|
+
h,
|
|
137
|
+
atr: toBase64(bytes),
|
|
138
|
+
opening,
|
|
139
|
+
charged: "0",
|
|
140
|
+
signedMax: openingMax(signed),
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* 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.
|
|
149
|
+
*/
|
|
150
|
+
export async function within(doc, hold, binding, signer, refund, inputs = {}) {
|
|
151
|
+
const b = stepsOf(binding);
|
|
152
|
+
if (!isObject(b) || typeof b.id !== "string" || !isObject(b.channel)) {
|
|
153
|
+
return declined("pairing-not-supported", "The pairing has no channel.");
|
|
154
|
+
}
|
|
155
|
+
if (typeof b.buildWithin !== "function") {
|
|
156
|
+
return declined("pairing-not-supported", `The pairing ${b.id} has no in-channel payment.`);
|
|
157
|
+
}
|
|
158
|
+
if (!isHold(hold))
|
|
159
|
+
return declined("signed-not-bound", "The channel hold is malformed.");
|
|
160
|
+
if (hold.pairing !== b.id)
|
|
161
|
+
return declined("pairing-not-supported", `The hold is not for the pairing ${b.id}.`);
|
|
162
|
+
const ns = b.id.split("/")[0];
|
|
163
|
+
let refundAmount;
|
|
164
|
+
if (refund !== undefined) {
|
|
165
|
+
if (!isObject(refund) || (refund.amount !== undefined && !DECIMAL.test(refund.amount))) {
|
|
166
|
+
return declined("no-payable-option", `${ns}/input-missing`);
|
|
167
|
+
}
|
|
168
|
+
refundAmount = refund.amount === undefined ? undefined : BigInt(refund.amount);
|
|
169
|
+
}
|
|
170
|
+
const channel = b.channel;
|
|
171
|
+
const bytes = fromBase64(hold.atr);
|
|
172
|
+
if (bytes === undefined || bytes.length > MAX_ATR_BYTES)
|
|
173
|
+
return declined("signed-not-bound", "The held ATR is unreadable.");
|
|
174
|
+
const h = await hash(bytes);
|
|
175
|
+
if (!hashEquals(hold.h, h))
|
|
176
|
+
return declined("hash-mismatch", "The held ATR does not hash to the held hash.");
|
|
177
|
+
const opened = await guarded(() => b.bound(hold.opening));
|
|
178
|
+
if (isRefusal(opened) || !hashEquals(opened, h)) {
|
|
179
|
+
return declined("signed-not-bound", "The held opening does not carry the held ATR's hash.");
|
|
180
|
+
}
|
|
181
|
+
const openedRef = await guarded(() => channel.ref(hold.opening));
|
|
182
|
+
if (isRefusal(openedRef) || openedRef.network !== hold.network || openedRef.channel !== hold.channel) {
|
|
183
|
+
return declined("signed-not-bound", "The held opening does not name the held channel.");
|
|
184
|
+
}
|
|
185
|
+
if (ns === "mpp")
|
|
186
|
+
return sessionWithin(b, doc, hold, h, signer, refund);
|
|
187
|
+
const read = await guarded(() => b.read(doc));
|
|
188
|
+
if (isRefusal(read))
|
|
189
|
+
return declined("offer-unreadable", read.code);
|
|
190
|
+
if (!hashEquals(read.h, h)) {
|
|
191
|
+
return declined("hash-mismatch", "The challenge advertises another ATR's hash than the one this channel opened for.");
|
|
192
|
+
}
|
|
193
|
+
const offer = read.offer;
|
|
194
|
+
const options = isObject(offer) && Array.isArray(offer["options"]) ? offer["options"] : [];
|
|
195
|
+
const accepted = options.find((o) => isObject(o) && o["network"] === hold.network);
|
|
196
|
+
if (accepted === undefined)
|
|
197
|
+
return declined("no-payable-option", `${ns}/no-payable-option`);
|
|
198
|
+
if (typeof accepted["amount"] !== "string" || !DECIMAL.test(accepted["amount"])) {
|
|
199
|
+
return declined("offer-unreadable", `${ns}/option-malformed`);
|
|
200
|
+
}
|
|
201
|
+
const maxClaimableAmount = refund !== undefined ? BigInt(hold.charged) : BigInt(hold.charged) + BigInt(accepted["amount"]);
|
|
202
|
+
const payload = hold.opening["payload"];
|
|
203
|
+
const channelConfig = isObject(payload) ? payload["channelConfig"] : undefined;
|
|
204
|
+
const required = isObject(offer) ? offer["required"] : undefined;
|
|
205
|
+
const unsigned = await guarded(() => b.buildWithin({
|
|
206
|
+
required,
|
|
207
|
+
accepted,
|
|
208
|
+
channelConfig,
|
|
209
|
+
maxClaimableAmount,
|
|
210
|
+
...(refund !== undefined ? { refund: refundAmount === undefined ? {} : { amount: refundAmount } } : {}),
|
|
211
|
+
...(refund !== undefined ? refundInputs(isObject(inputs) ? inputs : {}) : {}),
|
|
212
|
+
}, h));
|
|
213
|
+
if (isRefusal(unsigned))
|
|
214
|
+
return declined("offer-unreadable", unsigned.code);
|
|
215
|
+
const batch = unsigned;
|
|
216
|
+
const request = {
|
|
217
|
+
kind: "batch",
|
|
218
|
+
requests: batch.requests,
|
|
219
|
+
};
|
|
220
|
+
let answer;
|
|
221
|
+
try {
|
|
222
|
+
answer = await signer.sign(request);
|
|
223
|
+
}
|
|
224
|
+
catch {
|
|
225
|
+
return declined("signer-failed", "The signer did not sign.");
|
|
226
|
+
}
|
|
227
|
+
if (!Array.isArray(answer) || answer.length !== batch.requests.length || !answer.every((s) => typeof s === "string")) {
|
|
228
|
+
return declined("signed-not-bound", "The signer's answer did not complete the payment.");
|
|
229
|
+
}
|
|
230
|
+
const completed = await guarded(() => batch.complete(answer));
|
|
231
|
+
if (isRefusal(completed))
|
|
232
|
+
return declined("signed-not-bound", completed.code);
|
|
233
|
+
const signed = withPaymentIdentifier(completed, required, newRef());
|
|
234
|
+
if (isRefusal(signed))
|
|
235
|
+
return declined("signed-not-bound", signed.code);
|
|
236
|
+
const expected = refund !== undefined && refundAmount === undefined ? "close" : "within";
|
|
237
|
+
const kind = await guarded(() => channel.kind(signed));
|
|
238
|
+
if (kind !== expected)
|
|
239
|
+
return declined("signed-not-bound", `The signed payment is not a ${expected} payment.`);
|
|
240
|
+
const inside = await guarded(() => channel.boundWithin(signed));
|
|
241
|
+
if (isRefusal(inside) ? !NOT_BOUND_WITHIN.test(inside.code) : !hashEquals(inside, h)) {
|
|
242
|
+
return declined("signed-not-bound", "The signed voucher does not commit to the held ATR's hash.");
|
|
243
|
+
}
|
|
244
|
+
const ref = await guarded(() => channel.ref(signed));
|
|
245
|
+
if (isRefusal(ref) || ref.network !== hold.network || ref.channel !== hold.channel) {
|
|
246
|
+
return declined("signed-not-bound", "The signed voucher does not name the held channel.");
|
|
247
|
+
}
|
|
248
|
+
const signedMax = BigInt(hold.signedMax) > maxClaimableAmount ? hold.signedMax : maxClaimableAmount.toString();
|
|
249
|
+
return { signed, hold: { ...hold, signedMax } };
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* One voucher, or the close, in a held MPP session. The within challenge is the first of the document that either
|
|
253
|
+
* 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`.
|
|
258
|
+
*/
|
|
259
|
+
async function sessionWithin(b, doc, hold, h, signer, refund) {
|
|
260
|
+
if (refund !== undefined && refund.amount !== undefined) {
|
|
261
|
+
return declined("pairing-not-supported", "mpp/within-action-not-built");
|
|
262
|
+
}
|
|
263
|
+
const channel = b.channel;
|
|
264
|
+
const challenges = Array.isArray(doc) ? doc.slice(0, MAX_CHALLENGES) : [];
|
|
265
|
+
let challenge;
|
|
266
|
+
for (const each of challenges) {
|
|
267
|
+
if (!isObject(each))
|
|
268
|
+
continue;
|
|
269
|
+
const c = each;
|
|
270
|
+
const named = namedChannel(c, b.id);
|
|
271
|
+
if (named === undefined) {
|
|
272
|
+
if (offers(c, b.id) && mppNetwork(c) === hold.network) {
|
|
273
|
+
challenge = c;
|
|
274
|
+
break;
|
|
275
|
+
}
|
|
276
|
+
continue;
|
|
277
|
+
}
|
|
278
|
+
if (named === null)
|
|
279
|
+
continue;
|
|
280
|
+
if (named.network !== hold.network)
|
|
281
|
+
continue;
|
|
282
|
+
if (named.channel !== hold.channel) {
|
|
283
|
+
return declined("no-payable-option", "The challenge names a channel this hold did not open.");
|
|
284
|
+
}
|
|
285
|
+
challenge = c;
|
|
286
|
+
break;
|
|
287
|
+
}
|
|
288
|
+
if (challenge === undefined)
|
|
289
|
+
return declined("no-payable-option", "mpp/no-payable-option");
|
|
290
|
+
const named = legalContextOf(challenge);
|
|
291
|
+
if (named === "malformed")
|
|
292
|
+
return declined("offer-unreadable", "mpp/legal-context-malformed");
|
|
293
|
+
if (named !== undefined && !hashEquals(named, h)) {
|
|
294
|
+
return declined("hash-mismatch", "The challenge names another ATR's hash than the one this channel opened for.");
|
|
295
|
+
}
|
|
296
|
+
const amount = requestOf(challenge)?.["amount"];
|
|
297
|
+
if (typeof amount !== "string" || !DECIMAL.test(amount))
|
|
298
|
+
return declined("offer-unreadable", "mpp/request-malformed");
|
|
299
|
+
const action = refund !== undefined ? "close" : "voucher";
|
|
300
|
+
const cumulativeAmount = action === "close" ? BigInt(hold.charged) : BigInt(hold.charged) + BigInt(amount);
|
|
301
|
+
const unsigned = await guarded(() => b.buildWithin({ challenge, opening: hold.opening, cumulativeAmount, action }, h));
|
|
302
|
+
if (isRefusal(unsigned)) {
|
|
303
|
+
const code = unsigned.code.endsWith("/within-action-not-built") ? "pairing-not-supported" : "offer-unreadable";
|
|
304
|
+
return declined(code, unsigned.code);
|
|
305
|
+
}
|
|
306
|
+
const batch = unsigned;
|
|
307
|
+
let answer;
|
|
308
|
+
try {
|
|
309
|
+
answer = await signer.sign({ kind: "batch", requests: batch.requests });
|
|
310
|
+
}
|
|
311
|
+
catch {
|
|
312
|
+
return declined("signer-failed", "The signer did not sign.");
|
|
313
|
+
}
|
|
314
|
+
if (!Array.isArray(answer) || answer.length !== batch.requests.length || !answer.every((s) => typeof s === "string")) {
|
|
315
|
+
return declined("signed-not-bound", "The signer's answer did not complete the payment.");
|
|
316
|
+
}
|
|
317
|
+
const signed = await guarded(() => batch.complete(answer));
|
|
318
|
+
if (isRefusal(signed))
|
|
319
|
+
return declined("signed-not-bound", signed.code);
|
|
320
|
+
const expected = action === "close" ? "close" : "within";
|
|
321
|
+
const kind = await guarded(() => channel.kind(signed));
|
|
322
|
+
if (kind !== expected)
|
|
323
|
+
return declined("signed-not-bound", `The signed payment is not a ${expected} payment.`);
|
|
324
|
+
const inside = await guarded(() => channel.boundWithin(signed));
|
|
325
|
+
if (isRefusal(inside) ? !NOT_BOUND_WITHIN.test(inside.code) : !hashEquals(inside, h)) {
|
|
326
|
+
return declined("signed-not-bound", "The signed voucher does not commit to the held ATR's hash.");
|
|
327
|
+
}
|
|
328
|
+
const ref = await guarded(() => channel.ref(signed));
|
|
329
|
+
if (isRefusal(ref) || ref.network !== hold.network || ref.channel !== hold.channel) {
|
|
330
|
+
return declined("signed-not-bound", "The signed voucher does not name the held channel.");
|
|
331
|
+
}
|
|
332
|
+
const signedMax = BigInt(hold.signedMax) > cumulativeAmount ? hold.signedMax : cumulativeAmount.toString();
|
|
333
|
+
return { signed: signed, hold: { ...hold, signedMax } };
|
|
334
|
+
}
|
|
335
|
+
/**
|
|
336
|
+
* The channel a challenge of the pairing names for the client to resume: undefined when it names none, null when the
|
|
337
|
+
* challenge is not of the pairing, and otherwise `sessionResume`'s network and channel, spelled as the pairing's
|
|
338
|
+
* `channel.ref` spells a held channel. A named channel that `sessionResume` cannot read names a channel no hold opened.
|
|
339
|
+
*/
|
|
340
|
+
function namedChannel(c, pairing) {
|
|
341
|
+
const r = sessionResume(c);
|
|
342
|
+
if (r === null)
|
|
343
|
+
return undefined;
|
|
344
|
+
if (`mpp/${String(c.intent)}/${String(c.method)}` !== pairing)
|
|
345
|
+
return null;
|
|
346
|
+
return isRefusal(r) ? { network: "", channel: "" } : r;
|
|
347
|
+
}
|
|
348
|
+
/**
|
|
349
|
+
* 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.
|
|
351
|
+
*/
|
|
352
|
+
function legalContextOf(c) {
|
|
353
|
+
if (c.opaque === undefined)
|
|
354
|
+
return undefined;
|
|
355
|
+
const map = typeof c.opaque === "string" ? base64UrlJson(c.opaque) : undefined;
|
|
356
|
+
if (!isObject(map))
|
|
357
|
+
return "malformed";
|
|
358
|
+
const lc = map["legalContext"];
|
|
359
|
+
if (lc === undefined)
|
|
360
|
+
return undefined;
|
|
361
|
+
const named = typeof lc === "string" ? fromLcpString(lc) : null;
|
|
362
|
+
return named ?? "malformed";
|
|
363
|
+
}
|
|
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
|
+
}
|
|
376
|
+
}
|
|
377
|
+
/**
|
|
378
|
+
* Records the server's cumulative charge for the channel. It must be a decimal no lower than the charge last recorded
|
|
379
|
+
* and no higher than the largest amount signed in the channel.
|
|
380
|
+
*/
|
|
381
|
+
export function recordCharge(hold, chargedCumulativeAmount) {
|
|
382
|
+
if (!isHold(hold))
|
|
383
|
+
return declined("signed-not-bound", "The channel hold is malformed.");
|
|
384
|
+
if (typeof chargedCumulativeAmount !== "string" || !DECIMAL.test(chargedCumulativeAmount)) {
|
|
385
|
+
return declined("offer-unreadable", "The charged amount is not a decimal.");
|
|
386
|
+
}
|
|
387
|
+
const charged = BigInt(chargedCumulativeAmount);
|
|
388
|
+
if (charged < BigInt(hold.charged)) {
|
|
389
|
+
return declined("offer-unreadable", "The charged amount is below the charge already recorded.");
|
|
390
|
+
}
|
|
391
|
+
if (charged > BigInt(hold.signedMax)) {
|
|
392
|
+
return declined("offer-unreadable", "The charged amount is above the largest amount signed in the channel.");
|
|
393
|
+
}
|
|
394
|
+
return { ...hold, charged: charged.toString() };
|
|
395
|
+
}
|
package/dist/gate.d.ts
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The buyer gate. `confirm` reads the offer, fetches the ATR from the seller's link, compares its SHA-256 with the
|
|
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.
|
|
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";
|
|
10
|
+
export declare function declined(code: DeclineCode, detail: string): Declined;
|
|
11
|
+
export declare function isObject(v: unknown): v is Record<string, unknown>;
|
|
12
|
+
/** The pairing's namespace: its id up to the first `/`. */
|
|
13
|
+
export declare function namespaceOf(binding: Binding): string;
|
|
14
|
+
export declare function pieceOf(binding: Binding): BuyerPiece | undefined;
|
|
15
|
+
export declare function unsupported(binding: Binding): Declined;
|
|
16
|
+
/** 24 random bytes as unpadded base64url: 32 characters from `[A-Za-z0-9_-]`. */
|
|
17
|
+
export declare function newRef(): string;
|
|
18
|
+
/** Whether an answer to a `redirect: "manual"` request is a redirect: a 3xx status, or the opaque form a browser gives. */
|
|
19
|
+
export declare function redirected(response: Response): boolean;
|
|
20
|
+
/**
|
|
21
|
+
* 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.
|
|
24
|
+
*/
|
|
25
|
+
export declare function confirm(doc: unknown, binding: Binding, account: string, fetch: Fetch, inputs?: Inputs): Promise<{
|
|
26
|
+
chosen: Chosen;
|
|
27
|
+
request: SigningRequest | null;
|
|
28
|
+
bytes: Uint8Array;
|
|
29
|
+
h: AtrHash;
|
|
30
|
+
agreement?: string;
|
|
31
|
+
} | Declined>;
|
|
32
|
+
/**
|
|
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.
|
|
39
|
+
*/
|
|
40
|
+
export declare function finish(bytes: Uint8Array, chosen: Chosen, signature: Signature, binding: Binding): Promise<{
|
|
41
|
+
signed: Presented;
|
|
42
|
+
landed?: unknown;
|
|
43
|
+
h: AtrHash;
|
|
44
|
+
} | {
|
|
45
|
+
next: SigningRequest;
|
|
46
|
+
h: AtrHash;
|
|
47
|
+
} | Declined>;
|
|
48
|
+
/** Confirms that a payment held later carries, inside what was signed, the hash of the kept bytes. */
|
|
49
|
+
export declare function check(bytes: Uint8Array, presented: unknown, binding: Binding): Promise<{
|
|
50
|
+
h: AtrHash;
|
|
51
|
+
} | Declined>;
|
|
52
|
+
/**
|
|
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`.
|
|
55
|
+
*/
|
|
56
|
+
export declare function pay(binding: Binding, read: Read, doc: unknown, signer: Signer, inputs: Inputs, bytes: Uint8Array): Promise<{
|
|
57
|
+
signed: Presented | null;
|
|
58
|
+
landed?: unknown;
|
|
59
|
+
h: AtrHash;
|
|
60
|
+
} | Declined>;
|
|
61
|
+
/**
|
|
62
|
+
* The signer, once per step in order, then `finish` over its answers. A request of null is a build that is itself the
|
|
63
|
+
* payment: `finish` completes it with no signer call.
|
|
64
|
+
*/
|
|
65
|
+
export declare function signSteps(binding: Binding, chosen: Chosen, first: SigningRequest | null, signer: Signer, bytes: Uint8Array, h: AtrHash): Promise<{
|
|
66
|
+
signed: Presented | null;
|
|
67
|
+
landed?: unknown;
|
|
68
|
+
h: AtrHash;
|
|
69
|
+
} | Declined>;
|