@agirails/sdk 2.0.4 → 2.2.0

package/dist/utils/retry.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetryResult = exports.withRetry = exports.calculateBackoffDelay = exports.isRetryableError = void 0;
+const errors_1 = require("../errors");
+// ============================================================================
+// 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
+ */
+function isRetryableError(error) {
+    if (!error)
+        return false;
+    // Rate limit errors are always retryable
+    if (error instanceof errors_1.StorageRateLimitError) {
+        return true;
+    }
+    const e = error;
+    // 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;
+}
+exports.isRetryableError = isRetryableError;
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param options - Retry options
+ * @returns Delay in milliseconds
+ */
+function calculateBackoffDelay(attempt, options = {}) {
+    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);
+}
+exports.calculateBackoffDelay = calculateBackoffDelay;
+/**
+ * Sleep for specified duration
+ *
+ * @param ms - Milliseconds to sleep
+ */
+function sleep(ms) {
+    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);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+async function withRetry(operation, options = {}) {
+    const { maxAttempts = DEFAULT_MAX_ATTEMPTS, isRetryable = isRetryableError, onRetry } = options;
+    let lastError;
+    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 errors_1.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;
+}
+exports.withRetry = withRetry;
+/**
+ * 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);
+ * }
+ * ```
+ */
+async function withRetryResult(operation, options = {}) {
+    const { maxAttempts = DEFAULT_MAX_ATTEMPTS, isRetryable = isRetryableError, onRetry } = options;
+    let lastError;
+    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 errors_1.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
+    };
+}
+exports.withRetryResult = withRetryResult;
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

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

package/dist/utils/validation.d.ts

@@ -1,6 +1,30 @@
 /**
  * Input validation utilities
  */
+/** Ethereum address validation pattern */
+export declare const ADDRESS_PATTERN: RegExp;
+/** Transaction ID (bytes32) validation pattern */
+export declare const TX_ID_PATTERN: RegExp;
+/** Hash (bytes32) validation pattern */
+export declare const HASH_PATTERN: RegExp;
+/** Signature (65 bytes = 130 hex chars) validation pattern */
+export declare const SIGNATURE_PATTERN: RegExp;
+/** CID validation pattern (CIDv0 or CIDv1) */
+export declare const CID_PATTERN: RegExp;
+/** Arweave TX ID pattern (43 characters, base64url) */
+export declare const ARWEAVE_TX_ID_PATTERN: RegExp;
+/** Semver pattern for version validation */
+export declare const SEMVER_PATTERN: RegExp;
+/**
+ * Allowed IPFS gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+export declare const ALLOWED_IPFS_GATEWAYS: readonly ["ipfs.filebase.io", "gateway.pinata.cloud", "cloudflare-ipfs.com", "ipfs.io", "dweb.link", "w3s.link", "nftstorage.link"];
+/**
+ * Allowed Arweave gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+export declare const ALLOWED_ARWEAVE_GATEWAYS: readonly ["arweave.net", "gateway.irys.xyz", "arweave.dev"];
 /**
  * Validate Ethereum address
  */
@@ -43,4 +67,80 @@ export declare function validateTxId(txId: string, fieldName?: string): void;
  * @throws {ValidationError} If endpoint is invalid or points to private IP
  */
 export declare function validateEndpointURL(endpoint: string, fieldName?: string): Promise<void>;
+/**
+ * Validate IPFS CID format
+ *
+ * @param cid - IPFS CID to validate
+ * @param fieldName - Field name for error messages
+ * @throws {InvalidCIDError} If CID is invalid
+ */
+export declare function validateCID(cid: string, fieldName?: string): void;
+/**
+ * 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 declare function validateArweaveTxId(txId: string, fieldName?: string): void;
+/**
+ * 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 declare function validateGatewayURL(url: string, allowedGateways: readonly string[], fieldName?: string): void;
+/**
+ * Validate semver version string
+ *
+ * @param version - Version string to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If version is invalid
+ */
+export declare function validateSemver(version: string, fieldName?: string): void;
+/**
+ * Validate hash (bytes32) format
+ *
+ * @param hash - Hash to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If hash is invalid
+ */
+export declare function validateHash(hash: string, fieldName?: string): void;
+/**
+ * Validate signature format (65 bytes)
+ *
+ * @param signature - Signature to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If signature is invalid
+ */
+export declare function validateSignature(signature: string, fieldName?: string): void;
+/**
+ * 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 declare function sanitizeErrorMessage(error: unknown): string;
+/**
+ * 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 declare function createSafeError(error: unknown, operation: string): {
+    message: string;
+    code: string;
+    operation: string;
+};
 //# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAOA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAQpF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,GAAE,MAAiB,GAAG,IAAI,CASlF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,IAAI,CASvF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,MAAwB,GAClC,IAAI,CAaN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAI3E;AAwDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFzG"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AASA;;GAEG;AAMH,0CAA0C;AAC1C,eAAO,MAAM,eAAe,QAAwB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,aAAa,QAAwB,CAAC;AAEnD,wCAAwC;AACxC,eAAO,MAAM,YAAY,QAAwB,CAAC;AAElD,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AAExD,8CAA8C;AAC9C,eAAO,MAAM,WAAW,QAAkD,CAAC;AAE3E,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,QAAwB,CAAC;AAE3D,4CAA4C;AAC5C,eAAO,MAAM,cAAc,QAAoB,CAAC;AAMhD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qIAQxB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,wBAAwB,6DAI3B,CAAC;AAMX;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAQpF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,GAAE,MAAiB,GAAG,IAAI,CASlF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,IAAI,CASvF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,MAAwB,GAClC,IAAI,CAaN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAI3E;AA8DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFzG;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,IAAI,CAQxE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAWlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,SAAS,GAAE,MAAqB,GAC/B,IAAI,CA0CN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAQnF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAQ3E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,GAAE,MAAoB,GAAG,IAAI,CAW1F;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsC3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAStD"}

package/dist/utils/validation.js

@@ -23,12 +23,57 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateEndpointURL = exports.validateTxId = exports.validateDisputeWindow = exports.validateDeadline = exports.validateAmount = exports.validateAddress = void 0;
+exports.createSafeError = exports.sanitizeErrorMessage = exports.validateSignature = exports.validateHash = exports.validateSemver = exports.validateGatewayURL = exports.validateArweaveTxId = exports.validateCID = exports.validateEndpointURL = exports.validateTxId = exports.validateDisputeWindow = exports.validateDeadline = exports.validateAmount = exports.validateAddress = exports.ALLOWED_ARWEAVE_GATEWAYS = exports.ALLOWED_IPFS_GATEWAYS = exports.SEMVER_PATTERN = exports.ARWEAVE_TX_ID_PATTERN = exports.CID_PATTERN = exports.SIGNATURE_PATTERN = exports.HASH_PATTERN = exports.TX_ID_PATTERN = exports.ADDRESS_PATTERN = void 0;
 const ethers_1 = require("ethers");
 const errors_1 = require("../errors");
 /**
  * Input validation utilities
  */
+// ============================================================================
+// Shared Validation Patterns (AIP-7 Storage)
+// ============================================================================
+/** Ethereum address validation pattern */
+exports.ADDRESS_PATTERN = /^0x[a-fA-F0-9]{40}$/;
+/** Transaction ID (bytes32) validation pattern */
+exports.TX_ID_PATTERN = /^0x[a-fA-F0-9]{64}$/;
+/** Hash (bytes32) validation pattern */
+exports.HASH_PATTERN = /^0x[a-fA-F0-9]{64}$/;
+/** Signature (65 bytes = 130 hex chars) validation pattern */
+exports.SIGNATURE_PATTERN = /^0x[a-fA-F0-9]{130}$/;
+/** CID validation pattern (CIDv0 or CIDv1) */
+exports.CID_PATTERN = /^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{58,})$/;
+/** Arweave TX ID pattern (43 characters, base64url) */
+exports.ARWEAVE_TX_ID_PATTERN = /^[a-zA-Z0-9_-]{43}$/;
+/** Semver pattern for version validation */
+exports.SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+// ============================================================================
+// Gateway URL Whitelist (SSRF Protection - P0-1)
+// ============================================================================
+/**
+ * Allowed IPFS gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+exports.ALLOWED_IPFS_GATEWAYS = [
+    'ipfs.filebase.io',
+    'gateway.pinata.cloud',
+    'cloudflare-ipfs.com',
+    'ipfs.io',
+    'dweb.link',
+    'w3s.link',
+    'nftstorage.link'
+];
+/**
+ * Allowed Arweave gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+exports.ALLOWED_ARWEAVE_GATEWAYS = [
+    'arweave.net',
+    'gateway.irys.xyz',
+    'arweave.dev'
+];
+// ============================================================================
+// Validation Functions
+// ============================================================================
 /**
  * Validate Ethereum address
  */
@@ -116,13 +161,19 @@ function isPrivateIP(ip) {
         }
     }
     // 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
@@ -220,4 +271,200 @@ async function validateEndpointURL(endpoint, fieldName = 'endpoint') {
     // IPFS endpoints skip DNS check (no DNS resolution for IPFS CIDs)
 }
 exports.validateEndpointURL = validateEndpointURL;
+// ============================================================================
+// 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
+ */
+function validateCID(cid, fieldName = 'cid') {
+    if (!cid || typeof cid !== 'string') {
+        throw new errors_1.InvalidCIDError(String(cid), 'CID is required');
+    }
+    if (!exports.CID_PATTERN.test(cid)) {
+        throw new errors_1.InvalidCIDError(cid, 'Invalid CID format (expected CIDv0 Qm... or CIDv1 bafy...)');
+    }
+}
+exports.validateCID = validateCID;
+/**
+ * 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
+ */
+function validateArweaveTxId(txId, fieldName = 'txId') {
+    if (!txId || typeof txId !== 'string') {
+        throw new errors_1.InvalidArweaveTxIdError(String(txId), 'TX ID is required');
+    }
+    if (!exports.ARWEAVE_TX_ID_PATTERN.test(txId)) {
+        throw new errors_1.InvalidArweaveTxIdError(txId, 'Invalid format (expected 43 character base64url string)');
+    }
+}
+exports.validateArweaveTxId = validateArweaveTxId;
+/**
+ * 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
+ */
+function validateGatewayURL(url, allowedGateways, fieldName = 'gatewayUrl') {
+    if (!url || typeof url !== 'string') {
+        throw new errors_1.ValidationError(fieldName, 'Gateway URL is required');
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        throw new errors_1.ValidationError(fieldName, 'Invalid URL format');
+    }
+    // Must be HTTPS
+    if (parsedUrl.protocol !== 'https:') {
+        throw new errors_1.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 errors_1.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 errors_1.ValidationError(fieldName, `Gateway "${hostname}" is not in the allowed list. ` +
+            `Allowed gateways: ${allowedGateways.join(', ')}. ` +
+            `This restriction prevents SSRF attacks.`);
+    }
+}
+exports.validateGatewayURL = validateGatewayURL;
+/**
+ * Validate semver version string
+ *
+ * @param version - Version string to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If version is invalid
+ */
+function validateSemver(version, fieldName = 'version') {
+    if (!version || typeof version !== 'string') {
+        throw new errors_1.ValidationError(fieldName, 'Version is required');
+    }
+    if (!exports.SEMVER_PATTERN.test(version)) {
+        throw new errors_1.ValidationError(fieldName, 'Must be semver format (e.g., 1.0.0)');
+    }
+}
+exports.validateSemver = validateSemver;
+/**
+ * Validate hash (bytes32) format
+ *
+ * @param hash - Hash to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If hash is invalid
+ */
+function validateHash(hash, fieldName = 'hash') {
+    if (!hash || typeof hash !== 'string') {
+        throw new errors_1.ValidationError(fieldName, 'Hash is required');
+    }
+    if (!exports.HASH_PATTERN.test(hash)) {
+        throw new errors_1.ValidationError(fieldName, 'Invalid hash format (expected bytes32 hex string)');
+    }
+}
+exports.validateHash = validateHash;
+/**
+ * Validate signature format (65 bytes)
+ *
+ * @param signature - Signature to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If signature is invalid
+ */
+function validateSignature(signature, fieldName = 'signature') {
+    if (!signature || typeof signature !== 'string') {
+        throw new errors_1.ValidationError(fieldName, 'Signature is required');
+    }
+    if (!exports.SIGNATURE_PATTERN.test(signature)) {
+        throw new errors_1.ValidationError(fieldName, 'Invalid signature format (expected 65 bytes = 0x + 130 hex chars)');
+    }
+}
+exports.validateSignature = validateSignature;
+// ============================================================================
+// 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
+ */
+function sanitizeErrorMessage(error) {
+    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;
+}
+exports.sanitizeErrorMessage = sanitizeErrorMessage;
+/**
+ * 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
+ */
+function createSafeError(error, operation) {
+    const sanitizedMessage = sanitizeErrorMessage(error);
+    // Don't expose internal details - generic message with operation context
+    return {
+        message: `Operation failed: ${operation}. ${sanitizedMessage}`,
+        code: error?.code || 'UNKNOWN_ERROR',
+        operation
+    };
+}
+exports.createSafeError = createSafeError;
 //# sourceMappingURL=validation.js.map