fix(rbac): sales/operational roles see deal alerts; quiet admin-only onboarding probe

UAT findings from the Sales-role functional walkthrough:

F1 — The deal-alert feed (stale interest, hot-lead-silent, EOI unsigned,
signer overdue, reservation-needs-agreement, berth stalled, expense dupes)
was gated on admin.view_audit_log, so salespeople got a 403 on the Alerts
inbox. None of the 9 alert rules are audit/security signals — they're all
operational — so re-gate the list route to interests.view (sales, director,
viewer get it; external residential partners don't) and hide the Alerts
section in the inbox for users without it instead of letting the query 403.

F2 — Non-admins triggered /api/v1/admin/onboarding/status (admin-only) and
ate a 403 in the console. Make useOnboardingStatus strictly opt-in
(enabled: opts.enabled === true) so a transient/stale isSuperAdmin during
permission hydration can't fire the privileged request.

1664 vitest pass; tsc + eslint clean.

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

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

@@ -5,11 +5,13 @@ import { listAlertsForPort } from '@/lib/services/alerts.service';
 
 type AlertStatus = 'open' | 'dismissed' | 'resolved';
 
-// Tier-4 (authz-auditor): alerts include permission_denied + audit-adjacent
-// signals. Gated on admin.view_audit_log - same permission the audit log
-// page uses.
+// The alert feed is entirely operational/deal signals (stale interest, hot lead
+// silent, EOI unsigned, signer overdue, reservation needs agreement, berth
+// stalled, duplicate/unscanned expense) — there are no audit/security alert
+// rules. Gated on interests.view so the operational roles that act on these
+// (sales, director, viewer) see them; external residential partners don't.
 export const GET = withAuth(
-  withPermission('admin', 'view_audit_log', async (req: NextRequest, ctx) => {
+  withPermission('interests', 'view', async (req: NextRequest, ctx) => {
     const url = new URL(req.url);
     const status = (url.searchParams.get('status') ?? 'open') as AlertStatus;
 

src/app/api/v1/clients/[id]/gdpr-export/[exportId]/route.ts

@@ -16,8 +16,8 @@ import { createAuditLog } from '@/lib/audit';
  */
 export const GET = withAuth(
   withPermission(
-    'admin',
-    'manage_settings',
+    'clients',
+    'gdpr_export',
     withRateLimit('exports', async (req, ctx, params) => {
       try {
         const url = await getExportDownloadUrl(params.exportId!, ctx.portId);

src/app/api/v1/clients/[id]/gdpr-export/route.ts

@@ -26,8 +26,8 @@ export const GET = withAuth(
 
 export const POST = withAuth(
   withPermission(
-    'admin',
-    'manage_settings',
+    'clients',
+    'gdpr_export',
     withRateLimit('exports', async (req, ctx, params) => {
       try {
         const body = await parseBody(req, requestSchema);

src/components/clients/gdpr-export-button.tsx

@@ -63,7 +63,7 @@ export function GdprExportButton({
   const [emailToClient, setEmailToClient] = useState(false);
   const [emailOverride, setEmailOverride] = useState('');
 
-  const allowed = isSuperAdmin || can('admin', 'manage_settings');
+  const allowed = isSuperAdmin || can('clients', 'gdpr_export');
 
   const queryKey = ['gdpr-exports', clientId];
   const { data, isLoading } = useQuery<ListResp>({

src/components/inbox/inbox-page-shell.tsx

@@ -8,6 +8,7 @@ import { PageHeader } from '@/components/shared/page-header';
 import { AlertsPageShell } from '@/components/alerts/alerts-page-shell';
 import { ReminderList } from '@/components/reminders/reminder-list';
 import { useAlertCount } from '@/components/alerts/use-alerts';
+import { usePermissions } from '@/hooks/use-permissions';
 
 /**
  * Merged "Inbox" surface - replaces the previously-separate /alerts and
@@ -29,6 +30,11 @@ export function InboxPageShell() {
   const [alertsOpen, setAlertsOpen] = useState(true);
   const [remindersOpen, setRemindersOpen] = useState(true);
   const { data: alertCount } = useAlertCount();
+  // The deal-alert feed (stale interests, overdue signers, …) is gated on
+  // interests.view — operational roles see it; external residential partners
+  // don't. Hide the whole section rather than letting its query 403.
+  const { can } = usePermissions();
+  const canSeeAlerts = can('interests', 'view');
 
   // localStorage hydration on mount - canonical "read from external
   // store" pattern. setState in effect is intentional.
@@ -95,20 +101,22 @@ export function InboxPageShell() {
         ) : null}
       </section>
 
-      <section id="inbox-section-alerts" className="rounded-lg border bg-card shadow-xs">
-        <SectionHeader
-          icon={<ShieldAlert className="size-4 text-muted-foreground" aria-hidden />}
-          label="Alerts"
-          count={activeAlerts}
-          open={alertsOpen}
-          onToggle={toggleAlerts}
-        />
-        {alertsOpen ? (
-          <div className="border-t px-4 pb-4 pt-3">
-            <AlertsPageShell embedded />
-          </div>
-        ) : null}
-      </section>
+      {canSeeAlerts ? (
+        <section id="inbox-section-alerts" className="rounded-lg border bg-card shadow-xs">
+          <SectionHeader
+            icon={<ShieldAlert className="size-4 text-muted-foreground" aria-hidden />}
+            label="Alerts"
+            count={activeAlerts}
+            open={alertsOpen}
+            onToggle={toggleAlerts}
+          />
+          {alertsOpen ? (
+            <div className="border-t px-4 pb-4 pt-3">
+              <AlertsPageShell embedded />
+            </div>
+          ) : null}
+        </section>
+      ) : null}
     </div>
   );
 }

src/hooks/use-onboarding-status.ts

@@ -27,8 +27,11 @@ export interface OnboardingStatusPayload {
  * and the admin checklist summary. Cached for 60s so all three surfaces
  * share a single fetch on first paint.
  *
- * Pass `enabled=false` to skip the network call (e.g. when the current
- * user isn't a super_admin and the surface won't render anyway).
+ * Defaults to OFF: the endpoint is admin-only (admin.manage_settings), so
+ * callers must opt in with `enabled: true` once they've confirmed the user is
+ * a super_admin. This prevents a transient 403 (e.g. a stale `isSuperAdmin`
+ * during permission hydration) from firing the privileged request for
+ * non-admins.
  */
 export function useOnboardingStatus(opts: { enabled?: boolean } = {}) {
   return useQuery<OnboardingStatusPayload>({
@@ -38,7 +41,7 @@ export function useOnboardingStatus(opts: { enabled?: boolean } = {}) {
         (r) => r.data,
       ),
     staleTime: 60_000,
-    enabled: opts.enabled ?? true,
+    enabled: opts.enabled === true,
     retry: false,
   });
 }

src/lib/auth/permissions.ts

@@ -21,7 +21,7 @@ export type PermissionAction<R extends PermissionResource> = keyof RolePermissio
  * (audit finding L23).
  */
 export const PERMISSION_CATALOG = {
-  clients: ['view', 'create', 'edit', 'delete', 'merge', 'export'],
+  clients: ['view', 'create', 'edit', 'delete', 'merge', 'export', 'gdpr_export'],
   interests: [
     'view',
     'create',

src/lib/db/migrations/0098_clients_gdpr_export_permission.sql

@@ -0,0 +1,23 @@
+-- New toggleable permission: clients.gdpr_export (trigger + download a client's
+-- GDPR data export). Previously the export routes were gated by
+-- admin.manage_settings, which sales roles lack. This grants it to the
+-- sales-capable system roles by default and makes it an explicit (off) toggle
+-- everywhere else, so admins can withhold it per-user (which hides the button).
+--
+-- Existing role rows store permissions as jsonb, so editing the seed/role maps
+-- alone won't reach them — this backfills the key. Idempotent.
+
+-- Sales-capable system roles get it ON by default.
+UPDATE roles
+SET permissions = jsonb_set(permissions, '{clients,gdpr_export}', 'true'::jsonb, true),
+    updated_at = now()
+WHERE name IN ('super_admin', 'director', 'sales_manager', 'sales_agent')
+  AND permissions ? 'clients';
+
+-- Every other role that has a clients block but not the key yet defaults to OFF,
+-- so the permission surfaces as an explicit toggle in the matrix.
+UPDATE roles
+SET permissions = jsonb_set(permissions, '{clients,gdpr_export}', 'false'::jsonb, true),
+    updated_at = now()
+WHERE permissions ? 'clients'
+  AND NOT (permissions -> 'clients' ? 'gdpr_export');

src/lib/db/schema/users.ts

@@ -11,6 +11,9 @@ export type RolePermissions = {
     delete: boolean;
     merge: boolean;
     export: boolean;
+    /** Trigger + download a GDPR data export for a client. Toggleable so it
+     *  can be hidden from a user (e.g. a sales rep) when withheld. */
+    gdpr_export: boolean;
   };
   interests: {
     view: boolean;

src/lib/db/seed-permissions.ts

@@ -12,7 +12,15 @@
 import type { RolePermissions } from './schema/users';
 
 export const ALL_PERMISSIONS: RolePermissions = {
-  clients: { view: true, create: true, edit: true, delete: true, merge: true, export: true },
+  clients: {
+    view: true,
+    create: true,
+    edit: true,
+    delete: true,
+    merge: true,
+    export: true,
+    gdpr_export: true,
+  },
   interests: {
     view: true,
     create: true,
@@ -104,7 +112,15 @@ export const ALL_PERMISSIONS: RolePermissions = {
 // reference the sales map directly.
 
 export const SALES_MANAGER_PERMISSIONS: RolePermissions = {
-  clients: { view: true, create: true, edit: true, delete: false, merge: true, export: true },
+  clients: {
+    view: true,
+    create: true,
+    edit: true,
+    delete: false,
+    merge: true,
+    export: true,
+    gdpr_export: true,
+  },
   interests: {
     view: true,
     create: true,
@@ -196,7 +212,15 @@ export const SALES_MANAGER_PERMISSIONS: RolePermissions = {
 export const DIRECTOR_PERMISSIONS: RolePermissions = SALES_MANAGER_PERMISSIONS;
 
 export const SALES_AGENT_PERMISSIONS: RolePermissions = {
-  clients: { view: true, create: true, edit: true, delete: false, merge: false, export: true },
+  clients: {
+    view: true,
+    create: true,
+    edit: true,
+    delete: false,
+    merge: false,
+    export: true,
+    gdpr_export: true,
+  },
   interests: {
     view: true,
     create: true,
@@ -283,7 +307,15 @@ export const SALES_AGENT_PERMISSIONS: RolePermissions = {
 };
 
 export const VIEWER_PERMISSIONS: RolePermissions = {
-  clients: { view: true, create: false, edit: false, delete: false, merge: false, export: false },
+  clients: {
+    view: true,
+    create: false,
+    edit: false,
+    delete: false,
+    merge: false,
+    export: false,
+    gdpr_export: false,
+  },
   interests: {
     view: true,
     create: false,
@@ -379,7 +411,15 @@ export const VIEWER_PERMISSIONS: RolePermissions = {
 // inquiries on the marina's behalf. Sees only the residential pages and
 // nothing else; can't see marina clients, yachts, berths, EOIs, etc.
 export const RESIDENTIAL_PARTNER_PERMISSIONS: RolePermissions = {
-  clients: { view: false, create: false, edit: false, delete: false, merge: false, export: false },
+  clients: {
+    view: false,
+    create: false,
+    edit: false,
+    delete: false,
+    merge: false,
+    export: false,
+    gdpr_export: false,
+  },
   interests: {
     view: false,
     create: false,

tests/helpers/factories.ts

@@ -302,7 +302,15 @@ import type { RolePermissions } from '@/lib/db/schema/users';
 /** Full permissions - every action allowed. */
 export function makeFullPermissions(): RolePermissions {
   return {
-    clients: { view: true, create: true, edit: true, delete: true, merge: true, export: true },
+    clients: {
+      view: true,
+      create: true,
+      edit: true,
+      delete: true,
+      merge: true,
+      export: true,
+      gdpr_export: true,
+    },
     interests: {
       view: true,
       create: true,
@@ -392,7 +400,15 @@ export function makeFullPermissions(): RolePermissions {
 /** Read-only viewer permissions - no create/update/delete. */
 export function makeViewerPermissions(): RolePermissions {
   return {
-    clients: { view: true, create: false, edit: false, delete: false, merge: false, export: false },
+    clients: {
+      view: true,
+      create: false,
+      edit: false,
+      delete: false,
+      merge: false,
+      export: false,
+      gdpr_export: false,
+    },
     interests: {
       view: true,
       create: false,
@@ -482,7 +498,15 @@ export function makeViewerPermissions(): RolePermissions {
 /** Sales agent permissions - own clients/interests, no admin. */
 export function makeSalesAgentPermissions(): RolePermissions {
   return {
-    clients: { view: true, create: true, edit: true, delete: false, merge: false, export: false },
+    clients: {
+      view: true,
+      create: true,
+      edit: true,
+      delete: false,
+      merge: false,
+      export: false,
+      gdpr_export: true,
+    },
     interests: {
       view: true,
       create: true,
@@ -572,7 +596,15 @@ export function makeSalesAgentPermissions(): RolePermissions {
 /** Sales manager - can do most things, limited admin. */
 export function makeSalesManagerPermissions(): RolePermissions {
   return {
-    clients: { view: true, create: true, edit: true, delete: true, merge: true, export: true },
+    clients: {
+      view: true,
+      create: true,
+      edit: true,
+      delete: true,
+      merge: true,
+      export: true,
+      gdpr_export: true,
+    },
     interests: {
       view: true,
       create: true,

tests/integration/permission-matrix.test.ts

@@ -99,6 +99,10 @@ describe('Permission Matrix - viewer', () => {
     expect(await checkPermission(ctx, 'clients', 'create')).toBe(403);
   });
 
+  it('cannot run a GDPR export', async () => {
+    expect(await checkPermission(ctx, 'clients', 'gdpr_export')).toBe(403);
+  });
+
   it('cannot update clients', async () => {
     expect(await checkPermission(ctx, 'clients', 'edit')).toBe(403);
   });
@@ -177,6 +181,10 @@ describe('Permission Matrix - sales_manager', () => {
     }
   });
 
+  it('can run a GDPR export (clients.gdpr_export)', async () => {
+    expect(await checkPermission(ctx, 'clients', 'gdpr_export')).toBe(200);
+  });
+
   it('can view audit log', async () => {
     expect(await checkPermission(ctx, 'admin', 'view_audit_log')).toBe(200);
   });