create-ailk 0.19.0 → 0.20.0

package/templates/apps/api/src/__tests__/stripe-boot.test.ts

@@ -0,0 +1,132 @@
+// oss: false
+/**
+ * @file stripe-boot.test.ts
+ *
+ * The real `build()` admits apps/api's Stripe key at boot (#8450 D4): an
+ * unset `STRIPE_MODE` is today's sandbox-only boot, and only a restricted
+ * live key beside `STRIPE_MODE=live` on a production build boots live. Each
+ * case runs in its own module registry (`jest.isolateModulesAsync`), because
+ * admission is one-way per process. Live-shaped keys are composed at runtime
+ * from fragments, never written out.
+ *
+ * External boundaries are mocked exactly as `server.test.ts` mocks them.
+ */
+import type { FastifyInstance } from "fastify";
+
+jest.mock("@fastify/cors", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@fastify/rate-limit", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+type ServerModule = typeof import("../server");
+type StripeShim = typeof import("../lib/stripe");
+
+const restrictedLiveKey = ["rk", "live", ""].join("_") + "FixtureOnlyBoot";
+
+const ENV_KEYS = ["STRIPE_SECRET_KEY", "STRIPE_MODE", "VERCEL_ENV"] as const;
+type EnvKey = (typeof ENV_KEYS)[number];
+
+/** Boot `build()` in a fresh registry under `env`; hand `fn` the app (or the rejection) and the shim. */
+async function boot(
+  env: Partial<Record<EnvKey, string>>,
+  fn: (result: { app?: FastifyInstance; error?: unknown; shim: StripeShim }) => Promise<void>,
+): Promise<void> {
+  const saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+  try {
+    for (const k of ENV_KEYS) {
+      if (env[k] === undefined) delete process.env[k];
+      else process.env[k] = env[k];
+    }
+    await jest.isolateModulesAsync(async () => {
+      const { build } = require("../server") as ServerModule;
+      const shim = require("../lib/stripe") as StripeShim;
+      let app: FastifyInstance | undefined;
+      let error: unknown;
+      try {
+        app = await build();
+      } catch (err) {
+        error = err;
+      }
+      try {
+        await fn({ app, error, shim });
+      } finally {
+        await app?.close();
+      }
+    });
+  } finally {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  }
+}
+
+/** POST the checkout route `n` times from one IP; return the status codes. */
+async function postCheckout(app: FastifyInstance, n: number): Promise<number[]> {
+  const codes: number[] = [];
+  for (let i = 0; i < n; i += 1) {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      remoteAddress: "203.0.113.7",
+      payload: {},
+    });
+    codes.push(res.statusCode);
+  }
+  return codes;
+}
+
+describe("build() — Stripe key admission at boot (#8450 D4)", () => {
+  it("refuses a restricted live key when STRIPE_MODE is unset (unchanged by default)", async () => {
+    await boot({ STRIPE_SECRET_KEY: restrictedLiveKey, VERCEL_ENV: "production" }, async ({ app, error, shim }) => {
+      expect(app).toBeUndefined();
+      expect(error).toBeInstanceOf(shim.StripeConfigError);
+      expect((error as Error).message).toMatch(/sandbox only/);
+      expect(shim.stripeKeyMode()).toBe("test");
+    });
+  });
+
+  it("boots in test mode on a test key with STRIPE_MODE unset, with no checkout bucket", async () => {
+    await boot({ STRIPE_SECRET_KEY: "sk_test_boot_fixture" }, async ({ app, error, shim }) => {
+      expect(error).toBeUndefined();
+      expect(app).toBeDefined();
+      expect(shim.stripeKeyMode()).toBe("test");
+      // No commerce claim, so every POST is the gate's own answer — never a 429.
+      const codes = await postCheckout(app!, 12);
+      expect(codes).not.toContain(429);
+    });
+  });
+
+  it("boots live on a restricted live key beside STRIPE_MODE=live on a production build", async () => {
+    await boot(
+      { STRIPE_SECRET_KEY: restrictedLiveKey, STRIPE_MODE: "live", VERCEL_ENV: "production" },
+      async ({ app, error, shim }) => {
+        expect(error).toBeUndefined();
+        expect(app).toBeDefined();
+        expect(shim.stripeKeyMode()).toBe("live");
+        expect(() => shim.assertAdmittedStripeKey(restrictedLiveKey)).not.toThrow();
+      },
+    );
+  });
+
+  it("gives a live process's checkout routes their own per-IP bucket (§ 9 SEC-14)", async () => {
+    await boot(
+      { STRIPE_SECRET_KEY: restrictedLiveKey, STRIPE_MODE: "live", VERCEL_ENV: "production" },
+      async ({ app }) => {
+        const { __resetBuckets, DEFAULT_PER_IP_PER_MINUTE_STRICT } =
+          require("../middleware/rate-limit") as typeof import("../middleware/rate-limit");
+        __resetBuckets();
+        const codes = await postCheckout(app!, DEFAULT_PER_IP_PER_MINUTE_STRICT + 1);
+        expect(codes.slice(0, DEFAULT_PER_IP_PER_MINUTE_STRICT)).not.toContain(429);
+        expect(codes[DEFAULT_PER_IP_PER_MINUTE_STRICT]).toBe(429);
+      },
+    );
+  });
+});

package/templates/apps/api/src/bin/__tests__/rate-limit-probe.test.ts

@@ -0,0 +1,184 @@
+/**
+ * @file rate-limit-probe.test.ts
+ *
+ * Unit tests for `runRateLimitProbe` (#5040 AC-10), with a stubbed `fetch`
+ * and a no-op `sleep`. Each stub tracks per-identity call counts; the probe
+ * itself picks its TEST-NET-3 addresses at random, so the stubs key their
+ * behavior off "the first identity used" and "every other identity" rather
+ * than a literal address.
+ */
+import { runRateLimitProbe, type ProbeFetch } from "../../lib/rate-limit-probe.js";
+
+const ORIGIN = "https://example-deployment.vercel.app";
+const noopSleep = async () => undefined;
+
+function headerIdentity(init: { headers: Record<string, string> }): string {
+  return init.headers["x-forwarded-for"] ?? "unknown";
+}
+
+/** Limits every distinct identity independently to `limit` per window. */
+function perIdentityLimiter(limit: number): ProbeFetch {
+  const counts = new Map<string, number>();
+  return async (_url, init) => {
+    const id = headerIdentity(init);
+    const count = (counts.get(id) ?? 0) + 1;
+    counts.set(id, count);
+    return { status: count <= limit ? 200 : 429 };
+  };
+}
+
+/**
+ * Limits ONLY the first identity used; every other identity always
+ * succeeds (#5040 AC-10(d): "answers 200 to every burst request").
+ */
+function firstIdentityOnlyLimiter(limit: number): ProbeFetch {
+  let firstId: string | undefined;
+  const counts = new Map<string, number>();
+  return async (_url, init) => {
+    const id = headerIdentity(init);
+    if (firstId === undefined) firstId = id;
+    if (id !== firstId) return { status: 200 };
+    const count = (counts.get(id) ?? 0) + 1;
+    counts.set(id, count);
+    return { status: count <= limit ? 200 : 429 };
+  };
+}
+
+/**
+ * Limits the first identity and never lets ANY other identity through
+ * either (#5040 AC-10(f): "answers 429 to every burst request").
+ */
+function alwaysOverLimiter(limit: number): ProbeFetch {
+  let firstId: string | undefined;
+  const counts = new Map<string, number>();
+  return async (_url, init) => {
+    const id = headerIdentity(init);
+    if (firstId === undefined) firstId = id;
+    const count = (counts.get(id) ?? 0) + 1;
+    counts.set(id, count);
+    if (id === firstId) return { status: count <= limit ? 200 : 429 };
+    return { status: 429 };
+  };
+}
+
+describe("runRateLimitProbe (#5040 AC-10)", () => {
+  it("(a) a per-identity limiter gives xff: survives, burst: holds (10/30), exit 0", async () => {
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: perIdentityLimiter(10),
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(0);
+    expect(log).toHaveBeenCalledWith("xff: survives");
+    expect(log).toHaveBeenCalledWith("burst: holds (10/30)");
+  });
+
+  it("(b) a shared, header-blind identity gives xff: overwritten, sleeps exactly once with 62000, exit 0", async () => {
+    let count = 0;
+    const fetch: ProbeFetch = async () => {
+      count += 1;
+      return { status: count <= 10 ? 200 : 429 };
+    };
+    const sleep = jest.fn(async (ms: number) => {
+      // Simulate the real window rolling over once the probe waits it out.
+      void ms;
+      count = 0;
+    });
+
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch,
+      sleep,
+      log: jest.fn(),
+    });
+
+    expect(code).toBe(0);
+    expect(sleep).toHaveBeenCalledTimes(1);
+    expect(sleep).toHaveBeenCalledWith(62_000);
+  });
+
+  it("(c) a limiter that never answers 429 gives limiter: not-observed, exit 1", async () => {
+    const log = jest.fn();
+    const fetchAlways200: ProbeFetch = async () => ({ status: 200 });
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: fetchAlways200,
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(1);
+    expect(log).toHaveBeenCalledWith("limiter: not-observed");
+  });
+
+  it("(d) only the first identity is limited, every other answers 200: burst: exceeded (30/30), exit 1", async () => {
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: firstIdentityOnlyLimiter(10),
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(1);
+    expect(log).toHaveBeenCalledWith("xff: survives");
+    expect(log).toHaveBeenCalledWith("burst: exceeded (30/30)");
+  });
+
+  it("(e) --origin http://example.com is refused before any fetch call", async () => {
+    const fetch = jest.fn();
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: "http://example.com",
+      fetch,
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(2);
+    expect(fetch).not.toHaveBeenCalled();
+    expect(log).toHaveBeenCalledWith("probe: error invalid-origin");
+  });
+
+  it("(f) every burst request answers 429: burst: inconclusive (0/30), exit 1", async () => {
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: alwaysOverLimiter(10),
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(1);
+    expect(log).toHaveBeenCalledWith("burst: inconclusive (0/30)");
+  });
+
+  it("a loopback http origin is accepted", async () => {
+    const code = await runRateLimitProbe({
+      origin: "http://localhost:3002",
+      fetch: perIdentityLimiter(10),
+      sleep: noopSleep,
+      log: jest.fn(),
+    });
+    expect(code).toBe(0);
+  });
+
+  it("a network error during the burst answers probe: error <code>, exit 2", async () => {
+    const log = jest.fn();
+    let count = 0;
+    const fetch: ProbeFetch = async () => {
+      count += 1;
+      if (count <= 11) return { status: count <= 10 ? 200 : 429 };
+      if (count === 12) return { status: 200 }; // the xff probe (survives)
+      const err = new Error("boom") as Error & { code: string };
+      err.code = "ECONNRESET";
+      throw err;
+    };
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch,
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(2);
+    expect(log).toHaveBeenCalledWith("probe: error ECONNRESET");
+  });
+});

package/templates/apps/api/src/bin/rate-limit-probe.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/* istanbul ignore file -- CLI bootstrap; the logic it wraps
+   (runRateLimitProbe) is unit-tested directly in __tests__/rate-limit-probe.test.ts
+   — the abandon-sweep.ts / lib/abandon-email.ts split. */
+/**
+ * The live rate-limiter probe (#5040 D9, FR-7, AC-10).
+ *
+ * Dev:        `pnpm --filter @working-theory/api rate-limit:probe --origin <https origin>`
+ * Production: `node dist/bin/rate-limit-probe.js --origin <https origin>`
+ *
+ * Answers the two platform facts #5040 and #5111 need a live deployment for:
+ *
+ *   1. Does a client-chosen `x-forwarded-for` survive to the serverless
+ *      function, or does the edge overwrite it? (`xff: survives | overwritten`)
+ *   2. Does a concurrent burst against ONE identity stay within the
+ *      configured limit? (`burst: holds | exceeded | inconclusive`)
+ *
+ * It only ever calls `GET <origin>/v1/aeo/score/example` — a no-fetch,
+ * no-write read already behind the aeo scope's strict limiter (#5111) — and
+ * refuses an origin that is not `https:` or loopback `http:` before any
+ * network call.
+ */
+import { runRateLimitProbe } from "../lib/rate-limit-probe.js";
+
+function parseOrigin(argv: readonly string[]): string | undefined {
+  const index = argv.indexOf("--origin");
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+async function main(): Promise<number> {
+  const origin = parseOrigin(process.argv.slice(2));
+  if (!origin) {
+    console.log("probe: error missing --origin");
+    return 2;
+  }
+  return runRateLimitProbe({
+    origin,
+    fetch: (url, init) => globalThis.fetch(url, init),
+  });
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err: unknown) => {
+    // Belt-and-braces, as abandon-sweep.ts: runRateLimitProbe catches its own
+    // network/status errors, so this only stops a bare unhandled rejection.
+    console.log(
+      `probe: error ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exitCode = 2;
+  });

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -436,6 +436,10 @@ export const prisma = {
     createMany: jest.fn(),
     findMany: jest.fn(),
   },
+  // #8438 D2 — a banner visitor linked to a Person (insert-or-ignore).
+  consentVisitorLink: {
+    createMany: jest.fn(),
+  },
   // ── Inbox namespace (Appointment — #6085, brief H7) ──────────────────────
   // `updateMany` — the § D7(a) guarded write, one per family (lifecycle /
   // payment / no-show); `findFirst` — the disambiguating read on a zero-match
@@ -542,6 +546,10 @@ export const prisma = {
   // `$executeRaw` — the per-booking `pg_advisory_xact_lock` (#7532 D5),
   // taken inside `$transaction`. Suites on that path arm both.
   $executeRaw: jest.fn(),
+  // `$queryRaw` — the consent ledger's reads (lib/consent-store.ts, #8438 D4):
+  // `DISTINCT ON` current-state and keyset history cannot be a Prisma
+  // `findMany`. Suites on that path arm it with the rows to serve.
+  $queryRaw: jest.fn(),
   $connect: jest.fn(),
   $disconnect: jest.fn(),
 };

package/templates/apps/api/src/lib/__tests__/consent-ledger-double.ts

@@ -0,0 +1,237 @@
+/**
+ * @file consent-ledger-double.ts
+ * @description An in-memory model of the consent ledger for suites that run
+ * the REAL `services/consent.ts` and `lib/consent-store.ts` over the mocked
+ * Prisma client (`lib/__mocks__/prisma.ts`) — #8438.
+ *
+ * `armConsentLedger(prisma)` wires the mocked client so that:
+ *   - `$transaction(fn)` runs `fn` on the same client;
+ *   - `consentGrant.createMany` appends to the returned `ledger`;
+ *   - `consentVisitorLink.createMany` appends to `links` (skipping a repeat);
+ *   - `$queryRaw` answers the way the store's SQL would — newest row per
+ *     purpose for the own / any-source / platform readings, the visitor's
+ *     newest choice, and keyset history pages — by recognising each query's
+ *     SQL text.
+ *
+ * This proves the writers' and routes' decisions ("write only when the answer
+ * changes", "own rows only", "a cursor of another Person is invalid") against
+ * a model with the same semantics as the SQL. The SQL itself is proved
+ * against a real database in `database/__tests__/consent-ledger.db.test.ts`.
+ */
+
+export type LedgerRow = {
+  id: string;
+  workspaceId: string;
+  subjectType: string;
+  subjectId: string;
+  personId: string | null;
+  purposeId: string;
+  granted: boolean;
+  source: string;
+  sourceRef: string | null;
+  policyVersion: number | null;
+  locale: string;
+  statement: string;
+  createdAt: Date;
+};
+
+export type LinkRow = {
+  workspaceId: string;
+  visitorId: string;
+  personId: string;
+  source: string;
+};
+
+const OWN_SOURCES = ["sign_up", "account_settings", "email_unsubscribe"];
+
+type Mockable = {
+  mockImplementation: (fn: (...args: never[]) => unknown) => unknown;
+  mockResolvedValue: (v: unknown) => unknown;
+};
+
+interface ArmablePrisma {
+  $transaction: unknown;
+  $executeRaw: unknown;
+  $queryRaw: unknown;
+  consentGrant: { createMany: unknown };
+  consentVisitorLink: { createMany: unknown };
+}
+
+export interface ConsentLedgerDouble {
+  ledger: LedgerRow[];
+  links: LinkRow[];
+}
+
+let clock = 0;
+
+export function armConsentLedger(prisma: unknown): ConsentLedgerDouble {
+  const p = prisma as ArmablePrisma;
+  const double: ConsentLedgerDouble = { ledger: [], links: [] };
+  clock = 0;
+
+  (p.$transaction as Mockable).mockImplementation((async (
+    fn: (tx: unknown) => unknown,
+  ) => fn(prisma)) as never);
+  (p.$executeRaw as Mockable).mockResolvedValue(1);
+
+  (p.consentGrant.createMany as Mockable).mockImplementation(((args: {
+    data: Array<Omit<LedgerRow, "id" | "createdAt">>;
+  }) => {
+    for (const row of args.data) {
+      clock += 1;
+      double.ledger.push({
+        ...row,
+        id: `cnsnt_00000000-0000-7000-8000-${String(clock).padStart(12, "0")}`,
+        createdAt: new Date(Date.UTC(2026, 9, 12, 0, 0, clock)),
+      });
+    }
+    return Promise.resolve({ count: args.data.length });
+  }) as never);
+
+  (p.consentVisitorLink.createMany as Mockable).mockImplementation(((args: {
+    data: LinkRow[];
+  }) => {
+    let count = 0;
+    for (const row of args.data) {
+      const seen = double.links.some(
+        (l) =>
+          l.workspaceId === row.workspaceId &&
+          l.visitorId === row.visitorId &&
+          l.personId === row.personId,
+      );
+      if (!seen) {
+        double.links.push(row);
+        count += 1;
+      }
+    }
+    return Promise.resolve({ count });
+  }) as never);
+
+  (p.$queryRaw as Mockable).mockImplementation(((
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ) => {
+    const sql = strings.join("?");
+    const [workspaceId] = values as [string];
+
+    const linkedVisitors = (personId: string) =>
+      new Set(
+        double.links
+          .filter(
+            (l) => l.workspaceId === workspaceId && l.personId === personId,
+          )
+          .map((l) => l.visitorId),
+      );
+    const anySource = (personId: string) =>
+      double.ledger.filter(
+        (r) =>
+          r.workspaceId === workspaceId &&
+          (r.personId === personId ||
+            (r.subjectType === "visitor" &&
+              linkedVisitors(personId).has(r.subjectId))),
+      );
+    const newestPerPurpose = (rows: LedgerRow[]) => {
+      const byPurpose = new Map<string, LedgerRow>();
+      for (const row of rows) byPurpose.set(row.purposeId, row);
+      return [...byPurpose.values()];
+    };
+    const state = (r: LedgerRow) => ({
+      id: r.id,
+      purposeId: r.purposeId,
+      granted: r.granted,
+      at: r.createdAt,
+      source: r.source,
+      sourceRef: r.sourceRef,
+      policyVersion: r.policyVersion,
+    });
+
+    // The visitor's newest choice for one purpose (the cookie writer's dedupe).
+    if (
+      sql.includes(`"subject_type" = 'visitor'`) &&
+      sql.includes("LIMIT 1") &&
+      !sql.includes("person_id")
+    ) {
+      const [, visitorId, purposeId] = values as [string, string, string];
+      const rows = double.ledger.filter(
+        (r) =>
+          r.workspaceId === workspaceId &&
+          r.subjectType === "visitor" &&
+          r.subjectId === visitorId &&
+          r.purposeId === purposeId,
+      );
+      const last = rows[rows.length - 1];
+      return Promise.resolve(
+        last
+          ? [{ granted: last.granted, policyVersion: last.policyVersion }]
+          : [],
+      );
+    }
+    // The platform reading: subject `user`.
+    if (sql.includes(`"subject_type" = 'user'`)) {
+      const [, userId] = values as [string, string];
+      return Promise.resolve(
+        newestPerPurpose(
+          double.ledger.filter(
+            (r) =>
+              r.workspaceId === workspaceId &&
+              r.subjectType === "user" &&
+              r.subjectId === userId,
+          ),
+        ).map(state),
+      );
+    }
+    // A history cursor check: does this row id belong to this Person's scope?
+    if (sql.includes('SELECT g."id" FROM "consent_grants" g')) {
+      const [, cursor, personId] = values as [string, string, string];
+      return Promise.resolve(
+        anySource(personId)
+          .filter((r) => r.id === cursor)
+          .map((r) => ({ id: r.id })),
+      );
+    }
+    // A history page: newest first, keyset on (created_at, id).
+    if (
+      sql.includes('ORDER BY g."created_at" DESC, g."id" DESC') &&
+      sql.includes('g."locale"')
+    ) {
+      const personId = values[1] as string;
+      const cursor = values[values.length - 3] as string | null;
+      let rows = anySource(personId).slice().reverse();
+      if (cursor) {
+        const at = rows.findIndex((r) => r.id === cursor);
+        rows = rows.slice(at + 1);
+      }
+      const limit = values[values.length - 1] as number;
+      return Promise.resolve(
+        rows.slice(0, limit).map((r) => ({
+          ...state(r),
+          locale: r.locale,
+          statement: r.statement,
+          subjectType: r.subjectType,
+        })),
+      );
+    }
+    // The own reading (a Person's own-source rows).
+    if (sql.includes(`'sign_up', 'account_settings', 'email_unsubscribe'`)) {
+      const [, personId] = values as [string, string];
+      return Promise.resolve(
+        newestPerPurpose(
+          double.ledger.filter(
+            (r) =>
+              r.workspaceId === workspaceId &&
+              r.personId === personId &&
+              OWN_SOURCES.includes(r.source),
+          ),
+        ).map(state),
+      );
+    }
+    // The any-source reading.
+    if (sql.includes("consent_visitor_links")) {
+      const [, personId] = values as [string, string];
+      return Promise.resolve(newestPerPurpose(anySource(personId)).map(state));
+    }
+    return Promise.resolve([]);
+  }) as never);
+
+  return double;
+}