Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

2.8 KB
Raw Blame
import { env } from "../../env";
import {
  OutboundUrlValidationError,
  parseOutboundUrl,
  resolveHost,
  validateOutboundUrlHost,
  type OutboundUrlValidationWhitelist,
} from "../outbound-url/validation";

export type WebhookValidationWhitelist = OutboundUrlValidationWhitelist;
export { resolveHost };

export const WEBHOOK_URL_VALIDATION_LOG_CONTEXT = "Webhook";
const DEFAULT_WEBHOOK_ALLOWED_PORTS = ["443", "80"] as const;

export type WebhookUrlValidationOptions = {
  allowedPorts?: readonly string[] | "any";
};

export function whitelistFromEnv(): WebhookValidationWhitelist {
  return {
    hosts: env.LANGFUSE_WEBHOOK_WHITELISTED_HOST || [],
    ips: env.LANGFUSE_WEBHOOK_WHITELISTED_IPS || [],
    ip_ranges: env.LANGFUSE_WEBHOOK_WHITELISTED_IP_SEGMENTS || [],
  };
}

/** webhookWhitelistFromEnv adds the webhook-only positive host list to the shared exemption list. */
export function webhookWhitelistFromEnv(): WebhookValidationWhitelist {
  return {
    ...whitelistFromEnv(),
    allowedHosts: env.LANGFUSE_WEBHOOK_ALLOWED_HOSTS,
  };
}

/**
 * Validates a webhook URL to prevent SSRF attacks by blocking internal/private IP addresses
 * Should be called when saving webhook URLs and before sending webhooks
 *
 * Security Note: This validation has a Time-of-Check-Time-of-Use (TOCTOU) vulnerability
 * where DNS can change between validation and actual HTTP request. For maximum security,
 * the HTTP client should also implement IP blocking at connection time.
 */
export async function validateWebhookURL(
  urlString: string,
  whitelist: WebhookValidationWhitelist = whitelistFromEnv(),
  options: WebhookUrlValidationOptions = {},
): Promise<void> {
  const url = parseOutboundUrl(urlString);

  // Coded, not bare Error: callers classify rejections off the `code` rather
  // than the message. validateBlobStorageEndpoint already does this for the
  // protocol check; these two were the only outbound-URL rejections in the repo
  // that reached callers uncoded, which silently excluded them from
  // customer-fault classification. Messages are unchanged.
  if (!["https:", "http:"].includes(url.protocol)) {
    throw new OutboundUrlValidationError(
      "protocol-not-allowed",
      "Only HTTP and HTTPS protocols are allowed",
    );
  }

  const allowedPorts = options.allowedPorts ?? DEFAULT_WEBHOOK_ALLOWED_PORTS;
  if (url.port && allowedPorts !== "any" && !allowedPorts.includes(url.port)) {
    throw new OutboundUrlValidationError(
      "port-not-allowed",
      "Only ports 80 and 443 are allowed",
    );
  }

  await validateOutboundUrlHost({
    url,
    whitelist,
    logContext: WEBHOOK_URL_VALIDATION_LOG_CONTEXT,
    // Preserve the existing webhook behavior: public IP literals must still
    // pass the same DNS-resolution path as hostname destinations.
    shouldSkipDnsCheckForLiteralIps: false,
  });
}