@andreprado/agentkit 0.1.0 → 0.1.1

package/src/runtime/channels/net-guard.ts

@@ -0,0 +1,480 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import type { IncomingMessage } from "node:http";
+import { request as httpsRequest } from "node:https";
+import type { LookupFunction } from "node:net";
+import { pipeline, Readable } from "node:stream";
+import { createBrotliDecompress, createUnzip } from "node:zlib";
+
+import { AgentKitError } from "../errors";
+
+// Outbound requests to operator-configured URLs (webhook outputs, self-hosted
+// WhatsApp gateways) must not reach private networks. Checking the hostname
+// text is not enough: a public name can resolve to a private address, and a
+// public server can redirect to one. So every guarded request resolves DNS,
+// rejects blocked addresses, pins the connection to the checked address, and
+// never follows redirects.
+
+export type OutboundResolver = (hostname: string) => Promise<string[]>;
+
+export type ResolvedOutboundUrl = {
+  href: string;
+  address: string;
+  family: 4 | 6;
+};
+
+export type PinnedRequestInit = {
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  signal?: AbortSignal;
+};
+
+export type PublicHttpsFetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+// Test seams only. Production callers never pass these, so private addresses
+// stay blocked and TLS is verified against the system CA store.
+export type PinnedTransportOptions = {
+  isBlockedAddress?: (address: string) => boolean;
+  ca?: string;
+};
+
+export function createPublicHttpsFetch(
+  label: string,
+  resolver: OutboundResolver = resolveOutboundAddresses,
+  transport: PinnedTransportOptions = {},
+): PublicHttpsFetch {
+  return async (url, init = {}) => {
+    const parsed = new URL(url);
+
+    if (parsed.protocol !== "https:") {
+      throw new AgentKitError("channel_payload_invalid", `${label} must use HTTPS.`);
+    }
+
+    if (isBlockedOutboundHost(parsed.hostname)) {
+      throw new AgentKitError("channel_payload_invalid", `${label} host is not allowed.`);
+    }
+
+    if (init.body !== undefined && init.body !== null && typeof init.body !== "string") {
+      throw new AgentKitError("channel_payload_invalid", `${label} requests only support string bodies.`);
+    }
+
+    const signal = init.signal ?? undefined;
+    const resolved = await resolvePublicOutboundUrl(parsed.href, label, resolver, signal, transport.isBlockedAddress);
+    const headers: Record<string, string> = {};
+
+    new Headers(init.headers).forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    return pinnedHttpsFetch(
+      resolved,
+      {
+        method: init.method ?? "GET",
+        headers,
+        body: init.body ?? undefined,
+        signal,
+      },
+      label,
+      transport,
+    );
+  };
+}
+
+export async function resolvePublicOutboundUrl(
+  href: string,
+  label: string,
+  resolver: OutboundResolver = resolveOutboundAddresses,
+  signal?: AbortSignal,
+  isBlockedAddress: (address: string) => boolean = isBlockedOutboundHost,
+): Promise<ResolvedOutboundUrl> {
+  const url = new URL(href);
+  let addresses: string[];
+
+  try {
+    addresses = await resolveWithinDeadline(resolver, url.hostname, signal, label);
+  } catch (error) {
+    if (error instanceof AgentKitError) {
+      throw error;
+    }
+
+    throw new AgentKitError(
+      "channel_provider_unavailable",
+      `${label} host could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (addresses.length === 0) {
+    throw new AgentKitError("channel_provider_unavailable", `${label} host did not resolve.`);
+  }
+
+  for (const address of addresses) {
+    if (isBlockedAddress(address)) {
+      throw new AgentKitError("channel_payload_invalid", `${label} host resolved to a blocked address.`);
+    }
+  }
+
+  const address = normalizeOutboundHost(addresses[0]);
+
+  return {
+    href,
+    address,
+    family: parseIpv4Octets(address) ? 4 : 6,
+  };
+}
+
+// Node's https.request does not follow redirects, so a 3xx response is
+// returned to the caller as-is rather than being chased to another host.
+export function pinnedHttpsFetch(
+  resolved: ResolvedOutboundUrl,
+  init: PinnedRequestInit,
+  label: string,
+  transport: PinnedTransportOptions = {},
+): Promise<Response> {
+  const url = new URL(resolved.href);
+  const isBlockedAddress = transport.isBlockedAddress ?? isBlockedOutboundHost;
+  // Node calls lookup with `all: true` (for happy-eyeballs family selection),
+  // which expects an array of records instead of a single address.
+  const lookup = ((_hostname: string, options: { all?: boolean }, callback: (...args: unknown[]) => void) => {
+    if (options?.all) {
+      callback(null, [{ address: resolved.address, family: resolved.family }]);
+      return;
+    }
+
+    callback(null, resolved.address, resolved.family);
+  }) as unknown as LookupFunction;
+
+  return new Promise((resolve, reject) => {
+    const request = httpsRequest(
+      url,
+      {
+        method: init.method,
+        headers: init.headers,
+        lookup,
+        signal: init.signal,
+        ...(transport.ca ? { ca: transport.ca } : {}),
+      },
+      (response) => {
+        // Everything here runs outside the promise executor, so any throw must
+        // become a rejection or it would crash the process.
+        try {
+          assertAllowedRemoteAddress(response.socket.remoteAddress, label, isBlockedAddress);
+          const status = response.statusCode ?? 502;
+          const bodyless = init.method.toUpperCase() === "HEAD" || NULL_BODY_STATUSES.has(status);
+
+          if (bodyless) {
+            response.resume();
+          }
+
+          resolve(
+            new Response(bodyless ? null : (Readable.toWeb(decodedResponseBody(response)) as unknown as ReadableStream<Uint8Array>), {
+              status,
+              headers: headersFromIncomingMessage(response.headers),
+            }),
+          );
+        } catch (error) {
+          response.destroy(error instanceof Error ? error : new Error(String(error)));
+          reject(error);
+        }
+      },
+    );
+
+    request.on("socket", (socket) => {
+      const validateSocket = () => {
+        try {
+          assertAllowedRemoteAddress(socket.remoteAddress, label, isBlockedAddress);
+        } catch (error) {
+          request.destroy(error instanceof Error ? error : new Error(String(error)));
+        }
+      };
+
+      socket.once("connect", validateSocket);
+      socket.once("secureConnect", validateSocket);
+    });
+    request.once("error", reject);
+    request.end(init.body);
+  });
+}
+
+function decodedResponseBody(response: IncomingMessage): Readable {
+  const encodings = response.headers["content-encoding"]?.toLowerCase().split(",").map((value) => value.trim()) ?? [];
+
+  if (encodings.length === 0 || !encodings.every((value) => ["gzip", "x-gzip", "deflate", "x-deflate", "br"].includes(value))) {
+    return response;
+  }
+
+  const decoders = encodings.reverse().map((encoding) => encoding === "br" ? createBrotliDecompress() : createUnzip());
+  // Keep decoding streamed so callers enforce limits on decoded bytes. Pipeline
+  // propagates source errors and destroys the socket when the reader cancels.
+  pipeline([response, ...decoders], () => {});
+  return decoders[decoders.length - 1];
+}
+
+export async function resolveOutboundAddresses(hostname: string): Promise<string[]> {
+  const host = normalizeOutboundHost(hostname);
+
+  if (parseIpv4Octets(host) || parseIpv6Segments(host)) {
+    return [host];
+  }
+
+  const records = await dnsLookup(host, {
+    all: true,
+    verbatim: true,
+  });
+
+  return records.map((record) => record.address);
+}
+
+export function isBlockedOutboundHost(hostname: string): boolean {
+  const host = normalizeOutboundHost(hostname);
+
+  if (
+    host === "localhost" ||
+    host.endsWith(".localhost") ||
+    host === "metadata.google.internal"
+  ) {
+    return true;
+  }
+
+  const ipv4 = parseIpv4Octets(host);
+
+  if (ipv4) {
+    return isBlockedIpv4Octets(ipv4);
+  }
+
+  const ipv6 = parseIpv6Segments(host);
+
+  if (ipv6) {
+    return isBlockedIpv6Segments(ipv6);
+  }
+
+  return false;
+}
+
+export function normalizeOutboundHost(hostname: string): string {
+  return hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "").replace(/\.$/, "");
+}
+
+// The Fetch Response constructor rejects a body for these statuses.
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+
+// Resolution happens before the request exists, so the caller's deadline has to
+// cover it here; otherwise a stalled resolver outlives the request timeout.
+// Nothing has been sent yet, so this failure is always safe to retry.
+async function resolveWithinDeadline(
+  resolver: OutboundResolver,
+  hostname: string,
+  signal: AbortSignal | undefined,
+  label: string,
+): Promise<string[]> {
+  const deadlineError = () =>
+    new AgentKitError("channel_provider_unavailable", `${label} host resolution did not finish before the request deadline.`);
+
+  if (!signal) {
+    return resolver(hostname);
+  }
+
+  if (signal.aborted) {
+    throw deadlineError();
+  }
+
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(deadlineError());
+
+    signal.addEventListener("abort", onAbort, { once: true });
+    resolver(hostname).then(
+      (addresses) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(addresses);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function assertAllowedRemoteAddress(
+  address: string | undefined,
+  label: string,
+  isBlockedAddress: (address: string) => boolean,
+): void {
+  if (!address || isBlockedAddress(address)) {
+    throw new AgentKitError("channel_payload_invalid", `${label} connected to a blocked address.`);
+  }
+}
+
+function headersFromIncomingMessage(headers: Record<string, string | string[] | number | undefined>): Headers {
+  const result = new Headers();
+
+  for (const [key, value] of Object.entries(headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        result.append(key, item);
+      }
+      continue;
+    }
+
+    if (value !== undefined) {
+      result.set(key, String(value));
+    }
+  }
+
+  return result;
+}
+
+function parseIpv4Octets(host: string): number[] | undefined {
+  const parts = host.split(".");
+
+  if (parts.length !== 4) {
+    return undefined;
+  }
+
+  const octets = parts.map((part) => Number(part));
+
+  if (octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return undefined;
+  }
+
+  return octets;
+}
+
+function isBlockedIpv4Octets(parts: number[]): boolean {
+  const [a, b] = parts;
+
+  return (
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 198 && (b === 18 || b === 19)) ||
+    a >= 224
+  );
+}
+
+function parseIpv6Segments(host: string): number[] | undefined {
+  if (!host.includes(":")) {
+    return undefined;
+  }
+
+  if (host === "::") {
+    return new Array(8).fill(0);
+  }
+
+  const [leftRaw, rightRaw, extra] = host.split("::");
+
+  if (extra !== undefined) {
+    return undefined;
+  }
+
+  const left = parseIpv6SegmentSide(leftRaw ?? "");
+  const right = parseIpv6SegmentSide(rightRaw ?? "");
+
+  if (!left || !right) {
+    return undefined;
+  }
+
+  if (rightRaw === undefined) {
+    return left.length === 8 ? left : undefined;
+  }
+
+  const missing = 8 - left.length - right.length;
+
+  if (missing < 1) {
+    return undefined;
+  }
+
+  return [...left, ...new Array(missing).fill(0), ...right];
+}
+
+function parseIpv6SegmentSide(value: string): number[] | undefined {
+  if (!value) {
+    return [];
+  }
+
+  const segments: number[] = [];
+
+  const parts = value.split(":");
+
+  for (const [index, part] of parts.entries()) {
+    if (part.includes(".")) {
+      if (index !== parts.length - 1) {
+        return undefined;
+      }
+
+      const octets = parseIpv4Octets(part);
+
+      if (!octets) {
+        return undefined;
+      }
+
+      segments.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
+      continue;
+    }
+
+    if (!/^[0-9a-f]{1,4}$/i.test(part)) {
+      return undefined;
+    }
+
+    segments.push(parseInt(part, 16));
+  }
+
+  return segments;
+}
+
+function isBlockedIpv6Segments(parts: number[]): boolean {
+  if (parts.length !== 8) {
+    return true;
+  }
+
+  const embeddedIpv4 = ipv4OctetsFromIpv6Segments(parts);
+
+  if (embeddedIpv4) {
+    return isBlockedIpv4Octets(embeddedIpv4);
+  }
+
+  const isAllZero = parts.every((part) => part === 0);
+
+  if (isAllZero || (parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1)) {
+    return true;
+  }
+
+  const first = parts[0];
+
+  return (
+    (first & 0xfe00) === 0xfc00 ||
+    (first & 0xffc0) === 0xfe80 ||
+    (first & 0xff00) === 0xff00
+  );
+}
+
+function ipv4OctetsFromIpv6Segments(parts: number[]): number[] | undefined {
+  const trailingIpv4 = [
+    (parts[6] >> 8) & 0xff,
+    parts[6] & 0xff,
+    (parts[7] >> 8) & 0xff,
+    parts[7] & 0xff,
+  ];
+
+  if (parts.slice(0, 5).every((part) => part === 0) && (parts[5] === 0xffff || parts[5] === 0)) {
+    return trailingIpv4;
+  }
+
+  if (parts[0] === 0x64 && parts[1] === 0xff9b && parts.slice(2, 6).every((part) => part === 0)) {
+    return trailingIpv4;
+  }
+
+  if (parts[0] === 0x2002) {
+    return [
+      (parts[1] >> 8) & 0xff,
+      parts[1] & 0xff,
+      (parts[2] >> 8) & 0xff,
+      parts[2] & 0xff,
+    ];
+  }
+
+  return undefined;
+}

package/src/runtime/channels/provider-fetch.ts

@@ -0,0 +1,54 @@
+import { isAgentKitError } from "../errors";
+
+// Deadlines for outbound provider calls. Without them a hung provider stalls
+// a delivery job until the runtime's own socket defaults give up.
+export const CHANNEL_SEND_TIMEOUT_MS = 15_000;
+export const CHANNEL_STATUS_TIMEOUT_MS = 15_000;
+export const CHANNEL_DOWNLOAD_TIMEOUT_MS = 60_000;
+
+export type SendRequestFailure = {
+  retryable: boolean;
+  code: "channel_provider_unavailable" | "channel_send_failed";
+  reason: string;
+};
+
+// Classifies a failure thrown by fetch() for a non-idempotent send. A deadline
+// can fire after the provider has already accepted the message, and none of
+// the chat providers deduplicate on our idempotency key, so retrying a timed
+// out send risks delivering the reply twice.
+export function classifySendRequestError(error: unknown): SendRequestFailure {
+  if (isOutboundGuardRejection(error)) {
+    return {
+      retryable: false,
+      code: "channel_send_failed",
+      reason: "was blocked by the outbound network guard",
+    };
+  }
+
+  if (isDeadlineError(error)) {
+    return {
+      retryable: false,
+      code: "channel_send_failed",
+      reason: "timed out before a response; the provider may already have accepted the message, so it will not be retried",
+    };
+  }
+
+  return {
+    retryable: true,
+    code: "channel_provider_unavailable",
+    reason: "failed before a response",
+  };
+}
+
+// Downloads and status checks are safe to repeat; only a guard rejection is final.
+export function isRetryableReadRequestError(error: unknown): boolean {
+  return !isOutboundGuardRejection(error);
+}
+
+export function isDeadlineError(error: unknown): boolean {
+  return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+
+function isOutboundGuardRejection(error: unknown): boolean {
+  return isAgentKitError(error) && error.code === "channel_payload_invalid";
+}

package/src/runtime/channels/slack.ts

@@ -7,6 +7,10 @@ import type {
   WebhookVerificationResult,
 } from "../channels";
 import { AgentKitError } from "../errors";
+import {
+  CHANNEL_SEND_TIMEOUT_MS,
+  classifySendRequestError,
+} from "./provider-fetch";
 
 const SLACK_API_BASE_URL = "https://slack.com/api";
 const SLACK_SIGNATURE_VERSION = "v0";
@@ -285,16 +289,18 @@ export async function sendSlackMessage(
 
   try {
     response = await fetcher(actualRequest.url, {
+      signal: AbortSignal.timeout(CHANNEL_SEND_TIMEOUT_MS),
       method: actualRequest.method,
       headers: actualRequest.headers,
       body: JSON.stringify(actualRequest.body),
     });
   } catch (error) {
+    const failure = classifySendRequestError(error);
     return {
       ok: false,
-      retryable: true,
-      code: "channel_provider_unavailable",
-      message: `Slack chat.postMessage request failed before a response: ${redactSlackToken(
+      retryable: failure.retryable,
+      code: failure.code,
+      message: `Slack chat.postMessage request ${failure.reason}: ${redactSlackToken(
         error instanceof Error ? error.message : String(error),
         input.secrets.SLACK_BOT_TOKEN,
       )}`,

package/src/runtime/channels/telegram.ts

@@ -8,6 +8,12 @@ import type {
   WebhookVerificationResult,
 } from "../channels";
 import { AgentKitError } from "../errors";
+import {
+  CHANNEL_DOWNLOAD_TIMEOUT_MS,
+  CHANNEL_SEND_TIMEOUT_MS,
+  classifySendRequestError,
+  isRetryableReadRequestError,
+} from "./provider-fetch";
 
 export const telegramChannelAdapter: ChannelAdapter = {
   type: "telegram",
@@ -221,6 +227,7 @@ export async function sendTelegramMessage(
 
   try {
     response = await fetcher(actualRequest.url, {
+      signal: AbortSignal.timeout(CHANNEL_SEND_TIMEOUT_MS),
       method: actualRequest.method,
       headers: {
         "Content-Type": "application/json",
@@ -228,13 +235,14 @@ export async function sendTelegramMessage(
       body: JSON.stringify(actualRequest.body),
     });
   } catch (error) {
+    const failure = classifySendRequestError(error);
     const errorMessage = (error instanceof Error ? error.message : String(error)).replace(token, "<redacted>");
 
     return {
       ok: false,
-      retryable: true,
-      code: "channel_provider_unavailable",
-      message: `Telegram sendMessage request failed before a response: ${errorMessage}`,
+      retryable: failure.retryable,
+      code: failure.code,
+      message: `Telegram sendMessage request ${failure.reason}: ${errorMessage}`,
       providerRequestId: request.idempotencyKey,
       providerMetadata: {
         method: request.method,
@@ -331,11 +339,14 @@ export async function downloadTelegramMedia(
   try {
     const url = new URL(`/bot${token}/getFile`, telegramApiBaseUrl(input.secrets));
     url.searchParams.set("file_id", audio.providerMediaId);
-    fileResponse = await fetcher(url.href, { method: "GET" });
+    fileResponse = await fetcher(url.href, {
+      method: "GET",
+      signal: AbortSignal.timeout(CHANNEL_DOWNLOAD_TIMEOUT_MS),
+    });
   } catch (error) {
     return {
       ok: false,
-      retryable: true,
+      retryable: isRetryableReadRequestError(error),
       code: "channel_provider_unavailable",
       message: `Telegram getFile request failed before a response: ${redactToken(
         error instanceof Error ? error.message : String(error),
@@ -397,11 +408,14 @@ export async function downloadTelegramMedia(
   let mediaResponse: Response;
 
   try {
-    mediaResponse = await fetcher(`${telegramApiBaseUrl(input.secrets)}/file/bot${token}/${filePath}`, { method: "GET" });
+    mediaResponse = await fetcher(`${telegramApiBaseUrl(input.secrets)}/file/bot${token}/${filePath}`, {
+      method: "GET",
+      signal: AbortSignal.timeout(CHANNEL_DOWNLOAD_TIMEOUT_MS),
+    });
   } catch (error) {
     return {
       ok: false,
-      retryable: true,
+      retryable: isRetryableReadRequestError(error),
       code: "channel_provider_unavailable",
       message: `Telegram file download failed before a response: ${redactToken(
         error instanceof Error ? error.message : String(error),
@@ -591,8 +605,8 @@ async function readResponseBytesWithLimit(
     }
   | {
       ok: false;
-      retryable: false;
-      code: "channel_audio_too_large";
+      retryable: boolean;
+      code: "channel_audio_too_large" | "channel_provider_unavailable";
       message: string;
       providerMetadata?: Record<string, unknown>;
     }
@@ -613,7 +627,18 @@ async function readResponseBytesWithLimit(
   }
 
   if (!response.body) {
-    const audio = new Uint8Array(await response.arrayBuffer());
+    let audio: Uint8Array;
+
+    try {
+      audio = new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      return {
+        ok: false,
+        retryable: true,
+        code: "channel_provider_unavailable",
+        message: `Media download response could not be read: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
 
     if (audio.byteLength > maxBytes) {
       return {
@@ -659,6 +684,14 @@ async function readResponseBytesWithLimit(
 
       chunks.push(chunk.value);
     }
+  } catch (error) {
+    await reader.cancel().catch(() => undefined);
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Media download response could not be read: ${error instanceof Error ? error.message : String(error)}`,
+    };
   } finally {
     reader.releaseLock();
   }