create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/services/consent.ts

@@ -1,834 +0,0 @@
-/**
- * @file consent.ts
- * @description The consent-grant writer (#5275 Part B) — `recordConsent`,
- * the one function that turns a person's answers to a site's consent
- * purposes into `ConsentGrant` rows, plus `recordLegacyConsent`, the D11
- * path for a caller that could only say `consent: true`.
- *
- * SURFACE-AGNOSTIC BY DESIGN (D10). A grant's subject is a `subjectType` +
- * `subjectId` pair of plain scalars with no relation into any other table
- * (ADR 0009 invariant 1), so a new surface — the newsletter subscribe path
- * is the named follow-up — adopts consent by adding ONE call here and NO
- * migration. Nothing in this module knows what a project listing is.
- *
- * THE EVIDENCE RULE (spec §5.2): no row is ever written with statement text
- * the system did not actually render to that person. Two consequences:
- *
- *   - `recordConsent` resolves each statement from the SAME registry and the
- *     SAME `resolveConsentStatement` the renderer used (D7), so the recorded
- *     wording and the rendered wording are one string by construction, and a
- *     request body never carries wording at all. A purpose id the registry
- *     does not know is skipped, not written: no statement was rendered for it.
- *   - A grant whose wording cannot be proven — a legacy `consent: true` body,
- *     or the migration backfill — carries `UNRECOVERABLE_CONSENT_STATEMENT`,
- *     never today's default text. Stamping current wording onto a grant
- *     nobody read would fabricate evidence (D11).
- *
- * APPEND-ONLY (D9): every write is a `createMany`; this module never
- * updates or upserts, so a later withdrawal sits beside the earlier grant
- * rather than replacing it. Declines are written as `granted: false` (D8).
- */
-
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-
-import type { Prisma } from "@working-theory/database";
-import { logger } from "@working-theory/observability";
-import {
-  ACCOUNT_TERMS_PURPOSE_ID,
-  consentPolicyHref,
-  consentPurposeById,
-  consentPurposeKind,
-  consentVisitorIdSchema,
-  cookiePurpose,
-  resolveConsentStatement,
-  resolveLocalizedString,
-  SITE_CONSENT_CONFIG_DEFAULTS,
-  type ConsentSource,
-  type MemberConsentPurpose,
-  type SiteConsentConfig,
-} from "@working-theory/validation";
-
-import {
-  anySourceConsentRows,
-  effectiveConsent,
-  latestVisitorChoice,
-  ownConsentRows,
-  personHasCheckoutGrant,
-  userPlatformRows,
-  type PurposeConsentState,
-} from "../lib/consent-store.js";
-import { prisma } from "../lib/prisma.js";
-
-/**
- * The one delegate this module writes through — the shape of `prisma` AND of
- * the `tx` client an interactive `$transaction` hands out, so a caller that
- * creates the subject row can write the grant in the SAME transaction (the
- * listing's `start` does): either the row and its evidence both land, or
- * neither does.
- */
-export interface ConsentWriteClient {
-  consentGrant: {
-    createMany(args: { data: ConsentGrantRow[] }): Promise<{ count: number }>;
-  };
-}
-
-/** The sources a writer may name — `legacy` is the migration's alone (D1). */
-export type ConsentWriteSource = Exclude<ConsentSource, "legacy">;
-
-export interface ConsentGrantRow {
-  siteId: string;
-  /**
-   * #6374 — the tenancy fence's isolation key, equal to `siteId` by
-   * construction. Non-optional on purpose: `consent_grants.workspace_id` is
-   * NOT NULL as of
-   * database/migrations/20260922120000_tenancy_fence, so a row builder that
-   * forgot it would fail at runtime; declaring it required here makes the
-   * type checker say so instead.
-   */
-  workspaceId: string;
-  subjectType: string;
-  subjectId: string;
-  purposeId: string;
-  granted: boolean;
-  locale: string;
-  statement: string;
-  statementHash: string;
-  /** #8438 D2 — the Person this row counts toward; `null` for a visitor, listing or user subject. */
-  personId: string | null;
-  /** #8438 D2 — where the answer came from. Required: every writer must say. */
-  source: ConsentWriteSource;
-  /** #8438 D2 — the magnet slug for `magnet`; `spoke:<id>` for a hub-credential write. */
-  sourceRef: string | null;
-  /** #8438 D2 — the registry's policy version the person read. */
-  policyVersion: number;
-}
-
-/**
- * The most keys a `consents` map may carry on an anonymous request. Any real
- * registry is a handful of purposes; the cap bounds the per-request work an
- * unbounded map could buy (security review, Low 3).
- */
-export const MAX_CONSENT_KEYS = 64;
-
-/**
- * The statement sentinel for a grant whose wording cannot be proven — a row
- * carrying it records THAT a person consented (and when), not WHAT they read.
- * Written on exactly two paths: `recordLegacyConsent` (a body carrying only
- * the legacy `consent: true` literal, D11) and the consent_grants migration's
- * backfill of pre-existing listings, which must carry this exact literal.
- * It is never a substitute for real wording: a caller that rendered a
- * statement records it through `recordConsent`.
- */
-export const UNRECOVERABLE_CONSENT_STATEMENT =
-  "[unrecoverable: no statement was rendered by this system for this grant]";
-
-/** BCP-47 `und` — the locale of a statement nobody read. */
-export const UNRECOVERABLE_CONSENT_LOCALE = "und";
-
-/** sha256 hex of a statement — the `statementHash` that groups identical wordings. */
-export function consentStatementHash(statement: string): string {
-  return createHash("sha256").update(statement).digest("hex");
-}
-
-/**
- * The site's consent registry.
- *
- * There is no per-site consent config ROW yet (spec §4 deliberately adds
- * none), so every site resolves to `SITE_CONSENT_CONFIG_DEFAULTS`. This
- * function is the single seam a `SiteConsentConfig` row wires into later
- * (the `listingConfigFor` shape: read the blob, `consentConfigFor(blob)`).
- * The RENDERER (`packages/ui`) resolves its statements from the same
- * `SITE_CONSENT_CONFIG_DEFAULTS`, which is what keeps the recorded statement
- * identical to the rendered one until a config row exists — at which point
- * both sides must read the same row.
- */
-export async function consentConfigForSite(
-  _siteId: string,
-): Promise<SiteConsentConfig> {
-  return SITE_CONSENT_CONFIG_DEFAULTS;
-}
-
-/**
- * The id of the first REQUIRED registry purpose `consents` does not GRANT —
- * declined (`false`) or simply absent — or `undefined` when every required
- * purpose is `true`. Absence counts as unmet on purpose (security review,
- * Medium 1): a body carrying `consents: {}` beside `consent: true` would
- * otherwise create the subject with no grant row at all, which is a worse
- * record than the legacy sentinel. A surface whose subject cannot exist
- * without the required purposes (the listing: the row goes on to publish the
- * founder's address) checks this before creating the subject.
- */
-export function requiredConsentUnmet(
-  config: SiteConsentConfig,
-  consents: Record<string, boolean>,
-): string | undefined {
-  for (const purpose of config.purposes) {
-    // A `signUp` agreement is asked on the member sign-up form (#8438 D13),
-    // never on a lead or listing form — a form that cannot show it cannot
-    // be refused for lacking it.
-    if (purpose.required && !purpose.signUp && consents[purpose.id] !== true) {
-      return purpose.id;
-    }
-  }
-  return undefined;
-}
-
-export interface RecordConsentInput {
-  siteId: string;
-  /** e.g. `project_listing`, `subscriber` — a plain scalar, no relation (D10). */
-  subjectType: string;
-  subjectId: string;
-  /** The Person the answers count toward, when the writer knows one (#8438 D3). */
-  personId: string | null;
-  /** Where the answers came from — required, so every caller must say (#8438 D3). */
-  source: ConsentWriteSource;
-  /** The magnet slug for `source: "magnet"`. */
-  sourceRef?: string;
-  /** The locale the statements were RENDERED in; the served locale is what gets recorded. */
-  locale: string;
-  config: SiteConsentConfig;
-  /** purposeId → the person's answer. `false` is a stored decline (D8). */
-  consents: Record<string, boolean>;
-}
-
-/**
- * Write one `ConsentGrant` row per answered purpose in one `createMany`.
- * Returns the number of rows written. Append-only — never update/upsert.
- * `db` defaults to the shared client; pass a `$transaction` client to land
- * the grant atomically with the subject row it belongs to.
- */
-export async function recordConsent(
-  input: RecordConsentInput,
-  db: ConsentWriteClient = prisma,
-): Promise<number> {
-  const rows: ConsentGrantRow[] = [];
-  const unknown: string[] = [];
-
-  for (const [purposeId, granted] of Object.entries(input.consents)) {
-    const purpose = consentPurposeById(input.config, purposeId);
-    if (!purpose) {
-      // Not in the registry ⇒ no statement was rendered for it ⇒ nothing to
-      // record (the evidence rule). Collected and logged ONCE per call below,
-      // because a client naming a purpose the site does not declare is a
-      // drift someone should see — and a map full of junk keys must not buy
-      // a log line each.
-      unknown.push(purposeId);
-      continue;
-    }
-    const { statement, locale } = resolveConsentStatement(purpose, input.locale);
-    rows.push({
-      siteId: input.siteId,
-      // #6374 — the isolation key, equal to `siteId` by construction.
-      // `input.siteId` is the caller's already-resolved site id; the
-      // `consent_grants_workspace_site_agree` CHECK makes a disagreement
-      // unstorable, and `consent_grants_workspace_id_format` rejects a raw
-      // alias loudly. Never read from a request body (AC-6).
-      workspaceId: input.siteId,
-      subjectType: input.subjectType,
-      subjectId: input.subjectId,
-      purposeId,
-      granted,
-      locale,
-      statement,
-      statementHash: consentStatementHash(statement),
-      personId: input.personId,
-      source: input.source,
-      sourceRef: input.sourceRef ?? null,
-      policyVersion: purpose.policyVersion,
-    });
-  }
-
-  if (unknown.length > 0) {
-    logger.warn(
-      {
-        siteId: input.siteId,
-        subjectType: input.subjectType,
-        unknownCount: unknown.length,
-        sample: unknown.slice(0, 5),
-      },
-      "[consent] skipping unknown purpose ids — not in the site's consent registry, no statement was rendered for them",
-    );
-  }
-
-  if (rows.length === 0) return 0;
-  const result = await db.consentGrant.createMany({ data: rows });
-  return result.count;
-}
-
-export interface RecordLegacyConsentInput {
-  siteId: string;
-  subjectType: string;
-  subjectId: string;
-  /** Where the legacy `consent: true` came from (#8438 D3). */
-  source: ConsentWriteSource;
-  config: SiteConsentConfig;
-}
-
-/**
- * The D11 path: a body that carried only the legacy `consent: true` literal.
- * Writes ONE grant against the site's first `required` purpose (falling back
- * to its first purpose), `granted: true`, with the statement marked
- * unrecoverable — the caller affirmed, but this system rendered it no
- * wording to affirm.
- */
-export async function recordLegacyConsent(
-  input: RecordLegacyConsentInput,
-  db: ConsentWriteClient = prisma,
-): Promise<number> {
-  const purpose =
-    input.config.purposes.find((p) => p.required) ?? input.config.purposes[0];
-  if (!purpose) return 0;
-
-  const result = await db.consentGrant.createMany({
-    data: [
-      {
-        siteId: input.siteId,
-        // #6374 — the isolation key, equal to `siteId` by construction; the
-        // same stamp the D10 path's row builder above applies.
-        workspaceId: input.siteId,
-        subjectType: input.subjectType,
-        subjectId: input.subjectId,
-        purposeId: purpose.id,
-        granted: true,
-        locale: UNRECOVERABLE_CONSENT_LOCALE,
-        statement: UNRECOVERABLE_CONSENT_STATEMENT,
-        statementHash: consentStatementHash(UNRECOVERABLE_CONSENT_STATEMENT),
-        personId: null,
-        source: input.source,
-        sourceRef: null,
-        policyVersion: purpose.policyVersion,
-      },
-    ],
-  });
-  return result.count;
-}
-
-// ─── #8438 — the person, banner, link and unsubscribe writers ───────────────
-
-type Tx = Prisma.TransactionClient;
-
-/**
- * The advisory lock every read-then-append below takes first (the member
- * writes' `ailk:member-inbound:<personId>` pattern): two identical requests
- * at the same moment write one row, not two.
- */
-async function lockConsent(tx: Tx, key: string): Promise<void> {
-  await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`;
-}
-
-function oneRow(args: {
-  workspaceId: string;
-  subjectType: string;
-  subjectId: string;
-  personId: string | null;
-  purposeId: string;
-  granted: boolean;
-  source: ConsentWriteSource;
-  sourceRef: string | null;
-  policyVersion: number;
-  statement: string;
-  locale: string;
-}): ConsentGrantRow {
-  return {
-    siteId: args.workspaceId,
-    workspaceId: args.workspaceId,
-    subjectType: args.subjectType,
-    subjectId: args.subjectId,
-    purposeId: args.purposeId,
-    granted: args.granted,
-    locale: args.locale,
-    statement: args.statement,
-    statementHash: consentStatementHash(args.statement),
-    personId: args.personId,
-    source: args.source,
-    sourceRef: args.sourceRef,
-    policyVersion: args.policyVersion,
-  };
-}
-
-export type RecordCookieChoiceInput = {
-  workspaceId: string;
-  visitorId: string;
-  choice: "accepted" | "declined";
-  locale: string;
-};
-
-/**
- * The cookie banner's log (D3): one row per CHANGE of a visitor's choice,
- * subject `visitor` / `visitorId`, source `cookie_banner`. Writes nothing
- * when the registry declares no cookie purpose, and nothing when the
- * visitor's newest row already records the same choice at the same policy
- * version — a replayed choice adds no row (SEC-8438-2).
- */
-export async function recordCookieChoice(
-  input: RecordCookieChoiceInput,
-  config?: SiteConsentConfig,
-): Promise<{ recorded: boolean }> {
-  const registry = config ?? (await consentConfigForSite(input.workspaceId));
-  const purpose = cookiePurpose(registry);
-  if (!purpose) return { recorded: false };
-  const granted = input.choice === "accepted";
-  const { statement, locale } = resolveConsentStatement(purpose, input.locale);
-
-  return prisma.$transaction(async (tx) => {
-    await lockConsent(
-      tx,
-      `ailk:consent:${input.workspaceId}:visitor:${input.visitorId}:${purpose.id}`,
-    );
-    const latest = await latestVisitorChoice(
-      input.workspaceId,
-      input.visitorId,
-      purpose.id,
-      tx,
-    );
-    if (
-      latest !== null &&
-      latest.granted === granted &&
-      latest.policyVersion === purpose.policyVersion
-    ) {
-      return { recorded: false };
-    }
-    await tx.consentGrant.createMany({
-      data: [
-        oneRow({
-          workspaceId: input.workspaceId,
-          subjectType: "visitor",
-          subjectId: input.visitorId,
-          personId: null,
-          purposeId: purpose.id,
-          granted,
-          source: "cookie_banner",
-          sourceRef: null,
-          policyVersion: purpose.policyVersion,
-          statement,
-          locale,
-        }),
-      ],
-    });
-    return { recorded: true };
-  });
-}
-
-export interface RecordPersonConsentInput {
-  workspaceId: string;
-  /** The Person the answer counts toward; `null` for the owner's platform consents (subject `user`). */
-  personId: string | null;
-  purposeId: string;
-  granted: boolean;
-  source: ConsentWriteSource;
-  /** `spoke:<id>` for a hub-credential write (SEC-8438-16); the magnet slug otherwise. */
-  sourceRef?: string;
-  locale: string;
-  config: SiteConsentConfig;
-  /** The subject the row names: `person`/`personId` for a member, `user`/`userId` for the owner. */
-  subject: { subjectType: string; subjectId: string };
-}
-
-export type RecordPersonConsentResult =
-  | { ok: true; changed: boolean }
-  | {
-      ok: false;
-      code: "purpose_unknown" | "agreement_not_withdrawable" | "cookie_purpose";
-    };
-
-/**
- * The settings, unsubscribe and sign-up write (D3). It appends a row only
- * when the answer changes the reading it is checked against:
- *
- *   - settings and sign-up are checked against the person's OWN reading;
- *   - an unsubscribe is checked against BOTH readings and is skipped only
- *     when each already says "not granted", so a newer anonymous decline
- *     can never hide a member's own grant;
- *   - an agreement writes only when no grant exists at the purpose's current
- *     policy version;
- *   - the owner's platform consents (no Person) are checked against the
- *     owner's own `user` rows.
- *
- * So a double click, a re-clicked link or a mail scanner adds no rows. It
- * refuses withdrawing an agreement and any write to the cookie purpose (the
- * banner owns cookies). The read and the append share one transaction whose
- * first statement is an advisory lock on the (subject, purpose) pair.
- */
-export async function recordPersonConsent(
-  input: RecordPersonConsentInput,
-): Promise<RecordPersonConsentResult> {
-  const purpose = consentPurposeById(input.config, input.purposeId);
-  if (!purpose) return { ok: false, code: "purpose_unknown" };
-  if (purpose.area === "cookies") return { ok: false, code: "cookie_purpose" };
-  const kind = consentPurposeKind(purpose);
-  if (kind === "agreement" && !input.granted) {
-    return { ok: false, code: "agreement_not_withdrawable" };
-  }
-  const { statement, locale } = resolveConsentStatement(purpose, input.locale);
-
-  return prisma.$transaction(async (tx) => {
-    await lockConsent(
-      tx,
-      `ailk:consent:${input.workspaceId}:${input.subject.subjectType}:${input.subject.subjectId}:${purpose.id}`,
-    );
-    const rows =
-      input.personId === null
-        ? await userPlatformRows(input.workspaceId, input.subject.subjectId, tx)
-        : await ownConsentRows(input.workspaceId, input.personId, tx);
-    const current = rows.find((row) => row.purposeId === purpose.id) ?? null;
-    // An unsubscribe is also checked against the any-source reading: an
-    // anonymous form's newer decline must not hide a member's own grant, so a
-    // withdrawal is skipped only when BOTH readings already say "not granted".
-    const anyCurrent =
-      input.source === "email_unsubscribe" && input.personId !== null
-        ? ((
-            await anySourceConsentRows(input.workspaceId, input.personId, tx)
-          ).find((row) => row.purposeId === purpose.id) ?? null)
-        : current;
-
-    const unchanged =
-      kind === "agreement"
-        ? current?.granted === true && current.policyVersion === purpose.policyVersion
-        : input.granted === effectiveConsent(kind, current) &&
-          input.granted === effectiveConsent(kind, anyCurrent);
-    if (unchanged) return { ok: true as const, changed: false };
-
-    await tx.consentGrant.createMany({
-      data: [
-        oneRow({
-          workspaceId: input.workspaceId,
-          subjectType: input.subject.subjectType,
-          subjectId: input.subject.subjectId,
-          personId: input.personId,
-          purposeId: purpose.id,
-          granted: input.granted,
-          source: input.source,
-          sourceRef: input.sourceRef ?? null,
-          policyVersion: purpose.policyVersion,
-          statement,
-          locale,
-        }),
-      ],
-    });
-    return { ok: true as const, changed: true };
-  });
-}
-
-export type RecordCheckoutConsentOutcome =
-  "recorded" | "unchanged" | "purpose_unknown" | "version_changed";
-
-/**
- * `<purposeId>@<policyVersion>` of the account terms as the registry reads
- * them now, and that version — the only stamp a checkout grant is recorded
- * for (SEC-8765-E). A spoke purchase's lead names the stamp it accepted
- * (#8778); derived, never written down, so a version bump retires every
- * older stamp.
- */
-export function currentAccountTermsStamp(): {
-  stamp: string;
-  policyVersion: number;
-} | null {
-  const purpose = consentPurposeById(
-    SITE_CONSENT_CONFIG_DEFAULTS,
-    ACCOUNT_TERMS_PURPOSE_ID,
-  );
-  return purpose
-    ? {
-        stamp: `${purpose.id}@${purpose.policyVersion}`,
-        policyVersion: purpose.policyVersion,
-      }
-    : null;
-}
-
-/**
- * The buyer's grant from a completed Stripe Checkout whose terms box was
- * accepted (#8765 D14): ONE `account_terms` row, subject `person` /
- * `personId`, source `checkout`, `sourceRef` the Checkout Session id, locale
- * `en`, and the registry's current statement, hash and policy version — the
- * statement the box showed once its link keys were resolved (D12).
- *
- * One transaction whose first statement is an advisory lock on
- * `ailk:consent:<workspaceId>:checkout:<sessionId>`; then, when this Person
- * already holds this session's `checkout` row, nothing is written (NFR7) — so
- * a webhook redelivery, even after a restart, adds no row. The row goes
- * through `recordConsent` on the transaction client. A `checkout` row is
- * unverified (D13): it reaches only the operator's any-source reading.
- * When the site registry's `account_terms` version is not the version the
- * session was stamped with, nothing is written (`version_changed`): the row
- * would otherwise record terms the box never showed.
- *
- * @param input.workspaceId the server-resolved workspace of the buyer's Person.
- * @param input.personId the buyer's Person, resolved by `checkoutBuyerPerson`.
- * @param input.sessionId the signed event's Checkout Session id.
- * @param input.policyVersion the version the session's `ailk_terms` stamp names.
- */
-export async function recordCheckoutConsent(input: {
-  workspaceId: string;
-  personId: string;
-  sessionId: string;
-  policyVersion: number;
-}): Promise<RecordCheckoutConsentOutcome> {
-  const config = await consentConfigForSite(input.workspaceId);
-  const purpose = consentPurposeById(config, ACCOUNT_TERMS_PURPOSE_ID);
-  if (!purpose) return "purpose_unknown";
-  if (purpose.policyVersion !== input.policyVersion) return "version_changed";
-
-  return prisma.$transaction(async (tx) => {
-    await lockConsent(
-      tx,
-      `ailk:consent:${input.workspaceId}:checkout:${input.sessionId}`,
-    );
-    if (
-      await personHasCheckoutGrant(
-        input.workspaceId,
-        input.personId,
-        purpose.id,
-        input.sessionId,
-        tx,
-      )
-    ) {
-      return "unchanged" as const;
-    }
-    await recordConsent(
-      {
-        siteId: input.workspaceId,
-        subjectType: "person",
-        subjectId: input.personId,
-        personId: input.personId,
-        source: "checkout",
-        sourceRef: input.sessionId,
-        locale: "en",
-        config,
-        consents: { [purpose.id]: true },
-      },
-      tx,
-    );
-    return "recorded" as const;
-  });
-}
-
-/**
- * One registry purpose as a settings screen reads it (D6): the wording in
- * `locale`, the policy link, and the caller's OWN state. `state` is `null`
- * when no own row exists; `effective` is what that means now.
- */
-export function consentPurposeView(
-  config: SiteConsentConfig,
-  state: PurposeConsentState,
-  locale: string,
-): MemberConsentPurpose {
-  const purpose = consentPurposeById(config, state.purposeId);
-  if (!purpose) throw new Error("consentPurposeView: purpose not in registry");
-  return {
-    id: purpose.id,
-    kind: state.kind,
-    area: purpose.area ?? null,
-    required: purpose.required,
-    signUp: purpose.signUp,
-    description:
-      purpose.description === undefined
-        ? purpose.id
-        : resolveLocalizedString(purpose.description, locale, "en"),
-    statement: resolveConsentStatement(purpose, locale).statement,
-    policyHref: consentPolicyHref(config, purpose) ?? null,
-    policyVersion: purpose.policyVersion,
-    state:
-      state.row === null
-        ? null
-        : {
-            granted: state.row.granted,
-            at: state.row.at.toISOString(),
-            source: state.row.source,
-            policyVersion: state.row.policyVersion,
-          },
-    effective: state.effective,
-  };
-}
-
-/** The request header a site's own server forwards the banner visitor id in (D11, D12). */
-export const CONSENT_VISITOR_HEADER = "x-ailk-consent-visitor";
-
-/**
- * The visitor id a request carries, or `undefined`. Only a v4 UUID counts: a
- * malformed or repeated header is ignored (and so links nothing), never
- * echoed and never logged (D11).
- */
-export function consentVisitorFromHeader(value: unknown): string | undefined {
-  return typeof value === "string" && consentVisitorIdSchema.safeParse(value).success
-    ? value
-    : undefined;
-}
-
-/** The delegate a visitor link is written through (an insert-or-ignore). */
-export interface ConsentLinkWriteClient {
-  consentVisitorLink: {
-    createMany(args: {
-      data: Array<{
-        workspaceId: string;
-        visitorId: string;
-        personId: string;
-        source: string;
-      }>;
-      skipDuplicates: true;
-    }): Promise<{ count: number }>;
-  };
-}
-
-/**
- * Link a banner visitor to the Person a later form or sign-in identifies
- * (C5): an insert-or-ignore on the unique key, so a repeat link is a no-op.
- * Never throws — a failure is logged `{ event, outcome }` and swallowed,
- * because a link must never fail a lead.
- */
-export async function linkConsentVisitor(
-  input: {
-    workspaceId: string;
-    visitorId: string;
-    personId: string;
-    source: "magnet" | "api" | "account_settings";
-  },
-  db: ConsentLinkWriteClient = prisma,
-): Promise<void> {
-  try {
-    await db.consentVisitorLink.createMany({
-      data: [
-        {
-          workspaceId: input.workspaceId,
-          visitorId: input.visitorId,
-          personId: input.personId,
-          source: input.source,
-        },
-      ],
-      skipDuplicates: true,
-    });
-  } catch {
-    logger.warn(
-      { event: "consent-visitor-link", outcome: "failed" },
-      "[consent] visitor link not written",
-    );
-  }
-}
-
-/** Whether `personId` is a Person of `workspaceId` (the unsubscribe route's check, D9). */
-export async function consentPersonExists(
-  workspaceId: string,
-  personId: string,
-  db: Pick<Tx, "person"> = prisma,
-): Promise<boolean> {
-  const found = await db.person.findFirst({
-    where: { id: personId, workspaceId },
-    select: { id: true },
-  });
-  return found !== null;
-}
-
-// ─── The unsubscribe link (D3, D9, SEC-8438-9) ──────────────────────────────
-
-/** Raised when a link is minted with no usable `AILK_CONSENT_LINK_SECRET`. */
-export class ConsentLinkSecretMissing extends Error {
-  constructor() {
-    super(
-      "AILK_CONSENT_LINK_SECRET is unset or shorter than 32 bytes — no unsubscribe link can be minted",
-    );
-    this.name = "ConsentLinkSecretMissing";
-  }
-}
-
-/** A token older than this is refused. */
-export const CONSENT_LINK_MAX_AGE_DAYS = 400;
-const CONSENT_LINK_VERSION = "v1";
-
-function linkSecret(): Buffer | null {
-  const secret = process.env["AILK_CONSENT_LINK_SECRET"];
-  if (secret === undefined || Buffer.byteLength(secret) < 32) return null;
-  return Buffer.from(secret);
-}
-
-/** Whether a usable link secret is configured (the route answers 503 otherwise). */
-export function consentLinkSecretConfigured(): boolean {
-  return linkSecret() !== null;
-}
-
-function signLink(secret: Buffer, body: string): string {
-  return createHmac("sha256", secret).update(body).digest("base64url");
-}
-
-export interface ConsentLinkClaims {
-  workspaceId: string;
-  personId: string;
-  purposeId: string;
-}
-
-/**
- * Mint the signed token an email's unsubscribe link carries:
- * `v1.<base64url(JSON {w,p,u,iat})>.<base64url(HMAC-SHA256)>`. `v1` names the
- * key generation, so a later rotation adds `v2` beside it. Throws
- * `ConsentLinkSecretMissing` with no usable secret — a sender therefore
- * cannot silently send an email without its link. The ids in the payload are
- * readable, not secret; they grant nothing without the HMAC.
- */
-export function consentUnsubscribeToken(
-  claims: ConsentLinkClaims,
-  now: Date = new Date(),
-): string {
-  const secret = linkSecret();
-  if (secret === null) throw new ConsentLinkSecretMissing();
-  const payload = Buffer.from(
-    JSON.stringify({
-      w: claims.workspaceId,
-      p: claims.personId,
-      u: claims.purposeId,
-      iat: Math.floor(now.getTime() / 1000),
-    }),
-  ).toString("base64url");
-  const body = `${CONSENT_LINK_VERSION}.${payload}`;
-  return `${body}.${signLink(secret, body)}`;
-}
-
-const LINK_WORKSPACE_ID = /^wksp_[0-9a-f-]{36}$/;
-const LINK_PERSON_ID = /^person_[0-9a-f-]{36}$/;
-const LINK_PURPOSE_ID = /^[a-z][a-z0-9_]{0,63}$/;
-
-/**
- * Verify a token. Constant-time, and `null` on ANY defect — a wrong version,
- * a flipped character, a malformed payload, a token older than 400 days or
- * dated in the future, or an unset secret.
- */
-export function verifyConsentUnsubscribeToken(
-  token: string,
-  now: Date = new Date(),
-): ConsentLinkClaims | null {
-  const secret = linkSecret();
-  if (secret === null) return null;
-  const parts = token.split(".");
-  if (parts.length !== 3) return null;
-  const [version, payload, signature] = parts as [string, string, string];
-  if (version !== CONSENT_LINK_VERSION) return null;
-  const expected = Buffer.from(
-    signLink(secret, `${version}.${payload}`),
-    "utf8",
-  );
-  const given = Buffer.from(signature, "utf8");
-  if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
-    return null;
-  }
-  let claims: unknown;
-  try {
-    claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-  } catch {
-    return null;
-  }
-  if (typeof claims !== "object" || claims === null) return null;
-  const { w, p, u, iat } = claims as Record<string, unknown>;
-  if (
-    typeof w !== "string" ||
-    typeof p !== "string" ||
-    typeof u !== "string" ||
-    typeof iat !== "number" ||
-    !LINK_WORKSPACE_ID.test(w) ||
-    !LINK_PERSON_ID.test(p) ||
-    !LINK_PURPOSE_ID.test(u)
-  ) {
-    return null;
-  }
-  const ageMs = now.getTime() - iat * 1000;
-  if (ageMs > CONSENT_LINK_MAX_AGE_DAYS * 86_400_000 || ageMs < -300_000) {
-    return null;
-  }
-  return { workspaceId: w, personId: p, purposeId: u };
-}