Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

17.2 KB
Raw Blame
import { Injectable, NotFoundException, BadRequestException, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { FindManyOptions, In, IsNull, LessThan, MoreThan, Not, Repository } from 'typeorm';
import { ConfigService } from '@nestjs/config';
import { Webhook } from './entities/webhook.entity';
import { WebhookDeliveryFailure } from './entities/webhook-delivery-failure.entity';
import { Session } from '../session/entities/session.entity';
import { CreateWebhookDto, UpdateWebhookDto } from './dto';
import { createLogger } from '../../common/services/logger.service';
import { resolveSessionScope } from '../../common/security/session-scope';
import { ListOptions, resolveListWindow } from '../../common/utils/paginate';
import { generateDeliveryId } from './utils/idempotency.util';
import { buildDeliveryHeaders } from './utils/deliver-once';
import {
  assertSafeFetchUrl,
  withSafeFetch,
  isSsrfProtectionEnabled,
  SsrfBlockedError,
  SSRF_BLOCKED_CLIENT_MESSAGE,
  redactSsrfError,
} from '../../common/security/ssrf-guard';
import { WebhookDeliveryService, WebhookPayload } from './webhook-delivery.service';

// Delivery-engine types (payload and queue job shapes) live on WebhookDeliveryService; re-exported
// here so existing importers (the queue processor) keep a single stable path.
export type { WebhookPayload, WebhookJobData } from './webhook-delivery.service';

/**
 * Upper bound on how many webhooks one session can register. One inbound event fans out to EVERY
 * registered webhook of the session, so an unbounded count multiplies per-event payload copies
 * (clones, outbound sockets, queued jobs). Default 16; override with WEBHOOK_MAX_PER_SESSION
 * (0 disables). Only NEW registrations above the cap are refused — existing ones are grandfathered.
 */
const DEFAULT_WEBHOOK_MAX_PER_SESSION = 16;

/**
 * Webhook registration and operational queries: CRUD, the test probe, and the delivery-failure
 * listing/retention. Event delivery itself (fan-out, queueing, retries, dead-lettering) lives on
 * WebhookDeliveryService; dispatch() here is the stable facade every event producer calls.
 */
@Injectable()
export class WebhookService implements OnModuleInit, OnModuleDestroy {
  private readonly logger = createLogger('WebhookService');
  private cleanupTimer?: ReturnType<typeof setInterval>;
  private payloadCleanupTimer?: ReturnType<typeof setInterval>;

  constructor(
    @InjectRepository(Webhook, 'data')
    private readonly webhookRepository: Repository<Webhook>,
    @InjectRepository(WebhookDeliveryFailure, 'data')
    private readonly failureRepository: Repository<WebhookDeliveryFailure>,
    @InjectRepository(Session, 'data')
    private readonly sessionRepository: Repository<Session>,
    private readonly configService: ConfigService,
    private readonly delivery: WebhookDeliveryService,
  ) {}

  /**
   * Periodically prune webhook_delivery_failures older than WEBHOOK_FAILURE_RETENTION_DAYS
   * (default 90; set <= 0 to disable). Runs once at startup, then daily. The table records every
   * failed or unsent delivery (a later successful delivery removes its row), so without this it grows
   * without bound under a receiver outage. (Mirrors AuditService's audit-log retention.)
   */
  onModuleInit(): void {
    this.schedulePayloadPrune();
    const parsed = Number.parseInt(process.env.WEBHOOK_FAILURE_RETENTION_DAYS ?? '', 10);
    const retentionDays = Number.isInteger(parsed) ? Math.max(0, parsed) : 90;
    if (retentionDays <= 0) {
      this.logger.log('Webhook delivery-failure retention disabled (WEBHOOK_FAILURE_RETENTION_DAYS <= 0)');
      return;
    }
    const runPrune = (): void => {
      this.pruneDeliveryFailures(retentionDays)
        .then(n => {
          if (n > 0) this.logger.log(`Pruned ${n} webhook delivery-failure(s) older than ${retentionDays} day(s)`);
        })
        .catch(err =>
          this.logger.error('Webhook delivery-failure cleanup failed', err instanceof Error ? err.stack : String(err)),
        );
    };
    runPrune(); // prune once at startup
    this.cleanupTimer = setInterval(runPrune, 24 * 60 * 60 * 1000);
    this.cleanupTimer.unref?.();
  }

  onModuleDestroy(): void {
    if (this.cleanupTimer) {
      clearInterval(this.cleanupTimer);
    }
    if (this.payloadCleanupTimer) {
      clearInterval(this.payloadCleanupTimer);
    }
  }

  /**
   * Delete delivery-failure rows older than the retention window. Returns the number removed.
   */
  async pruneDeliveryFailures(olderThanDays: number): Promise<number> {
    const cutoff = new Date();
    cutoff.setDate(cutoff.getDate() - olderThanDays);
    const result = await this.failureRepository.delete({ createdAt: LessThan(cutoff) });
    return result.affected || 0;
  }

  /**
   * Clear the replay payload of every failure row recorded more than `olderThanHours` ago; the row
   * itself stays for WEBHOOK_FAILURE_RETENTION_DAYS. 0 clears every stored payload. Returns the
   * number of rows cleared.
   */
  async pruneDeliveryFailurePayloads(olderThanHours: number): Promise<number> {
    const cutoff = new Date(Date.now() - olderThanHours * 60 * 60 * 1000);
    const result = await this.failureRepository.update(
      { payload: Not(IsNull()), createdAt: LessThan(cutoff) },
      { payload: null },
    );
    return result.affected || 0;
  }

  /**
   * WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS bounds how long a failure row holds a whole event body.
   * With the knob on, expired payloads are cleared at startup and then hourly. With it off (0, the
   * default) nothing new is stored, and one startup pass clears what an earlier setting left behind,
   * so turning the feature off also stops keeping the bodies it already stored.
   */
  private schedulePayloadPrune(): void {
    const hours = this.configService.get<number>('webhook.failurePayloadRetentionHours', 0);
    const runPrune = (): void => {
      this.pruneDeliveryFailurePayloads(hours)
        .then(n => {
          if (n > 0) this.logger.log(`Cleared the replay payload of ${n} webhook delivery-failure(s)`);
        })
        .catch(err =>
          this.logger.error(
            'Webhook delivery-failure payload cleanup failed',
            err instanceof Error ? err.stack : String(err),
          ),
        );
    };
    runPrune();
    if (hours > 0) {
      this.payloadCleanupTimer = setInterval(runPrune, 60 * 60 * 1000);
      this.payloadCleanupTimer.unref?.();
    }
  }

  /**
   * Reject an internal/unsafe webhook URL at registration, so a bad URL fails
   * synchronously with a 400 instead of silently failing at delivery time. Honors the same
   * SSRF flag + SSRF_ALLOWED_HOSTS escape-hatch as delivery. Maps the guard error to 400.
   */
  private async validateWebhookUrl(url: string): Promise<void> {
    // Credentials embedded in the URL (https://user:pass@host/hook) would be persisted with the row
    // and echoed into delivery logs and dead-letter rows, and are never legitimate for a webhook
    // target — reject outright rather than strip-and-accept. Runs regardless of the SSRF flag.
    let parsed: URL | null = null;
    try {
      parsed = new URL(url);
    } catch {
      // Unparseable: @IsUrl on the DTO (and the SSRF guard when enabled) owns that rejection.
    }
    if (parsed && (parsed.username !== '' || parsed.password !== '')) {
      throw new BadRequestException('Webhook URL must not contain credentials (userinfo)');
    }
    if (!isSsrfProtectionEnabled()) return;
    try {
      await assertSafeFetchUrl(url);
    } catch (error) {
      if (error instanceof SsrfBlockedError) {
        // The raw message names the resolved internal IP (a recon oracle): log it server-side, return generic.
        this.logger.warn(`Webhook URL rejected by SSRF guard: ${error.message}`);
        throw new BadRequestException(SSRF_BLOCKED_CLIENT_MESSAGE);
      }
      throw error;
    }
  }

  async create(sessionId: string, dto: CreateWebhookDto): Promise<Webhook> {
    // The webhooks.sessionId FK makes a missing session surface as a driver error (500) at save time;
    // check first so the caller gets a truthful 404 for a session that does not exist.
    const sessionExists = await this.sessionRepository.exists({ where: { id: sessionId } });
    if (!sessionExists) {
      throw new NotFoundException(`Session with id '${sessionId}' not found`);
    }
    await this.validateWebhookUrl(dto.url);
    // Per-session fan-out cap. Soft by design: a concurrent create can race the count check — the
    // cap bounds amplification, it is not a hard invariant. Webhooks already above the cap are left
    // alone; only NEW registrations are refused.
    const maxPerSession = this.configService.get<number>('webhook.maxPerSession', DEFAULT_WEBHOOK_MAX_PER_SESSION);
    if (maxPerSession > 0) {
      const existing = await this.webhookRepository.count({ where: { sessionId } });
      if (existing >= maxPerSession) {
        throw new BadRequestException(
          `Webhook limit reached for this session (${existing}/${maxPerSession}); delete one before registering another`,
        );
      }
    }
    const webhook = this.webhookRepository.create({
      sessionId,
      url: dto.url,
      events: dto.events || ['message.received'],
      secret: dto.secret || null,
      headers: dto.headers || {},
      filters: dto.filters ?? null,
      retryCount: dto.retryCount ?? 3,
    });

    // No transaction of its own: the session can be deleted while the URL is checked, and on SQLite's single shared
    // connection the rollback of the foreign key failure would discard what other callers wrote while it was open.
    const saved = await this.webhookRepository.save(webhook, { transaction: false });
    this.delivery.invalidateOptInSubscriptions(sessionId);
    return saved;
  }

  async findBySession(sessionId: string): Promise<Webhook[]> {
    return this.webhookRepository.find({
      where: { sessionId },
      order: { createdAt: 'DESC' },
    });
  }

  async findAll(allowedSessions?: string[] | null, opts: ListOptions = {}): Promise<Webhook[]> {
    // A session-restricted key only sees its own sessions' webhooks; an unrestricted key
    // (null/empty allowlist, e.g. ADMIN) sees all — mirroring the ApiKeyGuard allowedSessions model.
    const { limit, offset } = resolveListWindow(opts.limit, opts.offset);
    // `id` tiebreaks the second-resolution `createdAt` so a paged walk has a total order.
    const options: FindManyOptions<Webhook> = {
      order: { createdAt: 'DESC', id: 'DESC' },
      take: limit,
      skip: offset,
    };
    if (allowedSessions && allowedSessions.length > 0) {
      options.where = { sessionId: In(allowedSessions) };
    }
    return this.webhookRepository.find(options);
  }

  /**
   * Recently-failed webhook deliveries (most recent first), so an operator can see what was lost during
   * a receiver outage. ADMIN-only operational data; an optional sessionId narrows it. Bounded by the
   * shared pagination window. The calling key's allowedSessions is authoritative — the sessionId query
   * param may only narrow within it — because this endpoint takes sessionId as a query param, which the
   * ApiKeyGuard fence (route params only) does not scope; otherwise a session-restricted key could read
   * every session's failed-delivery URLs and errors.
   */
  async listDeliveryFailures(
    opts: ListOptions & { sessionId?: string } = {},
    allowedSessions?: string[] | null,
  ): Promise<Array<WebhookDeliveryFailure & { replayable: boolean }>> {
    const { limit, offset } = resolveListWindow(opts.limit, opts.offset);
    const sessionScope = resolveSessionScope(allowedSessions, opts.sessionId);
    if (sessionScope !== null && sessionScope.length === 0) return []; // requested session outside the key's scope
    const rows = await this.failureRepository.find({
      where: sessionScope ? { sessionId: In(sessionScope) } : {},
      // A receiver outage writes a burst of failures inside one second; `id` keeps the page order total.
      order: { createdAt: 'DESC', id: 'DESC' },
      take: limit,
      skip: offset,
    });
    // `payload` is select: false, so the page above never carries an event body. Which rows hold one
    // is a second, id-only read; with payload retention off no row does and it matches nothing.
    const replayable = new Set<string>();
    const hours = this.configService.get<number>('webhook.failurePayloadRetentionHours', 0);
    if (rows.length > 0 && hours > 0) {
      const withPayload = await this.failureRepository.find({
        select: { id: true },
        where: {
          id: In(rows.map(r => r.id)),
          payload: Not(IsNull()),
          attempts: MoreThan(0),
          idempotencyKey: Not(IsNull()),
          createdAt: MoreThan(new Date(Date.now() - hours * 60 * 60 * 1000)),
        },
      });
      for (const r of withPayload) replayable.add(r.id);
    }
    return rows.map(r => Object.assign(r, { replayable: replayable.has(r.id) }));
  }

  async findOne(sessionId: string, id: string): Promise<Webhook> {
    // Scope by the URL's sessionId so one session cannot read/act on another's webhook by id.
    // A wrong-session id resolves to not-found (no cross-session existence oracle).
    const webhook = await this.webhookRepository.findOne({ where: { id, sessionId } });
    if (!webhook) {
      throw new NotFoundException(`Webhook with id '${id}' not found`);
    }
    return webhook;
  }

  async update(sessionId: string, id: string, dto: UpdateWebhookDto): Promise<Webhook> {
    const webhook = await this.findOne(sessionId, id);
    const patch: Partial<Pick<Webhook, 'url' | 'events' | 'secret' | 'headers' | 'filters' | 'active' | 'retryCount'>> =
      {};

    // An unchanged URL is not re-validated: every edit re-sends it, so a webhook whose host stopped
    // resolving or became SSRF-blocked could not otherwise be deactivated or re-filtered. Delivery
    // still checks the URL on every send.
    if (dto.url !== undefined && dto.url !== webhook.url) {
      await this.validateWebhookUrl(dto.url);
      patch.url = dto.url;
    }
    if (dto.events !== undefined) patch.events = dto.events;
    // Normalize empty string to null (parity with create) — an empty secret means "no HMAC",
    // not a stored blank that silently disables signing while looking configured.
    if (dto.secret !== undefined) patch.secret = dto.secret || null;
    if (dto.headers !== undefined) patch.headers = dto.headers;
    if (dto.filters !== undefined) patch.filters = dto.filters;
    if (dto.active !== undefined) patch.active = dto.active;
    if (dto.retryCount !== undefined) patch.retryCount = dto.retryCount;
    if (Object.keys(patch).length === 0) return webhook;

    // A conditional UPDATE of the carried fields, not save() of the entity read above: save() would
    // re-insert a row a concurrent DELETE removed during the URL check, and write back stale values
    // of every column this request did not touch.
    const result = await this.webhookRepository.update({ id, sessionId }, patch);
    this.delivery.invalidateOptInSubscriptions(sessionId);
    if (!result.affected) throw new NotFoundException(`Webhook with id '${id}' not found`);
    return this.findOne(sessionId, id);
  }

  async delete(sessionId: string, id: string): Promise<void> {
    const webhook = await this.findOne(sessionId, id);
    await this.webhookRepository.remove(webhook);
    this.delivery.invalidateOptInSubscriptions(sessionId);
  }

  async test(sessionId: string, webhookId: string): Promise<{ success: boolean; statusCode?: number; error?: string }> {
    const webhook = await this.findOne(sessionId, webhookId);

    // Every test is a new event: a key derived from the webhook alone repeats on every call, so a
    // receiver that dedups on it acknowledges the second test without running its handler.
    const deliveryId = generateDeliveryId();
    const testPayload: WebhookPayload = {
      event: 'test',
      timestamp: new Date().toISOString(),
      sessionId,
      idempotencyKey: `test_${deliveryId}_${webhook.id}`,
      deliveryId,
      data: {
        message: 'This is a test webhook from OpenWA',
        webhookId: webhook.id,
        url: webhook.url,
      },
    };

    const body = JSON.stringify(testPayload);
    // The same header builder as a real delivery, so the probe tests what the receiver will get.
    const headers = buildDeliveryHeaders(webhook, 'test', testPayload.idempotencyKey, deliveryId, body);

    try {
      return await withSafeFetch(
        webhook.url,
        {
          method: 'POST',
          headers,
          body,
          // Use the configured WEBHOOK_TIMEOUT (single source of truth across queued/test/direct paths).
          signal: AbortSignal.timeout(this.configService.get<number>('webhook.timeout', 10000)),
        },
        response => ({ success: response.ok, statusCode: response.status }),
        { guard: isSsrfProtectionEnabled() },
      );
    } catch (error) {
      return {
        success: false,
        error: redactSsrfError(error, this.logger, 'webhook test'),
      };
    }
  }

  /**
   * Delivery facade: same entry point event producers have always called; the engine lives on
   * WebhookDeliveryService. Not async on purpose: a frame suspended on the engine would keep the
   * unshed event alive until every delivery settles.
   */
  dispatch(sessionId: string, event: string, data: Record<string, unknown>): Promise<void> {
    return this.delivery.dispatch(sessionId, event, data);
  }
}