create-ailk 0.19.0 → 0.20.0

package/templates/database/__tests__/consent-ledger.db.test.ts

@@ -0,0 +1,345 @@
+/**
+ * @file consent-ledger.db.test.ts
+ *
+ * LIVE-DATABASE proof of the consent ledger (#8438, spec
+ * docs/specs/8438-consent-registry-and-ledger-step-spec.md D2, AC-2). Requires
+ * DATABASE_URL pointing at a Postgres with the migrations applied — the suite
+ * SKIPS when DATABASE_URL is unset, keeping the workspace Jest run DB-free
+ * (the repo convention; the `apps/api Route Tests (Postgres)` workflow runs it).
+ *
+ * What it proves that a mock cannot:
+ *   1. consent_grants and consent_visitor_links refuse UPDATE, DELETE and
+ *      TRUNCATE, each raising `<table> is append-only`.
+ *   2. A new ledger row must name its source and, unless legacy, its policy
+ *      version; the source vocabulary is closed.
+ *   3. A row stored before the ledger reads source = 'legacy' (written here
+ *      the only way the table allows) and the column has no default for a
+ *      writer that forgets.
+ *   4. consent_visitor_links takes only a v4 UUID visitor id, ignores a
+ *      repeat link, and carries no network or browser evidence column.
+ *
+ * Rows are append-only, so this suite cannot clean up after itself: every run
+ * stamps fresh workspace and person ids and leaves its rows behind.
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+/** A well-formed `<prefix>_<uuid v7-shaped>` id, fresh per call. */
+function id(prefix: string): string {
+  const hex = randomUUID().replace(/-/g, "");
+  return `${prefix}_${hex.slice(0, 8)}-${hex.slice(8, 12)}-7${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+
+describeDb("the consent ledger (#8438 D2, AC-2, live DB)", () => {
+  let db: Client;
+  const WS = id("wksp");
+  const PERSON = id("person");
+  const VISITOR = randomUUID();
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+  });
+
+  afterAll(async () => {
+    await db.end();
+  });
+
+  const insertGrant = (
+    cols: {
+      source?: string | null;
+      policyVersion?: number | null;
+      personId?: string | null;
+      omitSource?: boolean;
+    } = {},
+  ) => {
+    const names = [
+      "site_id",
+      "workspace_id",
+      "subject_type",
+      "subject_id",
+      "purpose_id",
+      "granted",
+      "locale",
+      "statement",
+      "statement_hash",
+      "person_id",
+      "policy_version",
+    ];
+    const values: unknown[] = [
+      WS,
+      WS,
+      "lead",
+      "lead_1",
+      "service_terms",
+      true,
+      "en",
+      "You agree.",
+      "hash",
+      cols.personId === undefined ? PERSON : cols.personId,
+      cols.policyVersion === undefined ? 1 : cols.policyVersion,
+    ];
+    if (!cols.omitSource) {
+      names.push("source");
+      values.push(cols.source === undefined ? "magnet" : cols.source);
+    }
+    const placeholders = values.map((_, i) => `$${i + 1}`).join(", ");
+    return db.query(
+      `INSERT INTO "consent_grants" (${names.map((n) => `"${n}"`).join(", ")}) VALUES (${placeholders}) RETURNING "id"`,
+      values,
+    );
+  };
+
+  const insertLink = (
+    cols: { visitorId?: string; source?: string; personId?: string } = {},
+  ) =>
+    db.query(
+      `INSERT INTO "consent_visitor_links" ("workspace_id", "visitor_id", "person_id", "source")
+       VALUES ($1, $2, $3, $4) RETURNING "id"`,
+      [
+        WS,
+        cols.visitorId ?? VISITOR,
+        cols.personId ?? PERSON,
+        cols.source ?? "magnet",
+      ],
+    );
+
+  describe("consent_grants", () => {
+    it("accepts a row that names its source and policy version", async () => {
+      const result = await insertGrant({ source: "account_settings" });
+      expect(result.rows[0].id).toMatch(/^cnsnt_/);
+    });
+
+    it("refuses an UPDATE, a row DELETE and a TRUNCATE with `consent_grants is append-only`", async () => {
+      await insertGrant();
+      await expect(
+        db.query(`UPDATE "consent_grants" SET "granted" = NOT "granted"`),
+      ).rejects.toThrow(/consent_grants is append-only/);
+      await expect(db.query(`DELETE FROM "consent_grants"`)).rejects.toThrow(
+        /consent_grants is append-only/,
+      );
+      await expect(db.query(`TRUNCATE "consent_grants"`)).rejects.toThrow(
+        /consent_grants is append-only/,
+      );
+    });
+
+    it("refuses a new row with source 'magnet' and no policy_version", async () => {
+      await expect(
+        insertGrant({ source: "magnet", policyVersion: null }),
+      ).rejects.toThrow(/consent_grants_policy_version_present/);
+    });
+
+    it("refuses a source outside the vocabulary and a zero policy_version", async () => {
+      await expect(insertGrant({ source: "telepathy" })).rejects.toThrow(
+        /consent_grants_source_known/,
+      );
+      await expect(insertGrant({ policyVersion: 0 })).rejects.toThrow(
+        /consent_grants_policy_version_positive/,
+      );
+    });
+
+    it("has no default source: a writer that forgets is refused", async () => {
+      await expect(insertGrant({ omitSource: true })).rejects.toThrow(
+        /null value in column "source"/,
+      );
+    });
+
+    it("lets a legacy row carry no policy_version, and reads it back as legacy", async () => {
+      const legacyPerson = id("person");
+      await insertGrant({
+        source: "legacy",
+        policyVersion: null,
+        personId: legacyPerson,
+      });
+      const read = await db.query(
+        `SELECT "source", "policy_version" FROM "consent_grants" WHERE "person_id" = $1`,
+        [legacyPerson],
+      );
+      expect(read.rows).toEqual([{ source: "legacy", policy_version: null }]);
+    });
+
+    it("refuses a person_id that is not a person id", async () => {
+      await expect(insertGrant({ personId: "someone" })).rejects.toThrow(
+        /consent_grants_person_id_format/,
+      );
+    });
+  });
+
+  describe("consent_visitor_links", () => {
+    it("accepts a link and ignores a repeat of it", async () => {
+      await insertLink();
+      const again = await db.query(
+        `INSERT INTO "consent_visitor_links" ("workspace_id", "visitor_id", "person_id", "source")
+         VALUES ($1, $2, $3, 'magnet') ON CONFLICT DO NOTHING`,
+        [WS, VISITOR, PERSON],
+      );
+      expect(again.rowCount).toBe(0);
+    });
+
+    it("refuses an UPDATE, a row DELETE and a TRUNCATE with `consent_visitor_links is append-only`", async () => {
+      await expect(
+        db.query(`UPDATE "consent_visitor_links" SET "source" = 'api'`),
+      ).rejects.toThrow(/consent_visitor_links is append-only/);
+      await expect(
+        db.query(`DELETE FROM "consent_visitor_links"`),
+      ).rejects.toThrow(/consent_visitor_links is append-only/);
+      await expect(
+        db.query(`TRUNCATE "consent_visitor_links"`),
+      ).rejects.toThrow(/consent_visitor_links is append-only/);
+    });
+
+    it("refuses a visitor id that is not a v4 UUID, a bad source and a bad person id", async () => {
+      await expect(
+        insertLink({ visitorId: "01920000-8168-7000-8000-0000000000b1" }),
+      ).rejects.toThrow(/consent_visitor_links_visitor_id_format/);
+      await expect(insertLink({ visitorId: "visitor-1" })).rejects.toThrow(
+        /consent_visitor_links_visitor_id_format/,
+      );
+      await expect(
+        insertLink({ visitorId: randomUUID(), source: "cookie_banner" }),
+      ).rejects.toThrow(/consent_visitor_links_source_known/);
+      await expect(
+        insertLink({ visitorId: randomUUID(), personId: "nobody" }),
+      ).rejects.toThrow(/consent_visitor_links_person_id_format/);
+    });
+
+    it("gives the table an id with the registered cvlink prefix", async () => {
+      const result = await insertLink({ visitorId: randomUUID() });
+      expect(result.rows[0].id).toMatch(/^cvlink_/);
+    });
+  });
+
+  describe("the store's own SQL against this database (SEC-8438-2 flood case)", () => {
+    /**
+     * Pull one `$queryRaw` template out of `apps/api/src/lib/consent-store.ts`
+     * and number its `${…}` holes, so the very SQL the API runs is what this
+     * suite runs: the readers cannot drift from what is proved here.
+     */
+    function storeSql(fn: string, nth = 0): { text: string; holes: string[] } {
+      const source = readFileSync(
+        join(__dirname, "../../apps/api/src/lib/consent-store.ts"),
+        "utf8",
+      );
+      const start = source.indexOf(`export async function ${fn}(`);
+      expect(start).toBeGreaterThan(-1);
+      let open = source.indexOf("$queryRaw", start);
+      for (let i = 0; i < nth; i += 1) open = source.indexOf("$queryRaw", open + 1);
+      const tick = source.indexOf("`", open);
+      const end = source.indexOf("`", tick + 1);
+      const holes: string[] = [];
+      const text = source
+        .slice(tick + 1, end)
+        .replace(/\$\{([^}]+)\}/g, (_match, expr: string) => {
+          let at = holes.indexOf(expr);
+          if (at === -1) {
+            holes.push(expr);
+            at = holes.length - 1;
+          }
+          return `$${at + 1}`;
+        });
+      return { text, holes };
+    }
+    function runStore(fn: string, values: Record<string, unknown>, nth = 0) {
+      const { text, holes } = storeSql(fn, nth);
+      return db.query(
+        text,
+        holes.map((hole) => values[hole]),
+      );
+    }
+
+    it("a Person's withdrawal survives 600 magnet grants and 600 linked-visitor cookie rows, and every row pages out once", async () => {
+      const ws = id("wksp");
+      const person = id("person");
+      const visitor = randomUUID();
+      const insertMany = (cols: {
+        n: number;
+        subjectType: string;
+        subjectId: string;
+        personId: string | null;
+        granted: boolean;
+        source: string;
+      }) =>
+        db.query(
+          `INSERT INTO "consent_grants"
+             ("site_id", "workspace_id", "subject_type", "subject_id", "purpose_id", "granted",
+              "locale", "statement", "statement_hash", "person_id", "source", "policy_version")
+           SELECT $1, $1, $2, $3, 'share_data', $4, 'en', 'Share usage data.', 'h', $5, $6, 1
+           FROM generate_series(1, $7::int)`,
+          [ws, cols.subjectType, cols.subjectId, cols.granted, cols.personId, cols.source, cols.n],
+        );
+
+      await insertMany({
+        n: 1,
+        subjectType: "person",
+        subjectId: person,
+        personId: person,
+        granted: false,
+        source: "account_settings",
+      });
+      await db.query(
+        `INSERT INTO "consent_visitor_links" ("workspace_id", "visitor_id", "person_id", "source")
+         VALUES ($1, $2, $3, 'magnet')`,
+        [ws, visitor, person],
+      );
+      await insertMany({
+        n: 600,
+        subjectType: "lead",
+        subjectId: "lead_1",
+        personId: person,
+        granted: true,
+        source: "magnet",
+      });
+      await insertMany({
+        n: 600,
+        subjectType: "visitor",
+        subjectId: visitor,
+        personId: null,
+        granted: true,
+        source: "cookie_banner",
+      });
+
+      // The OWN reading: still withdrawn.
+      const own = await runStore("ownConsentRows", { workspaceId: ws, personId: person });
+      expect(own.rows.map((r) => [r.purposeId, r.granted, r.source])).toEqual([
+        ["share_data", false, "account_settings"],
+      ]);
+
+      // The ANY-SOURCE reading: a flood row is newest, granted, and unverified.
+      const any = await runStore("anySourceConsentRows", { workspaceId: ws, personId: person });
+      expect(any.rows).toHaveLength(1);
+      expect(any.rows[0].granted).toBe(true);
+      expect(["magnet", "cookie_banner"]).toContain(any.rows[0].source);
+
+      // History: 1,201 rows, 500 a page, each exactly once.
+      const seen: string[] = [];
+      let cursor: string | null = null;
+      for (let pages = 0; pages < 5; pages += 1) {
+        const page = await runStore("personConsentHistory", {
+          workspaceId: ws,
+          personId: person,
+          cursorId: cursor,
+          "CONSENT_HISTORY_PAGE_SIZE + 1": 501,
+          // the page query is the function's second `$queryRaw`
+        }, 1);
+        const rows = page.rows.slice(0, 500);
+        seen.push(...rows.map((r) => r.id as string));
+        if (page.rows.length <= 500) break;
+        cursor = rows[rows.length - 1].id as string;
+      }
+      expect(seen).toHaveLength(1201);
+      expect(new Set(seen).size).toBe(1201);
+
+      // Another workspace's reading of the same Person sees nothing.
+      const elsewhere = await runStore("anySourceConsentRows", {
+        workspaceId: id("wksp"),
+        personId: person,
+      });
+      expect(elsewhere.rows).toHaveLength(0);
+    });
+  });
+});

package/templates/database/__tests__/fence-fan-out.db.test.ts

@@ -138,6 +138,8 @@ const TABLES: FenceTable[] = [
       "locale",
       "statement",
       "statement_hash",
+      "source",
+      "policy_version",
     ],
     vals: () => [
       "subscriber",
@@ -147,6 +149,8 @@ const TABLES: FenceTable[] = [
       "en",
       "I agree",
       `hash-${RUN}`,
+      "api",
+      1,
     ],
   },
   {
@@ -694,8 +698,8 @@ describeDb("the #6374 fence fan-out constraints (live DB)", () => {
       await db.query(
         `INSERT INTO "consent_grants"
            ("site_id", "workspace_id", "subject_type", "subject_id", "purpose_id",
-            "granted", "locale", "statement", "statement_hash")
-         VALUES ($1, $1, 'subscriber', $2, $3, true, 'en', 'I agree', $4)`,
+            "granted", "locale", "statement", "statement_hash", "source", "policy_version")
+         VALUES ($1, $1, 'subscriber', $2, $3, true, 'en', 'I agree', $4, 'api', 1)`,
         [workspaceCId, `cascade-${RUN}`, `purpose-${RUN}`, `hash-${RUN}`],
       );
 

package/templates/database/__tests__/fixtures/person-contact-backfill.json

@@ -0,0 +1,182 @@
+{
+  "_comment": "#8435 AC-3 — the contact backfill fixture. person-contact.db.test.ts seeds `input` into live Postgres, runs database/migrations/20261014121000_person_contact_backfill/migration.sql, and asserts the people rows equal `expected.people` and every subscriber and callback is stamped as `expected.stamps` says (a null stamp means the row stays NULL). Timestamps are UTC.",
+  "workspaces": {
+    "A": "wksp_01920000-8435-7000-8000-00000000000a",
+    "B": "wksp_01920000-8435-7000-8000-00000000000b"
+  },
+  "input": {
+    "people": [
+      {
+        "key": "pre",
+        "workspace": "A",
+        "email": "lead-person@example.com",
+        "name": "Pat Lead",
+        "user": null
+      },
+      {
+        "key": "linked",
+        "workspace": "A",
+        "email": "linked@example.com",
+        "name": null,
+        "user": "user_01920000-8435-7000-8000-0000000000e1"
+      }
+    ],
+    "subscribers": [
+      {
+        "key": "S1",
+        "workspace": "A",
+        "email": " Sub@Example.com ",
+        "createdAt": "2026-02-01T00:00:00.000Z"
+      },
+      {
+        "key": "S2",
+        "workspace": "A",
+        "email": "sub@example.com",
+        "createdAt": "2026-02-02T00:00:00.000Z"
+      },
+      {
+        "key": "S3",
+        "workspace": "B",
+        "email": "Sub@Example.com",
+        "createdAt": "2026-02-03T00:00:00.000Z"
+      },
+      {
+        "key": "S4",
+        "workspace": "A",
+        "email": "lead-person@example.com",
+        "createdAt": "2026-02-04T00:00:00.000Z"
+      },
+      {
+        "key": "S5",
+        "workspace": "A",
+        "email": "not an email",
+        "createdAt": "2026-02-05T00:00:00.000Z"
+      }
+    ],
+    "callbacks": [
+      {
+        "key": "C1",
+        "workspace": "A",
+        "name": "Cal",
+        "phone": "+1 415-555-0123",
+        "payload": { "email": "Both@Example.com" },
+        "buyerEmail": "other@example.com",
+        "createdAt": "2026-03-01T00:00:00.000Z"
+      },
+      {
+        "key": "C1b",
+        "workspace": "A",
+        "name": "Cal Again",
+        "phone": "+442071234567",
+        "payload": { "email": "both@example.com" },
+        "buyerEmail": null,
+        "createdAt": "2026-03-02T00:00:00.000Z"
+      },
+      {
+        "key": "C2",
+        "workspace": "A",
+        "name": "Bea",
+        "phone": "0207 123 4567",
+        "payload": {},
+        "buyerEmail": "Buyer@Example.com",
+        "createdAt": "2026-03-03T00:00:00.000Z"
+      },
+      {
+        "key": "C3",
+        "workspace": "A",
+        "name": "Nobody",
+        "phone": "+14155550000",
+        "payload": {},
+        "buyerEmail": null,
+        "createdAt": "2026-03-04T00:00:00.000Z"
+      },
+      {
+        "key": "C4",
+        "workspace": "A",
+        "name": "Bad Email",
+        "phone": "+14155550001",
+        "payload": { "email": "bad email" },
+        "buyerEmail": null,
+        "createdAt": "2026-03-05T00:00:00.000Z"
+      },
+      {
+        "key": "C5",
+        "workspace": "A",
+        "name": "Lin",
+        "phone": "+442079460000",
+        "payload": { "email": "linked@example.com" },
+        "buyerEmail": null,
+        "createdAt": "2026-03-06T00:00:00.000Z"
+      },
+      {
+        "key": "C6",
+        "workspace": "A",
+        "name": "Numeric",
+        "phone": "+14155550002",
+        "payload": { "email": 12345 },
+        "buyerEmail": "fallback@example.com",
+        "createdAt": "2026-03-07T00:00:00.000Z"
+      }
+    ]
+  },
+  "expected": {
+    "people": [
+      {
+        "workspace": "A",
+        "email": "both@example.com",
+        "name": "Cal",
+        "telephone": "+14155550123"
+      },
+      {
+        "workspace": "A",
+        "email": "buyer@example.com",
+        "name": "Bea",
+        "telephone": null
+      },
+      {
+        "workspace": "A",
+        "email": "fallback@example.com",
+        "name": "Numeric",
+        "telephone": "+14155550002"
+      },
+      {
+        "workspace": "A",
+        "email": "lead-person@example.com",
+        "name": "Pat Lead",
+        "telephone": null
+      },
+      {
+        "workspace": "A",
+        "email": "linked@example.com",
+        "name": null,
+        "telephone": null
+      },
+      {
+        "workspace": "A",
+        "email": "sub@example.com",
+        "name": null,
+        "telephone": null
+      },
+      {
+        "workspace": "B",
+        "email": "sub@example.com",
+        "name": null,
+        "telephone": null
+      }
+    ],
+    "stamps": {
+      "S1": { "workspace": "A", "email": "sub@example.com" },
+      "S2": { "workspace": "A", "email": "sub@example.com" },
+      "S3": { "workspace": "B", "email": "sub@example.com" },
+      "S4": { "workspace": "A", "email": "lead-person@example.com" },
+      "S5": null,
+      "C1": { "workspace": "A", "email": "both@example.com" },
+      "C1b": { "workspace": "A", "email": "both@example.com" },
+      "C2": { "workspace": "A", "email": "buyer@example.com" },
+      "C3": null,
+      "C4": null,
+      "C5": { "workspace": "A", "email": "linked@example.com" },
+      "C6": { "workspace": "A", "email": "fallback@example.com" }
+    }
+  }
+}

package/templates/database/__tests__/outbound-message-action.db.test.ts

@@ -0,0 +1,80 @@
+/**
+ * @file outbound-message-action.db.test.ts
+ *
+ * LIVE-DATABASE proof of the replaced `interactions_outbound_shape` CHECK
+ * (#8515, spec docs/specs/8515-standard-client-onboarding-diagnostic-and-spec.md
+ * D6; AC-4). Requires DATABASE_URL pointing at a Postgres with the migrations
+ * applied — the suite SKIPS when DATABASE_URL is unset, keeping the workspace
+ * Jest run DB-free (the repo convention; the `apps/api Route Tests (Postgres)`
+ * workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `member-contract.db.test.ts` does. An
+ * outbound `message` may carry exactly `{"action": "onboarding"}` and no other
+ * payload; a payload-free outbound row still lands, and the payload-by-kind
+ * rule for inbound rows is unchanged.
+ */
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+describeDb("the outbound message action (#8515 D6, AC-4, live DB)", () => {
+  let db: Client;
+  const WS = "wksp_01920000-8515-7000-8000-0000000000c1";
+  const USER = "user_01920000-8515-7000-8000-0000000000c1";
+  let person: string;
+
+  const cleanup = async () => {
+    await db.query(`DELETE FROM "interactions" WHERE "workspace_id" = $1`, [WS]);
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = $1`, [WS]);
+  };
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+    person = (
+      await db.query<{ id: string }>(
+        `INSERT INTO "people" ("workspace_id", "email", "updated_at") VALUES ($1, 'cleo@example.com', now()) RETURNING "id"`,
+        [WS],
+      )
+    ).rows[0]!.id;
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  const insert = (direction: string, kind: string, payload: unknown) =>
+    db.query<{ id: string }>(
+      `INSERT INTO "interactions" ("workspace_id", "person_id", "channel", "direction", "kind", "subject", "body", "payload", "created_by")
+       VALUES ($1, $2, 'member', $3, $4, 'Your onboarding questions', 'Please answer a few questions.', $5, $6) RETURNING "id"`,
+      [WS, person, direction, kind, payload === null ? null : JSON.stringify(payload), USER],
+    );
+
+  it("an outbound message carrying the onboarding action lands", async () => {
+    const row = await insert("outbound", "message", { action: "onboarding" });
+    expect(row.rows[0]!.id).toMatch(/^intx_/);
+  });
+
+  it("an outbound payload-free message still lands", async () => {
+    const row = await insert("outbound", "message", null);
+    expect(row.rows[0]!.id).toMatch(/^intx_/);
+  });
+
+  it.each([
+    ["another action", { action: "invoice" }],
+    ["a link", { link: "https://x.example" }],
+    ["the action with an extra key", { action: "onboarding", href: "https://x.example" }],
+  ])("an outbound message carrying %s fails interactions_outbound_shape", async (_label, payload) => {
+    await expect(insert("outbound", "message", payload)).rejects.toMatchObject({
+      constraint: "interactions_outbound_shape",
+    });
+  });
+
+  it("an inbound quote without a payload still fails interactions_payload_by_kind", async () => {
+    await expect(insert("inbound", "quote", null)).rejects.toMatchObject({
+      constraint: "interactions_payload_by_kind",
+    });
+  });
+});