pn-new-crm/src/app/api/webhooks/documenso/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { createHash } from 'crypto';

import { db } from '@/lib/db';
import { verifyDocumensoSecret } from '@/lib/services/documenso-webhook';
import { listDocumensoWebhookSecrets } from '@/lib/services/port-config';
import {
  handleRecipientSigned,
  handleDocumentCompleted,
  handleDocumentExpired,
  handleDocumentOpened,
  handleDocumentRejected,
  handleDocumentCancelled,
} from '@/lib/services/documents.service';
import { logger } from '@/lib/logger';
import { createAuditLog } from '@/lib/audit';
import { checkRateLimit, rateLimiters } from '@/lib/rate-limit';
import { captureErrorEvent } from '@/lib/services/error-events.service';

// BR-024: Dedup via signatureHash unique index on documentEvents
// Always return 200 from webhook (webhook best practice)

// Documenso emits Prisma enum names on the wire (e.g. "DOCUMENT_SIGNED").
// The UI displays them as lowercase-dotted ("document.signed") but the JSON
// body uses the enum value as-is. Normalize both forms in case 2.x ever flips.
function canonicalizeEvent(event: string): string {
  return event.toUpperCase().replace(/\./g, '_');
}

type DocumensoRecipient = {
  email: string;
  signingStatus?: string;
  readStatus?: string;
  signedAt?: string | null;
};

type DocumensoWebhookBody = {
  event: string;
  payload: {
    id: number | string;
    recipients?: DocumensoRecipient[];
  };
};

export async function POST(req: NextRequest): Promise<NextResponse> {
  let rawBody: string;

  try {
    rawBody = await req.text();
  } catch {
    return NextResponse.json({ ok: false }, { status: 200 });
  }

  // Documenso v1.13 + 2.x send the secret in plaintext via X-Documenso-Secret.
  // Resolve the matching port by trying each configured per-port secret
  // (plus the global env fallback) with timing-safe comparison. The
  // resolved portId, when non-null, is threaded into handleDocumentExpired
  // so two ports sharing a documensoId can't cross-mutate (auditor-D §22).
  const providedSecret = req.headers.get('x-documenso-secret') ?? '';
  const secrets = await listDocumensoWebhookSecrets();
  let matchedPortId: string | null = null;
  let matched = false;
  for (const entry of secrets) {
    if (verifyDocumensoSecret(providedSecret, entry.secret)) {
      matched = true;
      matchedPortId = entry.portId;
      break;
    }
  }
  if (!matched) {
    const callerIp =
      req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
      req.headers.get('x-real-ip') ??
      'unknown';
    // Rate-limit per IP. Real Documenso traffic won't fail the secret
    // check, so any traffic here is enumeration / brute-force; we cap
    // it sharply to keep audit-log volume bounded too.
    const rl = await checkRateLimit(callerIp, rateLimiters.webhookBadSecret);
    logger.warn(
      { providedLen: providedSecret.length, ip: callerIp, allowed: rl.allowed },
      'Invalid Documenso webhook secret',
    );
    if (rl.allowed) {
      void createAuditLog({
        userId: null,
        portId: null,
        action: 'webhook_failed',
        entityType: 'webhook_inbound',
        entityId: 'documenso',
        metadata: {
          reason: 'invalid_secret',
          providedLen: providedSecret.length,
        },
        ipAddress: callerIp,
        userAgent: req.headers.get('user-agent') ?? '',
        severity: 'warning',
        source: 'webhook',
      });
    }
    // Always return 200 (webhook best-practice — don't leak signal).
    return NextResponse.json({ ok: false, error: 'Invalid secret' }, { status: 200 });
  }

  // Compute deduplication hash
  const signatureHash = createHash('sha256').update(rawBody).digest('hex');

  let parsed: DocumensoWebhookBody;

  try {
    parsed = JSON.parse(rawBody) as DocumensoWebhookBody;
  } catch {
    logger.warn('Failed to parse Documenso webhook payload');
    return NextResponse.json({ ok: false }, { status: 200 });
  }

  // Replay guard: if any event with this hash already exists, skip.
  try {
    const existing = await db.query.documentEvents.findFirst({
      where: (de, { eq }) => eq(de.signatureHash, signatureHash),
    });

    if (existing) {
      logger.info({ signatureHash }, 'Duplicate Documenso webhook - skipping');
      return NextResponse.json({ ok: true }, { status: 200 });
    }
  } catch (err) {
    logger.error({ err }, 'Failed to check duplicate webhook');
  }

  const event = canonicalizeEvent(parsed.event);
  const documensoId = String(parsed.payload?.id ?? '');
  const recipients = parsed.payload?.recipients ?? [];

  if (!documensoId) {
    logger.warn({ event }, 'Documenso webhook missing payload.id');
    return NextResponse.json({ ok: true }, { status: 200 });
  }

  // Every handler accepts an optional `portId` and refuses to mutate when
  // the lookup is ambiguous across multiple ports without one. Forward
  // the secret-resolved portId everywhere — not just the expired path —
  // so signed/completed/opened/rejected/cancelled events can't flip a
  // foreign-tenant document via documensoId reuse.
  const portScope = matchedPortId ? { portId: matchedPortId } : {};

  try {
    switch (event) {
      case 'DOCUMENT_SIGNED':
      case 'DOCUMENT_RECIPIENT_COMPLETED':
      case 'RECIPIENT_SIGNED': {
        // v1.13 fires DOCUMENT_SIGNED per recipient sign;
        // 2.x fires DOCUMENT_RECIPIENT_COMPLETED for the same semantics.
        // Some 2.x deployments emit RECIPIENT_SIGNED as a v2-flavoured alias —
        // log when we see it (telemetry) and route to the same handler so v2
        // deployments don't silently drop per-recipient signs.
        if (event === 'RECIPIENT_SIGNED') {
          logger.info(
            { event, documensoId },
            'Documenso v2 RECIPIENT_SIGNED received — routing to recipient-signed handler',
          );
        }
        const signedRecipients = recipients.filter(
          (r) => r.signingStatus === 'SIGNED' || Boolean(r.signedAt),
        );
        for (const r of signedRecipients) {
          await handleRecipientSigned({
            documentId: documensoId,
            recipientEmail: r.email,
            signatureHash: `${signatureHash}:signed:${r.email}`,
            ...portScope,
          });
        }
        break;
      }

      case 'DOCUMENT_OPENED':
      case 'RECIPIENT_VIEWED': {
        // Documenso v1 sends `readStatus: 'OPENED'`; v2 has used both
        // upper and lower case across releases and may omit the field
        // entirely (the event itself signals the open). Treat the event
        // as the signal: dispatch a per-recipient open for every
        // recipient on the document so v2 deployments stop silently
        // dropping opens.
        //
        // RECIPIENT_VIEWED is the v2-flavoured alias for the same semantics
        // — log when we see it (telemetry) and route to the same handler.
        if (event === 'RECIPIENT_VIEWED') {
          logger.info(
            { event, documensoId },
            'Documenso v2 RECIPIENT_VIEWED received — routing to document-opened handler',
          );
        }
        const openedRecipients = recipients.filter(
          (r) => !r.readStatus || String(r.readStatus).toUpperCase() === 'OPENED',
        );
        for (const r of openedRecipients) {
          await handleDocumentOpened({
            documentId: documensoId,
            recipientEmail: r.email,
            signatureHash: `${signatureHash}:opened:${r.email}`,
            ...portScope,
          });
        }
        break;
      }

      case 'DOCUMENT_COMPLETED':
        await handleDocumentCompleted({ documentId: documensoId, ...portScope });
        break;

      case 'DOCUMENT_REJECTED':
      case 'DOCUMENT_DECLINED': {
        // Documenso v2 distinguishes Decline (recipient refuses to sign) from
        // Reject (admin cancels). Both currently map to the same "rejected"
        // terminal state in our domain — `handleDocumentRejected` records who
        // refused and freezes the workflow. Product may later refine
        // downstream UX (different audit tags / notifications), but the
        // storage shape is identical for now so they share a handler.
        const rejecting = recipients.find(
          (r) => r.signingStatus === 'REJECTED' || r.signingStatus === 'DECLINED',
        );
        await handleDocumentRejected({
          documentId: documensoId,
          recipientEmail: rejecting?.email,
          signatureHash,
          ...portScope,
        });
        break;
      }

      case 'DOCUMENT_CANCELLED':
        await handleDocumentCancelled({ documentId: documensoId, signatureHash, ...portScope });
        break;

      case 'DOCUMENT_EXPIRED':
        await handleDocumentExpired({ documentId: documensoId, ...portScope });
        break;

      case 'DOCUMENT_REMINDER_SENT':
        // Documenso auto-reminded a recipient. We don't mutate state — the
        // reminder is informational. Structured log line is enough for
        // telemetry without polluting the audit_logs table on every
        // auto-reminder Documenso sends across all ports.
        logger.info(
          {
            documensoId,
            recipients: recipients.map((r) => r.email),
            ...portScope,
          },
          'Documenso auto-reminder sent',
        );
        break;

      case 'DOCUMENT_CREATED':
      case 'DOCUMENT_SENT':
        // Created + sent are informational — we initiated these from our
        // side so the state is already authoritative in our DB. Log for
        // forward-compat / out-of-band-creation telemetry.
        logger.info({ event, documensoId, ...portScope }, 'Documenso lifecycle event');
        break;

      default:
        logger.info({ event }, 'Unhandled Documenso webhook event type');
    }
  } catch (err) {
    logger.error({ err, event }, 'Error processing Documenso webhook');
    // The audit caught that webhook handlers were the only API surface
    // bypassing the platform-error pipeline — admin/errors was silent on
    // Documenso webhook crashes. Pipe them in so they surface alongside
    // every other 5xx.
    void captureErrorEvent({
      statusCode: 500,
      error: err,
      metadata: { source: 'webhook', provider: 'documenso', event },
    });
  }

  return NextResponse.json({ ok: true }, { status: 200 });
}