@agirails/sdk 2.0.4 → 2.2.1

package/src/types/x402.ts

@@ -0,0 +1,219 @@
+/**
+ * X402 Protocol Types and Constants
+ *
+ * Defines types for the HTTP 402 Payment Required protocol implementation.
+ * X402 enables atomic, instant API payments - NO escrow, NO state machine.
+ *
+ * Key difference from ACTP:
+ * - ACTP: escrow → state machine → disputes → explicit release
+ * - x402: atomic payment → instant settlement → done
+ *
+ * Flow:
+ * 1. Client requests protected HTTPS endpoint → gets 402 response
+ * 2. Parse X-Payment-* headers (address, amount, network, deadline)
+ * 3. Execute atomic USDC transfer to provider (no escrow!)
+ * 4. Retry request with tx hash as proof
+ * 5. Return response - payment complete, no release needed
+ *
+ * Use x402 for: Simple API calls, instant delivery, low-value transactions
+ * Use ACTP for: Complex services, dispute protection, high-value transactions
+ *
+ * @module types/x402
+ */
+
+// ============================================================================
+// X402 Header Constants
+// ============================================================================
+
+/**
+ * Standard X402 payment headers sent in 402 responses.
+ *
+ * These headers inform the client how to pay for the requested resource.
+ */
+export const X402_HEADERS = {
+  /** Indicates payment is required (must be "true") */
+  REQUIRED: 'x-payment-required',
+  /** Provider's wallet address (0x-prefixed) */
+  ADDRESS: 'x-payment-address',
+  /** Amount in USDC wei (6 decimals) */
+  AMOUNT: 'x-payment-amount',
+  /** Network identifier (base-mainnet or base-sepolia) */
+  NETWORK: 'x-payment-network',
+  /** Token type (currently only USDC) */
+  TOKEN: 'x-payment-token',
+  /** Unix timestamp deadline for payment */
+  DEADLINE: 'x-payment-deadline',
+  /** Optional: Dispute window in seconds */
+  DISPUTE_WINDOW: 'x-dispute-window',
+  /** Optional: Service identifier for tracking */
+  SERVICE_ID: 'x-service-id',
+} as const;
+
+/**
+ * Proof headers sent when retrying with payment.
+ *
+ * After creating an ACTP transaction, the client includes these
+ * headers to prove payment was made.
+ */
+export const X402_PROOF_HEADERS = {
+  /** ACTP transaction ID (bytes32 hex) */
+  TX_ID: 'x-payment-tx-id',
+  /** ACTP escrow ID (bytes32 hex) */
+  ESCROW_ID: 'x-payment-escrow-id',
+} as const;
+
+// ============================================================================
+// X402 Types
+// ============================================================================
+
+/** Supported networks for x402 payments */
+export type X402Network = 'base-mainnet' | 'base-sepolia';
+
+/** Supported tokens (currently only USDC) */
+export type X402Token = 'USDC';
+
+/**
+ * Parsed payment headers from HTTP 402 response.
+ *
+ * Contains all information needed to create an ACTP transaction
+ * for the requested resource.
+ */
+export interface X402PaymentHeaders {
+  /** Whether payment is required (always true for valid 402) */
+  required: boolean;
+
+  /** Provider's wallet address (0x-prefixed, 42 chars) */
+  paymentAddress: string;
+
+  /** Amount in USDC wei (6 decimals, as string) */
+  amount: string;
+
+  /** Target network */
+  network: X402Network;
+
+  /** Token type */
+  token: X402Token;
+
+  /** Unix timestamp deadline for accepting payment */
+  deadline: number;
+
+  /** Optional: Dispute window in seconds */
+  disputeWindow?: number;
+
+  /** Optional: Service identifier for tracking/debugging */
+  serviceId?: string;
+}
+
+// ============================================================================
+// X402 Error Handling
+// ============================================================================
+
+/**
+ * Error codes for X402 protocol failures.
+ *
+ * Used to identify specific error types and enable proper error handling.
+ */
+export enum X402ErrorCode {
+  /** Response status was not 402 */
+  NOT_402_RESPONSE = 'NOT_402_RESPONSE',
+
+  /** Required X-Payment-* headers are missing */
+  MISSING_HEADERS = 'MISSING_HEADERS',
+
+  /** X-Payment-Amount is invalid (not a number, negative, etc.) */
+  INVALID_AMOUNT = 'INVALID_AMOUNT',
+
+  /** X-Payment-Address is not a valid Ethereum address */
+  INVALID_ADDRESS = 'INVALID_ADDRESS',
+
+  /** X-Payment-Network is not a recognized network */
+  INVALID_NETWORK = 'INVALID_NETWORK',
+
+  /** Server's network doesn't match client's expected network */
+  NETWORK_MISMATCH = 'NETWORK_MISMATCH',
+
+  /** Failed to create ACTP transaction or link escrow */
+  PAYMENT_FAILED = 'PAYMENT_FAILED',
+
+  /** Retry request with proof headers failed */
+  RETRY_FAILED = 'RETRY_FAILED',
+
+  /** X-Payment-Deadline has already passed */
+  DEADLINE_PASSED = 'DEADLINE_PASSED',
+
+  /** HTTPS protocol required but HTTP used */
+  INSECURE_PROTOCOL = 'INSECURE_PROTOCOL',
+}
+
+/**
+ * Custom error for X402 protocol failures.
+ *
+ * Provides structured error information for debugging and error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await x402Adapter.pay({ to: 'https://api.example.com', amount: '10' });
+ * } catch (error) {
+ *   if (error instanceof X402Error) {
+ *     if (error.code === X402ErrorCode.NETWORK_MISMATCH) {
+ *       console.error('Wrong network:', error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class X402Error extends Error {
+  public readonly name = 'X402Error';
+
+  /**
+   * Creates a new X402Error.
+   *
+   * @param message - Human-readable error message
+   * @param code - Error code for programmatic handling
+   * @param response - Optional HTTP response that triggered the error
+   */
+  constructor(
+    message: string,
+    public readonly code: X402ErrorCode,
+    public readonly response?: Response
+  ) {
+    super(message);
+
+    // Maintains proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, X402Error);
+    }
+  }
+
+  /**
+   * Creates a detailed error message with code.
+   */
+  toString(): string {
+    return `X402Error [${this.code}]: ${this.message}`;
+  }
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Type guard to check if an error is an X402Error.
+ *
+ * @param error - Error to check
+ * @returns True if error is X402Error
+ */
+export function isX402Error(error: unknown): error is X402Error {
+  return error instanceof X402Error;
+}
+
+/**
+ * Validates that a network string is a valid X402Network.
+ *
+ * @param network - Network string to validate
+ * @returns True if valid X402Network
+ */
+export function isValidX402Network(network: string): network is X402Network {
+  return network === 'base-mainnet' || network === 'base-sepolia';
+}

package/src/utils/IPFSClient.ts

@@ -4,6 +4,7 @@
  */
 
 import { create, IPFSHTTPClient, Options } from 'kubo-rpc-client';
+import { sdkLogger } from './Logger';
 
 /**
  * IPFS Client Interface (from DeliveryProofBuilder)
@@ -202,10 +203,10 @@ export class IPFSHTTPClientImpl implements IPFSClient {
 
     // For remote hosts, require HTTPS
     if (!isLocalhost && parsed.protocol !== 'https:') {
-      console.warn(
-        `[SECURITY WARNING] Using non-HTTPS protocol "${parsed.protocol}" for remote IPFS endpoint "${hostname}". ` +
-        `This may expose data in transit. Consider using HTTPS.`
-      );
+      sdkLogger.warn('Using non-HTTPS protocol for remote IPFS endpoint - data may be exposed in transit', {
+        protocol: parsed.protocol,
+        hostname,
+      });
     }
   }
 

package/src/utils/NonceManager.ts

@@ -10,6 +10,7 @@
  */
 
 import { assertSafeFileForRead, ensureSafeDir, ensureSafeFile } from './fsSafe';
+import { sdkLogger } from './Logger';
 
 /**
  * Maximum allowed nonce value.
@@ -525,7 +526,7 @@ export class FileBasedNonceManager implements NonceManager {
     this.inMemory.recordNonce(messageType, nonce);
     // Fire-and-forget to maintain sync interface
     this.saveToFile().catch((err) => {
-      console.error('Failed to save nonce manager state:', err);
+      sdkLogger.error('Failed to save nonce manager state', { error: err instanceof Error ? err.message : String(err) });
     });
   }
 
@@ -537,7 +538,7 @@ export class FileBasedNonceManager implements NonceManager {
     this.inMemory.resetNonce(messageType);
     // Fire-and-forget to maintain sync interface
     this.saveToFile().catch((err) => {
-      console.error('Failed to save nonce manager state:', err);
+      sdkLogger.error('Failed to save nonce manager state', { error: err instanceof Error ? err.message : String(err) });
     });
   }
 

package/src/utils/UsedAttestationTracker.ts

@@ -12,6 +12,7 @@
  */
 
 import { assertSafeFileForRead, ensureSafeDir, ensureSafeFile } from './fsSafe';
+import { sdkLogger } from './Logger';
 
 /**
  * Interface for tracking used attestations
@@ -205,10 +206,7 @@ export class InMemoryUsedAttestationTracker implements IUsedAttestationTracker {
   cleanupOldEntries(_maxAgeHours: number): number {
     // In-memory tracker doesn't track timestamps
     // This is a placeholder for future enhancement
-    console.warn(
-      'cleanupOldEntries not implemented for InMemoryUsedAttestationTracker. ' +
-      'Consider using FileBasedUsedAttestationTracker for time-based cleanup.'
-    );
+    sdkLogger.warn('cleanupOldEntries not implemented for InMemoryUsedAttestationTracker - use FileBasedUsedAttestationTracker');
     return 0;
   }
 }
@@ -350,7 +348,7 @@ export class FileBasedUsedAttestationTracker implements IUsedAttestationTracker
     const result = this.inMemory.recordUsageSync(attestationUID, txId);
     if (result) {
       this.saveToFile().catch((err) => {
-        console.error('Failed to save attestation tracker state:', err);
+        sdkLogger.error('Failed to save attestation tracker state', { error: err instanceof Error ? err.message : String(err) });
       });
     }
     return result;

package/src/utils/circuitBreaker.ts

@@ -0,0 +1,324 @@
+/**
+ * Circuit Breaker - Gateway Health Tracking (Retry Amplification Protection)
+ *
+ * Implements the Circuit Breaker pattern for storage gateways:
+ * - Tracks consecutive failures per gateway
+ * - "Opens" circuit after threshold failures (blocks requests)
+ * - Auto-resets after cooldown period
+ *
+ * This prevents retry amplification attacks where a malicious/failing
+ * gateway causes excessive retries.
+ *
+ * @module utils/circuitBreaker
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Circuit state
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+/**
+ * Gateway health record
+ */
+interface GatewayHealth {
+  /** Consecutive failure count */
+  failures: number;
+  /** Timestamp of last failure */
+  lastFailure: number;
+  /** Current circuit state */
+  state: CircuitState;
+  /** Timestamp when circuit opened */
+  openedAt?: number;
+}
+
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit (default: 5) */
+  failureThreshold?: number;
+
+  /** Cooldown period in ms before attempting reset (default: 60000 = 1 min) */
+  resetTimeoutMs?: number;
+
+  /** Time window in ms for counting failures (default: 300000 = 5 min) */
+  failureWindowMs?: number;
+
+  /** Number of successes in half-open to close circuit (default: 2) */
+  successThreshold?: number;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_RESET_TIMEOUT_MS = 60000; // 1 minute
+const DEFAULT_FAILURE_WINDOW_MS = 300000; // 5 minutes
+const DEFAULT_SUCCESS_THRESHOLD = 2;
+
+// ============================================================================
+// GatewayCircuitBreaker Class
+// ============================================================================
+
+/**
+ * Circuit Breaker for gateway health management
+ *
+ * Usage:
+ * ```typescript
+ * const circuitBreaker = new GatewayCircuitBreaker();
+ *
+ * // Before making request
+ * if (!circuitBreaker.isHealthy(gatewayUrl)) {
+ *   throw new Error('Gateway circuit open');
+ * }
+ *
+ * try {
+ *   const result = await fetchFromGateway(gatewayUrl);
+ *   circuitBreaker.recordSuccess(gatewayUrl);
+ *   return result;
+ * } catch (error) {
+ *   circuitBreaker.recordFailure(gatewayUrl);
+ *   throw error;
+ * }
+ * ```
+ */
+export class GatewayCircuitBreaker {
+  private readonly health = new Map<string, GatewayHealth>();
+  private readonly config: Required<CircuitBreakerConfig>;
+  private halfOpenSuccesses = new Map<string, number>();
+
+  constructor(config: CircuitBreakerConfig = {}) {
+    this.config = {
+      failureThreshold: config.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD,
+      resetTimeoutMs: config.resetTimeoutMs ?? DEFAULT_RESET_TIMEOUT_MS,
+      failureWindowMs: config.failureWindowMs ?? DEFAULT_FAILURE_WINDOW_MS,
+      successThreshold: config.successThreshold ?? DEFAULT_SUCCESS_THRESHOLD
+    };
+  }
+
+  /**
+   * Check if gateway is healthy (circuit closed or half-open)
+   *
+   * @param url - Gateway URL
+   * @returns true if requests should be allowed
+   */
+  isHealthy(url: string): boolean {
+    const state = this.getState(url);
+    return state !== 'OPEN';
+  }
+
+  /**
+   * Get current circuit state for gateway
+   *
+   * @param url - Gateway URL
+   * @returns Circuit state
+   */
+  getState(url: string): CircuitState {
+    const health = this.health.get(url);
+
+    if (!health) {
+      return 'CLOSED';
+    }
+
+    // Check if circuit should transition from OPEN to HALF_OPEN
+    if (health.state === 'OPEN') {
+      const timeSinceOpen = Date.now() - (health.openedAt || 0);
+      if (timeSinceOpen >= this.config.resetTimeoutMs) {
+        // Transition to half-open
+        health.state = 'HALF_OPEN';
+        this.halfOpenSuccesses.set(url, 0);
+      }
+    }
+
+    // Check if failures have expired (outside window)
+    if (health.state === 'CLOSED') {
+      const timeSinceLastFailure = Date.now() - health.lastFailure;
+      if (timeSinceLastFailure >= this.config.failureWindowMs) {
+        // Reset failure count
+        health.failures = 0;
+      }
+    }
+
+    return health.state;
+  }
+
+  /**
+   * Record a successful request
+   *
+   * @param url - Gateway URL
+   */
+  recordSuccess(url: string): void {
+    const health = this.health.get(url);
+
+    if (!health) {
+      return; // No failures recorded, nothing to do
+    }
+
+    if (health.state === 'HALF_OPEN') {
+      // Count successes in half-open state
+      const successes = (this.halfOpenSuccesses.get(url) || 0) + 1;
+      this.halfOpenSuccesses.set(url, successes);
+
+      if (successes >= this.config.successThreshold) {
+        // Enough successes - close circuit
+        this.reset(url);
+      }
+    } else if (health.state === 'CLOSED') {
+      // Reset failure count on success
+      health.failures = 0;
+    }
+  }
+
+  /**
+   * Record a failed request
+   *
+   * @param url - Gateway URL
+   */
+  recordFailure(url: string): void {
+    const now = Date.now();
+    let health = this.health.get(url);
+
+    if (!health) {
+      health = {
+        failures: 0,
+        lastFailure: now,
+        state: 'CLOSED'
+      };
+      this.health.set(url, health);
+    }
+
+    // If in half-open state, any failure opens circuit again
+    if (health.state === 'HALF_OPEN') {
+      health.state = 'OPEN';
+      health.openedAt = now;
+      health.failures = this.config.failureThreshold; // Keep at threshold
+      this.halfOpenSuccesses.delete(url);
+      return;
+    }
+
+    // Check if previous failures have expired
+    const timeSinceLastFailure = now - health.lastFailure;
+    if (timeSinceLastFailure >= this.config.failureWindowMs) {
+      health.failures = 0;
+    }
+
+    // Increment failure count
+    health.failures++;
+    health.lastFailure = now;
+
+    // Check if threshold reached
+    if (health.failures >= this.config.failureThreshold) {
+      health.state = 'OPEN';
+      health.openedAt = now;
+    }
+  }
+
+  /**
+   * Reset circuit for gateway (force close)
+   *
+   * @param url - Gateway URL
+   */
+  reset(url: string): void {
+    this.health.delete(url);
+    this.halfOpenSuccesses.delete(url);
+  }
+
+  /**
+   * Reset all circuits
+   */
+  resetAll(): void {
+    this.health.clear();
+    this.halfOpenSuccesses.clear();
+  }
+
+  /**
+   * Get health status for all tracked gateways
+   *
+   * @returns Map of gateway URL to health info
+   */
+  getHealthStatus(): Map<string, { state: CircuitState; failures: number }> {
+    const status = new Map<string, { state: CircuitState; failures: number }>();
+
+    for (const [url, health] of this.health) {
+      status.set(url, {
+        state: this.getState(url), // This updates state if needed
+        failures: health.failures
+      });
+    }
+
+    return status;
+  }
+
+  /**
+   * Get failure count for gateway
+   *
+   * @param url - Gateway URL
+   * @returns Number of consecutive failures
+   */
+  getFailureCount(url: string): number {
+    return this.health.get(url)?.failures || 0;
+  }
+}
+
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+
+/**
+ * Default global circuit breaker instance
+ *
+ * Use this for simple cases where a single circuit breaker is sufficient.
+ * For more control, create your own GatewayCircuitBreaker instance.
+ */
+export const globalCircuitBreaker = new GatewayCircuitBreaker();
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Wrap an async operation with circuit breaker protection
+ *
+ * @param url - Gateway URL to track
+ * @param operation - Async operation to execute
+ * @param circuitBreaker - Circuit breaker instance (default: global)
+ * @returns Operation result
+ * @throws Error if circuit is open, or operation error
+ *
+ * @example
+ * ```typescript
+ * const result = await withCircuitBreaker(
+ *   'https://ipfs.filebase.io',
+ *   () => fetch(url).then(r => r.json())
+ * );
+ * ```
+ */
+export async function withCircuitBreaker<T>(
+  url: string,
+  operation: () => Promise<T>,
+  circuitBreaker: GatewayCircuitBreaker = globalCircuitBreaker
+): Promise<T> {
+  // Check if circuit allows request
+  if (!circuitBreaker.isHealthy(url)) {
+    const state = circuitBreaker.getState(url);
+    throw new Error(
+      `Circuit breaker OPEN for gateway: ${url}. ` +
+      `State: ${state}, Failures: ${circuitBreaker.getFailureCount(url)}. ` +
+      `Please wait for cooldown period before retrying.`
+    );
+  }
+
+  try {
+    const result = await operation();
+    circuitBreaker.recordSuccess(url);
+    return result;
+  } catch (error) {
+    circuitBreaker.recordFailure(url);
+    throw error;
+  }
+}

package/src/utils/fsSafe.ts

@@ -73,3 +73,8 @@ export function ensureSafeFile(
 
 
 
+
+
+
+
+