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/lib/storage/index.ts

@@ -229,6 +229,13 @@ async function buildBackend(cfg: StorageConfigSnapshot): Promise<StorageBackend>
  * common need at call sites that don't track expiry. Mirrors the legacy
  * `getPresignedUrl(key)` helper in `@/lib/minio` but routes through the
  * active backend so filesystem-mode deployments work too.
+ *
+ * storage-pathing-auditor H2: when `portSlug` is not passed explicitly,
+ * we attempt to infer it from the key's first path segment — every
+ * storage key minted via `buildStoragePath(slug, …)` starts with the
+ * slug, so the inference is correct for the overwhelming majority of
+ * callers. This engages the filesystem-proxy port-binding token (`p`)
+ * verifier so a stolen-token / cross-port replay attempt fails fast.
  */
 export async function presignDownloadUrl(
   key: string,
@@ -237,10 +244,37 @@ export async function presignDownloadUrl(
   portSlug?: string,
 ): Promise<string> {
   const backend = await getStorageBackend();
-  const { url } = await backend.presignDownload(key, { expirySeconds, filename, portSlug });
+  const inferredSlug = portSlug ?? inferPortSlugFromKey(key);
+  const { url } = await backend.presignDownload(key, {
+    expirySeconds,
+    filename,
+    portSlug: inferredSlug,
+  });
   return url;
 }
 
+/**
+ * Best-effort recovery of the port slug from a storage key prefix.
+ * Returns undefined when the key doesn't look slug-prefixed (e.g. legacy
+ * keys minted before `buildStoragePath` was canonical) so the caller
+ * falls back to the no-binding path.
+ *
+ * A slug is conservatively defined as kebab/alphanumeric (the same
+ * shape `createPortSchema` enforces). Non-matching first segments
+ * include UUID-only keys like the legacy `berths/{id}/uploads/...`
+ * shape — those are still served but skip the binding gate.
+ */
+function inferPortSlugFromKey(key: string): string | undefined {
+  const slash = key.indexOf('/');
+  if (slash <= 0) return undefined;
+  const first = key.slice(0, slash);
+  if (!/^[a-z0-9-]+$/.test(first)) return undefined;
+  // Reserved namespaces that historically lived at the top level of the
+  // bucket and aren't port slugs.
+  if (first === 'berths' || first === 'backups' || first === 'tmp') return undefined;
+  return first;
+}
+
 // ─── re-exports ─────────────────────────────────────────────────────────────
 
 export { S3Backend } from './s3';

src/lib/storage/s3.ts

@@ -46,10 +46,27 @@ interface S3BackendConfig {
  */
 const STORAGE_DEFAULT_TIMEOUT_MS = 30_000;
 
+/**
+ * Named timeout error so `error-classifier.ts` `ERROR_NAME_HINTS` can
+ * distinguish "the storage call timed out" from a generic storage
+ * misconfiguration. The plain-Error form was dropping into the path-
+ * based classifier and losing the actionable hint.
+ */
+export class StorageTimeoutError extends Error {
+  readonly label: string;
+  readonly timeoutMs: number;
+  constructor(label: string, ms: number) {
+    super(`S3 ${label} timed out after ${ms}ms`);
+    this.name = 'TimeoutError';
+    this.label = label;
+    this.timeoutMs = ms;
+  }
+}
+
 function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
   let timer: NodeJS.Timeout | null = null;
   const timeout = new Promise<T>((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`S3 ${label} timed out after ${ms}ms`)), ms);
+    timer = setTimeout(() => reject(new StorageTimeoutError(label, ms)), ms);
   });
   return Promise.race([promise, timeout]).finally(() => {
     if (timer) clearTimeout(timer);