@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

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

@@ -0,0 +1,682 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+
+import type { GenericWebhookOutputChannelConfig } from "../../index";
+import type { ChannelAdapter, ChannelSendInput, ChannelSendResult, RawWebhookEvent } from "../channels";
+import { AgentKitError } from "../errors";
+import {
+  isBlockedOutboundHost,
+  pinnedHttpsFetch,
+  resolveOutboundAddresses,
+  resolvePublicOutboundUrl,
+  type OutboundResolver,
+  type ResolvedOutboundUrl,
+} from "./net-guard";
+
+const DEFAULT_SECRET_NAME = "AGENTKIT_WEBHOOK_SECRET";
+const DEFAULT_OUTPUT_HMAC_HEADER = "X-AgentKit-Webhook-Signature";
+const MAX_OUTPUT_RESPONSE_BYTES = 64_000;
+const GENERIC_WEBHOOK_OUTPUT_URL_LABEL = "Generic webhook output URL";
+
+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 = OutboundResolver;
+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 = resolveOutboundAddresses,
+): Promise<ChannelSendResult> {
+  let request: GenericWebhookOutputRequest;
+  let resolvedUrl: ResolvedOutboundUrl;
+  // Started before DNS resolution so a stalled resolver counts against the deadline.
+  const signal = AbortSignal.timeout(15_000);
+
+  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, signal);
+  } 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,
+  };
+
+  try {
+    response = fetcher
+      ? await fetcher(resolvedUrl.href, requestInit)
+      : await pinnedHttpsFetch(resolvedUrl, requestInit, GENERIC_WEBHOOK_OUTPUT_URL_LABEL);
+  } 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 (isBlockedOutboundHost(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,
+  signal: AbortSignal,
+): Promise<ResolvedOutboundUrl> {
+  return resolvePublicOutboundUrl(validateGenericWebhookOutputUrl(rawUrl), GENERIC_WEBHOOK_OUTPUT_URL_LABEL, resolver, signal);
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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);
+}