@agirails/sdk 2.0.1-beta → 2.0.2

package/src/utils/validation.ts

@@ -80,3 +80,167 @@ export function validateTxId(txId: string, fieldName: string = 'txId'): void {
   }
 }
 
+/**
+ * Check if IP address is private/local (SSRF protection)
+ *
+ * SECURITY FIX (H-1): Comprehensive private IP detection
+ * - IPv4: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16
+ * - IPv6: ::1, fc00::/7, fd00::/8, fe80::/10
+ * - IPv4-mapped IPv6: ::ffff:127.0.0.0/8, ::ffff:10.0.0.0/8, etc.
+ *
+ * @param ip - IP address (v4 or v6, no brackets)
+ * @returns true if IP is private/local
+ */
+function isPrivateIP(ip: string): boolean {
+  // Remove IPv6 brackets if present
+  const cleanIP = ip.replace(/^\[|\]$/g, '');
+
+  // IPv4 patterns
+  const ipv4PrivatePatterns = [
+    /^127\./,                      // Loopback
+    /^10\./,                       // Private class A
+    /^172\.(1[6-9]|2\d|3[01])\./,  // Private class B (172.16-172.31)
+    /^192\.168\./,                 // Private class C
+    /^169\.254\./,                 // Link-local / AWS metadata
+    /^0\./,                        // Invalid source
+    /^localhost$/i                 // Localhost hostname
+  ];
+
+  for (const pattern of ipv4PrivatePatterns) {
+    if (pattern.test(cleanIP)) {
+      return true;
+    }
+  }
+
+  // IPv6 patterns (without brackets)
+  const ipv6PrivatePatterns = [
+    /^::1$/,                       // IPv6 loopback
+    /^::ffff:127\./,               // IPv4-mapped localhost
+    /^::ffff:10\./,                // IPv4-mapped private 10.x
+    /^::ffff:192\.168\./,          // IPv4-mapped private 192.168.x
+    /^::ffff:172\.(1[6-9]|2\d|3[01])\./,  // IPv4-mapped private 172.16-31.x
+    /^::ffff:169\.254\./,          // IPv4-mapped link-local (CRITICAL: AWS metadata)
+    /^fc00:/i,                     // IPv6 ULA fc00::/7
+    /^fd/i,                        // IPv6 ULA fd00::/8
+    /^fe80:/i                      // IPv6 link-local fe80::/10
+  ];
+
+  for (const pattern of ipv6PrivatePatterns) {
+    if (pattern.test(cleanIP)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Validate endpoint URL (for AgentRegistry)
+ *
+ * SECURITY FIX (H-1): Enhanced SSRF protection with DNS resolution
+ *
+ * Security checks:
+ * - Valid URL format
+ * - HTTPS or IPFS protocols only
+ * - Maximum length 256 characters
+ * - DNS resolution check (hostname → IP validation)
+ * - No private/local IP addresses (SSRF protection)
+ * - Blocks AWS metadata endpoint (169.254.169.254)
+ * - Fail-secure: if DNS lookup fails, reject
+ *
+ * **CRITICAL**: This function is now ASYNC due to DNS resolution.
+ * All callers MUST await this function.
+ *
+ * @param endpoint - URL to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If endpoint is invalid or points to private IP
+ */
+export async function validateEndpointURL(endpoint: string, fieldName: string = 'endpoint'): Promise<void> {
+  if (!endpoint || endpoint.length === 0) {
+    throw new ValidationError(fieldName, 'Endpoint is required');
+  }
+
+  const MAX_LENGTH = 256;
+  if (endpoint.length > MAX_LENGTH) {
+    throw new ValidationError(fieldName, `Endpoint exceeds maximum length (${MAX_LENGTH})`);
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(endpoint);
+  } catch (e) {
+    throw new ValidationError(fieldName, 'Endpoint must be a valid URL');
+  }
+
+  const allowedProtocols = ['https:', 'ipfs:'];
+  if (!allowedProtocols.includes(parsedUrl.protocol)) {
+    throw new ValidationError(
+      fieldName,
+      `Endpoint protocol must be one of: ${allowedProtocols.join(', ')}`
+    );
+  }
+
+  // SECURITY FIX (H-1): First check hostname syntax
+  // URL().hostname strips brackets from IPv6 addresses
+  const hostname = parsedUrl.hostname;
+
+  // Check if hostname itself looks like a private IP (bypass DNS for direct IPs)
+  if (isPrivateIP(hostname)) {
+    throw new ValidationError(
+      fieldName,
+      `Endpoint hostname "${hostname}" is a private/local address (SSRF protection)`
+    );
+  }
+
+  // SECURITY FIX (H-1): DNS resolution check
+  // Resolve hostname to IP address(es) and validate each resolved IP
+  // This prevents DNS rebinding attacks where hostname resolves to private IP
+  if (parsedUrl.protocol === 'https:') {
+    try {
+      // Dynamic import for Node.js dns module (not available in browser)
+      // If running in browser, skip DNS check (browsers have their own SSRF protection)
+      const dns = await import('dns').catch(() => null);
+
+      if (dns) {
+        // Resolve hostname to ALL IP addresses and validate each (prevents AAAA/A bypass)
+        const results = await dns.promises.lookup(hostname, { all: true });
+
+        for (const { address, family } of results) {
+          // Validate resolved IP is not private
+          if (isPrivateIP(address)) {
+            throw new ValidationError(
+              fieldName,
+              `Endpoint hostname "${hostname}" resolves to private IP address ${address} (SSRF protection). ` +
+                `This could be an attempt to access internal services. ` +
+                `IP family: IPv${family}`
+            );
+          }
+
+          // SECURITY FIX (H-1): CRITICAL - Block AWS metadata endpoint explicitly
+          if (address === '169.254.169.254') {
+            throw new ValidationError(
+              fieldName,
+              `Endpoint resolves to AWS metadata endpoint (169.254.169.254). ` +
+                `This is blocked for security reasons (credential theft prevention).`
+            );
+          }
+        }
+      }
+    } catch (error: any) {
+      // SECURITY FIX (H-1): Fail-secure - if DNS lookup fails, reject
+      // Don't allow requests to unresolvable hostnames (could be DNS rebinding setup)
+      if (error instanceof ValidationError) {
+        throw error; // Re-throw validation errors
+      }
+
+      throw new ValidationError(
+        fieldName,
+        `Failed to resolve hostname "${hostname}": ${error.message}. ` +
+        `DNS resolution is required for SSRF protection (fail-secure mode).`
+      );
+    }
+  }
+
+  // IPFS endpoints skip DNS check (no DNS resolution for IPFS CIDs)
+}
+

package/src/__tests__/ProofGenerator.test.ts

@@ -1,124 +0,0 @@
-import { ProofGenerator } from '../protocol/ProofGenerator';
-
-describe('ProofGenerator', () => {
-  let proofGenerator: ProofGenerator;
-
-  beforeEach(() => {
-    proofGenerator = new ProofGenerator();
-  });
-
-  describe('hashContent', () => {
-    it('should hash string content', () => {
-      const content = 'Hello, ACTP!';
-      const hash = proofGenerator.hashContent(content);
-
-      expect(hash).toMatch(/^0x[a-f0-9]{64}$/);
-      expect(hash).toHaveLength(66); // 0x + 64 hex chars
-    });
-
-    it('should hash buffer content', () => {
-      const content = Buffer.from('Hello, ACTP!');
-      const hash = proofGenerator.hashContent(content);
-
-      expect(hash).toMatch(/^0x[a-f0-9]{64}$/);
-    });
-
-    it('should produce same hash for same content', () => {
-      const content = 'Test content';
-      const hash1 = proofGenerator.hashContent(content);
-      const hash2 = proofGenerator.hashContent(content);
-
-      expect(hash1).toBe(hash2);
-    });
-
-    it('should produce different hashes for different content', () => {
-      const hash1 = proofGenerator.hashContent('Content A');
-      const hash2 = proofGenerator.hashContent('Content B');
-
-      expect(hash1).not.toBe(hash2);
-    });
-  });
-
-  describe('generateDeliveryProof', () => {
-    it('should generate valid delivery proof', () => {
-      const txId = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
-      const deliverable = 'Completed translation work';
-
-      const proof = proofGenerator.generateDeliveryProof({
-        txId,
-        deliverable,
-        metadata: { language: 'es' }
-      });
-
-      expect(proof.txId).toBe(txId);
-      expect(proof.contentHash).toMatch(/^0x[a-f0-9]{64}$/);
-      expect(proof.timestamp).toBeGreaterThan(0);
-      expect(proof.metadata.size).toBeGreaterThan(0);
-      expect(proof.metadata.language).toBe('es');
-    });
-
-    it('should include default mimeType', () => {
-      const proof = proofGenerator.generateDeliveryProof({
-        txId: '0x1234',
-        deliverable: 'test'
-      });
-
-      expect(proof.metadata.mimeType).toBe('application/octet-stream');
-    });
-
-    it('should use custom mimeType', () => {
-      const proof = proofGenerator.generateDeliveryProof({
-        txId: '0x1234',
-        deliverable: 'test',
-        metadata: { mimeType: 'text/plain' }
-      });
-
-      expect(proof.metadata.mimeType).toBe('text/plain');
-    });
-  });
-
-  describe('verifyDeliverable', () => {
-    it('should verify matching deliverable', () => {
-      const deliverable = 'Test deliverable';
-      const hash = proofGenerator.hashContent(deliverable);
-
-      const isValid = proofGenerator.verifyDeliverable(deliverable, hash);
-      expect(isValid).toBe(true);
-    });
-
-    it('should reject non-matching deliverable', () => {
-      const deliverable = 'Test deliverable';
-      const wrongHash = proofGenerator.hashContent('Wrong content');
-
-      const isValid = proofGenerator.verifyDeliverable(deliverable, wrongHash);
-      expect(isValid).toBe(false);
-    });
-
-    it('should be case-insensitive for hash comparison', () => {
-      const deliverable = 'Test';
-      const hash = proofGenerator.hashContent(deliverable);
-      const upperHash = hash.toUpperCase();
-
-      const isValid = proofGenerator.verifyDeliverable(deliverable, upperHash);
-      expect(isValid).toBe(true);
-    });
-  });
-
-  describe('encodeProof and decodeProof', () => {
-    it('should encode and decode proof correctly', () => {
-      const originalProof = proofGenerator.generateDeliveryProof({
-        txId: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
-        deliverable: 'test'
-      });
-
-      const encoded = proofGenerator.encodeProof(originalProof);
-      const decoded = proofGenerator.decodeProof(encoded);
-
-      expect(decoded.txId).toBe(originalProof.txId);
-      expect(decoded.contentHash).toBe(originalProof.contentHash);
-      expect(decoded.timestamp).toBe(originalProof.timestamp);
-    });
-  });
-});
-
-