Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

5.5 KB
Raw Blame
import * as crypto from 'crypto';
import { Repository } from 'typeorm';
import { withSafeFetch, redactSsrfError, isSsrfProtectionEnabled } from '../../../common/security/ssrf-guard';
import { type LoggerService } from '../../../common/services/logger.service';
import { WebhookDeliveryFailure } from '../entities/webhook-delivery-failure.entity';
import { recordWebhookDeliveryFailure, statusCodeFromError } from './record-delivery-failure';
import { subscriptionCoversEvent } from '../../../common/utils/wildcard-events';

/**
 * Drop operator-supplied custom headers that target the names the system sets (Content-Type,
 * User-Agent or any X-OpenWA-* header, in any spelling) so a webhook config cannot forge the
 * signature/event/idempotency headers. Dropping, not overriding, is what makes the system value
 * win: the HTTP client joins a case variant with the system one instead of replacing it.
 * Connection-level and framing headers are dropped too: the HTTP client owns them, undici throws on
 * several (failing every delivery) and a wrong Content-Length breaks the request.
 */
export function sanitizeCustomHeaders(custom: Record<string, string> | null | undefined): Record<string, string> {
  const safe: Record<string, string> = {};
  for (const [key, value] of Object.entries(custom ?? {})) {
    if (
      !/^(content-type|x-openwa-)/i.test(key) &&
      !/^(user-agent|connection|content-length|expect|keep-alive|te|trailer|transfer-encoding|upgrade)$/i.test(key)
    ) {
      safe[key] = value;
    }
  }
  return safe;
}

/**
 * Whether a webhook row as read now may still receive `event`: it exists, is active and subscribes to
 * the event or to '*' (minus WILDCARD_EXCLUDED_EVENTS; an events column that is not an array subscribes to nothing). Its filters are
 * not re-applied here, since they need the event data. Every path that delivers after the dispatch
 * moment (a queued job, a direct retry, an outbox replay) runs this against a fresh row, so a removed,
 * disabled or unsubscribed webhook stops receiving the event.
 */
export function isDeliverableWebhook<T extends { active: boolean; events: string[]; sessionId?: string }>(
  row: T | null | undefined,
  event: string,
  sessionId?: string,
): row is T {
  return (
    !!row &&
    (sessionId === undefined || row.sessionId === sessionId) &&
    row.active &&
    Array.isArray(row.events) &&
    subscriptionCoversEvent(row.events, event)
  );
}

/** HMAC-SHA256 over the exact pre-serialized body, prefixed for receiver-side verification. */
export function generateSignature(payload: string, secret: string): string {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  return `sha256=${hmac.digest('hex')}`;
}

/**
 * The headers of one delivery attempt: the webhook's custom headers first, then the system headers
 * (which always win), then the signature over `body` when the webhook has a secret. Built from the
 * webhook row in hand, so a caller holding a fresh row sends its current headers and secret.
 */
export function buildDeliveryHeaders(
  webhook: { headers?: Record<string, string> | null; secret?: string | null },
  event: string,
  idempotencyKey: string,
  deliveryId: string,
  body: string,
  retryCount = 0,
): Record<string, string> {
  const headers: Record<string, string> = {
    ...sanitizeCustomHeaders(webhook.headers),
    'Content-Type': 'application/json',
    'User-Agent': 'OpenWA-Webhook/1.0.0',
    'X-OpenWA-Event': event,
    'X-OpenWA-Idempotency-Key': idempotencyKey,
    'X-OpenWA-Delivery-Id': deliveryId,
    'X-OpenWA-Retry-Count': String(retryCount),
  };
  if (webhook.secret) {
    headers['X-OpenWA-Signature'] = generateSignature(body, webhook.secret);
  }
  return headers;
}

/**
 * One SSRF-guarded POST + response classification: a non-ok status throws `HTTP <status>: <statusText>`,
 * ok returns the status. This is the byte-level delivery core BOTH paths previously duplicated line
 * for line; extracting it keeps the two sinks one contract: same fetch, same guard, same error
 * shape, same timeout knob.
 */
export async function postWebhookPayload(
  url: string,
  body: string,
  headers: Record<string, string>,
  timeoutMs: number,
  fetch: typeof withSafeFetch = withSafeFetch,
): Promise<{ status: number; statusText: string }> {
  const { ok, status, statusText } = await fetch(
    url,
    {
      method: 'POST',
      headers,
      body,
      signal: AbortSignal.timeout(timeoutMs),
    },
    response => ({ ok: response.ok, status: response.status, statusText: response.statusText }),
    { guard: isSsrfProtectionEnabled() },
  );
  if (!ok) throw new Error(`HTTP ${status}: ${statusText}`);
  return { status, statusText };
}

/**
 * Record a terminal webhook delivery failure (all retries exhausted) to the durable table. Shared
 * wrapper so both paths write the identical row shape. Best-effort: never throws back into the
 * delivery result (the caller's semantics depend on that). Returns false when an identical failure
 * was already recorded, so the caller can keep the failure metric in step with the table.
 */
export async function recordTerminalFailure(
  failureRepository: Repository<WebhookDeliveryFailure>,
  logger: LoggerService,
  input: Omit<Parameters<typeof recordWebhookDeliveryFailure>[2], 'lastStatusCode' | 'lastError'> & { error: unknown },
): Promise<boolean | null> {
  const { error, ...row } = input;
  const errMessage = redactSsrfError(error);
  return recordWebhookDeliveryFailure(failureRepository, logger, {
    ...row,
    lastStatusCode: statusCodeFromError(errMessage),
    lastError: errMessage,
  });
}