test(audit-fixes): cover the new permission and webhook surfaces

Adds integration coverage for the routes / handlers shipped in the
preceding audit-fix commits, plus refactors two route files to expose
inner handlers from a sibling `handlers.ts` (the pattern used elsewhere
in `src/app/api/v1`) so tests can call them without the
`withAuth(withPermission(…))` wrapper.

New tests (18 cases across 4 files):
- `tests/integration/portal-auth.test.ts` (6) — verifyPortalToken
  rejects tokens missing `aud: 'portal'` or `iss: 'pn-crm'`, with the
  wrong audience (CRM-session-replay shape) or wrong issuer, plus a
  round-trip happy path. Locks in the portal-vs-CRM token isolation.
- `tests/integration/api/saved-views-ownership.test.ts` (6) — patch
  and delete handlers return 403 for a different user, 404 for an
  unknown id or cross-port id, and 200 for the owner. Ownership is
  enforced at the route layer regardless of the service's internal
  filtering.
- `tests/integration/api/berth-reservations-list.test.ts` (3) — the
  new global list returns rows for the current port only and honors
  pagination params. A reservation in a different port never leaks.
- `tests/integration/documents-expired-webhook.test.ts` (3) —
  handleDocumentExpired flips the document to `expired`, also flips
  the linked interest's `eoiStatus`, writes a `documentEvents` row,
  and is a no-op (not a throw) when the documensoId is unknown.

Refactors:
- `src/app/api/v1/saved-views/[id]/route.ts` extracts `patchHandler` /
  `deleteHandler` (and the shared `assertViewOwner`) into
  `handlers.ts`. The route file is now a 4-line `withAuth(handler)`
  wrapper.
- `src/app/api/v1/berth-reservations/route.ts` extracts `listHandler`
  similarly. Tests import directly from `handlers.ts`.

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

src/app/api/v1/berth-reservations/handlers.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+
+import type { AuthContext } from '@/lib/api/helpers';
+import { parseQuery } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listReservations } from '@/lib/services/berth-reservations.service';
+import { listReservationsSchema } from '@/lib/validators/reservations';
+
+/**
+ * Port-scoped global list of reservations across all berths. Inner handler
+ * lives here so it can be invoked directly from integration tests without
+ * the `withAuth(withPermission(...))` wrappers (matches the convention
+ * used throughout `src/app/api/v1/*`).
+ */
+export async function listHandler(req: Request, ctx: AuthContext): Promise<NextResponse> {
+  try {
+    const query = parseQuery(req as never, listReservationsSchema);
+    const result = await listReservations(ctx.portId, query);
+    const { page, limit } = query;
+    const totalPages = Math.ceil(result.total / limit);
+    return NextResponse.json({
+      data: result.data,
+      pagination: {
+        page,
+        pageSize: limit,
+        total: result.total,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/berth-reservations/route.ts

@@ -1,31 +1,4 @@
-import { NextResponse } from 'next/server';
-
 import { withAuth, withPermission } from '@/lib/api/helpers';
-import { parseQuery } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { listReservations } from '@/lib/services/berth-reservations.service';
-import { listReservationsSchema } from '@/lib/validators/reservations';
+import { listHandler } from './handlers';
 
-export const GET = withAuth(
-  withPermission('reservations', 'view', async (req, ctx) => {
-    try {
-      const query = parseQuery(req, listReservationsSchema);
-      const result = await listReservations(ctx.portId, query);
-      const { page, limit } = query;
-      const totalPages = Math.ceil(result.total / limit);
-      return NextResponse.json({
-        data: result.data,
-        pagination: {
-          page,
-          pageSize: limit,
-          total: result.total,
-          totalPages,
-          hasNextPage: page < totalPages,
-          hasPreviousPage: page > 1,
-        },
-      });
-    } catch (error) {
-      return errorResponse(error);
-    }
-  }),
-);
+export const GET = withAuth(withPermission('reservations', 'view', listHandler));

src/app/api/v1/saved-views/[id]/handlers.ts

@@ -0,0 +1,68 @@
+import { and, eq } from 'drizzle-orm';
+import { NextResponse } from 'next/server';
+
+import type { AuthContext } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import { savedViews } from '@/lib/db/schema';
+import { errorResponse } from '@/lib/errors';
+import { savedViewsService } from '@/lib/services/saved-views.service';
+import { updateSavedViewSchema } from '@/lib/validators/saved-views';
+
+/**
+ * Resolves the view and enforces ownership before mutating.
+ *
+ * Returns a 404 when the view does not exist (or lives in a different port)
+ * and a 403 when it belongs to a different user. The 404-before-403 split
+ * matches the rest of the API and avoids leaking the existence of another
+ * user's saved view via timing or status code.
+ */
+async function assertViewOwner(
+  id: string,
+  portId: string,
+  userId: string,
+): Promise<NextResponse | null> {
+  const view = await db.query.savedViews.findFirst({
+    where: and(eq(savedViews.id, id), eq(savedViews.portId, portId)),
+  });
+  if (!view) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+  if (view.userId !== userId) {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+  }
+  return null;
+}
+
+export async function patchHandler(
+  req: Request,
+  ctx: AuthContext,
+  params: { id?: string },
+): Promise<NextResponse> {
+  try {
+    const id = params.id ?? '';
+    const denied = await assertViewOwner(id, ctx.portId, ctx.userId);
+    if (denied) return denied;
+    const body = await parseBody(req as never, updateSavedViewSchema);
+    const view = await savedViewsService.update(ctx.portId, ctx.userId, id, body);
+    return NextResponse.json({ data: view });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}
+
+export async function deleteHandler(
+  _req: Request,
+  ctx: AuthContext,
+  params: { id?: string },
+): Promise<NextResponse> {
+  try {
+    const id = params.id ?? '';
+    const denied = await assertViewOwner(id, ctx.portId, ctx.userId);
+    if (denied) return denied;
+    await savedViewsService.delete(ctx.portId, ctx.userId, id);
+    return NextResponse.json({ data: null }, { status: 200 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/saved-views/[id]/route.ts

@@ -1,53 +1,5 @@
-import { and, eq } from 'drizzle-orm';
-import { NextResponse } from 'next/server';
-
 import { withAuth } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { db } from '@/lib/db';
-import { savedViews } from '@/lib/db/schema';
-import { errorResponse } from '@/lib/errors';
-import { savedViewsService } from '@/lib/services/saved-views.service';
-import { updateSavedViewSchema } from '@/lib/validators/saved-views';
+import { patchHandler, deleteHandler } from './handlers';
 
-/** Resolves the view and enforces ownership before mutating. */
-async function assertViewOwner(
-  id: string,
-  portId: string,
-  userId: string,
-): Promise<NextResponse | null> {
-  const view = await db.query.savedViews.findFirst({
-    where: and(eq(savedViews.id, id), eq(savedViews.portId, portId)),
-  });
-  if (!view) {
-    return NextResponse.json({ error: 'Not found' }, { status: 404 });
-  }
-  if (view.userId !== userId) {
-    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
-  }
-  return null;
-}
-
-export const PATCH = withAuth(async (req, ctx, params) => {
-  try {
-    const id = params.id ?? '';
-    const denied = await assertViewOwner(id, ctx.portId, ctx.userId);
-    if (denied) return denied;
-    const body = await parseBody(req, updateSavedViewSchema);
-    const view = await savedViewsService.update(ctx.portId, ctx.userId, id, body);
-    return NextResponse.json({ data: view });
-  } catch (error) {
-    return errorResponse(error);
-  }
-});
-
-export const DELETE = withAuth(async (_req, ctx, params) => {
-  try {
-    const id = params.id ?? '';
-    const denied = await assertViewOwner(id, ctx.portId, ctx.userId);
-    if (denied) return denied;
-    await savedViewsService.delete(ctx.portId, ctx.userId, id);
-    return NextResponse.json({ data: null }, { status: 200 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-});
+export const PATCH = withAuth(patchHandler);
+export const DELETE = withAuth(deleteHandler);