fix(audit-tier-1): timeouts, lifecycle, per-port Documenso, FK constraints

Closes the second wave of HIGH-priority audit findings:

* fetchWithTimeout helper (new src/lib/fetch-with-timeout.ts) wraps
  Documenso, OCR, currency, Umami, IMAP, etc. — a hung upstream can
  no longer pin a worker concurrency slot indefinitely.  OpenAI client
  passes timeout: 30_000.  ImapFlow gets socket / greeting / connection
  timeouts.
* SIGTERM / SIGINT handler in src/server.ts drains in-flight HTTP,
  closes Socket.io, and disconnects Redis before exit; compose
  stop_grace_period bumped to 30s.  Adds closeSocketServer() helper.
* env.ts gains zod-validated PORT and MULTI_NODE_DEPLOYMENT, and
  filesystem.ts now reads from env (a typo can no longer silently
  disable the multi-node guard).
* Per-port Documenso template + recipient IDs land in system_settings
  with env fallback (PortDocumensoConfig now exposes eoiTemplateId,
  clientRecipientId, developerRecipientId, approvalRecipientId).
  document-templates.ts uses the per-port config and threads portId
  into documensoGenerateFromTemplate().
* Migration 0042 wires the eleven HIGH-tier missing FK constraints
  (documents/files/interests/reminders/berth_waiting_list/
  form_submissions) plus polymorphic CHECK round 2
  (yacht_ownership_history.owner_type, document_sends.document_kind),
  invoices.billing_entity_id NOT EMPTY, and clients.merged_into self-FK.
  Drizzle schema columns updated to .references(...) where possible
  so the misleading "FK wired in relations.ts" comments are gone.

Test status: 1168/1168 vitest, tsc clean.

Refs: docs/audit-comprehensive-2026-05-05.md HIGH §§5,6,7,8,9,10 +
MED §§14,15,16,18.

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

tests/unit/services/documenso-place-fields.test.ts

@@ -36,8 +36,11 @@ function configurePort(version: 'v1' | 'v2'): void {
     apiUrl: 'https://documenso.test',
     apiKey: 'sk_test',
     apiVersion: version,
-    eoiTemplateId: null,
+    eoiTemplateId: 8,
     defaultPathway: 'documenso-template',
+    clientRecipientId: 192,
+    developerRecipientId: 193,
+    approvalRecipientId: 194,
   });
 }
 

tests/unit/storage/filesystem-backend.test.ts

@@ -14,8 +14,20 @@ import { mkdtemp, rm, mkdir, symlink } from 'node:fs/promises';
 import * as path from 'node:path';
 import { tmpdir } from 'node:os';
 
-import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 
+// Stub the env module BEFORE importing the backend so the
+// MULTI_NODE_DEPLOYMENT toggle works — env is now read from the zod
+// schema once at module load, not from process.env at runtime.
+vi.mock('@/lib/env', async () => {
+  const actual = await vi.importActual<typeof import('@/lib/env')>('@/lib/env');
+  return {
+    ...actual,
+    env: { ...actual.env, MULTI_NODE_DEPLOYMENT: false },
+  };
+});
+
+import { env } from '@/lib/env';
 import {
   FilesystemBackend,
   signProxyToken,
@@ -125,8 +137,12 @@ describe('FilesystemBackend realpath check', () => {
   });
 
   it('refuses to start when MULTI_NODE_DEPLOYMENT=true', async () => {
-    const prev = process.env.MULTI_NODE_DEPLOYMENT;
-    process.env.MULTI_NODE_DEPLOYMENT = 'true';
+    const prev = env.MULTI_NODE_DEPLOYMENT;
+    // The backend reads env.MULTI_NODE_DEPLOYMENT (zod-validated, set
+    // once at module load). Mutate the in-memory env for the duration of
+    // this case — the surrounding vi.mock() above keeps every other env
+    // field intact.
+    (env as unknown as { MULTI_NODE_DEPLOYMENT: boolean }).MULTI_NODE_DEPLOYMENT = true;
     try {
       const tmp = await mkdtemp(path.join(tmpdir(), 'pn-storage-mn-'));
       await expect(
@@ -134,8 +150,7 @@ describe('FilesystemBackend realpath check', () => {
       ).rejects.toThrow(/MULTI_NODE_DEPLOYMENT/);
       await rm(tmp, { recursive: true, force: true });
     } finally {
-      if (prev === undefined) delete process.env.MULTI_NODE_DEPLOYMENT;
-      else process.env.MULTI_NODE_DEPLOYMENT = prev;
+      (env as unknown as { MULTI_NODE_DEPLOYMENT: boolean }).MULTI_NODE_DEPLOYMENT = prev;
     }
   });