s402 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,80 @@ 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).
 
+## [Unreleased]
+
+## [0.7.0] - 2026-04-22
+
+### Added
+
+- **`s402/compat-l402` — L402 read-path interop (DAN-344).** New entry point for consuming Lightning Labs' L402 (formerly LSAT) challenges as native s402 types. L402 is the oldest 402 dialect in production — shipping this turns the "universal read" positioning pillar from aspirational into airtight.
+  - `parseWwwAuthenticateL402(header)` — RFC 9110 auth-params parser accepting both `L402` and legacy `LSAT` auth-schemes (canonicalized to `L402` in output). Handles quoted-string + unquoted-token forms. Enforces required `macaroon` and `invoice` params.
+  - `decodeBolt11Summary(invoice)` — partial BOLT-11 decoder over the human-readable part only. Extracts network (`lightning:mainnet|testnet|regtest|signet`) and amount (converting m/u/n/p multipliers to millisatoshi with BigInt arithmetic). Rejects pico-BTC amounts not divisible by 10.
+  - `fromL402Challenge(challenge)` — translates an L402 challenge into `s402PaymentRequirements` with `scheme: 'exact'`, `asset: 'lightning:msat'`, sentinel `payTo: 'lightning:invoice'` (real destination lives in the invoice). Surfaces macaroon + invoice in `extensions.l402` for retry construction. Rejects amountless invoices as spec violations. Stamps a conservative `expiresAt = now + 60s` so that **S1 (stale payment rejection) stays load-bearing** for L402-derived requirements — the real BOLT-11 expiry tag is not decoded in v0.7 (scope deferral); the 60s floor guards against stale-invoice replay, with the tradeoff that long-expiry invoices trigger a re-fetch after 60s.
+  - **Signet prefix support**: recognizes both the canonical current-BOLT-11 prefix (`lntbs`, core-lightning + recent LND) and the legacy prefix (`lnsb`, older LND emissions). Both canonicalize to `lightning:signet` in the parsed output.
+- **~20 unit tests** at `test/compat-l402.test.ts` covering all four multiplier classes, all four network prefixes, LSAT/L402 alias handling, amountless invoices, malformed HRPs, and end-to-end header-to-requirements flows.
+- **Positioning document** at `docs/positioning.md` — canonical three-pillar USP: expressiveness (6 schemes), universal read (every 402 dialect), on-chain enforcement (Move invariants). Single source of truth for landing page, pitch, and grant copy.
+- **Universal 402 Absorption** project tracker on Linear ([project link](https://linear.app/dannydevs/project/universal-402-absorption-f6e181082db4)) with child issues DAN-344 (L402), DAN-345 (MPP Session), DAN-346 (MPP write path), DAN-347 (Google AP2), DAN-348 (IETF reference impl), DAN-349 (ERC-7824 watch).
+
+### Scope (intentionally deferred)
+
+- **L402 write path** — emitting L402 challenges requires a Lightning node to mint BOLT-11 invoices; out of scope for a wire-format library. Teams that need emission should keep Aperture in the path.
+- **Macaroon caveat decoding** — passed through opaque in v0.7; caveat introspection delegated to `node-macaroon` or equivalent.
+- **Full BOLT-11 tagged-field decoding** — node pubkey, routing hints, payment hash, description. Lightning wallets already decode these; we do not duplicate their work.
+- **BOLT-12 offers** — newer offer-based protocol, spec still evolving.
+
+### Changed
+
+- `docs/integrations.md` — added L402 compat-layer row (✅ v0.7).
+- `docs/guide/upgrade-l402.md` — new migration guide covering consumption, coexistence via `Accept-Payment`, BOLT-11 multiplier table, and honest comparison with L402.
+
+### Breaking
+
+- **Minimum Node.js bumped to 20** (from 18). Node 18 reached end-of-life April 2025; `envelope.ts`'s `computeTxBinding` relies on `globalThis.crypto.subtle` which is only available unflagged in Node 19+. `engines.node` updated to `>=20`, CI matrix dropped Node 18, README/docs updated. Node 20 and Node 22 remain fully supported.
+
+### Compatibility
+
+- **Non-compat consumers are additive.** No changes to existing types, scheme interfaces, wire format, or conformance vectors.
+- **Compat sub-path exports reorganized**: all three compat layers now live under `s402/compat/*` for symmetry and clearer intent.
+  - `s402/compat` → **`s402/compat/x402`** (breaking rename — x402 is now explicit, not the unlabeled default)
+  - `s402/compat-mpp` → **`s402/compat/mpp`**
+  - `s402/compat-l402` → **`s402/compat/l402`** (new in this release; shipped under the new path from day one)
+  - Source tree moved from flat `src/compat.ts`, `src/compat-mpp.ts`, `src/compat-l402.ts` to `src/compat/x402.ts`, `src/compat/mpp.ts`, `src/compat/l402.ts`. Pre-1.0 minor bump licenses the rename; no backward-compat aliases shipped — consumers update imports once.
+  - **Migration**: find-replace `'s402/compat'` → `'s402/compat/x402'`, `'s402/compat-mpp'` → `'s402/compat/mpp'`, `'s402/compat-l402'` → `'s402/compat/l402'`. Exported symbol names are unchanged.
+- Root `s402` entry still pulls no compat bundle — compat layers remain opt-in.
+
+## [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

package/README.md

@@ -14,7 +14,17 @@ bun add s402
 deno add npm:s402
 ```
 
-> **ESM-only.** This package ships ES modules only (`"type": "module"`). Requires Node.js >= 18. CommonJS `require()` is not supported.
+> **ESM-only.** This package ships ES modules only (`"type": "module"`). Requires Node.js >= 20. 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?
 

package/dist/compat/l402.d.mts

@@ -0,0 +1,94 @@
+import { s402PaymentRequirements } from "../types.mjs";
+
+//#region src/compat/l402.d.ts
+/**
+ * Parsed `WWW-Authenticate: L402` (or legacy `LSAT`) challenge.
+ *
+ * Per Lightning Labs' spec, an L402 challenge carries exactly two required
+ * auth-params: the `macaroon` (opaque bearer token with caveats) and the
+ * `invoice` (BOLT-11 payment request). The client pays the invoice via Lightning,
+ * receives the preimage, and presents `Authorization: L402 <macaroon>:<preimage>`
+ * on the retry.
+ */
+interface L402Challenge {
+  /** Canonicalized auth-scheme — always `"L402"`, even if the wire said `LSAT`. */
+  scheme: 'L402';
+  /** Base64-encoded macaroon. Treated as opaque by this module. */
+  macaroon: string;
+  /** BOLT-11 invoice (bech32 `ln...`). */
+  invoice: string;
+}
+/**
+ * Decoded BOLT-11 human-readable part (HRP). Only fields the translator needs.
+ *
+ * `amountMsat` is `null` for amountless invoices — BOLT-11 allows these, but
+ * they are unusual in L402 contexts since Aperture embeds the price in the
+ * invoice. Callers translating to s402 typically reject amountless invoices.
+ */
+interface Bolt11Summary {
+  network: 'lightning:mainnet' | 'lightning:testnet' | 'lightning:regtest' | 'lightning:signet';
+  /** Amount in millisatoshi as a non-negative integer string, or `null` if the invoice specifies no amount. */
+  amountMsat: string | null;
+}
+/**
+ * Parse a `WWW-Authenticate: L402 ...` header into an {@link L402Challenge}.
+ *
+ * Accepts both `L402` and legacy `LSAT` auth-schemes (case-insensitive) —
+ * Aperture in the wild still emits `LSAT` on older deployments. The output
+ * scheme is always canonicalized to `"L402"`.
+ *
+ * Returns `null` if the header is absent/empty or does not start with an L402
+ * auth-scheme. Throws `INVALID_PAYLOAD` if the scheme is present but required
+ * params (`macaroon`, `invoice`) are missing or malformed.
+ *
+ * @example
+ * ```ts
+ * const challenge = parseWwwAuthenticateL402(res.headers.get('WWW-Authenticate'));
+ * if (challenge) {
+ *   const requirements = fromL402Challenge(challenge);
+ *   // requirements.scheme === 'exact', requirements.network === 'lightning:mainnet', ...
+ * }
+ * ```
+ */
+declare function parseWwwAuthenticateL402(header: string | null | undefined): L402Challenge | null;
+/**
+ * Decode the BOLT-11 human-readable part of a Lightning invoice into its
+ * network and amount components. This is a **partial** decoder — it reads only
+ * the HRP (up to the bech32 `1` separator) because full BOLT-11 decoding
+ * requires bech32 + tagged-field parsing (~500 LOC) and the translator only
+ * needs network + amount.
+ *
+ * BOLT-11 HRP grammar: `ln{prefix}{amount?}{multiplier?}` where
+ *   - prefix ∈ {`bc`, `tb`, `bcrt`, `sb`}  (mainnet/testnet/regtest/signet)
+ *   - amount is a decimal integer (BTC units before multiplier)
+ *   - multiplier ∈ {`m`, `u`, `n`, `p`}  (milli/micro/nano/pico-BTC)
+ *
+ * Conversion to millisatoshi (msat = 10^-11 BTC):
+ *   - no multiplier: `amount * 10^11` msat
+ *   - `m`: `amount * 10^8` msat
+ *   - `u`: `amount * 10^5` msat
+ *   - `n`: `amount * 10^2` msat
+ *   - `p`: `amount / 10` msat  (amount must be multiple of 10)
+ *
+ * @throws {s402Error} `INVALID_PAYLOAD` if the HRP is malformed, the prefix is
+ *   unknown, or a pico-BTC amount is not a multiple of 10.
+ */
+declare function decodeBolt11Summary(invoice: string): Bolt11Summary;
+/**
+ * Translate an L402 challenge into s402 payment requirements using the `exact`
+ * scheme.
+ *
+ * The resulting requirements are consumable by a Lightning-aware s402 client.
+ * The `payTo` field is a sentinel (`"lightning:invoice"`) rather than a node
+ * pubkey because the true destination is inside the BOLT-11 invoice — which
+ * Lightning wallets decode themselves. The invoice and macaroon are surfaced
+ * under `extensions.l402` so the client can present them back on the retry
+ * (`Authorization: L402 <macaroon>:<preimage>`).
+ *
+ * @throws {s402Error} `INVALID_PAYLOAD` if the invoice HRP is malformed or the
+ *   invoice is amountless (L402 challenges always specify a price in the
+ *   invoice; an amountless invoice is a spec violation).
+ */
+declare function fromL402Challenge(challenge: L402Challenge): s402PaymentRequirements;
+//#endregion
+export { Bolt11Summary, L402Challenge, decodeBolt11Summary, fromL402Challenge, parseWwwAuthenticateL402 };

package/dist/compat/l402.mjs

@@ -0,0 +1,225 @@
+import { S402_VERSION } from "../types.mjs";
+import { s402Error } from "../errors.mjs";
+
+//#region src/compat/l402.ts
+const TOKEN_CHARS = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const L402_SCHEME_PATTERN = /^\s*(L402|LSAT)(?:\s+(.*))?$/i;
+/**
+* Parse a `WWW-Authenticate: L402 ...` header into an {@link L402Challenge}.
+*
+* Accepts both `L402` and legacy `LSAT` auth-schemes (case-insensitive) —
+* Aperture in the wild still emits `LSAT` on older deployments. The output
+* scheme is always canonicalized to `"L402"`.
+*
+* Returns `null` if the header is absent/empty or does not start with an L402
+* auth-scheme. Throws `INVALID_PAYLOAD` if the scheme is present but required
+* params (`macaroon`, `invoice`) are missing or malformed.
+*
+* @example
+* ```ts
+* const challenge = parseWwwAuthenticateL402(res.headers.get('WWW-Authenticate'));
+* if (challenge) {
+*   const requirements = fromL402Challenge(challenge);
+*   // requirements.scheme === 'exact', requirements.network === 'lightning:mainnet', ...
+* }
+* ```
+*/
+function parseWwwAuthenticateL402(header) {
+	if (!header) return null;
+	const match = L402_SCHEME_PATTERN.exec(header);
+	if (!match) return null;
+	const paramString = (match[2] ?? "").trim();
+	if (paramString.length === 0) throw new s402Error("INVALID_PAYLOAD", "L402 challenge missing auth-params");
+	const params = parseAuthParams(paramString);
+	const macaroon = params.macaroon;
+	const invoice = params.invoice;
+	if (typeof macaroon !== "string" || macaroon.length === 0) throw new s402Error("INVALID_PAYLOAD", "L402 challenge missing \"macaroon\" auth-param");
+	if (typeof invoice !== "string" || invoice.length === 0) throw new s402Error("INVALID_PAYLOAD", "L402 challenge missing \"invoice\" auth-param");
+	return {
+		scheme: "L402",
+		macaroon,
+		invoice
+	};
+}
+/**
+* Parse RFC 9110 §11.2 `auth-params` (`token "=" ( token / quoted-string )`
+* comma-separated). L402 uses the same grammar as MPP; this function mirrors
+* the MPP parser in `compat-mpp` rather than sharing a helper because the two
+* dialects may diverge on edge cases (e.g., L402 invoices have not historically
+* been quoted in Aperture output, whereas MPP params are consistently quoted).
+*/
+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) throw new s402Error("INVALID_PAYLOAD", `Empty auth-param value for "${key}" at position ${valueStart}`);
+		}
+		out[key] = value;
+	}
+	return out;
+}
+const HRP_PATTERN = /^ln(bcrt|tbs|bc|tb|sb)(\d+)?([munp])?1[a-z0-9]+$/;
+const NETWORK_BY_PREFIX = {
+	bc: "lightning:mainnet",
+	tb: "lightning:testnet",
+	bcrt: "lightning:regtest",
+	tbs: "lightning:signet",
+	sb: "lightning:signet"
+};
+/**
+* Decode the BOLT-11 human-readable part of a Lightning invoice into its
+* network and amount components. This is a **partial** decoder — it reads only
+* the HRP (up to the bech32 `1` separator) because full BOLT-11 decoding
+* requires bech32 + tagged-field parsing (~500 LOC) and the translator only
+* needs network + amount.
+*
+* BOLT-11 HRP grammar: `ln{prefix}{amount?}{multiplier?}` where
+*   - prefix ∈ {`bc`, `tb`, `bcrt`, `sb`}  (mainnet/testnet/regtest/signet)
+*   - amount is a decimal integer (BTC units before multiplier)
+*   - multiplier ∈ {`m`, `u`, `n`, `p`}  (milli/micro/nano/pico-BTC)
+*
+* Conversion to millisatoshi (msat = 10^-11 BTC):
+*   - no multiplier: `amount * 10^11` msat
+*   - `m`: `amount * 10^8` msat
+*   - `u`: `amount * 10^5` msat
+*   - `n`: `amount * 10^2` msat
+*   - `p`: `amount / 10` msat  (amount must be multiple of 10)
+*
+* @throws {s402Error} `INVALID_PAYLOAD` if the HRP is malformed, the prefix is
+*   unknown, or a pico-BTC amount is not a multiple of 10.
+*/
+function decodeBolt11Summary(invoice) {
+	if (typeof invoice !== "string" || invoice.length === 0) throw new s402Error("INVALID_PAYLOAD", "BOLT-11 invoice must be a non-empty string");
+	const lower = invoice.toLowerCase();
+	const match = HRP_PATTERN.exec(lower);
+	if (!match) throw new s402Error("INVALID_PAYLOAD", `Invoice does not match BOLT-11 HRP grammar (expected "ln(bc|tb|bcrt|sb){amount}{m|u|n|p}1..."): "${invoice}"`);
+	const prefix = match[1];
+	const amountPart = match[2];
+	const multiplier = match[3];
+	const network = NETWORK_BY_PREFIX[prefix];
+	if (!network) throw new s402Error("INVALID_PAYLOAD", `Unknown BOLT-11 network prefix: "${prefix}"`);
+	if (amountPart === void 0) {
+		if (multiplier !== void 0) throw new s402Error("INVALID_PAYLOAD", "BOLT-11 multiplier without amount");
+		return {
+			network,
+			amountMsat: null
+		};
+	}
+	const amount = BigInt(amountPart);
+	let amountMsat;
+	switch (multiplier) {
+		case void 0:
+			amountMsat = amount * 100000000000n;
+			break;
+		case "m":
+			amountMsat = amount * 100000000n;
+			break;
+		case "u":
+			amountMsat = amount * 100000n;
+			break;
+		case "n":
+			amountMsat = amount * 100n;
+			break;
+		case "p":
+			if (amount % 10n !== 0n) throw new s402Error("INVALID_PAYLOAD", `BOLT-11 pico-BTC amount must be a multiple of 10 (got ${amount}) — 1 msat is the minimum divisible unit`);
+			amountMsat = amount / 10n;
+			break;
+		default: throw new s402Error("INVALID_PAYLOAD", `Unknown BOLT-11 multiplier: "${multiplier}"`);
+	}
+	return {
+		network,
+		amountMsat: amountMsat.toString()
+	};
+}
+/**
+* Sentinel payTo for Lightning — the actual payment destination is encoded in
+* the invoice itself (BOLT-11 tagged fields carry node pubkey + payment hash).
+* An s402 client paying an L402 challenge routes through a Lightning wallet
+* that knows how to pay an invoice; the `payTo` field exists only to satisfy
+* the s402 schema.
+*/
+const LIGHTNING_INVOICE_SENTINEL = "lightning:invoice";
+/**
+* Conservative default expiry window applied to L402-derived requirements.
+*
+* BOLT-11 invoices carry their own expiry as a tagged field (type `x`) past
+* the `1` separator, defaulting to 3600 seconds per spec. This partial decoder
+* reads only the HRP, so the real invoice expiry is not surfaced. To keep
+* S1 (stale payment rejection) load-bearing for L402-derived requirements,
+* we stamp a conservative 60s window: an s402 client that caches requirements
+* longer than 60s must re-fetch the 402 response rather than reusing stale
+* ones against a possibly-expired invoice.
+*
+* Tradeoff: a long-lived invoice (e.g., Aperture's default 1-hour expiry) is
+* rejected by s402 after 60s even though the invoice is still payable. The
+* re-fetch cost is one extra round-trip, not a payment failure.
+*
+* A future v0.8 full BOLT-11 decoder can read the `x` tag and use the real
+* expiry. Until then, 60s is the safe floor.
+*/
+const L402_DEFAULT_EXPIRY_WINDOW_MS = 6e4;
+/**
+* Translate an L402 challenge into s402 payment requirements using the `exact`
+* scheme.
+*
+* The resulting requirements are consumable by a Lightning-aware s402 client.
+* The `payTo` field is a sentinel (`"lightning:invoice"`) rather than a node
+* pubkey because the true destination is inside the BOLT-11 invoice — which
+* Lightning wallets decode themselves. The invoice and macaroon are surfaced
+* under `extensions.l402` so the client can present them back on the retry
+* (`Authorization: L402 <macaroon>:<preimage>`).
+*
+* @throws {s402Error} `INVALID_PAYLOAD` if the invoice HRP is malformed or the
+*   invoice is amountless (L402 challenges always specify a price in the
+*   invoice; an amountless invoice is a spec violation).
+*/
+function fromL402Challenge(challenge) {
+	const summary = decodeBolt11Summary(challenge.invoice);
+	if (summary.amountMsat === null) throw new s402Error("INVALID_PAYLOAD", "L402 invoice is amountless — L402 challenges must specify an exact price via the BOLT-11 amount");
+	return {
+		s402Version: S402_VERSION,
+		accepts: ["exact"],
+		network: summary.network,
+		asset: "lightning:msat",
+		amount: summary.amountMsat,
+		payTo: LIGHTNING_INVOICE_SENTINEL,
+		expiresAt: Date.now() + L402_DEFAULT_EXPIRY_WINDOW_MS,
+		extensions: { l402: {
+			macaroon: challenge.macaroon,
+			invoice: challenge.invoice
+		} }
+	};
+}
+
+//#endregion
+export { decodeBolt11Summary, fromL402Challenge, parseWwwAuthenticateL402 };

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 };