create-ailk 0.19.0 → 0.19.1

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

@@ -29,16 +29,32 @@
  * rather than replacing it. Declines are written as `granted: false` (D8).
  */
 
-import { createHash } from "node:crypto";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 
+import type { Prisma } from "@working-theory/database";
 import { logger } from "@working-theory/observability";
 import {
+  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,
+  userPlatformRows,
+  type PurposeConsentState,
+} from "../lib/consent-store.js";
 import { prisma } from "../lib/prisma.js";
 
 /**
@@ -54,7 +70,10 @@ export interface ConsentWriteClient {
   };
 }
 
-interface ConsentGrantRow {
+/** 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
@@ -72,6 +91,14 @@ interface ConsentGrantRow {
   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;
 }
 
 /**
@@ -134,7 +161,12 @@ export function requiredConsentUnmet(
   consents: Record<string, boolean>,
 ): string | undefined {
   for (const purpose of config.purposes) {
-    if (purpose.required && consents[purpose.id] !== true) return purpose.id;
+    // 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;
 }
@@ -144,6 +176,12 @@ export interface RecordConsentInput {
   /** 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;
@@ -191,6 +229,10 @@ export async function recordConsent(
       locale,
       statement,
       statementHash: consentStatementHash(statement),
+      personId: input.personId,
+      source: input.source,
+      sourceRef: input.sourceRef ?? null,
+      policyVersion: purpose.policyVersion,
     });
   }
 
@@ -215,6 +257,8 @@ export interface RecordLegacyConsentInput {
   siteId: string;
   subjectType: string;
   subjectId: string;
+  /** Where the legacy `consent: true` came from (#8438 D3). */
+  source: ConsentWriteSource;
   config: SiteConsentConfig;
 }
 
@@ -247,8 +291,449 @@ export async function recordLegacyConsent(
         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 };
+  });
+}
+
+/**
+ * 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 };
+}