@tantainnovative/create-ndpr 0.4.0 → 0.5.0

package/templates/nextjs-consent-route.ts

@@ -1,165 +1,373 @@
 /**
- * Next.js App Router — Consent API Route
- * Generated by create-ndpr for: {{ORG_NAME}}
- *
- * NDPA Section 26 (consent) and Section 25 (lawful basis). Records the
- * subject's affirmative choice with the audit metadata NDPC asks for.
- *
- * 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
+ * Next.js App Router — tenant-scoped consent persistence for {{ORG_NAME_COMMENT}}.
+ * Subject and tenant identity come only from the generated server context.
  */
-
 import { NextRequest, NextResponse } from 'next/server';
+import {
+  getNDPRContextProblem,
+  resolveNDPRRequestContext,
+} from '{{NDPR_CONTEXT_IMPORT}}';
 // {{#if ORM=prisma}}
-import { PrismaClient } from '@prisma/client';
-
+import { Prisma, PrismaClient } from '@prisma/client';
 const prisma = new PrismaClient();
 // {{/if}}
 // {{#if ORM=drizzle}}
-import { db } from '@/drizzle';
-import { consentRecords, complianceAuditLog } from '@/drizzle/ndpr-schema';
-import { eq, and, isNull, desc } from 'drizzle-orm';
+import { db } from '{{NDPR_DB_IMPORT}}';
+import { consentRecords, complianceAuditLog } from '{{NDPR_SCHEMA_IMPORT}}';
+import { and, desc, eq, isNull } from 'drizzle-orm';
 // {{/if}}
 // {{#if ORM=none}}
-// TODO ({{ORG_NAME}}): wire this to your persistent store of choice. The
-// in-memory map below is enough to develop against locally but DOES NOT
-// satisfy NDPA Section 44 (record-keeping) or the auditability NDPC asks
-// about. Replace `consentStore`/`auditLog` with your DB / KV / API.
+// DEVELOPMENT ONLY: replace both stores with one durable transactional store.
 interface ConsentRecord {
-  id: string;
-  subjectId: string;
-  consents: Record<string, boolean>;
-  version: string;
-  method: string;
-  lawfulBasis: string | null;
-  ipAddress: string | null;
-  userAgent: string | null;
-  createdAt: Date;
-  revokedAt: Date | null;
+  id: string; tenantId: string; subjectId: string; activeSubjectKey: string | null;
+  consents: Record<string, boolean>; version: string; method: string;
+  hasInteracted: boolean; lawfulBasis: string | null;
+  ipAddress: string | null; userAgent: string | null; clientTimestamp: Date;
+  createdAt: Date; revokedAt: Date | null;
+}
+interface AuditRow {
+  id: string; tenantId: string; module: string; action: string;
+  entityId: string; performedBy: string | null; at: Date;
 }
 const consentStore = new Map<string, ConsentRecord>();
-const auditLog: Array<{ id: string; module: string; action: string; entityId: string; at: Date }> = [];
-function newId() { return crypto.randomUUID(); }
+const auditLog: AuditRow[] = [];
 // {{/if}}
 
-// GET /api/consent?subjectId=xxx
-export async function GET(req: NextRequest) {
-  const subjectId = req.nextUrl.searchParams.get('subjectId');
+interface ConsentSettings {
+  consents: Record<string, boolean>;
+  version: string;
+  method: string;
+  hasInteracted: boolean;
+  lawfulBasis?: string;
+  timestamp: number;
+}
 
-  if (!subjectId) {
-    return NextResponse.json({ error: 'subjectId required' }, { status: 400 });
+function validateConsentBody(body: unknown): string | null {
+  if (!body || typeof body !== 'object') return 'A JSON object is required';
+  const value = body as Record<string, unknown>;
+  if (!value.consents || typeof value.consents !== 'object' || Array.isArray(value.consents)) {
+    return 'consents must be an object';
+  }
+  if (Object.values(value.consents).some((consent) => typeof consent !== 'boolean')) {
+    return 'Every consent value must be boolean';
+  }
+  if (typeof value.version !== 'string' || !value.version.trim()) return 'version is required';
+  if (value.method !== undefined && (typeof value.method !== 'string' || !value.method.trim())) {
+    return 'method must be a non-empty string';
+  }
+  if (value.hasInteracted !== true && value.hasInteracted !== false) {
+    return 'hasInteracted must be boolean';
   }
+  if (typeof value.timestamp !== 'number' || !Number.isSafeInteger(value.timestamp) || value.timestamp < 0
+      || !Number.isFinite(new Date(value.timestamp).getTime())) {
+    return 'timestamp must be a non-negative safe-integer epoch value within the valid Date range';
+  }
+  if (value.lawfulBasis !== undefined && typeof value.lawfulBasis !== 'string') {
+    return 'lawfulBasis must be a string';
+  }
+  return null;
+}
+
+export async function GET(req: NextRequest) {
+  const context = await resolveNDPRRequestContext(req);
+  const problem = getNDPRContextProblem(context, 'subject');
+  if (problem) return NextResponse.json({ error: problem.error }, { status: problem.status });
+  const { tenantId, subjectId } = context as typeof context & { subjectId: string };
 
   // {{#if ORM=prisma}}
   const record = await prisma.consentRecord.findFirst({
-    where: { subjectId, revokedAt: null },
+    where: { tenantId, subjectId, revokedAt: null },
     orderBy: { createdAt: 'desc' },
   });
   // {{/if}}
   // {{#if ORM=drizzle}}
-  const [record] = await db
-    .select()
-    .from(consentRecords)
-    .where(and(eq(consentRecords.subjectId, subjectId), isNull(consentRecords.revokedAt)))
-    .orderBy(desc(consentRecords.createdAt))
-    .limit(1);
+  const [record] = await db.select().from(consentRecords)
+    .where(and(
+      eq(consentRecords.tenantId, tenantId),
+      eq(consentRecords.subjectId, subjectId),
+      isNull(consentRecords.revokedAt),
+    ))
+    .orderBy(desc(consentRecords.createdAt)).limit(1);
   // {{/if}}
   // {{#if ORM=none}}
   const record = [...consentStore.values()]
-    .filter((r) => r.subjectId === subjectId && r.revokedAt === null)
-    .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())[0];
+    .filter((row) => row.tenantId === tenantId && row.subjectId === subjectId && row.revokedAt === null)
+    .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())[0] ?? null;
   // {{/if}}
-
-  return NextResponse.json(record ?? null);
+  return NextResponse.json(record ? toConsentSettings(record) : null);
 }
 
-// POST /api/consent
 export async function POST(req: NextRequest) {
-  const body = await req.json();
-  const { subjectId, consents, version, method, lawfulBasis } = body;
+  const context = await resolveNDPRRequestContext(req);
+  const problem = getNDPRContextProblem(context, 'subject');
+  if (problem) return NextResponse.json({ error: problem.error }, { status: problem.status });
+  const { tenantId, subjectId } = context as typeof context & { subjectId: string };
+  const body: unknown = await req.json().catch(() => null);
+  const validationError = validateConsentBody(body);
+  if (validationError) return NextResponse.json({ error: validationError }, { status: 400 });
+  const value = body as Omit<ConsentSettings, 'method'> & { method?: string };
+  const input: ConsentSettings = { ...value, method: value.method ?? 'api' };
 
-  if (!subjectId || !consents || !version) {
-    return NextResponse.json(
-      { error: 'subjectId, consents, and version are required' },
-      { status: 400 },
-    );
-  }
-
-  const ipAddress = req.headers.get('x-forwarded-for');
+  const forwardedFor = req.headers.get('x-forwarded-for');
+  const ipAddress = forwardedFor?.split(',')[0]?.trim() || null;
   const userAgent = req.headers.get('user-agent');
+  const clientTimestamp = new Date(input.timestamp);
+  const activeSubjectKey = JSON.stringify([tenantId, subjectId]);
 
   // {{#if ORM=prisma}}
-  // Revoke previously active records (immutable-audit pattern — Section 44).
-  await prisma.consentRecord.updateMany({
-    where: { subjectId, revokedAt: null },
-    data: { revokedAt: new Date() },
-  });
+  const transactionResult = await prisma.$transaction(async (tx) => {
+    const replay = await tx.consentRecord.findFirst({
+      where: {
+        tenantId,
+        subjectId,
+        clientTimestamp,
+        version: input.version,
+        method: input.method,
+      },
+      orderBy: { createdAt: 'desc' },
+    });
+    if (replay) {
+      return sameConsentMutation(replay, input)
+        ? { kind: 'record' as const, record: replay }
+        : { kind: 'collision' as const };
+    }
 
-  const record = await prisma.consentRecord.create({
-    data: { subjectId, consents, version, method: method ?? 'api', lawfulBasis: lawfulBasis ?? null, ipAddress, userAgent },
-  });
-
-  await prisma.complianceAuditLog.create({
-    data: { module: 'consent', action: 'created', entityId: record.id, entityType: 'ConsentRecord', changes: { subjectId, version, consents } },
+    await tx.consentRecord.updateMany({
+      where: { tenantId, subjectId, revokedAt: null },
+      data: { revokedAt: new Date(), activeSubjectKey: null },
+    });
+    const created = await tx.consentRecord.create({ data: {
+      tenantId, subjectId, activeSubjectKey, consents: input.consents,
+      version: input.version, method: input.method,
+      hasInteracted: input.hasInteracted, lawfulBasis: input.lawfulBasis ?? null,
+      ipAddress, userAgent, clientTimestamp,
+    } });
+    await tx.complianceAuditLog.create({ data: {
+      tenantId, module: 'consent', action: 'created', entityId: created.id,
+      entityType: 'ConsentRecord', performedBy: context.actorId,
+      changes: {
+        subjectId, version: input.version, method: input.method,
+        hasInteracted: input.hasInteracted,
+        consentCategories: Object.keys(input.consents),
+      },
+    } });
+    return { kind: 'record' as const, record: created };
+  }, {
+    isolationLevel: Prisma.TransactionIsolationLevel.Serializable,
+  }).catch((error: unknown) => {
+    if (isConcurrencyConflict(error)) return null;
+    throw error;
   });
+  if (!transactionResult) {
+    return NextResponse.json(
+      { error: 'Concurrent consent update conflict; retry the same idempotent request.' },
+      { status: 409 },
+    );
+  }
+  if (transactionResult.kind === 'collision') {
+    return NextResponse.json(
+      { error: 'Idempotency collision: timestamp/version/method identify different consent data.' },
+      { status: 409 },
+    );
+  }
+  const record = transactionResult.record;
   // {{/if}}
   // {{#if ORM=drizzle}}
-  await db.update(consentRecords).set({ revokedAt: new Date() }).where(and(eq(consentRecords.subjectId, subjectId), isNull(consentRecords.revokedAt)));
+  const transactionResult = await db.transaction(async (tx) => {
+    const [replay] = await tx.select().from(consentRecords).where(and(
+      eq(consentRecords.tenantId, tenantId),
+      eq(consentRecords.subjectId, subjectId),
+      eq(consentRecords.clientTimestamp, clientTimestamp),
+      eq(consentRecords.version, input.version),
+      eq(consentRecords.method, input.method),
+    )).orderBy(desc(consentRecords.createdAt)).limit(1);
+    if (replay) {
+      return sameConsentMutation(replay, input)
+        ? { kind: 'record' as const, record: replay }
+        : { kind: 'collision' as const };
+    }
 
-  const [record] = await db.insert(consentRecords).values({
-    subjectId, consents, version, method: method ?? 'api', lawfulBasis: lawfulBasis ?? null, ipAddress, userAgent,
-  }).returning();
-
-  await db.insert(complianceAuditLog).values({
-    module: 'consent', action: 'created', entityId: record.id, entityType: 'ConsentRecord', changes: { subjectId, version, consents },
+    await tx.update(consentRecords).set({
+      revokedAt: new Date(),
+      activeSubjectKey: null,
+    }).where(and(
+      eq(consentRecords.tenantId, tenantId),
+      eq(consentRecords.subjectId, subjectId),
+      isNull(consentRecords.revokedAt),
+    ));
+    const [created] = await tx.insert(consentRecords).values({
+      tenantId, subjectId, activeSubjectKey, consents: input.consents,
+      version: input.version, method: input.method,
+      hasInteracted: input.hasInteracted, lawfulBasis: input.lawfulBasis ?? null,
+      ipAddress, userAgent, clientTimestamp,
+    }).returning();
+    await tx.insert(complianceAuditLog).values({
+      tenantId, module: 'consent', action: 'created', entityId: created.id,
+      entityType: 'ConsentRecord', performedBy: context.actorId,
+      changes: {
+        subjectId, version: input.version, method: input.method,
+        hasInteracted: input.hasInteracted,
+        consentCategories: Object.keys(input.consents),
+      },
+    });
+    return { kind: 'record' as const, record: created };
+  }, { isolationLevel: 'serializable' }).catch((error: unknown) => {
+    if (isConcurrencyConflict(error)) return null;
+    throw error;
   });
+  if (!transactionResult) {
+    return NextResponse.json(
+      { error: 'Concurrent consent update conflict; retry the same idempotent request.' },
+      { status: 409 },
+    );
+  }
+  if (transactionResult.kind === 'collision') {
+    return NextResponse.json(
+      { error: 'Idempotency collision: timestamp/version/method identify different consent data.' },
+      { status: 409 },
+    );
+  }
+  const record = transactionResult.record;
   // {{/if}}
   // {{#if ORM=none}}
-  // Revoke previously active records for this subject
-  for (const r of consentStore.values()) {
-    if (r.subjectId === subjectId && r.revokedAt === null) r.revokedAt = new Date();
+  const replay = [...consentStore.values()].find((row) =>
+    row.tenantId === tenantId
+    && row.subjectId === subjectId
+    && row.clientTimestamp.getTime() === input.timestamp
+    && row.version === input.version
+    && row.method === input.method,
+  );
+  if (replay) {
+    if (!sameConsentMutation(replay, input)) {
+      return NextResponse.json(
+        { error: 'Idempotency collision: timestamp/version/method identify different consent data.' },
+        { status: 409 },
+      );
+    }
+    return NextResponse.json(toConsentSettings(replay), { status: 201 });
+  }
+  const now = new Date();
+  for (const row of consentStore.values()) {
+    if (row.tenantId === tenantId && row.subjectId === subjectId && row.revokedAt === null) {
+      row.revokedAt = now;
+      row.activeSubjectKey = null;
+    }
   }
   const record: ConsentRecord = {
-    id: newId(), subjectId, consents, version, method: method ?? 'api',
-    lawfulBasis: lawfulBasis ?? null, ipAddress, userAgent,
-    createdAt: new Date(), revokedAt: null,
+    id: crypto.randomUUID(), tenantId, subjectId, activeSubjectKey,
+    consents: input.consents, version: input.version, method: input.method,
+    hasInteracted: input.hasInteracted, lawfulBasis: input.lawfulBasis ?? null,
+    ipAddress, userAgent, clientTimestamp, createdAt: now, revokedAt: null,
   };
   consentStore.set(record.id, record);
-  auditLog.push({ id: newId(), module: 'consent', action: 'created', entityId: record.id, at: new Date() });
+  auditLog.push({
+    id: crypto.randomUUID(), tenantId, module: 'consent', action: 'created',
+    entityId: record.id, performedBy: context.actorId, at: now,
+  });
   // {{/if}}
-
-  return NextResponse.json(record, { status: 201 });
+  return NextResponse.json(toConsentSettings(record), { status: 201 });
 }
 
-// DELETE /api/consent?subjectId=xxx — Section 26 withdrawal
 export async function DELETE(req: NextRequest) {
-  const subjectId = req.nextUrl.searchParams.get('subjectId');
-
-  if (!subjectId) {
-    return NextResponse.json({ error: 'subjectId required' }, { status: 400 });
-  }
+  const context = await resolveNDPRRequestContext(req);
+  const problem = getNDPRContextProblem(context, 'subject');
+  if (problem) return NextResponse.json({ error: problem.error }, { status: problem.status });
+  const { tenantId, subjectId } = context as typeof context & { subjectId: string };
+  const now = new Date();
 
   // {{#if ORM=prisma}}
-  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' },
+  const revoked = await prisma.$transaction(async (tx) => {
+    const result = await tx.consentRecord.updateMany({
+      where: { tenantId, subjectId, revokedAt: null },
+      data: { revokedAt: now, activeSubjectKey: null },
+    });
+    if (result.count > 0) {
+      await tx.complianceAuditLog.create({ data: {
+        tenantId, module: 'consent', action: 'revoked', entityId: subjectId,
+        entityType: 'ConsentRecord', performedBy: context.actorId,
+        changes: { subjectId, revokedRecords: result.count },
+      } });
+    }
+    return result.count;
   });
   // {{/if}}
   // {{#if ORM=drizzle}}
-  await db.update(consentRecords).set({ revokedAt: new Date() }).where(and(eq(consentRecords.subjectId, subjectId), isNull(consentRecords.revokedAt)));
-  await db.insert(complianceAuditLog).values({ module: 'consent', action: 'revoked', entityId: subjectId, entityType: 'ConsentRecord' });
+  const revoked = await db.transaction(async (tx) => {
+    const rows = await tx.update(consentRecords).set({
+      revokedAt: now,
+      activeSubjectKey: null,
+    }).where(and(
+      eq(consentRecords.tenantId, tenantId),
+      eq(consentRecords.subjectId, subjectId),
+      isNull(consentRecords.revokedAt),
+    )).returning({ id: consentRecords.id });
+    if (rows.length > 0) {
+      await tx.insert(complianceAuditLog).values({
+        tenantId, module: 'consent', action: 'revoked', entityId: subjectId,
+        entityType: 'ConsentRecord', performedBy: context.actorId,
+        changes: { subjectId, revokedRecords: rows.length },
+      });
+    }
+    return rows.length;
+  });
   // {{/if}}
   // {{#if ORM=none}}
-  for (const r of consentStore.values()) {
-    if (r.subjectId === subjectId && r.revokedAt === null) r.revokedAt = new Date();
+  let revoked = 0;
+  for (const row of consentStore.values()) {
+    if (row.tenantId === tenantId && row.subjectId === subjectId && row.revokedAt === null) {
+      row.revokedAt = now;
+      row.activeSubjectKey = null;
+      revoked += 1;
+    }
+  }
+  if (revoked > 0) {
+    auditLog.push({
+      id: crypto.randomUUID(), tenantId, module: 'consent', action: 'revoked',
+      entityId: subjectId, performedBy: context.actorId, at: now,
+    });
   }
-  auditLog.push({ id: newId(), module: 'consent', action: 'revoked', entityId: subjectId, at: new Date() });
   // {{/if}}
+  return NextResponse.json({ success: true, revoked });
+}
+
+function toConsentSettings(record: {
+  consents: unknown;
+  version: string;
+  method: string;
+  hasInteracted: boolean;
+  lawfulBasis: string | null;
+  clientTimestamp: Date | null;
+  createdAt: Date;
+}): ConsentSettings {
+  return {
+    consents: record.consents as Record<string, boolean>,
+    timestamp: record.clientTimestamp?.getTime() ?? record.createdAt.getTime(),
+    version: record.version,
+    method: record.method,
+    hasInteracted: record.hasInteracted,
+    lawfulBasis: record.lawfulBasis ?? undefined,
+  };
+}
+
+function sameConsentMutation(
+  record: { consents: unknown; hasInteracted: boolean; lawfulBasis: string | null },
+  input: ConsentSettings,
+): boolean {
+  const storedConsents = record.consents as Record<string, boolean>;
+  return JSON.stringify(sortedConsentEntries(storedConsents))
+      === JSON.stringify(sortedConsentEntries(input.consents))
+    && record.hasInteracted === input.hasInteracted
+    && (record.lawfulBasis ?? undefined) === input.lawfulBasis;
+}
+
+function sortedConsentEntries(consents: Record<string, boolean>) {
+  return Object.entries(consents).sort(([left], [right]) => left.localeCompare(right));
+}
 
-  return NextResponse.json({ success: true });
+function isConcurrencyConflict(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const candidate = error as { code?: unknown; cause?: unknown };
+  const code = typeof candidate.code === 'string' ? candidate.code : '';
+  if (['P2002', 'P2034', '23505', '40001', '40P01'].includes(code)) return true;
+  return candidate.cause !== error && isConcurrencyConflict(candidate.cause);
 }