@tantainnovative/ndpr-recipes 0.1.0

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

@@ -0,0 +1,182 @@
+/**
+ * Next.js App Router — Breach Notification List/Create Route
+ *
+ * Handles listing and creating data breach reports as required by NDPA
+ * Section 40, which mandates that controllers notify the NDPC within 72 hours
+ * of discovering a breach that poses a risk to data subject rights and freedoms.
+ *
+ * Endpoints
+ * ---------
+ *   GET  /api/breach       — List breach reports (optional ?status= filter)
+ *   POST /api/breach       — Create a new breach report
+ *
+ * How to use
+ * ----------
+ * Copy this file to `app/api/breach/route.ts` in your Next.js project.
+ * For single-report operations see `app/api/breach/[id]/route.ts`.
+ *
+ * @module breach/route
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+// ---------------------------------------------------------------------------
+// Severity auto-calculation helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive an initial severity rating from the breach category and the number
+ * of estimated affected subjects. This is a heuristic — the DPO should review
+ * and adjust before the NDPC notification is sent.
+ *
+ * @param category          - Breach category string (e.g. 'unauthorized_access')
+ * @param estimatedAffected - Approximate number of affected data subjects
+ * @returns 'critical' | 'high' | 'medium' | 'low'
+ */
+function calculateSeverity(
+  category: string,
+  estimatedAffected?: number,
+): 'critical' | 'high' | 'medium' | 'low' {
+  const highRiskCategories = [
+    'unauthorized_access',
+    'ransomware',
+    'data_exfiltration',
+    'identity_theft',
+  ];
+
+  if (highRiskCategories.includes(category)) {
+    if ((estimatedAffected ?? 0) > 1000) return 'critical';
+    return 'high';
+  }
+
+  if ((estimatedAffected ?? 0) > 500) return 'high';
+  if ((estimatedAffected ?? 0) > 50) return 'medium';
+  return 'low';
+}
+
+// ---------------------------------------------------------------------------
+// GET /api/breach?status=ongoing
+// ---------------------------------------------------------------------------
+
+/**
+ * List all breach reports, optionally filtered by status.
+ *
+ * Supports the DPO dashboard view. Returns reports ordered by reportedAt
+ * descending so the most recent (and likely most urgent) items appear first.
+ * Combine with the ?status=ongoing filter to see active incidents.
+ *
+ * Query params:
+ *   status (optional) — ongoing | investigating | resolved | closed
+ *
+ * Returns 200 with an array of BreachReport rows.
+ */
+export async function GET(req: NextRequest) {
+  const status = req.nextUrl.searchParams.get('status');
+
+  const reports = await prisma.breachReport.findMany({
+    where: status ? { status } : undefined,
+    orderBy: { reportedAt: 'desc' },
+  });
+
+  return NextResponse.json(reports);
+}
+
+// ---------------------------------------------------------------------------
+// POST /api/breach
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new data breach report.
+ *
+ * The NDPA Section 40 72-hour notification window begins from the moment a
+ * breach is discovered. This endpoint captures the initial report and
+ * auto-calculates an initial severity so the DPO can prioritise accordingly.
+ *
+ * Body (JSON):
+ *   title                (required) — short descriptive title
+ *   description          (required) — detailed description of the incident
+ *   category             (required) — breach category (e.g. 'unauthorized_access')
+ *   discoveredAt         (required) — ISO timestamp when breach was discovered
+ *   reporterName         (required) — name of the person filing the report
+ *   reporterEmail        (required) — reporter's email address
+ *   affectedSystems      (required) — array of system/service names affected
+ *   dataTypes            (required) — array of data type labels (e.g. ['PII', 'Financial'])
+ *   reporterDepartment   (optional) — reporter's department
+ *   occurredAt           (optional) — ISO timestamp when breach occurred (if known)
+ *   estimatedAffected    (optional) — approximate number of affected data subjects
+ *   initialActions       (optional) — immediate containment actions already taken
+ *
+ * Returns 201 with the newly created BreachReport row including auto-severity.
+ */
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const {
+    title,
+    description,
+    category,
+    discoveredAt,
+    occurredAt,
+    reporterName,
+    reporterEmail,
+    reporterDepartment,
+    affectedSystems,
+    dataTypes,
+    estimatedAffected,
+    initialActions,
+  } = body;
+
+  if (!title || !description || !category || !discoveredAt || !reporterName || !reporterEmail) {
+    return NextResponse.json(
+      {
+        error:
+          'title, description, category, discoveredAt, reporterName, and reporterEmail are required',
+      },
+      { status: 400 },
+    );
+  }
+
+  if (!Array.isArray(affectedSystems) || !Array.isArray(dataTypes)) {
+    return NextResponse.json(
+      { error: 'affectedSystems and dataTypes must be arrays' },
+      { status: 400 },
+    );
+  }
+
+  // Auto-calculate severity from category and scale of impact.
+  const severity = calculateSeverity(category, estimatedAffected);
+
+  const report = await prisma.breachReport.create({
+    data: {
+      title,
+      description,
+      category,
+      severity,
+      status: 'ongoing',
+      discoveredAt: new Date(discoveredAt),
+      occurredAt: occurredAt ? new Date(occurredAt) : null,
+      reporterName,
+      reporterEmail,
+      reporterDepartment: reporterDepartment ?? null,
+      affectedSystems,
+      dataTypes,
+      estimatedAffected: estimatedAffected ?? null,
+      initialActions: initialActions ?? null,
+    },
+  });
+
+  // Audit log — breach report creation is a high-significance event.
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'breach',
+      action: 'reported',
+      entityId: report.id,
+      entityType: 'BreachReport',
+      changes: { title, category, severity, status: 'ongoing' },
+    },
+  });
+
+  return NextResponse.json(report, { status: 201 });
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Next.js App Router — Compliance Score Route
+ *
+ * Returns an overall NDPA compliance score by reading the current state of
+ * all compliance-related tables. The score can be displayed on a DPO dashboard
+ * to surface gaps and track improvement over time.
+ *
+ * The score is calculated across five pillars (each 0–100):
+ *   - Consent         (NDPA Section 25) — % of subjects with active consent
+ *   - DSR             (NDPA Sections 34–38) — % of requests resolved on time
+ *   - Breach          (NDPA Section 40) — % of incidents with NDPC notified
+ *   - ROPA            (NDPA Section 2 / general accountability) — active records exist
+ *   - Audit trail     (NDPA Section 44) — recent audit activity
+ *
+ * Endpoints
+ * ---------
+ *   GET /api/compliance   — Returns the current compliance score object
+ *
+ * How to use
+ * ----------
+ * Copy this file to `app/api/compliance/route.ts` in your Next.js project.
+ *
+ * @module compliance/route
+ */
+
+import { NextResponse } from 'next/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+// ---------------------------------------------------------------------------
+// Score calculation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate the consent pillar score.
+ * Score = 100 if any active consent records exist; penalised otherwise.
+ */
+async function consentScore(): Promise<number> {
+  const total = await prisma.consentRecord.count({ where: { revokedAt: null } });
+  return total > 0 ? 100 : 0;
+}
+
+/**
+ * Calculate the DSR pillar score.
+ * Score = percentage of all DSR requests that were completed within the 30-day window.
+ * A score of 100 means all completed requests met the statutory deadline.
+ */
+async function dsrScore(): Promise<number> {
+  const total = await prisma.dSRRequest.count();
+  if (total === 0) return 100; // No requests yet — full marks (no violations)
+
+  const onTime = await prisma.dSRRequest.count({
+    where: {
+      status: 'completed',
+      completedAt: { not: null },
+      // completedAt <= dueAt
+    },
+  });
+
+  // Fall back to counting completed vs total when date comparison isn't trivial in Prisma.
+  const completed = await prisma.dSRRequest.count({ where: { status: 'completed' } });
+  const overdue = await prisma.dSRRequest.count({
+    where: {
+      status: { in: ['pending', 'in_progress'] },
+      dueAt: { lt: new Date() },
+    },
+  });
+
+  const violationRate = total > 0 ? overdue / total : 0;
+  return Math.max(0, Math.round((1 - violationRate) * 100));
+}
+
+/**
+ * Calculate the breach pillar score.
+ * Score = percentage of breach reports that have been NDPC-notified.
+ * New breaches (< 72 hours old) are excluded from the penalty calculation.
+ */
+async function breachScore(): Promise<number> {
+  const cutoff = new Date(Date.now() - 72 * 60 * 60 * 1000); // 72 hours ago
+
+  const totalMature = await prisma.breachReport.count({
+    where: { reportedAt: { lt: cutoff } },
+  });
+
+  if (totalMature === 0) return 100; // No mature incidents — full marks
+
+  const notified = await prisma.breachReport.count({
+    where: {
+      reportedAt: { lt: cutoff },
+      ndpcNotificationSent: true,
+    },
+  });
+
+  return Math.round((notified / totalMature) * 100);
+}
+
+/**
+ * Calculate the ROPA pillar score.
+ * Score = 100 if at least one active processing record exists; 0 otherwise.
+ * NDPA accountability principle requires controllers to maintain a ROPA.
+ */
+async function ropaScore(): Promise<number> {
+  const activeRecords = await prisma.processingRecord.count({ where: { status: 'active' } });
+  return activeRecords > 0 ? 100 : 0;
+}
+
+/**
+ * Calculate the audit trail pillar score.
+ * Score = 100 if there has been audit activity in the last 30 days; 0 otherwise.
+ */
+async function auditScore(): Promise<number> {
+  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+  const recentLogs = await prisma.complianceAuditLog.count({
+    where: { createdAt: { gte: thirtyDaysAgo } },
+  });
+  return recentLogs > 0 ? 100 : 0;
+}
+
+// ---------------------------------------------------------------------------
+// GET /api/compliance
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the overall NDPA compliance score and per-pillar breakdown.
+ *
+ * The overall score is the arithmetic mean of all five pillar scores.
+ * Scores are integers from 0–100, where 100 = fully compliant.
+ *
+ * Returns 200 with:
+ * {
+ *   overall: number,           — aggregate score (0–100)
+ *   pillars: {
+ *     consent: number,
+ *     dsr: number,
+ *     breach: number,
+ *     ropa: number,
+ *     audit: number,
+ *   },
+ *   calculatedAt: string,      — ISO timestamp
+ * }
+ */
+export async function GET() {
+  const [consent, dsr, breach, ropa, audit] = await Promise.all([
+    consentScore(),
+    dsrScore(),
+    breachScore(),
+    ropaScore(),
+    auditScore(),
+  ]);
+
+  const pillars = { consent, dsr, breach, ropa, audit };
+  const overall = Math.round(
+    Object.values(pillars).reduce((sum, v) => sum + v, 0) / Object.keys(pillars).length,
+  );
+
+  return NextResponse.json({
+    overall,
+    pillars,
+    calculatedAt: new Date().toISOString(),
+  });
+}

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

@@ -0,0 +1,161 @@
+/**
+ * Next.js App Router — Consent API Route
+ *
+ * Handles reading, writing, and revoking data subject consent records as
+ * required by NDPA Section 25 (lawful basis) and Section 26 (consent withdrawal).
+ *
+ * Endpoints
+ * ---------
+ *   GET    /api/consent?subjectId=xxx   — Load the active consent record
+ *   POST   /api/consent                 — Save new consent (revokes previous)
+ *   DELETE /api/consent?subjectId=xxx   — Revoke all active consent
+ *
+ * How to use
+ * ----------
+ * Copy this file to `app/api/consent/route.ts` in your Next.js project.
+ * Ensure the `ndpr_consent_records` table exists (run the ndpr-recipes migration).
+ *
+ * @module consent/route
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+// ---------------------------------------------------------------------------
+// GET /api/consent?subjectId=xxx
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the most recent active (non-revoked) consent record for a data subject.
+ *
+ * NDPA Section 25 requires that data controllers retain evidence of consent —
+ * this endpoint lets your front-end verify whether a subject has already
+ * consented so you can skip the consent banner on return visits.
+ *
+ * Query params:
+ *   subjectId (required) — stable identifier for the data subject
+ *
+ * Returns 200 with the ConsentRecord, or 200 with `null` if none exists.
+ */
+export async function GET(req: NextRequest) {
+  const subjectId = req.nextUrl.searchParams.get('subjectId');
+
+  if (!subjectId) {
+    return NextResponse.json({ error: 'subjectId required' }, { status: 400 });
+  }
+
+  const record = await prisma.consentRecord.findFirst({
+    where: { subjectId, revokedAt: null },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return NextResponse.json(record);
+}
+
+// ---------------------------------------------------------------------------
+// POST /api/consent
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist a new consent decision for a data subject.
+ *
+ * The route follows the immutable-audit pattern mandated by NDPA Section 25:
+ * any previously active record is soft-revoked before the new one is inserted,
+ * so the full consent history is preserved for accountability purposes.
+ *
+ * Body (JSON):
+ *   subjectId   (required) — stable subject identifier
+ *   consents    (required) — map of consent category → boolean
+ *   version     (required) — consent policy version string
+ *   method      (optional) — how consent was captured (default: 'api')
+ *   lawfulBasis (optional) — NDPA lawful basis, e.g. 'consent', 'legitimate_interest'
+ *
+ * Returns 201 with the newly created ConsentRecord.
+ */
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const { subjectId, consents, version, method, lawfulBasis } = body;
+
+  if (!subjectId || !consents || !version) {
+    return NextResponse.json(
+      { error: 'subjectId, consents, and version are required' },
+      { status: 400 },
+    );
+  }
+
+  // Revoke any previously active consent records so there is at most one
+  // active record per subject at all times (immutable-audit pattern).
+  await prisma.consentRecord.updateMany({
+    where: { subjectId, revokedAt: null },
+    data: { revokedAt: new Date() },
+  });
+
+  // Insert the new consent record, capturing request metadata for evidence.
+  const record = await prisma.consentRecord.create({
+    data: {
+      subjectId,
+      consents,
+      version,
+      method: method ?? 'api',
+      lawfulBasis: lawfulBasis ?? null,
+      ipAddress: req.headers.get('x-forwarded-for'),
+      userAgent: req.headers.get('user-agent'),
+    },
+  });
+
+  // Write an audit log entry for accountability (NDPA Section 44).
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'consent',
+      action: 'created',
+      entityId: record.id,
+      entityType: 'ConsentRecord',
+      changes: { subjectId, version, consents },
+    },
+  });
+
+  return NextResponse.json(record, { status: 201 });
+}
+
+// ---------------------------------------------------------------------------
+// DELETE /api/consent?subjectId=xxx
+// ---------------------------------------------------------------------------
+
+/**
+ * Revoke all active consent records for a data subject.
+ *
+ * NDPA Section 26 grants data subjects the right to withdraw consent at any
+ * time. This endpoint soft-revokes records rather than deleting them so the
+ * audit trail remains intact for regulatory inspection.
+ *
+ * Query params:
+ *   subjectId (required) — stable identifier for the data subject
+ *
+ * Returns 200 `{ success: true }` when complete.
+ */
+export async function DELETE(req: NextRequest) {
+  const subjectId = req.nextUrl.searchParams.get('subjectId');
+
+  if (!subjectId) {
+    return NextResponse.json({ error: 'subjectId required' }, { status: 400 });
+  }
+
+  await prisma.consentRecord.updateMany({
+    where: { subjectId, revokedAt: null },
+    data: { revokedAt: new Date() },
+  });
+
+  // Write an audit log entry for the revocation.
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'consent',
+      action: 'revoked',
+      entityId: subjectId,
+      entityType: 'ConsentRecord',
+    },
+  });
+
+  return NextResponse.json({ success: true });
+}

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

@@ -0,0 +1,115 @@
+/**
+ * Next.js App Router — DSR Single-Request Route
+ *
+ * Handles reading and updating individual Data Subject Rights requests.
+ * Used by the DPO/admin interface to view request details and move requests
+ * through the processing workflow as required by NDPA Sections 34–38.
+ *
+ * Endpoints
+ * ---------
+ *   GET   /api/dsr/[id]   — Fetch a single DSR request by ID
+ *   PATCH /api/dsr/[id]   — Update request status, assignee, or internal notes
+ *
+ * How to use
+ * ----------
+ * Copy this file to `app/api/dsr/[id]/route.ts` in your Next.js project.
+ *
+ * @module dsr/[id]/route
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+/** Next.js App Router route context — contains dynamic segment params */
+interface RouteContext {
+  params: { id: string };
+}
+
+// ---------------------------------------------------------------------------
+// GET /api/dsr/[id]
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a single DSR request by its ID.
+ *
+ * Used by the admin detail view to display full request information including
+ * the submission timestamp, due date, and any internal notes added by the DPO.
+ *
+ * Path params:
+ *   id (required) — the DSRRequest record ID
+ *
+ * Returns 200 with the DSRRequest row, or 404 if not found.
+ */
+export async function GET(_req: NextRequest, { params }: RouteContext) {
+  const { id } = params;
+
+  const request = await prisma.dSRRequest.findUnique({ where: { id } });
+
+  if (!request) {
+    return NextResponse.json({ error: 'DSR request not found' }, { status: 404 });
+  }
+
+  return NextResponse.json(request);
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /api/dsr/[id]
+// ---------------------------------------------------------------------------
+
+/**
+ * Update a DSR request's status, assignee, or internal notes.
+ *
+ * This route is called by DPO tooling to progress a request through the
+ * statutory workflow: pending → in_progress → completed (or rejected).
+ * Status transitions are timestamped so the 30-day SLA can be tracked.
+ *
+ * Body (JSON, all fields optional):
+ *   status        — pending | in_progress | completed | rejected
+ *   assignedTo    — name/ID of the staff member handling the request
+ *   internalNotes — free-text notes visible only to internal staff
+ *
+ * Returns 200 with the updated DSRRequest row.
+ */
+export async function PATCH(req: NextRequest, { params }: RouteContext) {
+  const { id } = params;
+  const body = await req.json();
+  const { status, assignedTo, internalNotes } = body;
+
+  // Build the update payload — only include fields the caller supplied.
+  const data: Record<string, unknown> = {};
+
+  if (status !== undefined) {
+    data.status = status;
+
+    // Stamp workflow timestamps when moving to acknowledged or completed states.
+    if (status === 'in_progress') data.acknowledgedAt = new Date();
+    if (status === 'completed') data.completedAt = new Date();
+  }
+
+  if (assignedTo !== undefined) data.assignedTo = assignedTo;
+  if (internalNotes !== undefined) data.internalNotes = internalNotes;
+
+  if (Object.keys(data).length === 0) {
+    return NextResponse.json(
+      { error: 'At least one of status, assignedTo, or internalNotes must be provided' },
+      { status: 400 },
+    );
+  }
+
+  const updated = await prisma.dSRRequest.update({ where: { id }, data });
+
+  // Audit log for every status change (NDPA Section 44 accountability).
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'dsr',
+      action: 'updated',
+      entityId: id,
+      entityType: 'DSRRequest',
+      changes: data as any,
+    },
+  });
+
+  return NextResponse.json(updated);
+}