create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/routes/consent/__tests__/account.test.ts

@@ -0,0 +1,386 @@
+/**
+ * @file account.test.ts
+ * @description The sign-up agreements' evidence route and the account-level
+ * reading (#8765 D2, D5; AC-2, AC-3 and AC-4, route parts).
+ *
+ * External dependency boundaries mocked:
+ *   - @working-theory/database (via moduleNameMapper -> prisma-client.js mock;
+ *     prisma singleton via __mocks__/prisma.ts), driven by the in-memory
+ *     ledger double
+ *   - `resolveSiteWorkspaceId` — the seam to the deployment's site workspace
+ *
+ * The real `services/consent.ts` writer and `lib/consent-store.ts` reader run
+ * over the ledger double. The auth preHandler is replaced by a hook that sets
+ * the fields it sets (`userId`, `sessionTenant`, `hubSession`), so user `u1`'s
+ * cookie session, spoke `S1`'s hub credential for `u1` and a personal token
+ * are each one line.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+const mockResolveSiteWorkspaceId = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/site.js", () => ({
+  resolveSiteWorkspaceId: () => mockResolveSiteWorkspaceId(),
+}));
+
+import { createHash } from "node:crypto";
+
+import {
+  ACCOUNT_TERMS_STATEMENT,
+  SITE_CONSENT_CONFIG_DEFAULTS,
+  siteConsentConfigSchema,
+} from "@working-theory/validation";
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+import {
+  armConsentLedger,
+  type ConsentLedgerDouble,
+} from "../../../lib/__tests__/consent-ledger-double.js";
+import { prisma } from "../../../lib/prisma.js";
+import * as consentService from "../../../services/consent.js";
+import { consentAccountRoutes, consentSignUpRoute } from "../index.js";
+
+/** The deployment's own site workspace. */
+const W = "wksp_01920000-0000-7000-8000-0000000000a1";
+/** Spoke S1's own workspace — never where an account-level row is written. */
+const S1_WS = "wksp_01920000-0000-7000-8000-0000000000b1";
+const S1 = "spoke_01920000-0000-7000-8000-0000000000b1";
+const U1 = "user_01920000-0000-7000-8000-0000000000a1";
+
+const sha256 = (text: string) =>
+  createHash("sha256").update(text).digest("hex");
+
+type Caller = "cookie" | "hub" | "token" | "none";
+
+let double: ConsentLedgerDouble;
+let app: FastifyInstance;
+
+async function build(caller: Caller): Promise<FastifyInstance> {
+  const instance = Fastify();
+  instance.decorateRequest("userId", undefined);
+  instance.decorateRequest("sessionTenant", undefined);
+  instance.decorateRequest("hubSession", undefined);
+  instance.addHook("onRequest", async (request) => {
+    // eslint-disable-next-line no-restricted-syntax -- the test stands in for the auth preHandler, which assigns decorated fields the bare Fastify type does not declare
+    const c = request as unknown as Record<string, unknown>;
+    if (caller === "none") return;
+    c["userId"] = U1;
+    if (caller === "cookie") c["sessionTenant"] = { sessionRowId: "s" };
+    if (caller === "hub") c["hubSession"] = { spokeId: S1, workspaceId: S1_WS };
+  });
+  await instance.register(consentSignUpRoute);
+  await instance.register(consentAccountRoutes);
+  await instance.ready();
+  return instance;
+}
+
+/** The registry with `account_terms` moved to `version`, everything else the default. */
+function registryAt(version: number) {
+  return siteConsentConfigSchema.parse({
+    ...SITE_CONSENT_CONFIG_DEFAULTS,
+    purposes: SITE_CONSENT_CONFIG_DEFAULTS.purposes.map((p) =>
+      p.id === "account_terms" ? { ...p, policyVersion: version } : p,
+    ),
+  });
+}
+
+const getAccount = (query = "") =>
+  app.inject({ method: "GET", url: `/v1/consent/account${query}` });
+const postAccount = (payload: unknown) =>
+  app.inject({
+    method: "POST",
+    url: "/v1/consent/account",
+    payload: payload as object,
+  });
+
+beforeEach(() => {
+  jest.restoreAllMocks();
+  jest.clearAllMocks();
+  double = armConsentLedger(prisma);
+  mockResolveSiteWorkspaceId.mockResolvedValue(W);
+});
+
+afterEach(async () => {
+  await app?.close();
+});
+
+describe("GET /v1/consent/sign-up (D2)", () => {
+  const get = (query = "") =>
+    app.inject({ method: "GET", url: `/v1/consent/sign-up${query}` });
+
+  beforeEach(async () => {
+    app = await build("none");
+  });
+
+  it("answers anonymously with W and one account_terms entry at version 2, its statement and its sha256", async () => {
+    const res = await get();
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["cache-control"]).toBe("no-store");
+    expect(res.json()).toEqual({
+      ok: true,
+      data: {
+        workspaceId: W,
+        agreements: [
+          {
+            purposeId: "account_terms",
+            policyVersion: 2,
+            locale: "en",
+            statement: ACCOUNT_TERMS_STATEMENT,
+            statementHash: sha256(ACCOUNT_TERMS_STATEMENT),
+          },
+        ],
+      },
+    });
+  });
+
+  it("reads the default locale en, and records the locale the statement was read in", async () => {
+    const plain = (await get()).json().data.agreements[0];
+    const fr = (await get("?locale=fr")).json().data.agreements[0];
+    expect(plain.locale).toBe("en");
+    // The registry declares only English, so a French reader read English.
+    expect(fr).toEqual(plain);
+  });
+
+  it("is the evidence the writer stamps: the hash of the statement a grant records", async () => {
+    const evidence = (await get()).json().data.agreements[0];
+    await app.close();
+    app = await build("cookie");
+    await postAccount({ purposeIds: ["account_terms"] });
+    expect(double.ledger[0]?.statement).toBe(evidence.statement);
+    expect(
+      consentService.consentStatementHash(double.ledger[0]!.statement),
+    ).toBe(evidence.statementHash);
+  });
+
+  it("refuses a malformed query with 400 invalid_input", async () => {
+    for (const query of ["?locale=not_a_locale", "?workspaceId=x"]) {
+      const res = await get(query);
+      expect(res.statusCode).toBe(400);
+      expect(res.json().error.code).toBe("invalid_input");
+    }
+  });
+
+  it("answers 503 tenant_unresolved, uncached, when the site workspace does not resolve", async () => {
+    mockResolveSiteWorkspaceId.mockResolvedValue(null);
+    const res = await get();
+    expect(res.statusCode).toBe(503);
+    expect(res.json().error.code).toBe("tenant_unresolved");
+    expect(res.headers["cache-control"]).toBe("no-store");
+  });
+});
+
+describe("GET/POST /v1/consent/account (D5) — AC-2", () => {
+  it("asks a user with no user rows: complete false, one entry never accepted", async () => {
+    app = await build("cookie");
+    const res = await getAccount();
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data).toEqual({
+      complete: false,
+      agreements: [
+        {
+          id: "account_terms",
+          statement: ACCOUNT_TERMS_STATEMENT,
+          policyVersion: 2,
+          acceptedVersion: null,
+          acceptedAt: null,
+          current: false,
+        },
+      ],
+    });
+  });
+
+  it("POST writes one dated user row in W and answers complete; a second POST adds nothing", async () => {
+    app = await build("cookie");
+    const res = await postAccount({ purposeIds: ["account_terms"] });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.complete).toBe(true);
+    expect(double.ledger).toHaveLength(1);
+    expect(double.ledger[0]).toMatchObject({
+      workspaceId: W,
+      subjectType: "user",
+      subjectId: U1,
+      personId: null,
+      purposeId: "account_terms",
+      granted: true,
+      source: "account_settings",
+      sourceRef: null,
+      policyVersion: 2,
+      statement: ACCOUNT_TERMS_STATEMENT,
+    });
+    expect(double.ledger[0]?.createdAt).toBeInstanceOf(Date);
+    const [entry] = res.json().data.agreements;
+    expect(entry).toMatchObject({
+      acceptedVersion: 2,
+      acceptedAt: double.ledger[0]!.createdAt.toISOString(),
+      current: true,
+    });
+
+    const again = await postAccount({ purposeIds: ["account_terms"] });
+    expect(again.statusCode).toBe(200);
+    expect(again.json().data.complete).toBe(true);
+    expect(double.ledger).toHaveLength(1);
+  });
+
+  it("the same POST from S1's credential writes in W, with sourceRef spoke:S1", async () => {
+    app = await build("hub");
+    const res = await postAccount({ purposeIds: ["account_terms"] });
+    expect(res.statusCode).toBe(200);
+    expect(double.ledger).toHaveLength(1);
+    expect(double.ledger[0]).toMatchObject({
+      workspaceId: W,
+      subjectType: "user",
+      subjectId: U1,
+      sourceRef: `spoke:${S1}`,
+    });
+  });
+
+  it("refuses a purpose that is not a sign-up agreement with 404 purpose_unknown, writing nothing — even beside a valid one", async () => {
+    app = await build("cookie");
+    for (const purposeIds of [
+      ["service_terms"],
+      ["account_terms", "service_terms"],
+      ["nope"],
+    ]) {
+      const res = await postAccount({ purposeIds });
+      expect(res.statusCode).toBe(404);
+      expect(res.json().error.code).toBe("purpose_unknown");
+    }
+    expect(double.ledger).toHaveLength(0);
+  });
+
+  it("refuses a malformed body with 400 invalid_input", async () => {
+    app = await build("cookie");
+    for (const body of [
+      {},
+      { purposeIds: [] },
+      { purposeIds: ["account_terms"], userId: U1 },
+      { purposeIds: ["account_terms"], locale: "not_a_locale" },
+    ]) {
+      const res = await postAccount(body);
+      expect(res.statusCode).toBe(400);
+      expect(res.json().error.code).toBe("invalid_input");
+    }
+    expect(double.ledger).toHaveLength(0);
+  });
+
+  it("refuses a personal token and an anonymous caller with 401, before any read", async () => {
+    for (const caller of ["token", "none"] as const) {
+      app = await build(caller);
+      expect((await getAccount()).statusCode).toBe(401);
+      expect(
+        (await postAccount({ purposeIds: ["account_terms"] })).statusCode,
+      ).toBe(401);
+      await app.close();
+    }
+    app = await build("cookie");
+    expect(prisma.$queryRaw).not.toHaveBeenCalled();
+    expect(double.ledger).toHaveLength(0);
+  });
+
+  it("answers 503 tenant_unresolved when the site workspace does not resolve", async () => {
+    mockResolveSiteWorkspaceId.mockResolvedValue(null);
+    app = await build("cookie");
+    expect((await getAccount()).statusCode).toBe(503);
+    const res = await postAccount({ purposeIds: ["account_terms"] });
+    expect(res.statusCode).toBe(503);
+    expect(res.json().error.code).toBe("tenant_unresolved");
+    expect(double.ledger).toHaveLength(0);
+  });
+
+  it("reads a newest row that is not a grant as never accepted", async () => {
+    app = await build("cookie");
+    await postAccount({ purposeIds: ["account_terms"] });
+    double.ledger.push({
+      ...double.ledger[0]!,
+      id: "cnsnt_00000000-0000-7000-8000-0000000000f1",
+      granted: false,
+      createdAt: new Date(Date.UTC(2026, 9, 13)),
+    });
+    expect((await getAccount()).json().data.agreements[0]).toMatchObject({
+      acceptedVersion: null,
+      acceptedAt: null,
+      current: false,
+    });
+  });
+
+  it("logs { event, outcome } only", async () => {
+    app = await build("cookie");
+    const lines: unknown[] = [];
+    const capture = ((obj: unknown) => {
+      lines.push(obj);
+    }) as never;
+    jest.spyOn(app.log, "info").mockImplementation(capture);
+    jest.spyOn(app.log, "warn").mockImplementation(capture);
+    await postAccount({ purposeIds: ["account_terms"] });
+    await postAccount({ purposeIds: ["service_terms"] });
+    const ours = lines.filter(
+      (l) => typeof l === "object" && l !== null && "event" in l,
+    );
+    expect(ours).toEqual([
+      { event: "account-agreements", outcome: "saved" },
+      { event: "account-agreements", outcome: "purpose_unknown" },
+    ]);
+  });
+});
+
+describe("GET /v1/consent/account — AC-3 (route)", () => {
+  it("a grant at version 2 in W reads complete from S1's credential", async () => {
+    app = await build("cookie");
+    await postAccount({ purposeIds: ["account_terms"] });
+    await app.close();
+    app = await build("hub");
+    const res = await getAccount();
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.complete).toBe(true);
+    expect(res.json().data.agreements[0]).toMatchObject({
+      acceptedVersion: 2,
+      current: true,
+    });
+  });
+});
+
+describe("GET/POST /v1/consent/account — AC-4 (route)", () => {
+  it("a bump to version 3 asks again; accepting appends a row and keeps the old one unchanged", async () => {
+    app = await build("cookie");
+    await postAccount({ purposeIds: ["account_terms"] });
+    const before = structuredClone(double.ledger[0]);
+
+    jest
+      .spyOn(consentService, "consentConfigForSite")
+      .mockResolvedValue(registryAt(3));
+
+    const read = (await getAccount()).json().data;
+    expect(read.complete).toBe(false);
+    expect(read.agreements[0]).toMatchObject({
+      policyVersion: 3,
+      acceptedVersion: 2,
+      current: false,
+    });
+
+    const res = await postAccount({ purposeIds: ["account_terms"] });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.complete).toBe(true);
+    expect(double.ledger).toHaveLength(2);
+    expect(double.ledger[0]).toEqual(before);
+    expect(double.ledger[1]).toMatchObject({
+      subjectType: "user",
+      subjectId: U1,
+      policyVersion: 3,
+      granted: true,
+    });
+    // The append-only double offers no way to change a stored row: the
+    // ledger delegate is append and read only, so an update would throw.
+    for (const method of [
+      "update",
+      "updateMany",
+      "upsert",
+      "delete",
+      "deleteMany",
+    ]) {
+      expect(method in prisma.consentGrant).toBe(false);
+    }
+  });
+});

package/templates/apps/api/src/routes/consent/__tests__/sign-up-rate-limit.test.ts

@@ -0,0 +1,160 @@
+/**
+ * @file sign-up-rate-limit.test.ts
+ * @description #8805 — the sign-up agreements' evidence read is counted per
+ * site key, end to end: the real `build()`, the `signupevidence` scope's own
+ * limiter and the REAL `@fastify/rate-limit` global ceiling.
+ *
+ * Every sign-up reads `GET /v1/consent/sign-up` from the web's server, and
+ * every web instance behind one egress address used to share one per-IP
+ * bucket of 10 a minute — which an anonymous caller spoofing that address's
+ * `X-Forwarded-For` could fill. A request presenting a VALID site key (the
+ * `x-ailk-spoke-key` the web's api-client already sends) is now counted
+ * against that key's own bucket instead, in both limiters; an invalid or
+ * absent key keeps the per-IP 10.
+ *
+ * External dependency boundary mocked: `resolveCallerSite`, the registry
+ * lookup a key digests to (one key valid, every other refused), and
+ * `resolveSiteWorkspaceId`, the route's own workspace seam. `DATABASE_URL` is
+ * unset for the file's duration, so the limiter counts in the memory store.
+ */
+
+const mockResolveCallerSite = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted; the registry lookup is the database boundary
+jest.mock("../../../services/public-site-resolver.js", () => ({
+  ...jest.requireActual<object>("../../../services/public-site-resolver.js"),
+  resolveCallerSite: (...args: unknown[]) => mockResolveCallerSite(...args),
+}));
+
+const mockResolveSiteWorkspaceId = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/site.js", () => ({
+  ...jest.requireActual<object>("../../../lib/site.js"),
+  resolveSiteWorkspaceId: () => mockResolveSiteWorkspaceId(),
+}));
+
+jest.mock("@fastify/cors", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+import type { FastifyRequest } from "fastify";
+
+import { __resetBuckets } from "../../../middleware/rate-limit";
+import { build } from "../../../server";
+
+/** The deployment's own site workspace. */
+const W = "wksp_01920000-0000-7000-8000-0000000000a1";
+/** The spoke's own workspace — never the evidence route's answer. */
+const SPOKE_WS = "wksp_01920000-0000-7000-8000-0000000000b1";
+const SPOKE_ID = "spoke_01920000-0000-7000-8000-0000000000b1";
+const VALID = "ailk_spk_valid-site-key";
+const WEB_EGRESS = "198.51.100.20";
+
+describe("GET /v1/consent/sign-up against the real limiters (#8805)", () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any matches server.test.ts
+  let app: any;
+  const prior = {
+    databaseUrl: process.env.DATABASE_URL,
+    perKey: process.env.AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE,
+  };
+
+  async function statuses(
+    count: number,
+    headers: Record<string, string>,
+  ): Promise<number[]> {
+    const codes: number[] = [];
+    for (let i = 0; i < count; i++) {
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/consent/sign-up",
+        headers,
+      });
+      codes.push(res.statusCode);
+    }
+    return codes;
+  }
+
+  const keyed = (key: string = VALID) => ({
+    "x-forwarded-for": WEB_EGRESS,
+    "x-ailk-spoke-key": key,
+  });
+
+  beforeEach(async () => {
+    __resetBuckets();
+    delete process.env.DATABASE_URL;
+    delete process.env.AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE;
+    mockResolveSiteWorkspaceId.mockResolvedValue(W);
+    mockResolveCallerSite.mockImplementation((req: FastifyRequest) =>
+      Promise.resolve(
+        req.headers["x-ailk-spoke-key"] === VALID
+          ? { kind: "spoke", spokeId: SPOKE_ID, workspaceId: SPOKE_WS }
+          : { kind: "refused", reason: "key-unknown" },
+      ),
+    );
+    app = await build();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+    app = undefined;
+  });
+
+  afterAll(() => {
+    for (const [name, value] of [
+      ["DATABASE_URL", prior.databaseUrl],
+      ["AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE", prior.perKey],
+    ] as const) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  it("admits keyed requests from one IP past 10 a minute — and past the global 60 — up to the key ceiling of 120", async () => {
+    const codes = await statuses(121, keyed());
+    expect(codes.slice(0, 120).every((code) => code !== 429)).toBe(true);
+    expect(codes[120]).toBe(429);
+  });
+
+  it("refuses the eleventh keyless request from one IP with 429", async () => {
+    const codes = await statuses(11, { "x-forwarded-for": WEB_EGRESS });
+    expect(codes.slice(0, 10).every((code) => code !== 429)).toBe(true);
+    expect(codes[10]).toBe(429);
+  });
+
+  it("refuses the eleventh request with an invalid key from one IP with 429", async () => {
+    const codes = await statuses(11, keyed("ailk_spk_forged"));
+    expect(codes.slice(0, 10).every((code) => code !== 429)).toBe(true);
+    expect(codes[10]).toBe(429);
+  });
+
+  it("a spoofer filling the web egress address's buckets leaves the keyed caller its budget", async () => {
+    const spoofed = await statuses(70, { "x-forwarded-for": WEB_EGRESS });
+    expect(spoofed[69]).toBe(429);
+    const codes = await statuses(20, keyed());
+    expect(codes.every((code) => code !== 429)).toBe(true);
+  });
+
+  it("reads AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE over the default", async () => {
+    await app.close();
+    process.env.AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE = "15";
+    app = await build();
+    await app.ready();
+    const codes = await statuses(16, keyed());
+    expect(codes.slice(0, 15).every((code) => code !== 429)).toBe(true);
+    expect(codes[15]).toBe(429);
+  });
+
+  it("answers a keyed request with the site workspace, never the key's", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/consent/sign-up",
+      headers: keyed(),
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.workspaceId).toBe(W);
+  });
+});