@tantainnovative/create-ndpr 0.1.0 → 0.5.0

package/templates/express-request-context.ts

@@ -0,0 +1,130 @@
+import type { Request } from 'express';
+
+export interface NDPRVerifiedActor {
+  id: string;
+  displayName: string;
+  email: string;
+  department?: string;
+  subjectId?: string;
+  roles: readonly string[];
+}
+
+export interface NDPRRequestContext {
+  tenantId: string;
+  actor: NDPRVerifiedActor | null;
+  actorId: string | null;
+  subjectId: string | null;
+  subjectSource: 'verified-account-subject' | 'anonymous-uuid-capability' | null;
+  roles: readonly string[];
+}
+
+export type NDPRContextRequirement = 'tenant' | 'subject' | 'staff';
+export interface NDPRContextProblem { status: 401 | 403 | 503; error: string }
+export type NDPRVerifiedActorResolver = (
+  request: Request,
+) => Promise<NDPRVerifiedActor | null>;
+
+const ANONYMOUS_SUBJECT_PATTERN =
+  /^anon_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const STAFF_ROLES = new Set(['ndpr:staff', 'ndpr:admin']);
+
+/**
+ * Replace this safe default with a verified Express auth/session integration.
+ * Never trust actor, account subject, profile, role, or tenant fields from
+ * request-controlled input.
+ */
+export async function resolveVerifiedNDPRActor(
+  _request: Request,
+): Promise<NDPRVerifiedActor | null> {
+  return null;
+}
+
+/**
+ * The tenant comes only from server configuration. The only client-provided
+ * identity accepted by default is a random anon_<UUID> subject capability;
+ * it never grants staff access.
+ */
+export async function resolveNDPRRequestContext(
+  request: Request,
+  actorResolver: NDPRVerifiedActorResolver = resolveVerifiedNDPRActor,
+): Promise<NDPRRequestContext> {
+  const tenantId = process.env.NDPR_TENANT_ID?.trim() ?? '';
+  const candidate = request.get('x-ndpr-subject-id')?.trim() ?? '';
+  const anonymousSubjectId = ANONYMOUS_SUBJECT_PATTERN.test(candidate)
+    ? candidate
+    : null;
+  const actor = normalizeVerifiedActor(await actorResolver(request));
+  const subjectId = actor?.subjectId ?? anonymousSubjectId;
+  const subjectSource = actor?.subjectId
+    ? 'verified-account-subject' as const
+    : anonymousSubjectId
+      ? 'anonymous-uuid-capability' as const
+      : null;
+
+  return {
+    tenantId,
+    actor,
+    actorId: actor?.id ?? null,
+    subjectId,
+    subjectSource,
+    roles: actor?.roles ?? [],
+  };
+}
+
+export function getNDPRContextProblem(
+  context: NDPRRequestContext,
+  requirement: NDPRContextRequirement,
+): NDPRContextProblem | null {
+  if (!context.tenantId) {
+    return {
+      status: 503,
+      error: 'NDPR_TENANT_ID is not configured on the server',
+    };
+  }
+  if (requirement === 'subject' && !context.subjectId) {
+    return { status: 401, error: 'A verified data-subject identity is required' };
+  }
+  if (requirement === 'staff' && !context.actorId) {
+    return {
+      status: 401,
+      error: 'Connect resolveVerifiedNDPRActor to verified staff authentication',
+    };
+  }
+  if (requirement === 'staff'
+    && !context.roles.some((role) => STAFF_ROLES.has(role))) {
+    return { status: 403, error: 'NDPR staff or administrator role required' };
+  }
+  return null;
+}
+
+function normalizeVerifiedActor(
+  actor: NDPRVerifiedActor | null,
+): NDPRVerifiedActor | null {
+  if (!actor
+    || typeof actor.id !== 'string'
+    || typeof actor.displayName !== 'string'
+    || typeof actor.email !== 'string'
+    || !Array.isArray(actor.roles)) {
+    return null;
+  }
+  const id = actor.id.trim();
+  const displayName = actor.displayName.trim();
+  const email = actor.email.trim();
+  if (!id || !displayName || !email) return null;
+
+  return {
+    id,
+    displayName,
+    email,
+    department: typeof actor.department === 'string'
+      ? actor.department.trim() || undefined
+      : undefined,
+    subjectId: typeof actor.subjectId === 'string'
+      ? actor.subjectId.trim() || undefined
+      : undefined,
+    roles: actor.roles
+      .filter((role): role is string => typeof role === 'string')
+      .map((role) => role.trim())
+      .filter(Boolean),
+  };
+}

package/templates/github-ndpr-audit.yml

@@ -0,0 +1,31 @@
+# NDPA 2023 / NDPC GAID 2025 compliance gate — generated by create-ndpr for {{ORG_NAME_COMMENT}}.
+#
+# Runs `ndpr audit` on every push and pull request. The audit scores your
+# compliance config (consent, DSR, DPIA, breach, policy, lawful basis,
+# cross-border, RoPA) plus your GAID 2025 DCPMI designation inputs, and exits
+# non-zero when the overall score drops below the threshold — so a regression
+# fails CI the same way a broken test would.
+#
+# Edit ndpr.audit.json to reflect your real posture, then raise --min-score
+# over time as you close gaps. Docs: https://ndprtoolkit.com.ng/docs/guides/audit-cli
+name: NDPA compliance audit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ndpr-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      # The `ndpr` CLI ships with the toolkit. --no-save keeps it out of your
+      # package.json if you don't already depend on it directly.
+      - name: Install the NDPR toolkit (provides the `ndpr` CLI)
+        run: npm install --no-save @tantainnovative/ndpr-toolkit@{{TOOLKIT_VERSION}}
+      - name: Run the NDPA compliance audit
+        run: npx ndpr audit --min-score 70

package/templates/ndpr-audit.json

@@ -0,0 +1,14 @@
+{
+  "minScore": 70,
+  "compliance": {
+    "consent": { "hasConsentMechanism": true, "hasPurposeSpecification": true, "hasWithdrawalMechanism": true, "hasMinorProtection": false, "consentRecordsRetained": true },
+    "dsr": { "hasRequestMechanism": true, "supportsAccess": true, "supportsRectification": true, "supportsErasure": false, "supportsPortability": false, "supportsObjection": false, "responseTimelineDays": 30 },
+    "dpia": { "conductedForHighRisk": true, "documentedRisks": true, "mitigationMeasures": true },
+    "breach": { "hasNotificationProcess": true, "notifiesWithin72Hours": true, "hasRiskAssessment": true, "hasRecordKeeping": true },
+    "policy": { "hasPrivacyPolicy": true, "isPubliclyAccessible": true, "lastUpdated": "2026-01-01", "coversAllSections": true },
+    "lawfulBasis": { "documentedForAllProcessing": true, "hasLegitimateInterestAssessment": false },
+    "crossBorder": { "hasTransferMechanisms": true, "adequacyAssessed": true, "ndpcApprovalObtained": false },
+    "ropa": { "maintained": true, "includesAllProcessing": true, "lastReviewed": "2026-01-01" }
+  },
+  "dcpmi": { "dataSubjectsInSixMonths": 0 }
+}

package/templates/nextjs-breach-route.ts

@@ -1,107 +1,173 @@
 /**
- * Next.js App Router — Breach Notification Route
- * Generated by create-ndpr for: {{ORG_NAME}}
- *
- * NDPA §40 — data controllers must 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
+ * Next.js App Router — tenant-scoped breach register for {{ORG_NAME_COMMENT}}.
+ * All operations require verified staff context. Readiness is advisory; it is
+ * not evidence that a regulator or affected subject was notified.
  */
-
 import { NextRequest, NextResponse } from 'next/server';
+import { assessBreachNotification } from '@tantainnovative/ndpr-toolkit/server';
+import { getNDPRContextProblem, resolveNDPRRequestContext } from '{{NDPR_CONTEXT_IMPORT}}';
+// {{#if ORM=prisma}}
 import { PrismaClient } from '@prisma/client';
-
 const prisma = new PrismaClient();
+// {{/if}}
+// {{#if ORM=drizzle}}
+import { db } from '{{NDPR_DB_IMPORT}}';
+import { breachReports, complianceAuditLog } from '{{NDPR_SCHEMA_IMPORT}}';
+import { and, desc, eq } from 'drizzle-orm';
+// {{/if}}
+// {{#if ORM=none}}
+// DEVELOPMENT ONLY: replace both stores with one durable transactional store.
+interface BreachRow {
+  id: string; tenantId: string; title: string; description: string; category: string;
+  severity: Severity; status: string; discoveredAt: Date; occurredAt: Date | null;
+  reportedAt: Date; reporterName: string; reporterEmail: string; reporterDepartment: string | null;
+  affectedSystems: string[]; dataTypes: string[]; estimatedAffected: number | null;
+  approximateRecordCount: number | null; dataSubjectCategories: string[];
+  likelyConsequences: string | null; mitigationMeasures: string | null;
+  involvesSensitiveData: boolean; isPhasedReport: boolean; supplementsReportId: string | null;
+  initialActions: string | null;
+}
+const breachStore = new Map<string, BreachRow>();
+const auditLog: Array<{ id: string; tenantId: string; action: string; entityId: string; performedBy: string; at: Date }> = [];
+// {{/if}}
 
-function calculateSeverity(
-  category: string,
-  estimatedAffected?: number,
-): 'critical' | 'high' | 'medium' | 'low' {
-  const highRisk = ['unauthorized_access', 'ransomware', 'data_exfiltration', 'identity_theft'];
-  if (highRisk.includes(category)) {
-    return (estimatedAffected ?? 0) > 1000 ? 'critical' : 'high';
-  }
+type Severity = 'critical' | 'high' | 'medium' | 'low';
+function calculateSeverity(category: string, estimatedAffected: number | null): Severity {
+  const highRisk = new Set(['unauthorized_access', 'ransomware', 'data_exfiltration', 'identity_theft']);
+  if (highRisk.has(category)) return (estimatedAffected ?? 0) > 1000 ? 'critical' : 'high';
   if ((estimatedAffected ?? 0) > 500) return 'high';
   if ((estimatedAffected ?? 0) > 50) return 'medium';
   return 'low';
 }
+function finiteNonNegative(value: unknown): number | null {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
 
-// GET /api/breach?status=ongoing
 export async function GET(req: NextRequest) {
+  const context = await resolveNDPRRequestContext(req);
+  const problem = getNDPRContextProblem(context, 'staff');
+  if (problem) return NextResponse.json({ error: problem.error }, { status: problem.status });
   const status = req.nextUrl.searchParams.get('status');
 
+  // {{#if ORM=prisma}}
   const reports = await prisma.breachReport.findMany({
-    where: status ? { status } : undefined,
+    where: { tenantId: context.tenantId, ...(status ? { status } : {}) },
     orderBy: { reportedAt: 'desc' },
   });
-
+  // {{/if}}
+  // {{#if ORM=drizzle}}
+  const reports = status
+    ? await db.select().from(breachReports).where(and(eq(breachReports.tenantId, context.tenantId), eq(breachReports.status, status))).orderBy(desc(breachReports.reportedAt))
+    : await db.select().from(breachReports).where(eq(breachReports.tenantId, context.tenantId)).orderBy(desc(breachReports.reportedAt));
+  // {{/if}}
+  // {{#if ORM=none}}
+  const reports = [...breachStore.values()]
+    .filter((row) => row.tenantId === context.tenantId && (!status || row.status === status))
+    .sort((a, b) => b.reportedAt.getTime() - a.reportedAt.getTime());
+  // {{/if}}
   return NextResponse.json(reports);
 }
 
-// POST /api/breach
 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 },
-    );
+  const context = await resolveNDPRRequestContext(req);
+  const problem = getNDPRContextProblem(context, 'staff');
+  if (problem) return NextResponse.json({ error: problem.error }, { status: problem.status });
+  const actor = context.actor;
+  if (!actor) {
+    return NextResponse.json({ error: 'Verified staff profile is required' }, { status: 401 });
   }
-
-  if (!Array.isArray(affectedSystems) || !Array.isArray(dataTypes)) {
-    return NextResponse.json(
-      { error: 'affectedSystems and dataTypes must be arrays' },
-      { status: 400 },
-    );
+  const actorId = actor.id;
+  const body: unknown = await req.json().catch(() => null);
+  if (!body || typeof body !== 'object') return NextResponse.json({ error: 'A JSON object is required' }, { status: 400 });
+  const input = body as Record<string, unknown>;
+  const required = ['title', 'description', 'category', 'discoveredAt'] as const;
+  if (required.some((field) => typeof input[field] !== 'string' || !(input[field] as string).trim())) {
+    return NextResponse.json({ error: `${required.join(', ')} are required strings` }, { status: 400 });
   }
+  if (!Array.isArray(input.affectedSystems) || !input.affectedSystems.every((v) => typeof v === 'string') ||
+      !Array.isArray(input.dataTypes) || !input.dataTypes.every((v) => typeof v === 'string')) {
+    return NextResponse.json({ error: 'affectedSystems and dataTypes must be string arrays' }, { status: 400 });
+  }
+  const discoveredAt = new Date(input.discoveredAt as string);
+  const occurredAt = typeof input.occurredAt === 'string' ? new Date(input.occurredAt) : null;
+  if (!Number.isFinite(discoveredAt.getTime()) || discoveredAt.getTime() > Date.now() ||
+      (occurredAt && (!Number.isFinite(occurredAt.getTime()) || occurredAt > discoveredAt))) {
+    return NextResponse.json({ error: 'Breach dates are invalid or inconsistent' }, { status: 400 });
+  }
+  const estimatedAffected = input.estimatedAffected == null ? null : finiteNonNegative(input.estimatedAffected);
+  const approximateRecordCount = input.approximateRecordCount == null ? null : finiteNonNegative(input.approximateRecordCount);
+  if ((input.estimatedAffected != null && estimatedAffected === null) ||
+      (input.approximateRecordCount != null && approximateRecordCount === null)) {
+    return NextResponse.json({ error: 'Affected-subject and record counts must be finite non-negative numbers' }, { status: 400 });
+  }
+  const dataSubjectCategories = Array.isArray(input.dataSubjectCategories) && input.dataSubjectCategories.every((v) => typeof v === 'string')
+    ? input.dataSubjectCategories as string[] : [];
+  const severity = calculateSeverity(input.category as string, estimatedAffected);
+  const reportedAt = new Date();
+  const data = {
+    tenantId: context.tenantId,
+    title: input.title as string, description: input.description as string,
+    category: input.category as string, severity, status: 'ongoing', discoveredAt, occurredAt,
+    reporterName: actor.displayName, reporterEmail: actor.email,
+    reporterDepartment: actor.department ?? null,
+    affectedSystems: input.affectedSystems as string[], dataTypes: input.dataTypes as string[],
+    estimatedAffected, approximateRecordCount, dataSubjectCategories,
+    likelyConsequences: typeof input.likelyConsequences === 'string' ? input.likelyConsequences : null,
+    mitigationMeasures: typeof input.mitigationMeasures === 'string' ? input.mitigationMeasures : null,
+    involvesSensitiveData: input.involvesSensitiveData === true,
+    isPhasedReport: input.isPhasedReport === true,
+    supplementsReportId: typeof input.supplementsReportId === 'string' ? input.supplementsReportId : null,
+    initialActions: typeof input.initialActions === 'string' ? input.initialActions : null,
+  };
 
-  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,
-    },
+  // {{#if ORM=prisma}}
+  const report = await prisma.$transaction(async (tx) => {
+    const created = await tx.breachReport.create({ data });
+    await tx.complianceAuditLog.create({ data: {
+      tenantId: context.tenantId, module: 'breach', action: 'reported',
+      entityId: created.id, entityType: 'BreachReport', performedBy: actorId,
+      changes: { title: data.title, category: data.category, severity, status: 'ongoing' },
+    } });
+    return created;
   });
-
-  await prisma.complianceAuditLog.create({
-    data: {
-      module: 'breach',
-      action: 'reported',
-      entityId: report.id,
-      entityType: 'BreachReport',
-      changes: { title, category, severity, status: 'ongoing' },
-    },
+  // {{/if}}
+  // {{#if ORM=drizzle}}
+  const report = await db.transaction(async (tx) => {
+    const [created] = await tx.insert(breachReports).values(data).returning();
+    await tx.insert(complianceAuditLog).values({
+      tenantId: context.tenantId, module: 'breach', action: 'reported',
+      entityId: created.id, entityType: 'BreachReport', performedBy: actorId,
+      changes: { title: data.title, category: data.category, severity, status: 'ongoing' },
+    });
+    return created;
   });
+  // {{/if}}
+  // {{#if ORM=none}}
+  const report: BreachRow = { id: crypto.randomUUID(), ...data, reportedAt };
+  breachStore.set(report.id, report);
+  auditLog.push({ id: crypto.randomUUID(), tenantId: context.tenantId, action: 'reported', entityId: report.id, performedBy: actorId, at: reportedAt });
+  // {{/if}}
 
-  return NextResponse.json(report, { status: 201 });
+  const ndpcReadiness = assessBreachNotification({
+    id: report.id, title: data.title, description: data.description, category: data.category,
+    discoveredAt: discoveredAt.getTime(), occurredAt: occurredAt?.getTime(), reportedAt: reportedAt.getTime(),
+    reporter: { name: data.reporterName, email: data.reporterEmail, department: data.reporterDepartment ?? '' },
+    affectedSystems: data.affectedSystems, dataTypes: data.dataTypes,
+    involvesSensitiveData: data.involvesSensitiveData,
+    estimatedAffectedSubjects: estimatedAffected ?? undefined,
+    approximateRecordCount: approximateRecordCount ?? undefined,
+    dataSubjectCategories, likelyConsequences: data.likelyConsequences ?? undefined,
+    mitigationMeasures: data.mitigationMeasures ?? undefined,
+    isPhasedReport: data.isPhasedReport, supplementsReportId: data.supplementsReportId ?? undefined,
+    initialActions: data.initialActions ?? undefined,
+    dpoContact: { name: `{{ORG_NAME_TEMPLATE}} DPO`, email: `{{DPO_EMAIL_TEMPLATE}}` }, status: 'ongoing',
+  });
+  return NextResponse.json({ ...report, ndpcReadiness: {
+    complete: ndpcReadiness.complete, ready: ndpcReadiness.ready, valid: ndpcReadiness.valid,
+    completeness: ndpcReadiness.completeness, missing: ndpcReadiness.missing,
+    validationErrors: ndpcReadiness.validationErrors,
+    notificationRequired: ndpcReadiness.notificationRequired,
+    hoursRemaining: ndpcReadiness.timing.hoursRemaining,
+    evidenceRecorded: ndpcReadiness.evidence.notificationProvided,
+  } }, { status: 201 });
 }