test(audit-tier-5): webhook + cross-port test coverage

Closes the highest-priority gaps from audit HIGH §19 + MED §§20–21:

* New tests/integration/documenso-webhook-route.test.ts exercises the
  receiver route end-to-end: bad-secret rejection, valid-secret +
  DOCUMENT_SIGNED writes a documentEvents row, dedup via signatureHash
  refuses replays of the same body.
* tests/integration/documents-expired-webhook.test.ts gains a
  cross-port assertion: two ports holding the same documenso_id, port
  A receives the expired event, port B's document must NOT flip.  Made
  passing today by extending handleDocumentExpired to accept an
  optional `portId` and refuse to mutate when the lookup is ambiguous
  across multiple ports without one.
* tests/integration/custom-fields.test.ts gains a Cross-port Isolation
  describe: definitions in port A invisible from port B,
  setValues from port B with a port-A fieldId is rejected,
  getValues for a port-A entity from port B is empty.

Deferred: Tier 5.1 (new test suites for portal-auth / users /
email-accounts / document-sends / sales-email-config) is a multi-hour
test-writing task best handled in a dedicated PR.  Each service is
already covered indirectly via route + integration tests; the audit's
ask is direct service tests with cross-port negative paths, which
this commit doesn't address.

Test status: 1175/1175 vitest (was 1168), tsc clean.

Refs: docs/audit-comprehensive-2026-05-05.md HIGH §19 (auditor-J Issue 2)
+ MED §§20–21 (auditor-J Issues 3–4).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/integration/documenso-webhook-route.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Tests for the Documenso webhook receiver route at
+ * `src/app/api/webhooks/documenso/route.ts`.
+ *
+ * The receiver was previously only covered indirectly: the unit test
+ * `webhook-event-map.test.ts` validates the static event-name map, and
+ * `documents-expired-webhook.test.ts` calls handlers directly. Neither
+ * exercised the route's auth, dedup, dispatch loop, or 200-on-failure
+ * envelope. This file fills that gap.
+ *
+ * Refs: docs/audit-comprehensive-2026-05-05.md HIGH §19 (auditor-J Issue 2).
+ */
+import { describe, it, expect } from 'vitest';
+import { eq } from 'drizzle-orm';
+import { NextRequest } from 'next/server';
+
+import { POST as documensoWebhook } from '@/app/api/webhooks/documenso/route';
+import { db } from '@/lib/db';
+import { documents, documentEvents } from '@/lib/db/schema/documents';
+import { env } from '@/lib/env';
+import { makeClient, makePort } from '../helpers/factories';
+
+function buildRequest(body: Record<string, unknown>, secret: string): NextRequest {
+  return new NextRequest('http://localhost:3000/api/webhooks/documenso', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-documenso-secret': secret,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+describe('Documenso webhook route', () => {
+  it('returns 200 with ok:false when the secret header is missing or wrong', async () => {
+    const req = buildRequest(
+      { event: 'DOCUMENT_SIGNED', payload: { id: 'abc', recipients: [] } },
+      'wrong-secret',
+    );
+    const res = await documensoWebhook(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toMatchObject({ ok: false });
+  });
+
+  it('with a valid secret + DOCUMENT_SIGNED writes a documentEvents row', async () => {
+    const port = await makePort();
+    const client = await makeClient({ portId: port.id });
+
+    const documensoId = `docu-test-${Date.now()}`;
+    const [doc] = await db
+      .insert(documents)
+      .values({
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'eoi',
+        title: 'Webhook test EOI',
+        status: 'sent',
+        documensoId,
+        createdBy: 'seed',
+      })
+      .returning();
+
+    const req = buildRequest(
+      {
+        event: 'DOCUMENT_SIGNED',
+        payload: {
+          id: documensoId,
+          recipients: [{ email: 'signer@test.invalid', signingStatus: 'SIGNED' }],
+        },
+      },
+      env.DOCUMENSO_WEBHOOK_SECRET,
+    );
+    const res = await documensoWebhook(req);
+    expect(res.status).toBe(200);
+
+    const events = await db
+      .select()
+      .from(documentEvents)
+      .where(eq(documentEvents.documentId, doc!.id));
+    expect(events.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('replays of the same body are no-ops (signatureHash dedup)', async () => {
+    const port = await makePort();
+    const client = await makeClient({ portId: port.id });
+
+    const documensoId = `docu-dedup-${Date.now()}`;
+    const [doc] = await db
+      .insert(documents)
+      .values({
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'eoi',
+        title: 'Dedup test EOI',
+        status: 'sent',
+        documensoId,
+        createdBy: 'seed',
+      })
+      .returning();
+
+    const body = {
+      event: 'DOCUMENT_OPENED',
+      payload: {
+        id: documensoId,
+        recipients: [{ email: 'opener@test.invalid', readStatus: 'OPENED' }],
+      },
+    };
+
+    await documensoWebhook(buildRequest(body, env.DOCUMENSO_WEBHOOK_SECRET));
+    await documensoWebhook(buildRequest(body, env.DOCUMENSO_WEBHOOK_SECRET));
+
+    const events = await db
+      .select()
+      .from(documentEvents)
+      .where(eq(documentEvents.documentId, doc!.id));
+    // The route's `handleDocumentOpened` writes an event with type
+    // `'viewed'`. One row from the first call; the second should have
+    // been refused by the signatureHash dedup guard.
+    const viewedEvents = events.filter((e) => e.eventType === 'viewed');
+    expect(viewedEvents.length).toBe(1);
+  });
+});