@andreprado/agentkit 0.1.0-alpha.9 → 0.1.0

package/src/runtime/channels/generic-webhook.ts

@@ -0,0 +1,974 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpsRequest } from "node:https";
+import type { LookupFunction } from "node:net";
+import { Readable } from "node:stream";
+
+import type { GenericWebhookOutputChannelConfig } from "../../index";
+import type { ChannelAdapter, ChannelSendInput, ChannelSendResult, RawWebhookEvent } from "../channels";
+import { AgentKitError } from "../errors";
+
+const DEFAULT_SECRET_NAME = "AGENTKIT_WEBHOOK_SECRET";
+const DEFAULT_OUTPUT_HMAC_HEADER = "X-AgentKit-Webhook-Signature";
+const MAX_OUTPUT_RESPONSE_BYTES = 64_000;
+
+export const genericWebhookChannelAdapter: ChannelAdapter = {
+  type: "webhook",
+  provider: "generic",
+  requiredSecrets: [DEFAULT_SECRET_NAME],
+  verifyWebhook(input) {
+    const expected = input.secrets[DEFAULT_SECRET_NAME];
+
+    if (!expected) {
+      return {
+        ok: false,
+        code: "channel_secret_missing",
+        message: `Secret ${DEFAULT_SECRET_NAME} is not set for this channel.`,
+      };
+    }
+
+    const signature = input.headers.get("x-agentkit-webhook-signature") ?? input.headers.get("x-agentkit-signature");
+
+    if (signature) {
+      const expectedSignature = `sha256=${createHmac("sha256", expected).update(input.rawBody).digest("hex")}`;
+
+      if (constantTimeEqual(signature.trim(), expectedSignature)) {
+        return { ok: true };
+      }
+
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Generic webhook HMAC signature did not match.",
+      };
+    }
+
+    const bearer = readBearerToken(input.headers.get("authorization"));
+    const headerToken =
+      input.headers.get("x-agentkit-webhook-secret") ??
+      input.headers.get("x-agentkit-channel-token") ??
+      input.headers.get("x-agentkit-webhook-token");
+
+    if (constantTimeEqual(bearer, expected) || constantTimeEqual(headerToken ?? "", expected)) {
+      return { ok: true };
+    }
+
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Generic webhook token did not match.",
+    };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const eventId = readFirstScalar(body, ["event_id", "eventId", "id"]) ?? readNestedMessageId(body);
+
+    if (!eventId) {
+      throw new AgentKitError("channel_payload_invalid", "Generic webhook payload is missing event_id.");
+    }
+
+    const text = readMessageText(body);
+    const identitySource =
+      readFirstScalar(body, [
+        "external_id",
+        "externalId",
+        "user_id",
+        "userId",
+        "contact_id",
+        "contactId",
+        "conversation_id",
+        "conversationId",
+        "client_id",
+        "clientId",
+        "visitor_id",
+        "visitorId",
+        "source_id",
+        "sourceId",
+      ]) ?? `event:${eventId}`;
+    const identityKey = `webhook:generic:identity:${sha256(identitySource).slice(0, 32)}`;
+    const base = {
+      type: "webhook" as const,
+      provider: "generic" as const,
+      providerEventId: eventId,
+      dedupeKey: `webhook:generic:${input.channelId}:${eventId}`,
+      externalIdentity: {
+        key: identityKey,
+        redactedDisplay: identityKey,
+      },
+      receivedAt: input.receivedAt,
+    };
+
+    if (!text) {
+      return [
+        {
+          ...base,
+          kind: "unsupported" as const,
+          unsupportedReason: "unsupported_message_type:missing_text",
+        },
+      ];
+    }
+
+    return [
+      {
+        ...base,
+        kind: "message" as const,
+        message: {
+          role: "user" as const,
+          contentType: "text" as const,
+          content: text,
+          providerMessageId: readNestedMessageId(body) ?? eventId,
+        },
+      },
+    ];
+  },
+  async sendMessage(input) {
+    if (isGenericWebhookOutputChannel(input.channel)) {
+      return sendGenericWebhookOutputMessage(input, input.channel);
+    }
+
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: buildGenericWebhookProviderRequestId(input),
+    };
+  },
+  getStatus() {
+    return {
+      status: "connected",
+      checkedAt: new Date().toISOString(),
+      providerMetadata: {
+        outbound: "stubbed",
+      },
+    };
+  },
+};
+
+type GenericWebhookOutputRequest = {
+  method: "POST";
+  url: string;
+  headers: Record<string, string>;
+  body: Record<string, unknown>;
+  idempotencyKey: string;
+};
+
+type GenericWebhookOutputFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type GenericWebhookOutputResolver = (hostname: string) => Promise<string[]>;
+type GenericWebhookOutputResolvedUrl = {
+  href: string;
+  address: string;
+  family: 4 | 6;
+};
+type GenericWebhookOutputRequestInit = {
+  method: "POST";
+  headers: Record<string, string>;
+  body: string;
+  redirect: "manual";
+  signal: AbortSignal;
+};
+
+export function buildGenericWebhookOutputRequest(
+  input: ChannelSendInput,
+  channel: GenericWebhookOutputChannelConfig,
+): GenericWebhookOutputRequest {
+  if (input.message.contentType !== "text") {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook output supports only text channel messages.");
+  }
+
+  const rawUrl = input.secrets[channel.urlSecret];
+
+  if (!rawUrl) {
+    throw new AgentKitError("channel_secret_missing", `Secret ${channel.urlSecret} is missing.`);
+  }
+
+  const idempotencyKey = buildGenericWebhookOutputRequestId(input);
+  const body = {
+    event_id: idempotencyKey,
+    conversation_id: input.conversationId,
+    channel_id: input.channelId,
+    external_identity: input.externalIdentity.key,
+    message: {
+      role: "assistant",
+      content_type: "text",
+      content: input.message.content,
+    },
+  };
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "X-AgentKit-Event-ID": idempotencyKey,
+  };
+
+  applyGenericWebhookOutputAuthHeaders({
+    auth: channel.auth,
+    secrets: input.secrets,
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  return {
+    method: "POST",
+    url: validateGenericWebhookOutputUrl(rawUrl),
+    headers,
+    body,
+    idempotencyKey,
+  };
+}
+
+export async function sendGenericWebhookOutputMessage(
+  input: ChannelSendInput,
+  channel: GenericWebhookOutputChannelConfig,
+  fetcher?: GenericWebhookOutputFetch,
+  resolver: GenericWebhookOutputResolver = resolveGenericWebhookOutputAddresses,
+): Promise<ChannelSendResult> {
+  let request: GenericWebhookOutputRequest;
+  let resolvedUrl: GenericWebhookOutputResolvedUrl;
+
+  try {
+    request = buildGenericWebhookOutputRequest(input, channel);
+
+    if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+      return {
+        ok: true,
+        status: "stubbed",
+        providerRequestId: request.idempotencyKey,
+        providerMetadata: redactedGenericWebhookOutputRequest(request),
+      };
+    }
+
+    resolvedUrl = await validateGenericWebhookOutputResolvedUrl(request.url, resolver);
+  } catch (error) {
+    return genericWebhookOutputFailureFromError(error);
+  }
+
+  let response: Response;
+  const requestInit: GenericWebhookOutputRequestInit = {
+    method: request.method,
+    headers: request.headers,
+    body: JSON.stringify(request.body),
+    redirect: "manual",
+    signal: AbortSignal.timeout(15_000),
+  };
+
+  try {
+    response = fetcher
+      ? await fetcher(resolvedUrl.href, requestInit)
+      : await fetchGenericWebhookOutputResponse(resolvedUrl, requestInit);
+  } catch (error) {
+    if (error instanceof AgentKitError) {
+      return {
+        ...genericWebhookOutputFailureFromError(error),
+        providerRequestId: request.idempotencyKey,
+        providerMetadata: redactedGenericWebhookOutputRequest(request),
+      };
+    }
+
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Generic webhook output request failed before a response: ${redactGenericWebhookOutputText(
+        error instanceof Error ? error.message : String(error),
+        input.secrets,
+      )}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: redactedGenericWebhookOutputRequest(request),
+    };
+  }
+
+  const payload = await readGenericWebhookOutputResponseBody(response);
+  const providerMessageId = readGenericWebhookOutputProviderMessageId(payload) ?? request.idempotencyKey;
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: response.status === 429 || response.status >= 500,
+      code: "channel_send_failed",
+      message: redactGenericWebhookOutputText(readGenericWebhookOutputErrorMessage(payload, response.status), input.secrets),
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        ...redactedGenericWebhookOutputRequest(request),
+        status: response.status,
+        body: redactGenericWebhookOutputValue(payload, input.secrets),
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: request.idempotencyKey,
+    providerMessageId,
+    providerMetadata: {
+      ...redactedGenericWebhookOutputRequest(request),
+      status: response.status,
+      body: redactGenericWebhookOutputValue(payload, input.secrets),
+    },
+  };
+}
+
+function buildGenericWebhookProviderRequestId(input: ChannelSendInput): string {
+  return `webhook:generic:${input.channelId}:${input.conversationId}`;
+}
+
+function buildGenericWebhookOutputRequestId(input: ChannelSendInput): string {
+  return `webhook:generic:${input.channelId}:${input.deliveryId ?? input.jobId ?? randomUUID()}`;
+}
+
+function isGenericWebhookOutputChannel(value: unknown): value is GenericWebhookOutputChannelConfig {
+  return (
+    isRecord(value) &&
+    value.type === "webhook" &&
+    value.provider === "generic" &&
+    value.direction === "outbound" &&
+    typeof value.urlSecret === "string" &&
+    isRecord(value.auth)
+  );
+}
+
+function applyGenericWebhookOutputAuthHeaders(input: {
+  auth: GenericWebhookOutputChannelConfig["auth"];
+  secrets: Record<string, string>;
+  headers: Record<string, string>;
+  body: string;
+}): void {
+  if (input.auth.type === "none") {
+    return;
+  }
+
+  if (input.auth.type === "bearer") {
+    const token = input.secrets[input.auth.tokenSecret];
+
+    if (!token) {
+      throw new AgentKitError("channel_secret_missing", `Secret ${input.auth.tokenSecret} is missing.`);
+    }
+
+    input.headers.Authorization = `Bearer ${token}`;
+    return;
+  }
+
+  if (input.auth.type === "header") {
+    const value = input.secrets[input.auth.valueSecret];
+
+    if (!value) {
+      throw new AgentKitError("channel_secret_missing", `Secret ${input.auth.valueSecret} is missing.`);
+    }
+
+    input.headers[input.auth.headerName] = value;
+    return;
+  }
+
+  const secret = input.secrets[input.auth.secret];
+
+  if (!secret) {
+    throw new AgentKitError("channel_secret_missing", `Secret ${input.auth.secret} is missing.`);
+  }
+
+  input.headers[input.auth.headerName ?? DEFAULT_OUTPUT_HMAC_HEADER] =
+    `sha256=${createHmac("sha256", secret).update(input.body).digest("hex")}`;
+}
+
+function genericWebhookOutputFailureFromError(error: unknown): ChannelSendResult {
+  if (error instanceof AgentKitError) {
+    if (error.code === "channel_provider_unavailable") {
+      return {
+        ok: false,
+        retryable: true,
+        code: "channel_provider_unavailable",
+        message: error.message,
+      };
+    }
+
+    return {
+      ok: false,
+      retryable: false,
+      code: error.code === "channel_secret_missing" ? "channel_secret_missing" : "channel_send_failed",
+      message: error.message,
+    };
+  }
+
+  return {
+    ok: false,
+    retryable: false,
+    code: "channel_send_failed",
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+function validateGenericWebhookOutputUrl(rawUrl: string): string {
+  let url: URL;
+
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook output URL must be a valid HTTPS URL.");
+  }
+
+  if (url.protocol !== "https:") {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook output URL must use HTTPS.");
+  }
+
+  if (url.username || url.password) {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook output URL must not include credentials.");
+  }
+
+  if (isBlockedGenericWebhookOutputHost(url.hostname)) {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook output URL host is not allowed.");
+  }
+
+  return url.href;
+}
+
+async function validateGenericWebhookOutputResolvedUrl(
+  rawUrl: string,
+  resolver: GenericWebhookOutputResolver,
+): Promise<GenericWebhookOutputResolvedUrl> {
+  const href = validateGenericWebhookOutputUrl(rawUrl);
+  const url = new URL(href);
+  let addresses: string[];
+
+  try {
+    addresses = await resolver(url.hostname);
+  } catch (error) {
+    throw new AgentKitError(
+      "channel_provider_unavailable",
+      `Generic webhook output URL host could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (addresses.length === 0) {
+    throw new AgentKitError("channel_provider_unavailable", "Generic webhook output URL host did not resolve.");
+  }
+
+  for (const address of addresses) {
+    if (isBlockedGenericWebhookOutputHost(address)) {
+      throw new AgentKitError("channel_payload_invalid", "Generic webhook output URL host resolved to a blocked address.");
+    }
+  }
+
+  const address = normalizeGenericWebhookOutputHost(addresses[0]);
+
+  return {
+    href,
+    address,
+    family: parseIpv4Octets(address) ? 4 : 6,
+  };
+}
+
+function fetchGenericWebhookOutputResponse(
+  resolvedUrl: GenericWebhookOutputResolvedUrl,
+  init: GenericWebhookOutputRequestInit,
+): Promise<Response> {
+  const url = new URL(resolvedUrl.href);
+  const lookup: LookupFunction = (_hostname, _options, callback) => {
+    callback(null, resolvedUrl.address, resolvedUrl.family);
+  };
+
+  return new Promise((resolve, reject) => {
+    const request = httpsRequest(
+      url,
+      {
+        method: init.method,
+        headers: init.headers,
+        lookup,
+        signal: init.signal,
+      },
+      (response) => {
+        try {
+          assertAllowedGenericWebhookOutputRemoteAddress(response.socket.remoteAddress);
+        } catch (error) {
+          response.destroy(error instanceof Error ? error : new Error(String(error)));
+          reject(error);
+          return;
+        }
+
+        resolve(
+          new Response(Readable.toWeb(response) as unknown as ReadableStream<Uint8Array>, {
+            status: response.statusCode ?? 502,
+            headers: headersFromIncomingMessage(response.headers),
+          }),
+        );
+      },
+    );
+
+    request.on("socket", (socket) => {
+      const validateSocket = () => {
+        try {
+          assertAllowedGenericWebhookOutputRemoteAddress(socket.remoteAddress);
+        } 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 assertAllowedGenericWebhookOutputRemoteAddress(address: string | undefined): void {
+  if (!address || isBlockedGenericWebhookOutputHost(address)) {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook output URL 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;
+}
+
+async function resolveGenericWebhookOutputAddresses(hostname: string): Promise<string[]> {
+  const host = normalizeGenericWebhookOutputHost(hostname);
+
+  if (parseIpv4Octets(host) || parseIpv6Segments(host)) {
+    return [host];
+  }
+
+  const records = await dnsLookup(host, {
+    all: true,
+    verbatim: true,
+  });
+
+  return records.map((record) => record.address);
+}
+
+function isBlockedGenericWebhookOutputHost(hostname: string): boolean {
+  const host = normalizeGenericWebhookOutputHost(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;
+}
+
+function normalizeGenericWebhookOutputHost(hostname: string): string {
+  return hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "").replace(/\.$/, "");
+}
+
+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;
+}
+
+function redactedGenericWebhookOutputRequest(request: GenericWebhookOutputRequest): Record<string, unknown> {
+  return {
+    method: request.method,
+    url: redactGenericWebhookOutputUrl(request.url),
+    body: request.body,
+  };
+}
+
+function redactGenericWebhookOutputUrl(rawUrl: string): string {
+  try {
+    const url = new URL(rawUrl);
+    url.search = url.search ? "?<redacted>" : "";
+    return url.href;
+  } catch {
+    return "<redacted>";
+  }
+}
+
+async function readGenericWebhookOutputResponseBody(response: Response): Promise<unknown> {
+  const text = await readGenericWebhookOutputResponseText(response, MAX_OUTPUT_RESPONSE_BYTES);
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+async function readGenericWebhookOutputResponseText(response: Response, maxBytes: number): Promise<string> {
+  const reader = response.body?.getReader();
+
+  if (!reader) {
+    return "";
+  }
+
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+
+  try {
+    while (true) {
+      const chunk = await reader.read();
+
+      if (chunk.done) {
+        break;
+      }
+
+      totalBytes += chunk.value.byteLength;
+
+      if (totalBytes > maxBytes) {
+        break;
+      }
+
+      chunks.push(chunk.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return new TextDecoder().decode(concatUint8Arrays(chunks));
+}
+
+function concatUint8Arrays(chunks: Uint8Array[]): Uint8Array {
+  const totalBytes = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const output = new Uint8Array(totalBytes);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return output;
+}
+
+function readGenericWebhookOutputProviderMessageId(payload: unknown): string | undefined {
+  if (!isRecord(payload)) {
+    return undefined;
+  }
+
+  return readFirstScalar(payload, ["message_id", "messageId", "event_id", "eventId", "id"]);
+}
+
+function readGenericWebhookOutputErrorMessage(payload: unknown, status: number): string {
+  if (isRecord(payload)) {
+    const error = payload.error;
+
+    if (typeof error === "string") {
+      return error;
+    }
+
+    if (isRecord(error)) {
+      const message = readFirstScalar(error, ["message", "detail", "code"]);
+
+      if (message) {
+        return message;
+      }
+    }
+
+    const message = readFirstScalar(payload, ["message", "detail", "code"]);
+
+    if (message) {
+      return message;
+    }
+  }
+
+  if (typeof payload === "string" && payload.trim()) {
+    return payload.trim();
+  }
+
+  return `Generic webhook output returned HTTP ${status}.`;
+}
+
+function redactGenericWebhookOutputText(value: string, secrets: Record<string, string>): string {
+  let redacted = value;
+
+  for (const secret of Object.values(secrets)) {
+    if (secret) {
+      redacted = redacted.split(secret).join("<redacted>");
+    }
+  }
+
+  return redacted;
+}
+
+function redactGenericWebhookOutputValue(value: unknown, secrets: Record<string, string>): unknown {
+  if (typeof value === "string") {
+    return redactGenericWebhookOutputText(value, secrets);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => redactGenericWebhookOutputValue(item, secrets));
+  }
+
+  if (isRecord(value)) {
+    const redacted: Record<string, unknown> = {};
+
+    for (const [key, entry] of Object.entries(value)) {
+      redacted[key] = /secret|token|authorization|password|api[_-]?key/i.test(key)
+        ? "<redacted>"
+        : redactGenericWebhookOutputValue(entry, secrets);
+    }
+
+    return redacted;
+  }
+
+  return value;
+}
+
+function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
+  const contentType = input.headers.get("content-type") ?? "";
+
+  if (contentType && !contentType.toLowerCase().includes("application/json")) {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook payload must use content-type application/json.");
+  }
+
+  try {
+    const parsed = JSON.parse(input.rawBody) as unknown;
+
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook payload must be valid JSON.", {
+      cause: error,
+    });
+  }
+
+  throw new AgentKitError("channel_payload_invalid", "Generic webhook payload must be a JSON object.");
+}
+
+function readMessageText(body: Record<string, unknown>): string | undefined {
+  const message = body.message;
+
+  if (typeof message === "string") {
+    return normalizeNonEmpty(message);
+  }
+
+  if (isRecord(message)) {
+    return readFirstScalar(message, ["text", "content", "body"]);
+  }
+
+  return readFirstScalar(body, ["text", "content", "prompt", "input"]);
+}
+
+function readNestedMessageId(body: Record<string, unknown>): string | undefined {
+  const message = body.message;
+  return isRecord(message) ? readFirstScalar(message, ["id", "message_id", "messageId"]) : undefined;
+}
+
+function readFirstScalar(value: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const field = value[key];
+
+    if (typeof field === "string") {
+      const normalized = normalizeNonEmpty(field);
+
+      if (normalized) {
+        return normalized;
+      }
+    }
+
+    if (typeof field === "number" && Number.isFinite(field)) {
+      return String(field);
+    }
+  }
+
+  return undefined;
+}
+
+function normalizeNonEmpty(value: string): string | undefined {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function readBearerToken(value: string | null): string {
+  if (!value?.startsWith("Bearer ")) {
+    return "";
+  }
+
+  return value.slice("Bearer ".length).trim();
+}
+
+function constantTimeEqual(left: string, right: string): boolean {
+  const leftDigest = createHash("sha256").update(left).digest();
+  const rightDigest = createHash("sha256").update(right).digest();
+  return timingSafeEqual(leftDigest, rightDigest) && left === right;
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}