s402 0.4.0 → 0.6.0

package/dist/compat.mjs

@@ -8,7 +8,7 @@ import { isValidAmount, pickRequirementsFields, validateRequirementsShape } from
 * Handles both V1 (`maxAmountRequired`) and V2 (`amount`) wire formats.
 * Maps x402's single scheme to s402's accepts array.
 */
-function fromX402Requirements(x402) {
+function fromX402Requirements(x402, now) {
 	const amount = x402.amount ?? x402.maxAmountRequired;
 	if (!amount) throw new s402Error("INVALID_PAYLOAD", "x402 requirements missing both \"amount\" (V2) and \"maxAmountRequired\" (V1)");
 	if (!isValidAmount(amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${amount}": must be a non-negative integer string`);
@@ -20,6 +20,7 @@ function fromX402Requirements(x402) {
 		if (e instanceof s402Error) throw e;
 		throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl is not a valid URL");
 	}
+	const expiresAt = x402.maxTimeoutSeconds != null && x402.maxTimeoutSeconds > 0 ? (now ?? Date.now()) + x402.maxTimeoutSeconds * 1e3 : void 0;
 	return {
 		s402Version: S402_VERSION,
 		accepts: ["exact"],
@@ -28,6 +29,7 @@ function fromX402Requirements(x402) {
 		amount,
 		payTo: x402.payTo,
 		facilitatorUrl: x402.facilitatorUrl,
+		expiresAt,
 		extensions: x402.extensions
 	};
 }
@@ -50,7 +52,7 @@ function fromX402Payload(x402) {
 }
 /**
 * Convert outbound s402 requirements to x402 V1 wire format.
-* Strips s402-only fields (mandate, stream, escrow, unlock extensions).
+* Strips s402-only fields (mandate, upto, prepaid, stream, escrow, unlock extensions).
 * Only works for "exact" scheme — other schemes have no x402 equivalent.
 *
 * Includes both `maxAmountRequired` (V1) and `amount` (V2) for maximum interop.
@@ -113,14 +115,14 @@ function isX402Envelope(obj) {
 * Picks the first requirement from the `accepts` array.
 * Copies `x402Version` from the envelope onto the requirement for downstream processing.
 */
-function fromX402Envelope(envelope) {
+function fromX402Envelope(envelope, now) {
 	if (!envelope.accepts || envelope.accepts.length === 0) throw new s402Error("INVALID_PAYLOAD", "x402 V2 envelope has empty accepts array");
 	const req = {
 		...envelope.accepts[0],
 		x402Version: envelope.x402Version
 	};
 	validateX402Shape(req);
-	return fromX402Requirements(req);
+	return fromX402Requirements(req, now);
 }
 /**
 * Auto-detect and normalize: if x402, convert to s402. If already s402, validate and pass through.
@@ -143,20 +145,20 @@ function fromX402Envelope(envelope) {
 * // Always returns s402PaymentRequirements regardless of input format
 * ```
 */
-function normalizeRequirements(obj) {
+function normalizeRequirements(obj, now) {
 	if (obj == null || typeof obj !== "object" || Array.isArray(obj)) throw new s402Error("INVALID_PAYLOAD", `Payment requirements must be a plain object, got ${obj === null ? "null" : Array.isArray(obj) ? "array" : typeof obj}`);
 	if (isS402(obj)) {
 		validateRequirementsShape(obj);
 		return pickRequirementsFields(obj);
 	}
 	if (isX402Envelope(obj)) {
-		const record = fromX402Envelope(obj);
+		const record = fromX402Envelope(obj, now);
 		validateRequirementsShape(record);
 		return pickRequirementsFields(record);
 	}
 	if (isX402(obj)) {
 		validateX402Shape(obj);
-		const record = fromX402Requirements(obj);
+		const record = fromX402Requirements(obj, now);
 		validateRequirementsShape(record);
 		return pickRequirementsFields(record);
 	}

package/dist/errors.d.mts

@@ -24,6 +24,9 @@ declare const s402ErrorCode: {
   readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
   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 {
@@ -35,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

@@ -23,7 +23,10 @@ const s402ErrorCode = {
 	REQUIREMENTS_EXPIRED: "REQUIREMENTS_EXPIRED",
 	VERIFICATION_FAILED: "VERIFICATION_FAILED",
 	SETTLEMENT_FAILED: "SETTLEMENT_FAILED",
-	DIGEST_MISMATCH: "DIGEST_MISMATCH"
+	DIGEST_MISMATCH: "DIGEST_MISMATCH",
+	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 = {
@@ -90,12 +93,24 @@ const ERROR_HINTS = {
 	DIGEST_MISMATCH: {
 		retryable: false,
 		suggestedAction: "Facilitator returned a transaction digest that does not match the signed payload. Do NOT retry — treat payment as non-settled and investigate the facilitator."
+	},
+	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);
  * ```
@@ -117,9 +117,13 @@ declare function isValidU64Amount(s: string): boolean;
  */
 declare function validateMandateShape(value: unknown): void;
 /**
- * Validate stream sub-object.
- * Checks required fields are present and correctly typed.
+ * Validate upto sub-object (usage-based variable settlement).
  */
+declare function validateUptoShape(value: unknown): void;
+/**
+ * Validate settlementOverrides sub-object.
+ */
+declare function validateSettlementOverridesShape(value: unknown): void;
 declare function validateStreamShape(value: unknown): void;
 /**
  * Validate escrow sub-object.
@@ -140,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) */
@@ -157,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.
  */
@@ -195,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, validateStreamShape, validateSubObjects, validateUnlockShape };
+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);
 * ```
@@ -83,10 +83,12 @@ const S402_REQUIREMENTS_KEYS = new Set([
 	"receiptRequired",
 	"settlementMode",
 	"expiresAt",
+	"upto",
+	"settlementOverrides",
+	"prepaid",
 	"stream",
 	"escrow",
 	"unlock",
-	"prepaid",
 	"extensions"
 ]);
 /** Known keys for each sub-object type — used to strip extra keys at the trust boundary. */
@@ -96,6 +98,21 @@ const S402_SUB_OBJECT_KEYS = {
 		"minPerTx",
 		"coinType"
 	]),
+	upto: new Set([
+		"maxAmount",
+		"settlementDeadlineMs",
+		"usageReportUrl",
+		"estimatedAmount"
+	]),
+	settlementOverrides: new Set(["actualAmount"]),
+	prepaid: new Set([
+		"ratePerCall",
+		"maxCalls",
+		"minDeposit",
+		"withdrawalDelayMs",
+		"providerPubkey",
+		"disputeWindowMs"
+	]),
 	stream: new Set([
 		"ratePerSecond",
 		"budgetCap",
@@ -111,14 +128,6 @@ const S402_SUB_OBJECT_KEYS = {
 		"encryptionId",
 		"encryptedContentId",
 		"encryptionServiceId"
-	]),
-	prepaid: new Set([
-		"ratePerCall",
-		"maxCalls",
-		"minDeposit",
-		"withdrawalDelayMs",
-		"providerPubkey",
-		"disputeWindowMs"
 	])
 };
 /** Strip unknown keys from a sub-object, returning a clean copy. */
@@ -178,22 +187,29 @@ const S402_PAYLOAD_TOP_KEYS = new Set([
 ]);
 /**
 * Known inner payload keys per scheme. All schemes share transaction + signature;
-* unlock adds encryptionId, prepaid adds ratePerCall + maxCalls.
+* upto adds maxAmount + settlementCeiling, prepaid adds ratePerCall + maxCalls,
+* unlock adds encryptionId.
 */
 const S402_PAYLOAD_INNER_KEYS = {
 	exact: new Set(["transaction", "signature"]),
-	stream: new Set(["transaction", "signature"]),
-	escrow: new Set(["transaction", "signature"]),
-	unlock: new Set([
+	upto: new Set([
 		"transaction",
 		"signature",
-		"encryptionId"
+		"maxAmount",
+		"settlementCeiling"
 	]),
 	prepaid: new Set([
 		"transaction",
 		"signature",
 		"ratePerCall",
 		"maxCalls"
+	]),
+	stream: new Set(["transaction", "signature"]),
+	escrow: new Set(["transaction", "signature"]),
+	unlock: new Set([
+		"transaction",
+		"signature",
+		"encryptionId"
 	])
 };
 /** Return a clean payload object with only known s402 payload fields. */
@@ -249,9 +265,11 @@ const S402_SETTLE_RESPONSE_KEYS = new Set([
 	"txDigest",
 	"receiptId",
 	"finalityMs",
+	"actualAmount",
+	"depositId",
+	"balanceId",
 	"streamId",
 	"escrowId",
-	"balanceId",
 	"error",
 	"errorCode"
 ]);
@@ -277,10 +295,11 @@ function decodeSettleResponse(header) {
 /** Valid s402 payment scheme values */
 const VALID_SCHEMES = new Set([
 	"exact",
+	"upto",
+	"prepaid",
 	"stream",
 	"escrow",
-	"unlock",
-	"prepaid"
+	"unlock"
 ]);
 /**
 * Check that a string represents a canonical non-negative integer.
@@ -338,12 +357,37 @@ function validateMandateShape(value) {
 	const obj = value;
 	if (typeof obj.required !== "boolean") throw new s402Error("INVALID_PAYLOAD", `mandate.required must be a boolean, got ${typeof obj.required}`);
 	assertOptionalString(obj, "minPerTx", "mandate");
+	if (typeof obj.minPerTx === "string" && !isValidAmount(obj.minPerTx)) throw new s402Error("INVALID_PAYLOAD", `mandate.minPerTx must be a non-negative integer string, got "${obj.minPerTx}"`);
 	assertOptionalString(obj, "coinType", "mandate");
 }
 /**
-* Validate stream sub-object.
-* Checks required fields are present and correctly typed.
+* Validate upto sub-object (usage-based variable settlement).
+*/
+function validateUptoShape(value) {
+	assertPlainObject(value, "upto");
+	const obj = value;
+	assertString(obj, "maxAmount", "upto");
+	if (typeof obj.maxAmount === "string" && !isValidAmount(obj.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto.maxAmount must be a non-negative integer string, got "${obj.maxAmount}"`);
+	assertString(obj, "settlementDeadlineMs", "upto");
+	if (typeof obj.settlementDeadlineMs === "string" && !isValidAmount(obj.settlementDeadlineMs)) throw new s402Error("INVALID_PAYLOAD", `upto.settlementDeadlineMs must be a non-negative integer string (Unix timestamp ms), got "${obj.settlementDeadlineMs}"`);
+	assertOptionalString(obj, "usageReportUrl", "upto");
+	assertOptionalString(obj, "estimatedAmount", "upto");
+	if (typeof obj.estimatedAmount === "string") {
+		if (!isValidAmount(obj.estimatedAmount)) throw new s402Error("INVALID_PAYLOAD", `upto.estimatedAmount must be a non-negative integer string, got "${obj.estimatedAmount}"`);
+		if (typeof obj.maxAmount === "string" && isValidAmount(obj.maxAmount)) {
+			if (BigInt(obj.estimatedAmount) > BigInt(obj.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto.estimatedAmount (${obj.estimatedAmount}) must be <= maxAmount (${obj.maxAmount})`);
+		}
+	}
+}
+/**
+* Validate settlementOverrides sub-object.
 */
+function validateSettlementOverridesShape(value) {
+	assertPlainObject(value, "settlementOverrides");
+	const obj = value;
+	assertString(obj, "actualAmount", "settlementOverrides");
+	if (typeof obj.actualAmount === "string" && !isValidAmount(obj.actualAmount)) throw new s402Error("INVALID_PAYLOAD", `settlementOverrides.actualAmount must be a non-negative integer string, got "${obj.actualAmount}"`);
+}
 function validateStreamShape(value) {
 	assertPlainObject(value, "stream");
 	const obj = value;
@@ -404,10 +448,12 @@ function validatePrepaidShape(value) {
 */
 function validateSubObjects(record) {
 	if (record.mandate !== void 0) validateMandateShape(record.mandate);
+	if (record.upto !== void 0) validateUptoShape(record.upto);
+	if (record.settlementOverrides !== void 0) validateSettlementOverridesShape(record.settlementOverrides);
+	if (record.prepaid !== void 0) validatePrepaidShape(record.prepaid);
 	if (record.stream !== void 0) validateStreamShape(record.stream);
 	if (record.escrow !== void 0) validateEscrowShape(record.escrow);
 	if (record.unlock !== void 0) validateUnlockShape(record.unlock);
-	if (record.prepaid !== void 0) validatePrepaidShape(record.prepaid);
 }
 /** Validate that decoded payment requirements have the required shape. */
 function validateRequirementsShape(obj) {
@@ -474,8 +520,25 @@ function validatePayloadShape(obj) {
 	if (typeof inner.transaction !== "string") throw new s402Error("INVALID_PAYLOAD", `payload.transaction must be a string, got ${typeof inner.transaction}`);
 	if (typeof inner.signature !== "string") throw new s402Error("INVALID_PAYLOAD", `payload.signature must be a string, got ${typeof inner.signature}`);
 	if (record.scheme === "unlock" && typeof inner.encryptionId !== "string") throw new s402Error("INVALID_PAYLOAD", `unlock payload requires encryptionId (string), got ${typeof inner.encryptionId}`);
-	if (record.scheme === "prepaid" && typeof inner.ratePerCall !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload requires ratePerCall (string), got ${typeof inner.ratePerCall}`);
-	if (record.scheme === "prepaid" && inner.maxCalls !== void 0 && typeof inner.maxCalls !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload maxCalls must be a string if provided, got ${typeof inner.maxCalls}`);
+	if (record.scheme === "upto") {
+		if (typeof inner.maxAmount !== "string") throw new s402Error("INVALID_PAYLOAD", `upto payload requires maxAmount (string), got ${typeof inner.maxAmount}`);
+		if (!isValidAmount(inner.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto payload maxAmount must be a non-negative integer string, got "${inner.maxAmount}"`);
+		if (inner.settlementCeiling !== void 0) {
+			if (typeof inner.settlementCeiling !== "string") throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling must be a string if provided, got ${typeof inner.settlementCeiling}`);
+			if (!isValidAmount(inner.settlementCeiling)) throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling must be a non-negative integer string, got "${inner.settlementCeiling}"`);
+			const ceiling = BigInt(inner.settlementCeiling);
+			if (ceiling < 1n) throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling must be >= 1, got "${inner.settlementCeiling}"`);
+			if (ceiling > BigInt(inner.maxAmount)) throw new s402Error("INVALID_PAYLOAD", `upto payload settlementCeiling (${inner.settlementCeiling}) must be <= maxAmount (${inner.maxAmount})`);
+		}
+	}
+	if (record.scheme === "prepaid") {
+		if (typeof inner.ratePerCall !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload requires ratePerCall (string), got ${typeof inner.ratePerCall}`);
+		if (!isValidAmount(inner.ratePerCall)) throw new s402Error("INVALID_PAYLOAD", `prepaid payload ratePerCall must be a non-negative integer string, got "${inner.ratePerCall}"`);
+		if (inner.maxCalls !== void 0) {
+			if (typeof inner.maxCalls !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload maxCalls must be a string if provided, got ${typeof inner.maxCalls}`);
+			if (!isValidAmount(inner.maxCalls)) throw new s402Error("INVALID_PAYLOAD", `prepaid payload maxCalls must be a non-negative integer string, got "${inner.maxCalls}"`);
+		}
+	}
 }
 /** Validate that a decoded settle response has the required shape. */
 function validateSettleShape(obj) {
@@ -488,11 +551,28 @@ function validateSettleShape(obj) {
 	if (record.streamId !== void 0 && typeof record.streamId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: streamId must be a string, got ${typeof record.streamId}`);
 	if (record.escrowId !== void 0 && typeof record.escrowId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: escrowId must be a string, got ${typeof record.escrowId}`);
 	if (record.balanceId !== void 0 && typeof record.balanceId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: balanceId must be a string, got ${typeof record.balanceId}`);
+	if (record.actualAmount !== void 0 && typeof record.actualAmount !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: actualAmount must be a string, got ${typeof record.actualAmount}`);
+	if (record.depositId !== void 0 && typeof record.depositId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: depositId must be a string, got ${typeof record.depositId}`);
 	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);
@@ -500,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);
@@ -516,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);
@@ -532,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);
@@ -544,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";
 }
@@ -605,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, validateStreamShape, validateSubObjects, validateUnlockShape };
+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 };