fix(audit-wave-11): dossier sweep — error-ux + webhook + storage + search + maintainability

Final pass over the unaddressed AUDIT-2026-05-12 dossiers, taking the
tractable Critical/High items from each:

error-ux-auditor (5 items)
- C2: 17 toast.error(err.message) sites swept to toastError(err, …) so
  every user-visible failure carries a copy-paste Reference ID
- C3: apiFetch synthesizes a client-side correlation id when a 5xx
  comes back with a non-JSON body (reverse-proxy HTML pages); message
  becomes "The server is unreachable. Please try again." with code
  UPSTREAM_UNREACHABLE
- C4: checkRateLimit fails OPEN when Redis is unavailable so an outage
  no longer 500s login + portal sign-in; logged at warn so monitoring
  catches it
- H2: StorageTimeoutError (name='TimeoutError') replaces the plain
  Error throw in s3.ts withTimeout — error-classifier hints fire now
- H5: errorResponse() adopted across /api/storage/[token],
  /api/public/website-inquiries, and the Documenso webhook body (drops
  the "Invalid secret" reconnaissance string)

outbound-webhook-auditor (5 items)
- C1: signature is now HMAC(secret, `${ts}.${body}`) with the
  timestamp surfaced as X-Webhook-Timestamp so receivers can reject
  replays outside a freshness window
- C3: dead-letter with reason missing_signing_secret when secret is
  null (defence-in-depth against DB tampering / future migration
  mistakes)
- H2: webhooks queue bumped to maxAttempts=8 with 30 s base
  exponential backoff so a 30 s receiver blip during a deploy no
  longer dead-letters every in-flight event; per-queue
  backoffDelayMs added to QUEUE_CONFIGS
- M1: SSRF denylist gains Oracle Cloud metadata 192.0.0.192
- M2: dispatch-time https:// assertion before fetch, so a bad DB edit
  can't slip plaintext through

storage-pathing-auditor (2 items)
- H1: berth-PDF presigned-upload keys now `${portSlug}/berths/…/…`
  with portSlug threaded into backend.presignUpload — engages the
  filesystem-proxy port-binding `p` token verifier
- H2: presignDownloadUrl auto-derives portSlug from the key's first
  segment when callers don't pass it, so all 8 download sites engage
  the `p`-token guard without per-site plumbing

search-auditor (1 item)
- H3: removed dead void wantEmail; void wantPhone; pair plus the
  unused looksLikeEmail helper — the bucket-reorder it was scaffolded
  for was never wired

maintainability-auditor (1 item)
- M2: swept seven abandoned `void <symbol>` markers and their dead
  imports across clients/bulk, interests/bulk, admin/email-templates,
  admin/website-submissions, alert-rules, and notes.service

Deferred to future work (substantial refactors, schema migrations, or
multi-file UI work):
- error-ux M3-M8 (global-error.tsx, per-route loading.tsx coverage,
  ErrorBanner component, /api/ready route, worker DLQ admin surface)
- maintainability C1-C4 (documents/search/notes service splits,
  interest-tabs split — multi-hour refactors)
- currency C1-H5 (mixed-currency dashboard aggregation, FX history
  table, rounding policy) — wait for second non-USD port
- outbound-webhook C2 (deliveries reaper job), H1 (DNS-rebind TOCTOU
  with undici Agent), H3 (circuit-breaker), H5 (presigned-post-policy)
- storage-pathing C2 (orphan reaper), H3-H5 (streaming + content-type
  binding)

Tests: 1315/1315 vitest ✅ ; tsc clean.

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

src/components/admin/audit/audit-log-list.tsx

@@ -20,6 +20,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { AuditLogCard } from './audit-log-card';
 
 interface AuditEntry {
@@ -180,7 +181,7 @@ export function AuditLogList() {
       setEntries((prev) => [...prev, ...res.data]);
       setNextCursor(res.pagination.nextCursor);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Failed to load more audit entries');
+      toastError(err, 'Failed to load more audit entries');
     } finally {
       setLoadingMore(false);
     }

src/components/admin/inquiry-inbox.tsx

@@ -11,6 +11,7 @@ import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 type TriageState = 'open' | 'assigned' | 'converted' | 'dismissed';
 type StateFilter = 'inbox' | 'open' | 'assigned' | 'converted' | 'dismissed' | 'all';
@@ -112,7 +113,7 @@ export function InquiryInbox() {
       toast.success(`Marked ${vars.state}.`);
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Triage update failed');
+      toastError(err, 'Triage update failed');
     },
   });
 

src/components/admin/webhooks/webhook-delivery-log.tsx

@@ -14,6 +14,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { usePermissions } from '@/hooks/use-permissions';
 
 interface Delivery {
@@ -56,7 +57,7 @@ export function WebhookDeliveryLog({ webhookId }: Props) {
       toast.success('Replay queued');
       await load(page);
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Replay failed');
+      toastError(err, 'Replay failed');
     } finally {
       setRetrying(null);
     }

src/components/clients/bulk-archive-wizard.tsx

@@ -18,6 +18,7 @@ import { Badge } from '@/components/ui/badge';
 import { Textarea } from '@/components/ui/textarea';
 import { WarningCallout } from '@/components/ui/warning-callout';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface PreflightItem {
   clientId: string;
@@ -107,7 +108,7 @@ function BulkArchiveWizardBody({ open, onOpenChange, clientIds, onSuccess }: Pro
       onSuccess?.();
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Bulk archive failed');
+      toastError(err, 'Bulk archive failed');
     },
   });
 

src/components/clients/bulk-hard-delete-dialog.tsx

@@ -17,6 +17,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface Props {
   open: boolean;
@@ -69,7 +70,7 @@ function BulkHardDeleteDialogBody({ onOpenChange, clientIds, onDeleted }: Props)
       toast.success(`Code sent to ${res.data.sentToMaskedEmail}`);
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Failed to send code');
+      toastError(err, 'Failed to send code');
     },
   });
 
@@ -100,7 +101,7 @@ function BulkHardDeleteDialogBody({ onOpenChange, clientIds, onDeleted }: Props)
       }
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Bulk delete failed');
+      toastError(err, 'Bulk delete failed');
     },
   });
 

src/components/clients/client-list.tsx

@@ -43,6 +43,7 @@ import { usePaginatedQuery } from '@/hooks/use-paginated-query';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { useTablePreferences } from '@/hooks/use-table-preferences';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 export function ClientList() {
   const params = useParams<{ portSlug: string }>();
@@ -120,7 +121,7 @@ export function ClientList() {
       }
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Bulk action failed');
+      toastError(err, 'Bulk action failed');
     },
   });
 

src/components/clients/hard-delete-dialog.tsx

@@ -18,6 +18,7 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { WarningCallout } from '@/components/ui/warning-callout';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface Props {
   open: boolean;
@@ -66,7 +67,7 @@ function HardDeleteDialogBody({ onOpenChange, clientId, clientName, onDeleted }:
       toast.success(`Code sent to ${res.data.sentToMaskedEmail}`);
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Failed to send code');
+      toastError(err, 'Failed to send code');
     },
   });
 
@@ -83,7 +84,7 @@ function HardDeleteDialogBody({ onOpenChange, clientId, clientName, onDeleted }:
       onDeleted?.();
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Delete failed');
+      toastError(err, 'Delete failed');
     },
   });
 

src/components/clients/smart-archive-dialog.tsx

@@ -18,6 +18,7 @@ import { Badge } from '@/components/ui/badge';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Textarea } from '@/components/ui/textarea';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface DossierBerth {
   berthId: string;
@@ -266,7 +267,7 @@ function SmartArchiveDialogBody({
       onSuccess?.();
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Archive failed');
+      toastError(err, 'Archive failed');
     },
   });
 

src/components/clients/smart-restore-dialog.tsx

@@ -26,6 +26,7 @@ import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Checkbox } from '@/components/ui/checkbox';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 
 interface RestoreReversal {
   id: string;
@@ -109,7 +110,7 @@ function SmartRestoreDialogBody({ open, onOpenChange, clientId, clientName, onSu
       onSuccess?.();
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Restore failed');
+      toastError(err, 'Restore failed');
     },
   });
 

src/components/interests/external-eoi-upload-dialog.tsx

@@ -9,6 +9,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Textarea } from '@/components/ui/textarea';
+import { toastError } from '@/lib/api/toast-error';
 import {
   Dialog,
   DialogContent,
@@ -68,7 +69,7 @@ export function ExternalEoiUploadDialog({ open, onOpenChange, interestId, onSucc
       onSuccess?.();
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Upload failed');
+      toastError(err, 'Upload failed');
     },
   });
 

src/components/interests/interest-stage-picker.tsx

@@ -23,6 +23,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
 import { usePermissions } from '@/hooks/use-permissions';
 import { PIPELINE_STAGES, STAGE_LABELS, stageLabel, canTransitionStage } from '@/lib/constants';
 
@@ -74,7 +75,7 @@ export function InterestStagePicker({
       toast.success(overrideEffective ? 'Stage overridden' : 'Stage updated');
     },
     onError: (err: unknown) => {
-      toast.error(err instanceof Error ? err.message : 'Stage change failed');
+      toastError(err, 'Stage change failed');
     },
   });
 

src/components/portal/change-password-form.tsx

@@ -6,6 +6,7 @@ import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { toastError } from '@/lib/api/toast-error';
 
 export function ChangePasswordForm() {
   const [current, setCurrent] = useState('');
@@ -34,7 +35,7 @@ export function ChangePasswordForm() {
       setNext('');
       setConfirm('');
     } catch (err) {
-      toast.error(err instanceof Error ? err.message : 'Password change failed');
+      toastError(err, 'Password change failed');
     } finally {
       setPending(false);
     }