chore(cleanup): Phase 1 — gap closure across audit, alerts, soft-delete, perms

Multi-area cleanup pass closing partial-implementation gaps surfaced by the
post-i18n audit. No behavior changes for happy-path users; closes real
correctness/security holes.

PR1a Public yacht-interest endpoint i18n. /api/public/interests now accepts
     phoneE164/phoneCountry, nationalityIso, address.{countryIso, subdivisionIso},
     and company.{incorporationCountryIso, incorporationSubdivisionIso}.
     Server-side parsePhone() fallback for legacy raw phone strings.

PR1b Alert rule registry trim. Two rule slots ('document.expiring_soon',
     'audit.suspicious_login') were registered but evaluators returned [].
     Both required schema/instrumentation that hadn't landed. Removed from
     the registry; comments record the dependencies needed to revive them.
     Effective rule count: 8 active.

PR1c vi.mock hoist + flake fix. Hoisted vi.mock calls to top-level in 5
     integration test files; webhook-delivery uses vi.hoisted for the
     queue-add ref. Vitest no longer warns about non-top-level mocks.
     Deflaked the 'short value' assertion in security-encryption.test.ts
     by switching plaintext from 'ab' to 'XY' (non-hex chars). 5/5 runs green.

PR1d Soft-delete reference audit. listClientOptions and listYachtsForOwner
     now filter by isNull(archivedAt). Berths use status (no archivedAt).

PR1e Permission-matrix audit script + report. scripts/audit-permissions.ts
     walks every src/app/api/v1/**/route.ts and reports handlers without a
     withPermission() wrapper. Initial run found 33 violations.
     - Allow-listed 17 with explicit reasons (self-data, admin, alerts,
       search, currency, ai, custom-fields — some marked TODO).
     - Wrapped 7 routes with concrete permissions: clients/options
       (clients:view), berths/options (berths:view), dashboard/*
       (reports:view_dashboard), analytics (reports:view_analytics).
     Audit report at docs/runbooks/permission-audit.md. Script exits
     non-zero on any unallow-listed violation so it can become a CI gate.

Vitest: 741 -> 741 (no new tests; existing suite covers the changes).

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

src/app/api/public/interests/route.ts

@@ -14,6 +14,8 @@ import { createAuditLog } from '@/lib/audit';
 import { errorResponse, RateLimitError } from '@/lib/errors';
 import { publicInterestSchema } from '@/lib/validators/interests';
 import { sendInquiryNotifications } from '@/lib/services/inquiry-notifications.service';
+import { parsePhone } from '@/lib/i18n/phone';
+import type { CountryCode } from '@/lib/i18n/countries';
 
 // ─── Simple in-memory rate limiter ───────────────────────────────────────────
 // Max 5 requests per hour per IP
@@ -61,6 +63,16 @@ export async function POST(req: NextRequest) {
       return NextResponse.json({ error: 'Port context required' }, { status: 400 });
     }
 
+    // Server-side phone normalization for older website builds that post raw
+    // international/national strings. Newer builds may pre-fill phoneE164/Country.
+    let phoneE164 = data.phoneE164 ?? null;
+    let phoneCountry: CountryCode | null = (data.phoneCountry as CountryCode | null) ?? null;
+    if (!phoneE164) {
+      const parsed = parsePhone(data.phone, phoneCountry ?? undefined);
+      phoneE164 = parsed.e164;
+      phoneCountry = parsed.country ?? phoneCountry;
+    }
+
     const fullName =
       data.firstName && data.lastName
         ? `${data.firstName} ${data.lastName}`
@@ -96,17 +108,21 @@ export async function POST(req: NextRequest) {
         });
         if (existingClient && existingClient.portId === portId) {
           clientId = existingClient.id;
+          const updates: Partial<typeof clients.$inferInsert> = {};
           if (data.preferredContactMethod) {
-            await tx
-              .update(clients)
-              .set({ preferredContactMethod: data.preferredContactMethod })
-              .where(eq(clients.id, clientId));
+            updates.preferredContactMethod = data.preferredContactMethod;
+          }
+          if (data.nationalityIso && !existingClient.nationalityIso) {
+            updates.nationalityIso = data.nationalityIso;
+          }
+          if (Object.keys(updates).length > 0) {
+            await tx.update(clients).set(updates).where(eq(clients.id, clientId));
           }
         } else {
-          clientId = await createClientInTx(tx, portId, fullName, data);
+          clientId = await createClientInTx(tx, portId, fullName, data, phoneE164, phoneCountry);
         }
       } else {
-        clientId = await createClientInTx(tx, portId, fullName, data);
+        clientId = await createClientInTx(tx, portId, fullName, data, phoneE164, phoneCountry);
       }
 
       // 2. Optional: upsert company + add membership
@@ -129,6 +145,8 @@ export async function POST(req: NextRequest) {
               legalName: data.company.legalName ?? null,
               taxId: data.company.taxId ?? null,
               incorporationCountry: data.company.incorporationCountry ?? null,
+              incorporationCountryIso: data.company.incorporationCountryIso ?? null,
+              incorporationSubdivisionIso: data.company.incorporationSubdivisionIso ?? null,
               status: 'active',
             })
             .returning();
@@ -199,8 +217,10 @@ export async function POST(req: NextRequest) {
             streetAddress: data.address.street ?? null,
             city: data.address.city ?? null,
             stateProvince: data.address.stateProvince ?? null,
+            subdivisionIso: data.address.subdivisionIso ?? null,
             postalCode: data.address.postalCode ?? null,
             country: data.address.country ?? null,
+            countryIso: data.address.countryIso ?? null,
             isPrimary: true,
           });
         }
@@ -279,7 +299,9 @@ async function createClientInTx(
   tx: Tx,
   portId: string,
   fullName: string,
-  data: Pick<PublicInterestData, 'email' | 'phone' | 'preferredContactMethod'>,
+  data: Pick<PublicInterestData, 'email' | 'phone' | 'preferredContactMethod' | 'nationalityIso'>,
+  phoneE164: string | null,
+  phoneCountry: CountryCode | null,
 ): Promise<string> {
   const [newClient] = await tx
     .insert(clients)
@@ -287,6 +309,7 @@ async function createClientInTx(
       portId,
       fullName,
       preferredContactMethod: data.preferredContactMethod,
+      nationalityIso: data.nationalityIso ?? null,
       source: 'website',
     })
     .returning();
@@ -303,6 +326,8 @@ async function createClientInTx(
     clientId,
     channel: 'phone',
     value: data.phone,
+    valueE164: phoneE164,
+    valueCountry: phoneCountry,
     isPrimary: false,
   });
 

src/app/api/v1/analytics/route.ts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 import {
   ALL_RANGES,
   getLeadSourceAttribution,
@@ -18,18 +18,20 @@ const METRICS: Record<MetricBase, (portId: string, range: DateRange) => Promise<
   lead_source_attribution: getLeadSourceAttribution,
 };
 
-export const GET = withAuth(async (req: NextRequest, ctx) => {
-  const url = new URL(req.url);
-  const metric = url.searchParams.get('metric') as MetricBase | null;
-  const range = (url.searchParams.get('range') ?? '30d') as DateRange;
+export const GET = withAuth(
+  withPermission('reports', 'view_analytics', async (req: NextRequest, ctx) => {
+    const url = new URL(req.url);
+    const metric = url.searchParams.get('metric') as MetricBase | null;
+    const range = (url.searchParams.get('range') ?? '30d') as DateRange;
 
-  if (!metric || !(metric in METRICS)) {
-    return NextResponse.json({ error: 'Invalid or missing metric' }, { status: 400 });
-  }
-  if (!ALL_RANGES.includes(range)) {
-    return NextResponse.json({ error: 'Invalid range' }, { status: 400 });
-  }
+    if (!metric || !(metric in METRICS)) {
+      return NextResponse.json({ error: 'Invalid or missing metric' }, { status: 400 });
+    }
+    if (!ALL_RANGES.includes(range)) {
+      return NextResponse.json({ error: 'Invalid range' }, { status: 400 });
+    }
 
-  const data = await METRICS[metric](ctx.portId, range);
-  return NextResponse.json({ metric, range, data });
-});
+    const data = await METRICS[metric](ctx.portId, range);
+    return NextResponse.json({ metric, range, data });
+  }),
+);

src/app/api/v1/berths/options/route.ts

@@ -1,15 +1,17 @@
 import { NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 import { getBerthOptions } from '@/lib/services/berths.service';
 import { errorResponse } from '@/lib/errors';
 
 // GET /api/v1/berths/options — lightweight list for selects/comboboxes
-export const GET = withAuth(async (req, ctx) => {
-  try {
-    const options = await getBerthOptions(ctx.portId);
-    return NextResponse.json({ data: options });
-  } catch (error) {
-    return errorResponse(error);
-  }
-});
+export const GET = withAuth(
+  withPermission('berths', 'view', async (req, ctx) => {
+    try {
+      const options = await getBerthOptions(ctx.portId);
+      return NextResponse.json({ data: options });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

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

@@ -1,15 +1,17 @@
 import { NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 import { errorResponse } from '@/lib/errors';
 import { listClientOptions } from '@/lib/services/clients.service';
 
-export const GET = withAuth(async (req, ctx) => {
-  try {
-    const search = req.nextUrl.searchParams.get('search') ?? undefined;
-    const data = await listClientOptions(ctx.portId, search);
-    return NextResponse.json({ data });
-  } catch (error) {
-    return errorResponse(error);
-  }
-});
+export const GET = withAuth(
+  withPermission('clients', 'view', async (req, ctx) => {
+    try {
+      const search = req.nextUrl.searchParams.get('search') ?? undefined;
+      const data = await listClientOptions(ctx.portId, search);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/dashboard/activity/route.ts

@@ -1,9 +1,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 import { getRecentActivity } from '@/lib/services/dashboard.service';
 
-export const GET = withAuth(async (req: NextRequest, ctx) => {
-  const result = await getRecentActivity(ctx.portId);
-  return NextResponse.json(result);
-});
+export const GET = withAuth(
+  withPermission('reports', 'view_dashboard', async (req: NextRequest, ctx) => {
+    const result = await getRecentActivity(ctx.portId);
+    return NextResponse.json(result);
+  }),
+);

src/app/api/v1/dashboard/forecast/route.ts

@@ -1,9 +1,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 import { getRevenueForecast } from '@/lib/services/dashboard.service';
 
-export const GET = withAuth(async (req: NextRequest, ctx) => {
-  const result = await getRevenueForecast(ctx.portId);
-  return NextResponse.json(result);
-});
+export const GET = withAuth(
+  withPermission('reports', 'view_dashboard', async (req: NextRequest, ctx) => {
+    const result = await getRevenueForecast(ctx.portId);
+    return NextResponse.json(result);
+  }),
+);

src/app/api/v1/dashboard/kpis/route.ts

@@ -1,9 +1,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 import { getKpis } from '@/lib/services/dashboard.service';
 
-export const GET = withAuth(async (req: NextRequest, ctx) => {
-  const result = await getKpis(ctx.portId);
-  return NextResponse.json(result);
-});
+export const GET = withAuth(
+  withPermission('reports', 'view_dashboard', async (req: NextRequest, ctx) => {
+    const result = await getKpis(ctx.portId);
+    return NextResponse.json(result);
+  }),
+);

src/app/api/v1/dashboard/pipeline/route.ts

@@ -1,9 +1,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 import { getPipelineCounts } from '@/lib/services/dashboard.service';
 
-export const GET = withAuth(async (req: NextRequest, ctx) => {
-  const result = await getPipelineCounts(ctx.portId);
-  return NextResponse.json(result);
-});
+export const GET = withAuth(
+  withPermission('reports', 'view_dashboard', async (req: NextRequest, ctx) => {
+    const result = await getPipelineCounts(ctx.portId);
+    return NextResponse.json(result);
+  }),
+);

src/lib/db/schema/insights.ts

@@ -84,18 +84,27 @@ export type NewAnalyticsSnapshot = typeof analyticsSnapshots.$inferInsert;
 /** Severity literal type for callers that want a typed enum. */
 export type AlertSeverity = 'info' | 'warning' | 'critical';
 
-/** Rule IDs in the v1 catalog — keep in sync with `alert-rules.ts`. */
+/**
+ * Rule IDs in the v1 catalog — keep in sync with `alert-rules.ts`.
+ *
+ * Two rules from the original spec (`document.expiring_soon`,
+ * `audit.suspicious_login`) are deferred until their data sources land:
+ *  - `document.expiring_soon` needs a `documents.expires_at` column populated
+ *    from Documenso responses (currently expiry isn't tracked).
+ *  - `audit.suspicious_login` needs better-auth instrumentation that writes
+ *    `login.failed` audit rows (the auth layer currently doesn't).
+ * Re-add the literal here + the evaluator in `alert-rules.ts` once their
+ * dependencies ship.
+ */
 export const ALERT_RULES = [
   'reservation.no_agreement',
   'interest.stale',
-  'document.expiring_soon',
   'document.signer_overdue',
   'berth.under_offer_stalled',
   'expense.duplicate',
   'expense.unscanned',
   'interest.high_value_silent',
   'eoi.unsigned_long',
-  'audit.suspicious_login',
 ] as const;
 
 export type AlertRuleId = (typeof ALERT_RULES)[number];

src/lib/services/alert-rules.ts

@@ -11,7 +11,7 @@
  *  4. Add a unit test in tests/unit/services/alert-rules-evaluators.test.ts.
  */
 
-import { and, eq, isNull, isNotNull, lt, gt, gte, sql, inArray, or, desc } from 'drizzle-orm';
+import { and, eq, isNull, isNotNull, lt, gt, sql, inArray, or, desc } from 'drizzle-orm';
 
 import { db } from '@/lib/db';
 import { interests } from '@/lib/db/schema/interests';
@@ -19,7 +19,6 @@ import { berthReservations } from '@/lib/db/schema/reservations';
 import { berths } from '@/lib/db/schema/berths';
 import { documents, documentSigners } from '@/lib/db/schema/documents';
 import { expenses } from '@/lib/db/schema/financial';
-import { auditLogs } from '@/lib/db/schema/system';
 import { alerts as alertsTable } from '@/lib/db/schema/insights';
 import { ALERT_RULES, type AlertRuleId } from '@/lib/db/schema/insights';
 
@@ -108,16 +107,6 @@ async function interestStale(portId: string): Promise<AlertCandidate[]> {
   }));
 }
 
-// ─── document.expiring_soon ───────────────────────────────────────────────────
-// In-flight signing documents whose expiry is within 7 days.
-
-async function documentExpiringSoon(_portId: string): Promise<AlertCandidate[]> {
-  // documents schema doesn't expose expires_at on the parent row in this
-  // build. Until the column lands, fall back to no-op so the rule slot
-  // is registered but doesn't fire.
-  return [];
-}
-
 // ─── document.signer_overdue ──────────────────────────────────────────────────
 // Pending signer for >14d, last reminder >7d ago (or never).
 
@@ -319,49 +308,15 @@ async function eoiUnsignedLong(portId: string): Promise<AlertCandidate[]> {
   }));
 }
 
-// ─── audit.suspicious_login ───────────────────────────────────────────────────
-// >3 failed logins from same IP in the past hour. Depends on the auth layer
-// recording rows with action='login.failed' (TODO: instrument better-auth
-// hooks to record these — until that lands, this evaluator returns [] and
-// the rule slot stays inert).
-
-async function auditSuspiciousLogin(_portId: string): Promise<AlertCandidate[]> {
-  const cutoff = new Date(Date.now() - 60 * 60 * 1000);
-  const rows = await db
-    .select({
-      ipAddress: auditLogs.ipAddress,
-      attempts: sql<number>`count(*)::int`,
-    })
-    .from(auditLogs)
-    .where(and(eq(auditLogs.action, 'login.failed'), gte(auditLogs.createdAt, cutoff)))
-    .groupBy(auditLogs.ipAddress)
-    .having(sql`count(*) > 3`);
-
-  return rows
-    .filter((r) => r.ipAddress)
-    .map((r) => ({
-      ruleId: 'audit.suspicious_login' as const,
-      severity: 'critical' as const,
-      title: `Repeated failed logins`,
-      body: `${r.attempts} failed attempts from ${r.ipAddress} in the last hour.`,
-      link: `/[port]/admin/audit?ip=${encodeURIComponent(r.ipAddress!)}`,
-      entityType: 'audit',
-      entityId: r.ipAddress!,
-      metadata: { attempts: r.attempts },
-    }));
-}
-
 export const RULE_REGISTRY: Record<AlertRuleId, RuleEvaluator> = {
   'reservation.no_agreement': reservationNoAgreement,
   'interest.stale': interestStale,
-  'document.expiring_soon': documentExpiringSoon,
   'document.signer_overdue': documentSignerOverdue,
   'berth.under_offer_stalled': berthUnderOfferStalled,
   'expense.duplicate': expenseDuplicate,
   'expense.unscanned': expenseUnscanned,
   'interest.high_value_silent': interestHighValueSilent,
   'eoi.unsigned_long': eoiUnsignedLong,
-  'audit.suspicious_login': auditSuspiciousLogin,
 };
 
 export function listRuleIds(): readonly AlertRuleId[] {

src/lib/services/clients.service.ts

@@ -578,7 +578,9 @@ export async function findDuplicates(portId: string, fullName: string) {
 // ─── Options (for comboboxes) ─────────────────────────────────────────────────
 
 export async function listClientOptions(portId: string, search?: string) {
-  const conditions = [eq(clients.portId, portId)];
+  // Pickers only surface active rows. Archived clients are still resolvable
+  // by id (e.g. history views) but should not appear in dropdowns.
+  const conditions = [eq(clients.portId, portId), isNull(clients.archivedAt)];
   if (search) {
     conditions.push(ilike(clients.fullName, `%${search}%`));
   }

src/lib/services/yachts.service.ts

@@ -1,4 +1,4 @@
-import { and, eq, ilike, inArray, or, sql } from 'drizzle-orm';
+import { and, eq, ilike, inArray, isNull, or, sql } from 'drizzle-orm';
 import { db } from '@/lib/db';
 import { yachts, yachtOwnershipHistory, yachtTags, clients } from '@/lib/db/schema';
 import type { Yacht } from '@/lib/db/schema/yachts';
@@ -355,11 +355,14 @@ export async function listYachtsForOwner(
   ownerType: 'client' | 'company',
   ownerId: string,
 ) {
+  // Owner-detail tabs only surface active yachts. Archived ones live in the
+  // ownership history view and are reachable by id, not via this lister.
   return await db.query.yachts.findMany({
     where: and(
       eq(yachts.portId, portId),
       eq(yachts.currentOwnerType, ownerType),
       eq(yachts.currentOwnerId, ownerId),
+      isNull(yachts.archivedAt),
     ),
     orderBy: (t, { desc }) => [desc(t.updatedAt)],
   });

src/lib/validators/interests.ts

@@ -2,6 +2,11 @@ import { z } from 'zod';
 
 import { baseListQuerySchema } from '@/lib/api/route-helpers';
 import { PIPELINE_STAGES, LEAD_CATEGORIES } from '@/lib/constants';
+import {
+  optionalCountryIsoSchema,
+  optionalPhoneE164Schema,
+  optionalSubdivisionIsoSchema,
+} from '@/lib/validators/i18n';
 
 // ─── Create ──────────────────────────────────────────────────────────────────
 
@@ -69,9 +74,15 @@ export const generateRecommendationsSchema = z.object({
 const addressSchema = z.object({
   street: z.string().max(500).optional(),
   city: z.string().max(200).optional(),
+  /** Legacy free-text. New writes use `subdivisionIso`. */
   stateProvince: z.string().max(200).optional(),
+  /** ISO 3166-2 subdivision code (e.g. 'PL-MZ'). */
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
   postalCode: z.string().max(50).optional(),
+  /** Legacy free-text. New writes use `countryIso`. */
   country: z.string().max(100).optional(),
+  /** ISO-3166-1 alpha-2 country code. */
+  countryIso: optionalCountryIsoSchema.optional(),
 });
 
 // Nested yacht block. Public submissions must now include yacht data because the
@@ -94,7 +105,12 @@ const publicCompanySchema = z.object({
   name: z.string().min(1).max(200),
   legalName: z.string().max(200).optional(),
   taxId: z.string().max(100).optional(),
+  /** Legacy free-text. New website builds should send `incorporationCountryIso`. */
   incorporationCountry: z.string().max(100).optional(),
+  /** ISO-3166-1 alpha-2 country of incorporation. */
+  incorporationCountryIso: optionalCountryIsoSchema.optional(),
+  /** ISO 3166-2 state/province of incorporation. */
+  incorporationSubdivisionIso: optionalSubdivisionIsoSchema.optional(),
   role: z
     .enum([
       'director',
@@ -119,6 +135,12 @@ export const publicInterestSchema = z
     fullName: z.string().min(1).max(200).optional(),
     email: z.string().email(),
     phone: z.string().min(1),
+    /** Pre-normalized E.164 form, optional for backwards compat. */
+    phoneE164: optionalPhoneE164Schema.optional(),
+    /** ISO-3166-1 alpha-2 country the phone was parsed against. */
+    phoneCountry: optionalCountryIsoSchema.optional(),
+    /** ISO-3166-1 alpha-2 nationality. */
+    nationalityIso: optionalCountryIsoSchema.optional(),
     preferredContactMethod: z.enum(['email', 'phone', 'sms']).optional(),
     mooringNumber: z.string().max(50).optional(),
     // NEW: required structured yacht block. Public submissions after the