@peac/adapter-x402 0.12.0-preview.2 → 0.12.1

package/dist/normalize.d.ts

@@ -0,0 +1,97 @@
+/**
+ * x402 semantic normalization (Layer B)
+ *
+ * Converts EIP-712 placeholder values into semantic absence.
+ * This layer exists because EIP-712 requires fixed schemas, so unused
+ * values are represented as `0` (for numbers) and `""` (for strings).
+ *
+ * Normalization rules:
+ * - `validUntil === 0` -> `undefined` (EIP-712 "no expiry" placeholder)
+ * - `transaction === ""` -> `undefined` (EIP-712 "no transaction" placeholder)
+ * - All other fields pass through unchanged
+ *
+ * IMPORTANT: Raw artifacts are NEVER mutated. Normalization produces
+ * new objects; the originals are preserved in proofs.
+ */
+import type { RawOfferPayload, RawReceiptPayload } from './raw.js';
+/**
+ * Normalized offer payload (semantically clean)
+ *
+ * Same fields as RawOfferPayload, but with EIP-712 placeholders
+ * converted to semantic absence (`undefined`).
+ */
+export interface NormalizedOfferPayload {
+    /** Schema version */
+    version: number;
+    /** Resource URL the offer is for */
+    resourceUrl: string;
+    /** Settlement scheme */
+    scheme: string;
+    /** CAIP-2 network identifier */
+    network: string;
+    /** Payment asset identifier */
+    asset: string;
+    /** Payment recipient address */
+    payTo: string;
+    /** Payment amount in minor units */
+    amount: string;
+    /**
+     * Offer expiry as epoch seconds
+     *
+     * `undefined` means "no expiry" (was `0` in EIP-712 encoding, or absent).
+     * Verification layer enforces expiry policy separately.
+     */
+    validUntil?: number;
+}
+/**
+ * Normalized receipt payload (semantically clean)
+ *
+ * Same fields as RawReceiptPayload, but with EIP-712 placeholders
+ * converted to semantic absence (`undefined`).
+ */
+export interface NormalizedReceiptPayload {
+    /** Schema version */
+    version: number;
+    /** CAIP-2 network identifier */
+    network: string;
+    /** Resource URL the receipt is for */
+    resourceUrl: string;
+    /** Payer address */
+    payer: string;
+    /** Receipt issuance timestamp (epoch seconds) */
+    issuedAt: number;
+    /**
+     * On-chain transaction reference
+     *
+     * `undefined` means "no transaction reference" (was `""` in EIP-712, or absent).
+     * Privacy-minimal: transaction is optional enrichable evidence, not receipt identity.
+     */
+    transaction?: string;
+}
+/**
+ * Normalize an offer payload from raw wire to semantic representation
+ *
+ * Applies EIP-712 placeholder rules:
+ * - `validUntil === 0` -> `undefined` (no expiry)
+ *
+ * `validUntil` is always present in the raw payload (required per upstream TS).
+ * All other fields pass through unchanged.
+ *
+ * @param raw - The raw offer payload (Layer A2)
+ * @returns Normalized offer payload (Layer B)
+ */
+export declare function normalizeOfferPayload(raw: RawOfferPayload): NormalizedOfferPayload;
+/**
+ * Normalize a receipt payload from raw wire to semantic representation
+ *
+ * Applies EIP-712 placeholder rules:
+ * - `transaction === ""` -> `undefined` (no transaction)
+ *
+ * `transaction` is always present in the raw payload (required per upstream TS).
+ * All other fields pass through unchanged.
+ *
+ * @param raw - The raw receipt payload (Layer A2)
+ * @returns Normalized receipt payload (Layer B)
+ */
+export declare function normalizeReceiptPayload(raw: RawReceiptPayload): NormalizedReceiptPayload;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAMnE;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,GAAG,sBAAsB,CAclF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,iBAAiB,GAAG,wBAAwB,CAYxF"}

package/dist/normalize.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * x402 semantic normalization (Layer B)
+ *
+ * Converts EIP-712 placeholder values into semantic absence.
+ * This layer exists because EIP-712 requires fixed schemas, so unused
+ * values are represented as `0` (for numbers) and `""` (for strings).
+ *
+ * Normalization rules:
+ * - `validUntil === 0` -> `undefined` (EIP-712 "no expiry" placeholder)
+ * - `transaction === ""` -> `undefined` (EIP-712 "no transaction" placeholder)
+ * - All other fields pass through unchanged
+ *
+ * IMPORTANT: Raw artifacts are NEVER mutated. Normalization produces
+ * new objects; the originals are preserved in proofs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOfferPayload = normalizeOfferPayload;
+exports.normalizeReceiptPayload = normalizeReceiptPayload;
+// ---------------------------------------------------------------------------
+// Normalization Functions
+// ---------------------------------------------------------------------------
+/**
+ * Normalize an offer payload from raw wire to semantic representation
+ *
+ * Applies EIP-712 placeholder rules:
+ * - `validUntil === 0` -> `undefined` (no expiry)
+ *
+ * `validUntil` is always present in the raw payload (required per upstream TS).
+ * All other fields pass through unchanged.
+ *
+ * @param raw - The raw offer payload (Layer A2)
+ * @returns Normalized offer payload (Layer B)
+ */
+function normalizeOfferPayload(raw) {
+    return {
+        version: raw.version,
+        resourceUrl: raw.resourceUrl,
+        scheme: raw.scheme,
+        network: raw.network,
+        asset: raw.asset,
+        payTo: raw.payTo,
+        amount: raw.amount,
+        // EIP-712 placeholder: 0 means "no expiry"
+        ...(raw.validUntil !== 0 && {
+            validUntil: raw.validUntil,
+        }),
+    };
+}
+/**
+ * Normalize a receipt payload from raw wire to semantic representation
+ *
+ * Applies EIP-712 placeholder rules:
+ * - `transaction === ""` -> `undefined` (no transaction)
+ *
+ * `transaction` is always present in the raw payload (required per upstream TS).
+ * All other fields pass through unchanged.
+ *
+ * @param raw - The raw receipt payload (Layer A2)
+ * @returns Normalized receipt payload (Layer B)
+ */
+function normalizeReceiptPayload(raw) {
+    return {
+        version: raw.version,
+        network: raw.network,
+        resourceUrl: raw.resourceUrl,
+        payer: raw.payer,
+        issuedAt: raw.issuedAt,
+        // EIP-712 placeholder: "" means "no transaction"
+        ...(raw.transaction !== '' && {
+            transaction: raw.transaction,
+        }),
+    };
+}
+//# sourceMappingURL=normalize.js.map

package/dist/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAgFH,sDAcC;AAcD,0DAYC;AAxDD,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,SAAgB,qBAAqB,CAAC,GAAoB;IACxD,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,2CAA2C;QAC3C,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,CAAC,IAAI;YAC1B,UAAU,EAAE,GAAG,CAAC,UAAU;SAC3B,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,uBAAuB,CAAC,GAAsB;IAC5D,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,iDAAiD;QACjD,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,EAAE,IAAI;YAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;SAC7B,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/raw.d.ts

@@ -0,0 +1,246 @@
+/**
+ * x402 raw wire types and extraction (Layer A)
+ *
+ * Exact mirror of upstream coinbase/x402 TypeScript types and field shapes
+ * after PR #935 (Offer/Receipt Extension) merged at commit f2bbb5c.
+ *
+ * This layer exists to:
+ * 1. Match upstream encoded wire shapes exactly (no renames, no approximations)
+ * 2. Provide extraction helpers for both JWS and EIP-712 formats
+ * 3. Serve as the single source of truth for wire-level types
+ *
+ * Upstream TypeScript keeps `validUntil` and `transaction` as always-present
+ * fields because EIP-712 requires fixed schemas. Unused values are encoded as
+ * `0` (validUntil) and `""` (transaction). This layer preserves that encoding;
+ * semantic normalization to `undefined` happens in Layer B (normalize.ts).
+ *
+ * IMPORTANT: Types in this file MUST match upstream exactly.
+ * Do NOT rename fields, add PEAC-specific fields, or change types.
+ */
+/**
+ * Upstream extension key for offer/receipt extension
+ *
+ * Matches upstream `OFFER_RECEIPT = "offer-receipt"`.
+ * Used in `extensions["offer-receipt"].info`.
+ */
+export declare const OFFER_RECEIPT: "offer-receipt";
+/**
+ * Exact upstream x402 offer payload (encoded, Layer A2)
+ *
+ * Field names and types match coinbase/x402 PR #935 TS interface exactly.
+ * All fields are always present in the encoded payload.
+ * EIP-712 uses `0` for unused `validUntil` (encoding placeholder, not semantic absence).
+ * Conversion to semantic optionality happens exclusively in Layer B (normalize.ts).
+ */
+export interface RawOfferPayload {
+    /** Schema version (upstream: number, not string) */
+    version: number;
+    /** Resource URL the offer is for (required per upstream) */
+    resourceUrl: string;
+    /** Settlement scheme (required per upstream) */
+    scheme: string;
+    /** CAIP-2 network identifier (e.g., "eip155:8453") */
+    network: string;
+    /** Payment asset identifier (e.g., "USDC") */
+    asset: string;
+    /** Payment recipient address */
+    payTo: string;
+    /** Payment amount in minor units */
+    amount: string;
+    /**
+     * Offer expiry as epoch seconds
+     *
+     * Always present in the encoded payload per upstream TS interface.
+     * EIP-712 encodes unused values as `0` (fixed schema requirement).
+     * Layer B (normalize.ts) converts `0` to `undefined` (semantic absence).
+     */
+    validUntil: number;
+}
+/**
+ * Exact upstream x402 receipt payload (encoded, Layer A2)
+ *
+ * Field names and types match coinbase/x402 PR #935 TS interface exactly.
+ * All fields are always present in the encoded payload.
+ * EIP-712 uses `""` for unused `transaction` (encoding placeholder, not semantic absence).
+ * Conversion to semantic optionality happens exclusively in Layer B (normalize.ts).
+ *
+ * Privacy-minimal by design: receipts carry service-delivery proof, not payment details.
+ */
+export interface RawReceiptPayload {
+    /** Schema version (upstream: number) */
+    version: number;
+    /** CAIP-2 network identifier */
+    network: string;
+    /** Resource URL the receipt is for */
+    resourceUrl: string;
+    /** Payer address */
+    payer: string;
+    /** Receipt issuance timestamp (epoch seconds) */
+    issuedAt: number;
+    /**
+     * On-chain transaction reference
+     *
+     * Always present in the encoded payload per upstream TS interface.
+     * EIP-712 encodes unused values as `""` (fixed schema requirement).
+     * Layer B (normalize.ts) converts `""` to `undefined` (semantic absence).
+     */
+    transaction: string;
+}
+/**
+ * JWS-signed offer (compact serialization)
+ *
+ * For JWS format, the payload is encoded inside the compact JWS string.
+ * There is no separate `payload` field. The `signature` field contains
+ * the full compact JWS (header.payload.signature).
+ */
+export interface RawJWSSignedOffer {
+    format: 'jws';
+    /** Compact JWS containing the offer payload (header.payload.signature) */
+    signature: string;
+    /** Index into accepts[] that this offer targets (per-offer, not top-level) */
+    acceptIndex?: number;
+}
+/**
+ * EIP-712 signed offer
+ *
+ * For EIP-712 format, the payload is a separate field alongside
+ * the hex-encoded ECDSA signature.
+ */
+export interface RawEIP712SignedOffer {
+    format: 'eip712';
+    /** The signed offer payload */
+    payload: RawOfferPayload;
+    /** Hex-encoded ECDSA signature */
+    signature: string;
+    /** Index into accepts[] that this offer targets (per-offer, not top-level) */
+    acceptIndex?: number;
+}
+/** Discriminated union of signed offer formats */
+export type RawSignedOffer = RawJWSSignedOffer | RawEIP712SignedOffer;
+/**
+ * JWS-signed receipt (compact serialization)
+ *
+ * Same pattern as JWS offers: payload is inside the compact JWS string.
+ */
+export interface RawJWSSignedReceipt {
+    format: 'jws';
+    /** Compact JWS containing the receipt payload */
+    signature: string;
+}
+/**
+ * EIP-712 signed receipt
+ */
+export interface RawEIP712SignedReceipt {
+    format: 'eip712';
+    /** The signed receipt payload */
+    payload: RawReceiptPayload;
+    /** Hex-encoded ECDSA signature */
+    signature: string;
+}
+/** Discriminated union of signed receipt formats */
+export type RawSignedReceipt = RawJWSSignedReceipt | RawEIP712SignedReceipt;
+/**
+ * Upstream x402 extension info structure
+ *
+ * In upstream, the offer/receipt data lives under:
+ * `extensions["offer-receipt"].info`
+ */
+export interface RawX402ExtensionInfo {
+    /** Array of signed offers */
+    offers: RawSignedOffer[];
+    /** Optional signed receipt */
+    receipt?: RawSignedReceipt;
+}
+/**
+ * Default maximum compact JWS byte length (64 KB)
+ *
+ * Enforced BEFORE base64url decoding to prevent memory amplification.
+ */
+export declare const MAX_COMPACT_JWS_BYTES: number;
+/**
+ * Parsed compact JWS components
+ *
+ * The raw `compact` string is the signed artifact and MUST be preserved as-is.
+ * These parsed components are for extraction only; never reconstruct from parts.
+ */
+export interface ParsedCompactJWS {
+    /** Decoded JOSE header */
+    header: Record<string, unknown>;
+    /** Decoded payload (guaranteed to be a plain object) */
+    payload: Record<string, unknown>;
+    /** Raw signature segment (base64url-encoded) */
+    signatureSegment: string;
+}
+/**
+ * Parse a compact JWS string with hardened validation
+ *
+ * Contract:
+ * 1. Exactly 3 segments (split on `.`)
+ * 2. No padding characters (`=`) in any segment
+ * 3. Size limit enforced BEFORE decoding
+ * 4. Payload MUST be a plain JSON object (not array, primitive, or null)
+ * 5. Never reconstruct: the compact JWS is the signed artifact
+ * 6. Fail-closed on any anomaly
+ *
+ * @param compact - The compact JWS string
+ * @param maxBytes - Maximum byte length (default: MAX_COMPACT_JWS_BYTES)
+ * @returns Parsed components
+ * @throws X402Error with specific error code on any parsing failure
+ */
+export declare function parseCompactJWS(compact: string, maxBytes?: number): ParsedCompactJWS;
+/**
+ * Extract offer payload from a signed offer
+ *
+ * For EIP-712: returns the `payload` field directly.
+ * For JWS: decodes the compact JWS and returns the decoded payload.
+ *
+ * @param offer - The signed offer (discriminated union)
+ * @param maxJwsBytes - Maximum JWS byte length for JWS format
+ * @returns The raw offer payload
+ * @throws X402Error if extraction fails
+ */
+export declare function extractOfferPayload(offer: RawSignedOffer, maxJwsBytes?: number): RawOfferPayload;
+/**
+ * Extract receipt payload from a signed receipt
+ *
+ * For EIP-712: returns the `payload` field directly.
+ * For JWS: decodes the compact JWS and returns the decoded payload.
+ *
+ * @param receipt - The signed receipt (discriminated union)
+ * @param maxJwsBytes - Maximum JWS byte length for JWS format
+ * @returns The raw receipt payload
+ * @throws X402Error if extraction fails
+ */
+export declare function extractReceiptPayload(receipt: RawSignedReceipt, maxJwsBytes?: number): RawReceiptPayload;
+/**
+ * Extract x402 extension info from an upstream response body
+ *
+ * Equivalent to upstream's `extractOffersFromPaymentRequired()` but operates
+ * on the raw response body rather than the upstream `PaymentRequired` type.
+ * Looks for `extensions["offer-receipt"].info` in the body.
+ *
+ * This is the entry point for converting raw upstream wire data into
+ * PEAC's `X402OfferReceiptChallenge` convenience type.
+ *
+ * @param body - The upstream response body (unknown shape)
+ * @returns The extension info, or null if absent/malformed
+ */
+export declare function extractExtensionInfo(body: unknown): RawX402ExtensionInfo | null;
+/**
+ * Standard x402 response header names for payment receipts
+ *
+ * Upstream uses `X-PAYMENT-RESPONSE` (primary) and `PAYMENT-RESPONSE` (alias).
+ */
+export declare const X402_RECEIPT_HEADERS: readonly ["x-payment-response", "payment-response"];
+/**
+ * Extract signed receipt from x402 settlement response headers
+ *
+ * Equivalent to upstream's `extractReceiptFromResponse()` but operates
+ * on raw headers rather than a `Response` object. Upstream sends the
+ * signed receipt as JSON in `X-PAYMENT-RESPONSE` or `PAYMENT-RESPONSE`.
+ *
+ * @param headers - Response headers (case-insensitive lookup)
+ * @returns The signed receipt, or null if absent/malformed
+ */
+export declare function extractReceiptFromHeaders(headers: Record<string, string | string[] | undefined>): RawSignedReceipt | null;
+//# sourceMappingURL=raw.d.ts.map

package/dist/raw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../src/raw.ts"],"names":[],"mappings":"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"}

package/dist/raw.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * x402 raw wire types and extraction (Layer A)
+ *
+ * Exact mirror of upstream coinbase/x402 TypeScript types and field shapes
+ * after PR #935 (Offer/Receipt Extension) merged at commit f2bbb5c.
+ *
+ * This layer exists to:
+ * 1. Match upstream encoded wire shapes exactly (no renames, no approximations)
+ * 2. Provide extraction helpers for both JWS and EIP-712 formats
+ * 3. Serve as the single source of truth for wire-level types
+ *
+ * Upstream TypeScript keeps `validUntil` and `transaction` as always-present
+ * fields because EIP-712 requires fixed schemas. Unused values are encoded as
+ * `0` (validUntil) and `""` (transaction). This layer preserves that encoding;
+ * semantic normalization to `undefined` happens in Layer B (normalize.ts).
+ *
+ * IMPORTANT: Types in this file MUST match upstream exactly.
+ * Do NOT rename fields, add PEAC-specific fields, or change types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402_RECEIPT_HEADERS = exports.MAX_COMPACT_JWS_BYTES = exports.OFFER_RECEIPT = void 0;
+exports.parseCompactJWS = parseCompactJWS;
+exports.extractOfferPayload = extractOfferPayload;
+exports.extractReceiptPayload = extractReceiptPayload;
+exports.extractExtensionInfo = extractExtensionInfo;
+exports.extractReceiptFromHeaders = extractReceiptFromHeaders;
+const crypto_1 = require("@peac/crypto");
+const errors_js_1 = require("./errors.js");
+// ---------------------------------------------------------------------------
+// Upstream Extension Constant
+// ---------------------------------------------------------------------------
+/**
+ * Upstream extension key for offer/receipt extension
+ *
+ * Matches upstream `OFFER_RECEIPT = "offer-receipt"`.
+ * Used in `extensions["offer-receipt"].info`.
+ */
+exports.OFFER_RECEIPT = 'offer-receipt';
+// ---------------------------------------------------------------------------
+// JWS Parsing Contract (Hardened)
+// ---------------------------------------------------------------------------
+/**
+ * Default maximum compact JWS byte length (64 KB)
+ *
+ * Enforced BEFORE base64url decoding to prevent memory amplification.
+ */
+exports.MAX_COMPACT_JWS_BYTES = 64 * 1024;
+/**
+ * Parse a compact JWS string with hardened validation
+ *
+ * Contract:
+ * 1. Exactly 3 segments (split on `.`)
+ * 2. No padding characters (`=`) in any segment
+ * 3. Size limit enforced BEFORE decoding
+ * 4. Payload MUST be a plain JSON object (not array, primitive, or null)
+ * 5. Never reconstruct: the compact JWS is the signed artifact
+ * 6. Fail-closed on any anomaly
+ *
+ * @param compact - The compact JWS string
+ * @param maxBytes - Maximum byte length (default: MAX_COMPACT_JWS_BYTES)
+ * @returns Parsed components
+ * @throws X402Error with specific error code on any parsing failure
+ */
+function parseCompactJWS(compact, maxBytes = exports.MAX_COMPACT_JWS_BYTES) {
+    // 1. Size limit before any processing
+    if (compact.length > maxBytes) {
+        throw new errors_js_1.X402Error('jws_too_large', `Compact JWS exceeds ${maxBytes} byte limit`);
+    }
+    // 2. Split into exactly 3 segments
+    const segments = compact.split('.');
+    if (segments.length !== 3) {
+        throw new errors_js_1.X402Error('jws_malformed', `Expected 3 segments in compact JWS, got ${segments.length}`);
+    }
+    // 3. Reject padded base64url (per RFC 7515, base64url has no padding)
+    for (const seg of segments) {
+        if (seg.includes('=')) {
+            throw new errors_js_1.X402Error('jws_padded_base64url', 'Padded base64url is not valid in compact JWS (RFC 7515)');
+        }
+    }
+    // 4. Decode header
+    let header;
+    try {
+        const headerJson = (0, crypto_1.base64urlDecodeString)(segments[0]);
+        header = JSON.parse(headerJson);
+    }
+    catch (e) {
+        throw new errors_js_1.X402Error('jws_malformed', `Failed to decode JWS header: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (typeof header !== 'object' || header === null || Array.isArray(header)) {
+        throw new errors_js_1.X402Error('jws_malformed', 'JWS header must be a JSON object');
+    }
+    // 5. Decode payload
+    let payload;
+    try {
+        const payloadJson = (0, crypto_1.base64urlDecodeString)(segments[1]);
+        payload = JSON.parse(payloadJson);
+    }
+    catch (e) {
+        throw new errors_js_1.X402Error('jws_malformed', `Failed to decode JWS payload: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // 6. Payload must be a plain object (not array, primitive, or null)
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        throw new errors_js_1.X402Error('jws_payload_not_object', 'JWS payload must be a JSON object');
+    }
+    return {
+        header: header,
+        payload: payload,
+        signatureSegment: segments[2],
+    };
+}
+// ---------------------------------------------------------------------------
+// Payload Extraction Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract offer payload from a signed offer
+ *
+ * For EIP-712: returns the `payload` field directly.
+ * For JWS: decodes the compact JWS and returns the decoded payload.
+ *
+ * @param offer - The signed offer (discriminated union)
+ * @param maxJwsBytes - Maximum JWS byte length for JWS format
+ * @returns The raw offer payload
+ * @throws X402Error if extraction fails
+ */
+function extractOfferPayload(offer, maxJwsBytes) {
+    if (offer.format === 'eip712') {
+        return offer.payload;
+    }
+    // JWS format: decode from compact serialization
+    const parsed = parseCompactJWS(offer.signature, maxJwsBytes);
+    return parsed.payload;
+}
+/**
+ * Extract receipt payload from a signed receipt
+ *
+ * For EIP-712: returns the `payload` field directly.
+ * For JWS: decodes the compact JWS and returns the decoded payload.
+ *
+ * @param receipt - The signed receipt (discriminated union)
+ * @param maxJwsBytes - Maximum JWS byte length for JWS format
+ * @returns The raw receipt payload
+ * @throws X402Error if extraction fails
+ */
+function extractReceiptPayload(receipt, maxJwsBytes) {
+    if (receipt.format === 'eip712') {
+        return receipt.payload;
+    }
+    // JWS format: decode from compact serialization
+    const parsed = parseCompactJWS(receipt.signature, maxJwsBytes);
+    return parsed.payload;
+}
+/**
+ * Extract x402 extension info from an upstream response body
+ *
+ * Equivalent to upstream's `extractOffersFromPaymentRequired()` but operates
+ * on the raw response body rather than the upstream `PaymentRequired` type.
+ * Looks for `extensions["offer-receipt"].info` in the body.
+ *
+ * This is the entry point for converting raw upstream wire data into
+ * PEAC's `X402OfferReceiptChallenge` convenience type.
+ *
+ * @param body - The upstream response body (unknown shape)
+ * @returns The extension info, or null if absent/malformed
+ */
+function extractExtensionInfo(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        return null;
+    }
+    const typed = body;
+    const extensions = typed.extensions;
+    if (typeof extensions !== 'object' || extensions === null || Array.isArray(extensions)) {
+        return null;
+    }
+    const ext = extensions;
+    const offerReceipt = ext['offer-receipt'];
+    if (typeof offerReceipt !== 'object' || offerReceipt === null || Array.isArray(offerReceipt)) {
+        return null;
+    }
+    const orTyped = offerReceipt;
+    const info = orTyped.info;
+    if (typeof info !== 'object' || info === null || Array.isArray(info)) {
+        return null;
+    }
+    const infoTyped = info;
+    // Validate offers is an array
+    if (!Array.isArray(infoTyped.offers)) {
+        return null;
+    }
+    return {
+        offers: infoTyped.offers,
+        ...(infoTyped.receipt !== undefined && {
+            receipt: infoTyped.receipt,
+        }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Upstream Message Shape Extractors
+// ---------------------------------------------------------------------------
+/**
+ * Standard x402 response header names for payment receipts
+ *
+ * Upstream uses `X-PAYMENT-RESPONSE` (primary) and `PAYMENT-RESPONSE` (alias).
+ */
+exports.X402_RECEIPT_HEADERS = ['x-payment-response', 'payment-response'];
+/**
+ * Extract signed receipt from x402 settlement response headers
+ *
+ * Equivalent to upstream's `extractReceiptFromResponse()` but operates
+ * on raw headers rather than a `Response` object. Upstream sends the
+ * signed receipt as JSON in `X-PAYMENT-RESPONSE` or `PAYMENT-RESPONSE`.
+ *
+ * @param headers - Response headers (case-insensitive lookup)
+ * @returns The signed receipt, or null if absent/malformed
+ */
+function extractReceiptFromHeaders(headers) {
+    // Case-insensitive header lookup
+    const lowerHeaders = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value !== undefined) {
+            lowerHeaders[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+        }
+    }
+    let raw;
+    for (const name of exports.X402_RECEIPT_HEADERS) {
+        raw = lowerHeaders[name];
+        if (raw)
+            break;
+    }
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        if (parsed.format !== 'eip712' && parsed.format !== 'jws')
+            return null;
+        if (typeof parsed.signature !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=raw.js.map