@peac/adapter-x402 0.10.5

package/dist/types.d.ts

@@ -0,0 +1,392 @@
+/**
+ * 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).
+ */
+import type { JsonObject } from '@peac/kernel';
+export type { Result, AdapterError, AdapterErrorCode, JsonObject } from '@peac/adapter-core';
+/**
+ * Profile identifier for x402 Offer/Receipt extension records
+ *
+ * This profile targets the EXTENSION flow (signed offers + signed receipts),
+ * NOT the baseline x402 header flow (PAYMENT-REQUIRED, etc.).
+ *
+ * `peac-x402/0.1` is RESERVED for future baseline header flow support.
+ */
+export declare const X402_OFFER_RECEIPT_PROFILE: "peac-x402-offer-receipt/0.1";
+/**
+ * Maximum number of accept entries allowed (DoS protection)
+ *
+ * Prevents CPU exhaustion from maliciously large accepts arrays.
+ * O(n) scan becomes O(128) worst case.
+ */
+export declare const MAX_ACCEPT_ENTRIES = 128;
+/**
+ * Maximum total bytes for accepts array JSON (DoS protection)
+ *
+ * Prevents memory exhaustion from large accept payloads.
+ * 256 KiB is generous for legitimate use cases.
+ */
+export declare const MAX_TOTAL_ACCEPTS_BYTES: number;
+/**
+ * Maximum length for amount string (prevents arbitrary-precision DoS)
+ *
+ * 78 chars supports uint256 (Ethereum's max) without truncation.
+ */
+export declare const MAX_AMOUNT_LENGTH = 78;
+/**
+ * Signature format for x402 artifacts
+ *
+ * - eip712: EIP-712 typed structured data signature (Ethereum)
+ * - jws: JWS compact serialization (RFC 7515)
+ */
+export type SignatureFormat = 'eip712' | 'jws';
+/**
+ * x402 Offer payload (inside the signed envelope)
+ *
+ * These fields are cryptographically bound by the signature.
+ * Any modification invalidates the signature.
+ */
+export interface OfferPayload {
+    /** Schema version (in signed payload) */
+    version: string;
+    /** Offer expiry as epoch seconds (in signed payload) */
+    validUntil: number;
+    /** CAIP-2 network identifier (e.g., "eip155:8453") */
+    network: string;
+    /** Payment asset identifier (e.g., "USDC", "ETH") */
+    asset: string;
+    /** Payment amount in minor units */
+    amount: string;
+    /** Payment recipient address */
+    payTo: string;
+    /** Settlement scheme (e.g., "exact", "flexible") */
+    scheme?: string;
+    /** Settlement parameters (scheme-specific) */
+    settlement?: JsonObject;
+}
+/**
+ * x402 Signed Offer (envelope)
+ *
+ * The offer envelope contains:
+ * - payload: signed content (cryptographically bound)
+ * - signature: EIP-712 or JWS signature over the payload
+ * - format: which signature scheme was used
+ */
+export interface SignedOffer {
+    /** The signed payload */
+    payload: OfferPayload;
+    /** Signature over the payload */
+    signature: string;
+    /** Signature format */
+    format: SignatureFormat;
+}
+/**
+ * x402 Receipt payload (inside the signed envelope)
+ */
+export interface ReceiptPayload {
+    /** Schema version */
+    version: string;
+    /** CAIP-2 network identifier */
+    network: string;
+    /** On-chain transaction hash */
+    txHash: string;
+    /** Payment asset */
+    asset?: string;
+    /** Payment amount in minor units */
+    amount?: string;
+    /** Payment recipient */
+    payTo?: string;
+}
+/**
+ * x402 Signed Receipt (envelope)
+ */
+export interface SignedReceipt {
+    /** The signed payload */
+    payload: ReceiptPayload;
+    /** Signature over the payload */
+    signature: string;
+    /** Signature format */
+    format: SignatureFormat;
+}
+/**
+ * A single accept entry: the terms under which a facilitator accepts payment
+ *
+ * These are the terms that offers are matched against during verification.
+ * Term-matching is the binding mechanism (not acceptIndex).
+ */
+export interface AcceptEntry {
+    /** CAIP-2 network identifier */
+    network: string;
+    /** Payment asset */
+    asset: string;
+    /** Payment recipient address */
+    payTo: string;
+    /** Maximum amount in minor units */
+    amount: string;
+    /** Settlement scheme */
+    scheme?: string;
+    /** Settlement parameters */
+    settlement?: JsonObject;
+}
+/**
+ * x402 PaymentRequired response with offer/receipt extension
+ *
+ * This is the 402 response sent by the resource server.
+ * The extension data lives under extensions["offer-receipt"].
+ */
+export interface X402PaymentRequired {
+    /** List of acceptable payment terms */
+    accepts: AcceptEntry[];
+    /**
+     * Index into accepts[] that the offer targets.
+     *
+     * IMPORTANT: This field is OUTSIDE the signed payload (unsigned envelope).
+     * Verifiers MUST NOT rely on it as binding.
+     * Treat as advisory hint only; always verify via term-matching.
+     */
+    acceptIndex?: number;
+    /** Signed offer */
+    offer: SignedOffer;
+    /** Resource URL being accessed */
+    resourceUrl?: string;
+}
+/**
+ * x402 Settlement response with receipt extension
+ */
+export interface X402SettlementResponse {
+    /** Signed receipt proving settlement */
+    receipt: SignedReceipt;
+    /** Resource URL that was accessed */
+    resourceUrl?: string;
+    /** Reference back to the offer */
+    offerRef?: string;
+    /**
+     * Forward-compatibility: unknown extension fields from x402 evolution
+     *
+     * This allows the adapter to tolerate additions from upstream PRs
+     * (e.g., #1004 TXID, #1015 fee extensions) without breaking.
+     * Unknown fields are preserved in proofs but NOT copied to evidence.
+     */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Result of offer verification
+ */
+export interface OfferVerification {
+    /** Whether the offer is valid */
+    valid: boolean;
+    /** The matched accept entry (if valid) */
+    matchedAccept?: AcceptEntry;
+    /** Index of the matched accept entry */
+    matchedIndex?: number;
+    /** Whether acceptIndex was used as hint (vs full scan) */
+    usedHint: boolean;
+    /** Verification errors (if invalid) */
+    errors: VerificationError[];
+    /**
+     * Term-matching details (always populated for deterministic output)
+     *
+     * This makes mismatchDetected first-class in the verification output,
+     * rather than requiring callers to pass it externally.
+     *
+     * All fields are required booleans for predictable downstream processing.
+     */
+    termMatching: {
+        /** Method used: 'hint' (acceptIndex) or 'scan' (full array scan) */
+        method: 'hint' | 'scan';
+        /** Whether the acceptIndex hint was provided */
+        hintProvided: boolean;
+        /** Whether the hint pointed to a non-matching entry */
+        hintMismatchDetected: boolean;
+    };
+}
+/**
+ * Result of receipt verification
+ */
+export interface ReceiptVerification {
+    /** Whether the receipt is valid */
+    valid: boolean;
+    /** Verification errors (if invalid) */
+    errors: VerificationError[];
+}
+/**
+ * Structured verification error
+ */
+export interface VerificationError {
+    /** Error code (from X402ErrorCode) */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Field that caused the error */
+    field?: string;
+}
+/**
+ * Verification status metadata
+ *
+ * Records what verification was performed and how.
+ * CRITICAL: `valid: true` from verifyOffer/verifyReceipt does NOT imply
+ * cryptographic signature validity unless a crypto verifier was supplied.
+ */
+export interface VerificationStatus {
+    /** Structural validation always performed by this adapter */
+    structural: true;
+    /** Cryptographic signature verification status */
+    cryptographic: {
+        /** Whether crypto verification was performed */
+        verified: boolean;
+        /** Why crypto wasn't verified (if not verified) */
+        reason?: 'not_checked' | 'verifier_not_supplied' | 'verifier_failed';
+        /** Signature format */
+        format?: 'eip712' | 'jws';
+        /** Signer identity (if verified and available) */
+        signer?: string;
+    };
+    /** Term-matching verification status */
+    termMatching: {
+        /** Whether a matching accept entry was found */
+        matched: boolean;
+        /** Method used: 'hint' (acceptIndex) or 'scan' (full scan) */
+        method: 'hint' | 'scan';
+        /** Index of matched accept entry */
+        matchedIndex?: number;
+        /** Why term-matching wasn't performed (if matched is false and no verification was done) */
+        reason?: 'not_verified';
+    };
+}
+/**
+ * PEAC interaction record for an x402 Offer/Receipt extension flow
+ *
+ * This is the canonical record produced by mapping x402 proofs
+ * into the PEAC evidence layer.
+ *
+ * NOTE: This profile targets the x402 Offer/Receipt EXTENSION,
+ * NOT the baseline x402 header flow.
+ */
+export interface X402PeacRecord {
+    /** Record format version (extension profile, not baseline) */
+    version: typeof X402_OFFER_RECEIPT_PROFILE;
+    /** Raw x402 proofs (preserved for audit) */
+    proofs: {
+        x402: {
+            offer: SignedOffer;
+            receipt: SignedReceipt;
+        };
+    };
+    /** Normalized evidence fields (extracted from signed payloads) */
+    evidence: {
+        /** Offer expiry (epoch seconds, from signed payload) */
+        validUntil: number;
+        /** CAIP-2 network */
+        network: string;
+        /** Payment recipient (neutral naming; x402 calls this "payTo") */
+        payee: string;
+        /** Payment asset */
+        asset: string;
+        /** Payment amount in minor units */
+        amount: string;
+        /** On-chain transaction hash (from receipt) */
+        txHash: string;
+        /** Schema version (from offer) */
+        offerVersion: string;
+        /** Schema version (from receipt, if present) */
+        receiptVersion?: string;
+    };
+    /** Unsigned metadata and verification status */
+    hints: {
+        acceptIndex?: {
+            /** The acceptIndex value from the envelope */
+            value: number;
+            /** Always true -- acceptIndex is outside the signature */
+            untrusted: true;
+            /** True if acceptIndex pointed to a non-matching entry (when mismatchPolicy != 'fail') */
+            mismatchDetected?: boolean;
+        };
+        resourceUrl?: string;
+        /**
+         * Verification status metadata
+         *
+         * IMPORTANT: `valid: true` does NOT imply cryptographic signature validity
+         * unless verification.cryptographic.verified is true.
+         */
+        verification?: VerificationStatus;
+    };
+    /** RFC 8785 JCS + SHA-256 digest of this record */
+    digest?: string;
+    /** ISO 8601 timestamp of record creation */
+    createdAt: string;
+}
+/**
+ * Mismatch policy for acceptIndex hint verification
+ *
+ * Controls behavior when acceptIndex points to an entry that doesn't match
+ * the signed offer payload.
+ *
+ * - 'fail': Reject with accept_term_mismatch error (default, recommended)
+ * - 'warn_and_scan': Log warning, continue with scan, record in hints
+ * - 'ignore_and_scan': Skip hint check entirely, always scan
+ */
+export type MismatchPolicy = 'fail' | 'warn_and_scan' | 'ignore_and_scan';
+/**
+ * Adapter configuration
+ *
+ * This adapter implements the PaymentProofAdapter interface from @peac/adapter-core.
+ * See docs/specs/X402-PROFILE.md for the normative specification.
+ */
+export interface X402AdapterConfig {
+    /** Supported offer versions (default: ["1"]) */
+    supportedVersions?: string[];
+    /** Clock skew tolerance in seconds for validUntil (default: 60) */
+    clockSkewSeconds?: number;
+    /** Current time override for testing (epoch seconds) */
+    nowSeconds?: number;
+    /**
+     * How to handle acceptIndex mismatch (default: "fail")
+     *
+     * When "warn_and_scan" or "ignore_and_scan", the adapter will:
+     * 1. Record the mismatch in hints.acceptIndex.mismatchDetected
+     * 2. Continue verification via full scan
+     * 3. Succeed if scan finds a unique match
+     */
+    mismatchPolicy?: MismatchPolicy;
+    /**
+     * Maximum number of accept entries allowed (default: 128)
+     *
+     * DoS protection: prevents CPU exhaustion from large accepts arrays.
+     */
+    maxAcceptEntries?: number;
+    /**
+     * Maximum total bytes for accepts array JSON (default: 256 KiB)
+     *
+     * DoS protection: prevents memory exhaustion from large payloads.
+     * Note: This requires caller to pass raw JSON size if available.
+     */
+    maxTotalAcceptsBytes?: number;
+    /**
+     * Enable strict CAIP-2 network format validation (default: true)
+     *
+     * When enabled, validates network strings match CAIP-2 format (namespace:reference).
+     */
+    strictNetworkValidation?: boolean;
+    /**
+     * Enable strict amount validation (default: true)
+     *
+     * When enabled, validates amount is a non-negative integer string.
+     */
+    strictAmountValidation?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * 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).
+ */
+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;
+// ---------------------------------------------------------------------------
+// Profile Identifier
+// ---------------------------------------------------------------------------
+/**
+ * Profile identifier for x402 Offer/Receipt extension records
+ *
+ * This profile targets the EXTENSION flow (signed offers + signed receipts),
+ * NOT the baseline x402 header flow (PAYMENT-REQUIRED, etc.).
+ *
+ * `peac-x402/0.1` is RESERVED for future baseline header flow support.
+ */
+exports.X402_OFFER_RECEIPT_PROFILE = 'peac-x402-offer-receipt/0.1';
+// ---------------------------------------------------------------------------
+// DoS Protection Limits
+// ---------------------------------------------------------------------------
+/**
+ * Maximum number of accept entries allowed (DoS protection)
+ *
+ * Prevents CPU exhaustion from maliciously large accepts arrays.
+ * O(n) scan becomes O(128) worst case.
+ */
+exports.MAX_ACCEPT_ENTRIES = 128;
+/**
+ * Maximum total bytes for accepts array JSON (DoS protection)
+ *
+ * Prevents memory exhaustion from large accept payloads.
+ * 256 KiB is generous for legitimate use cases.
+ */
+exports.MAX_TOTAL_ACCEPTS_BYTES = 256 * 1024; // 256 KiB
+/**
+ * Maximum length for amount string (prevents arbitrary-precision DoS)
+ *
+ * 78 chars supports uint256 (Ethereum's max) without truncation.
+ */
+exports.MAX_AMOUNT_LENGTH = 78;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +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"}

package/dist/verify.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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)
+ *
+ * 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.
+ *
+ * `valid: true` does NOT imply cryptographic signature validity unless a
+ * CryptoVerifier is supplied and `verification.cryptographic.verified` is true.
+ *
+ * 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.
+ */
+import type { OfferPayload, SignedOffer, SignedReceipt, AcceptEntry, OfferVerification, ReceiptVerification, X402AdapterConfig } from './types.js';
+/**
+ * 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).
+ *
+ * @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;
+/**
+ * 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
+ */
+export declare function verifyReceipt(receipt: SignedReceipt, config?: X402AdapterConfig): ReceiptVerification;
+/**
+ * Match offer payload fields against a single accept entry
+ *
+ * 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.
+ *
+ * @returns Array of mismatched field names (empty = match)
+ */
+export declare function matchAcceptTerms(payload: OfferPayload, accept: AcceptEntry): string[];
+/**
+ * Select the matching accept entry from the list
+ *
+ * Selection logic:
+ * - If acceptIndex provided: bounds-check, then term-match that entry
+ * - 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): {
+    entry: AcceptEntry;
+    index: number;
+    usedHint: boolean;
+};
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +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"}