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>

src/lib/settings/resolver.ts

@@ -0,0 +1,362 @@
+import { and, eq, isNull } from 'drizzle-orm';
+import { z } from 'zod';
+
+import { createAuditLog, type AuditMeta } from '@/lib/audit';
+import { db } from '@/lib/db';
+import { systemSettings } from '@/lib/db/schema';
+import { NotFoundError, ValidationError } from '@/lib/errors';
+import { decrypt, encrypt } from '@/lib/utils/encryption';
+
+import { registryFor } from './registry';
+import type { ResolvedSetting, SettingEntry, SettingSource } from './types';
+
+/**
+ * Stored shape for encrypted JSONB values. The encrypt() helper returns a
+ * JSON string of this shape — we wrap it in the JSONB column verbatim.
+ */
+interface EncryptedEnvelope {
+  iv: string;
+  tag: string;
+  data: string;
+}
+
+function isEncryptedEnvelope(value: unknown): value is EncryptedEnvelope {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { iv?: unknown }).iv === 'string' &&
+    typeof (value as { tag?: unknown }).tag === 'string' &&
+    typeof (value as { data?: unknown }).data === 'string'
+  );
+}
+
+/**
+ * Validator inferred from the entry type when no explicit `validator` is set.
+ * Keeps the registry concise — only override when standard rules don't fit.
+ */
+function defaultValidator(entry: SettingEntry): z.ZodTypeAny {
+  if (entry.validator) return entry.validator;
+  switch (entry.type) {
+    case 'string':
+    case 'password':
+    case 'textarea':
+    case 'user-select':
+      return z.string();
+    case 'url':
+      return z.string().url();
+    case 'email':
+      return z.string().email();
+    case 'number':
+      return z.coerce.number();
+    case 'boolean':
+      return z.coerce.boolean();
+    case 'select':
+      if (entry.options) {
+        return z.enum(entry.options.map((o) => o.value) as [string, ...string[]]);
+      }
+      return z.string();
+    default:
+      return z.unknown();
+  }
+}
+
+function coerceForType(entry: SettingEntry, raw: unknown): unknown {
+  if (raw == null) return null;
+  if (entry.transform) return entry.transform(raw);
+  if (entry.type === 'number') {
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (entry.type === 'boolean') {
+    if (typeof raw === 'boolean') return raw;
+    if (raw === 'true' || raw === '1') return true;
+    if (raw === 'false' || raw === '0') return false;
+    return Boolean(raw);
+  }
+  return raw;
+}
+
+function readEnvValue(entry: SettingEntry): unknown | null {
+  if (!entry.envFallback) return null;
+  const v = process.env[entry.envFallback];
+  if (v == null || v === '') return null;
+  return coerceForType(entry, v);
+}
+
+function unwrapStoredValue(entry: SettingEntry, stored: unknown): unknown {
+  if (stored == null) return null;
+  if (entry.encrypted && isEncryptedEnvelope(stored)) {
+    return decrypt(JSON.stringify(stored));
+  }
+  // Settings written via the legacy upsertSetting helper wrap the value in
+  // `{ value: ... }`. Unwrap that shape transparently for backward compat.
+  if (
+    typeof stored === 'object' &&
+    stored !== null &&
+    'value' in stored &&
+    Object.keys(stored as object).length === 1
+  ) {
+    return (stored as { value: unknown }).value;
+  }
+  return stored;
+}
+
+interface ResolvedRaw {
+  source: SettingSource;
+  rawValue: unknown;
+}
+
+/**
+ * Lower-level lookup that returns both the resolved value AND the source it
+ * came from (port row, global row, env, or registry default). The admin API
+ * uses this directly to drive the "Using env fallback" badge; service code
+ * usually calls `getSetting()` which discards the source.
+ */
+export async function resolveSettingWithSource(
+  key: string,
+  portId: string | null,
+): Promise<ResolvedRaw> {
+  const entry = registryFor(key);
+  if (!entry) throw new Error(`Unknown setting key: ${key}`);
+
+  // 1. Port-specific row (only meaningful for port-scoped entries).
+  if (portId && entry.scope === 'port') {
+    const row = await db.query.systemSettings.findFirst({
+      where: and(eq(systemSettings.key, key), eq(systemSettings.portId, portId)),
+    });
+    if (row?.value != null) {
+      return { source: 'port', rawValue: unwrapStoredValue(entry, row.value) };
+    }
+  }
+
+  // 2. Global row (port_id IS NULL).
+  const globalRow = await db.query.systemSettings.findFirst({
+    where: and(eq(systemSettings.key, key), isNull(systemSettings.portId)),
+  });
+  if (globalRow?.value != null) {
+    return { source: 'global', rawValue: unwrapStoredValue(entry, globalRow.value) };
+  }
+
+  // 3. Env fallback.
+  const envValue = readEnvValue(entry);
+  if (envValue != null) {
+    return { source: 'env', rawValue: envValue };
+  }
+
+  // 4. Registry default.
+  return { source: 'default', rawValue: entry.defaultValue ?? null };
+}
+
+/**
+ * Resolves a setting value through the precedence chain: port → global → env
+ * → registry default. Encrypted values are decrypted on the way out.
+ *
+ * Use this from service code that needs the concrete cleartext value
+ * (e.g. building an outbound Documenso request).
+ */
+export async function getSetting<T = unknown>(
+  key: string,
+  portId: string | null,
+): Promise<T | null> {
+  const { rawValue } = await resolveSettingWithSource(key, portId);
+  return rawValue as T | null;
+}
+
+/**
+ * Batch resolver — efficient for the admin form which needs every field in a
+ * section. Returns a map keyed by setting key.
+ */
+export async function resolveSettings(
+  keys: string[],
+  portId: string | null,
+): Promise<Map<string, ResolvedRaw>> {
+  const out = new Map<string, ResolvedRaw>();
+  await Promise.all(
+    keys.map(async (k) => {
+      out.set(k, await resolveSettingWithSource(k, portId));
+    }),
+  );
+  return out;
+}
+
+/**
+ * Shape returned to the admin API. Sensitive fields surface `isSet` only.
+ */
+export async function resolveForAdminAPI(
+  keys: string[],
+  portId: string | null,
+): Promise<Map<string, ResolvedSetting>> {
+  const resolved = await resolveSettings(keys, portId);
+  const out = new Map<string, ResolvedSetting>();
+  for (const key of keys) {
+    const entry = registryFor(key);
+    if (!entry) continue;
+    const r = resolved.get(key);
+    if (!r) continue;
+    const isSet = r.source !== 'default' && r.rawValue != null && r.rawValue !== '';
+    const surfaceSensitive = entry.sensitive || entry.encrypted;
+    out.set(key, {
+      key,
+      source: r.source,
+      isSet,
+      value: surfaceSensitive ? undefined : (r.rawValue ?? undefined),
+    });
+  }
+  return out;
+}
+
+/**
+ * Validate and persist a setting. Encrypts if registered as encrypted. Always
+ * writes to the row scope appropriate to the entry: port-scoped entries with
+ * a non-null portId write the port row; global-scoped entries (or when called
+ * with portId=null) write the global row.
+ */
+export async function writeSetting(
+  key: string,
+  rawValue: unknown,
+  portId: string | null,
+  meta: AuditMeta,
+): Promise<void> {
+  const entry = registryFor(key);
+  if (!entry) throw new ValidationError(`Unknown setting: ${key}`);
+
+  // Empty value on a settable field == delete the row (revert to fallback).
+  // Sensitive/encrypted: empty input means "don't change" rather than
+  // "revert" — UI shows ••• placeholder so an unchanged save shouldn't
+  // wipe the stored ciphertext. The dedicated DELETE endpoint exists for
+  // explicit reverts.
+  if (rawValue === '' || rawValue == null) {
+    if (entry.encrypted || entry.sensitive) {
+      // No-op: leaving the existing row untouched.
+      return;
+    }
+    await deleteSetting(key, portId, meta);
+    return;
+  }
+
+  const validator = defaultValidator(entry);
+  const parsed = validator.safeParse(rawValue);
+  if (!parsed.success) {
+    throw new ValidationError(
+      `Invalid value for "${key}": ${parsed.error.issues
+        .map((i) => `${i.path.join('.')}: ${i.message}`)
+        .join('; ')}`,
+    );
+  }
+  const value = parsed.data;
+
+  const writePortId = entry.scope === 'global' ? null : portId;
+  const storedValue = entry.encrypted
+    ? (JSON.parse(encrypt(String(value))) as EncryptedEnvelope)
+    : value;
+
+  // Read existing for audit diff.
+  const existing = writePortId
+    ? await db.query.systemSettings.findFirst({
+        where: and(eq(systemSettings.key, key), eq(systemSettings.portId, writePortId)),
+      })
+    : await db.query.systemSettings.findFirst({
+        where: and(eq(systemSettings.key, key), isNull(systemSettings.portId)),
+      });
+
+  await db
+    .insert(systemSettings)
+    .values({
+      key,
+      value: storedValue as Record<string, unknown>,
+      portId: writePortId,
+      updatedBy: meta.userId,
+    })
+    .onConflictDoUpdate({
+      target: [systemSettings.key, systemSettings.portId],
+      set: {
+        value: storedValue as Record<string, unknown>,
+        updatedBy: meta.userId,
+        updatedAt: new Date(),
+      },
+    });
+
+  // Audit-log with redaction for sensitive / encrypted fields — fixes AU-02
+  // (encrypted ciphertext stored in audit_logs.new_value).
+  const isSecret = entry.encrypted || entry.sensitive;
+  void createAuditLog({
+    userId: meta.userId,
+    portId: meta.portId,
+    action: existing ? 'update' : 'create',
+    entityType: 'setting',
+    entityId: key,
+    oldValue: existing ? { value: isSecret ? '[redacted]' : existing.value } : undefined,
+    newValue: { value: isSecret ? '[redacted]' : value },
+    metadata: { settingKey: key, scope: entry.scope },
+    ipAddress: meta.ipAddress,
+    userAgent: meta.userAgent,
+  });
+}
+
+/**
+ * Delete a setting row, reverting the resolver to global → env → default.
+ * No-op (with NotFoundError) if no row exists at the target scope.
+ */
+export async function deleteSetting(
+  key: string,
+  portId: string | null,
+  meta: AuditMeta,
+): Promise<void> {
+  const entry = registryFor(key);
+  if (!entry) throw new ValidationError(`Unknown setting: ${key}`);
+
+  const writePortId = entry.scope === 'global' ? null : portId;
+
+  const existing = writePortId
+    ? await db.query.systemSettings.findFirst({
+        where: and(eq(systemSettings.key, key), eq(systemSettings.portId, writePortId)),
+      })
+    : await db.query.systemSettings.findFirst({
+        where: and(eq(systemSettings.key, key), isNull(systemSettings.portId)),
+      });
+
+  if (!existing) throw new NotFoundError('Setting');
+
+  await db
+    .delete(systemSettings)
+    .where(
+      writePortId
+        ? and(eq(systemSettings.key, key), eq(systemSettings.portId, writePortId))
+        : and(eq(systemSettings.key, key), isNull(systemSettings.portId)),
+    );
+
+  const isSecret = entry.encrypted || entry.sensitive;
+  void createAuditLog({
+    userId: meta.userId,
+    portId: meta.portId,
+    action: 'delete',
+    entityType: 'setting',
+    entityId: key,
+    oldValue: { value: isSecret ? '[redacted]' : existing.value },
+    metadata: { settingKey: key, scope: entry.scope },
+    ipAddress: meta.ipAddress,
+    userAgent: meta.userAgent,
+  });
+}
+
+/**
+ * One-click migration: read the env var named in `entry.envFallback`, write
+ * it as the current scope's row. Used by the admin UI "Copy from env" button.
+ */
+export async function copyFromEnv(
+  key: string,
+  portId: string | null,
+  meta: AuditMeta,
+): Promise<{ copied: boolean; envValue?: string }> {
+  const entry = registryFor(key);
+  if (!entry) throw new ValidationError(`Unknown setting: ${key}`);
+  if (!entry.envFallback) {
+    throw new ValidationError(`Setting "${key}" has no env fallback configured`);
+  }
+  const envValue = process.env[entry.envFallback];
+  if (envValue == null || envValue === '') {
+    return { copied: false };
+  }
+  await writeSetting(key, envValue, portId, meta);
+  return { copied: true, envValue: entry.encrypted || entry.sensitive ? undefined : envValue };
+}