@peac/adapter-x402 0.12.0 → 0.12.2

package/dist/types.js

@@ -2,24 +2,14 @@
 /**
  * x402 Offer/Receipt extension types
  *
- * Models the x402 offer/receipt flow:
- * - SignedOffer: EIP-712 or JWS signed payment terms
- * - SignedReceipt: Settlement proof binding offer to on-chain transaction
- * - AcceptEntry: Terms an offer can match against
- * - acceptIndex: Unsigned envelope field (hint only, not binding)
- *
- * Key design choices:
- * - validUntil: epoch seconds in signed payload
- * - version: in signed payload
- * - acceptIndex: unsigned envelope field (outside signature)
- * - metadata: deferred to v2
- *
- * NOTE: This adapter targets the x402 Offer/Receipt EXTENSION,
- * NOT the baseline x402 header flow. The profile identifier reflects this:
- * `peac-x402-offer-receipt/0.1` (extension) vs `peac-x402/0.1` (baseline, reserved).
+ * Public API types for the x402 adapter. Uses raw wire types (Layer A)
+ * and normalized types (Layer B) from their respective modules.
+ *
+ * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_AMOUNT_LENGTH = exports.MAX_TOTAL_ACCEPTS_BYTES = exports.MAX_ACCEPT_ENTRIES = exports.X402_OFFER_RECEIPT_PROFILE = void 0;
+exports.defaultAddressComparator = defaultAddressComparator;
 // ---------------------------------------------------------------------------
 // Profile Identifier
 // ---------------------------------------------------------------------------
@@ -31,7 +21,7 @@ exports.MAX_AMOUNT_LENGTH = exports.MAX_TOTAL_ACCEPTS_BYTES = exports.MAX_ACCEPT
  *
  * `peac-x402/0.1` is RESERVED for future baseline header flow support.
  */
-exports.X402_OFFER_RECEIPT_PROFILE = 'peac-x402-offer-receipt/0.1';
+exports.X402_OFFER_RECEIPT_PROFILE = 'peac-x402-offer-receipt/0.2';
 // ---------------------------------------------------------------------------
 // DoS Protection Limits
 // ---------------------------------------------------------------------------
@@ -55,4 +45,16 @@ exports.MAX_TOTAL_ACCEPTS_BYTES = 256 * 1024; // 256 KiB
  * 78 chars supports uint256 (Ethereum's max) without truncation.
  */
 exports.MAX_AMOUNT_LENGTH = 78;
+/**
+ * Default network-aware address comparator
+ *
+ * EVM networks (eip155:*): case-insensitive (EIP-55 checksums are cosmetic encoding).
+ * All other networks: exact string comparison (fail-closed for unknown formats).
+ */
+function defaultAddressComparator(a, b, network) {
+    if (network.startsWith('eip155:')) {
+        return a.toLowerCase() === b.toLowerCase();
+    }
+    return a === b;
+}
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAOH,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;GAOG;AACU,QAAA,0BAA0B,GAAG,6BAAsC,CAAC;AAEjF,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,GAAG,CAAC;AAEtC;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,UAAU;AAE7D;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,EAAE,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA4bH,4DAKC;AA3aD,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;GAOG;AACU,QAAA,0BAA0B,GAAG,6BAAsC,CAAC;AAEjF,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,GAAG,CAAC;AAEtC;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,UAAU;AAE7D;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,EAAE,CAAC;AAyXpC;;;;;GAKG;AACH,SAAgB,wBAAwB,CAAC,CAAS,EAAE,CAAS,EAAE,OAAe;IAC5E,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7C,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}

package/dist/verify.d.ts

@@ -1,63 +1,77 @@
 /**
  * x402 Offer/Receipt verification
  *
- * Verification rules (PEAC-first):
- * 1. Structural validation (format, required fields)
- * 2. DoS guards (accepts array limits)
- * 3. Amount validation (non-negative integer string)
- * 4. Network validation (CAIP-2 format)
- * 5. Expiry check (validUntil vs current time)
- * 6. Version check (supported versions)
- * 7. Signature format validation (EIP-712 or JWS structure)
- * 8. Term-matching (offer payload vs accept entry)
+ * Verification layers:
+ * 1. Wire validation (verifyWire): structural shape, format tags, required fields
+ * 2. Offer term verification (verifyOfferTerms): version, expiry, amount, network, term-matching
+ * 3. Receipt semantic verification (verifyReceiptSemantics): required fields, recency
+ * 4. Offer-receipt consistency (verifyOfferReceiptConsistency): resourceUrl, network, freshness
+ * 5. Opt-in crypto + authorization: CryptoVerifier and SignerAuthorizer interfaces (types only)
  *
- * IMPORTANT: Cryptographic signature verification (EIP-712 recovery, JWS validation)
- * is NOT performed here. That requires a crypto provider (viem, ethers, etc.)
- * and should be done by the caller before passing artifacts to this adapter.
+ * Each layer is separately callable and separately reportable.
  *
- * `valid: true` does NOT imply cryptographic signature validity unless a
- * CryptoVerifier is supplied and `verification.cryptographic.verified` is true.
+ * IMPORTANT: Cryptographic signature verification is NOT performed here.
+ * That requires injecting a CryptoVerifier implementation.
+ */
+import type { RawSignedOffer, RawSignedReceipt } from './raw.js';
+import type { NormalizedOfferPayload, NormalizedReceiptPayload } from './normalize.js';
+import type { AcceptEntry, OfferVerification, ReceiptVerification, ConsistencyVerification, ConsistencyOptions, WireVerification, X402AdapterConfig, AddressComparator } from './types.js';
+/**
+ * Validate raw wire structure of a signed offer
  *
- * The focus of this module is TERM-MATCHING: ensuring the signed payload
- * fields match the declared accept terms. This is the binding mechanism
- * that makes unsigned acceptIndex irrelevant for security.
+ * Checks discriminated union shape, format tag, required fields.
+ * No semantic interpretation, no payload extraction.
  */
-import type { OfferPayload, SignedOffer, SignedReceipt, AcceptEntry, OfferVerification, ReceiptVerification, X402AdapterConfig } from './types.js';
+export declare function verifyOfferWire(offer: RawSignedOffer): WireVerification;
+/**
+ * Validate raw wire structure of a signed receipt
+ */
+export declare function verifyReceiptWire(receipt: RawSignedReceipt): WireVerification;
 /**
  * Verify an x402 signed offer against accept terms
  *
- * This performs structural validation, expiry/version checks, and
- * term-matching against the provided accept entries. It does NOT verify
- * the cryptographic signature (that is the caller's responsibility).
+ * Extracts and normalizes payload, then performs:
+ * - Version check
+ * - Expiry check (with offerExpiryPolicy)
+ * - Amount/network validation
+ * - Term-matching against accept entries
  *
  * @param offer - The signed offer to verify
  * @param accepts - The list of acceptable payment terms
- * @param acceptIndex - Optional hint index (unsigned, treat as advisory)
  * @param config - Optional adapter configuration
  * @returns Verification result with matched accept entry or errors
  */
-export declare function verifyOffer(offer: SignedOffer, accepts: AcceptEntry[], acceptIndex?: number, config?: X402AdapterConfig): OfferVerification;
+export declare function verifyOffer(offer: RawSignedOffer, accepts: AcceptEntry[], config?: X402AdapterConfig): OfferVerification;
 /**
  * Verify an x402 signed receipt
  *
- * Performs structural validation on the receipt. Does NOT verify
- * the cryptographic signature.
- *
- * @param receipt - The signed receipt to verify
- * @param config - Optional adapter configuration
- * @returns Verification result with errors if invalid
+ * Extracts and normalizes payload, then performs:
+ * - Required field validation (version, network, resourceUrl, payer, issuedAt)
+ * - Version check
+ * - Payer format check
+ * - issuedAt recency check
+ * - Network validation
  */
-export declare function verifyReceipt(receipt: SignedReceipt, config?: X402AdapterConfig): ReceiptVerification;
+export declare function verifyReceipt(receipt: RawSignedReceipt, config?: X402AdapterConfig): ReceiptVerification;
 /**
- * Match offer payload fields against a single accept entry
+ * Verify consistency between an offer and a receipt
  *
- * Compares: network, asset, payTo, amount, scheme, settlement
- * All present fields must match exactly. Amount comparison is string-based
- * (minor units) to avoid floating-point issues.
+ * Checks:
+ * - resourceUrl must match (exact string comparison)
+ * - network must match
+ * - issuedAt freshness relative to offer validity window
+ * - payer must match one of payerCandidates (if provided, network-aware)
+ */
+export declare function verifyOfferReceiptConsistency(offerPayload: NormalizedOfferPayload, receiptPayload: NormalizedReceiptPayload, config?: X402AdapterConfig, options?: ConsistencyOptions): ConsistencyVerification;
+/**
+ * Match normalized offer payload fields against a single accept entry
  *
+ * Compares: network, asset, payTo, amount, scheme
+ * All fields must match. Amount comparison is string-based.
+ * payTo comparison uses the address comparator (network-aware).
  * @returns Array of mismatched field names (empty = match)
  */
-export declare function matchAcceptTerms(payload: OfferPayload, accept: AcceptEntry): string[];
+export declare function matchAcceptTerms(payload: NormalizedOfferPayload, accept: AcceptEntry, addressComparator?: AddressComparator): string[];
 /**
  * Select the matching accept entry from the list
  *
@@ -66,13 +80,8 @@ export declare function matchAcceptTerms(payload: OfferPayload, accept: AcceptEn
  * - If absent: scan all entries for a unique match
  * - If multiple matches: fail closed (ambiguous)
  * - If no matches: fail closed
- *
- * @param payload - Offer payload to match
- * @param accepts - List of accept entries
- * @param acceptIndex - Optional hint (unsigned, untrusted)
- * @returns The matched entry and its index, or throws X402Error
  */
-export declare function selectAccept(payload: OfferPayload, accepts: AcceptEntry[], acceptIndex?: number): {
+export declare function selectAccept(payload: NormalizedOfferPayload, accepts: AcceptEntry[], acceptIndex?: number, addressComparator?: AddressComparator): {
     entry: AcceptEntry;
     index: number;
     usedHint: boolean;

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EAEnB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AA+PpB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,WAAW,EAAE,EACtB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,iBAAiB,GACzB,iBAAiB,CAuInB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EACtB,MAAM,CAAC,EAAE,iBAAiB,GACzB,mBAAmB,CAgDrB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAwBrF;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,WAAW,EAAE,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CA4D1D"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EACV,cAAc,EAEd,gBAAgB,EAIjB,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAEvF,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAEhB,iBAAiB,EAEjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAsMpB;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAgEvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CA8C7E;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,CAAC,EAAE,iBAAiB,GACzB,iBAAiB,CA8KnB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,mBAAmB,CAsFrB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,sBAAsB,EACpC,cAAc,EAAE,wBAAwB,EACxC,MAAM,CAAC,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,uBAAuB,CAqDzB;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,WAAW,EACnB,iBAAiB,GAAE,iBAA4C,GAC9D,MAAM,EAAE,CAsBV;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,WAAW,EAAE,EACtB,WAAW,CAAC,EAAE,MAAM,EACpB,iBAAiB,GAAE,iBAA4C,GAC9D;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAyD1D"}