feat(a2a): add DNS rebinding protection and robust URL reconstruction

Author: alisa-alisa

packages/core/src/agents/a2a-client-manager.test.ts

@@ -38,7 +38,13 @@ vi.mock('../utils/debugLogger.js', () => ({
 }));
 
 vi.mock('node:dns/promises', () => ({
-  lookup: vi.fn().mockResolvedValue([{ address: '93.184.216.34' }]),
+  lookup: vi.fn().mockImplementation(async (hostname, options) => {
+    const addr = { address: '93.184.216.34', family: 4 };
+    if (options?.all) {
+      return [addr];
+    }
+    return addr;
+  }),
 }));
 
 describe('A2AClientManager', () => {
@@ -415,9 +421,11 @@ describe('A2AClientManager', () => {
     it('should throw if a domain resolves to a private IP (DNS SSRF protection)', async () => {
       const maliciousDomainUrl =
         'http://malicious.com/.well-known/agent-card.json';
-      vi.mocked(lookup).mockResolvedValueOnce([
-        { address: '10.0.0.1', family: 4 },
-      ]);
+       
+      vi.mocked(lookup).mockImplementationOnce(async () => 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+         [{ address: '10.0.0.1', family: 4 }] as any
+      );
 
       await expect(
         manager.loadAgent('dns-ssrf-agent', maliciousDomainUrl),
@@ -463,5 +471,24 @@ describe('A2AClientManager', () => {
         undefined,
       );
     });
+
+    it('should correctly handle URLs with standardPath in the hash fragment', async () => {
+      const fragmentUrl =
+        'http://localhost:9001/.well-known/agent-card.json#.well-known/agent-card.json';
+      const resolverInstance = {
+        resolve: vi.fn().mockResolvedValue({ name: 'test' } as AgentCard),
+      };
+      vi.mocked(sdkClient.DefaultAgentCardResolver).mockReturnValue(
+        resolverInstance as unknown as sdkClient.DefaultAgentCardResolver,
+      );
+
+      await manager.loadAgent('fragment-agent', fragmentUrl);
+
+      // Should correctly ignore the hash fragment and use the path from the URL object
+      expect(resolverInstance.resolve).toHaveBeenCalledWith(
+        'http://localhost:9001/',
+        '.well-known/agent-card.json',
+      );
+    });
   });
 });

packages/core/src/agents/a2a-client-manager.ts

@@ -12,45 +12,55 @@ import type {
   TaskStatusUpdateEvent,
   TaskArtifactUpdateEvent,
 } from '@a2a-js/sdk';
+import type { AuthenticationHandler, Client } from '@a2a-js/sdk/client';
 import {
   ClientFactory,
   ClientFactoryOptions,
   DefaultAgentCardResolver,
-  RestTransportFactory,
   JsonRpcTransportFactory,
-  type AuthenticationHandler,
+  RestTransportFactory,
   createAuthenticatingFetchWithRetry,
-  type Client,
 } from '@a2a-js/sdk/client';
 import { GrpcTransportFactory } from '@a2a-js/sdk/client/grpc';
 import { v4 as uuidv4 } from 'uuid';
 import { Agent as UndiciAgent } from 'undici';
-import { getGrpcCredentials, normalizeAgentCard } from './a2aUtils.js';
-import { isPrivateIpAsync } from '../utils/fetch.js';
+import {
+  getGrpcChannelOptions,
+  getGrpcCredentials,
+  normalizeAgentCard,
+  pinUrlToIp,
+} from './a2aUtils.js';
+import { isPrivateIpAsync, safeLookup } from '../utils/fetch.js';
 import { debugLogger } from '../utils/debugLogger.js';
 
+/**
+ * Result of sending a message, which can be a full message, a task,
+ * or an incremental status/artifact update.
+ */
+export type SendMessageResult =
+  | Message
+  | Task
+  | TaskStatusUpdateEvent
+  | TaskArtifactUpdateEvent;
+
 // Remote agents can take 10+ minutes (e.g. Deep Research).
 // Use a dedicated dispatcher so the global 5-min timeout isn't affected.
 const A2A_TIMEOUT = 1800000; // 30 minutes
 const a2aDispatcher = new UndiciAgent({
   headersTimeout: A2A_TIMEOUT,
   bodyTimeout: A2A_TIMEOUT,
+  connect: {
+    // SSRF protection at the connection level (mitigates DNS rebinding)
+    lookup: safeLookup,
+  },
 });
 const a2aFetch: typeof fetch = (input, init) =>
   // @ts-expect-error The `dispatcher` property is a Node.js extension to fetch not present in standard types.
   fetch(input, { ...init, dispatcher: a2aDispatcher });
 
-export type SendMessageResult =
-  | Message
-  | Task
-  | TaskStatusUpdateEvent
-  | TaskArtifactUpdateEvent;
-
 /**
- * Orchestrates communication with A2A agents.
- *
- * This manager handles agent discovery, card caching, and client lifecycle.
- * It provides a unified messaging interface using the standard A2A SDK.
+ * Orchestrates communication with remote A2A agents.
+ * Manages protocol negotiation, authentication, and transport selection.
  */
 export class A2AClientManager {
   private static instance: A2AClientManager;
@@ -83,7 +93,7 @@ export class A2AClientManager {
   /**
    * Loads an agent by fetching its AgentCard and caches the client.
    * @param name The name to assign to the agent.
-   * @param agentCardUrl The full URL to the agent's card.
+   * @param agentCardUrl {string} The full URL to the agent's card.
    * @param authHandler Optional authentication handler to use for this agent.
    * @returns The loaded AgentCard.
    */
@@ -100,16 +110,26 @@ export class A2AClientManager {
     const resolver = new DefaultAgentCardResolver({ fetchImpl });
     const agentCard = await this.resolveAgentCard(name, agentCardUrl, resolver);
 
+    // Pin URL to IP to prevent DNS rebinding for gRPC (connection-level SSRF protection)
+    const { pinnedUrl, hostname } = await pinUrlToIp(agentCard.url, name);
+
     // Configure standard SDK client for tool registration and discovery
     const clientOptions = ClientFactoryOptions.createFrom(
       ClientFactoryOptions.default,
       {
         transports: [
           new RestTransportFactory({ fetchImpl }),
           new JsonRpcTransportFactory({ fetchImpl }),
-          new GrpcTransportFactory({
-            grpcChannelCredentials: getGrpcCredentials(agentCard.url),
-          }),
+          new GrpcTransportFactory(
+            // gRPC transport options extension is supported by runtime but missing in SDK types
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+            {
+              target: pinnedUrl,
+              grpcChannelCredentials: getGrpcCredentials(agentCard.url),
+              grpcChannelOptions: getGrpcChannelOptions(hostname),
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            } as any,
+          ),
         ],
         cardResolver: resolver,
       },
@@ -166,7 +186,7 @@ export class A2AClientManager {
     try {
       yield* client.sendMessageStream(messageParams, {
         signal: options?.signal,
-      });
+      }) as AsyncIterable<SendMessageResult>;
     } catch (error: unknown) {
       const prefix = `[A2AClientManager] sendMessageStream Error [${agentName}]`;
       if (error instanceof Error) {
@@ -275,7 +295,14 @@ export class A2AClientManager {
       if (parsedUrl.pathname.endsWith(standardPath)) {
         // Correctly split the URL into baseUrl and standard path
         path = standardPath;
-        baseUrl = url.substring(0, url.lastIndexOf(standardPath));
+        // Reconstruct baseUrl from parsed components to avoid issues with hashes or query params.
+        parsedUrl.pathname = parsedUrl.pathname.substring(
+          0,
+          parsedUrl.pathname.lastIndexOf(standardPath),
+        );
+        parsedUrl.search = '';
+        parsedUrl.hash = '';
+        baseUrl = parsedUrl.toString();
       }
     } catch (e) {
       throw new Error(`Invalid agent card URL: ${url}`, { cause: e });