hope-events/backend/src/utils/consent.js

/**
 * Parental consent for youth events.
 *
 * Rules:
 * - On an event with requiresParentalConsent, every attendee gives a date of birth.
 *   Anyone under 18 on the event's start date needs a parent/guardian (name, email,
 *   phone), who is sent a consent request by email AND WhatsApp — regardless of anyone's
 *   notification preference.
 * - A request's link token is random; only its HMAC is stored. Links expire when the
 *   event ends and can be re-sent (which issues a new token).
 * - The parent's answer records the time, IP, device, typed name, and the exact consent
 *   text and version they saw. Medical/emergency details are stored encrypted and purged
 *   a set number of days after the event (setting consent_medical_retention_days).
 * - Tickets are issued as normal but can't be checked in until consent is given — the
 *   latest request for the attendee decides. On a consent event, a ticket with no named
 *   attendee is treated as missing consent. Supervisors can override (audited).
 * - Reminders go 2 days after the request, then every 3 days, until answered or the event.
 */

const crypto = require('crypto');
const prisma = require('../config/db');

const DAY = 24 * 60 * 60 * 1000;
const FIRST_REMINDER_AFTER = 2 * DAY;
const REMINDER_EVERY = 3 * DAY;
const DEFAULT_RETENTION_DAYS = 30;

function consentError(message, statusCode = 400) {
  const err = new Error(message);
  err.statusCode = statusCode;
  return err;
}

// ─── Pure helpers ─────────────────────────────────────────────────────────────

/** Whole years old on `onDate`. */
function ageOn(dateOfBirth, onDate) {
  const dob = new Date(dateOfBirth);
  const on = new Date(onDate);
  let age = on.getUTCFullYear() - dob.getUTCFullYear();
  const beforeBirthday = on.getUTCMonth() < dob.getUTCMonth()
    || (on.getUTCMonth() === dob.getUTCMonth() && on.getUTCDate() < dob.getUTCDate());
  if (beforeBirthday) age -= 1;
  return age;
}

/** Under 18 on the event's start date. */
function isMinor(dateOfBirth, eventStart) {
  if (!dateOfBirth) return false;
  return ageOn(dateOfBirth, eventStart) < 18;
}

/**
 * Consent state for one attendee: 'not_required' | 'missing' | 'pending' | 'given' | 'declined'.
 * `latest` is the attendee's most recent ConsentRequest (or null).
 */
function consentStatusFor(attendee, event, latest) {
  if (!event?.requiresParentalConsent) return 'not_required';
  if (!attendee) return 'missing'; // unnamed place on a consent event
  if (!isMinor(attendee.dateOfBirth, event.startDate)) return 'not_required';
  if (!latest) return 'missing';
  return latest.status;
}

/** Whether a pending request is due a reminder now. */
function reminderDue(request, now = new Date()) {
  if (!request || request.status !== 'pending') return false;
  const t = new Date(now).getTime();
  if (t >= new Date(request.expiresAt).getTime()) return false;
  const gap = request.remindersSent === 0 ? FIRST_REMINDER_AFTER : REMINDER_EVERY;
  return t - new Date(request.lastSentAt).getTime() >= gap;
}

const str = (v, max = 500) => String(v ?? '').trim().slice(0, max);

/**
 * Checks a parent's answer on the consent page. Pure. Returns the cleaned answer.
 * @param {object} body  - { decision: 'give'|'decline', signedName, isGuardian, medical, emergency, photoConsent }
 * @param {object} event - with consentCollectMedical / Emergency / Photo
 */
function validateConsentAnswer(body, event) {
  const decision = body?.decision;
  if (decision !== 'give' && decision !== 'decline') throw consentError('Choose to give or decline consent.');
  const signedName = str(body.signedName, 200);
  if (signedName.length < 2) throw consentError('Type your full name to sign.');
  if (body.isGuardian !== true) throw consentError('Confirm that you are the parent or legal guardian.');

  const out = { decision, signedName, medical: null, emergency: null, photoConsent: null };
  if (decision === 'decline') return out;

  if (event.consentCollectMedical) {
    const m = body.medical || {};
    out.medical = {
      allergies: str(m.allergies), medication: str(m.medication),
      conditions: str(m.conditions), medicalAid: str(m.medicalAid, 200),
    };
  }
  if (event.consentCollectEmergency) {
    const em = body.emergency || {};
    out.emergency = { name: str(em.name, 200), phone: str(em.phone, 40), relationship: str(em.relationship, 100) };
    if (!out.emergency.name || !out.emergency.phone) throw consentError('Add an emergency contact name and phone number.');
  }
  if (event.consentCollectPhoto) {
    if (body.photoConsent !== true && body.photoConsent !== false) throw consentError('Answer the photo consent question.');
    out.photoConsent = body.photoConsent;
  }
  return out;
}

// ─── Tokens ───────────────────────────────────────────────────────────────────

const hashToken = (token) => crypto.createHmac('sha256', process.env.JWT_SECRET || '').update(`consent:${token}`).digest('hex');
const newToken = () => crypto.randomBytes(24).toString('hex');

function consentLink(token) {
  const base = (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').split(',')[0].trim().replace(/\/$/, '');
  return `${base}/consent/${token}`;
}

// ─── Encryption of medical/emergency details ──────────────────────────────────

function sealJson(value) {
  if (!value) return null;
  const { encrypt } = require('./encryption');
  return encrypt(JSON.stringify(value));
}

function openJson(value) {
  if (!value) return null;
  try {
    const { decrypt } = require('./encryption');
    return JSON.parse(decrypt(value));
  } catch {
    return null;
  }
}

// ─── Database helpers ─────────────────────────────────────────────────────────

/** Latest request per attendee id. */
async function latestRequestsFor(attendeeIds, db = prisma) {
  if (!attendeeIds.length) return new Map();
  const rows = await db.consentRequest.findMany({ where: { attendeeId: { in: attendeeIds } }, orderBy: { createdAt: 'desc' } });
  const out = new Map();
  for (const r of rows) if (!out.has(r.attendeeId)) out.set(r.attendeeId, r);
  return out;
}

async function sendConsentMessage(request, token, { reminder = false } = {}) {
  const { sendMail, emailWrapper, ctaButton, fallbackLink } = require('./email');
  const { waTextAny } = require('./notify');
  const { isValidZAPhone } = require('./whatsapp');
  const { getSettingSync } = require('./settingsCache');
  const orgName = getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
  const ff = `-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif`;

  const event = request.event || await prisma.event.findUnique({ where: { id: request.eventId } });
  const attendee = request.attendee || await prisma.attendee.findUnique({ where: { id: request.attendeeId } });
  const link = consentLink(token);
  const when = event?.startDate ? new Date(event.startDate).toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' }) : '';
  const subject = `${reminder ? 'Reminder: ' : ''}Consent needed for ${attendee.name} — ${event.title}`;
  const intro = `${attendee.name} has been registered for <strong>${event.title}</strong>${when ? ` on <strong>${when}</strong>` : ''}. As their parent or guardian, please review the details and give (or decline) consent.`;
  const sent = [];

  if (request.parentEmail && request.parentEmail.includes('@')) {
    const html = emailWrapper(`
      <p style="font-size:22px;font-weight:800;color:#0f172a;margin:0 0 8px 0">${reminder ? 'A reminder: ' : ''}Parental consent needed</p>
      <p style="margin:0 0 8px 0;color:#374151;font-family:${ff}">Hi <strong>${request.parentName || 'there'}</strong>,</p>
      <p style="margin:0 0 24px 0;color:#374151;font-family:${ff}">${intro}</p>
      ${ctaButton('Review and give consent', link)}
      ${fallbackLink(link)}
      <p style="font-size:13px;color:#64748b;margin:16px 0 0 0;font-family:${ff}">${attendee.name} can't be checked in at the event until consent is given.</p>
    `, { preheader: `Consent needed for ${attendee.name}` });
    try {
      await sendMail({ to: request.parentEmail, subject, html, text: `Hi ${request.parentName || 'there'},\n\n${intro.replace(/<[^>]+>/g, '')}\n\nReview and give consent: ${link}\n\n${orgName}` });
      sent.push('email');
    } catch (e) {
      console.warn('[consent] email failed:', e?.message || e);
    }
  }
  if (request.parentPhone && isValidZAPhone(request.parentPhone)) {
    await waTextAny({ name: request.parentName, phoneNumber: request.parentPhone },
      `${reminder ? '⏰ Reminder: ' : ''}Hi ${request.parentName || 'there'}, ${attendee.name} has been registered for *${event.title}*${when ? ` on ${when}` : ''}. Please give (or decline) parental consent here: ${link}`);
    sent.push('WhatsApp');
  }
  return sent;
}

/**
 * Creates (and sends) a consent request for an attendee. Earlier requests stay as the
 * record of what was agreed before; this one now decides check-in.
 */
async function createConsentRequest(attendee, event) {
  const token = newToken();
  const request = await prisma.consentRequest.create({
    data: {
      attendeeId: attendee.id,
      eventId: event.id,
      tokenHash: hashToken(token),
      textVersion: event.consentTextVersion || 1,
      consentText: event.consentText || '',
      parentName: attendee.parentName,
      parentEmail: attendee.parentEmail,
      parentPhone: attendee.parentPhone,
      expiresAt: event.endDate,
    },
  });
  const sent = await sendConsentMessage({ ...request, event, attendee }, token);
  return { request, sent };
}

/**
 * Makes sure every under-18 attendee on a registration has a consent request — creates
 * and sends one for anyone who has none yet, or whose parent details have changed since.
 */
async function ensureConsentRequests(registrationId) {
  const reg = await prisma.registration.findUnique({ where: { id: registrationId }, include: { event: true, attendees: true } });
  if (!reg || !reg.event.requiresParentalConsent || reg.status === 'cancelled') return 0;
  const minors = reg.attendees.filter(a => isMinor(a.dateOfBirth, reg.event.startDate));
  const latest = await latestRequestsFor(minors.map(a => a.id));
  let created = 0;
  for (const a of minors) {
    const r = latest.get(a.id);
    const parentChanged = r && (r.parentEmail !== a.parentEmail || r.parentPhone !== a.parentPhone);
    if (!r || (parentChanged && r.status !== 'given')) {
      await createConsentRequest(a, reg.event);
      created += 1;
    }
  }
  return created;
}

/** Re-sends a request with a fresh link (the old link stops working). */
async function resendConsentRequest(requestId) {
  const request = await prisma.consentRequest.findUnique({ where: { id: requestId }, include: { event: true, attendee: true } });
  if (!request) throw consentError('Consent request not found', 404);
  if (request.status !== 'pending') throw consentError(`Consent has already been ${request.status}.`);
  if (new Date(request.expiresAt) < new Date()) throw consentError('This event has ended.');
  const token = newToken();
  await prisma.consentRequest.update({ where: { id: request.id }, data: { tokenHash: hashToken(token), lastSentAt: new Date() } });
  return sendConsentMessage(request, token, { reminder: true });
}

async function findRequestByToken(token) {
  if (!token || typeof token !== 'string' || token.length > 100) return null;
  return prisma.consentRequest.findUnique({
    where: { tokenHash: hashToken(token) },
    include: { event: true, attendee: { include: { registration: { include: { user: { select: { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true } } } } } } },
  });
}

/**
 * Consent state for each ticket id — for the scan gate and staff screens.
 * @returns {Promise<Map<string, string>>} ticketId → consent status
 */
async function consentStatusForTickets(ticketIds) {
  const tickets = await prisma.ticket.findMany({ where: { id: { in: ticketIds } }, include: { event: true, attendee: true } });
  const latest = await latestRequestsFor(tickets.map(t => t.attendeeId).filter(Boolean));
  const out = new Map();
  for (const t of tickets) {
    out.set(t.id, consentStatusFor(t.attendee, t.event, t.attendeeId ? latest.get(t.attendeeId) : null));
  }
  return out;
}

/** Daily job: reminders for unanswered requests. */
async function sendConsentReminders(now = new Date()) {
  const pending = await prisma.consentRequest.findMany({
    where: { status: 'pending', expiresAt: { gt: now } },
    include: { event: true, attendee: true },
  });
  // Only the latest request per attendee is still live.
  const latest = await latestRequestsFor([...new Set(pending.map(r => r.attendeeId))]);
  let sent = 0;
  for (const r of pending) {
    if (latest.get(r.attendeeId)?.id !== r.id || !reminderDue(r, now)) continue;
    if (new Date(r.event.startDate) <= now) continue; // the event has started
    const token = newToken();
    await prisma.consentRequest.update({ where: { id: r.id }, data: { tokenHash: hashToken(token), lastSentAt: now, remindersSent: { increment: 1 } } });
    await sendConsentMessage(r, token, { reminder: true }).catch(e => console.warn('[consent] reminder failed:', e?.message || e));
    sent += 1;
  }
  return sent;
}

/** Daily job: delete medical/emergency details a set number of days after the event. */
async function purgeConsentMedicalData(now = new Date()) {
  const { getSettingSync } = require('./settingsCache');
  const days = Math.max(0, parseInt(getSettingSync('consent_medical_retention_days', String(DEFAULT_RETENTION_DAYS)), 10) || DEFAULT_RETENTION_DAYS);
  const cutoff = new Date(new Date(now).getTime() - days * DAY);
  const res = await prisma.consentRequest.updateMany({
    where: { medicalPurgedAt: null, event: { endDate: { lt: cutoff } }, OR: [{ medical: { not: null } }, { emergency: { not: null } }] },
    data: { medical: null, emergency: null, medicalPurgedAt: now },
  });
  return res.count;
}

/** Clears parent, medical and emergency details for a person's registrations (anonymise). */
async function clearConsentDataForUser(userId, db = prisma) {
  const attendees = await db.attendee.findMany({ where: { OR: [{ userId }, { registration: { userId } }] }, select: { id: true } });
  const ids = attendees.map(a => a.id);
  if (!ids.length) return 0;
  await db.attendee.updateMany({ where: { id: { in: ids } }, data: { parentName: null, parentEmail: null, parentPhone: null, dateOfBirth: null, email: null, phone: null } });
  const res = await db.consentRequest.updateMany({
    where: { attendeeId: { in: ids } },
    data: { medical: null, emergency: null, parentName: null, parentEmail: null, parentPhone: null, ip: null, device: null, medicalPurgedAt: new Date() },
  });
  return res.count;
}

module.exports = {
  DEFAULT_RETENTION_DAYS,
  consentError,
  ageOn,
  isMinor,
  consentStatusFor,
  reminderDue,
  validateConsentAnswer,
  hashToken,
  consentLink,
  sealJson,
  openJson,
  latestRequestsFor,
  createConsentRequest,
  ensureConsentRequests,
  resendConsentRequest,
  findRequestByToken,
  consentStatusForTickets,
  sendConsentReminders,
  purgeConsentMedicalData,
  clearConsentDataForUser,
};