feat(gdpr): staff-triggered client-data export bundle (Article 15)

Adds a full GDPR Article 15 (right of access) workflow. Staff trigger
an export from the client detail; a BullMQ worker assembles every row
keyed to that client (profile, contacts, addresses, notes, tags,
yachts, company memberships, interests, reservations, invoices,
documents, last 500 audit events) into JSON + a self-contained HTML
report, ZIPs them, uploads to MinIO, and optionally emails the client
a 7-day signed download link.

- New table gdpr_exports tracks lifecycle (pending → building → ready
  → sent / failed) with a 30-day cleanup target
- Bundle builder (gdpr-bundle-builder.ts) — pure read-side, tenant-
  scoped, with HTML escaping to block injection from rogue field values
- Worker hook in export queue dispatches on job name 'gdpr-export'
- New audit actions: 'request_gdpr_export', 'send_gdpr_export'
- API: POST/GET /api/v1/clients/:id/gdpr-export (admin-gated, exports
  rate-limit, Article-15 audit on POST); GET /:exportId returns a
  fresh signed URL
- UI: <GdprExportButton> dialog on client detail header — admin-only,
  shows recent exports, supports email-to-client + override recipient,
  polls every 5s while open
- Validation: refuses email-to-client when no primary email + no
  override (rather than silently dropping the send)

Tests: 778/778 vitest (was 771) — +7 covering builder happy path,
HTML escaping, tenant isolation, empty client, request-flow validation,
and audit / queue interaction.

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

src/lib/audit.ts

@@ -14,7 +14,9 @@ export type AuditAction =
   | 'permission_denied'
   | 'revert'
   | 'revoke_invite'
-  | 'resend_invite';
+  | 'resend_invite'
+  | 'request_gdpr_export'
+  | 'send_gdpr_export';
 
 export interface AuditLogParams {
   /** Null for system-generated events. */

src/lib/db/migrations/0018_stormy_spencer_smythe.sql

@@ -0,0 +1,21 @@
+CREATE TABLE "gdpr_exports" (
+	"id" text PRIMARY KEY NOT NULL,
+	"port_id" text NOT NULL,
+	"client_id" text NOT NULL,
+	"requested_by" text NOT NULL,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"storage_key" text,
+	"size_bytes" integer,
+	"error" text,
+	"sent_to" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"ready_at" timestamp with time zone,
+	"sent_at" timestamp with time zone,
+	"expires_at" timestamp with time zone
+);
+--> statement-breakpoint
+ALTER TABLE "gdpr_exports" ADD CONSTRAINT "gdpr_exports_port_id_ports_id_fk" FOREIGN KEY ("port_id") REFERENCES "public"."ports"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "gdpr_exports" ADD CONSTRAINT "gdpr_exports_client_id_clients_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."clients"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "gdpr_exports" ADD CONSTRAINT "gdpr_exports_requested_by_user_id_fk" FOREIGN KEY ("requested_by") REFERENCES "public"."user"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_gdpr_exports_client" ON "gdpr_exports" USING btree ("client_id");--> statement-breakpoint
+CREATE INDEX "idx_gdpr_exports_port_created" ON "gdpr_exports" USING btree ("port_id","created_at");

src/lib/db/migrations/meta/_journal.json

@@ -127,6 +127,13 @@
       "when": 1777398450555,
       "tag": "0017_tiny_mercury",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1777399135032,
+      "tag": "0018_stormy_spencer_smythe",
+      "breakpoints": true
     }
   ]
 }

src/lib/db/schema/gdpr.ts

@@ -0,0 +1,56 @@
+/**
+ * GDPR client-data export tracking.
+ *
+ * Each row is one export request. The actual bundle (a ZIP holding
+ * `client.json` + `client.html` and a copy of every attached file)
+ * lives in MinIO; we keep the storage key here plus the lifecycle
+ * markers needed for audit + the "download history" UI.
+ */
+
+import { pgTable, text, timestamp, integer, index } from 'drizzle-orm/pg-core';
+
+import { ports } from './ports';
+import { clients } from './clients';
+import { user } from './users';
+
+export const gdprExports = pgTable(
+  'gdpr_exports',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id, { onDelete: 'cascade' }),
+    clientId: text('client_id')
+      .notNull()
+      .references(() => clients.id, { onDelete: 'cascade' }),
+    /** Staff member who requested the export. */
+    requestedBy: text('requested_by')
+      .notNull()
+      .references(() => user.id, { onDelete: 'restrict' }),
+    /** 'pending' | 'building' | 'ready' | 'sent' | 'failed' */
+    status: text('status').notNull().default('pending'),
+    /** MinIO path under the configured bucket — null until the worker uploads. */
+    storageKey: text('storage_key'),
+    sizeBytes: integer('size_bytes'),
+    /** When status='failed', the truncated error message. */
+    error: text('error'),
+    /** Email recipient if the bundle was emailed (typically the client's primary). */
+    sentTo: text('sent_to'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    readyAt: timestamp('ready_at', { withTimezone: true }),
+    sentAt: timestamp('sent_at', { withTimezone: true }),
+    /** Cleanup target — bundles are removed from MinIO after this. */
+    expiresAt: timestamp('expires_at', { withTimezone: true }),
+  },
+  (table) => [
+    index('idx_gdpr_exports_client').on(table.clientId),
+    index('idx_gdpr_exports_port_created').on(table.portId, table.createdAt),
+  ],
+);
+
+export type GdprExport = typeof gdprExports.$inferSelect;
+export type NewGdprExport = typeof gdprExports.$inferInsert;
+
+export type GdprExportStatus = 'pending' | 'building' | 'ready' | 'sent' | 'failed';

src/lib/db/schema/index.ts

@@ -53,5 +53,8 @@ export * from './insights';
 // AI usage ledger (Phase 3b)
 export * from './ai-usage';
 
+// GDPR export tracking (Phase 3d)
+export * from './gdpr';
+
 // Relations (must come last — references all tables)
 export * from './relations';

src/lib/queue/workers/export.ts

@@ -8,10 +8,22 @@ export const exportWorker = new Worker(
   'export',
   async (job: Job) => {
     logger.info({ jobId: job.id, jobName: job.name }, 'Processing export job');
-    // TODO(L2): implement export job handlers
-    //   - CSV data export
-    //   - PDF export
-    //   - Parent company report export
+    switch (job.name) {
+      case 'gdpr-export': {
+        const data = job.data as {
+          exportId: string;
+          portId: string;
+          clientId: string;
+          emailToClient: boolean;
+          emailOverride: string | null;
+        };
+        const { processGdprExportJob } = await import('@/lib/services/gdpr-export.service');
+        await processGdprExportJob(data);
+        break;
+      }
+      default:
+        logger.warn({ jobName: job.name }, 'Unknown export job');
+    }
   },
   {
     connection: { url: process.env.REDIS_URL! } as ConnectionOptions,

src/lib/services/gdpr-bundle-builder.ts

@@ -0,0 +1,267 @@
+/**
+ * Builds the structured payload that becomes the JSON + HTML inside a
+ * GDPR client-data export. Pure read-side — no writes, no I/O outside
+ * Drizzle. The worker pairs this with the actual ZIP/upload/email work.
+ *
+ * GDPR Article 15 (right of access) requires that we hand the data
+ * subject everything we hold about them. This builder enumerates every
+ * table that carries a `clientId` foreign key plus the polymorphic
+ * yacht ownership rows that resolve to this client.
+ */
+
+import { and, eq, or } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { NotFoundError } from '@/lib/errors';
+import {
+  clients,
+  clientContacts,
+  clientAddresses,
+  clientNotes,
+  clientRelationships,
+  clientTags,
+} from '@/lib/db/schema/clients';
+import { tags } from '@/lib/db/schema/system';
+import { companies, companyMemberships } from '@/lib/db/schema/companies';
+import { yachts } from '@/lib/db/schema/yachts';
+import { interests } from '@/lib/db/schema/interests';
+import { berthReservations } from '@/lib/db/schema/reservations';
+import { invoices } from '@/lib/db/schema/financial';
+import { documents } from '@/lib/db/schema/documents';
+import { auditLogs } from '@/lib/db/schema/system';
+
+export interface GdprBundle {
+  /** Bundle metadata for traceability. */
+  meta: {
+    generatedAt: string;
+    portId: string;
+    clientId: string;
+    schemaVersion: 1;
+  };
+  client: Record<string, unknown>;
+  contacts: Record<string, unknown>[];
+  addresses: Record<string, unknown>[];
+  tags: Array<{ id: string; name: string; color: string }>;
+  relationships: Record<string, unknown>[];
+  notes: Record<string, unknown>[];
+  ownedYachts: Record<string, unknown>[];
+  companyMemberships: Array<{
+    membership: Record<string, unknown>;
+    company: Record<string, unknown>;
+  }>;
+  interests: Record<string, unknown>[];
+  reservations: Record<string, unknown>[];
+  invoices: Record<string, unknown>[];
+  documents: Record<string, unknown>[];
+  auditTrail: Record<string, unknown>[];
+}
+
+/**
+ * Loads every row that references this client across all tenant-scoped
+ * tables. Every query is filtered by `portId` as well, so a stale FK
+ * to another tenant never leaks across.
+ */
+export async function buildClientBundle(clientId: string, portId: string): Promise<GdprBundle> {
+  const client = await db.query.clients.findFirst({ where: eq(clients.id, clientId) });
+  if (!client || client.portId !== portId) {
+    throw new NotFoundError('Client');
+  }
+
+  const [
+    contacts,
+    addresses,
+    relationships,
+    notes,
+    tagJoins,
+    ownedYachts,
+    membershipRows,
+    interestRows,
+    reservationRows,
+    invoiceRows,
+    documentRows,
+    auditRows,
+  ] = await Promise.all([
+    db.query.clientContacts.findMany({ where: eq(clientContacts.clientId, clientId) }),
+    db.query.clientAddresses.findMany({ where: eq(clientAddresses.clientId, clientId) }),
+    db.query.clientRelationships.findMany({
+      where: or(
+        eq(clientRelationships.clientAId, clientId),
+        eq(clientRelationships.clientBId, clientId),
+      ),
+    }),
+    db.query.clientNotes.findMany({ where: eq(clientNotes.clientId, clientId) }),
+    db
+      .select({
+        id: tags.id,
+        name: tags.name,
+        color: tags.color,
+      })
+      .from(clientTags)
+      .innerJoin(tags, eq(clientTags.tagId, tags.id))
+      .where(eq(clientTags.clientId, clientId)),
+    db.query.yachts.findMany({
+      where: and(
+        eq(yachts.portId, portId),
+        eq(yachts.currentOwnerType, 'client'),
+        eq(yachts.currentOwnerId, clientId),
+      ),
+    }),
+    db
+      .select({ membership: companyMemberships, company: companies })
+      .from(companyMemberships)
+      .innerJoin(companies, eq(companyMemberships.companyId, companies.id))
+      .where(and(eq(companyMemberships.clientId, clientId), eq(companies.portId, portId))),
+    db.query.interests.findMany({
+      where: and(eq(interests.clientId, clientId), eq(interests.portId, portId)),
+    }),
+    db.query.berthReservations.findMany({
+      where: and(eq(berthReservations.clientId, clientId), eq(berthReservations.portId, portId)),
+    }),
+    db.query.invoices.findMany({
+      where: and(
+        eq(invoices.portId, portId),
+        eq(invoices.billingEntityType, 'client'),
+        eq(invoices.billingEntityId, clientId),
+      ),
+    }),
+    db.query.documents.findMany({
+      where: and(eq(documents.portId, portId), eq(documents.clientId, clientId)),
+    }),
+    db.query.auditLogs.findMany({
+      where: and(
+        eq(auditLogs.portId, portId),
+        eq(auditLogs.entityType, 'client'),
+        eq(auditLogs.entityId, clientId),
+      ),
+      orderBy: (t, { desc }) => [desc(t.createdAt)],
+      limit: 500,
+    }),
+  ]);
+
+  return {
+    meta: {
+      generatedAt: new Date().toISOString(),
+      portId,
+      clientId,
+      schemaVersion: 1,
+    },
+    client: client as unknown as Record<string, unknown>,
+    contacts: contacts as unknown as Record<string, unknown>[],
+    addresses: addresses as unknown as Record<string, unknown>[],
+    tags: tagJoins,
+    relationships: relationships as unknown as Record<string, unknown>[],
+    notes: notes as unknown as Record<string, unknown>[],
+    ownedYachts: ownedYachts as unknown as Record<string, unknown>[],
+    companyMemberships: membershipRows as unknown as Array<{
+      membership: Record<string, unknown>;
+      company: Record<string, unknown>;
+    }>,
+    interests: interestRows as unknown as Record<string, unknown>[],
+    reservations: reservationRows as unknown as Record<string, unknown>[],
+    invoices: invoiceRows as unknown as Record<string, unknown>[],
+    documents: documentRows as unknown as Record<string, unknown>[],
+    auditTrail: auditRows as unknown as Record<string, unknown>[],
+  };
+}
+
+// ─── HTML rendering ──────────────────────────────────────────────────────────
+
+function escapeHtml(s: unknown): string {
+  if (s === null || s === undefined) return '';
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function tableSection(title: string, rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) {
+    return `<section><h2>${escapeHtml(title)}</h2><p class="empty">No records.</p></section>`;
+  }
+  const headers = Array.from(
+    rows.reduce<Set<string>>((set, r) => {
+      Object.keys(r).forEach((k) => set.add(k));
+      return set;
+    }, new Set()),
+  );
+  const headerHtml = headers.map((h) => `<th>${escapeHtml(h)}</th>`).join('');
+  const bodyHtml = rows
+    .map(
+      (r) =>
+        `<tr>${headers
+          .map((h) => {
+            const v = r[h];
+            const cell = typeof v === 'object' && v !== null ? JSON.stringify(v) : v;
+            return `<td>${escapeHtml(cell)}</td>`;
+          })
+          .join('')}</tr>`,
+    )
+    .join('');
+  return `
+    <section>
+      <h2>${escapeHtml(title)} <small>(${rows.length})</small></h2>
+      <table><thead><tr>${headerHtml}</tr></thead><tbody>${bodyHtml}</tbody></table>
+    </section>
+  `;
+}
+
+/**
+ * Renders the bundle as a self-contained HTML document — no external
+ * resources, no JS — so it opens in any browser including offline.
+ */
+export function renderBundleHtml(bundle: GdprBundle): string {
+  const clientName = String(bundle.client.fullName ?? bundle.meta.clientId ?? 'Unknown');
+  const sections = [
+    tableSection('Client', [bundle.client]),
+    tableSection('Contacts', bundle.contacts),
+    tableSection('Addresses', bundle.addresses),
+    tableSection('Tags', bundle.tags as unknown as Record<string, unknown>[]),
+    tableSection('Relationships', bundle.relationships),
+    tableSection('Notes', bundle.notes),
+    tableSection('Owned yachts', bundle.ownedYachts),
+    tableSection(
+      'Company memberships',
+      bundle.companyMemberships.map((m) => ({
+        ...m.membership,
+        companyName: m.company.name,
+        companyLegalName: m.company.legalName,
+      })),
+    ),
+    tableSection('Interests', bundle.interests),
+    tableSection('Reservations', bundle.reservations),
+    tableSection('Invoices', bundle.invoices),
+    tableSection('Documents', bundle.documents),
+    tableSection('Audit trail (last 500 events)', bundle.auditTrail),
+  ].join('\n');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Personal data export — ${escapeHtml(clientName)}</title>
+<style>
+  body { font: 14px/1.5 -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif; margin: 2rem; max-width: 1200px; }
+  h1 { border-bottom: 2px solid #333; padding-bottom: 0.5rem; }
+  h2 { color: #1a3a5c; margin-top: 2rem; }
+  small { font-weight: normal; color: #666; }
+  .empty { color: #888; font-style: italic; }
+  table { width: 100%; border-collapse: collapse; margin: 0.5rem 0; font-size: 12px; }
+  th, td { border: 1px solid #ddd; padding: 4px 8px; vertical-align: top; word-break: break-word; }
+  th { background: #f0f4f8; text-align: left; }
+  tr:nth-child(even) { background: #fafbfc; }
+  .meta { background: #f0f4f8; padding: 1rem; border-radius: 4px; }
+</style>
+</head>
+<body>
+  <h1>Personal data export</h1>
+  <div class="meta">
+    <div><strong>Client:</strong> ${escapeHtml(clientName)} <code>(${escapeHtml(bundle.meta.clientId)})</code></div>
+    <div><strong>Generated:</strong> ${escapeHtml(bundle.meta.generatedAt)}</div>
+    <div><strong>Schema version:</strong> ${escapeHtml(bundle.meta.schemaVersion)}</div>
+  </div>
+  ${sections}
+</body>
+</html>`;
+}

src/lib/services/gdpr-export.service.ts

@@ -0,0 +1,265 @@
+/**
+ * GDPR client-data export orchestration.
+ *
+ * `requestExport()` creates a row, queues a BullMQ job, and returns. The
+ * `processExportJob()` handler builds the bundle, ZIPs JSON+HTML into
+ * MinIO, optionally emails the client a download link, and updates the
+ * row to status='ready' or 'sent'.
+ *
+ * Bundles are kept for 30 days then expired by maintenance (the
+ * gdpr_exports.expires_at column is the cleanup target).
+ */
+
+import archiver from 'archiver';
+import { eq, and } from 'drizzle-orm';
+import { PassThrough } from 'node:stream';
+
+import { db } from '@/lib/db';
+import { gdprExports, type GdprExport } from '@/lib/db/schema/gdpr';
+import { clients, clientContacts } from '@/lib/db/schema/clients';
+import { ports } from '@/lib/db/schema/ports';
+import { env } from '@/lib/env';
+import { NotFoundError, ValidationError } from '@/lib/errors';
+import { logger } from '@/lib/logger';
+import { minioClient, getPresignedUrl } from '@/lib/minio';
+import { getQueue } from '@/lib/queue';
+import { createAuditLog } from '@/lib/audit';
+import { buildClientBundle, renderBundleHtml } from '@/lib/services/gdpr-bundle-builder';
+
+const EXPIRY_DAYS = 30;
+const PRESIGN_EXPIRY_SECONDS = 7 * 24 * 60 * 60; // 7 days for the email link
+
+interface RequestExportInput {
+  clientId: string;
+  portId: string;
+  requestedBy: string;
+  /** When true, the bundle is emailed to the client's primary address once ready. */
+  emailToClient: boolean;
+  /** Override recipient (e.g. lawyer or agent). When set, takes precedence over the client's primary email. */
+  emailOverride?: string | null;
+  ipAddress: string;
+  userAgent: string;
+}
+
+export interface RequestExportResult {
+  export: GdprExport;
+}
+
+export async function requestGdprExport(input: RequestExportInput): Promise<RequestExportResult> {
+  const client = await db.query.clients.findFirst({
+    where: eq(clients.id, input.clientId),
+  });
+  if (!client || client.portId !== input.portId) throw new NotFoundError('Client');
+
+  if (input.emailToClient && !input.emailOverride) {
+    const primary = await db.query.clientContacts.findFirst({
+      where: and(
+        eq(clientContacts.clientId, input.clientId),
+        eq(clientContacts.channel, 'email'),
+        eq(clientContacts.isPrimary, true),
+      ),
+    });
+    if (!primary) {
+      throw new ValidationError(
+        'Client has no primary email contact — provide an emailOverride or add one before exporting.',
+      );
+    }
+  }
+
+  const [row] = await db
+    .insert(gdprExports)
+    .values({
+      portId: input.portId,
+      clientId: input.clientId,
+      requestedBy: input.requestedBy,
+      status: 'pending',
+    })
+    .returning();
+  if (!row) throw new Error('Failed to create export row');
+
+  void createAuditLog({
+    userId: input.requestedBy,
+    portId: input.portId,
+    action: 'request_gdpr_export',
+    entityType: 'client',
+    entityId: input.clientId,
+    metadata: { exportId: row.id, emailToClient: input.emailToClient },
+    ipAddress: input.ipAddress,
+    userAgent: input.userAgent,
+  });
+
+  await getQueue('export').add('gdpr-export', {
+    exportId: row.id,
+    portId: input.portId,
+    clientId: input.clientId,
+    emailToClient: input.emailToClient,
+    emailOverride: input.emailOverride ?? null,
+  });
+
+  return { export: row };
+}
+
+interface ProcessJobInput {
+  exportId: string;
+  portId: string;
+  clientId: string;
+  emailToClient: boolean;
+  emailOverride: string | null;
+}
+
+/**
+ * Worker entry point. Loads the bundle, ZIPs it, uploads to MinIO,
+ * (optionally) emails the client. Failures mark the row 'failed' with
+ * the truncated error.
+ */
+export async function processGdprExportJob(input: ProcessJobInput): Promise<void> {
+  await db
+    .update(gdprExports)
+    .set({ status: 'building' })
+    .where(eq(gdprExports.id, input.exportId));
+
+  try {
+    const bundle = await buildClientBundle(input.clientId, input.portId);
+    const json = JSON.stringify(bundle, null, 2);
+    const html = renderBundleHtml(bundle);
+
+    // Stream a ZIP into a buffer. Receipts/contracts are not included
+    // here — they live on file rows referenced by the bundle and would
+    // bloat the archive. Add them later if Article-15 requests demand.
+    const zip = archiver('zip', { zlib: { level: 9 } });
+    const sink = new PassThrough();
+    const chunks: Buffer[] = [];
+    sink.on('data', (c: Buffer) => chunks.push(c));
+    const done = new Promise<Buffer>((resolve, reject) => {
+      sink.on('end', () => resolve(Buffer.concat(chunks)));
+      sink.on('error', reject);
+      zip.on('error', reject);
+    });
+    zip.pipe(sink);
+    zip.append(json, { name: 'client.json' });
+    zip.append(html, { name: 'client.html' });
+    zip.append(
+      `Personal data export for client ${input.clientId}\nGenerated ${bundle.meta.generatedAt}\n`,
+      { name: 'README.txt' },
+    );
+    await zip.finalize();
+    const buffer = await done;
+
+    const port = await db.query.ports.findFirst({ where: eq(ports.id, input.portId) });
+    const portSlug = port?.slug ?? 'unknown';
+    const storageKey = `${portSlug}/gdpr-exports/${input.clientId}/${input.exportId}.zip`;
+
+    await minioClient.putObject(env.MINIO_BUCKET, storageKey, buffer, buffer.length, {
+      'Content-Type': 'application/zip',
+      'Content-Disposition': `attachment; filename="gdpr-export-${input.clientId}.zip"`,
+    });
+
+    const expiresAt = new Date(Date.now() + EXPIRY_DAYS * 24 * 60 * 60 * 1000);
+    await db
+      .update(gdprExports)
+      .set({
+        status: 'ready',
+        storageKey,
+        sizeBytes: buffer.length,
+        readyAt: new Date(),
+        expiresAt,
+      })
+      .where(eq(gdprExports.id, input.exportId));
+
+    if (input.emailToClient) {
+      await emailExport(input, storageKey);
+    }
+  } catch (err) {
+    logger.error({ err, exportId: input.exportId }, 'GDPR export job failed');
+    await db
+      .update(gdprExports)
+      .set({
+        status: 'failed',
+        error: err instanceof Error ? err.message.slice(0, 1000) : 'Unknown error',
+      })
+      .where(eq(gdprExports.id, input.exportId));
+    throw err; // let BullMQ retry per the queue config
+  }
+}
+
+async function emailExport(input: ProcessJobInput, storageKey: string): Promise<void> {
+  // Resolve the recipient: explicit override beats primary contact.
+  let recipient = input.emailOverride;
+  if (!recipient) {
+    const primary = await db.query.clientContacts.findFirst({
+      where: and(
+        eq(clientContacts.clientId, input.clientId),
+        eq(clientContacts.channel, 'email'),
+        eq(clientContacts.isPrimary, true),
+      ),
+    });
+    recipient = primary?.value ?? null;
+  }
+  if (!recipient) {
+    logger.warn(
+      { exportId: input.exportId, clientId: input.clientId },
+      'GDPR export ready but no email recipient — skipping send',
+    );
+    return;
+  }
+
+  const url = await getPresignedUrl(storageKey, PRESIGN_EXPIRY_SECONDS);
+  const client = await db.query.clients.findFirst({ where: eq(clients.id, input.clientId) });
+  const name = client?.fullName ?? 'there';
+  const expiry = new Date(Date.now() + PRESIGN_EXPIRY_SECONDS * 1000).toUTCString();
+
+  const subject = 'Your personal data export is ready';
+  const html = `
+    <p>Hello ${escapeHtml(name)},</p>
+    <p>You requested a copy of the personal data we hold about you. The export is ready and contains:</p>
+    <ul>
+      <li><code>client.json</code> — machine-readable data dump</li>
+      <li><code>client.html</code> — same data as a printable web page</li>
+    </ul>
+    <p><a href="${url}">Download the export (ZIP, expires ${escapeHtml(expiry)})</a></p>
+    <p>If you have any questions, reply to this email.</p>
+  `;
+  const text = `Your personal data export is ready: ${url}\nThe link expires ${expiry}.`;
+
+  const { sendEmail } = await import('@/lib/email/index');
+  await sendEmail(recipient, subject, html, undefined, text, input.portId);
+
+  await db
+    .update(gdprExports)
+    .set({ status: 'sent', sentAt: new Date(), sentTo: recipient })
+    .where(eq(gdprExports.id, input.exportId));
+}
+
+function escapeHtml(s: unknown): string {
+  if (s === null || s === undefined) return '';
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/** Lists exports for a client (most-recent first) — feeds the admin "history" UI. */
+export async function listClientExports(clientId: string, portId: string) {
+  const client = await db.query.clients.findFirst({ where: eq(clients.id, clientId) });
+  if (!client || client.portId !== portId) throw new NotFoundError('Client');
+
+  return db.query.gdprExports.findMany({
+    where: eq(gdprExports.clientId, clientId),
+    orderBy: (t, { desc }) => [desc(t.createdAt)],
+    limit: 25,
+  });
+}
+
+/** Generates a fresh signed URL for an existing ready/sent export. */
+export async function getExportDownloadUrl(exportId: string, portId: string): Promise<string> {
+  const row = await db.query.gdprExports.findFirst({
+    where: and(eq(gdprExports.id, exportId), eq(gdprExports.portId, portId)),
+  });
+  if (!row) throw new NotFoundError('Export');
+  if (!row.storageKey || (row.status !== 'ready' && row.status !== 'sent')) {
+    throw new ValidationError('Export is not ready to download');
+  }
+  return getPresignedUrl(row.storageKey, PRESIGN_EXPIRY_SECONDS);
+}