s402 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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

package/README.md

@@ -14,7 +14,7 @@ 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
 

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 → compat/mpp.d.mts}

@@ -1,6 +1,6 @@
-import { s402PaymentRequirements } from "./types.mjs";
+import { s402PaymentRequirements } from "../types.mjs";
 
-//#region src/compat-mpp.d.ts
+//#region src/compat/mpp.d.ts
 /**
  * Parsed `WWW-Authenticate: Payment` challenge parameters.
  *

package/dist/{compat-mpp.mjs → compat/mpp.mjs}

@@ -1,8 +1,8 @@
-import { S402_VERSION } from "./types.mjs";
-import { s402Error } from "./errors.mjs";
-import { isValidAmount } from "./http.mjs";
+import { S402_VERSION } from "../types.mjs";
+import { s402Error } from "../errors.mjs";
+import { isValidAmount } from "../http.mjs";
 
-//#region src/compat-mpp.ts
+//#region src/compat/mpp.ts
 const TOKEN_CHARS = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const AUTH_SCHEME_PATTERN = /^\s*Payment(?:\s+(.*))?$/i;
 /**

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/http.mjs

@@ -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)");

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { createS402Error, s402Error, s402ErrorCode, s402ErrorCodeType, s402ErrorInfo } from "./errors.mjs";
 import { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PaymentSession, s402PrepaidExtra, s402PrepaidPayload, s402RegistryQuery, s402Scheme, s402ServiceEntry, s402SettleResponse, s402SettlementMode, s402SettlementOverrides, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402UptoExtra, s402UptoPayload, s402VerifyResponse } from "./types.mjs";
 import { MAX_BODY_BYTES, S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
-import { a as s402ServerScheme, i as s402RouteConfig, n as s402DirectScheme, o as s402SettlementVerification, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-CKinOhyx.mjs";
+import { a as s402ServerScheme, i as s402RouteConfig, n as s402DirectScheme, o as s402SettlementVerification, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-M-z-UV0c.mjs";
 import { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader, s402Receipt, s402ReceiptSigner, s402ReceiptVerifier } from "./receipts.mjs";
 
 //#region src/client.d.ts
@@ -32,7 +32,7 @@ declare class s402Client {
    * `accepts` array that we have a registered implementation for.
    *
    * Accepts typed s402PaymentRequirements only. For x402 input, normalize
-   * first via `normalizeRequirements()` from 's402/compat'.
+   * first via `normalizeRequirements()` from 's402/compat/x402'.
    *
    * @param requirements - Server's payment requirements (from a 402 response)
    * @returns Payment payload ready to send in the `x-payment` header

package/dist/index.mjs

@@ -35,7 +35,7 @@ var s402Client = class {
 	* `accepts` array that we have a registered implementation for.
 	*
 	* Accepts typed s402PaymentRequirements only. For x402 input, normalize
-	* first via `normalizeRequirements()` from 's402/compat'.
+	* first via `normalizeRequirements()` from 's402/compat/x402'.
 	*
 	* @param requirements - Server's payment requirements (from a 402 response)
 	* @returns Payment payload ready to send in the `x-payment` header

package/dist/test-utils.d.mts

@@ -1,5 +1,5 @@
 import { s402PaymentPayload, s402PaymentRequirements, s402SettleResponse, s402VerifyResponse } from "./types.mjs";
-import { a as s402ServerScheme, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-CKinOhyx.mjs";
+import { a as s402ServerScheme, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-M-z-UV0c.mjs";
 
 //#region src/test-utils.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s402",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for six payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "agent-payments"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "sideEffects": false,
   "files": [
@@ -68,19 +68,26 @@
       },
       "default": "./dist/http.mjs"
     },
-    "./compat": {
+    "./compat/x402": {
       "import": {
-        "types": "./dist/compat.d.mts",
-        "default": "./dist/compat.mjs"
+        "types": "./dist/compat/x402.d.mts",
+        "default": "./dist/compat/x402.mjs"
       },
-      "default": "./dist/compat.mjs"
+      "default": "./dist/compat/x402.mjs"
     },
-    "./compat-mpp": {
+    "./compat/mpp": {
       "import": {
-        "types": "./dist/compat-mpp.d.mts",
-        "default": "./dist/compat-mpp.mjs"
+        "types": "./dist/compat/mpp.d.mts",
+        "default": "./dist/compat/mpp.mjs"
       },
-      "default": "./dist/compat-mpp.mjs"
+      "default": "./dist/compat/mpp.mjs"
+    },
+    "./compat/l402": {
+      "import": {
+        "types": "./dist/compat/l402.d.mts",
+        "default": "./dist/compat/l402.mjs"
+      },
+      "default": "./dist/compat/l402.mjs"
     },
     "./errors": {
       "import": {