@tantainnovative/ndpr-recipes 0.1.0

package/src/express/routes/breach.ts

@@ -0,0 +1,259 @@
+/**
+ * Express — Breach Notification Router
+ *
+ * Handles listing, creating, retrieving, and updating 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.
+ *
+ * Routes
+ * ------
+ *   GET   /breach            — List breach reports (optional ?status= filter)
+ *   POST  /breach            — Create a new breach report (auto-calculates severity)
+ *   GET   /breach/:id        — Fetch a single breach report by ID
+ *   PATCH /breach/:id        — Update status, severity, actions, or NDPC notification flag
+ *
+ * How to use
+ * ----------
+ * This router is mounted automatically by `createNDPRRouter()` in `../index.ts`.
+ *
+ * @module express/routes/breach
+ */
+
+import { Router } from 'express';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+export const breachRouter = Router();
+
+// ---------------------------------------------------------------------------
+// Severity auto-calculation helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive an initial severity rating from breach category and scale of impact.
+ * The DPO should review and adjust this before the NDPC notification is sent.
+ */
+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 /breach?status=ongoing
+// ---------------------------------------------------------------------------
+
+/**
+ * List all breach reports, optionally filtered by status.
+ *
+ * Returns reports ordered by reportedAt descending so the most recent
+ * (likely most urgent) incidents appear first. Use ?status=ongoing to view
+ * only active incidents requiring attention or NDPC notification.
+ *
+ * Query params:
+ *   status (optional) — ongoing | investigating | resolved | closed
+ *
+ * Returns 200 with an array of BreachReport rows.
+ */
+breachRouter.get('/', async (req, res) => {
+  const { status } = req.query;
+
+  const reports = await prisma.breachReport.findMany({
+    where: typeof status === 'string' ? { status } : undefined,
+    orderBy: { reportedAt: 'desc' },
+  });
+
+  return res.json(reports);
+});
+
+// ---------------------------------------------------------------------------
+// POST /breach
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new data breach report.
+ *
+ * The 72-hour NDPC notification clock (NDPA Section 40) starts from the
+ * discoveredAt timestamp. Severity is auto-calculated from category and scale
+ * — the DPO should review before submitting the formal NDPC notification.
+ *
+ * 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 reporting person
+ *   reporterEmail        (required) — reporter's email address
+ *   affectedSystems      (required) — array of affected system/service names
+ *   dataTypes            (required) — array of data type labels affected
+ *   reporterDepartment   (optional) — reporter's department
+ *   occurredAt           (optional) — ISO timestamp when breach occurred (if known)
+ *   estimatedAffected    (optional) — approximate number of affected data subjects
+ *   initialActions       (optional) — containment actions already taken
+ *
+ * Returns 201 with the newly created BreachReport row including auto-severity.
+ */
+breachRouter.post('/', async (req, res) => {
+  const {
+    title,
+    description,
+    category,
+    discoveredAt,
+    occurredAt,
+    reporterName,
+    reporterEmail,
+    reporterDepartment,
+    affectedSystems,
+    dataTypes,
+    estimatedAffected,
+    initialActions,
+  } = req.body;
+
+  if (!title || !description || !category || !discoveredAt || !reporterName || !reporterEmail) {
+    return res.status(400).json({
+      error:
+        'title, description, category, discoveredAt, reporterName, and reporterEmail are required',
+    });
+  }
+
+  if (!Array.isArray(affectedSystems) || !Array.isArray(dataTypes)) {
+    return res.status(400).json({
+      error: 'affectedSystems and dataTypes must be arrays',
+    });
+  }
+
+  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,
+    },
+  });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'breach',
+      action: 'reported',
+      entityId: report.id,
+      entityType: 'BreachReport',
+      changes: { title, category, severity, status: 'ongoing' },
+    },
+  });
+
+  return res.status(201).json(report);
+});
+
+// ---------------------------------------------------------------------------
+// GET /breach/:id
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a single breach report by its ID.
+ *
+ * Returns the full report including affected systems, data types, reporter
+ * details, and NDPC notification status. Used by the incident detail view
+ * and for generating the formal NDPC notification document.
+ *
+ * Path params:
+ *   id (required) — the BreachReport record ID
+ *
+ * Returns 200 with the BreachReport row, or 404 if not found.
+ */
+breachRouter.get('/:id', async (req, res) => {
+  const { id } = req.params;
+
+  const report = await prisma.breachReport.findUnique({ where: { id } });
+
+  if (!report) {
+    return res.status(404).json({ error: 'Breach report not found' });
+  }
+
+  return res.json(report);
+});
+
+// ---------------------------------------------------------------------------
+// PATCH /breach/:id
+// ---------------------------------------------------------------------------
+
+/**
+ * Update a breach report's status, severity, actions, or NDPC notification flag.
+ *
+ * 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)
+ *
+ * Setting ndpcNotificationSent=true stamps ndpcNotifiedAt, fulfilling the
+ * 72-hour notification requirement under NDPA Section 40.
+ *
+ * Body (JSON, all fields optional):
+ *   status                — ongoing | investigating | resolved | closed
+ *   severity              — critical | high | medium | low
+ *   initialActions        — containment/remediation actions text
+ *   ndpcNotificationSent  — boolean — set true once NDPC is formally notified
+ *
+ * Returns 200 with the updated BreachReport row.
+ */
+breachRouter.patch('/:id', async (req, res) => {
+  const { id } = req.params;
+  const { status, severity, initialActions, ndpcNotificationSent } = req.body;
+
+  const data: Record<string, unknown> = {};
+  if (status !== undefined) data.status = status;
+  if (severity !== undefined) data.severity = severity;
+  if (initialActions !== undefined) data.initialActions = initialActions;
+  if (ndpcNotificationSent === true) {
+    data.ndpcNotificationSent = true;
+    data.ndpcNotifiedAt = new Date();
+  }
+
+  if (Object.keys(data).length === 0) {
+    return res.status(400).json({
+      error:
+        'At least one of status, severity, initialActions, or ndpcNotificationSent must be provided',
+    });
+  }
+
+  const updated = await prisma.breachReport.update({ where: { id }, data });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'breach',
+      action: 'updated',
+      entityId: id,
+      entityType: 'BreachReport',
+      changes: data as any,
+    },
+  });
+
+  return res.json(updated);
+});

package/src/express/routes/compliance.ts

@@ -0,0 +1,130 @@
+/**
+ * Express — Compliance Score Router
+ *
+ * Returns an overall NDPA compliance score by reading the current state of
+ * all compliance-related tables. Designed for a DPO dashboard to surface
+ * gaps and track compliance posture improvement over time.
+ *
+ * The score is calculated across five pillars (each 0–100):
+ *   - Consent     (NDPA Section 25) — active consent records exist
+ *   - DSR         (NDPA Sections 34–38) — requests processed without overdue violations
+ *   - Breach      (NDPA Section 40) — incidents notified to NDPC within 72 hours
+ *   - ROPA        (NDPA accountability principle) — active processing records exist
+ *   - Audit trail (NDPA Section 44) — recent audit activity in the last 30 days
+ *
+ * Routes
+ * ------
+ *   GET /compliance   — Returns the current compliance score object
+ *
+ * @module express/routes/compliance
+ */
+
+import { Router } from 'express';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+export const complianceRouter = Router();
+
+// ---------------------------------------------------------------------------
+// Score calculation helpers
+// ---------------------------------------------------------------------------
+
+/** Consent pillar: 100 if any active consent records exist; 0 otherwise. */
+async function consentScore(): Promise<number> {
+  const total = await prisma.consentRecord.count({ where: { revokedAt: null } });
+  return total > 0 ? 100 : 0;
+}
+
+/**
+ * DSR pillar: penalises overdue requests.
+ * Score = (1 − overdue/total) × 100, clamped to [0, 100].
+ */
+async function dsrScore(): Promise<number> {
+  const total = await prisma.dSRRequest.count();
+  if (total === 0) return 100;
+
+  const overdue = await prisma.dSRRequest.count({
+    where: {
+      status: { in: ['pending', 'in_progress'] },
+      dueAt: { lt: new Date() },
+    },
+  });
+
+  return Math.max(0, Math.round((1 - overdue / total) * 100));
+}
+
+/**
+ * Breach pillar: percentage of mature incidents (> 72 hours old) with NDPC notified.
+ * New breaches inside the 72-hour window are excluded from the calculation.
+ */
+async function breachScore(): Promise<number> {
+  const cutoff = new Date(Date.now() - 72 * 60 * 60 * 1000);
+  const totalMature = await prisma.breachReport.count({ where: { reportedAt: { lt: cutoff } } });
+  if (totalMature === 0) return 100;
+
+  const notified = await prisma.breachReport.count({
+    where: { reportedAt: { lt: cutoff }, ndpcNotificationSent: true },
+  });
+
+  return Math.round((notified / totalMature) * 100);
+}
+
+/** ROPA pillar: 100 if at least one active processing record exists; 0 otherwise. */
+async function ropaScore(): Promise<number> {
+  const active = await prisma.processingRecord.count({ where: { status: 'active' } });
+  return active > 0 ? 100 : 0;
+}
+
+/** Audit trail pillar: 100 if there has been audit activity in the last 30 days. */
+async function auditScore(): Promise<number> {
+  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+  const recent = await prisma.complianceAuditLog.count({
+    where: { createdAt: { gte: thirtyDaysAgo } },
+  });
+  return recent > 0 ? 100 : 0;
+}
+
+// ---------------------------------------------------------------------------
+// GET /compliance
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the overall NDPA compliance score and per-pillar breakdown.
+ *
+ * The overall score is the arithmetic mean of the five pillar scores.
+ * A score of 100 means all five pillars are fully compliant; lower scores
+ * indicate specific areas that need attention.
+ *
+ * Returns 200 with:
+ * {
+ *   overall: number,      — aggregate score (0–100)
+ *   pillars: {
+ *     consent: number,
+ *     dsr: number,
+ *     breach: number,
+ *     ropa: number,
+ *     audit: number,
+ *   },
+ *   calculatedAt: string, — ISO timestamp
+ * }
+ */
+complianceRouter.get('/', async (_req, res) => {
+  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 res.json({
+    overall,
+    pillars,
+    calculatedAt: new Date().toISOString(),
+  });
+});

package/src/express/routes/consent.ts

@@ -0,0 +1,163 @@
+/**
+ * Express — Consent Router
+ *
+ * GET, POST, and DELETE handlers for data subject consent records as required
+ * by NDPA Section 25 (lawful basis of processing) and Section 26 (right to
+ * withdraw consent). Mirrors the Next.js App Router consent route in logic.
+ *
+ * Routes
+ * ------
+ *   GET    /consent?subjectId=xxx   — Load the active consent record
+ *   POST   /consent                 — Save new consent (revokes previous)
+ *   DELETE /consent?subjectId=xxx   — Revoke all active consent
+ *
+ * How to use
+ * ----------
+ * Mount this router in your Express app (see `../index.ts`):
+ *
+ *   import { createNDPRRouter } from '@tantainnovative/ndpr-recipes/express';
+ *   app.use('/ndpr', createNDPRRouter());
+ *
+ * @module express/routes/consent
+ */
+
+import { Router } from 'express';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+export const consentRouter = Router();
+
+// ---------------------------------------------------------------------------
+// GET /consent?subjectId=xxx
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the most recent active (non-revoked) consent record for a data subject.
+ *
+ * NDPA Section 25 requires evidence of consent to be retained. This endpoint
+ * lets your application verify existing consent before processing personal data.
+ *
+ * Query params:
+ *   subjectId (required) — stable identifier for the data subject
+ *
+ * Returns 200 with the ConsentRecord, or 200 `null` if none exists.
+ */
+consentRouter.get('/', async (req, res) => {
+  const { subjectId } = req.query;
+
+  if (!subjectId || typeof subjectId !== 'string') {
+    return res.status(400).json({ error: 'subjectId required' });
+  }
+
+  const record = await prisma.consentRecord.findFirst({
+    where: { subjectId, revokedAt: null },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return res.json(record);
+});
+
+// ---------------------------------------------------------------------------
+// POST /consent
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist a new consent decision for a data subject.
+ *
+ * Follows the immutable-audit pattern: any active record is soft-revoked
+ * before the new one is inserted, preserving full consent history as required
+ * by the NDPA accountability principle (Section 44).
+ *
+ * Body (JSON):
+ *   subjectId   (required) — stable subject identifier
+ *   consents    (required) — map of consent category → boolean
+ *   version     (required) — consent policy version string
+ *   method      (optional) — capture method (default: 'api')
+ *   lawfulBasis (optional) — e.g. 'consent', 'legitimate_interests'
+ *
+ * Returns 201 with the newly created ConsentRecord.
+ */
+consentRouter.post('/', async (req, res) => {
+  const { subjectId, consents, version, method, lawfulBasis } = req.body;
+
+  if (!subjectId || !consents || !version) {
+    return res
+      .status(400)
+      .json({ error: 'subjectId, consents, and version are required' });
+  }
+
+  // Revoke any previously active consent records (immutable-audit pattern).
+  await prisma.consentRecord.updateMany({
+    where: { subjectId, revokedAt: null },
+    data: { revokedAt: new Date() },
+  });
+
+  // Insert new record, capturing request metadata for compliance evidence.
+  const record = await prisma.consentRecord.create({
+    data: {
+      subjectId,
+      consents,
+      version,
+      method: method ?? 'api',
+      lawfulBasis: lawfulBasis ?? null,
+      ipAddress:
+        (req.headers['x-forwarded-for'] as string)?.split(',')[0].trim() ??
+        req.socket.remoteAddress ??
+        null,
+      userAgent: req.headers['user-agent'] ?? null,
+    },
+  });
+
+  // Audit log for NDPA Section 44 accountability.
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'consent',
+      action: 'created',
+      entityId: record.id,
+      entityType: 'ConsentRecord',
+      changes: { subjectId, version, consents },
+    },
+  });
+
+  return res.status(201).json(record);
+});
+
+// ---------------------------------------------------------------------------
+// DELETE /consent?subjectId=xxx
+// ---------------------------------------------------------------------------
+
+/**
+ * Revoke all active consent records for a data subject.
+ *
+ * NDPA Section 26 grants the right to withdraw consent at any time.
+ * Records are soft-revoked (revokedAt set) rather than deleted to preserve
+ * the audit trail for regulatory inspection.
+ *
+ * Query params:
+ *   subjectId (required) — stable identifier for the data subject
+ *
+ * Returns 200 `{ success: true }` when complete.
+ */
+consentRouter.delete('/', async (req, res) => {
+  const { subjectId } = req.query;
+
+  if (!subjectId || typeof subjectId !== 'string') {
+    return res.status(400).json({ error: 'subjectId required' });
+  }
+
+  await prisma.consentRecord.updateMany({
+    where: { subjectId, revokedAt: null },
+    data: { revokedAt: new Date() },
+  });
+
+  await prisma.complianceAuditLog.create({
+    data: {
+      module: 'consent',
+      action: 'revoked',
+      entityId: subjectId,
+      entityType: 'ConsentRecord',
+    },
+  });
+
+  return res.json({ success: true });
+});