@agirails/sdk 2.0.4 → 2.2.1

package/src/utils/retry.ts

@@ -0,0 +1,365 @@
+/**
+ * Retry Utility - Exponential Backoff with Jitter (P1-2)
+ *
+ * Implements retry logic for storage operations with:
+ * - Exponential backoff (doubles delay each attempt)
+ * - Random jitter (prevents thundering herd)
+ * - Maximum retry limit
+ * - Configurable retry conditions
+ *
+ * @module utils/retry
+ */
+
+import { StorageRateLimitError } from '../errors';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Retry configuration options
+ */
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number;
+
+  /** Initial delay in milliseconds (default: 1000) */
+  initialDelayMs?: number;
+
+  /** Maximum delay in milliseconds (default: 30000) */
+  maxDelayMs?: number;
+
+  /** Multiplier for exponential backoff (default: 2) */
+  backoffMultiplier?: number;
+
+  /** Jitter factor 0-1 (default: 0.1 = ±10%) */
+  jitterFactor?: number;
+
+  /** Function to determine if error is retryable (default: built-in check) */
+  isRetryable?: (error: unknown) => boolean;
+
+  /** Callback for each retry attempt (for logging) */
+  onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+
+/**
+ * Result of retry operation
+ */
+export interface RetryResult<T> {
+  /** Operation result (if successful) */
+  result?: T;
+
+  /** Final error (if all retries failed) */
+  error?: unknown;
+
+  /** Number of attempts made */
+  attempts: number;
+
+  /** Total time spent (including delays) */
+  totalTimeMs: number;
+
+  /** Whether operation succeeded */
+  success: boolean;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 10000; // Reduced from 30s to 10s (NEW-4: prevent long stalls)
+const DEFAULT_BACKOFF_MULTIPLIER = 2;
+const DEFAULT_JITTER_FACTOR = 0.1;
+
+/**
+ * Default list of retryable HTTP status codes
+ */
+const RETRYABLE_STATUS_CODES = new Set([
+  408, // Request Timeout
+  429, // Too Many Requests
+  500, // Internal Server Error
+  502, // Bad Gateway
+  503, // Service Unavailable
+  504  // Gateway Timeout
+]);
+
+/**
+ * Default list of retryable error codes
+ */
+const RETRYABLE_ERROR_CODES = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+  'ENETUNREACH',
+  'EAI_AGAIN',
+  'EPIPE',
+  'EHOSTUNREACH'
+]);
+
+// ============================================================================
+// Functions
+// ============================================================================
+
+/**
+ * Default function to determine if error is retryable
+ *
+ * @param error - Error to check
+ * @returns True if error should trigger retry
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (!error) return false;
+
+  // Rate limit errors are always retryable
+  if (error instanceof StorageRateLimitError) {
+    return true;
+  }
+
+  const e = error as any;
+
+  // Check HTTP status codes
+  if (e.statusCode && RETRYABLE_STATUS_CODES.has(e.statusCode)) {
+    return true;
+  }
+
+  if (e.status && RETRYABLE_STATUS_CODES.has(e.status)) {
+    return true;
+  }
+
+  // Check error codes (network errors)
+  if (e.code && RETRYABLE_ERROR_CODES.has(e.code)) {
+    return true;
+  }
+
+  // Check for timeout errors
+  if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+    return true;
+  }
+
+  // Check message for common retryable patterns
+  const message = String(e.message || e).toLowerCase();
+  if (
+    message.includes('timeout') ||
+    message.includes('rate limit') ||
+    message.includes('too many requests') ||
+    message.includes('service unavailable') ||
+    message.includes('temporarily unavailable')
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param options - Retry options
+ * @returns Delay in milliseconds
+ */
+export function calculateBackoffDelay(
+  attempt: number,
+  options: RetryOptions = {}
+): number {
+  const {
+    initialDelayMs = DEFAULT_INITIAL_DELAY_MS,
+    maxDelayMs = DEFAULT_MAX_DELAY_MS,
+    backoffMultiplier = DEFAULT_BACKOFF_MULTIPLIER,
+    jitterFactor = DEFAULT_JITTER_FACTOR
+  } = options;
+
+  // Exponential backoff: initialDelay * (multiplier ^ (attempt - 1))
+  const exponentialDelay = initialDelayMs * Math.pow(backoffMultiplier, attempt - 1);
+
+  // Cap at max delay
+  const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+
+  // Add jitter: ±jitterFactor
+  const jitter = cappedDelay * jitterFactor * (Math.random() * 2 - 1);
+  const finalDelay = Math.max(0, cappedDelay + jitter);
+
+  return Math.round(finalDelay);
+}
+
+/**
+ * Sleep for specified duration
+ *
+ * @param ms - Milliseconds to sleep
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute async operation with retry logic
+ *
+ * Implements exponential backoff with jitter for handling transient failures.
+ * Particularly useful for storage operations that may fail due to:
+ * - Rate limiting
+ * - Network timeouts
+ * - Temporary service unavailability
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to operation result or throwing final error
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await withRetry(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * // With logging
+ * const result = await withRetry(
+ *   () => client.downloadJSON(cid),
+ *   {
+ *     maxAttempts: 5,
+ *     onRetry: (attempt, error, delay) => {
+ *       console.log(`Retry ${attempt}, waiting ${delay}ms:`, error);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    isRetryable = isRetryableError,
+    onRetry
+  } = options;
+
+  let lastError: unknown;
+  const startTime = Date.now();
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      // Check if this is the last attempt
+      if (attempt >= maxAttempts) {
+        break;
+      }
+
+      // Check if error is retryable
+      if (!isRetryable(error)) {
+        break;
+      }
+
+      // Calculate delay
+      let delayMs = calculateBackoffDelay(attempt, options);
+
+      // If rate limit error with retry-after header, use that instead
+      if (error instanceof StorageRateLimitError && error.details?.retryAfter) {
+        delayMs = Math.max(delayMs, error.details.retryAfter * 1000);
+      }
+
+      // Notify callback
+      if (onRetry) {
+        onRetry(attempt, error, delayMs);
+      }
+
+      // Wait before retry
+      await sleep(delayMs);
+    }
+  }
+
+  // All retries failed
+  throw lastError;
+}
+
+/**
+ * Execute async operation with retry logic, returning detailed result
+ *
+ * Unlike `withRetry`, this function never throws - it returns a result object
+ * with success/failure status and metadata.
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to detailed result object
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetryResult(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Uploaded:', result.result);
+ * } else {
+ *   console.error(`Failed after ${result.attempts} attempts:`, result.error);
+ * }
+ * ```
+ */
+export async function withRetryResult<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<RetryResult<T>> {
+  const {
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    isRetryable = isRetryableError,
+    onRetry
+  } = options;
+
+  let lastError: unknown;
+  const startTime = Date.now();
+  let attempts = 0;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    attempts = attempt;
+
+    try {
+      const result = await operation();
+      return {
+        result,
+        attempts,
+        totalTimeMs: Date.now() - startTime,
+        success: true
+      };
+    } catch (error) {
+      lastError = error;
+
+      // Check if this is the last attempt
+      if (attempt >= maxAttempts) {
+        break;
+      }
+
+      // Check if error is retryable
+      if (!isRetryable(error)) {
+        break;
+      }
+
+      // Calculate delay
+      let delayMs = calculateBackoffDelay(attempt, options);
+
+      // If rate limit error with retry-after header, use that instead
+      if (error instanceof StorageRateLimitError && error.details?.retryAfter) {
+        delayMs = Math.max(delayMs, error.details.retryAfter * 1000);
+      }
+
+      // Notify callback
+      if (onRetry) {
+        onRetry(attempt, error, delayMs);
+      }
+
+      // Wait before retry
+      await sleep(delayMs);
+    }
+  }
+
+  return {
+    error: lastError,
+    attempts,
+    totalTimeMs: Date.now() - startTime,
+    success: false
+  };
+}

package/src/utils/validation.ts

@@ -2,13 +2,72 @@ import { isAddress, getAddress } from 'ethers';
 import {
   InvalidAddressError,
   InvalidAmountError,
-  ValidationError
+  ValidationError,
+  InvalidCIDError,
+  InvalidArweaveTxIdError
 } from '../errors';
 
 /**
  * Input validation utilities
  */
 
+// ============================================================================
+// Shared Validation Patterns (AIP-7 Storage)
+// ============================================================================
+
+/** Ethereum address validation pattern */
+export const ADDRESS_PATTERN = /^0x[a-fA-F0-9]{40}$/;
+
+/** Transaction ID (bytes32) validation pattern */
+export const TX_ID_PATTERN = /^0x[a-fA-F0-9]{64}$/;
+
+/** Hash (bytes32) validation pattern */
+export const HASH_PATTERN = /^0x[a-fA-F0-9]{64}$/;
+
+/** Signature (65 bytes = 130 hex chars) validation pattern */
+export const SIGNATURE_PATTERN = /^0x[a-fA-F0-9]{130}$/;
+
+/** CID validation pattern (CIDv0 or CIDv1) */
+export const CID_PATTERN = /^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{58,})$/;
+
+/** Arweave TX ID pattern (43 characters, base64url) */
+export const ARWEAVE_TX_ID_PATTERN = /^[a-zA-Z0-9_-]{43}$/;
+
+/** Semver pattern for version validation */
+export const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+
+// ============================================================================
+// Gateway URL Whitelist (SSRF Protection - P0-1)
+// ============================================================================
+
+/**
+ * Allowed IPFS gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+export const ALLOWED_IPFS_GATEWAYS = [
+  'ipfs.filebase.io',
+  'gateway.pinata.cloud',
+  'cloudflare-ipfs.com',
+  'ipfs.io',
+  'dweb.link',
+  'w3s.link',
+  'nftstorage.link'
+] as const;
+
+/**
+ * Allowed Arweave gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+export const ALLOWED_ARWEAVE_GATEWAYS = [
+  'arweave.net',
+  'gateway.irys.xyz',
+  'arweave.dev'
+] as const;
+
+// ============================================================================
+// Validation Functions
+// ============================================================================
+
 /**
  * Validate Ethereum address
  */
@@ -113,13 +172,19 @@ function isPrivateIP(ip: string): boolean {
   }
 
   // IPv6 patterns (without brackets)
+  // Includes both standard ::ffff: and alternative ::ffff:0: notation (NEW-2 fix)
   const ipv6PrivatePatterns = [
     /^::1$/,                       // IPv6 loopback
     /^::ffff:127\./,               // IPv4-mapped localhost
+    /^::ffff:0:127\./,             // Alternative IPv4-mapped localhost
     /^::ffff:10\./,                // IPv4-mapped private 10.x
+    /^::ffff:0:10\./,              // Alternative IPv4-mapped private 10.x
     /^::ffff:192\.168\./,          // IPv4-mapped private 192.168.x
+    /^::ffff:0:192\.168\./,        // Alternative IPv4-mapped private 192.168.x
     /^::ffff:172\.(1[6-9]|2\d|3[01])\./,  // IPv4-mapped private 172.16-31.x
+    /^::ffff:0:172\.(1[6-9]|2\d|3[01])\./,// Alternative IPv4-mapped private 172.16-31.x
     /^::ffff:169\.254\./,          // IPv4-mapped link-local (CRITICAL: AWS metadata)
+    /^::ffff:0:169\.254\./,        // Alternative IPv4-mapped link-local
     /^fc00:/i,                     // IPv6 ULA fc00::/7
     /^fd/i,                        // IPv6 ULA fd00::/8
     /^fe80:/i                      // IPv6 link-local fe80::/10
@@ -244,3 +309,232 @@ export async function validateEndpointURL(endpoint: string, fieldName: string =
   // IPFS endpoints skip DNS check (no DNS resolution for IPFS CIDs)
 }
 
+// ============================================================================
+// Storage Validation Functions (AIP-7)
+// ============================================================================
+
+/**
+ * Validate IPFS CID format
+ *
+ * @param cid - IPFS CID to validate
+ * @param fieldName - Field name for error messages
+ * @throws {InvalidCIDError} If CID is invalid
+ */
+export function validateCID(cid: string, fieldName: string = 'cid'): void {
+  if (!cid || typeof cid !== 'string') {
+    throw new InvalidCIDError(String(cid), 'CID is required');
+  }
+
+  if (!CID_PATTERN.test(cid)) {
+    throw new InvalidCIDError(cid, 'Invalid CID format (expected CIDv0 Qm... or CIDv1 bafy...)');
+  }
+}
+
+/**
+ * Validate Arweave transaction ID format
+ *
+ * @param txId - Arweave TX ID to validate
+ * @param fieldName - Field name for error messages
+ * @throws {InvalidArweaveTxIdError} If TX ID is invalid
+ */
+export function validateArweaveTxId(txId: string, fieldName: string = 'txId'): void {
+  if (!txId || typeof txId !== 'string') {
+    throw new InvalidArweaveTxIdError(String(txId), 'TX ID is required');
+  }
+
+  if (!ARWEAVE_TX_ID_PATTERN.test(txId)) {
+    throw new InvalidArweaveTxIdError(
+      txId,
+      'Invalid format (expected 43 character base64url string)'
+    );
+  }
+}
+
+/**
+ * Validate gateway URL against whitelist (SSRF Protection - P0-1)
+ *
+ * SECURITY FIX: Only allow downloads from whitelisted gateway domains.
+ * This prevents SSRF attacks where attacker controls the gateway URL.
+ *
+ * @param url - Full gateway URL to validate
+ * @param allowedGateways - List of allowed gateway domains
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If gateway is not whitelisted
+ */
+export function validateGatewayURL(
+  url: string,
+  allowedGateways: readonly string[],
+  fieldName: string = 'gatewayUrl'
+): void {
+  if (!url || typeof url !== 'string') {
+    throw new ValidationError(fieldName, 'Gateway URL is required');
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(url);
+  } catch {
+    throw new ValidationError(fieldName, 'Invalid URL format');
+  }
+
+  // Must be HTTPS
+  if (parsedUrl.protocol !== 'https:') {
+    throw new ValidationError(fieldName, 'Gateway URL must use HTTPS');
+  }
+
+  // NEW-3: Validate port (must be 443 or default, prevents port bypass attacks)
+  const port = parsedUrl.port;
+  if (port && !['443', ''].includes(port)) {
+    throw new ValidationError(
+      fieldName,
+      `Gateway URL must use standard HTTPS port (443). Found port: ${port}. ` +
+      `Non-standard ports may bypass whitelist intent.`
+    );
+  }
+
+  // Check hostname against whitelist
+  const hostname = parsedUrl.hostname.toLowerCase();
+  const isAllowed = allowedGateways.some(gateway =>
+    hostname === gateway.toLowerCase() ||
+    hostname.endsWith('.' + gateway.toLowerCase())
+  );
+
+  if (!isAllowed) {
+    throw new ValidationError(
+      fieldName,
+      `Gateway "${hostname}" is not in the allowed list. ` +
+      `Allowed gateways: ${allowedGateways.join(', ')}. ` +
+      `This restriction prevents SSRF attacks.`
+    );
+  }
+}
+
+/**
+ * Validate semver version string
+ *
+ * @param version - Version string to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If version is invalid
+ */
+export function validateSemver(version: string, fieldName: string = 'version'): void {
+  if (!version || typeof version !== 'string') {
+    throw new ValidationError(fieldName, 'Version is required');
+  }
+
+  if (!SEMVER_PATTERN.test(version)) {
+    throw new ValidationError(fieldName, 'Must be semver format (e.g., 1.0.0)');
+  }
+}
+
+/**
+ * Validate hash (bytes32) format
+ *
+ * @param hash - Hash to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If hash is invalid
+ */
+export function validateHash(hash: string, fieldName: string = 'hash'): void {
+  if (!hash || typeof hash !== 'string') {
+    throw new ValidationError(fieldName, 'Hash is required');
+  }
+
+  if (!HASH_PATTERN.test(hash)) {
+    throw new ValidationError(fieldName, 'Invalid hash format (expected bytes32 hex string)');
+  }
+}
+
+/**
+ * Validate signature format (65 bytes)
+ *
+ * @param signature - Signature to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If signature is invalid
+ */
+export function validateSignature(signature: string, fieldName: string = 'signature'): void {
+  if (!signature || typeof signature !== 'string') {
+    throw new ValidationError(fieldName, 'Signature is required');
+  }
+
+  if (!SIGNATURE_PATTERN.test(signature)) {
+    throw new ValidationError(
+      fieldName,
+      'Invalid signature format (expected 65 bytes = 0x + 130 hex chars)'
+    );
+  }
+}
+
+// ============================================================================
+// Error Sanitization (P0-2)
+// ============================================================================
+
+/**
+ * Sanitize error messages to remove sensitive data
+ *
+ * SECURITY FIX (P0-2): Removes credentials, private keys, and other
+ * sensitive data from error messages before logging/returning.
+ *
+ * @param error - Error to sanitize
+ * @returns Sanitized error message
+ */
+export function sanitizeErrorMessage(error: unknown): string {
+  if (!error) return 'Unknown error';
+
+  let message = '';
+  if (error instanceof Error) {
+    message = error.message;
+  } else if (typeof error === 'string') {
+    message = error;
+  } else {
+    message = String(error);
+  }
+
+  // Patterns to redact
+  const sensitivePatterns = [
+    // Private keys (hex)
+    /0x[a-fA-F0-9]{64}/g,
+    // AWS access key IDs
+    /AKIA[0-9A-Z]{16}/g,
+    // AWS secret keys (40 chars)
+    /[a-zA-Z0-9/+=]{40}/g,
+    // Bearer tokens
+    /Bearer\s+[a-zA-Z0-9._-]+/gi,
+    // API keys (generic pattern)
+    /api[_-]?key[=:]\s*["']?[a-zA-Z0-9_-]+["']?/gi,
+    // Secret in URL query params
+    /secret[=][^&\s]+/gi,
+    // Password in URL
+    /password[=][^&\s]+/gi,
+    // Authorization headers
+    /authorization[=:]\s*["']?[^"'\s]+["']?/gi
+  ];
+
+  let sanitized = message;
+  for (const pattern of sensitivePatterns) {
+    sanitized = sanitized.replace(pattern, '[REDACTED]');
+  }
+
+  return sanitized;
+}
+
+/**
+ * Create a safe error object for external consumption
+ *
+ * SECURITY FIX (P0-2): Returns error without stack trace or sensitive details
+ *
+ * @param error - Original error
+ * @param operation - What operation failed
+ * @returns Safe error object
+ */
+export function createSafeError(
+  error: unknown,
+  operation: string
+): { message: string; code: string; operation: string } {
+  const sanitizedMessage = sanitizeErrorMessage(error);
+
+  // Don't expose internal details - generic message with operation context
+  return {
+    message: `Operation failed: ${operation}. ${sanitizedMessage}`,
+    code: (error as any)?.code || 'UNKNOWN_ERROR',
+    operation
+  };
+}