@tantainnovative/ndpr-recipes 0.1.0

package/src/drizzle/schema.ts

@@ -0,0 +1,484 @@
+/**
+ * Drizzle ORM schema for NDPA compliance tables.
+ *
+ * This mirrors the Prisma schema in `prisma/schema.prisma` using Drizzle's
+ * `pgTable` API. Copy this file into your project and use it with your Drizzle
+ * database instance. It defines all five compliance tables required for
+ * full NDPA coverage:
+ *
+ *   - ndpr_consent_records      — Immutable consent audit trail (NDPA §25–26)
+ *   - ndpr_dsr_requests         — Data subject rights requests (NDPA Part IV)
+ *   - ndpr_breach_reports       — Breach incident records (NDPA §40)
+ *   - ndpr_processing_records   — Record of Processing Activities / ROPA
+ *   - ndpr_audit_log            — General compliance audit log
+ *
+ * Prerequisites
+ * -------------
+ * - `drizzle-orm` must be installed in your project.
+ * - `@paralleldrive/cuid2` must be installed (`pnpm add @paralleldrive/cuid2`).
+ * - Run `drizzle-kit push` or generate migrations to apply the schema.
+ *
+ * @module drizzle/schema
+ */
+
+import {
+  pgTable,
+  text,
+  timestamp,
+  json,
+  boolean,
+  integer,
+  index,
+} from 'drizzle-orm/pg-core';
+import { createId } from '@paralleldrive/cuid2';
+
+// ---------------------------------------------------------------------------
+// ndpr_consent_records
+// ---------------------------------------------------------------------------
+
+/**
+ * Immutable consent audit trail.
+ *
+ * Records are NEVER deleted. Revocation sets `revokedAt` on the existing row.
+ * At most one row per `subjectId` should have `revokedAt = NULL` at any time —
+ * this invariant is maintained by the drizzleConsentAdapter.
+ *
+ * NDPA reference: Sections 25–26 (consent and consent withdrawal)
+ */
+export const consentRecords = pgTable(
+  'ndpr_consent_records',
+  {
+    /** CUID2 primary key — collision-resistant, URL-safe, sortable */
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => createId()),
+
+    /**
+     * Stable identifier for the data subject.
+     * Use your application's user ID, session ID, or hashed email address.
+     * Never store raw PII here if you can avoid it — a pseudonymous ID is preferred.
+     */
+    subjectId: text('subject_id').notNull(),
+
+    /**
+     * Map of consent category → boolean.
+     * Stored as JSON so the schema does not need to change when new
+     * consent categories are added to the toolkit.
+     *
+     * Example: { "analytics": true, "marketing": false, "functional": true }
+     */
+    consents: json('consents').notNull(),
+
+    /** The consent policy version the subject agreed to (e.g. "1.0", "2024-01"). */
+    version: text('version').notNull(),
+
+    /** How consent was captured: "banner", "api", "form", "import", etc. */
+    method: text('method').notNull(),
+
+    /**
+     * NDPA lawful basis for processing.
+     * One of: "consent" | "contract" | "legal_obligation" | "vital_interests" |
+     *         "public_task" | "legitimate_interest"
+     */
+    lawfulBasis: text('lawful_basis'),
+
+    /** IP address at the time of consent — retained as evidence for regulators. */
+    ipAddress: text('ip_address'),
+
+    /** User-agent string at the time of consent — provides device/browser context. */
+    userAgent: text('user_agent'),
+
+    /** Timestamp when the consent record was created. */
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+
+    /**
+     * Timestamp when the consent was revoked.
+     * NULL means the record is currently active. Non-NULL means it has been
+     * superseded or explicitly withdrawn by the data subject.
+     */
+    revokedAt: timestamp('revoked_at'),
+  },
+  (table) => ({
+    /** Index on subjectId to make per-subject queries fast. */
+    subjectIdIdx: index('consent_subject_id_idx').on(table.subjectId),
+  }),
+);
+
+// ---------------------------------------------------------------------------
+// ndpr_dsr_requests
+// ---------------------------------------------------------------------------
+
+/**
+ * Data Subject Rights (DSR) request tracking.
+ *
+ * Records every DSR request submitted by a data subject. Status transitions
+ * follow the NDPA 30-day response window (NDPA Section 29–36):
+ *
+ *   pending → in_progress → completed
+ *                         → rejected
+ *
+ * NDPA reference: Part IV, Sections 29–36
+ */
+export const dsrRequests = pgTable(
+  'ndpr_dsr_requests',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => createId()),
+
+    /**
+     * DSR type — one of:
+     *   "access" | "erasure" | "portability" | "rectification" |
+     *   "restriction" | "objection" | "automated_decision"
+     */
+    type: text('type').notNull(),
+
+    /**
+     * Processing status.
+     * Default is "pending" when a new request comes in.
+     */
+    status: text('status').notNull().default('pending'),
+
+    /** Full name of the data subject making the request. */
+    subjectName: text('subject_name').notNull(),
+
+    /** Email address of the data subject — used to communicate outcomes. */
+    subjectEmail: text('subject_email').notNull(),
+
+    /** Optional phone number for the data subject. */
+    subjectPhone: text('subject_phone'),
+
+    /**
+     * Type of identifier used to locate the subject's data in your systems.
+     * E.g. "email", "account_id", "national_id".
+     */
+    identifierType: text('identifier_type').notNull(),
+
+    /** The actual identifier value corresponding to `identifierType`. */
+    identifierValue: text('identifier_value').notNull(),
+
+    /** Optional free-text description / reason provided by the subject. */
+    description: text('description'),
+
+    /** Internal staff notes — never expose these to the data subject. */
+    internalNotes: text('internal_notes'),
+
+    /** Email of the staff member assigned to handle this request. */
+    assignedTo: text('assigned_to'),
+
+    /** When the request was submitted. */
+    submittedAt: timestamp('submitted_at').defaultNow().notNull(),
+
+    /** When the request was acknowledged to the subject. */
+    acknowledgedAt: timestamp('acknowledged_at'),
+
+    /** When the request was fully completed. */
+    completedAt: timestamp('completed_at'),
+
+    /**
+     * NDPA mandates a 30-day response window from submission.
+     * This should be set to `submittedAt + 30 days` on creation.
+     */
+    dueAt: timestamp('due_at').notNull(),
+  },
+  (table) => ({
+    statusIdx: index('dsr_status_idx').on(table.status),
+    subjectEmailIdx: index('dsr_subject_email_idx').on(table.subjectEmail),
+  }),
+);
+
+// ---------------------------------------------------------------------------
+// ndpr_breach_reports
+// ---------------------------------------------------------------------------
+
+/**
+ * Personal data breach incident reports.
+ *
+ * Under NDPA Section 40, data controllers must notify the NDPC within 72 hours
+ * of becoming aware of a breach. This table tracks every breach incident and
+ * its notification status.
+ *
+ * Records are never deleted — status transitions from "ongoing" to "resolved"
+ * once the incident is closed.
+ *
+ * NDPA reference: Section 40 (breach notification to NDPC)
+ */
+export const breachReports = pgTable(
+  'ndpr_breach_reports',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => createId()),
+
+    /** Short title describing the breach (e.g. "Customer database exposed"). */
+    title: text('title').notNull(),
+
+    /** Detailed description of what happened, how, and what data was affected. */
+    description: text('description').notNull(),
+
+    /**
+     * Breach category — classifies the type of incident:
+     *   "confidentiality" | "integrity" | "availability" | "combined"
+     */
+    category: text('category').notNull(),
+
+    /**
+     * Risk severity level.
+     * One of: "low" | "medium" | "high" | "critical"
+     */
+    severity: text('severity').notNull(),
+
+    /**
+     * Current status of the incident.
+     * One of: "ongoing" | "contained" | "resolved"
+     */
+    status: text('status').notNull().default('ongoing'),
+
+    /** When the breach was first discovered by your organisation. */
+    discoveredAt: timestamp('discovered_at').notNull(),
+
+    /** When the breach actually occurred (may differ from discoveredAt). */
+    occurredAt: timestamp('occurred_at'),
+
+    /** When the breach was formally logged in this system. */
+    reportedAt: timestamp('reported_at').defaultNow().notNull(),
+
+    /**
+     * When the NDPC was notified.
+     * NULL means notification has not yet been sent.
+     * The 72-hour window starts from `discoveredAt`.
+     */
+    ndpcNotifiedAt: timestamp('ndpc_notified_at'),
+
+    /** Full name of the person who reported the breach internally. */
+    reporterName: text('reporter_name').notNull(),
+
+    /** Email address of the breach reporter. */
+    reporterEmail: text('reporter_email').notNull(),
+
+    /** Department or business unit of the reporter. */
+    reporterDepartment: text('reporter_department'),
+
+    /**
+     * List of systems or services that were affected.
+     * Stored as a JSON array of strings.
+     * Example: ["user-auth-service", "payments-db"]
+     */
+    affectedSystems: json('affected_systems').notNull(),
+
+    /**
+     * Categories of personal data involved in the breach.
+     * Stored as a JSON array of strings.
+     * Example: ["email", "national_id", "financial_data"]
+     */
+    dataTypes: json('data_types').notNull(),
+
+    /** Estimated number of data subjects affected. */
+    estimatedAffected: integer('estimated_affected'),
+
+    /** Description of any immediate containment actions taken. */
+    initialActions: text('initial_actions'),
+
+    /**
+     * Whether the mandatory NDPC notification has been sent.
+     * Use `ndpcNotifiedAt` for the exact timestamp.
+     */
+    ndpcNotificationSent: boolean('ndpc_notification_sent').notNull().default(false),
+  },
+  (table) => ({
+    statusIdx: index('breach_status_idx').on(table.status),
+    severityIdx: index('breach_severity_idx').on(table.severity),
+  }),
+);
+
+// ---------------------------------------------------------------------------
+// ndpr_processing_records
+// ---------------------------------------------------------------------------
+
+/**
+ * Record of Processing Activities (ROPA).
+ *
+ * Data controllers are required under the NDPA accountability principle to
+ * maintain a register of all personal data processing activities. Each row
+ * represents one distinct processing activity (e.g. "Email marketing",
+ * "HR payroll processing", "Website analytics").
+ *
+ * Records are never deleted — inactive activities are archived by setting
+ * `status = 'archived'`.
+ *
+ * NDPA reference: Accountability principle; Schedule 1, Part 1
+ */
+export const processingRecords = pgTable(
+  'ndpr_processing_records',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => createId()),
+
+    /** The primary purpose of this processing activity. */
+    purpose: text('purpose').notNull(),
+
+    /**
+     * NDPA lawful basis for this processing activity.
+     * One of: "consent" | "contract" | "legal_obligation" | "vital_interests" |
+     *         "public_task" | "legitimate_interest"
+     */
+    lawfulBasis: text('lawful_basis').notNull(),
+
+    /**
+     * Categories of personal data processed.
+     * Stored as a JSON array of strings.
+     * Example: ["name", "email", "purchase_history"]
+     */
+    dataCategories: json('data_categories').notNull(),
+
+    /**
+     * Categories of data subjects whose data is processed.
+     * Stored as a JSON array of strings.
+     * Example: ["customers", "employees", "website_visitors"]
+     */
+    dataSubjects: json('data_subjects').notNull(),
+
+    /**
+     * Third parties to whom data is disclosed.
+     * Stored as a JSON array of strings.
+     * Example: ["Mailchimp", "Stripe", "Google Analytics"]
+     */
+    recipients: json('recipients').notNull(),
+
+    /**
+     * How long data is retained for this activity.
+     * Use a human-readable string: "2 years", "Until account deletion", etc.
+     */
+    retentionPeriod: text('retention_period').notNull(),
+
+    /**
+     * Technical and organisational security measures in place.
+     * Stored as a JSON array of strings.
+     * Example: ["encryption_at_rest", "access_controls", "audit_logging"]
+     */
+    securityMeasures: json('security_measures').notNull(),
+
+    /**
+     * Countries to which data is transferred outside Nigeria.
+     * Stored as a JSON array of country codes/names, or null if no transfers.
+     */
+    transferCountries: json('transfer_countries'),
+
+    /**
+     * Legal mechanism used for the cross-border transfer.
+     * E.g. "adequacy_decision", "standard_contractual_clauses", "consent".
+     */
+    transferMechanism: text('transfer_mechanism'),
+
+    /**
+     * Whether a Data Protection Impact Assessment (DPIA) was conducted.
+     * Required for high-risk processing activities.
+     */
+    dpiaConducted: boolean('dpia_conducted').notNull().default(false),
+
+    /**
+     * Current status of this processing activity.
+     * One of: "active" | "archived"
+     */
+    status: text('status').notNull().default('active'),
+
+    /** When this processing record was first created. */
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+
+    /** When this processing record was last updated. */
+    updatedAt: timestamp('updated_at').defaultNow().notNull(),
+  },
+);
+
+// ---------------------------------------------------------------------------
+// ndpr_audit_log
+// ---------------------------------------------------------------------------
+
+/**
+ * General compliance audit log.
+ *
+ * Records every significant compliance action across all modules. The audit
+ * log is append-only — rows are never updated or deleted. It provides an
+ * authoritative trail for regulatory inspection under the NDPA accountability
+ * principle.
+ *
+ * NDPA reference: Section 44 (accountability); Schedule 1, Part 1
+ */
+export const auditLog = pgTable(
+  'ndpr_audit_log',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => createId()),
+
+    /**
+     * Which compliance module generated this entry.
+     * One of: "consent" | "dsr" | "breach" | "ropa" | "system"
+     */
+    module: text('module').notNull(),
+
+    /**
+     * The action that occurred.
+     * E.g. "created", "updated", "revoked", "deleted", "notified"
+     */
+    action: text('action').notNull(),
+
+    /** ID of the entity that was acted upon. */
+    entityId: text('entity_id').notNull(),
+
+    /**
+     * Type/model of the entity.
+     * E.g. "ConsentRecord", "DSRRequest", "BreachReport"
+     */
+    entityType: text('entity_type').notNull(),
+
+    /**
+     * Snapshot of what changed.
+     * Stored as JSON. The exact shape depends on the module and action.
+     */
+    changes: json('changes'),
+
+    /**
+     * Who performed the action.
+     * May be a user ID, email address, or system identifier.
+     * NULL indicates an automated/system action.
+     */
+    performedBy: text('performed_by'),
+
+    /** Exact timestamp when the audit event occurred. */
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+  },
+  (table) => ({
+    moduleEntityIdx: index('audit_module_entity_idx').on(table.module, table.entityId),
+  }),
+);
+
+// ---------------------------------------------------------------------------
+// Type exports — infer table row types for use throughout your application
+// ---------------------------------------------------------------------------
+
+/** Row type for ndpr_consent_records */
+export type ConsentRecord = typeof consentRecords.$inferSelect;
+/** Insert type for ndpr_consent_records */
+export type NewConsentRecord = typeof consentRecords.$inferInsert;
+
+/** Row type for ndpr_dsr_requests */
+export type DSRRequest = typeof dsrRequests.$inferSelect;
+/** Insert type for ndpr_dsr_requests */
+export type NewDSRRequest = typeof dsrRequests.$inferInsert;
+
+/** Row type for ndpr_breach_reports */
+export type BreachReport = typeof breachReports.$inferSelect;
+/** Insert type for ndpr_breach_reports */
+export type NewBreachReport = typeof breachReports.$inferInsert;
+
+/** Row type for ndpr_processing_records */
+export type ProcessingRecord = typeof processingRecords.$inferSelect;
+/** Insert type for ndpr_processing_records */
+export type NewProcessingRecord = typeof processingRecords.$inferInsert;
+
+/** Row type for ndpr_audit_log */
+export type AuditLogEntry = typeof auditLog.$inferSelect;
+/** Insert type for ndpr_audit_log */
+export type NewAuditLogEntry = typeof auditLog.$inferInsert;

package/src/express/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Express — NDPR Router Factory
+ *
+ * Assembles all NDPA compliance route modules into a single Express Router
+ * that can be mounted at any path in your application with a single call.
+ *
+ * This entry point is the recommended way to add the full compliance API to
+ * an existing Express or NestJS (with Express adapter) application.
+ *
+ * Mounted routes
+ * --------------
+ *   /consent    — Consent management (NDPA Section 25, 26)
+ *   /dsr        — Data Subject Rights requests (NDPA Sections 34–38)
+ *   /breach     — Breach notification workflow (NDPA Section 40)
+ *   /compliance — Compliance score dashboard
+ *   /ropa       — Record of Processing Activities (NDPA accountability principle)
+ *
+ * How to use
+ * ----------
+ * Copy this file and the `routes/` + `middleware/` directories into your project,
+ * then mount the router in your Express app:
+ *
+ *   import express from 'express';
+ *   import cookieParser from 'cookie-parser';
+ *   import { createNDPRRouter } from './ndpr/express';
+ *
+ *   const app = express();
+ *   app.use(express.json());
+ *   app.use(cookieParser());   // required for consent cookie fallback
+ *   app.use('/api/ndpr', createNDPRRouter());
+ *
+ * The full compliance API is then available at:
+ *   GET  /api/ndpr/consent?subjectId=xxx
+ *   POST /api/ndpr/dsr
+ *   GET  /api/ndpr/compliance
+ *   ... etc.
+ *
+ * Protecting routes with consent middleware
+ * -----------------------------------------
+ *   import { requireConsent } from './ndpr/express/middleware/consent-check';
+ *
+ *   app.post('/email/marketing', requireConsent('marketing'), sendEmailHandler);
+ *
+ * @module express/index
+ */
+
+import { Router } from 'express';
+import { consentRouter } from './routes/consent';
+import { dsrRouter } from './routes/dsr';
+import { breachRouter } from './routes/breach';
+import { complianceRouter } from './routes/compliance';
+import { ropaRouter } from './routes/ropa';
+
+/**
+ * Create and return a fully configured NDPR compliance Express Router.
+ *
+ * All five compliance modules are mounted as sub-routers under their
+ * respective path prefixes. Each module handles its own Prisma queries
+ * and audit logging — no additional wiring is required beyond mounting
+ * this router in your app.
+ *
+ * @returns An Express Router with all NDPR compliance routes mounted.
+ */
+export function createNDPRRouter(): Router {
+  const router = Router();
+
+  router.use('/consent', consentRouter);
+  router.use('/dsr', dsrRouter);
+  router.use('/breach', breachRouter);
+  router.use('/compliance', complianceRouter);
+  router.use('/ropa', ropaRouter);
+
+  return router;
+}
+
+// Re-export middleware and individual routers for granular use.
+export { consentRouter } from './routes/consent';
+export { dsrRouter } from './routes/dsr';
+export { breachRouter } from './routes/breach';
+export { complianceRouter } from './routes/compliance';
+export { ropaRouter } from './routes/ropa';
+export { requireConsent, requireAllConsents } from './middleware/consent-check';

package/src/express/middleware/consent-check.ts

@@ -0,0 +1,133 @@
+/**
+ * Express — Consent Gate Middleware
+ *
+ * Provides a middleware factory that blocks requests from data subjects who
+ * have not granted the required consent type, implementing the consent
+ * enforcement required by NDPA Section 25.
+ *
+ * NDPA Section 25 requires that data processing based on consent only occurs
+ * when the subject has freely given specific, informed, and unambiguous consent.
+ * This middleware enforces that requirement at the HTTP layer so individual
+ * route handlers don't need to repeat the check.
+ *
+ * How to use
+ * ----------
+ * Apply the middleware to any Express route or router that requires consent:
+ *
+ *   import { requireConsent } from './middleware/consent-check';
+ *
+ *   // Protect a single route
+ *   app.post('/email/send', requireConsent('marketing'), sendEmailHandler);
+ *
+ *   // Protect an entire router
+ *   analyticsRouter.use(requireConsent('analytics'));
+ *
+ * Subject identification
+ * ----------------------
+ * The middleware 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 the consent banner on the client)
+ *
+ * @module express/middleware/consent-check
+ */
+
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+/**
+ * Express middleware factory that enforces a specific consent type.
+ *
+ * Returns a standard Express middleware function that:
+ *   1. Resolves the data subject's identifier from the request.
+ *   2. Loads the most recent active consent record for that subject.
+ *   3. Verifies that the required consent type is set to `true`.
+ *   4. Calls `next()` if consent is present, or responds with 403 if not.
+ *
+ * @param consentType - The consent category key to check (e.g. 'marketing', 'analytics')
+ * @returns Express middleware function
+ *
+ * @example
+ *   router.post('/newsletter/subscribe', requireConsent('marketing'), handler);
+ */
+export function requireConsent(consentType: string) {
+  return async (req: any, res: any, next: any): Promise<void> => {
+    // Resolve subject identifier from header (preferred) or cookie fallback.
+    const subjectId: string | undefined =
+      req.headers['x-subject-id'] || req.cookies?.subject_id;
+
+    if (!subjectId) {
+      res.status(403).json({ error: 'Consent verification required' });
+      return;
+    }
+
+    // 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) {
+      res.status(403).json({ error: 'No consent on record' });
+      return;
+    }
+
+    // Verify that the specific consent category has been granted.
+    const consents = record.consents as Record<string, boolean>;
+
+    if (!consents[consentType]) {
+      res.status(403).json({ error: `Consent for "${consentType}" not granted` });
+      return;
+    }
+
+    // Consent verified — attach consent record to request for downstream use.
+    req.consentRecord = record;
+    next();
+  };
+}
+
+/**
+ * Convenience middleware that requires ALL of the listed consent types.
+ *
+ * If any one of the required consent types is missing, the request is blocked.
+ * Useful when a single endpoint processes data under multiple consent categories.
+ *
+ * @param consentTypes - Array of consent category keys, all of which must be granted
+ *
+ * @example
+ *   router.post('/profile/sync', requireAllConsents(['analytics', 'personalisation']), handler);
+ */
+export function requireAllConsents(consentTypes: string[]) {
+  return async (req: any, res: any, next: any): Promise<void> => {
+    const subjectId: string | undefined =
+      req.headers['x-subject-id'] || req.cookies?.subject_id;
+
+    if (!subjectId) {
+      res.status(403).json({ error: 'Consent verification required' });
+      return;
+    }
+
+    const record = await prisma.consentRecord.findFirst({
+      where: { subjectId, revokedAt: null },
+      orderBy: { createdAt: 'desc' },
+    });
+
+    if (!record) {
+      res.status(403).json({ error: 'No consent on record' });
+      return;
+    }
+
+    const consents = record.consents as Record<string, boolean>;
+    const missing = consentTypes.filter((type) => !consents[type]);
+
+    if (missing.length > 0) {
+      res.status(403).json({
+        error: `Consent not granted for: ${missing.join(', ')}`,
+      });
+      return;
+    }
+
+    req.consentRecord = record;
+    next();
+  };
+}