@tantainnovative/ndpr-recipes 0.1.0

package/src/express/routes/dsr.ts

@@ -0,0 +1,203 @@
+/**
+ * Express — DSR (Data Subject Rights) Router
+ *
+ * Handles listing, creating, retrieving, and updating Data Subject Rights
+ * requests as required by NDPA Sections 34–38 (rights to access, rectification,
+ * erasure, portability, and objection). Requests must be fulfilled within
+ * 30 days of submission under the Act.
+ *
+ * Routes
+ * ------
+ *   GET    /dsr              — List DSR requests (optional ?status= filter)
+ *   POST   /dsr              — Submit a new DSR request
+ *   GET    /dsr/:id          — Fetch a single DSR request by ID
+ *   PATCH  /dsr/:id          — Update request status, assignee, or internal notes
+ *
+ * How to use
+ * ----------
+ * This router is mounted automatically by `createNDPRRouter()` in `../index.ts`.
+ *
+ * @module express/routes/dsr
+ */
+
+import { Router } from 'express';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+export const dsrRouter = Router();
+
+// ---------------------------------------------------------------------------
+// GET /dsr?status=pending
+// ---------------------------------------------------------------------------
+
+/**
+ * List all DSR requests, optionally filtered by status.
+ *
+ * Returns requests ordered newest-first so overdue items are easier to spot.
+ * Filter by status=pending to see requests awaiting acknowledgement.
+ *
+ * Query params:
+ *   status (optional) — pending | in_progress | completed | rejected
+ *
+ * Returns 200 with an array of DSRRequest rows.
+ */
+dsrRouter.get('/', async (req, res) => {
+  const { status } = req.query;
+
+  const requests = await prisma.dSRRequest.findMany({
+    where: typeof status === 'string' ? { status } : undefined,
+    orderBy: { submittedAt: 'desc' },
+  });
+
+  return res.json(requests);
+});
+
+// ---------------------------------------------------------------------------
+// POST /dsr
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit a new Data Subject Rights request.
+ *
+ * Creates a new request with status 'pending' and automatically sets the
+ * statutory 30-day deadline (dueAt) as required by NDPA Section 34.
+ * An audit log entry is created for accountability purposes.
+ *
+ * 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.
+ */
+dsrRouter.post('/', async (req, res) => {
+  const {
+    type,
+    subjectName,
+    subjectEmail,
+    subjectPhone,
+    identifierType,
+    identifierValue,
+    description,
+  } = req.body;
+
+  if (!type || !subjectName || !subjectEmail || !identifierType || !identifierValue) {
+    return res.status(400).json({
+      error:
+        'type, subjectName, subjectEmail, identifierType, and identifierValue are required',
+    });
+  }
+
+  // NDPA mandates a 30-day response window from 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,
+    },
+  });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'dsr',
+      action: 'submitted',
+      entityId: request.id,
+      entityType: 'DSRRequest',
+      changes: { type, subjectEmail, status: 'pending' },
+    },
+  });
+
+  return res.status(201).json(request);
+});
+
+// ---------------------------------------------------------------------------
+// GET /dsr/:id
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a single DSR request by its ID.
+ *
+ * Returns full request details including the due date, submission timestamp,
+ * assignee, 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.
+ */
+dsrRouter.get('/:id', async (req, res) => {
+  const { id } = req.params;
+
+  const request = await prisma.dSRRequest.findUnique({ where: { id } });
+
+  if (!request) {
+    return res.status(404).json({ error: 'DSR request not found' });
+  }
+
+  return res.json(request);
+});
+
+// ---------------------------------------------------------------------------
+// PATCH /dsr/:id
+// ---------------------------------------------------------------------------
+
+/**
+ * Update a DSR request's status, assignee, or internal notes.
+ *
+ * Used by DPO tooling to progress requests through the statutory workflow:
+ * pending → in_progress → completed (or rejected). Status transitions are
+ * timestamped so the 30-day SLA can be tracked per NDPA Section 34.
+ *
+ * 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.
+ */
+dsrRouter.patch('/:id', async (req, res) => {
+  const { id } = req.params;
+  const { status, assignedTo, internalNotes } = req.body;
+
+  const data: Record<string, unknown> = {};
+  if (status !== undefined) {
+    data.status = status;
+    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 res.status(400).json({
+      error: 'At least one of status, assignedTo, or internalNotes must be provided',
+    });
+  }
+
+  const updated = await prisma.dSRRequest.update({ where: { id }, data });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'dsr',
+      action: 'updated',
+      entityId: id,
+      entityType: 'DSRRequest',
+      changes: data as any,
+    },
+  });
+
+  return res.json(updated);
+});

package/src/express/routes/ropa.ts

@@ -0,0 +1,225 @@
+/**
+ * Express — ROPA (Record of Processing Activities) Router
+ *
+ * Handles listing, creating, updating, and archiving processing activity records.
+ * Under the NDPA accountability principle, data controllers must maintain a
+ * Record of Processing Activities (ROPA). This router provides the full CRUD
+ * surface for managing that record.
+ *
+ * Routes
+ * ------
+ *   GET    /ropa           — List all processing records (optional ?status= filter)
+ *   POST   /ropa           — Create a new processing record
+ *   PATCH  /ropa           — Update a processing record (body must include `id`)
+ *   DELETE /ropa?id=xxx    — Archive a processing record (soft delete)
+ *
+ * How to use
+ * ----------
+ * This router is mounted automatically by `createNDPRRouter()` in `../index.ts`.
+ *
+ * @module express/routes/ropa
+ */
+
+import { Router } from 'express';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+export const ropaRouter = Router();
+
+// ---------------------------------------------------------------------------
+// GET /ropa?status=active
+// ---------------------------------------------------------------------------
+
+/**
+ * List all processing activity records.
+ *
+ * Returns records ordered by creation date ascending so the ROPA reads
+ * chronologically. Filter by status=active to see only current activities;
+ * status=archived to review historical entries retained for audit purposes.
+ *
+ * Query params:
+ *   status (optional) — active | archived
+ *
+ * Returns 200 with an array of ProcessingRecord rows.
+ */
+ropaRouter.get('/', async (req, res) => {
+  const { status } = req.query;
+
+  const records = await prisma.processingRecord.findMany({
+    where: typeof status === 'string' ? { status } : undefined,
+    orderBy: { createdAt: 'asc' },
+  });
+
+  return res.json(records);
+});
+
+// ---------------------------------------------------------------------------
+// POST /ropa
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new processing activity record.
+ *
+ * Each record documents a single processing activity (e.g. "Customer order
+ * processing" or "Marketing email campaigns"). Together, all active records
+ * form the organisation's ROPA 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
+ *   dataSubjects        (required) — array of subject category labels
+ *   recipients          (required) — array of recipient category labels
+ *   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 the transfers
+ *   dpiaConducted       (optional) — whether a DPIA has been performed (default false)
+ *
+ * Returns 201 with the newly created ProcessingRecord row.
+ */
+ropaRouter.post('/', async (req, res) => {
+  const {
+    purpose,
+    lawfulBasis,
+    dataCategories,
+    dataSubjects,
+    recipients,
+    retentionPeriod,
+    securityMeasures,
+    transferCountries,
+    transferMechanism,
+    dpiaConducted,
+  } = req.body;
+
+  if (
+    !purpose ||
+    !lawfulBasis ||
+    !Array.isArray(dataCategories) ||
+    !Array.isArray(dataSubjects) ||
+    !Array.isArray(recipients) ||
+    !retentionPeriod ||
+    !Array.isArray(securityMeasures)
+  ) {
+    return res.status(400).json({
+      error:
+        'purpose, lawfulBasis, dataCategories, dataSubjects, recipients, retentionPeriod, and securityMeasures are required',
+    });
+  }
+
+  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 res.status(201).json(record);
+});
+
+// ---------------------------------------------------------------------------
+// PATCH /ropa
+// ---------------------------------------------------------------------------
+
+/**
+ * Update an existing processing activity record.
+ *
+ * Call this when a processing activity changes — e.g. a new data category
+ * is added, the retention policy is updated, or a DPIA is conducted.
+ * Keeping the ROPA accurate and current is part of the NDPA accountability obligation.
+ *
+ * Body (JSON):
+ *   id   (required) — ID of the ProcessingRecord to update
+ *   ...  (all other POST fields are optional — only include what changed)
+ *
+ * Returns 200 with the updated ProcessingRecord row.
+ */
+ropaRouter.patch('/', async (req, res) => {
+  const { id, ...fields } = req.body;
+
+  if (!id) {
+    return res.status(400).json({ error: 'id is required in the request body' });
+  }
+
+  const existing = await prisma.processingRecord.findUnique({ where: { id } });
+  if (!existing) {
+    return res.status(404).json({ error: 'Processing record not found' });
+  }
+
+  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 res.json(updated);
+});
+
+// ---------------------------------------------------------------------------
+// DELETE /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 at a single point in time.
+ *
+ * Query params:
+ *   id (required) — ID of the ProcessingRecord to archive
+ *
+ * Returns 200 `{ success: true }` when complete.
+ */
+ropaRouter.delete('/', async (req, res) => {
+  const { id } = req.query;
+
+  if (!id || typeof id !== 'string') {
+    return res.status(400).json({ error: 'id query parameter required' });
+  }
+
+  const existing = await prisma.processingRecord.findUnique({ where: { id } });
+  if (!existing) {
+    return res.status(404).json({ error: 'Processing record not found' });
+  }
+
+  await prisma.processingRecord.update({ where: { id }, data: { status: 'archived' } });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'ropa',
+      action: 'archived',
+      entityId: id,
+      entityType: 'ProcessingRecord',
+    },
+  });
+
+  return res.json({ success: true });
+});

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

@@ -0,0 +1,121 @@
+/**
+ * Next.js App Router — Breach Notification Single-Report Route
+ *
+ * Handles reading and updating individual breach reports.
+ * Used by the DPO interface to track an incident through its lifecycle
+ * and record the NDPC notification status as required by NDPA Section 40.
+ *
+ * Endpoints
+ * ---------
+ *   GET   /api/breach/[id]   — Fetch a single breach report by ID
+ *   PATCH /api/breach/[id]   — Update breach status, severity, or add actions taken
+ *
+ * How to use
+ * ----------
+ * Copy this file to `app/api/breach/[id]/route.ts` in your Next.js project.
+ *
+ * @module breach/[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/breach/[id]
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a single breach report by its ID.
+ *
+ * Returns the full report including affected systems, data types, and the
+ * NDPC notification status. Used by the incident detail page and for
+ * generating the formal NDPC breach notification document.
+ *
+ * Path params:
+ *   id (required) — the BreachReport record ID
+ *
+ * Returns 200 with the BreachReport row, or 404 if not found.
+ */
+export async function GET(_req: NextRequest, { params }: RouteContext) {
+  const { id } = params;
+
+  const report = await prisma.breachReport.findUnique({ where: { id } });
+
+  if (!report) {
+    return NextResponse.json({ error: 'Breach report not found' }, { status: 404 });
+  }
+
+  return NextResponse.json(report);
+}
+
+// ---------------------------------------------------------------------------
+// PATCH /api/breach/[id]
+// ---------------------------------------------------------------------------
+
+/**
+ * Update a breach report's status, severity, NDPC notification status, or
+ * containment actions.
+ *
+ * Key workflow transitions tracked here:
+ *   ongoing → investigating     (DPO has begun assessment)
+ *   investigating → resolved    (threat contained, remediation complete)
+ *   resolved → closed           (post-incident review done, NDPC notified)
+ *
+ * The ndpcNotificationSent flag and ndpcNotifiedAt timestamp are set here
+ * once the formal NDPC notification has been dispatched, fulfilling the
+ * 72-hour reporting obligation under NDPA Section 40.
+ *
+ * Body (JSON, all fields optional):
+ *   status                — ongoing | investigating | resolved | closed
+ *   severity              — critical | high | medium | low
+ *   initialActions        — append/replace containment actions text
+ *   ndpcNotificationSent  — boolean — set true once NDPC is formally notified
+ *
+ * Returns 200 with the updated BreachReport row.
+ */
+export async function PATCH(req: NextRequest, { params }: RouteContext) {
+  const { id } = params;
+  const body = await req.json();
+  const { status, severity, initialActions, ndpcNotificationSent } = body;
+
+  const data: Record<string, unknown> = {};
+
+  if (status !== undefined) data.status = status;
+  if (severity !== undefined) data.severity = severity;
+  if (initialActions !== undefined) data.initialActions = initialActions;
+
+  // Stamp the NDPC notification timestamp when the flag is first set to true.
+  if (ndpcNotificationSent === true) {
+    data.ndpcNotificationSent = true;
+    data.ndpcNotifiedAt = new Date();
+  }
+
+  if (Object.keys(data).length === 0) {
+    return NextResponse.json(
+      { error: 'At least one of status, severity, initialActions, or ndpcNotificationSent must be provided' },
+      { status: 400 },
+    );
+  }
+
+  const updated = await prisma.breachReport.update({ where: { id }, data });
+
+  // Audit log — every status change on a breach is significant for compliance.
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'breach',
+      action: 'updated',
+      entityId: id,
+      entityType: 'BreachReport',
+      changes: data as any,
+    },
+  });
+
+  return NextResponse.json(updated);
+}