@peac/adapter-core 0.10.0 → 0.10.6

package/README.md

@@ -89,4 +89,6 @@ Apache-2.0
 
 ---
 
-Part of the [PEAC Protocol](https://peacprotocol.org).
+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/index.d.ts

@@ -10,4 +10,5 @@ export type { JsonPrimitive, JsonValue, JsonArray, JsonObject } from '@peac/kern
 export { type Result, ok, err, adapterErr, isOk, isErr, map, mapErr, chain, unwrap, unwrapOr, } from './result.js';
 export type { AdapterError, AdapterErrorCode } from './types.js';
 export { requireString, optionalString, requireNumber, requireAmount, requireCurrency, optionalNetwork, requireObject, optionalTimestamp, optionalBoolean, requireEnum, optionalEnum, } from './validators.js';
+export type { NormalizedTerms, NormalizedSettlement, TermsVerification, SettlementVerification, VerificationError, PaymentProofRecord, VerificationContext, PaymentProofAdapter, CryptoVerifier, } from './payment-proof.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGpF,OAAO,EACL,KAAK,MAAM,EACX,EAAE,EACF,GAAG,EACH,UAAU,EACV,IAAI,EACJ,KAAK,EACL,GAAG,EACH,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,GACT,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjE,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGpF,OAAO,EACL,KAAK,MAAM,EACX,EAAE,EACF,GAAG,EACH,UAAU,EACV,IAAI,EACJ,KAAK,EACL,GAAG,EACH,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,GACT,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjE,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,GACf,MAAM,oBAAoB,CAAC"}

package/dist/payment-proof.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Payment Proof Adapter Interface
+ *
+ * Defines the contract that all payment proof adapters must implement.
+ * This interface ensures consistency across different payment protocols
+ * (x402, Stripe, UPI, Lightning, etc.) while allowing protocol-specific
+ * implementations.
+ *
+ * @packageDocumentation
+ */
+import type { Result } from './result.js';
+import type { AdapterError } from './types.js';
+/**
+ * Normalized payment terms extracted from proof artifacts
+ *
+ * This is the common denominator across all payment protocols.
+ * Protocol-specific fields belong in the raw proofs, not here.
+ */
+export interface NormalizedTerms {
+    /** Payment asset (e.g., "USDC", "USD", "BTC") */
+    asset: string;
+    /** Payment amount in minor units as string (to avoid precision loss) */
+    amount: string;
+    /** Payment recipient identifier (address, account, etc.) */
+    payee: string;
+    /** Network identifier (CAIP-2 preferred, but protocol-specific allowed) */
+    network?: string;
+    /** Terms validity window */
+    timebounds?: {
+        /** Not valid before (epoch seconds) */
+        notBefore?: number;
+        /** Not valid after (epoch seconds) */
+        notAfter?: number;
+    };
+}
+/**
+ * Normalized settlement evidence extracted from proof artifacts
+ */
+export interface NormalizedSettlement {
+    /** Settlement reference (tx hash, payment intent ID, etc.) */
+    reference: string;
+    /** Settlement network (may differ from terms network) */
+    network?: string;
+    /** Settlement status */
+    status: 'confirmed' | 'pending' | 'failed';
+    /** Settlement timestamp (epoch seconds) */
+    settledAt?: number;
+}
+/**
+ * Result of terms verification
+ */
+export interface TermsVerification<TRaw = unknown> {
+    /** Whether verification passed */
+    valid: boolean;
+    /** Normalized terms (if valid) */
+    terms?: NormalizedTerms;
+    /** Raw proof artifact (preserved for audit) */
+    raw: TRaw;
+    /** Verification errors (if invalid) */
+    errors: VerificationError[];
+    /** Whether a hint was used for binding (protocol-specific) */
+    usedHint?: boolean;
+}
+/**
+ * Result of settlement verification
+ */
+export interface SettlementVerification<TRaw = unknown> {
+    /** Whether verification passed */
+    valid: boolean;
+    /** Normalized settlement (if valid) */
+    settlement?: NormalizedSettlement;
+    /** Raw proof artifact (preserved for audit) */
+    raw: TRaw;
+    /** Verification errors (if invalid) */
+    errors: VerificationError[];
+}
+/**
+ * Structured verification error
+ */
+export interface VerificationError {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Field that caused the error */
+    field?: string;
+}
+/**
+ * Base PEAC record structure for payment proofs
+ *
+ * Adapters extend this with protocol-specific fields in `proofs` and `hints`.
+ */
+export interface PaymentProofRecord<TProofs = unknown, THints = unknown> {
+    /** Profile identifier (e.g., "peac-x402-offer-receipt/0.1") */
+    version: string;
+    /** Raw proof artifacts (preserved for audit) */
+    proofs: TProofs;
+    /** Normalized evidence fields */
+    evidence: {
+        /** From terms */
+        asset: string;
+        amount: string;
+        payee: string;
+        network?: string;
+        validUntil?: number;
+        /** From settlement */
+        reference?: string;
+        settledAt?: number;
+    };
+    /** Protocol-specific hints (marked as untrusted where appropriate) */
+    hints: THints;
+    /** RFC 8785 JCS + SHA-256 digest */
+    digest?: string;
+    /** ISO 8601 timestamp of record creation */
+    createdAt: string;
+}
+/**
+ * Verification context provided to adapter methods
+ */
+export interface VerificationContext {
+    /** Current time override (epoch seconds, for testing) */
+    nowSeconds?: number;
+    /** Clock skew tolerance in seconds */
+    clockSkewSeconds?: number;
+    /** Mismatch policy for hint-based binding */
+    mismatchPolicy?: 'fail' | 'warn_and_scan' | 'ignore_and_scan';
+}
+/**
+ * Payment Proof Adapter Interface
+ *
+ * All payment proof adapters must implement this interface.
+ * This ensures a consistent API surface across different payment protocols.
+ *
+ * @typeParam TTermsInput - Protocol-specific terms input type
+ * @typeParam TSettlementInput - Protocol-specific settlement input type
+ * @typeParam TTermsRaw - Protocol-specific raw terms artifact type
+ * @typeParam TSettlementRaw - Protocol-specific raw settlement artifact type
+ * @typeParam TRecord - Protocol-specific PEAC record type
+ *
+ * @example
+ * // x402 adapter implements this interface
+ * const adapter: PaymentProofAdapter<
+ *   X402PaymentRequired,
+ *   X402SettlementResponse,
+ *   SignedOffer,
+ *   SignedReceipt,
+ *   X402PeacRecord
+ * > = {
+ *   profileId: 'peac-x402-offer-receipt/0.1',
+ *   verifyTerms: (input, ctx) => { ... },
+ *   verifySettlement: (input, ctx) => { ... },
+ *   toRecord: (terms, settlement) => { ... },
+ * };
+ */
+export interface PaymentProofAdapter<TTermsInput = unknown, TSettlementInput = unknown, TTermsRaw = unknown, TSettlementRaw = unknown, TRecord extends PaymentProofRecord = PaymentProofRecord> {
+    /**
+     * Profile identifier for this adapter
+     *
+     * Format: "peac-{protocol}/{version}" (e.g., "peac-x402-offer-receipt/0.1")
+     */
+    readonly profileId: string;
+    /**
+     * Verify payment terms
+     *
+     * Performs structural validation, expiry checks, and protocol-specific
+     * binding verification (e.g., term-matching for x402).
+     *
+     * Does NOT perform cryptographic signature verification unless
+     * a crypto verifier is injected via context.
+     *
+     * @param input - Protocol-specific terms input
+     * @param context - Verification context (optional)
+     * @returns Verification result with normalized terms
+     */
+    verifyTerms(input: TTermsInput, context?: VerificationContext): Result<TermsVerification<TTermsRaw>, AdapterError>;
+    /**
+     * Verify settlement proof
+     *
+     * Performs structural validation of the settlement artifact.
+     *
+     * Does NOT verify on-chain settlement status - that is the caller's
+     * responsibility via chain RPC.
+     *
+     * @param input - Protocol-specific settlement input
+     * @param context - Verification context (optional)
+     * @returns Verification result with normalized settlement
+     */
+    verifySettlement(input: TSettlementInput, context?: VerificationContext): Result<SettlementVerification<TSettlementRaw>, AdapterError>;
+    /**
+     * Map verified proofs to a PEAC record
+     *
+     * @param terms - Verified terms result
+     * @param settlement - Verified settlement result
+     * @returns PEAC record with normalized evidence and raw proofs
+     */
+    toRecord(terms: TermsVerification<TTermsRaw>, settlement: SettlementVerification<TSettlementRaw>): Result<TRecord, AdapterError>;
+}
+/**
+ * Optional cryptographic verifier interface
+ *
+ * Adapters may accept an injected crypto verifier for signature validation.
+ * This allows callers to provide protocol-specific verification (EIP-712,
+ * JWS, etc.) without the adapter depending on crypto libraries.
+ */
+export interface CryptoVerifier<TInput = unknown> {
+    /**
+     * Verify cryptographic signature
+     *
+     * @param input - Input to verify (protocol-specific)
+     * @returns true if signature is valid, false otherwise
+     */
+    verify(input: TInput): Promise<boolean>;
+    /**
+     * Get signer identity from verified input
+     *
+     * @param input - Verified input
+     * @returns Signer identifier (address, key ID, etc.)
+     */
+    getSigner?(input: TInput): Promise<string>;
+}
+//# sourceMappingURL=payment-proof.d.ts.map

package/dist/payment-proof.d.ts.map

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

package/dist/payment-proof.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Payment Proof Adapter Interface
+ *
+ * Defines the contract that all payment proof adapters must implement.
+ * This interface ensures consistency across different payment protocols
+ * (x402, Stripe, UPI, Lightning, etc.) while allowing protocol-specific
+ * implementations.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=payment-proof.js.map

package/dist/payment-proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-proof.js","sourceRoot":"","sources":["../src/payment-proof.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/adapter-core",
-  "version": "0.10.0",
+  "version": "0.10.6",
   "description": "Shared utilities for PEAC payment rail adapters",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@peac/kernel": "0.10.0"
+    "@peac/kernel": "0.10.6"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",