s402 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,69 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-04-19
+
+### Added
+
+- **`s402/compat-mpp` — MPP read-path interop (DAN-339).** New entry point for consuming Stripe/Tempo Machine Payment Protocol 402 responses as native s402 types. All parsing is grounded against the actual MPP spec drafts in `tempoxyz/mpp-specs` (draft-httpauth-payment-00, draft-payment-intent-charge-00), not hearsay.
+  - `parseWwwAuthenticatePayment(header)` — RFC 9110 auth-params parser for `WWW-Authenticate: Payment`. Handles quoted-string escapes, unquoted tokens, enforces required `id`/`realm`/`method`/`intent`/`request`, preserves optional `digest`/`expires`/`description`/`opaque`.
+  - `parseMppAcceptPayment(header)` — method/intent pair grammar with wildcards on either side (`tempo/charge`, `tempo/*`, `*/session`, `*/*`) and q-values per core spec §6.1. Stable sort by descending q, preserves client order on ties.
+  - `matchMppRange(range, method, intent)` — specificity scoring (exact=2, one-wild=1, all-wild=0, no-match=−1) for the "prefer most specific matching range" rule.
+  - `decodeMppChargeRequest(challenge)` — decodes the base64url JCS `request` blob for the charge intent. Validates `amount` as non-negative integer, requires `currency`, preserves `methodDetails` untouched.
+  - `decodeMppCredential(authorizationHeader)` — base64url-nopad `Authorization: Payment <...>` decoder with trust-boundary shape validation on `challenge` and `payload`.
+  - `fromMppChargeChallenge(challenge, now?)` — translates blockchain-method Charge challenges (`tempo`/`evm`/`solana`/`lightning`/`stellar`) into `s402PaymentRequirements` with `scheme: 'exact'`. Resolves network via `eip155:{chainId}` / `tempo:{chainId}` conventions, carries challenge provenance into `extensions.mpp` for downstream routing, rejects processor-based methods (Stripe/card have no payTo in the Charge request), rejects expired challenges.
+- **40 spec-grounded unit tests** at `test/compat-mpp.test.ts` drawn from the spec's own §5.1.4 / §6.1 / §Request Schema fixtures.
+- **ADR-005 — Interop When Possible, Superset When Wise.** The governing strategic principle behind the compat layer: absorb x402/MPP as payment-in formats where their design is legitimate; superset them on primitives their business models forbid. See `docs/adr/005-interop-superset-principle.md`.
+
+### Scope (intentionally deferred to v0.7+)
+
+- Session intent (cumulative voucher ↔ Prepaid translation shim)
+- Method-specific credential-tier dispatch (EVM `permit2`/`authorization`/`transaction`/`hash`; Tempo `transaction`/`hash`/`proof`)
+- HMAC-SHA256 challenge-binding verification (server-side, needs secret)
+- Write path — emitting MPP-shaped `WWW-Authenticate: Payment` challenges from an s402 server
+
+### Changed
+
+- **956 tests across 21 files** (was 916). The 40 new compat-mpp tests join 30 unit + 6 live-server integration tests for `Accept-Payment` that shipped earlier in the 0.5 dev cycle.
+- Migration guide (`docs/guide/upgrade-mpp.md`) updated to reference real exported APIs rather than placeholder code.
+- `docs/integrations.md` compat-layer table updated: MPP Charge (read) is 🟡 v0.3, MPP `Accept-Payment` is ✅ Production, MPP Charge (write) and Session remain 📋 roadmap.
+
+### Compatibility
+
+- **Purely additive.** No changes to existing types, scheme interfaces, wire format, or conformance vectors. Existing 0.5.x consumers require no code changes.
+- **New sub-path export**: `s402/compat-mpp` sits alongside the existing `s402/compat` (x402 interop). Both are opt-in — importing from the root `s402` entry does not pull the compat bundles.
+
+## [0.5.0] - 2026-04-12
+
+### Added
+
+- **`upto` scheme V2 features (DAN-284).** Two new fields close x402's upto overcharge vulnerability:
+  - `estimatedAmount` on `s402UptoExtra` — server's advisory cost estimate so clients can set tight ceilings
+  - `settlementCeiling` on `s402UptoPayload` — client-chosen, on-chain-enforced cap. Move contract rejects `actualAmount > settlementCeiling`. Must satisfy `1 <= settlementCeiling <= maxAmount`. See ADR-003 §Decision 3 and §Decision 8.
+- **Extension system (DAN-285, ADR-004).** Typed, lifecycle-aware plugin architecture:
+  - Three actor-specific interfaces: `s402ClientExtension`, `s402ServerExtension`, `s402FacilitatorExtension`
+  - Four facilitator hooks in pipeline order: `beforeVerify` → `afterVerify` → `beforeSettle` → `afterSettle`
+  - `s402ExtensionRegistry` with dependency ordering via Kahn's topological sort
+  - Critical vs advisory error handling: `critical: true` extensions throw, advisory extensions log and continue
+  - `getExtensionData<T>()` / `setExtensionData()` type-safe helpers
+  - `./extensions` sub-path export added to package.json
+- **`skipVerify` option on `process()`.** New `s402ProcessOptions` interface with `skipVerify?: boolean`. Eliminates the verify() dry-run RPC round-trip (~200-400ms) for chains where failed transactions cost zero gas (Sui PTBs). All pre-flight checks (expiration, scheme-mismatch, dedup) still run.
+- **`EXTENSION_FAILED` error code** — `retryable: false`, for critical extension pipeline failures.
+- **154 conformance test vectors** (was ~130). New vectors for: upto requirements with estimatedAmount, upto payloads with settlementCeiling, settle responses with actualAmount/depositId, V2 rejection vectors, upto roundtrips, mandate.minPerTx validation.
+
+### Fixed
+
+- **Settle response type validation (M1).** `validateSettleShape` now rejects non-string `actualAmount` and `depositId` — a malicious facilitator could previously inject numeric types that passed through to consumer code.
+- **Prepaid payload amount validation (M2).** `ratePerCall` and `maxCalls` in payload now validated with `isValidAmount()`, matching the requirements-side validation. Previously only type-checked as strings.
+- **Mandate minPerTx amount validation (L1).** `mandate.minPerTx` now validated with `isValidAmount()` for consistency with other amount fields.
+- **afterSettle error observability.** Catch block now forwards to `extensionErrorHandler` instead of silently swallowing critical extension errors (the settlement result is still never changed — tx is already on-chain).
+- **Stale comment in validatePayloadShape.** Updated to document upto's scheme-specific inner keys alongside prepaid and unlock.
+
+### Changed
+
+- **831 tests across 17 files** (was 798). New coverage: standalone verify/settle guard tests, V2 validation edge cases, settle response type checks, prepaid amount validation, extension system integration.
+- Conformance README updated with `estimatedAmount` in upto sub-object keys and `settlementCeiling` in payload inner keys.
+
 ## [0.4.0] - 2026-04-11
 
 ### Changed

package/README.md

@@ -16,6 +16,16 @@ deno add npm:s402
 
 > **ESM-only.** This package ships ES modules only (`"type": "module"`). Requires Node.js >= 18. CommonJS `require()` is not supported.
 
+## Governing Principle
+
+> **We interop when possible. We superset when wise.**
+
+s402 does not fight x402 or Stripe MPP head-on. s402 **absorbs** them as payment-in formats where their design choices are legitimate (exact, upto), and **supersets** them on primitives their business models cannot ship (prepaid with on-chain ceiling, streaming with rate enforcement, escrow with arbiter, Seal-encrypted unlock).
+
+This is the Postgres-eats-MySQL move: the superset always eats the subset because adopters never lose what they had — they only gain. The asymmetry is in s402's favor because competitors' constraints forbid reciprocating. Stripe cannot accept s402 schemes without bypassing card-processing margin. x402's 2-scheme governance envelope cannot absorb s402's 5 without re-ratification.
+
+See [ADR-005](./docs/adr/005-interop-superset-principle.md) for the full reasoning.
+
 ## Why s402?
 
 HTTP 402 ("Payment Required") has been reserved since 1999 — waiting for a payment protocol that actually works. Coinbase's x402 proved the concept on EVM. s402 takes it further by leveraging what makes Sui different.

package/dist/compat-mpp.d.mts

@@ -0,0 +1,160 @@
+import { s402PaymentRequirements } from "./types.mjs";
+
+//#region src/compat-mpp.d.ts
+/**
+ * Parsed `WWW-Authenticate: Payment` challenge parameters.
+ *
+ * Required params per core spec §5.1.1: id, realm, method, intent, request.
+ * Optional params per §5.1.2: digest, expires, description, opaque.
+ * `request` is a base64url-nopad JCS-encoded JSON object — decoded separately
+ * by intent-specific parsers (see {@link decodeMppChargeRequest}).
+ */
+interface MppChallenge {
+  id: string;
+  realm: string;
+  method: string;
+  intent: string;
+  request: string;
+  digest?: string;
+  expires?: string;
+  description?: string;
+  opaque?: string;
+}
+/**
+ * Shared Charge-intent request fields per `draft-payment-intent-charge-00` §Request Schema.
+ *
+ * `amount` + `currency` are required across every method. `recipient` is
+ * REQUIRED for blockchain methods and OPTIONAL for processor-based methods
+ * (Stripe routes internally). `methodDetails` holds method-specific extension
+ * data (chainId, permit2Address, invoice, networkId, paymentMethodTypes, ...).
+ */
+interface MppChargeRequest {
+  amount: string;
+  currency: string;
+  recipient?: string;
+  description?: string;
+  externalId?: string;
+  methodDetails?: Record<string, unknown>;
+}
+/**
+ * Decoded `Authorization: Payment <base64url>` credential per core spec §5.2.
+ *
+ * `challenge` echoes the original challenge params (verified server-side).
+ * `payload` is method-specific (Permit2 signature, Lightning preimage, Stripe
+ * confirmation id, ...). `source` is RECOMMENDED DID format for payer identity.
+ */
+interface MppCredential {
+  challenge: {
+    id: string;
+    realm: string;
+    method: string;
+    intent: string;
+    request: string;
+    digest?: string;
+    expires?: string;
+    description?: string;
+    opaque?: string;
+  };
+  source?: string;
+  payload: Record<string, unknown>;
+}
+/**
+ * Entry in an MPP `Accept-Payment` header.
+ *
+ * MPP preference uses method/intent pairs with wildcards on either side
+ * (`tempo/x`, `x/session`, `x/x` where `x` is the literal `*`) and q-values
+ * per RFC 9110. This differs from s402's flat scheme tokens (`s402/exact`,
+ * `s402/prepaid`) which `parseAcceptPayment` treats as opaque strings.
+ */
+interface MppPaymentRange {
+  /** Lowercase method id or "*" wildcard. */
+  method: string;
+  /** Intent token or "*" wildcard. */
+  intent: string;
+  /** Quality factor in [0,1]; 0 means "do not use". */
+  q: number;
+}
+/**
+ * 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);
+ *   // ...
+ * }
+ * ```
+ */
+declare function parseWwwAuthenticatePayment(header: string | null | undefined): MppChallenge | null;
+/**
+ * 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 }]
+ * ```
+ */
+declare function parseMppAcceptPayment(header: string | null | undefined): MppPaymentRange[];
+/**
+ * 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."
+ */
+declare function matchMppRange(range: MppPaymentRange, method: string, intent: string): number;
+/**
+ * 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.
+ */
+declare function decodeMppChargeRequest(challenge: MppChallenge): MppChargeRequest;
+/**
+ * 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.
+ */
+declare function decodeMppCredential(authorizationHeader: string | null | undefined): MppCredential;
+/**
+ * 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`.
+ */
+declare function fromMppChargeChallenge(challenge: MppChallenge, now?: number): s402PaymentRequirements;
+//#endregion
+export { MppChallenge, MppChargeRequest, MppCredential, MppPaymentRange, decodeMppChargeRequest, decodeMppCredential, fromMppChargeChallenge, matchMppRange, parseMppAcceptPayment, parseWwwAuthenticatePayment };

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

@@ -58,7 +58,7 @@ interface x402PaymentPayload {
  * Handles both V1 (`maxAmountRequired`) and V2 (`amount`) wire formats.
  * Maps x402's single scheme to s402's accepts array.
  */
-declare function fromX402Requirements(x402: x402PaymentRequirements): s402PaymentRequirements;
+declare function fromX402Requirements(x402: x402PaymentRequirements, now?: number): s402PaymentRequirements;
 /**
  * Convert inbound x402 payment payload to s402 format.
  * Validates that required fields are present and correctly typed.
@@ -66,7 +66,7 @@ declare function fromX402Requirements(x402: x402PaymentRequirements): s402Paymen
 declare function fromX402Payload(x402: x402PaymentPayload): s402ExactPayload;
 /**
  * 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.
@@ -101,7 +101,7 @@ declare function isX402Envelope(obj: Record<string, unknown>): boolean;
  * Picks the first requirement from the `accepts` array.
  * Copies `x402Version` from the envelope onto the requirement for downstream processing.
  */
-declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope): s402PaymentRequirements;
+declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope, now?: number): s402PaymentRequirements;
 /**
  * Auto-detect and normalize: if x402, convert to s402. If already s402, validate and pass through.
  * Handles x402 V1 (flat), x402 V2 (envelope with accepts array), and s402 formats.
@@ -123,6 +123,6 @@ declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope): s402Pa
  * // Always returns s402PaymentRequirements regardless of input format
  * ```
  */
-declare function normalizeRequirements(obj: Record<string, unknown>): s402PaymentRequirements;
+declare function normalizeRequirements(obj: Record<string, unknown>, now?: number): s402PaymentRequirements;
 //#endregion
 export { fromX402Envelope, fromX402Payload, fromX402Requirements, isS402, isX402, isX402Envelope, normalizeRequirements, toX402Payload, toX402Requirements, x402PaymentPayload, x402PaymentRequiredEnvelope, x402PaymentRequirements };