s402 0.4.0 → 0.6.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { S402_HEADERS, S402_VERSION } from "./types.mjs";
 import { createS402Error, s402Error, s402ErrorCode } from "./errors.mjs";
-import { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
+import { MAX_BODY_BYTES, S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
 import { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader } from "./receipts.mjs";
 
 //#region src/client.ts
@@ -108,9 +108,9 @@ var s402ResourceServer = class {
 	* const requirements = server.buildRequirements({
 	*   schemes: ['exact'],
 	*   price: '1000000',
-	*   network: 'sui:mainnet',
-	*   payTo: '0xYOUR_ADDRESS',
-	*   asset: '0x2::sui::SUI',
+	*   network: 'your-chain:mainnet',
+	*   payTo: 'YOUR_ADDRESS',
+	*   asset: 'NATIVE_TOKEN',
 	* });
 	* res.status(402).setHeader('payment-required', encodePaymentRequired(requirements));
 	* ```
@@ -140,10 +140,11 @@ var s402ResourceServer = class {
 			protocolFeeBps: config.protocolFeeBps,
 			receiptRequired: config.receiptRequired,
 			settlementMode: config.settlementMode,
+			upto: config.upto,
+			prepaid: config.prepaid,
 			stream: config.stream,
 			escrow: config.escrow,
-			unlock: config.unlock,
-			prepaid: config.prepaid
+			unlock: config.unlock
 		};
 	}
 	/**
@@ -186,11 +187,136 @@ var s402ResourceServer = class {
 	}
 };
 
+//#endregion
+//#region src/extensions.ts
+/**
+* Type-safe extension data retrieval.
+*
+* The wire format is `Record<string, unknown>` for interop, but this helper
+* provides typed access for TypeScript consumers.
+*
+* @example
+* ```ts
+* interface DiscoveryData { services: string[] }
+* const data = getExtensionData<DiscoveryData>(requirements.extensions, 'org.s402.discovery');
+* if (data) console.log(data.services);
+* ```
+*/
+function getExtensionData(extensions, key) {
+	return extensions?.[key];
+}
+/**
+* Set extension data on an extensions record (creates if needed).
+* Returns a new extensions object (does not mutate the input).
+*/
+function setExtensionData(extensions, key, data) {
+	return {
+		...extensions,
+		[key]: data
+	};
+}
+/**
+* Registry for extensions with dependency-ordered execution.
+*
+* Extensions are stored by key and sorted topologically based on `dependsOn`.
+* Within the same dependency level, registration order is preserved.
+*
+* @example
+* ```ts
+* const registry = new s402ExtensionRegistry<s402FacilitatorExtension>();
+* registry.register(rateLimitExtension);
+* registry.register(analyticsExtension);
+* const sorted = registry.sorted(); // dependency-ordered list
+* ```
+*/
+var s402ExtensionRegistry = class {
+	extensions = /* @__PURE__ */ new Map();
+	sortedCache = null;
+	/**
+	* Register an extension. Throws on duplicate key or dependency cycle.
+	*/
+	register(ext) {
+		if (this.extensions.has(ext.key)) throw new s402Error("EXTENSION_FAILED", `Extension "${ext.key}" is already registered`);
+		this.extensions.set(ext.key, ext);
+		this.sortedCache = null;
+	}
+	/** Get a registered extension by key. */
+	get(key) {
+		return this.extensions.get(key);
+	}
+	/** Number of registered extensions. */
+	get size() {
+		return this.extensions.size;
+	}
+	/**
+	* Return extensions in topological (dependency) order.
+	* Cached until a new extension is registered.
+	*/
+	sorted() {
+		if (this.sortedCache) return this.sortedCache;
+		this.sortedCache = topologicalSort(this.extensions);
+		return this.sortedCache;
+	}
+};
+/**
+* Topological sort of extensions based on `dependsOn` declarations.
+* Uses Kahn's algorithm. Throws on cycles.
+*/
+function topologicalSort(extensions) {
+	if (extensions.size === 0) return [];
+	const inDegree = /* @__PURE__ */ new Map();
+	const dependents = /* @__PURE__ */ new Map();
+	for (const [key] of extensions) {
+		inDegree.set(key, 0);
+		dependents.set(key, []);
+	}
+	for (const [key, ext] of extensions) if (ext.dependsOn) for (const dep of ext.dependsOn) {
+		if (!extensions.has(dep)) throw new s402Error("EXTENSION_FAILED", `Extension "${key}" depends on "${dep}" which is not registered`);
+		dependents.get(dep).push(key);
+		inDegree.set(key, (inDegree.get(key) ?? 0) + 1);
+	}
+	const queue = [];
+	for (const [key, degree] of inDegree) if (degree === 0) queue.push(key);
+	const sorted = [];
+	while (queue.length > 0) {
+		const key = queue.shift();
+		sorted.push(extensions.get(key));
+		for (const dependent of dependents.get(key)) {
+			const newDegree = inDegree.get(dependent) - 1;
+			inDegree.set(dependent, newDegree);
+			if (newDegree === 0) queue.push(dependent);
+		}
+	}
+	if (sorted.length !== extensions.size) throw new s402Error("EXTENSION_FAILED", `Extension dependency cycle detected involving: ${[...extensions.keys()].filter((k) => !sorted.some((e) => e.key === k)).join(", ")}`);
+	return sorted;
+}
+/**
+* Run an async hook on all extensions in order.
+* Critical extensions throw on failure; advisory extensions call the error handler.
+*/
+async function runExtensionHooks(extensions, hookName, runner, onError) {
+	for (const ext of extensions) try {
+		await runner(ext);
+	} catch (e) {
+		if (ext.critical) throw new s402Error("EXTENSION_FAILED", `Critical extension "${ext.key}" failed in ${hookName}: ${e instanceof Error ? e.message : String(e)}`);
+		onError?.(ext, e);
+	}
+}
+
 //#endregion
 //#region src/facilitator.ts
 var s402Facilitator = class {
 	schemes = /* @__PURE__ */ new Map();
-	inFlight = /* @__PURE__ */ new Set();
+	inFlight = /* @__PURE__ */ new Map();
+	completed = /* @__PURE__ */ new Map();
+	dedupTtlMs;
+	dedupMaxEntries;
+	extensionRegistry = new s402ExtensionRegistry();
+	extensionErrorHandler;
+	constructor(options = {}) {
+		this.dedupTtlMs = options.dedupTtlMs ?? 3e5;
+		this.dedupMaxEntries = options.dedupMaxEntries ?? 1e4;
+	}
 	/**
 	* Register a scheme-specific facilitator for a network.
 	*/
@@ -200,6 +326,25 @@ var s402Facilitator = class {
 		return this;
 	}
 	/**
+	* Register a facilitator extension. Extensions fire in dependency order
+	* at four points in the process() pipeline: beforeVerify, afterVerify,
+	* beforeSettle, afterSettle.
+	*
+	* @throws {s402Error} `EXTENSION_FAILED` on duplicate key or dependency cycle
+	*/
+	registerExtension(ext) {
+		this.extensionRegistry.register(ext);
+		return this;
+	}
+	/**
+	* Set the handler for advisory (non-critical) extension failures.
+	* Critical extensions always throw; advisory extensions call this handler.
+	*/
+	onExtensionError(handler) {
+		this.extensionErrorHandler = handler;
+		return this;
+	}
+	/**
 	* Verify a payment payload by dispatching to the correct scheme.
 	* Includes expiration guard and scheme-mismatch check.
 	*/
@@ -284,6 +429,7 @@ var s402Facilitator = class {
 	*
 	* @param payload - Client's payment payload
 	* @param requirements - Server's payment requirements
+	* @param options - Optional process configuration (e.g., `{ skipVerify: true }` for zero-cost-failure chains)
 	* @returns Settlement result (check `result.success` and `result.errorCode`)
 	*
 	* @example
@@ -301,7 +447,7 @@ var s402Facilitator = class {
 	* }
 	* ```
 	*/
-	async process(payload, requirements) {
+	async process(payload, requirements, options) {
 		if (requirements.expiresAt != null) {
 			if (typeof requirements.expiresAt !== "number" || !Number.isFinite(requirements.expiresAt)) return {
 				success: false,
@@ -336,14 +482,39 @@ var s402Facilitator = class {
 				errorCode: "SCHEME_NOT_SUPPORTED"
 			};
 		}
-		const dedupeKey = JSON.stringify(payload);
-		if (this.inFlight.has(dedupeKey)) return {
-			success: false,
-			error: "Duplicate payment request already in flight",
-			errorCode: "INVALID_PAYLOAD"
-		};
-		this.inFlight.add(dedupeKey);
+		const dedupeKey = options?.idempotencyKey ?? JSON.stringify(payload);
+		const cached = this.getCached(dedupeKey);
+		if (cached) return cached;
+		const inFlight = this.inFlight.get(dedupeKey);
+		if (inFlight) return inFlight;
+		const resultPromise = this.executeProcess(payload, requirements, scheme, options).then((result) => {
+			this.cacheResult(dedupeKey, result);
+			return result;
+		});
+		this.inFlight.set(dedupeKey, resultPromise);
 		try {
+			return await resultPromise;
+		} finally {
+			this.inFlight.delete(dedupeKey);
+		}
+	}
+	async executeProcess(payload, requirements, scheme, options) {
+		const extensions = this.extensionRegistry.size > 0 ? this.extensionRegistry.sorted() : null;
+		if (!options?.skipVerify) {
+			if (extensions) try {
+				await runExtensionHooks(extensions, "beforeVerify", (ext) => ext.beforeVerify ? ext.beforeVerify(payload, requirements) : Promise.resolve(), this.extensionErrorHandler);
+			} catch (e) {
+				if (e instanceof s402Error) return {
+					success: false,
+					error: e.message,
+					errorCode: e.code
+				};
+				return {
+					success: false,
+					error: "Extension beforeVerify failed",
+					errorCode: "EXTENSION_FAILED"
+				};
+			}
 			let verifyResult;
 			try {
 				let verifyTimer;
@@ -362,25 +533,81 @@ var s402Facilitator = class {
 				error: verifyResult.invalidReason ?? "Payment verification failed",
 				errorCode: "VERIFICATION_FAILED"
 			};
-			if (typeof requirements.expiresAt === "number" && Date.now() > requirements.expiresAt) return {
-				success: false,
-				error: `Payment requirements expired during verification at ${new Date(requirements.expiresAt).toISOString()}`,
-				errorCode: "REQUIREMENTS_EXPIRED"
-			};
-			try {
-				let settleTimer;
-				return await Promise.race([scheme.settle(payload, requirements), new Promise((_, reject) => {
-					settleTimer = setTimeout(() => reject(/* @__PURE__ */ new Error("Settlement timed out after 15s")), 15e3);
-				})]).finally(() => clearTimeout(settleTimer));
+			if (extensions) try {
+				await runExtensionHooks(extensions, "afterVerify", (ext) => ext.afterVerify ? ext.afterVerify(payload, verifyResult) : Promise.resolve(), this.extensionErrorHandler);
 			} catch (e) {
+				if (e instanceof s402Error) return {
+					success: false,
+					error: e.message,
+					errorCode: e.code
+				};
 				return {
 					success: false,
-					error: e instanceof Error ? e.message : "Settlement failed with an unexpected error",
-					errorCode: "SETTLEMENT_FAILED"
+					error: "Extension afterVerify failed",
+					errorCode: "EXTENSION_FAILED"
 				};
 			}
-		} finally {
-			this.inFlight.delete(dedupeKey);
+			if (typeof requirements.expiresAt === "number" && Date.now() > requirements.expiresAt) return {
+				success: false,
+				error: `Payment requirements expired during verification at ${new Date(requirements.expiresAt).toISOString()}`,
+				errorCode: "REQUIREMENTS_EXPIRED"
+			};
+		}
+		if (extensions) try {
+			await runExtensionHooks(extensions, "beforeSettle", (ext) => ext.beforeSettle ? ext.beforeSettle(payload, requirements) : Promise.resolve(), this.extensionErrorHandler);
+		} catch (e) {
+			if (e instanceof s402Error) return {
+				success: false,
+				error: e.message,
+				errorCode: e.code
+			};
+			return {
+				success: false,
+				error: "Extension beforeSettle failed",
+				errorCode: "EXTENSION_FAILED"
+			};
+		}
+		let settleResult;
+		try {
+			let settleTimer;
+			settleResult = await Promise.race([scheme.settle(payload, requirements), new Promise((_, reject) => {
+				settleTimer = setTimeout(() => reject(/* @__PURE__ */ new Error("Settlement timed out after 15s")), 15e3);
+			})]).finally(() => clearTimeout(settleTimer));
+		} catch (e) {
+			return {
+				success: false,
+				error: e instanceof Error ? e.message : "Settlement failed with an unexpected error",
+				errorCode: "SETTLEMENT_FAILED"
+			};
+		}
+		if (extensions && settleResult.success) try {
+			await runExtensionHooks(extensions, "afterSettle", (ext) => ext.afterSettle ? ext.afterSettle(payload, settleResult) : Promise.resolve(), this.extensionErrorHandler);
+		} catch (e) {
+			this.extensionErrorHandler?.({
+				key: "afterSettle",
+				version: "0",
+				critical: true
+			}, e);
+		}
+		return settleResult;
+	}
+	getCached(key) {
+		const entry = this.completed.get(key);
+		if (!entry) return null;
+		if (Date.now() > entry.expiresAt) {
+			this.completed.delete(key);
+			return null;
+		}
+		return entry.result;
+	}
+	cacheResult(key, result) {
+		this.completed.set(key, {
+			result,
+			expiresAt: Date.now() + this.dedupTtlMs
+		});
+		if (this.completed.size > this.dedupMaxEntries) {
+			const oldestKey = this.completed.keys().next().value;
+			if (oldestKey !== void 0) this.completed.delete(oldestKey);
 		}
 	}
 	/**
@@ -406,4 +633,481 @@ var s402Facilitator = class {
 };
 
 //#endregion
-export { S402_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatReceiptHeader, isValidAmount, isValidU64Amount, parseReceiptHeader, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };
+//#region src/canonicalization.ts
+/**
+* s402 canonicalization — RFC 8785 JSON Canonicalization Scheme (JCS).
+*
+* JCS produces a deterministic byte sequence from a JSON value. Two parsers
+* that honor JCS produce identical bytes for semantically equal JSON, enabling
+* content-hashing and cross-language interop.
+*
+* Full spec: see `spec/canonicalization.md` (project-local, normative).
+* Summary applied here:
+*   - Object keys sorted by UTF-16 code unit order (RFC 8785 §3.2.3)
+*   - Numbers rendered per ECMA-404 shortest-roundtrip (RFC 8785 §3.2.2)
+*   - Strings escape only the minimum required (RFC 8785 §3.2.1)
+*   - Arrays preserve order
+*   - No whitespace
+*   - Reject non-finite numbers, BigInt, undefined, functions, symbols
+*
+* This module implements JCS *serialization* only. Strict parsing with
+* duplicate-key rejection is deferred to a later PR — envelope txBinding
+* verification never parses untrusted canonical JSON, so dup-key handling is
+* not on this critical path. (Client recomputes from its own objects.)
+*/
+/**
+* Serialize a JSON value to RFC 8785 canonical form.
+*
+* Returns a UTF-8 byte string (represented as `Uint8Array`). Callers hash the
+* bytes directly; do NOT re-encode via `TextEncoder` (double-encoding risk).
+*
+* @throws {s402Error} INVALID_PAYLOAD on non-JSON-safe values (NaN, Infinity,
+*                    bigint, undefined, functions, symbols, circular refs).
+*/
+function canonicalize(value) {
+	const out = [];
+	writeValue(value, out, /* @__PURE__ */ new WeakSet());
+	return new TextEncoder().encode(out.join(""));
+}
+/**
+* Convenience: canonicalize to a UTF-8 string.
+*
+* Use only when a downstream API demands a string; prefer the Uint8Array form
+* for digest inputs to avoid an extra encode/decode round-trip.
+*/
+function canonicalizeToString(value) {
+	const out = [];
+	writeValue(value, out, /* @__PURE__ */ new WeakSet());
+	return out.join("");
+}
+function writeValue(v, out, seen) {
+	if (v === null) {
+		out.push("null");
+		return;
+	}
+	const t = typeof v;
+	if (t === "boolean") {
+		out.push(v ? "true" : "false");
+		return;
+	}
+	if (t === "number") {
+		writeNumber(v, out);
+		return;
+	}
+	if (t === "string") {
+		writeString(v, out);
+		return;
+	}
+	if (t === "bigint") throw new s402Error("INVALID_PAYLOAD", "Canonicalization does not accept bigint — encode monetary amounts as decimal strings");
+	if (t === "undefined" || t === "function" || t === "symbol") throw new s402Error("INVALID_PAYLOAD", `Canonicalization does not accept ${t}`);
+	if (Array.isArray(v)) {
+		if (seen.has(v)) throw new s402Error("INVALID_PAYLOAD", "Canonicalization does not accept cyclic values");
+		seen.add(v);
+		out.push("[");
+		for (let i = 0; i < v.length; i++) {
+			if (i > 0) out.push(",");
+			writeValue(v[i], out, seen);
+		}
+		out.push("]");
+		seen.delete(v);
+		return;
+	}
+	if (t === "object") {
+		if (seen.has(v)) throw new s402Error("INVALID_PAYLOAD", "Canonicalization does not accept cyclic values");
+		seen.add(v);
+		const obj = v;
+		const keys = Object.keys(obj).sort();
+		out.push("{");
+		let first = true;
+		for (const k of keys) {
+			const val = obj[k];
+			if (val === void 0) continue;
+			if (!first) out.push(",");
+			first = false;
+			writeString(k, out);
+			out.push(":");
+			writeValue(val, out, seen);
+		}
+		out.push("}");
+		seen.delete(v);
+		return;
+	}
+	throw new s402Error("INVALID_PAYLOAD", `Canonicalization does not accept type ${t}`);
+}
+function writeNumber(n, out) {
+	if (!Number.isFinite(n)) throw new s402Error("INVALID_PAYLOAD", `Canonicalization does not accept non-finite numbers (got ${n})`);
+	if (n === 0) {
+		out.push("0");
+		return;
+	}
+	out.push(n.toString());
+}
+function writeString(s, out) {
+	out.push("\"");
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		switch (c) {
+			case 8:
+				out.push("\\b");
+				continue;
+			case 9:
+				out.push("\\t");
+				continue;
+			case 10:
+				out.push("\\n");
+				continue;
+			case 12:
+				out.push("\\f");
+				continue;
+			case 13:
+				out.push("\\r");
+				continue;
+			case 34:
+				out.push("\\\"");
+				continue;
+			case 92:
+				out.push("\\\\");
+				continue;
+		}
+		if (c < 32) {
+			out.push("\\u", c.toString(16).padStart(4, "0"));
+			continue;
+		}
+		out.push(s[i]);
+	}
+	out.push("\"");
+}
+
+//#endregion
+//#region src/envelope.ts
+/** Content type for the settlement envelope wire format. */
+const S402_ENVELOPE_CONTENT_TYPE = "application/vnd.s402.envelope+json";
+/**
+* Domain-separation prefix for txBinding digest inputs.
+* See `spec/canonicalization.md` §3.3 for the purpose registry.
+*/
+const TX_BINDING_PREFIX = "s402-txbinding-v1\0";
+/** ASCII record separator (U+001E) — unambiguous delimiter between canonical blobs. */
+const RECORD_SEPARATOR = 30;
+/**
+* Compute the `txBinding` value for a request pair.
+*
+* ```
+* txBinding = "sha256-" || base64url_no_pad(
+*   sha256(
+*     "s402-txbinding-v1\0"
+*     || JCS(requirements)
+*     || 0x1E
+*     || JCS(payload)
+*   )
+* )
+* ```
+*
+* Clients recompute this locally from their OWN `{requirements, payload}` and
+* compare to `envelope.txBinding` using a constant-time primitive. See S14.
+*/
+async function computeTxBinding(requirements, payload, alg = "sha256") {
+	if (alg !== "sha256") throw new s402Error("S402_UNKNOWN_ALGORITHM", `txBinding digest algorithm "${alg}" is not implemented in this build`);
+	const prefixBytes = new TextEncoder().encode(TX_BINDING_PREFIX);
+	const reqBytes = canonicalize(requirements);
+	const payloadBytes = canonicalize(payload);
+	const input = new Uint8Array(prefixBytes.length + reqBytes.length + 1 + payloadBytes.length);
+	let offset = 0;
+	input.set(prefixBytes, offset);
+	offset += prefixBytes.length;
+	input.set(reqBytes, offset);
+	offset += reqBytes.length;
+	input[offset] = RECORD_SEPARATOR;
+	offset += 1;
+	input.set(payloadBytes, offset);
+	const digestBuffer = await crypto.subtle.digest("SHA-256", input);
+	return `sha256-${toBase64UrlNoPad(new Uint8Array(digestBuffer))}`;
+}
+function toBase64UrlNoPad(bytes) {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function buildSettledEnvelope(ctx, settled) {
+	return {
+		...await buildBase(ctx),
+		status: "settled",
+		settled
+	};
+}
+async function buildVerifiedEnvelope(ctx) {
+	return {
+		...await buildBase(ctx),
+		status: "verified",
+		verified: {}
+	};
+}
+async function buildRejectedEnvelope(ctx, error) {
+	return {
+		...await buildBase(ctx),
+		status: "rejected",
+		rejected: { error }
+	};
+}
+async function buildPendingEnvelope(ctx, pending) {
+	return {
+		...await buildBase(ctx),
+		status: "pending",
+		pending
+	};
+}
+async function buildBase(ctx) {
+	const algs = ctx.algs ?? {
+		digest: "sha256",
+		sig: "ed25519"
+	};
+	const txBinding = await computeTxBinding(ctx.requirements, ctx.payload, algs.digest);
+	return {
+		s402Version: ctx.s402Version,
+		scheme: ctx.scheme,
+		specDigest: ctx.specDigest,
+		txBinding,
+		network: ctx.network,
+		algs,
+		timestamp: ctx.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+		facilitatorIds: ctx.facilitatorIds
+	};
+}
+function encodeEnvelopeBody(envelope) {
+	return JSON.stringify(envelope);
+}
+function decodeEnvelopeBody(body) {
+	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 envelope body must be a string, got ${typeof body}`);
+	if (body.length > MAX_BODY_BYTES) throw new s402Error("INVALID_PAYLOAD", `s402 envelope body exceeds maximum size (${body.length} > ${MAX_BODY_BYTES})`);
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (e) {
+		throw new s402Error("INVALID_PAYLOAD", `Failed to parse s402 envelope: ${e instanceof Error ? e.message : "invalid JSON"}`);
+	}
+	validateEnvelopeShape(parsed);
+	return parsed;
+}
+const VALID_STATUSES = new Set([
+	"settled",
+	"verified",
+	"rejected",
+	"pending"
+]);
+const VALID_DIGEST_ALGS = new Set([
+	"sha256",
+	"sha384",
+	"sha512",
+	"blake3"
+]);
+const VALID_SIG_ALGS = new Set([
+	"ed25519",
+	"ed25519ph",
+	"secp256k1",
+	"ml-dsa-44"
+]);
+function validateEnvelopeShape(v) {
+	if (v === null || typeof v !== "object") throw new s402Error("INVALID_PAYLOAD", "envelope must be an object");
+	const e = v;
+	requireString(e, "s402Version");
+	requireString(e, "scheme");
+	requireString(e, "specDigest");
+	requireString(e, "txBinding");
+	requireString(e, "network");
+	requireString(e, "timestamp");
+	const status = e.status;
+	if (typeof status !== "string" || !VALID_STATUSES.has(status)) throw new s402Error("INVALID_PAYLOAD", `envelope.status must be one of settled|verified|rejected|pending, got ${String(status)}`);
+	const algs = e.algs;
+	if (algs === null || typeof algs !== "object") throw new s402Error("INVALID_PAYLOAD", "envelope.algs must be an object");
+	const a = algs;
+	if (typeof a.digest !== "string" || !VALID_DIGEST_ALGS.has(a.digest)) throw new s402Error("S402_UNKNOWN_ALGORITHM", `envelope.algs.digest "${String(a.digest)}" is not recognized`);
+	if (typeof a.sig !== "string" || !VALID_SIG_ALGS.has(a.sig)) throw new s402Error("S402_UNKNOWN_ALGORITHM", `envelope.algs.sig "${String(a.sig)}" is not recognized`);
+	if (e.facilitatorIds !== void 0) {
+		if (!Array.isArray(e.facilitatorIds)) throw new s402Error("INVALID_PAYLOAD", "envelope.facilitatorIds must be an array if present");
+		for (const id of e.facilitatorIds) if (typeof id !== "string") throw new s402Error("INVALID_PAYLOAD", "envelope.facilitatorIds entries must be strings");
+	}
+	switch (status) {
+		case "settled":
+			if (e.settled === null || typeof e.settled !== "object") throw new s402Error("INVALID_PAYLOAD", "envelope.settled must be an object");
+			requireString(e.settled, "settledAt");
+			break;
+		case "verified":
+			if (e.verified === null || typeof e.verified !== "object") throw new s402Error("INVALID_PAYLOAD", "envelope.verified must be an object");
+			break;
+		case "rejected": {
+			if (e.rejected === null || typeof e.rejected !== "object") throw new s402Error("INVALID_PAYLOAD", "envelope.rejected must be an object");
+			const rej = e.rejected;
+			if (rej.error === null || typeof rej.error !== "object") throw new s402Error("INVALID_PAYLOAD", "envelope.rejected.error must be an object");
+			requireString(rej.error, "code");
+			requireString(rej.error, "message");
+			break;
+		}
+		case "pending":
+			if (e.pending === null || typeof e.pending !== "object") throw new s402Error("INVALID_PAYLOAD", "envelope.pending must be an object");
+			requireString(e.pending, "reason");
+			break;
+	}
+}
+function requireString(obj, key) {
+	if (typeof obj[key] !== "string" || obj[key] === "") throw new s402Error("INVALID_PAYLOAD", `envelope field "${key}" must be a non-empty string`);
+}
+/**
+* Perform the ADR-007 client-side MUST checks. Throws on any failure.
+*
+* Scheme-match, spec-digest, network, txBinding (constant-time), timestamp,
+* and algorithm acceptance. Resource-binding and unlock-attestation checks
+* live in higher layers (they need request-intent + scheme-specific context).
+*/
+async function verifyEnvelope(envelope, options) {
+	const { originalRequest, expectedSpecDigest, acceptedDigestAlgs = ["sha256"], acceptedSigAlgs = ["ed25519"], maxTimestampSkewMs = 300 * 1e3, now = Date.now } = options;
+	if (envelope.scheme !== originalRequest.payload.scheme) throw new s402Error("INVALID_PAYLOAD", `envelope.scheme "${envelope.scheme}" does not match payload scheme "${originalRequest.payload.scheme}"`);
+	if (!originalRequest.requirements.accepts.includes(envelope.scheme)) throw new s402Error("SCHEME_NOT_SUPPORTED", `envelope.scheme "${envelope.scheme}" is not in requirements.accepts`);
+	if (envelope.specDigest !== expectedSpecDigest) throw new s402Error("DIGEST_MISMATCH", `envelope.specDigest does not match expected scheme-digest`);
+	if (envelope.network !== originalRequest.requirements.network) throw new s402Error("NETWORK_MISMATCH", `envelope.network "${envelope.network}" does not match request network "${originalRequest.requirements.network}"`);
+	if (!acceptedDigestAlgs.includes(envelope.algs.digest)) throw new s402Error("S402_UNKNOWN_ALGORITHM", `envelope.algs.digest "${envelope.algs.digest}" is not in accepted set`);
+	if (!acceptedSigAlgs.includes(envelope.algs.sig)) throw new s402Error("S402_UNKNOWN_ALGORITHM", `envelope.algs.sig "${envelope.algs.sig}" is not in accepted set`);
+	const envTs = Date.parse(envelope.timestamp);
+	if (!Number.isFinite(envTs)) throw new s402Error("INVALID_PAYLOAD", `envelope.timestamp "${envelope.timestamp}" is not a valid ISO-8601 date`);
+	if (Math.abs(envTs - now()) > maxTimestampSkewMs) throw new s402Error("INVALID_PAYLOAD", `envelope.timestamp skew exceeds ${maxTimestampSkewMs}ms`);
+	const expectedTxBinding = await computeTxBinding(originalRequest.requirements, originalRequest.payload, envelope.algs.digest);
+	if (!constantTimeStringEqual(envelope.txBinding, expectedTxBinding)) throw new s402Error("S402_TX_BINDING_MISMATCH", `envelope.txBinding does not match locally recomputed binding`);
+}
+/**
+* Constant-time string equality — S14 invariant.
+*
+* Compares every character regardless of mismatches, so the time-to-answer
+* does not leak digest prefix information. Lengths are compared first (their
+* difference is not secret — a mismatched length means the response is
+* definitely not ours).
+*/
+function constantTimeStringEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+
+//#endregion
+//#region src/accept-payment.ts
+const Q_VALUE_PATTERN = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
+/**
+* Parse an `Accept-Payment` header into sorted preference entries.
+*
+* - Entries are returned in descending q-value order; ties preserve input order
+*   (stable sort).
+* - Malformed entries are dropped silently (robustness principle).
+* - Scheme tokens are lowercased. Whitespace around `;` and `,` is tolerated.
+* - Duplicate schemes: the highest-q occurrence wins.
+*
+* @example
+* parseAcceptPayment('s402/prepaid, s402/exact;q=0.8, tempo/charge;q=0.5');
+* // [
+* //   { scheme: 's402/prepaid', q: 1 },
+* //   { scheme: 's402/exact',   q: 0.8 },
+* //   { scheme: 'tempo/charge', q: 0.5 },
+* // ]
+*/
+function parseAcceptPayment(header) {
+	if (!header) return [];
+	const entries = [];
+	const seen = /* @__PURE__ */ new Map();
+	const segments = header.split(",");
+	for (let i = 0; i < segments.length; i++) {
+		const segment = segments[i].trim();
+		if (!segment) continue;
+		const parts = segment.split(";");
+		const scheme = parts[0].trim().toLowerCase();
+		if (!isValidSchemeToken(scheme)) continue;
+		let q = 1;
+		let valid = true;
+		for (let j = 1; j < parts.length; j++) {
+			const param = parts[j].trim();
+			if (!param) continue;
+			const eq = param.indexOf("=");
+			if (eq === -1) {
+				valid = false;
+				break;
+			}
+			const key = param.slice(0, eq).trim().toLowerCase();
+			const value = param.slice(eq + 1).trim();
+			if (key === "q") {
+				if (!Q_VALUE_PATTERN.test(value)) {
+					valid = false;
+					break;
+				}
+				q = Number.parseFloat(value);
+			}
+		}
+		if (!valid) continue;
+		const existing = seen.get(scheme);
+		if (existing !== void 0) {
+			if (entries[existing].q < q) entries[existing] = {
+				scheme,
+				q,
+				order: i
+			};
+			continue;
+		}
+		seen.set(scheme, entries.length);
+		entries.push({
+			scheme,
+			q,
+			order: i
+		});
+	}
+	entries.sort((a, b) => b.q - a.q || a.order - b.order);
+	return entries.map(({ scheme, q }) => ({
+		scheme,
+		q
+	}));
+}
+/**
+* Format a list of entries back into an `Accept-Payment` header string.
+*
+* Entries with `q=1` omit the parameter (it's the default). Other q-values
+* are emitted with up to 3 decimals, trailing zeros trimmed.
+*
+* @example
+* formatAcceptPayment([
+*   { scheme: 's402/prepaid', q: 1 },
+*   { scheme: 'tempo/charge', q: 0.5 },
+* ]);
+* // "s402/prepaid, tempo/charge;q=0.5"
+*/
+function formatAcceptPayment(entries) {
+	return entries.filter((e) => isValidSchemeToken(e.scheme) && e.q >= 0 && e.q <= 1).map((e) => e.q === 1 ? e.scheme : `${e.scheme};q=${formatQ(e.q)}`).join(", ");
+}
+/**
+* Select the best scheme both sides agree on.
+*
+* - Walks `preferred` in order (parseAcceptPayment returns them sorted by q).
+* - Returns the first scheme that appears in `supported`.
+* - Entries with `q=0` are explicit rejections and are skipped.
+* - Scheme comparison is case-insensitive; the returned string matches the
+*   casing from `supported`.
+* - If `preferred` is empty (no header), falls back to the first entry in
+*   `supported` (server's default).
+* - Returns `null` if no overlap exists.
+*/
+function selectBestScheme(preferred, supported) {
+	if (supported.length === 0) return null;
+	const supportedLower = /* @__PURE__ */ new Map();
+	for (const s of supported) supportedLower.set(s.toLowerCase(), s);
+	if (preferred.length === 0) return supported[0];
+	for (const entry of preferred) {
+		if (entry.q === 0) continue;
+		const match = supportedLower.get(entry.scheme);
+		if (match) return match;
+	}
+	return null;
+}
+function isValidSchemeToken(token) {
+	if (token.length === 0) return false;
+	return /^[A-Za-z0-9][A-Za-z0-9/\-_.+]*$/.test(token);
+}
+function formatQ(q) {
+	return q.toFixed(3).replace(/\.?0+$/, "") || "0";
+}
+
+//#endregion
+export { MAX_BODY_BYTES, S402_CONTENT_TYPE, S402_ENVELOPE_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, buildPendingEnvelope, buildRejectedEnvelope, buildSettledEnvelope, buildVerifiedEnvelope, canonicalize, canonicalizeToString, computeTxBinding, constantTimeStringEqual, createS402Error, decodeEnvelopeBody, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodeEnvelopeBody, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatAcceptPayment, formatReceiptHeader, getExtensionData, isValidAmount, isValidU64Amount, parseAcceptPayment, parseReceiptHeader, runExtensionHooks, s402Client, s402Error, s402ErrorCode, s402ExtensionRegistry, s402Facilitator, s402ResourceServer, selectBestScheme, setExtensionData, validateEnvelopeShape, validateRequirementsShape, verifyEnvelope };