fix(audit): comprehensive 2026-05-15 audit fix wave + Documenso v2 polish

Bundles the prior session's 50-task fix sweep (Documenso v2 + EOI/signing-
progress redesign + env-to-admin migration + dev-mode banner) with the
2026-05-18 audit fix wave (3 CRITICAL, 14 HIGH, 28 MEDIUM, 6 LOW).

CRITICAL (3):
 - C-01 interest-berths INNER JOIN -> LEFT JOIN so hard-deleted berths
   no longer silently drop interest links
 - C-02 /setup added to PUBLIC_PATHS; fresh-deploy bootstrap loop fixed
 - C-03 generic PATCH /interests/[id] no longer accepts pipelineStage —
   callers must go through /stage with the override-guard chain

HIGH (14/15):
 - H-01 explicit ON DELETE on previously-implicit NO ACTION FKs across
   interests/documents/reservations/reminders/invoices (migration 0070)
 - H-02 login page reads ?redirect= param with same-origin guard
 - H-03 CRM invite token moves to URL fragment so it never lands in
   nginx access logs / Referer headers
 - H-04 Retry-After header on sign-in-by-identifier 429 (RFC 6585 §4)
 - H-05 toggleAccount writes an audit row
 - H-06 upsertSetting masks any value whose key ends with _encrypted
 - H-07 archiveClient cascade fires per-interest audit rows
 - H-08 createSalesTransporter applies SMTP_TIMEOUTS
 - H-09 AppShell stable children — viewport flip across breakpoint no
   longer destroys in-progress form drafts
 - H-10 portal documents page swaps Unicode glyph status icons for
   Lucide CheckCircle2/XCircle/Circle + aria-labels
 - H-12 list components swap alert(...) for toast.warning(...)
 - H-13 5 icon-only buttons gain aria-label
 - H-14 parseBody treats empty bodies as {}
 - H-15 admin layout renders a 403 panel instead of silent bounce
 - H-11 not applicable — mobile-search-overlay IS a mobile bottom-sheet

MEDIUM (28+):
 - M-MT01-05 defense-in-depth port_id/parent-id filters on UPDATE/DELETE
   WHEREs across custom-fields, notes (all 6 entity types x update +
   delete), client-contacts, yacht ownerClient lookup, webhook reads
 - M-D01 documents-hub realtime event-name typo (file:created -> uploaded)
 - M-EM01 portal-auth emails thread through portId
 - M-EM02 sendEmail accepts cc/bcc params
 - M-EM04 notification_digest catalog key
 - M-IN01 portal presigned download URLs use 4h TTL
 - M-IN02 OpenAI client lazy-instantiated
 - M-IN04 stale pdfme refs updated to pdf-lib AcroForm
 - M-IN05 umami.testConnection returns tagged union
 - M-L01 reservations tenure_type unified with berths
 - M-L02 report-generators canonicalize stage values
 - M-AU01 audit log placeholder copy fixed
 - M-AU04 outcome_set / outcome_cleared distinct audit verbs
 - M-NEW-2 activity feed entity name+type separator
 - M-R01 portal allowlist narrowed + portal_session backstop in proxy
 - M-SC02 companies archived partial index
 - M-SC04 audit_logs.searchText documented as DB-managed
 - M-S01 storage_s3_access_key_encrypted admin field
 - M-U01 audit log empty state uses <EmptyState>
 - M-U09 invoice delete dialog -> <AlertDialog>
 - M-U10 toast.success on ClientForm + InterestForm create/edit
 - M-U11 settings-form-card logo preview alt text
 - M-U14 mobile topbar title on clients/yachts/interests/berths
 - M-U15 Invoices in mobile More-sheet

LOW (6/8):
 - L-AU01 severity defaults for security-relevant verbs
 - L-AU02 +13 missing actions in admin audit filter
 - L-AU03 +7 missing entity types in admin audit filter
 - L-AU04 dead listAuditLogs stubbed
 - L-D02 CLAUDE.md Owner-wins chain tightened

Bonus — Document detail polish (#67 partial, 3/6 deliverables):
 - state-aware action button per signer
 - watcher Add UI with display-name resolution
 - cleanSignerName cleanup

Prior session work bundled in:
 - Documenso v2 webhook + envelope-ID normalization + sequential signing
 - SigningProgress UI redesign (avatars, per-signer state, timestamps)
 - env->admin settings registry + RegistryDrivenForm + encrypted creds
 - Embedded-signing card + Test connection + setup help
 - Dev-mode EMAIL_REDIRECT_TO banner
 - Pipeline rules admin page
 - Sales email config card
 - Audit log details Sheet
 - EOI tab: Finalising badge, absolute timestamps, sequential indicator
 - Notes pipeline_stage_at_creation (migration 0069)
 - Documenso numeric ID dual-key webhook (migration 0068)
 - Dimensions criterion copy (migration 0067)

Tests: 1374/1374 vitest pass. tsc clean. lint clean.

See docs/AUDIT-FIX-WAVE-2026-05-18.md for the full progress report and
the user-input items still pending.

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

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

@@ -18,9 +18,30 @@ import { POST as documensoWebhook } from '@/app/api/webhooks/documenso/route';
 import { db } from '@/lib/db';
 import { documents, documentEvents } from '@/lib/db/schema/documents';
 import { interests } from '@/lib/db/schema/interests';
-import { env } from '@/lib/env';
+import { systemSettings } from '@/lib/db/schema/system';
+import { encrypt } from '@/lib/utils/encryption';
 import { makeClient, makePort } from '../helpers/factories';
 
+/**
+ * Seed a per-port webhook secret on the freshly-created test port and
+ * return both the port + the plaintext secret. The receiver iterates
+ * per-port secrets BEFORE the env fallback, so without this seed
+ * `listDocumensoWebhookSecrets()` resolves the matched port to whichever
+ * other port happens to share the env value (e.g. the dev `port-amador`
+ * row that ships with the .env example). Each test gets a unique
+ * secret so cross-test pollution can't happen either.
+ */
+async function seedWebhookSecret(portId: string): Promise<string> {
+  const secret = `test-webhook-${portId.slice(0, 8)}-${Date.now()}`.padEnd(48, 'x').slice(0, 48);
+  const envelope = JSON.parse(encrypt(secret));
+  await db.insert(systemSettings).values({
+    portId,
+    key: 'documenso_webhook_secret',
+    value: envelope,
+  });
+  return secret;
+}
+
 function buildRequest(body: Record<string, unknown>, secret: string): NextRequest {
   return new NextRequest('http://localhost:3000/api/webhooks/documenso', {
     method: 'POST',
@@ -46,6 +67,7 @@ describe('Documenso webhook route', () => {
 
   it('with a valid secret + DOCUMENT_SIGNED writes a documentEvents row', async () => {
     const port = await makePort();
+    const secret = await seedWebhookSecret(port.id);
     const client = await makeClient({ portId: port.id });
 
     const documensoId = `docu-test-${Date.now()}`;
@@ -70,7 +92,7 @@ describe('Documenso webhook route', () => {
           recipients: [{ email: 'signer@test.invalid', signingStatus: 'SIGNED' }],
         },
       },
-      env.DOCUMENSO_WEBHOOK_SECRET,
+      secret,
     );
     const res = await documensoWebhook(req);
     expect(res.status).toBe(200);
@@ -84,6 +106,7 @@ describe('Documenso webhook route', () => {
 
   it('DOCUMENT_COMPLETED for a reservation_agreement stamps reservationDocStatus on the linked interest', async () => {
     const port = await makePort();
+    const secret = await seedWebhookSecret(port.id);
     const client = await makeClient({ portId: port.id });
 
     const [interest] = await db
@@ -112,7 +135,7 @@ describe('Documenso webhook route', () => {
         event: 'DOCUMENT_COMPLETED',
         payload: { id: documensoId, recipients: [] },
       },
-      env.DOCUMENSO_WEBHOOK_SECRET,
+      secret,
     );
     const res = await documensoWebhook(req);
     expect(res.status).toBe(200);
@@ -124,6 +147,7 @@ describe('Documenso webhook route', () => {
 
   it('DOCUMENT_COMPLETED for a contract stamps contractDocStatus on the linked interest', async () => {
     const port = await makePort();
+    const secret = await seedWebhookSecret(port.id);
     const client = await makeClient({ portId: port.id });
 
     const [interest] = await db
@@ -152,7 +176,7 @@ describe('Documenso webhook route', () => {
         event: 'DOCUMENT_COMPLETED',
         payload: { id: documensoId, recipients: [] },
       },
-      env.DOCUMENSO_WEBHOOK_SECRET,
+      secret,
     );
     const res = await documensoWebhook(req);
     expect(res.status).toBe(200);
@@ -164,6 +188,7 @@ describe('Documenso webhook route', () => {
 
   it('replays of the same body are no-ops (signatureHash dedup)', async () => {
     const port = await makePort();
+    const secret = await seedWebhookSecret(port.id);
     const client = await makeClient({ portId: port.id });
 
     const documensoId = `docu-dedup-${Date.now()}`;
@@ -188,8 +213,8 @@ describe('Documenso webhook route', () => {
       },
     };
 
-    await documensoWebhook(buildRequest(body, env.DOCUMENSO_WEBHOOK_SECRET));
-    await documensoWebhook(buildRequest(body, env.DOCUMENSO_WEBHOOK_SECRET));
+    await documensoWebhook(buildRequest(body, secret));
+    await documensoWebhook(buildRequest(body, secret));
 
     const events = await db
       .select()

tests/integration/document-templates-generate-and-sign.test.ts

@@ -9,6 +9,7 @@ import {
   interests as interestsTable,
   interestBerths as interestBerthsTable,
 } from '@/lib/db/schema/interests';
+import { systemSettings } from '@/lib/db/schema/system';
 import { ValidationError } from '@/lib/errors';
 
 import { makeBerth, makeClient, makePort, makeYacht } from '../helpers/factories';
@@ -152,6 +153,19 @@ beforeAll(async () => {
 
   const template = await insertInApptemplate(port.id);
 
+  // Seed the per-port `eoi_signers` legacy blob so getPortEoiSigners returns
+  // a developer/approver pair. The env-to-admin migration retired the
+  // hardcoded DEFAULT_DEVELOPER_NAME constants, so tests that exercise
+  // auto-derived signers must seed the settings themselves.
+  await db.insert(systemSettings).values({
+    portId: port.id,
+    key: 'eoi_signers',
+    value: {
+      developer: { name: 'David Mizrahi', email: 'dm@portnimara.com' },
+      approver: { name: 'Abbie May', email: 'sales@portnimara.com' },
+    },
+  });
+
   setup = {
     portId: port.id,
     clientId: client.id,
@@ -181,11 +195,13 @@ describe('generateAndSign — inapp pathway', () => {
     vi.mocked(client.createDocument).mockResolvedValue({
       id: 'documenso-inapp-123',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
     vi.mocked(client.sendDocument).mockResolvedValue({
       id: 'documenso-inapp-123',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
 
@@ -216,11 +232,13 @@ describe('generateAndSign — inapp pathway', () => {
     vi.mocked(client.createDocument).mockResolvedValue({
       id: 'doc-auto-signers',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
     vi.mocked(client.sendDocument).mockResolvedValue({
       id: 'doc-auto-signers',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
 
@@ -280,11 +298,13 @@ describe('generateAndSign — inapp pathway', () => {
     vi.mocked(client.createDocument).mockResolvedValue({
       id: 'doc-eoi-pdf',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
     vi.mocked(client.sendDocument).mockResolvedValue({
       id: 'doc-eoi-pdf',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
 
@@ -336,6 +356,7 @@ describe('generateAndSign — documenso-template pathway', () => {
     vi.mocked(client.generateDocumentFromTemplate).mockResolvedValue({
       id: 'documenso-template-456',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
 
@@ -386,6 +407,7 @@ describe('generateAndSign — documenso-template pathway', () => {
     vi.mocked(client.generateDocumentFromTemplate).mockResolvedValue({
       id: 'documenso-template-789',
       status: 'PENDING',
+      numericId: null,
       recipients: [],
     });
 

tests/unit/pdf/fill-eoi-form.test.ts

@@ -46,7 +46,14 @@ function makeContext(overrides: Partial<EoiContext> = {}): EoiContext {
       nationality: 'US',
       primaryEmail: 'alice@example.com',
       primaryPhone: '+1-555-0100',
-      address: { street: '123 Main St', city: 'Austin', country: 'USA' },
+      address: {
+        street: '123 Main St',
+        city: 'Austin',
+        subdivision: 'TX',
+        postalCode: '78701',
+        country: 'United States',
+        countryIso: 'US',
+      },
     },
     yacht: {
       id: 'yacht-test-1',
@@ -57,6 +64,9 @@ function makeContext(overrides: Partial<EoiContext> = {}): EoiContext {
       lengthM: null,
       widthM: null,
       draftM: null,
+      lengthUnit: 'ft' as const,
+      widthUnit: 'ft' as const,
+      draftUnit: 'ft' as const,
       hullNumber: 'HN-1',
       flag: 'US',
       yearBuilt: 2020,

tests/unit/services/documenso-payload.test.ts

@@ -11,7 +11,14 @@ function makeContext(overrides?: Partial<EoiContext>): EoiContext {
       nationality: 'US',
       primaryEmail: 'alice@example.com',
       primaryPhone: '+1-555-0100',
-      address: { street: '123 Main St', city: 'Austin', country: 'USA' },
+      address: {
+        street: '123 Main St',
+        city: 'Austin',
+        subdivision: 'TX',
+        postalCode: '78701',
+        country: 'United States',
+        countryIso: 'US',
+      },
     },
     yacht: {
       id: 'yacht-fixture-1',
@@ -22,6 +29,9 @@ function makeContext(overrides?: Partial<EoiContext>): EoiContext {
       lengthM: null,
       widthM: null,
       draftM: null,
+      lengthUnit: 'ft' as const,
+      widthUnit: 'ft' as const,
+      draftUnit: 'ft' as const,
       hullNumber: 'ABC-123',
       flag: 'US',
       yearBuilt: 2020,
@@ -60,8 +70,15 @@ const OPTIONS = {
 };
 
 describe('buildDocumensoPayload', () => {
-  it('builds title as "{fullName}-EOI-NDA"', () => {
+  it('builds title as "{fullName}-EOI-NDA-{berthRange|mooringNumber}"', () => {
     const payload = buildDocumensoPayload(makeContext(), OPTIONS);
+    // Fixture has primary mooring A12, so the title suffix is "-A12".
+    expect(payload.title).toBe('Alice Smith-EOI-NDA-A12');
+  });
+
+  it('omits berth suffix from title when no berth is linked', () => {
+    const ctx = makeContext({ berth: null, eoiBerthRange: '' });
+    const payload = buildDocumensoPayload(ctx, OPTIONS);
     expect(payload.title).toBe('Alice Smith-EOI-NDA');
   });
 
@@ -75,11 +92,11 @@ describe('buildDocumensoPayload', () => {
     expect(payload.formValues).toEqual({
       Name: 'Alice Smith',
       Email: 'alice@example.com',
-      Address: '123 Main St, Austin, USA',
+      Address: '123 Main St, Austin, TX, 78701, US',
       'Yacht Name': 'Sea Breeze',
-      Length: '45',
-      Width: '14',
-      Draft: '6',
+      Length: '45 ft',
+      Width: '14 ft',
+      Draft: '6 ft',
       // Berth Number carries the formatBerthRange output — single-
       // berth EOI duplicates the primary mooring; multi-berth shows
       // the compact range. The separate 'Berth Range' formValue key
@@ -138,11 +155,18 @@ describe('buildDocumensoPayload', () => {
     const ctx = makeContext({
       client: {
         ...makeContext().client,
-        address: { street: '', city: 'Austin', country: 'USA' },
+        address: {
+          street: '',
+          city: 'Austin',
+          subdivision: '',
+          postalCode: '',
+          country: 'United States',
+          countryIso: 'US',
+        },
       },
     });
     const payload = buildDocumensoPayload(ctx, OPTIONS);
-    expect(payload.formValues.Address).toBe('Austin, USA');
+    expect(payload.formValues.Address).toBe('Austin, US');
   });
 
   it('sets Lease_10=false and Purchase=true (hardcoded)', () => {
@@ -161,17 +185,20 @@ describe('buildDocumensoPayload', () => {
       role: 'SIGNER',
       signingOrder: 1,
     });
+    // Developer + approver name/email default to '' so Documenso falls
+    // through to the template-stored values for those signers (we only
+    // override when the admin explicitly sets them via OPTIONS).
     expect(payload.recipients[1]).toEqual({
       id: 193,
-      name: 'David Mizrahi',
-      email: 'dm@portnimara.com',
+      name: '',
+      email: '',
       role: 'SIGNER',
       signingOrder: 2,
     });
     expect(payload.recipients[2]).toEqual({
       id: 194,
-      name: 'Abbie May',
-      email: 'sales@portnimara.com',
+      name: '',
+      email: '',
       role: 'APPROVER',
       signingOrder: 3,
     });

tests/unit/services/eoi-context.test.ts

@@ -146,7 +146,10 @@ describe('buildEoiContext', () => {
     expect(ctx.client.address).toEqual({
       street: '1 Harbour Way',
       city: 'Anguilla',
+      subdivision: '',
+      postalCode: '',
       country: 'Anguilla',
+      countryIso: 'AI',
     });
 
     // Yacht assertions.