@tantainnovative/ndpr-recipes 0.1.0

package/src/nextjs/app-router/api/dsr/route.ts

@@ -0,0 +1,128 @@
+/**
+ * Next.js App Router — DSR (Data Subject Rights) List/Create Route
+ *
+ * Handles listing and creating Data Subject Rights requests as required by
+ * NDPA Sections 34–38 (rights to access, rectification, erasure, portability,
+ * and objection). All requests must be acknowledged within 72 hours and
+ * fulfilled within 30 days under the Act.
+ *
+ * Endpoints
+ * ---------
+ *   GET  /api/dsr          — List DSR requests (optional ?status= filter)
+ *   POST /api/dsr          — Submit a new DSR request
+ *
+ * How to use
+ * ----------
+ * Copy this file to `app/api/dsr/route.ts` in your Next.js project.
+ * For single-request operations see `app/api/dsr/[id]/route.ts`.
+ *
+ * @module dsr/route
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+// ---------------------------------------------------------------------------
+// GET /api/dsr?status=pending
+// ---------------------------------------------------------------------------
+
+/**
+ * List all DSR requests, optionally filtered by status.
+ *
+ * Supports the admin/DPO dashboard — returns requests ordered newest-first
+ * so overdue items surface quickly. The optional `status` query parameter
+ * lets you display only pending, in-progress, or completed requests.
+ *
+ * Query params:
+ *   status (optional) — filter by request status: pending | in_progress | completed | rejected
+ *
+ * Returns 200 with an array of DSRRequest rows.
+ */
+export async function GET(req: NextRequest) {
+  const status = req.nextUrl.searchParams.get('status');
+
+  const requests = await prisma.dSRRequest.findMany({
+    where: status ? { status } : undefined,
+    orderBy: { submittedAt: 'desc' },
+  });
+
+  return NextResponse.json(requests);
+}
+
+// ---------------------------------------------------------------------------
+// POST /api/dsr
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit a new Data Subject Rights request.
+ *
+ * The NDPA requires organisations to provide a clear mechanism for data
+ * subjects to exercise their rights (Section 34). This route:
+ *   1. Validates required fields.
+ *   2. Calculates the statutory 30-day deadline (dueAt).
+ *   3. Persists the request with status 'pending'.
+ *   4. Writes an audit log entry for accountability.
+ *
+ * Body (JSON):
+ *   type             (required) — access | rectification | erasure | portability | objection
+ *   subjectName      (required) — full name of the data subject
+ *   subjectEmail     (required) — email address of the data subject
+ *   identifierType   (required) — how the subject is identified (e.g. 'email', 'account_id')
+ *   identifierValue  (required) — the subject's identifier value
+ *   subjectPhone     (optional) — phone number
+ *   description      (optional) — additional context from the subject
+ *
+ * Returns 201 with the newly created DSRRequest row.
+ */
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const {
+    type,
+    subjectName,
+    subjectEmail,
+    subjectPhone,
+    identifierType,
+    identifierValue,
+    description,
+  } = body;
+
+  if (!type || !subjectName || !subjectEmail || !identifierType || !identifierValue) {
+    return NextResponse.json(
+      { error: 'type, subjectName, subjectEmail, identifierType, and identifierValue are required' },
+      { status: 400 },
+    );
+  }
+
+  // NDPA mandates a 30-day response window from the date of submission.
+  const dueAt = new Date();
+  dueAt.setDate(dueAt.getDate() + 30);
+
+  const request = await prisma.dSRRequest.create({
+    data: {
+      type,
+      subjectName,
+      subjectEmail,
+      subjectPhone: subjectPhone ?? null,
+      identifierType,
+      identifierValue,
+      description: description ?? null,
+      status: 'pending',
+      dueAt,
+    },
+  });
+
+  // Audit log for NDPA Section 44 accountability principle.
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'dsr',
+      action: 'submitted',
+      entityId: request.id,
+      entityType: 'DSRRequest',
+      changes: { type, subjectEmail, status: 'pending' },
+    },
+  });
+
+  return NextResponse.json(request, { status: 201 });
+}

package/src/nextjs/app-router/api/ropa/route.ts

@@ -0,0 +1,234 @@
+/**
+ * Next.js App Router — ROPA (Record of Processing Activities) Route
+ *
+ * Handles listing, creating, updating, and archiving processing activity records.
+ * Under the NDPA accountability principle (analogous to GDPR Article 30), data
+ * controllers with more than 250 employees — or that process sensitive data —
+ * must maintain a Record of Processing Activities (ROPA).
+ *
+ * Endpoints
+ * ---------
+ *   GET    /api/ropa         — List all processing records (optional ?status= filter)
+ *   POST   /api/ropa         — Create a new processing record
+ *   PATCH  /api/ropa         — Update an existing processing record (body includes `id`)
+ *   DELETE /api/ropa?id=xxx  — Archive a processing record (soft delete)
+ *
+ * How to use
+ * ----------
+ * Copy this file to `app/api/ropa/route.ts` in your Next.js project.
+ *
+ * @module ropa/route
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+// ---------------------------------------------------------------------------
+// GET /api/ropa?status=active
+// ---------------------------------------------------------------------------
+
+/**
+ * List all processing activity records.
+ *
+ * Returns records ordered by creation date ascending so the ROPA reads
+ * chronologically. Filter by status to distinguish active from archived entries.
+ *
+ * Query params:
+ *   status (optional) — active | archived (default: returns all)
+ *
+ * Returns 200 with an array of ProcessingRecord rows.
+ */
+export async function GET(req: NextRequest) {
+  const status = req.nextUrl.searchParams.get('status');
+
+  const records = await prisma.processingRecord.findMany({
+    where: status ? { status } : undefined,
+    orderBy: { createdAt: 'asc' },
+  });
+
+  return NextResponse.json(records);
+}
+
+// ---------------------------------------------------------------------------
+// POST /api/ropa
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new processing activity record.
+ *
+ * Each record documents a single processing activity — for example, "Customer
+ * order processing" or "Marketing email campaigns". Together, all active records
+ * form the organisation's ROPA as required under the NDPA accountability principle.
+ *
+ * Body (JSON):
+ *   purpose             (required) — description of the processing activity
+ *   lawfulBasis         (required) — consent | contract | legal_obligation | vital_interests
+ *                                    | public_task | legitimate_interests
+ *   dataCategories      (required) — array of data category labels (e.g. ['name', 'email'])
+ *   dataSubjects        (required) — array of subject category labels (e.g. ['customers'])
+ *   recipients          (required) — array of recipient labels (e.g. ['payment processor'])
+ *   retentionPeriod     (required) — human-readable retention policy (e.g. '7 years')
+ *   securityMeasures    (required) — array of security measures in place
+ *   transferCountries   (optional) — array of countries receiving cross-border transfers
+ *   transferMechanism   (optional) — legal mechanism for transfers (e.g. 'adequacy decision')
+ *   dpiaConducted       (optional) — whether a DPIA has been performed (default false)
+ *
+ * Returns 201 with the newly created ProcessingRecord row.
+ */
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const {
+    purpose,
+    lawfulBasis,
+    dataCategories,
+    dataSubjects,
+    recipients,
+    retentionPeriod,
+    securityMeasures,
+    transferCountries,
+    transferMechanism,
+    dpiaConducted,
+  } = body;
+
+  if (
+    !purpose ||
+    !lawfulBasis ||
+    !Array.isArray(dataCategories) ||
+    !Array.isArray(dataSubjects) ||
+    !Array.isArray(recipients) ||
+    !retentionPeriod ||
+    !Array.isArray(securityMeasures)
+  ) {
+    return NextResponse.json(
+      {
+        error:
+          'purpose, lawfulBasis, dataCategories, dataSubjects, recipients, retentionPeriod, and securityMeasures are required',
+      },
+      { status: 400 },
+    );
+  }
+
+  const record = await prisma.processingRecord.create({
+    data: {
+      purpose,
+      lawfulBasis,
+      dataCategories,
+      dataSubjects,
+      recipients,
+      retentionPeriod,
+      securityMeasures,
+      transferCountries: transferCountries ?? null,
+      transferMechanism: transferMechanism ?? null,
+      dpiaConducted: dpiaConducted ?? false,
+      status: 'active',
+    },
+  });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'ropa',
+      action: 'created',
+      entityId: record.id,
+      entityType: 'ProcessingRecord',
+      changes: { purpose, lawfulBasis, status: 'active' },
+    },
+  });
+
+  return NextResponse.json(record, { status: 201 });
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /api/ropa
+// ---------------------------------------------------------------------------
+
+/**
+ * Update an existing processing activity record.
+ *
+ * Call this when a processing activity changes — e.g. a new data category
+ * is added, the retention period changes, or a DPIA is conducted. Keeping
+ * the ROPA up to date is part of the NDPA accountability obligation.
+ *
+ * Body (JSON):
+ *   id   (required) — ID of the ProcessingRecord to update
+ *   ...  (all other fields from POST are optional — only send what changed)
+ *
+ * Returns 200 with the updated ProcessingRecord row.
+ */
+export async function PATCH(req: NextRequest) {
+  const body = await req.json();
+  const { id, ...fields } = body;
+
+  if (!id) {
+    return NextResponse.json({ error: 'id is required in the request body' }, { status: 400 });
+  }
+
+  const existing = await prisma.processingRecord.findUnique({ where: { id } });
+  if (!existing) {
+    return NextResponse.json({ error: 'Processing record not found' }, { status: 404 });
+  }
+
+  const updated = await prisma.processingRecord.update({
+    where: { id },
+    data: fields,
+  });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'ropa',
+      action: 'updated',
+      entityId: id,
+      entityType: 'ProcessingRecord',
+      changes: fields,
+    },
+  });
+
+  return NextResponse.json(updated);
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /api/ropa?id=xxx
+// ---------------------------------------------------------------------------
+
+/**
+ * Archive a processing activity record (soft delete).
+ *
+ * Records are never hard-deleted — archiving sets status to 'archived' so
+ * the historical ROPA remains available for regulatory review. This supports
+ * the NDPA accountability principle requirement to demonstrate compliance
+ * over time, not just in the present.
+ *
+ * Query params:
+ *   id (required) — ID of the ProcessingRecord to archive
+ *
+ * Returns 200 `{ success: true }` when complete.
+ */
+export async function DELETE(req: NextRequest) {
+  const id = req.nextUrl.searchParams.get('id');
+
+  if (!id) {
+    return NextResponse.json({ error: 'id query parameter required' }, { status: 400 });
+  }
+
+  const existing = await prisma.processingRecord.findUnique({ where: { id } });
+  if (!existing) {
+    return NextResponse.json({ error: 'Processing record not found' }, { status: 404 });
+  }
+
+  await prisma.processingRecord.update({
+    where: { id },
+    data: { status: 'archived' },
+  });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'ropa',
+      action: 'archived',
+      entityId: id,
+      entityType: 'ProcessingRecord',
+    },
+  });
+
+  return NextResponse.json({ success: true });
+}

package/src/nextjs/app-router/layout-example.tsx

@@ -0,0 +1,178 @@
+/**
+ * Example: Full NDPA compliance wiring in a Next.js App Router layout.
+ *
+ * This file shows how to integrate the @tantainnovative/ndpr-toolkit consent
+ * banner with a persistent backend using the Prisma adapter. The pattern works
+ * for both the built-in Prisma adapter and the Drizzle adapter — swap out
+ * `prismaConsentAdapter` for `drizzleConsentAdapter` if you use Drizzle.
+ *
+ * What this example covers
+ * ------------------------
+ * - Wrapping your app with NDPRProvider so all child components can access the
+ *   consent context via `useConsent()`.
+ * - Rendering the NDPRConsent banner with a server-backed storage adapter so
+ *   consent decisions survive page refreshes and browser restarts.
+ * - Wiring the apiAdapter to your Next.js API route (`/api/consent`) for a
+ *   fully decoupled client ↔ server consent flow.
+ *
+ * Copy this file, adapt the userId retrieval to your auth system, and you're done.
+ *
+ * @see prisma/schema.prisma          — for the database schema
+ * @see src/nextjs/app-router/api/    — for the API route implementations
+ * @see src/adapters/prisma-consent.ts — for the server-side Prisma adapter
+ *
+ * @module nextjs/app-router/layout-example
+ */
+
+'use client';
+
+import React from 'react';
+import { NDPRProvider } from '@tantainnovative/ndpr-toolkit/core';
+import { NDPRConsent } from '@tantainnovative/ndpr-toolkit/presets';
+import { apiAdapter } from '@tantainnovative/ndpr-toolkit/adapters';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface NDPRLayoutProps {
+  children: React.ReactNode;
+  /**
+   * Optional: pass the authenticated user's ID down from your root layout.
+   * In a real app this comes from your session (NextAuth, Clerk, Supabase Auth, etc.).
+   *
+   * If no userId is available (unauthenticated visitor), pass a stable anonymous
+   * identifier instead — e.g. a UUID stored in a cookie. Consent must still be
+   * obtained even for non-authenticated users.
+   */
+  userId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Layout component
+// ---------------------------------------------------------------------------
+
+/**
+ * NDPRLayout — wraps your app with consent management and the banner UI.
+ *
+ * Recommended placement: inside your root `app/layout.tsx`, wrapped around
+ * the `{children}` slot. Example:
+ *
+ *   // app/layout.tsx
+ *   import { NDPRLayout } from '@/components/ndpr-layout';
+ *
+ *   export default async function RootLayout({ children }) {
+ *     const session = await getServerSession();
+ *     return (
+ *       <html lang="en">
+ *         <body>
+ *           <NDPRLayout userId={session?.user?.id}>
+ *             {children}
+ *           </NDPRLayout>
+ *         </body>
+ *       </html>
+ *     );
+ *   }
+ *
+ * Note: This component is marked 'use client' because NDPRProvider and the
+ * consent banner both require client-side interactivity. The session/userId
+ * should be resolved in the parent Server Component and passed as a prop.
+ */
+export default function NDPRLayout({ children, userId }: NDPRLayoutProps) {
+  // ---------------------------------------------------------------------------
+  // Subject identification
+  // ---------------------------------------------------------------------------
+
+  // In a real application, replace this with your actual auth system:
+  //   const { data: session } = useSession();           // NextAuth
+  //   const { user } = useUser();                       // Clerk
+  //   const { session } = useSessionContext();          // Supabase Auth
+  //
+  // For anonymous visitors: generate and persist a UUID in localStorage or a cookie
+  // so consent decisions are stable across page reloads.
+  const subjectId = userId ?? 'anonymous';
+
+  // ---------------------------------------------------------------------------
+  // Adapter
+  // ---------------------------------------------------------------------------
+
+  // apiAdapter points at the Next.js API route that wraps the Prisma/Drizzle adapter.
+  // The route is implemented in `src/nextjs/app-router/api/consent/route.ts`.
+  //
+  // For direct server-side use (SSR / Server Components), import and call
+  // `prismaConsentAdapter(prisma, subjectId)` directly instead.
+  const consentStorageAdapter = apiAdapter(`/api/consent?subjectId=${subjectId}`);
+
+  // ---------------------------------------------------------------------------
+  // Render
+  // ---------------------------------------------------------------------------
+
+  return (
+    <NDPRProvider
+      /**
+       * Your organisation's legal name — displayed in the consent banner headline
+       * and in the Data Subject Rights portal.
+       */
+      organizationName="Your Company"
+      /**
+       * DPO or privacy contact email — shown to data subjects who want to exercise
+       * their rights or ask questions about data processing.
+       */
+      dpoEmail="dpo@yourcompany.ng"
+    >
+      {/* Render your application's pages and components */}
+      {children}
+
+      {/*
+       * NDPRConsent — the NDPA-compliant consent banner.
+       *
+       * The `adapter` prop connects the banner to your database so consent
+       * decisions are persisted server-side and survive page refreshes.
+       *
+       * On first visit: the banner is displayed and the subject can accept,
+       * decline, or customise individual consent categories.
+       *
+       * On subsequent visits: the adapter loads the stored decision and the
+       * banner is hidden (no flicker, no double-prompt).
+       *
+       * The banner automatically handles:
+       *   - NDPA §25 — recording the lawful basis and consent version
+       *   - NDPA §26 — providing a clear withdrawal mechanism
+       *   - Immutable audit trail — every change is stored as a new record
+       */}
+      <NDPRConsent adapter={consentStorageAdapter} />
+    </NDPRProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Alternative: using the Drizzle adapter directly (no API route needed)
+// ---------------------------------------------------------------------------
+//
+// If you prefer to use the Drizzle adapter on the server side inside a
+// Server Component or a Route Handler, here is how to wire it:
+//
+//   import { drizzle } from 'drizzle-orm/node-postgres';
+//   import { Pool } from 'pg';
+//   import { drizzleConsentAdapter } from '@/adapters/drizzle-consent';
+//   import * as schema from '@/drizzle/schema';
+//
+//   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+//   const db = drizzle(pool, { schema });
+//
+//   // In a Server Component or API Route:
+//   const adapter = drizzleConsentAdapter(db, subjectId);
+//   const settings = await adapter.load();
+//
+// ---------------------------------------------------------------------------
+// Alternative: using the Prisma adapter directly (no API route needed)
+// ---------------------------------------------------------------------------
+//
+//   import { PrismaClient } from '@prisma/client';
+//   import { prismaConsentAdapter } from '@/adapters/prisma-consent';
+//
+//   const prisma = new PrismaClient();
+//
+//   // In a Server Component or API Route:
+//   const adapter = prismaConsentAdapter(prisma, subjectId);
+//   const settings = await adapter.load();

package/src/nextjs/app-router/middleware.ts

@@ -0,0 +1,113 @@
+/**
+ * Next.js App Router — Consent Middleware
+ *
+ * Provides a reusable consent-gate helper that can be called inside any
+ * App Router route handler (or in Next.js middleware.ts at the edge) to verify
+ * that a data subject has granted the required consent before the route proceeds.
+ *
+ * NDPA Section 25 requires that processing based on consent only happens when
+ * the data subject has freely given specific, informed, and unambiguous consent.
+ * This helper enforces that requirement at the HTTP layer.
+ *
+ * How to use
+ * ----------
+ * Call `consentMiddleware(req, 'marketing')` at the top of any route handler
+ * that requires a specific consent type. If the function returns a Response,
+ * return it immediately; otherwise continue with your logic:
+ *
+ *   import { consentMiddleware } from '../middleware';
+ *
+ *   export async function POST(req: NextRequest) {
+ *     const guard = await consentMiddleware(req, 'marketing');
+ *     if (guard) return guard; // blocked — return 403
+ *
+ *     // subject has consented — proceed
+ *   }
+ *
+ * Subject identification
+ * ----------------------
+ * The helper looks for a subject identifier in two places (in priority order):
+ *   1. The `x-subject-id` request header (set by your auth middleware or JWT)
+ *   2. The `subject_id` cookie (set by your consent banner on the client)
+ *
+ * @module middleware
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+/**
+ * Verify that the requesting data subject has granted the specified consent type.
+ *
+ * @param req             - The incoming NextRequest
+ * @param requiredConsent - The consent category key to check (e.g. 'marketing', 'analytics')
+ * @returns null if the subject has consented (allow through), or a NextResponse with
+ *          status 403 and an error body if the check fails (block the request).
+ */
+export async function consentMiddleware(
+  req: NextRequest,
+  requiredConsent: string,
+): Promise<NextResponse | null> {
+  // Resolve the subject identifier from the header or cookie.
+  const subjectId =
+    req.headers.get('x-subject-id') ?? req.cookies.get('subject_id')?.value ?? null;
+
+  if (!subjectId) {
+    return NextResponse.json(
+      { error: 'Consent verification required' },
+      { status: 403 },
+    );
+  }
+
+  // Load the most recent active consent record for this subject.
+  const record = await prisma.consentRecord.findFirst({
+    where: { subjectId, revokedAt: null },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  if (!record) {
+    return NextResponse.json(
+      { error: 'No consent on record' },
+      { status: 403 },
+    );
+  }
+
+  // Check that the specific consent type has been granted.
+  const consents = record.consents as Record<string, boolean>;
+
+  if (!consents[requiredConsent]) {
+    return NextResponse.json(
+      { error: `Consent for "${requiredConsent}" not granted` },
+      { status: 403 },
+    );
+  }
+
+  // Subject has consented — allow the request to proceed.
+  return null;
+}
+
+/**
+ * Higher-order helper: wraps a route handler with a consent gate.
+ *
+ * This is an alternative to calling consentMiddleware() manually at the top
+ * of every handler. Use it when all methods on a route require the same consent.
+ *
+ *   export const POST = withConsent('marketing', async (req) => {
+ *     // marketing consent guaranteed here
+ *   });
+ *
+ * @param requiredConsent - The consent category to enforce
+ * @param handler         - The route handler to wrap
+ */
+export function withConsent(
+  requiredConsent: string,
+  handler: (req: NextRequest, ctx: any) => Promise<NextResponse>,
+) {
+  return async (req: NextRequest, ctx: any): Promise<NextResponse> => {
+    const guard = await consentMiddleware(req, requiredConsent);
+    if (guard) return guard;
+    return handler(req, ctx);
+  };
+}