@agirails/sdk 2.5.2 → 2.5.4

package/src/utils/circuitBreaker.ts

@@ -1,324 +0,0 @@
-/**
- * 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/computeTypeHash.ts

@@ -1,48 +0,0 @@
-/**
- * Compute EIP-712 Type Hash for AIP-4 Delivery Proof
- * Reference: AIP-4 §3.3, EIP-712 specification
- *
- * Run with: npx tsx src/utils/computeTypeHash.ts
- */
-
-import { TypedDataEncoder, keccak256, toUtf8Bytes } from 'ethers';
-import { AIP4DeliveryProofTypes } from '../types/eip712';
-
-/**
- * Compute EIP-712 type hash for DeliveryProof
- * @returns Type hash (bytes32)
- */
-export function computeDeliveryProofTypeHash(): string {
-  const encoder = TypedDataEncoder.from(AIP4DeliveryProofTypes);
-  const typeString = encoder.encodeType('DeliveryProof');
-
-  // Type hash is keccak256 of the encoded type string
-  const typeHash = keccak256(toUtf8Bytes(typeString));
-
-  return typeHash;
-}
-
-/**
- * Get encoded type string for DeliveryProof
- * @returns Type string (for documentation)
- */
-export function getDeliveryProofTypeString(): string {
-  return TypedDataEncoder.from(AIP4DeliveryProofTypes).encodeType('DeliveryProof');
-}
-
-// If run directly, compute and print type hash
-if (require.main === module) {
-  console.log('=== AIP-4 Delivery Proof EIP-712 Type Hash ===\n');
-
-  const typeString = getDeliveryProofTypeString();
-  console.log('Type String:');
-  console.log(typeString);
-  console.log();
-
-  const typeHash = computeDeliveryProofTypeHash();
-  console.log('Type Hash (bytes32):');
-  console.log(typeHash);
-  console.log();
-
-  console.log('Use this type hash in your EIP-712 typed data configuration.');
-}

package/src/utils/fsSafe.ts

@@ -1,80 +0,0 @@
-/**
- * fsSafe - minimal filesystem hardening helpers
- *
- * Focus:
- * - Prevent symlink-based path escapes when persisting local state
- * - Avoid clobbering arbitrary files via pre-created symlink temp files
- *
- * NOTE: This is not a complete TOCTOU-proof sandbox, but it eliminates the
- * most common local symlink/hardlink footguns for SDK-managed state files.
- */
-
-import * as fs from 'fs';
-
-export function ensureSafeDir(dirPath: string, mode: number = 0o755): void {
-  if (fs.existsSync(dirPath)) {
-    const st = fs.lstatSync(dirPath);
-    if (st.isSymbolicLink()) {
-      throw new Error(`Refusing to use symlink directory: ${dirPath}`);
-    }
-    if (!st.isDirectory()) {
-      throw new Error(`Expected directory but found non-directory: ${dirPath}`);
-    }
-    return;
-  }
-
-  fs.mkdirSync(dirPath, { recursive: true, mode });
-
-  // Post-create sanity: ensure it didn't become a symlink (defense-in-depth)
-  const st = fs.lstatSync(dirPath);
-  if (st.isSymbolicLink() || !st.isDirectory()) {
-    throw new Error(`Created unsafe directory (symlink or non-dir): ${dirPath}`);
-  }
-}
-
-export function assertSafeFileForRead(filePath: string): void {
-  if (!fs.existsSync(filePath)) return;
-  const st = fs.lstatSync(filePath);
-  if (st.isSymbolicLink()) {
-    throw new Error(`Refusing to read from symlink file: ${filePath}`);
-  }
-  if (!st.isFile()) {
-    throw new Error(`Expected file but found non-file: ${filePath}`);
-  }
-}
-
-export function ensureSafeFile(
-  filePath: string,
-  contents: string,
-  mode: number = 0o644
-): void {
-  if (fs.existsSync(filePath)) {
-    const st = fs.lstatSync(filePath);
-    if (st.isSymbolicLink()) {
-      throw new Error(`Refusing to use symlink file: ${filePath}`);
-    }
-    if (!st.isFile()) {
-      throw new Error(`Expected file but found non-file: ${filePath}`);
-    }
-    return;
-  }
-
-  // Use exclusive create to avoid clobbering a file that appears between
-  // existsSync() and writeFileSync().
-  fs.writeFileSync(filePath, contents, {
-    encoding: 'utf-8',
-    mode,
-    flag: 'wx',
-  });
-}
-
-
-
-
-
-
-
-
-
-
-

package/src/utils/index.ts

@@ -1,80 +0,0 @@
-/**
- * ACTP SDK Utilities
- *
- * This module exports all utility classes for the ACTP SDK.
- *
- * @module utils
- */
-
-// Error Recovery (HIGH-6)
-export {
-  ErrorRecoveryGuide,
-  withRecoveryGuidance,
-  type ErrorRecoveryInfo,
-  type ErrorSeverity,
-  type ErrorCategory,
-} from './ErrorRecoveryGuide';
-
-// Rate Limiting & Circuit Breaker (M-4, M-5)
-export {
-  RateLimiter,
-  CircuitBreaker,
-  APIProtector,
-  type RateLimiterConfig,
-  type RateLimitResult,
-  type CircuitBreakerConfig,
-  type CircuitBreakerResult,
-  type CircuitState,
-} from './RateLimiter';
-
-// Logging & Metrics (M-6, M-7)
-export {
-  Logger,
-  MetricsCollector,
-  sdkLogger,
-  sdkMetrics,
-  type LogLevel,
-  type LogEntry,
-  type LoggerConfig,
-  type MetricsHook,
-} from './Logger';
-
-// SDK Lifecycle (M-8)
-export {
-  SDKLifecycle,
-  sdkLifecycle,
-  onShutdown,
-  registerDisposable,
-  shutdownSDK,
-  type Disposable,
-  type ShutdownHandler,
-  type LifecycleEvent,
-  type LifecycleListener,
-} from './SDKLifecycle';
-
-// Nonce Tracking (Security)
-export {
-  InMemoryReceivedNonceTracker,
-  SetBasedReceivedNonceTracker,
-  createReceivedNonceTracker,
-  type IReceivedNonceTracker,
-  type NonceValidationResult,
-} from './ReceivedNonceTracker';
-
-// Attestation Tracking (Security)
-export {
-  InMemoryUsedAttestationTracker,
-  FileBasedUsedAttestationTracker,
-  createUsedAttestationTracker,
-  type IUsedAttestationTracker,
-} from './UsedAttestationTracker';
-
-// Helper Utilities (L-7)
-export {
-  USDC,
-  Deadline,
-  Address,
-  Bytes32,
-  State,
-  DisputeWindow,
-} from './Helpers';