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/app/api/public/website-inquiries/route.ts

@@ -7,7 +7,13 @@ import { db } from '@/lib/db';
 import { ports } from '@/lib/db/schema/ports';
 import { websiteSubmissions } from '@/lib/db/schema/website-submissions';
 import { env } from '@/lib/env';
-import { errorResponse } from '@/lib/errors';
+import {
+  AppError,
+  errorResponse,
+  RateLimitError,
+  UnauthorizedError,
+  ValidationError,
+} from '@/lib/errors';
 import { logger } from '@/lib/logger';
 import { checkRateLimit, rateLimiters } from '@/lib/rate-limit';
 
@@ -63,16 +69,15 @@ export async function POST(req: NextRequest) {
   // Refuse outright if the CRM hasn't been wired up - safer than letting
   // unauthenticated traffic in just because the env var was forgotten.
   if (!env.WEBSITE_INTAKE_SECRET) {
-    return NextResponse.json(
-      { error: 'Website intake is not configured on this server.' },
-      { status: 503 },
+    return errorResponse(
+      new AppError(503, 'Website intake is not configured on this server.', 'NOT_CONFIGURED'),
     );
   }
 
   // Auth gate - shared secret in header, timing-safe compare.
   const secretHeader = req.headers.get('x-webhook-secret');
   if (!verifySecret(secretHeader)) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    return errorResponse(new UnauthorizedError());
   }
 
   // Rate limit. All website-side traffic shares the website's egress IP,
@@ -84,10 +89,7 @@ export async function POST(req: NextRequest) {
   const rl = await checkRateLimit(ip, rateLimiters.websiteIntake);
   if (!rl.allowed) {
     const retryAfter = Math.max(1, Math.ceil((rl.resetAt - Date.now()) / 1000));
-    return NextResponse.json(
-      { error: 'Rate limit exceeded' },
-      { status: 429, headers: { 'Retry-After': String(retryAfter) } },
-    );
+    return errorResponse(new RateLimitError(retryAfter));
   }
 
   // Parse + validate body. Reject anything that doesn't conform — the
@@ -97,9 +99,10 @@ export async function POST(req: NextRequest) {
     const body = await req.json();
     parsed = SubmissionSchema.parse(body);
   } catch (err) {
-    return NextResponse.json(
-      { error: 'Invalid payload', details: err instanceof Error ? err.message : 'parse error' },
-      { status: 400 },
+    return errorResponse(
+      new ValidationError('Invalid payload', [
+        { field: 'body', message: err instanceof Error ? err.message : 'parse error' },
+      ]),
     );
   }
 
@@ -119,7 +122,7 @@ export async function POST(req: NextRequest) {
       { portSlug: parsed.port_slug, submissionId: parsed.submission_id },
       'website-inquiry rejected: unknown port',
     );
-    return NextResponse.json({ error: 'Unknown port' }, { status: 400 });
+    return errorResponse(new ValidationError('Unknown port'));
   }
 
   // Idempotent insert. Two parallel requests carrying the same submission_id

src/app/api/storage/[token]/route.ts

@@ -21,7 +21,13 @@ import { Readable } from 'node:stream';
 import { NextRequest, NextResponse } from 'next/server';
 
 import { MAX_FILE_SIZE } from '@/lib/constants/file-validation';
-import { errorResponse } from '@/lib/errors';
+import {
+  AppError,
+  errorResponse,
+  ForbiddenError,
+  NotFoundError,
+  ValidationError,
+} from '@/lib/errors';
 import { logger } from '@/lib/logger';
 import { redis } from '@/lib/redis';
 import { FilesystemBackend, getStorageBackend } from '@/lib/storage';
@@ -47,16 +53,13 @@ export async function GET(
 
   const backend = await getStorageBackend();
   if (!(backend instanceof FilesystemBackend)) {
-    return NextResponse.json(
-      { error: 'Storage proxy is only available in filesystem mode' },
-      { status: 404 },
-    );
+    return errorResponse(new NotFoundError('storage proxy'));
   }
 
   const result = verifyProxyToken(token, backend.getHmacSecret(), 'get');
   if (!result.ok) {
     logger.warn({ reason: result.reason }, 'Storage proxy token rejected');
-    return NextResponse.json({ error: 'Invalid or expired token' }, { status: 403 });
+    return errorResponse(new ForbiddenError('Invalid or expired token'));
   }
   const { payload } = result;
 
@@ -72,7 +75,7 @@ export async function GET(
   const setOk = await redis.set(replayKey, '1', 'EX', remainingSeconds, 'NX');
   if (setOk !== 'OK') {
     logger.warn({ key: payload.k }, 'Storage proxy token replay rejected');
-    return NextResponse.json({ error: 'Token already used' }, { status: 403 });
+    return errorResponse(new ForbiddenError('Token already used'));
   }
 
   let absolutePath: string;
@@ -80,22 +83,22 @@ export async function GET(
     absolutePath = backend.resolveKeyForProxy(payload.k);
   } catch (err) {
     logger.warn({ err, key: payload.k }, 'Storage proxy key resolution failed');
-    return NextResponse.json({ error: 'Invalid key' }, { status: 400 });
+    return errorResponse(new ValidationError('Invalid key'));
   }
 
   let size: number;
   try {
     const stat = await fs.stat(absolutePath);
     if (!stat.isFile()) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
+      return errorResponse(new NotFoundError('file'));
     }
     size = stat.size;
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
     if (code === 'ENOENT') {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
+      return errorResponse(new NotFoundError('file'));
     }
-    throw err;
+    return errorResponse(err);
   }
 
   // Convert the Node Readable into a Web ReadableStream for NextResponse.
@@ -140,16 +143,13 @@ export async function PUT(
 
   const backend = await getStorageBackend();
   if (!(backend instanceof FilesystemBackend)) {
-    return NextResponse.json(
-      { error: 'Storage proxy is only available in filesystem mode' },
-      { status: 404 },
-    );
+    return errorResponse(new NotFoundError('storage proxy'));
   }
 
   const result = verifyProxyToken(token, backend.getHmacSecret(), 'put');
   if (!result.ok) {
     logger.warn({ reason: result.reason }, 'Storage proxy upload token rejected');
-    return NextResponse.json({ error: 'Invalid or expired token' }, { status: 403 });
+    return errorResponse(new ForbiddenError('Invalid or expired token'));
   }
   const { payload } = result;
 
@@ -164,7 +164,7 @@ export async function PUT(
   const setOk = await redis.set(replayKey, '1', 'EX', remainingSeconds, 'NX');
   if (setOk !== 'OK') {
     logger.warn({ key: payload.k }, 'Storage proxy upload token replay rejected');
-    return NextResponse.json({ error: 'Token already used' }, { status: 403 });
+    return errorResponse(new ForbiddenError('Token already used'));
   }
 
   // Pre-flight size check via Content-Length so a malicious caller can't
@@ -172,14 +172,17 @@ export async function PUT(
   const contentLengthHeader = req.headers.get('content-length');
   const contentLength = contentLengthHeader ? Number(contentLengthHeader) : NaN;
   if (Number.isFinite(contentLength) && contentLength > MAX_FILE_SIZE) {
-    return NextResponse.json(
-      { error: `File exceeds ${MAX_FILE_SIZE} byte cap (Content-Length: ${contentLength})` },
-      { status: 413 },
+    return errorResponse(
+      new AppError(
+        413,
+        `File exceeds ${MAX_FILE_SIZE} byte cap (Content-Length: ${contentLength})`,
+        'PAYLOAD_TOO_LARGE',
+      ),
     );
   }
 
   if (!req.body) {
-    return NextResponse.json({ error: 'Empty body' }, { status: 400 });
+    return errorResponse(new ValidationError('Empty body'));
   }
 
   // Read the body into a buffer with a hard cap. Filesystem deployments are
@@ -200,9 +203,8 @@ export async function PUT(
         } catch {
           /* ignore */
         }
-        return NextResponse.json(
-          { error: `File exceeds ${MAX_FILE_SIZE} byte cap` },
-          { status: 413 },
+        return errorResponse(
+          new AppError(413, `File exceeds ${MAX_FILE_SIZE} byte cap`, 'PAYLOAD_TOO_LARGE'),
         );
       }
       chunks.push(Buffer.from(value));
@@ -210,7 +212,7 @@ export async function PUT(
     buffer = Buffer.concat(chunks);
   } catch (err) {
     logger.warn({ err, key: payload.k }, 'Storage proxy upload read failed');
-    return NextResponse.json({ error: 'Upload read failed' }, { status: 400 });
+    return errorResponse(new ValidationError('Upload read failed'));
   }
 
   // Magic-byte gate: when the token was minted with `c=application/pdf`
@@ -218,9 +220,8 @@ export async function PUT(
   // that isn't actually a PDF. Mirrors the post-upload check in
   // berth-pdf.service.ts so the two paths behave identically.
   if (payload.c === 'application/pdf' && !isPdfMagic(buffer)) {
-    return NextResponse.json(
-      { error: 'Uploaded file failed PDF magic-byte check (does not start with %PDF-).' },
-      { status: 400 },
+    return errorResponse(
+      new ValidationError('Uploaded file failed PDF magic-byte check (does not start with %PDF-).'),
     );
   }
 

src/app/api/v1/admin/email-templates/route.ts

@@ -1,5 +1,5 @@
 import { NextResponse } from 'next/server';
-import { eq, inArray } from 'drizzle-orm';
+import { inArray } from 'drizzle-orm';
 import { z } from 'zod';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
@@ -87,5 +87,3 @@ export const PUT = withAuth(
     }
   }),
 );
-
-void eq;

src/app/api/v1/admin/website-submissions/route.ts

@@ -1,5 +1,5 @@
 import { NextResponse } from 'next/server';
-import { and, desc, eq, inArray, lt, sql, type SQL } from 'drizzle-orm';
+import { and, desc, eq, inArray, sql, type SQL } from 'drizzle-orm';
 import { z } from 'zod';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
@@ -71,6 +71,3 @@ export const GET = withAuth(
     }
   }),
 );
-
-// Suppress lt unused-import lint
-void lt;

src/app/api/v1/berths/[id]/pdf-upload-url/handlers.ts

@@ -54,13 +54,19 @@ export const postHandler: RouteHandler = async (req, ctx, params) => {
     // so a race between two reps just shifts which one wins the version
     // slot. The storage key is gen_random_uuid()-namespaced so collisions
     // in the storage layer are impossible.
+    //
+    // storage-pathing-auditor H1: prefix the port slug so the
+    // filesystem-proxy port-binding token (`p` field) can be wired and
+    // the namespace matches `buildStoragePath` (which always leads with
+    // the port slug).
     const sanitized = fileName.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 200) || 'berth.pdf';
-    const storageKey = `berths/${params.id!}/uploads/${crypto.randomUUID()}_${sanitized}`;
+    const storageKey = `${ctx.portSlug}/berths/${params.id!}/uploads/${crypto.randomUUID()}_${sanitized}`;
 
     const backend = await getStorageBackend();
     const presigned = await backend.presignUpload(storageKey, {
       contentType: 'application/pdf',
       expirySeconds: 900,
+      portSlug: ctx.portSlug,
     });
 
     return NextResponse.json({

src/app/api/v1/clients/bulk/route.ts

@@ -10,7 +10,6 @@ import { clients, clientTags } from '@/lib/db/schema/clients';
 import { setClientTags } from '@/lib/services/clients.service';
 import {
   getClientArchiveDossier,
-  HIGH_STAKES_STAGES,
   type ClientArchiveDossier,
 } from '@/lib/services/client-archive-dossier.service';
 import {
@@ -21,7 +20,6 @@ import { notifyNextInLine } from '@/lib/services/next-in-line-notify.service';
 import { getQueue } from '@/lib/queue';
 import { logger } from '@/lib/logger';
 import { errorResponse } from '@/lib/errors';
-import type { PipelineStage } from '@/lib/constants';
 
 const bulkSchema = z.discriminatedUnion('action', [
   z.object({
@@ -221,8 +219,3 @@ export const POST = withAuth(async (req, ctx) => {
 
   return NextResponse.json({ data: { results, summary } });
 });
-
-// Suppress unused-import warning when the helper isn't referenced after
-// future refactors strip the local archive call.
-void HIGH_STAKES_STAGES;
-void ({} as PipelineStage);

src/app/api/v1/interests/bulk/route.ts

@@ -1,8 +1,8 @@
 import { NextResponse } from 'next/server';
 import { z } from 'zod';
-import { eq, and, inArray } from 'drizzle-orm';
+import { eq, and } from 'drizzle-orm';
 
-import { withAuth, withPermission } from '@/lib/api/helpers';
+import { withAuth } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { db } from '@/lib/db';
 import { interests } from '@/lib/db/schema/interests';
@@ -128,8 +128,3 @@ export const POST = withAuth(async (req, ctx) => {
 
   return NextResponse.json({ data: { results, summary } });
 });
-
-// Keep a single import alive (linter); used in the Drizzle inArray pattern below
-// in case a future caller wants set-based ops instead of per-row loops.
-void inArray;
-void withPermission;

src/app/api/webhooks/documenso/route.ts

@@ -139,8 +139,11 @@ async function handleDocumensoWebhook(req: NextRequest): Promise<NextResponse> {
         source: 'webhook',
       });
     }
-    // Always return 200 (webhook best-practice — don't leak signal).
-    return NextResponse.json({ ok: false, error: 'Invalid secret' }, { status: 200 });
+    // Always return 200 (webhook best-practice — don't leak signal). Body
+    // is intentionally empty/uniform — error-ux-auditor H5 noted the
+    // literal "Invalid secret" string confirms the endpoint expects a
+    // secret, which is a free reconnaissance hint for enumeration.
+    return NextResponse.json({ ok: false }, { status: 200 });
   }
 
   // Compute deduplication hash