s402 0.5.0 → 0.7.0

package/dist/compat/mpp.mjs

@@ -0,0 +1,363 @@
+import { S402_VERSION } from "../types.mjs";
+import { s402Error } from "../errors.mjs";
+import { isValidAmount } from "../http.mjs";
+
+//#region src/compat/mpp.ts
+const TOKEN_CHARS = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const AUTH_SCHEME_PATTERN = /^\s*Payment(?:\s+(.*))?$/i;
+/**
+* Parse a `WWW-Authenticate: Payment ...` header into an {@link MppChallenge}.
+*
+* Returns null if the header is absent, empty, or doesn't start with `Payment`.
+* Throws `INVALID_PAYLOAD` if the Payment scheme is present but required params
+* are missing. Accepts a single Payment challenge per header line — per core
+* spec §7.1 (Intent Negotiation), servers emitting multiple challenges send
+* one header per challenge.
+*
+* @example
+* ```ts
+* const header = res.headers.get('WWW-Authenticate');
+* const challenge = parseWwwAuthenticatePayment(header);
+* if (challenge?.intent === 'charge') {
+*   const req = decodeMppChargeRequest(challenge);
+*   // ...
+* }
+* ```
+*/
+function parseWwwAuthenticatePayment(header) {
+	if (!header) return null;
+	const match = AUTH_SCHEME_PATTERN.exec(header);
+	if (!match) return null;
+	const paramString = (match[1] ?? "").trim();
+	if (paramString.length === 0) throw new s402Error("INVALID_PAYLOAD", "Payment challenge missing auth-params");
+	const params = parseAuthParams(paramString);
+	const missing = [
+		"id",
+		"realm",
+		"method",
+		"intent",
+		"request"
+	].filter((k) => typeof params[k] !== "string");
+	if (missing.length > 0) throw new s402Error("INVALID_PAYLOAD", `Payment challenge missing required auth-params: ${missing.join(", ")}`);
+	return {
+		id: params.id,
+		realm: params.realm,
+		method: params.method.toLowerCase(),
+		intent: params.intent,
+		request: params.request,
+		digest: params.digest,
+		expires: params.expires,
+		description: params.description,
+		opaque: params.opaque
+	};
+}
+/**
+* Parse an `auth-params` string per RFC 9110 §11.2: `token "=" ( token / quoted-string )`
+* list separated by `OWS "," OWS`. Unknown parameters are preserved in the
+* returned map so callers can ignore them per core spec §5.1.2.
+*/
+function parseAuthParams(input) {
+	const out = {};
+	let i = 0;
+	const n = input.length;
+	while (i < n) {
+		while (i < n && (input[i] === " " || input[i] === "	" || input[i] === ",")) i++;
+		if (i >= n) break;
+		const keyStart = i;
+		while (i < n && input[i] !== "=" && input[i] !== " " && input[i] !== "	") i++;
+		const key = input.slice(keyStart, i).toLowerCase();
+		if (key.length === 0 || !TOKEN_CHARS.test(key)) throw new s402Error("INVALID_PAYLOAD", `Malformed auth-param name at position ${keyStart}`);
+		while (i < n && (input[i] === " " || input[i] === "	")) i++;
+		if (input[i] !== "=") throw new s402Error("INVALID_PAYLOAD", `Missing "=" after auth-param "${key}"`);
+		i++;
+		while (i < n && (input[i] === " " || input[i] === "	")) i++;
+		let value;
+		if (input[i] === "\"") {
+			i++;
+			const valueStart = i;
+			let raw = "";
+			while (i < n && input[i] !== "\"") if (input[i] === "\\" && i + 1 < n) {
+				raw += input[i + 1];
+				i += 2;
+			} else {
+				raw += input[i];
+				i++;
+			}
+			if (input[i] !== "\"") throw new s402Error("INVALID_PAYLOAD", `Unterminated quoted-string starting at position ${valueStart}`);
+			i++;
+			value = raw;
+		} else {
+			const valueStart = i;
+			while (i < n && input[i] !== "," && input[i] !== " " && input[i] !== "	") i++;
+			value = input.slice(valueStart, i);
+			if (value.length === 0 || !TOKEN_CHARS.test(value)) throw new s402Error("INVALID_PAYLOAD", `Malformed auth-param value for "${key}"`);
+		}
+		out[key] = value;
+	}
+	return out;
+}
+const METHOD_ID_PATTERN = /^[a-z]+$|^\*$/;
+const INTENT_PATTERN = /^[a-zA-Z0-9\-_]+$|^\*$/;
+const Q_VALUE_PATTERN = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
+/**
+* Parse an MPP `Accept-Payment` header per core spec §6.1.
+*
+* Grammar: `Accept-Payment = #(method-or-* "/" intent-or-* [weight])`.
+* Drops malformed entries silently — spec §6.1: "If Accept-Payment is
+* malformed, servers MAY ignore it." Stable sort: descending q, original
+* order on ties (preserves client preference per §6.1).
+*
+* @example
+* ```ts
+* const ranges = parseMppAcceptPayment('tempo/charge, tempo/session;q=0, stripe/*;q=0.5');
+* // [{ method: 'tempo', intent: 'charge', q: 1 },
+* //  { method: 'stripe', intent: '*', q: 0.5 },
+* //  { method: 'tempo', intent: 'session', q: 0 }]
+* ```
+*/
+function parseMppAcceptPayment(header) {
+	if (!header) return [];
+	const entries = [];
+	const parts = header.split(",");
+	for (let i = 0; i < parts.length; i++) {
+		const segment = parts[i].trim();
+		if (segment.length === 0) continue;
+		const [tokenRaw, ...paramParts] = segment.split(";");
+		const token = tokenRaw.trim().toLowerCase();
+		const slash = token.indexOf("/");
+		if (slash <= 0 || slash === token.length - 1) continue;
+		const method = token.slice(0, slash);
+		const intent = token.slice(slash + 1);
+		if (!METHOD_ID_PATTERN.test(method) || !INTENT_PATTERN.test(intent)) continue;
+		let q = 1;
+		let qSeen = false;
+		let valid = true;
+		for (const p of paramParts) {
+			const [nameRaw, valRaw] = p.split("=");
+			if (!nameRaw || valRaw === void 0) continue;
+			if (nameRaw.trim().toLowerCase() !== "q") continue;
+			if (qSeen) {
+				valid = false;
+				break;
+			}
+			qSeen = true;
+			const val = valRaw.trim();
+			if (!Q_VALUE_PATTERN.test(val)) {
+				valid = false;
+				break;
+			}
+			const parsed = Number.parseFloat(val);
+			if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+				valid = false;
+				break;
+			}
+			q = parsed;
+		}
+		if (!valid) continue;
+		entries.push({
+			range: {
+				method,
+				intent,
+				q
+			},
+			order: i
+		});
+	}
+	entries.sort((a, b) => b.range.q - a.range.q || a.order - b.order);
+	return entries.map((e) => e.range);
+}
+/**
+* Match an MPP payment range against a concrete `method/intent` pair.
+*
+* Returns a specificity score: 2 (exact match on both), 1 (one wildcard),
+* 0 (both wildcards), -1 (no match). Higher specificity wins per spec §6.1:
+* "Prefer the most specific matching range when multiple ranges match."
+*/
+function matchMppRange(range, method, intent) {
+	const methodMatch = range.method === "*" || range.method === method.toLowerCase();
+	const intentMatch = range.intent === "*" || range.intent === intent;
+	if (!methodMatch || !intentMatch) return -1;
+	return (range.method !== "*" ? 1 : 0) + (range.intent !== "*" ? 1 : 0);
+}
+function base64urlDecodeToString(input) {
+	if (!/^[A-Za-z0-9_-]*$/.test(input)) throw new s402Error("INVALID_PAYLOAD", "Value is not valid base64url (no-padding)");
+	const pad = input.length % 4;
+	const b64 = (pad === 0 ? input : input + "=".repeat(4 - pad)).replace(/-/g, "+").replace(/_/g, "/");
+	try {
+		if (typeof globalThis.atob === "function") {
+			const bin = globalThis.atob(b64);
+			const bytes = new Uint8Array(bin.length);
+			for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+			return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		}
+		const BufferCtor = globalThis.Buffer;
+		if (BufferCtor) return BufferCtor.from(b64, "base64").toString("utf-8");
+		throw new s402Error("INVALID_PAYLOAD", "No base64 decoder available in this runtime");
+	} catch (e) {
+		if (e instanceof s402Error) throw e;
+		throw new s402Error("INVALID_PAYLOAD", "Failed to decode base64url value");
+	}
+}
+/**
+* Decode the `request` parameter of an MPP Charge challenge into its shared
+* fields. Per `draft-payment-intent-charge-00` §Request Schema, every Charge
+* method emits `amount` + `currency` as REQUIRED shared fields; blockchain
+* methods additionally require `recipient`.
+*
+* @throws {s402Error} `INVALID_PAYLOAD` if the request blob is not
+*   base64url-JSON, or is missing `amount` / `currency`, or if `amount` is
+*   not a non-negative integer string.
+*/
+function decodeMppChargeRequest(challenge) {
+	if (challenge.intent !== "charge") throw new s402Error("INVALID_PAYLOAD", `Expected intent="charge", got "${challenge.intent}"`);
+	const json = base64urlDecodeToString(challenge.request);
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		throw new s402Error("INVALID_PAYLOAD", "Charge request is not valid JSON");
+	}
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) throw new s402Error("INVALID_PAYLOAD", "Charge request must be a JSON object");
+	const obj = parsed;
+	if (typeof obj.amount !== "string") throw new s402Error("INVALID_PAYLOAD", "Charge request missing \"amount\" (string)");
+	if (typeof obj.currency !== "string") throw new s402Error("INVALID_PAYLOAD", "Charge request missing \"currency\" (string)");
+	if (!isValidAmount(obj.amount)) throw new s402Error("INVALID_PAYLOAD", `Charge "amount" must be a non-negative integer string, got "${obj.amount}"`);
+	const out = {
+		amount: obj.amount,
+		currency: obj.currency
+	};
+	if (typeof obj.recipient === "string") out.recipient = obj.recipient;
+	if (typeof obj.description === "string") out.description = obj.description;
+	if (typeof obj.externalId === "string") out.externalId = obj.externalId;
+	if (obj.methodDetails != null && typeof obj.methodDetails === "object" && !Array.isArray(obj.methodDetails)) out.methodDetails = obj.methodDetails;
+	return out;
+}
+/**
+* Decode an `Authorization: Payment <base64url>` credential into its JSON form.
+* Does not verify HMAC challenge-binding — that requires the server's secret
+* and is intentionally out of scope for this client-facing helper.
+*
+* @throws {s402Error} `INVALID_PAYLOAD` if the header is missing/malformed,
+*   the blob is not base64url-JSON, or required fields (`challenge`, `payload`)
+*   are missing.
+*/
+function decodeMppCredential(authorizationHeader) {
+	if (!authorizationHeader) throw new s402Error("INVALID_PAYLOAD", "Authorization header missing");
+	const match = /^\s*Payment\s+([A-Za-z0-9_-]+)\s*$/i.exec(authorizationHeader);
+	if (!match) throw new s402Error("INVALID_PAYLOAD", "Authorization header must be \"Payment <base64url>\" (RFC 4648 §5 no-padding)");
+	const json = base64urlDecodeToString(match[1]);
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		throw new s402Error("INVALID_PAYLOAD", "Credential blob is not valid JSON");
+	}
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) throw new s402Error("INVALID_PAYLOAD", "Credential must be a JSON object");
+	const obj = parsed;
+	if (obj.challenge == null || typeof obj.challenge !== "object" || Array.isArray(obj.challenge)) throw new s402Error("INVALID_PAYLOAD", "Credential missing \"challenge\" object");
+	if (obj.payload == null || typeof obj.payload !== "object" || Array.isArray(obj.payload)) throw new s402Error("INVALID_PAYLOAD", "Credential missing \"payload\" object");
+	const ch = obj.challenge;
+	for (const k of [
+		"id",
+		"realm",
+		"method",
+		"intent",
+		"request"
+	]) if (typeof ch[k] !== "string") throw new s402Error("INVALID_PAYLOAD", `Credential challenge missing "${k}" (string)`);
+	const credential = {
+		challenge: {
+			id: ch.id,
+			realm: ch.realm,
+			method: ch.method.toLowerCase(),
+			intent: ch.intent,
+			request: ch.request
+		},
+		payload: obj.payload
+	};
+	if (typeof ch.digest === "string") credential.challenge.digest = ch.digest;
+	if (typeof ch.expires === "string") credential.challenge.expires = ch.expires;
+	if (typeof ch.description === "string") credential.challenge.description = ch.description;
+	if (typeof ch.opaque === "string") credential.challenge.opaque = ch.opaque;
+	if (typeof obj.source === "string") credential.source = obj.source;
+	return credential;
+}
+/**
+* Known-mappable MPP methods. The set is deliberately conservative:
+* a method is only listed here if its Charge request shape reliably carries
+* the fields s402 needs (`recipient` as payTo, `currency` as asset). Processor
+* methods (`stripe`, `card`) route internally — their Charge requests do not
+* expose a payTo, so they need the write-path emitter, not this translator.
+*/
+const BLOCKCHAIN_CHARGE_METHODS = new Set([
+	"tempo",
+	"evm",
+	"solana",
+	"lightning",
+	"stellar"
+]);
+/**
+* Network identifier resolution for MPP Charge requests per method.
+*
+* The core spec leaves network naming to individual method specs. This helper
+* encodes the conventions from the published drafts — `evm:{chainId}` and
+* `tempo:{chainId}` follow EIP-155-style identifiers; Solana/Lightning/Stellar
+* fall back to a method-qualified default since their chain is implicit.
+*/
+function resolveNetwork(method, methodDetails) {
+	const chainId = methodDetails?.chainId;
+	if (typeof chainId === "number" && Number.isInteger(chainId) && chainId >= 0) {
+		if (method === "evm") return `eip155:${chainId}`;
+		if (method === "tempo") return `tempo:${chainId}`;
+	}
+	if (typeof chainId === "string" && /^[0-9]+$/.test(chainId)) {
+		if (method === "evm") return `eip155:${chainId}`;
+		if (method === "tempo") return `tempo:${chainId}`;
+	}
+	return `${method}:unknown`;
+}
+/**
+* Translate an MPP Charge challenge into s402 requirements using the `exact`
+* scheme. This is the inbound half of the coexistence pattern documented in
+* `guide/upgrade-mpp.md`: an s402 client receives an MPP 402, lifts it into
+* s402 types, then reuses its existing payment machinery.
+*
+* Only blockchain-like methods are translated here. Processor methods (Stripe
+* card, etc.) route internally and do not expose the payTo/asset fields s402
+* requires — keep those on the MPP path.
+*
+* @throws {s402Error} `INVALID_PAYLOAD` if the method is not a known
+*   blockchain-style Charge method, if the request is missing a recipient
+*   (REQUIRED for blockchain methods per charge spec), or if the challenge
+*   has expired at `now`.
+*/
+function fromMppChargeChallenge(challenge, now) {
+	if (challenge.intent !== "charge") throw new s402Error("INVALID_PAYLOAD", `fromMppChargeChallenge requires intent="charge", got "${challenge.intent}"`);
+	if (!BLOCKCHAIN_CHARGE_METHODS.has(challenge.method)) throw new s402Error("INVALID_PAYLOAD", `MPP method "${challenge.method}" is not mappable to s402 requirements — processor-based methods (stripe, card) have no payTo/asset exposed in the Charge request`);
+	const request = decodeMppChargeRequest(challenge);
+	if (typeof request.recipient !== "string" || request.recipient.length === 0) throw new s402Error("INVALID_PAYLOAD", "Blockchain Charge request missing \"recipient\" — required by charge-intent spec for blockchain methods");
+	let expiresAt;
+	if (challenge.expires) {
+		const ts = Date.parse(challenge.expires);
+		if (Number.isNaN(ts)) throw new s402Error("INVALID_PAYLOAD", `Challenge "expires" is not a valid RFC 3339 date-time: "${challenge.expires}"`);
+		expiresAt = ts;
+		if (ts <= (now ?? Date.now())) throw new s402Error("INVALID_PAYLOAD", "MPP challenge has already expired");
+	}
+	return {
+		s402Version: S402_VERSION,
+		accepts: ["exact"],
+		network: resolveNetwork(challenge.method, request.methodDetails),
+		asset: request.currency,
+		amount: request.amount,
+		payTo: request.recipient,
+		expiresAt,
+		extensions: { mpp: {
+			challengeId: challenge.id,
+			method: challenge.method,
+			intent: challenge.intent,
+			realm: challenge.realm
+		} }
+	};
+}
+
+//#endregion
+export { decodeMppChargeRequest, decodeMppCredential, fromMppChargeChallenge, matchMppRange, parseMppAcceptPayment, parseWwwAuthenticatePayment };

package/dist/{compat.d.mts → compat/x402.d.mts}

@@ -1,6 +1,6 @@
-import { s402ExactPayload, s402PaymentPayload, s402PaymentRequirements } from "./types.mjs";
+import { s402ExactPayload, s402PaymentPayload, s402PaymentRequirements } from "../types.mjs";
 
-//#region src/compat.d.ts
+//#region src/compat/x402.d.ts
 /**
  * x402 PaymentRequirements shape — supports both V1 and V2 wire formats.
  *
@@ -115,7 +115,7 @@ declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope, now?: n
  *
  * @example
  * ```ts
- * import { normalizeRequirements } from 's402/compat';
+ * import { normalizeRequirements } from 's402/compat/x402';
  *
  * // Works with any format — auto-detects s402 vs x402
  * const rawJson = JSON.parse(atob(header));

package/dist/{compat.mjs → compat/x402.mjs}

@@ -1,8 +1,8 @@
-import { S402_VERSION } from "./types.mjs";
-import { s402Error } from "./errors.mjs";
-import { isValidAmount, pickRequirementsFields, validateRequirementsShape } from "./http.mjs";
+import { S402_VERSION } from "../types.mjs";
+import { s402Error } from "../errors.mjs";
+import { isValidAmount, pickRequirementsFields, validateRequirementsShape } from "../http.mjs";
 
-//#region src/compat.ts
+//#region src/compat/x402.ts
 /**
 * Convert inbound x402 requirements to s402 format.
 * Handles both V1 (`maxAmountRequired`) and V2 (`amount`) wire formats.
@@ -137,7 +137,7 @@ function fromX402Envelope(envelope, now) {
 *
 * @example
 * ```ts
-* import { normalizeRequirements } from 's402/compat';
+* import { normalizeRequirements } from 's402/compat/x402';
 *
 * // Works with any format — auto-detects s402 vs x402
 * const rawJson = JSON.parse(atob(header));

package/dist/errors.d.mts

@@ -25,6 +25,8 @@ declare const s402ErrorCode: {
   readonly SETTLEMENT_FAILED: "SETTLEMENT_FAILED";
   readonly DIGEST_MISMATCH: "DIGEST_MISMATCH";
   readonly EXTENSION_FAILED: "EXTENSION_FAILED";
+  readonly S402_TX_BINDING_MISMATCH: "S402_TX_BINDING_MISMATCH";
+  readonly S402_UNKNOWN_ALGORITHM: "S402_UNKNOWN_ALGORITHM";
 };
 type s402ErrorCodeType = (typeof s402ErrorCode)[keyof typeof s402ErrorCode];
 interface s402ErrorInfo {
@@ -36,7 +38,7 @@ interface s402ErrorInfo {
 /**
  * Create a typed s402 error with recovery hints.
  *
- * @param code - One of the 16 s402 error codes (e.g. 'SETTLEMENT_FAILED')
+ * @param code - One of the s402 error codes (e.g. 'SETTLEMENT_FAILED')
  * @param message - Optional human-readable message (defaults to the code)
  * @returns Error info object with code, message, retryable flag, and suggestedAction
  *

package/dist/errors.mjs

@@ -24,7 +24,9 @@ const s402ErrorCode = {
 	VERIFICATION_FAILED: "VERIFICATION_FAILED",
 	SETTLEMENT_FAILED: "SETTLEMENT_FAILED",
 	DIGEST_MISMATCH: "DIGEST_MISMATCH",
-	EXTENSION_FAILED: "EXTENSION_FAILED"
+	EXTENSION_FAILED: "EXTENSION_FAILED",
+	S402_TX_BINDING_MISMATCH: "S402_TX_BINDING_MISMATCH",
+	S402_UNKNOWN_ALGORITHM: "S402_UNKNOWN_ALGORITHM"
 };
 /** Error recovery hints for each error code */
 const ERROR_HINTS = {
@@ -95,12 +97,20 @@ const ERROR_HINTS = {
 	EXTENSION_FAILED: {
 		retryable: false,
 		suggestedAction: "A critical extension blocked the payment flow. Contact the extension provider or disable the extension."
+	},
+	S402_TX_BINDING_MISMATCH: {
+		retryable: false,
+		suggestedAction: "Envelope txBinding does not match locally recomputed value — the facilitator is bound to a different request than the one you sent. Do NOT retry against the same facilitator. Treat as misbehavior and escalate out-of-band."
+	},
+	S402_UNKNOWN_ALGORITHM: {
+		retryable: false,
+		suggestedAction: "Envelope uses an algorithm (digest or signature) not in your accepted set. Upgrade the client to support it or reject the envelope. Never fall through to a weaker default."
 	}
 };
 /**
 * Create a typed s402 error with recovery hints.
 *
-* @param code - One of the 16 s402 error codes (e.g. 'SETTLEMENT_FAILED')
+* @param code - One of the s402 error codes (e.g. 'SETTLEMENT_FAILED')
 * @param message - Optional human-readable message (defaults to the code)
 * @returns Error info object with code, message, retryable flag, and suggestedAction
 *

package/dist/http.d.mts

@@ -14,10 +14,10 @@ import { s402PaymentPayload, s402PaymentRequirements, s402SettleResponse } from
  * const header = encodePaymentRequired({
  *   s402Version: '1',
  *   accepts: ['exact'],
- *   network: 'sui:mainnet',
- *   asset: '0x2::sui::SUI',
+ *   network: 'your-chain:mainnet',
+ *   asset: 'NATIVE_TOKEN',
  *   amount: '1000000',
- *   payTo: '0xYOUR_ADDRESS',
+ *   payTo: 'YOUR_ADDRESS',
  * });
  * response.headers.set('payment-required', header);
  * ```
@@ -144,8 +144,23 @@ declare function validatePrepaidShape(value: unknown): void;
 declare function validateSubObjects(record: Record<string, unknown>): void;
 /** Validate that decoded payment requirements have the required shape. */
 declare function validateRequirementsShape(obj: unknown): void;
-/** Content type for s402 JSON body transport */
+/**
+ * Content type for s402 JSON body transport.
+ *
+ * Covers generic s402 request/response bodies (payload, requirements, legacy
+ * settle). The settlement envelope (ADR-007) has its own more specific media
+ * type — see `S402_ENVELOPE_CONTENT_TYPE` in `./envelope`.
+ */
 declare const S402_CONTENT_TYPE: "application/s402+json";
+/**
+ * Maximum body size (1 MB). Defense-in-depth against oversized JSON payloads.
+ * Bigger than MAX_HEADER_BYTES (64KB) because body transport is designed for
+ * large PTBs; still bounded so a malicious client can't exhaust memory via
+ * JSON.parse. Hosts should also enforce their own limits upstream (Express
+ * `limit`, Nginx `client_max_body_size`), but a wire format library should
+ * not rely on runtime enforcement.
+ */
+declare const MAX_BODY_BYTES: number;
 /** Encode payment requirements as JSON string (for response body) */
 declare function encodeRequirementsBody(requirements: s402PaymentRequirements): string;
 /** Decode payment requirements from JSON string (from response body) */
@@ -161,8 +176,10 @@ declare function decodeSettleBody(body: string): s402SettleResponse;
 /**
  * Detect transport mode from an incoming request.
  *
- * Checks Content-Type for body transport, then falls back to header detection.
- * Returns 'body' if Content-Type is application/s402+json.
+ * Checks Content-Type for body transport (generic `application/s402+json`
+ * OR the envelope-specific `application/vnd.s402.envelope+json`), then falls
+ * back to header detection.
+ * Returns 'body' if either s402 body media type is present.
  * Returns 'header' if x-payment header is present.
  * Returns 'unknown' otherwise.
  */
@@ -199,4 +216,4 @@ declare function detectProtocol(headers: Headers): 's402' | 'x402' | 'unknown';
  */
 declare function extractRequirementsFromResponse(response: Response): s402PaymentRequirements | null;
 //#endregion
-export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateSettlementOverridesShape, validateStreamShape, validateSubObjects, validateUnlockShape, validateUptoShape };
+export { MAX_BODY_BYTES, S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateSettlementOverridesShape, validateStreamShape, validateSubObjects, validateUnlockShape, validateUptoShape };

package/dist/http.mjs

@@ -26,10 +26,10 @@ function fromBase64(b64) {
 * const header = encodePaymentRequired({
 *   s402Version: '1',
 *   accepts: ['exact'],
-*   network: 'sui:mainnet',
-*   asset: '0x2::sui::SUI',
+*   network: 'your-chain:mainnet',
+*   asset: 'NATIVE_TOKEN',
 *   amount: '1000000',
-*   payTo: '0xYOUR_ADDRESS',
+*   payTo: 'YOUR_ADDRESS',
 * });
 * response.headers.set('payment-required', header);
 * ```
@@ -459,7 +459,7 @@ function validateSubObjects(record) {
 function validateRequirementsShape(obj) {
 	if (obj == null || typeof obj !== "object") throw new s402Error("INVALID_PAYLOAD", "Payment requirements is not an object");
 	const record = obj;
-	if (record.s402Version === void 0) throw new s402Error("INVALID_PAYLOAD", "Missing s402Version. For x402 format, use normalizeRequirements() from s402/compat.");
+	if (record.s402Version === void 0) throw new s402Error("INVALID_PAYLOAD", "Missing s402Version. For x402 format, use normalizeRequirements() from s402/compat/x402.");
 	if (record.s402Version !== "1") throw new s402Error("INVALID_PAYLOAD", `Unsupported s402 version "${record.s402Version}". This library supports version "1".`);
 	const missing = [];
 	if (!Array.isArray(record.accepts)) missing.push("accepts (array)");
@@ -556,8 +556,23 @@ function validateSettleShape(obj) {
 	if (record.error !== void 0 && typeof record.error !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: error must be a string, got ${typeof record.error}`);
 	if (record.errorCode !== void 0 && typeof record.errorCode !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: errorCode must be a string, got ${typeof record.errorCode}`);
 }
-/** Content type for s402 JSON body transport */
+/**
+* Content type for s402 JSON body transport.
+*
+* Covers generic s402 request/response bodies (payload, requirements, legacy
+* settle). The settlement envelope (ADR-007) has its own more specific media
+* type — see `S402_ENVELOPE_CONTENT_TYPE` in `./envelope`.
+*/
 const S402_CONTENT_TYPE = "application/s402+json";
+/**
+* Maximum body size (1 MB). Defense-in-depth against oversized JSON payloads.
+* Bigger than MAX_HEADER_BYTES (64KB) because body transport is designed for
+* large PTBs; still bounded so a malicious client can't exhaust memory via
+* JSON.parse. Hosts should also enforce their own limits upstream (Express
+* `limit`, Nginx `client_max_body_size`), but a wire format library should
+* not rely on runtime enforcement.
+*/
+const MAX_BODY_BYTES = 1024 * 1024;
 /** Encode payment requirements as JSON string (for response body) */
 function encodeRequirementsBody(requirements) {
 	return JSON.stringify(requirements);
@@ -565,6 +580,7 @@ function encodeRequirementsBody(requirements) {
 /** Decode payment requirements from JSON string (from response body) */
 function decodeRequirementsBody(body) {
 	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 requirements body must be a string, got ${typeof body}`);
+	if (body.length > MAX_BODY_BYTES) throw new s402Error("INVALID_PAYLOAD", `s402 requirements body exceeds maximum size (${body.length} > ${MAX_BODY_BYTES})`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -581,6 +597,7 @@ function encodePayloadBody(payload) {
 /** Decode payment payload from JSON string (from request body) */
 function decodePayloadBody(body) {
 	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 payload body must be a string, got ${typeof body}`);
+	if (body.length > MAX_BODY_BYTES) throw new s402Error("INVALID_PAYLOAD", `s402 payload body exceeds maximum size (${body.length} > ${MAX_BODY_BYTES})`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -597,6 +614,7 @@ function encodeSettleBody(response) {
 /** Decode settlement response from JSON string (from response body) */
 function decodeSettleBody(body) {
 	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 settle body must be a string, got ${typeof body}`);
+	if (body.length > MAX_BODY_BYTES) throw new s402Error("INVALID_PAYLOAD", `s402 settle body exceeds maximum size (${body.length} > ${MAX_BODY_BYTES})`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -609,13 +627,17 @@ function decodeSettleBody(body) {
 /**
 * Detect transport mode from an incoming request.
 *
-* Checks Content-Type for body transport, then falls back to header detection.
-* Returns 'body' if Content-Type is application/s402+json.
+* Checks Content-Type for body transport (generic `application/s402+json`
+* OR the envelope-specific `application/vnd.s402.envelope+json`), then falls
+* back to header detection.
+* Returns 'body' if either s402 body media type is present.
 * Returns 'header' if x-payment header is present.
 * Returns 'unknown' otherwise.
 */
 function detectTransport(request) {
-	if (request.headers.get("content-type")?.includes(S402_CONTENT_TYPE)) return "body";
+	const contentType = request.headers.get("content-type");
+	if (contentType?.includes(S402_CONTENT_TYPE)) return "body";
+	if (contentType?.includes("application/vnd.s402.envelope+json")) return "body";
 	if (request.headers.get(S402_HEADERS.PAYMENT)) return "header";
 	return "unknown";
 }
@@ -670,4 +692,4 @@ function extractRequirementsFromResponse(response) {
 }
 
 //#endregion
-export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateSettlementOverridesShape, validateStreamShape, validateSubObjects, validateUnlockShape, validateUptoShape };
+export { MAX_BODY_BYTES, S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateSettlementOverridesShape, validateStreamShape, validateSubObjects, validateUnlockShape, validateUptoShape };