@peac/adapter-x402 0.10.5

package/README.md

@@ -0,0 +1,116 @@
+# @peac/adapter-x402
+
+x402 offer/receipt verification, term-matching, and PEAC record mapping.
+
+## Overview
+
+This package verifies x402 extension objects (offers and receipts) and maps
+them into canonical PEAC interaction records. It implements term-matching
+verification where `acceptIndex` is treated as an untrusted hint and the
+binding comes from matching signed payload fields against accept terms.
+
+## Install
+
+```bash
+pnpm add @peac/adapter-x402
+```
+
+## Usage
+
+### Verify an offer against accept terms
+
+```typescript
+import { verifyOffer } from '@peac/adapter-x402';
+
+const result = verifyOffer(signedOffer, acceptEntries, acceptIndex);
+
+if (result.valid) {
+  console.log('Matched accept entry:', result.matchedAccept);
+  console.log('Used hint:', result.usedHint);
+} else {
+  console.log('Verification failed:', result.errors);
+}
+```
+
+### Select accept entry with term-matching
+
+```typescript
+import { selectAccept } from '@peac/adapter-x402';
+
+// With hint (bounds-check + term-match)
+const match = selectAccept(offerPayload, accepts, acceptIndex);
+
+// Without hint (scan for unique match)
+const match = selectAccept(offerPayload, accepts);
+```
+
+### Map to PEAC record
+
+```typescript
+import { toPeacRecord } from '@peac/adapter-x402';
+
+const record = toPeacRecord(paymentRequired, settlementResponse);
+// record.proofs.x402.offer   -- raw offer preserved for audit
+// record.proofs.x402.receipt  -- raw receipt preserved for audit
+// record.evidence.txHash      -- from signed receipt payload
+// record.hints.acceptIndex    -- { value: 0, untrusted: true }
+```
+
+## acceptIndex: hint-only semantics
+
+In the x402 Offer/Receipt extension, `acceptIndex` is an unsigned envelope
+field outside the signed payload. Verifiers MUST NOT rely on it as a binding
+mechanism.
+
+This package treats `acceptIndex` as advisory:
+
+- If present: bounds-check, then term-match `accepts[acceptIndex]` against
+  the signed payload. Reject on mismatch.
+- If absent: scan all `accepts[]` entries for a unique match. If ambiguous
+  (multiple matches), reject.
+- If tampered: does not affect security because the binding comes from
+  comparing signed payload fields, not the unsigned index.
+
+## API
+
+### `verifyOffer(offer, accepts, acceptIndex?, config?)`
+
+Verify a signed offer against accept terms. Checks structure, expiry,
+version, signature format, and term-matching.
+
+### `verifyReceipt(receipt, config?)`
+
+Verify a signed receipt's structure and version.
+
+### `matchAcceptTerms(payload, accept)`
+
+Compare offer payload fields against a single accept entry. Returns an
+array of mismatched field names (empty means match).
+
+### `selectAccept(payload, accepts, acceptIndex?)`
+
+Select the matching accept entry. Throws `X402Error` on failure.
+
+### `toPeacRecord(paymentRequired, settlementResponse)`
+
+Map an x402 payment flow to a PEAC interaction record.
+
+## Error handling
+
+All verification functions return structured results with error arrays.
+The `selectAccept` and `toPeacRecord` functions throw `X402Error` with:
+
+- `code`: Machine-readable error code (lowercase snake_case)
+- `httpStatus`: Suggested HTTP status code
+- `field`: Optional field that caused the error
+- `details`: Optional structured details
+
+## License
+
+Apache-2.0
+
+---
+
+PEAC Protocol is an open source project stewarded by Originary and community contributors.
+
+[Docs](https://www.peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac) | [Originary](https://www.originary.xyz)

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * x402 adapter error codes and error class
+ *
+ * Error codes follow PEAC adapter convention: lowercase snake_case.
+ * These are adapter-level errors; kernel-level errors use E_* prefix.
+ */
+/**
+ * x402 adapter error codes
+ *
+ * Categories:
+ * - offer_*: Offer validation/verification errors
+ * - receipt_*: Receipt validation/verification errors
+ * - accept_*: Accept selection/matching errors
+ * - payload_*: Generic payload errors
+ * - amount_*: Amount validation errors
+ * - network_*: Network validation errors
+ */
+export type X402ErrorCode = 'offer_invalid_format' | 'offer_expired' | 'offer_version_unsupported' | 'offer_signature_invalid' | 'receipt_invalid_format' | 'receipt_signature_invalid' | 'receipt_version_unsupported' | 'accept_index_out_of_range' | 'accept_no_match' | 'accept_ambiguous' | 'accept_term_mismatch' | 'accept_too_many_entries' | 'payload_missing_field' | 'payload_tampered' | 'amount_invalid' | 'network_invalid';
+/**
+ * Custom error class for x402 adapter operations
+ *
+ * Provides structured error information with code, HTTP status,
+ * and optional field/details for debugging.
+ */
+export declare class X402Error extends Error {
+    readonly code: X402ErrorCode;
+    readonly httpStatus: number;
+    readonly field?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: X402ErrorCode, message: string, options?: {
+        field?: string;
+        details?: Record<string, unknown>;
+    });
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB,sBAAsB,GACtB,eAAe,GACf,2BAA2B,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,2BAA2B,GAC3B,6BAA6B,GAC7B,2BAA2B,GAC3B,iBAAiB,GACjB,kBAAkB,GAClB,sBAAsB,GACtB,yBAAyB,GACzB,uBAAuB,GACvB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,CAAC;AAwBtB;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE;IAUjE,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAUlC"}

package/dist/errors.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * x402 adapter error codes and error class
+ *
+ * Error codes follow PEAC adapter convention: lowercase snake_case.
+ * These are adapter-level errors; kernel-level errors use E_* prefix.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402Error = void 0;
+/**
+ * HTTP status mapping for error codes
+ */
+const ERROR_HTTP_STATUS = {
+    offer_invalid_format: 400,
+    offer_expired: 400,
+    offer_version_unsupported: 400,
+    offer_signature_invalid: 401,
+    receipt_invalid_format: 400,
+    receipt_signature_invalid: 401,
+    receipt_version_unsupported: 400,
+    accept_index_out_of_range: 400,
+    accept_no_match: 400,
+    accept_ambiguous: 400,
+    accept_term_mismatch: 400,
+    accept_too_many_entries: 400,
+    payload_missing_field: 400,
+    payload_tampered: 401,
+    amount_invalid: 400,
+    network_invalid: 400,
+};
+/**
+ * Custom error class for x402 adapter operations
+ *
+ * Provides structured error information with code, HTTP status,
+ * and optional field/details for debugging.
+ */
+class X402Error extends Error {
+    code;
+    httpStatus;
+    field;
+    details;
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'X402Error';
+        this.code = code;
+        this.httpStatus = ERROR_HTTP_STATUS[code] ?? 400;
+        this.field = options?.field;
+        this.details = options?.details;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            httpStatus: this.httpStatus,
+            ...(this.field !== undefined && { field: this.field }),
+            ...(this.details !== undefined && { details: this.details }),
+        };
+    }
+}
+exports.X402Error = X402Error;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AA+BH;;GAEG;AACH,MAAM,iBAAiB,GAAkC;IACvD,oBAAoB,EAAE,GAAG;IACzB,aAAa,EAAE,GAAG;IAClB,yBAAyB,EAAE,GAAG;IAC9B,uBAAuB,EAAE,GAAG;IAC5B,sBAAsB,EAAE,GAAG;IAC3B,yBAAyB,EAAE,GAAG;IAC9B,2BAA2B,EAAE,GAAG;IAChC,yBAAyB,EAAE,GAAG;IAC9B,eAAe,EAAE,GAAG;IACpB,gBAAgB,EAAE,GAAG;IACrB,oBAAoB,EAAE,GAAG;IACzB,uBAAuB,EAAE,GAAG;IAC5B,qBAAqB,EAAE,GAAG;IAC1B,gBAAgB,EAAE,GAAG;IACrB,cAAc,EAAE,GAAG;IACnB,eAAe,EAAE,GAAG;CACrB,CAAC;AAEF;;;;;GAKG;AACH,MAAa,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAgB;IACpB,UAAU,CAAS;IACnB,KAAK,CAAU;IACf,OAAO,CAA2B;IAE3C,YACE,IAAmB,EACnB,OAAe,EACf,OAA+D;QAE/D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;QACjD,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IAClC,CAAC;IAED,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YACtD,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;SAC7D,CAAC;IACJ,CAAC;CACF;AA7BD,8BA6BC"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @peac/adapter-x402
+ *
+ * x402 Offer/Receipt extension verification, term-matching, and PEAC record mapping.
+ *
+ * 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).
+ *
+ * Key capabilities:
+ * - Structural validation of x402 offers and receipts
+ * - Term-matching: verify signed payload against accept entries
+ * - Accept selection with acceptIndex as untrusted hint
+ * - Mapping to canonical PEAC interaction records
+ * - DoS protection: limits on accepts array size
+ * - Amount/network validation: CAIP-2 format, integer strings
+ *
+ * IMPORTANT: This package does NOT perform cryptographic signature verification
+ * (EIP-712 recovery, JWS validation). That is the caller's responsibility.
+ * `valid: true` does NOT imply cryptographic signature validity unless
+ * a CryptoVerifier is supplied and `verification.cryptographic.verified` is true.
+ *
+ * The focus is on term-matching and record mapping -- the verification
+ * layer that makes unsigned acceptIndex irrelevant for security.
+ *
+ * @packageDocumentation
+ */
+export type { SignatureFormat, OfferPayload, SignedOffer, ReceiptPayload, SignedReceipt, AcceptEntry, X402PaymentRequired, X402SettlementResponse, OfferVerification, ReceiptVerification, VerificationError, VerificationStatus, X402PeacRecord, X402AdapterConfig, MismatchPolicy, } from './types.js';
+export { X402_OFFER_RECEIPT_PROFILE, MAX_ACCEPT_ENTRIES, MAX_TOTAL_ACCEPTS_BYTES, MAX_AMOUNT_LENGTH, } from './types.js';
+export type { Result, AdapterError, AdapterErrorCode, JsonObject } from './types.js';
+export { X402Error } from './errors.js';
+export type { X402ErrorCode } from './errors.js';
+export { verifyOffer, verifyReceipt, matchAcceptTerms, selectAccept } from './verify.js';
+export { toPeacRecord } from './map.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,YAAY,EACV,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGrF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGzF,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * @peac/adapter-x402
+ *
+ * x402 Offer/Receipt extension verification, term-matching, and PEAC record mapping.
+ *
+ * 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).
+ *
+ * Key capabilities:
+ * - Structural validation of x402 offers and receipts
+ * - Term-matching: verify signed payload against accept entries
+ * - Accept selection with acceptIndex as untrusted hint
+ * - Mapping to canonical PEAC interaction records
+ * - DoS protection: limits on accepts array size
+ * - Amount/network validation: CAIP-2 format, integer strings
+ *
+ * IMPORTANT: This package does NOT perform cryptographic signature verification
+ * (EIP-712 recovery, JWS validation). That is the caller's responsibility.
+ * `valid: true` does NOT imply cryptographic signature validity unless
+ * a CryptoVerifier is supplied and `verification.cryptographic.verified` is true.
+ *
+ * The focus is on term-matching and record mapping -- the verification
+ * layer that makes unsigned acceptIndex irrelevant for security.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPeacRecord = exports.selectAccept = exports.matchAcceptTerms = exports.verifyReceipt = exports.verifyOffer = exports.X402Error = exports.MAX_AMOUNT_LENGTH = exports.MAX_TOTAL_ACCEPTS_BYTES = exports.MAX_ACCEPT_ENTRIES = exports.X402_OFFER_RECEIPT_PROFILE = void 0;
+// Constants
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "X402_OFFER_RECEIPT_PROFILE", { enumerable: true, get: function () { return types_js_1.X402_OFFER_RECEIPT_PROFILE; } });
+Object.defineProperty(exports, "MAX_ACCEPT_ENTRIES", { enumerable: true, get: function () { return types_js_1.MAX_ACCEPT_ENTRIES; } });
+Object.defineProperty(exports, "MAX_TOTAL_ACCEPTS_BYTES", { enumerable: true, get: function () { return types_js_1.MAX_TOTAL_ACCEPTS_BYTES; } });
+Object.defineProperty(exports, "MAX_AMOUNT_LENGTH", { enumerable: true, get: function () { return types_js_1.MAX_AMOUNT_LENGTH; } });
+// Errors
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "X402Error", { enumerable: true, get: function () { return errors_js_1.X402Error; } });
+// Verification
+var verify_js_1 = require("./verify.js");
+Object.defineProperty(exports, "verifyOffer", { enumerable: true, get: function () { return verify_js_1.verifyOffer; } });
+Object.defineProperty(exports, "verifyReceipt", { enumerable: true, get: function () { return verify_js_1.verifyReceipt; } });
+Object.defineProperty(exports, "matchAcceptTerms", { enumerable: true, get: function () { return verify_js_1.matchAcceptTerms; } });
+Object.defineProperty(exports, "selectAccept", { enumerable: true, get: function () { return verify_js_1.selectAccept; } });
+// Mapping
+var map_js_1 = require("./map.js");
+Object.defineProperty(exports, "toPeacRecord", { enumerable: true, get: function () { return map_js_1.toPeacRecord; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAqBH,YAAY;AACZ,uCAKoB;AAJlB,sHAAA,0BAA0B,OAAA;AAC1B,8GAAA,kBAAkB,OAAA;AAClB,mHAAA,uBAAuB,OAAA;AACvB,6GAAA,iBAAiB,OAAA;AAMnB,SAAS;AACT,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAGlB,eAAe;AACf,yCAAyF;AAAhF,wGAAA,WAAW,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAAE,yGAAA,YAAY,OAAA;AAEnE,UAAU;AACV,mCAAwC;AAA/B,sGAAA,YAAY,OAAA"}

package/dist/map.d.ts

@@ -0,0 +1,56 @@
+/**
+ * x402 to PEAC record mapping
+ *
+ * Maps x402 PaymentRequired + SettlementResponse into a canonical
+ * PEAC interaction record (X402PeacRecord).
+ *
+ * NOTE: This mapper produces records for the x402 Offer/Receipt EXTENSION,
+ * NOT the baseline x402 header flow. The profile identifier reflects this.
+ *
+ * The record preserves:
+ * - Raw proofs (offer + receipt) for audit/dispute
+ * - Normalized evidence fields from signed payloads
+ * - Unsigned hints (acceptIndex) explicitly marked as untrusted
+ * - Verification status metadata (structural, cryptographic, termMatching)
+ */
+import type { X402PaymentRequired, X402SettlementResponse, X402PeacRecord, OfferVerification } from './types.js';
+/**
+ * Options for record mapping
+ */
+export interface ToPeacRecordOptions {
+    /**
+     * Offer verification result (to populate verification hints)
+     *
+     * The termMatching field in OfferVerification is used to derive
+     * hints.acceptIndex.mismatchDetected automatically. This makes
+     * mismatch detection first-class without requiring external options.
+     */
+    offerVerification?: OfferVerification;
+    /**
+     * Whether cryptographic signature verification was performed
+     * Default: false (adapter does NOT perform crypto verification)
+     */
+    cryptoVerified?: boolean;
+    /**
+     * Signer identity (if crypto verification was performed)
+     */
+    cryptoSigner?: string;
+}
+/**
+ * Map x402 payment flow to a PEAC interaction record
+ *
+ * Takes a PaymentRequired (offer side) and SettlementResponse (receipt side)
+ * and produces a canonical PEAC record with normalized evidence.
+ *
+ * IMPORTANT: The resulting record does NOT indicate cryptographic signature
+ * validity unless you explicitly pass `cryptoVerified: true` in options.
+ * See `hints.verification.cryptographic` in the output.
+ *
+ * @param paymentRequired - The 402 response with offer and accepts
+ * @param settlementResponse - The settlement response with receipt
+ * @param options - Optional mapping options
+ * @returns Canonical PEAC interaction record
+ * @throws X402Error if inputs are structurally invalid
+ */
+export declare function toPeacRecord(paymentRequired: X402PaymentRequired, settlementResponse: X402SettlementResponse, options?: ToPeacRecordOptions): X402PeacRecord;
+//# sourceMappingURL=map.d.ts.map

package/dist/map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../src/map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EAEd,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAGpB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,eAAe,EAAE,mBAAmB,EACpC,kBAAkB,EAAE,sBAAsB,EAC1C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,cAAc,CAyFhB"}

package/dist/map.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * x402 to PEAC record mapping
+ *
+ * Maps x402 PaymentRequired + SettlementResponse into a canonical
+ * PEAC interaction record (X402PeacRecord).
+ *
+ * NOTE: This mapper produces records for the x402 Offer/Receipt EXTENSION,
+ * NOT the baseline x402 header flow. The profile identifier reflects this.
+ *
+ * The record preserves:
+ * - Raw proofs (offer + receipt) for audit/dispute
+ * - Normalized evidence fields from signed payloads
+ * - Unsigned hints (acceptIndex) explicitly marked as untrusted
+ * - Verification status metadata (structural, cryptographic, termMatching)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPeacRecord = toPeacRecord;
+const errors_js_1 = require("./errors.js");
+const types_js_1 = require("./types.js");
+/**
+ * Map x402 payment flow to a PEAC interaction record
+ *
+ * Takes a PaymentRequired (offer side) and SettlementResponse (receipt side)
+ * and produces a canonical PEAC record with normalized evidence.
+ *
+ * IMPORTANT: The resulting record does NOT indicate cryptographic signature
+ * validity unless you explicitly pass `cryptoVerified: true` in options.
+ * See `hints.verification.cryptographic` in the output.
+ *
+ * @param paymentRequired - The 402 response with offer and accepts
+ * @param settlementResponse - The settlement response with receipt
+ * @param options - Optional mapping options
+ * @returns Canonical PEAC interaction record
+ * @throws X402Error if inputs are structurally invalid
+ */
+function toPeacRecord(paymentRequired, settlementResponse, options) {
+    const offer = paymentRequired.offer;
+    const receipt = settlementResponse.receipt;
+    if (!offer?.payload) {
+        throw new errors_js_1.X402Error('offer_invalid_format', 'PaymentRequired must contain a valid offer with payload');
+    }
+    if (!receipt?.payload) {
+        throw new errors_js_1.X402Error('receipt_invalid_format', 'SettlementResponse must contain a valid receipt with payload');
+    }
+    const offerPayload = offer.payload;
+    const receiptPayload = receipt.payload;
+    // Build hints (unsigned metadata, explicitly untrusted)
+    const hints = {};
+    // Derive mismatchDetected from termMatching (first-class, always boolean when present)
+    const termMatching = options?.offerVerification?.termMatching;
+    const mismatchDetected = termMatching?.hintMismatchDetected ?? false;
+    if (paymentRequired.acceptIndex !== undefined) {
+        hints.acceptIndex = {
+            value: paymentRequired.acceptIndex,
+            untrusted: true,
+            ...(mismatchDetected && { mismatchDetected: true }),
+        };
+    }
+    const resourceUrl = paymentRequired.resourceUrl ?? settlementResponse.resourceUrl;
+    if (resourceUrl) {
+        hints.resourceUrl = resourceUrl;
+    }
+    // Build verification status
+    // IMPORTANT: If offerVerification is not provided, we cannot assume terms matched.
+    // Callers SHOULD provide offerVerification for a complete record.
+    const offerVerification = options?.offerVerification;
+    const termMatchingVerified = offerVerification !== undefined;
+    const verification = {
+        structural: true,
+        cryptographic: {
+            verified: options?.cryptoVerified ?? false,
+            ...(!(options?.cryptoVerified ?? false) && { reason: 'not_checked' }),
+            format: offer.format,
+            ...(options?.cryptoSigner && { signer: options.cryptoSigner }),
+        },
+        termMatching: {
+            // Safe-by-default: if verification wasn't performed, indicate that clearly
+            matched: termMatchingVerified ? offerVerification.valid : false,
+            method: offerVerification?.usedHint ? 'hint' : 'scan',
+            ...(offerVerification?.matchedIndex !== undefined && {
+                matchedIndex: offerVerification.matchedIndex,
+            }),
+            // Add flag to indicate if term-matching was actually performed
+            ...(!termMatchingVerified && { reason: 'not_verified' }),
+        },
+    };
+    hints.verification = verification;
+    return {
+        version: types_js_1.X402_OFFER_RECEIPT_PROFILE,
+        proofs: {
+            x402: {
+                offer,
+                receipt,
+            },
+        },
+        evidence: {
+            validUntil: offerPayload.validUntil,
+            network: offerPayload.network,
+            payee: offerPayload.payTo,
+            asset: offerPayload.asset,
+            amount: offerPayload.amount,
+            txHash: receiptPayload.txHash,
+            offerVersion: offerPayload.version,
+            ...(receiptPayload.version && { receiptVersion: receiptPayload.version }),
+        },
+        hints,
+        createdAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=map.js.map

package/dist/map.js.map

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