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>

src/lib/services/currency.ts

@@ -2,6 +2,7 @@ import { db } from '@/lib/db';
 import { currencyRates } from '@/lib/db/schema/system';
 import { eq, and } from 'drizzle-orm';
 import { logger } from '@/lib/logger';
+import { fetchWithTimeout } from '@/lib/fetch-with-timeout';
 
 export async function getRate(from: string, to: string): Promise<number | null> {
   if (from === to) return 1;
@@ -23,7 +24,7 @@ export async function convert(
 
 export async function refreshRates(): Promise<void> {
   try {
-    const res = await fetch('https://api.frankfurter.dev/v1/latest?base=USD');
+    const res = await fetchWithTimeout('https://api.frankfurter.dev/v1/latest?base=USD');
     if (!res.ok) throw new Error(`Frankfurter API error: ${res.status}`);
     const data = await res.json();
     const rates = data.rates as Record<string, number>;

src/lib/services/documenso-client.ts

@@ -1,6 +1,7 @@
 import { env } from '@/lib/env';
 import { logger } from '@/lib/logger';
 import { getPortDocumensoConfig, type DocumensoApiVersion } from '@/lib/services/port-config';
+import { fetchWithTimeout } from '@/lib/fetch-with-timeout';
 
 interface DocumensoCreds {
   baseUrl: string;
@@ -26,7 +27,7 @@ async function documensoFetch(
   portId?: string,
 ): Promise<unknown> {
   const { baseUrl, apiKey } = await resolveCreds(portId);
-  const res = await fetch(`${baseUrl}${path}`, {
+  const res = await fetchWithTimeout(`${baseUrl}${path}`, {
     ...options,
     headers: {
       Authorization: `Bearer ${apiKey}`,
@@ -241,7 +242,7 @@ export async function sendReminder(
 
 export async function downloadSignedPdf(docId: string, portId?: string): Promise<Buffer> {
   const { baseUrl, apiKey } = await resolveCreds(portId);
-  const res = await fetch(`${baseUrl}/api/v1/documents/${docId}/download`, {
+  const res = await fetchWithTimeout(`${baseUrl}/api/v1/documents/${docId}/download`, {
     headers: { Authorization: `Bearer ${apiKey}` },
   });
 
@@ -261,7 +262,7 @@ export async function checkDocumensoHealth(
 ): Promise<{ ok: boolean; status?: number; error?: string }> {
   try {
     const { baseUrl, apiKey } = await resolveCreds(portId);
-    const res = await fetch(`${baseUrl}/api/v1/health`, {
+    const res = await fetchWithTimeout(`${baseUrl}/api/v1/health`, {
       headers: { Authorization: `Bearer ${apiKey}` },
     });
     return { ok: res.ok, status: res.status };
@@ -355,7 +356,7 @@ export async function placeFields(
     // Note: v2 endpoint shape (envelopeId/recipientId types) must be
     // confirmed against a live Documenso 2.x instance - see PR11 realapi
     // suite. Spec risk register flags this drift as the top v2 risk.
-    const res = await fetch(`${baseUrl}/api/v2/envelope/field/create-many`, {
+    const res = await fetchWithTimeout(`${baseUrl}/api/v2/envelope/field/create-many`, {
       method: 'POST',
       headers: {
         Authorization: `Bearer ${apiKey}`,
@@ -387,7 +388,7 @@ export async function placeFields(
     // 1000 ms; 4xx responses (validation errors) fail-fast.
     let lastError: { status: number; body: string } | null = null;
     for (let attempt = 0; attempt < 3; attempt += 1) {
-      const res = await fetch(`${baseUrl}/api/v1/documents/${docId}/fields`, {
+      const res = await fetchWithTimeout(`${baseUrl}/api/v1/documents/${docId}/fields`, {
         method: 'POST',
         headers: {
           Authorization: `Bearer ${apiKey}`,
@@ -470,7 +471,7 @@ export function computeDefaultSignatureLayout(
 export async function voidDocument(docId: string, portId?: string): Promise<void> {
   const { baseUrl, apiKey, apiVersion } = await resolveCreds(portId);
   const path = apiVersion === 'v2' ? `/api/v2/envelope/${docId}` : `/api/v1/documents/${docId}`;
-  const res = await fetch(`${baseUrl}${path}`, {
+  const res = await fetchWithTimeout(`${baseUrl}${path}`, {
     method: 'DELETE',
     headers: { Authorization: `Bearer ${apiKey}` },
   });

src/lib/services/document-templates.ts

@@ -25,6 +25,7 @@ import {
   generateDocumentFromTemplate as documensoGenerateFromTemplate,
 } from '@/lib/services/documenso-client';
 import { buildDocumensoPayload, getPortEoiSigners } from '@/lib/services/documenso-payload';
+import { getPortDocumensoConfig } from '@/lib/services/port-config';
 import { generateEoiPdfFromTemplate } from '@/lib/pdf/fill-eoi-form';
 import { MERGE_FIELDS, type MergeFieldCatalog } from '@/lib/templates/merge-fields';
 import { buildEoiContext } from '@/lib/services/eoi-context';
@@ -882,12 +883,17 @@ async function generateAndSignViaDocumensoTemplate(
 
   const eoiContext = await buildEoiContext(context.interestId, portId);
   const signers = await getPortEoiSigners(portId);
+  // Per-port Documenso template + recipient IDs (with env fallback). Each
+  // tenant pointing at its own Documenso instance has different numeric
+  // template + recipient IDs, so a global env-only setup limits the
+  // platform to one Documenso instance per CRM process.
+  const docCfg = await getPortDocumensoConfig(portId);
 
   const payload = buildDocumensoPayload(eoiContext, {
     interestId: context.interestId,
-    clientRecipientId: env.DOCUMENSO_CLIENT_RECIPIENT_ID,
-    developerRecipientId: env.DOCUMENSO_DEVELOPER_RECIPIENT_ID,
-    approvalRecipientId: env.DOCUMENSO_APPROVAL_RECIPIENT_ID,
+    clientRecipientId: docCfg.clientRecipientId,
+    developerRecipientId: docCfg.developerRecipientId,
+    approvalRecipientId: docCfg.approvalRecipientId,
     developerName: signers.developer.name,
     developerEmail: signers.developer.email,
     approverName: signers.approver.name,
@@ -896,8 +902,9 @@ async function generateAndSignViaDocumensoTemplate(
   });
 
   const documensoDoc = await documensoGenerateFromTemplate(
-    env.DOCUMENSO_TEMPLATE_ID_EOI,
+    docCfg.eoiTemplateId,
     payload as unknown as Record<string, unknown>,
+    portId,
   );
 
   // Record a documents row referencing the Documenso document. No local file -

src/lib/services/email-threads.service.ts

@@ -265,6 +265,13 @@ export async function syncInbox(accountId: string): Promise<void> {
       pass: creds.password,
     },
     logger: false,
+    // Without these, a slow-streaming UID can hang the maintenance worker
+    // indefinitely (worker concurrency 1 → entire BullMQ maintenance queue
+    // stalls). 60s socket / 30s greeting / 30s connect is generous for any
+    // working server but bounds the hang.
+    socketTimeout: 60_000,
+    greetingTimeout: 30_000,
+    connectionTimeout: 30_000,
   });
 
   try {

src/lib/services/ocr-providers.ts

@@ -7,6 +7,9 @@
 import OpenAI from 'openai';
 
 import { logger } from '@/lib/logger';
+import { fetchWithTimeout } from '@/lib/fetch-with-timeout';
+
+const OCR_TIMEOUT_MS = 30_000;
 
 export interface ParsedReceiptLineItem {
   description: string;
@@ -73,7 +76,10 @@ function safeParse(content: string): ParsedReceipt {
 }
 
 async function runOpenAi({ imageBuffer, mimeType, apiKey, model }: RunArgs): Promise<OcrRunResult> {
-  const client = new OpenAI({ apiKey });
+  // Default OpenAI client has no timeout — a hung request would hold a Bull
+  // documents-worker concurrency slot until the OS reset it (~15 min). The
+  // 30s cap matches the cap on the (newer) email-draft worker fetch.
+  const client = new OpenAI({ apiKey, timeout: OCR_TIMEOUT_MS });
   const base64 = imageBuffer.toString('base64');
   const response = await client.chat.completions.create({
     model,
@@ -106,7 +112,8 @@ async function runOpenAi({ imageBuffer, mimeType, apiKey, model }: RunArgs): Pro
 
 async function runClaude({ imageBuffer, mimeType, apiKey, model }: RunArgs): Promise<OcrRunResult> {
   const base64 = imageBuffer.toString('base64');
-  const res = await fetch('https://api.anthropic.com/v1/messages', {
+  const res = await fetchWithTimeout('https://api.anthropic.com/v1/messages', {
+    timeoutMs: OCR_TIMEOUT_MS,
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',

src/lib/services/port-config.ts

@@ -30,6 +30,12 @@ export const SETTING_KEYS = {
   documensoApiKeyOverride: 'documenso_api_key_override',
   documensoApiVersionOverride: 'documenso_api_version_override',
   documensoEoiTemplateId: 'documenso_eoi_template_id',
+  // Documenso template recipient slot IDs are per-Documenso-instance
+  // numeric values, so they have to follow the per-port template config.
+  // Falling back to env keeps single-tenant deploys working.
+  documensoClientRecipientId: 'documenso_client_recipient_id',
+  documensoDeveloperRecipientId: 'documenso_developer_recipient_id',
+  documensoApprovalRecipientId: 'documenso_approval_recipient_id',
   eoiDefaultPathway: 'eoi_default_pathway',
 
   // Branding
@@ -136,16 +142,41 @@ export interface PortDocumensoConfig {
   apiUrl: string;
   apiKey: string;
   apiVersion: DocumensoApiVersion;
-  eoiTemplateId: string | null;
+  eoiTemplateId: number;
   defaultPathway: EoiPathway;
+  /** Documenso template recipient slot IDs (per-instance numeric). */
+  clientRecipientId: number;
+  developerRecipientId: number;
+  approvalRecipientId: number;
+}
+
+function toIntOrNull(raw: unknown): number | null {
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw;
+  if (typeof raw === 'string' && raw.trim()) {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
 }
 
 export async function getPortDocumensoConfig(portId: string): Promise<PortDocumensoConfig> {
-  const [apiUrl, apiKey, apiVersion, eoiTemplateId, defaultPathway] = await Promise.all([
+  const [
+    apiUrl,
+    apiKey,
+    apiVersion,
+    eoiTemplateId,
+    clientRecipientId,
+    developerRecipientId,
+    approvalRecipientId,
+    defaultPathway,
+  ] = await Promise.all([
     readSetting<string>(SETTING_KEYS.documensoApiUrlOverride, portId),
     readSetting<string>(SETTING_KEYS.documensoApiKeyOverride, portId),
     readSetting<DocumensoApiVersion>(SETTING_KEYS.documensoApiVersionOverride, portId),
-    readSetting<string>(SETTING_KEYS.documensoEoiTemplateId, portId),
+    readSetting<string | number>(SETTING_KEYS.documensoEoiTemplateId, portId),
+    readSetting<string | number>(SETTING_KEYS.documensoClientRecipientId, portId),
+    readSetting<string | number>(SETTING_KEYS.documensoDeveloperRecipientId, portId),
+    readSetting<string | number>(SETTING_KEYS.documensoApprovalRecipientId, portId),
     readSetting<EoiPathway>(SETTING_KEYS.eoiDefaultPathway, portId),
   ]);
 
@@ -153,7 +184,10 @@ export async function getPortDocumensoConfig(portId: string): Promise<PortDocume
     apiUrl: apiUrl ?? env.DOCUMENSO_API_URL,
     apiKey: apiKey ?? env.DOCUMENSO_API_KEY,
     apiVersion: apiVersion ?? env.DOCUMENSO_API_VERSION,
-    eoiTemplateId: eoiTemplateId ?? null,
+    eoiTemplateId: toIntOrNull(eoiTemplateId) ?? env.DOCUMENSO_TEMPLATE_ID_EOI,
+    clientRecipientId: toIntOrNull(clientRecipientId) ?? env.DOCUMENSO_CLIENT_RECIPIENT_ID,
+    developerRecipientId: toIntOrNull(developerRecipientId) ?? env.DOCUMENSO_DEVELOPER_RECIPIENT_ID,
+    approvalRecipientId: toIntOrNull(approvalRecipientId) ?? env.DOCUMENSO_APPROVAL_RECIPIENT_ID,
     defaultPathway: defaultPathway ?? 'documenso-template',
   };
 }

src/lib/services/umami.service.ts

@@ -21,6 +21,7 @@ import { and, eq, inArray } from 'drizzle-orm';
 import { db } from '@/lib/db';
 import { systemSettings } from '@/lib/db/schema/system';
 import { rangeToBounds, type DateRange } from '@/lib/analytics/range';
+import { fetchWithTimeout } from '@/lib/fetch-with-timeout';
 
 // ─── Settings access ────────────────────────────────────────────────────────
 
@@ -80,7 +81,7 @@ const jwtCache = new Map<string, CachedJwt>();
 const JWT_TTL_MS = 55 * 60 * 1000; // 55 min - Umami JWTs default to 1h
 
 async function loginAndCache(apiUrl: string, username: string, password: string): Promise<string> {
-  const res = await fetch(`${apiUrl}/api/auth/login`, {
+  const res = await fetchWithTimeout(`${apiUrl}/api/auth/login`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', accept: 'application/json' },
     body: JSON.stringify({ username, password }),
@@ -122,7 +123,7 @@ async function umamiFetch<T>(
     url.searchParams.set(k, String(v));
   }
 
-  const res = await fetch(url, {
+  const res = await fetchWithTimeout(url.toString(), {
     headers: {
       Authorization: `Bearer ${bearer}`,
       accept: 'application/json',