@peac/adapter-x402 0.12.0 → 0.12.2

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

package/dist/raw.js.map

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