create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/middleware/__tests__/auth.hub-session-path.test.ts

@@ -53,7 +53,11 @@ let spokeA: SeededSpoke;
 let spokeB: SeededSpoke;
 let handlerRuns: string[];
 
-/** D1's 18 strings plus #8435's two contact routes and #8438's two consents routes (22), in the list's order. */
+/**
+ * D1's 18 strings plus #8435's two contact routes, #8438's two consents
+ * routes, #8765's account-agreements pair and #8515's onboarding pair (26),
+ * in the list's order.
+ */
 const ADMITTED = [
   "GET /v1/hub-sign-in/me",
   "GET /v1/member/pieces",
@@ -77,6 +81,9 @@ const ADMITTED = [
   "POST /v1/member/deletion-request",
   "GET /v1/member/consents",
   "POST /v1/member/consents",
+  // #8765 D5 — the caller's account-level sign-up agreements.
+  "GET /v1/consent/account",
+  "POST /v1/consent/account",
   // #8515 D13 — the client's onboarding read and write.
   "GET /v1/member/onboarding",
   "POST /v1/member/onboarding",
@@ -86,6 +93,8 @@ const ADMITTED = [
 const OFF_LIST = [
   "GET /v1/consent/platform",
   "POST /v1/consent/platform",
+  // #8765 D2 — the anonymous sign-up evidence is never a credential's route.
+  "GET /v1/consent/sign-up",
   "GET /v1/member/other",
   "GET /v1/member/messages/:id",
   "GET /v1/waitlist-signups/me",
@@ -177,9 +186,9 @@ afterEach(async () => {
 });
 
 describe("HUB_SESSION_ROUTES", () => {
-  it("is exactly the 24 entries, by method and registered URL — never a prefix (AC-1, #8515 AC-6)", () => {
+  it("is exactly the 26 entries, by method and registered URL — never a prefix (AC-1, #8515 AC-6, #8765 AC-6)", () => {
     expect([...HUB_SESSION_ROUTES]).toEqual(ADMITTED);
-    expect(HUB_SESSION_ROUTES.length).toBe(24);
+    expect(HUB_SESSION_ROUTES.length).toBe(26);
     for (const route of HUB_SESSION_ROUTES) {
       expect({
         route,
@@ -222,6 +231,8 @@ describe("hub credential — admitted routes", () => {
 
 describe("hub credential — every other route is 404 with no handler run (AC-7)", () => {
   it.each([
+    ["GET", "/v1/consent/sign-up"],
+    ["GET", "/v1/consent/platform"],
     ["GET", "/v1/member/other"],
     ["GET", "/v1/member/messages/lead_1"],
     ["GET", "/v1/waitlist-signups/me"],

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

@@ -22,6 +22,9 @@ import {
   buildTrustedKeyDigests,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
   resolveRateLimitIdentity,
+  siteKeyReader,
+  SITE_KEYED_ROUTES,
+  DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE,
   type RateLimitOptions,
 } from "../rate-limit.js";
 
@@ -845,6 +848,7 @@ describe("per-visitor forwarding, scope namespace and per-scope env limit (#7394
         { method: "POST", url: "/v1/project-listings" },
         { method: "PATCH", url: "/v1/project-listings/drafts/:id" },
         { method: "POST", url: "/v1/project-listings/drafts/:id/submit" },
+        { method: "GET", url: "/v1/deliverables/open/:slug" },
       ]);
     });
   });
@@ -1189,3 +1193,217 @@ describe("per-visitor forwarding, scope namespace and per-scope env limit (#7394
     });
   });
 });
+
+describe("the sign-up evidence read is counted per site key (#8805)", () => {
+  const SIGN_UP = "/v1/consent/sign-up";
+  const WEB_EGRESS = "198.51.100.20";
+  const VALID = "ailk_spk_valid-site-key";
+  const SPOKE_ID = "spoke_01920000-0000-7000-8000-0000000000b1";
+  const ENV_KEYS = [
+    "AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_MINUTE",
+    "AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE",
+  ] as const;
+  const priorEnv = new Map<string, string | undefined>(
+    ENV_KEYS.map((name) => [name, process.env[name]]),
+  );
+
+  let app: FastifyInstance | undefined;
+  let verify: jest.Mock<Promise<string | null>, [unknown]>;
+  let logLines: Array<Record<string, unknown>>;
+
+  function signUpApp(opts: Partial<RateLimitOptions> = {}): FastifyInstance {
+    const instance = Fastify({
+      trustProxy: true,
+      logger: {
+        level: "warn",
+        stream: {
+          write(msg: string) {
+            logLines.push(JSON.parse(msg) as Record<string, unknown>);
+          },
+        },
+      },
+    });
+    instance.register(rateLimitMiddleware, {
+      perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
+      perKeyPerMinute: 25,
+      scope: "signupevidence",
+      siteKeyOf: siteKeyReader(verify),
+      ...opts,
+    });
+    instance.get(SIGN_UP, async () => ({ ok: true }));
+    instance.get("/v1/other", async () => ({ ok: true }));
+    return instance;
+  }
+
+  async function statuses(
+    count: number,
+    headers: Record<string, string>,
+    url: string = SIGN_UP,
+  ): Promise<number[]> {
+    if (!app) throw new Error("no app");
+    const codes: number[] = [];
+    for (let i = 0; i < count; i++) {
+      const res = await app.inject({ method: "GET", url, headers });
+      codes.push(res.statusCode);
+    }
+    return codes;
+  }
+
+  const keyed = (ip: string = WEB_EGRESS, key: string = VALID) => ({
+    "x-forwarded-for": ip,
+    "x-ailk-spoke-key": key,
+  });
+
+  beforeEach(() => {
+    __resetBuckets();
+    logLines = [];
+    for (const name of ENV_KEYS) delete process.env[name];
+    verify = jest.fn((req: unknown) => {
+      const headers = (req as { headers: Record<string, unknown> }).headers;
+      return Promise.resolve(
+        headers["x-ailk-spoke-key"] === VALID ? SPOKE_ID : null,
+      );
+    });
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+    app = undefined;
+  });
+
+  afterAll(() => {
+    for (const [name, value] of priorEnv) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  it("lists GET /v1/consent/sign-up as the one site-keyed route", () => {
+    expect(SITE_KEYED_ROUTES).toEqual([{ method: "GET", url: SIGN_UP }]);
+  });
+
+  it("names a per-key default well above the per-IP 10", () => {
+    expect(DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE).toBe(120);
+  });
+
+  it("admits keyed requests from one IP past 10 a minute, up to the key ceiling, then 429", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(26, keyed());
+    expect(codes.slice(0, 25).every((code) => code === 200)).toBe(true);
+    expect(codes[25]).toBe(429);
+  });
+
+  it("refuses the eleventh keyless request from one IP with 429", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, { "x-forwarded-for": WEB_EGRESS });
+    expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+    expect(codes[10]).toBe(429);
+    expect(verify).not.toHaveBeenCalled();
+  });
+
+  it("keeps an invalid key on the per-IP 10 a minute", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, keyed(WEB_EGRESS, "ailk_spk_forged"));
+    expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+    expect(codes[10]).toBe(429);
+  });
+
+  it("an anonymous caller spoofing the web's X-Forwarded-For cannot spend the keyed budget", async () => {
+    app = signUpApp();
+    await app.ready();
+    // The spoofer fills the per-IP bucket of the web's own egress address…
+    const spoofed = await statuses(30, { "x-forwarded-for": WEB_EGRESS });
+    expect(spoofed[10]).toBe(429);
+    // …and with a forged key too.
+    await statuses(30, keyed(WEB_EGRESS, "ailk_spk_forged"));
+    // The keyed caller behind that address still has its whole budget.
+    const codes = await statuses(25, keyed());
+    expect(codes.every((code) => code === 200)).toBe(true);
+  });
+
+  it("many web instances behind one egress share the key bucket, not an IP bucket", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes: number[] = [];
+    for (let i = 0; i < 26; i++) {
+      codes.push(...(await statuses(1, keyed(`203.0.113.${i + 1}`))));
+    }
+    expect(codes.slice(0, 25).every((code) => code === 200)).toBe(true);
+    expect(codes[25]).toBe(429);
+  });
+
+  it("a verification failure counts the request per IP, never unlimited", async () => {
+    verify.mockRejectedValue(new Error("db down: postgres://secret"));
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, keyed());
+    expect(codes[10]).toBe(429);
+    const line = logLines.find(
+      (l) => l["event"] === "rate_limit_site_key_unverified",
+    );
+    expect(line).toBeDefined();
+    expect(JSON.stringify(logLines)).not.toContain("postgres://secret");
+    expect(JSON.stringify(logLines)).not.toContain(VALID);
+  });
+
+  it("a lookup that outlasts its timeout counts the request per IP", async () => {
+    verify.mockImplementation(() => new Promise<string | null>(() => undefined));
+    app = signUpApp({ siteKeyOf: siteKeyReader(verify, 5) });
+    await app.ready();
+    const codes = await statuses(11, keyed());
+    expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+    expect(codes[10]).toBe(429);
+    expect(
+      logLines.some((l) => l["event"] === "rate_limit_site_key_unverified"),
+    ).toBe(true);
+  });
+
+  it("ignores a key on any route but the sign-up evidence read", async () => {
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(11, keyed(), "/v1/other");
+    expect(codes[10]).toBe(429);
+    expect(verify).not.toHaveBeenCalled();
+  });
+
+  it("verifies the key once per request, however many limiters read it", async () => {
+    const reader = siteKeyReader(verify);
+    app = signUpApp({ siteKeyOf: reader });
+    // A second reader of the same request, as the server-wide limiter is.
+    app.addHook("onRequest", async (req) => {
+      await reader(req);
+    });
+    await app.ready();
+    await statuses(3, keyed());
+    expect(verify).toHaveBeenCalledTimes(3);
+  });
+
+  it("reads AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE over the code value", async () => {
+    process.env.AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE = "12";
+    app = signUpApp();
+    await app.ready();
+    const codes = await statuses(13, keyed());
+    expect(codes.slice(0, 12).every((code) => code === 200)).toBe(true);
+    expect(codes[12]).toBe(429);
+  });
+
+  it("logs a keyed 429 with bucket site and the spoke id, never the key", async () => {
+    app = signUpApp({ perKeyPerMinute: 1 });
+    await app.ready();
+    await statuses(2, keyed());
+    const line = logLines.find((l) => l["msg"] === "rate_limited");
+    expect(line).toMatchObject({
+      ip: `site,${SPOKE_ID}`,
+      bucket: "site",
+    });
+    expect(JSON.stringify(logLines)).not.toContain(VALID);
+  });
+
+  it("rejects siteKeyOf without a scope", async () => {
+    app = signUpApp({ scope: undefined });
+    await expect(app.ready()).rejects.toThrow(/scope/);
+  });
+});

package/templates/apps/api/src/middleware/__tests__/write-budget.test.ts

@@ -0,0 +1,174 @@
+/**
+ * @file write-budget.test.ts
+ * @description The Stripe connection write budget (#8907 D9, AC-12; contract
+ * K10) — `chargeWriteBudget` in middleware/rate-limit.ts.
+ *
+ * It counts every write against an hourly per-Organization and per-person
+ * bucket in its OWN database store — never the process default — so neither
+ * `AILK_RATE_LIMIT_STORE=memory` nor the per-minute sweep of the shared maps
+ * can reset an hourly bucket (SEC-8907-2). A store that rejects falls back to
+ * a module-private count the sweep never touches, capped at `MAX_BUCKETS`.
+ */
+import Fastify from "fastify";
+
+import type { RateLimitBucket, RateLimitStore } from "../../lib/rate-limit-store.js";
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary; the budget's store is replaced below, so no client is ever built.
+jest.mock("../../lib/prisma.js", () => ({ prisma: {} }));
+
+const mockCreateDatabaseStore = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the database store's constructor is the seam the case under test is about: the budget must build its own database store whatever AILK_RATE_LIMIT_STORE says
+jest.mock("../../lib/rate-limit-store.js", () => ({
+  ...jest.requireActual("../../lib/rate-limit-store.js"),
+  createDatabaseRateLimitStore: (...args: unknown[]) => mockCreateDatabaseStore(...args),
+}));
+
+import {
+  __bucketCount,
+  __resetBuckets,
+  __setWriteBudgetStoreForTests,
+  __writeBudgetFallbackCount,
+  chargeWriteBudget,
+  MAX_BUCKETS,
+  rateLimitMiddleware,
+  STRIPE_CONNECTION_WRITES_PER_ORG_PER_HOUR,
+  STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR,
+} from "../rate-limit.js";
+
+const HOUR = 60 * 60 * 1000;
+const T0 = 1_800_000_000_000;
+
+/** A `hitKey` that counts per key and window, as the database store's upsert does. */
+function countingStore(): RateLimitStore & { hitKey: jest.Mock; keys: Map<string, RateLimitBucket> } {
+  const keys = new Map<string, RateLimitBucket>();
+  const hitKey = jest.fn(async (key: string, now: number, windowMs: number) => {
+    let bucket = keys.get(key);
+    if (!bucket || now - bucket.windowStartMs >= windowMs) {
+      bucket = { count: 0, windowStartMs: now };
+      keys.set(key, bucket);
+    }
+    bucket.count += 1;
+    return { ...bucket };
+  });
+  return {
+    keys,
+    hitKey,
+    hit: jest.fn(),
+    hasOpenWindow: jest.fn(),
+    sweep: jest.fn(),
+  };
+}
+
+function rejectingStore(): RateLimitStore {
+  return {
+    hitKey: jest.fn().mockRejectedValue(new Error("db down")),
+    hit: jest.fn(),
+    hasOpenWindow: jest.fn(),
+    sweep: jest.fn(),
+  };
+}
+
+const charge = (key: string, now: number, limit = STRIPE_CONNECTION_WRITES_PER_ORG_PER_HOUR) =>
+  chargeWriteBudget({ scope: "stripeconn", charges: [{ key, limit }], windowMs: HOUR, now });
+
+beforeEach(() => {
+  __resetBuckets();
+  mockCreateDatabaseStore.mockReset();
+});
+
+afterAll(() => __setWriteBudgetStoreForTests(undefined));
+
+describe("chargeWriteBudget (#8907 D9)", () => {
+  it("answers ok ten times for one Organization, refuses the eleventh, and opens again an hour later", async () => {
+    __setWriteBudgetStoreForTests(countingStore());
+    for (let i = 0; i < 10; i++) {
+      expect(await charge("org,org_a", T0 + i * 1000)).toEqual({ ok: true });
+    }
+    const refused = await charge("org,org_a", T0 + 10_000);
+    expect(refused.ok).toBe(false);
+    if (refused.ok) throw new Error("expected a refusal");
+    expect(refused.retryAfterSeconds).toBeGreaterThanOrEqual(1);
+    expect(refused.retryAfterSeconds).toBeLessThanOrEqual(3600);
+    expect(await charge("org,org_a", T0 + HOUR)).toEqual({ ok: true });
+  });
+
+  it("counts a person's key independently, at its own limit", async () => {
+    __setWriteBudgetStoreForTests(countingStore());
+    for (let i = 0; i < 11; i++) await charge("org,org_a", T0 + i);
+    for (let i = 0; i < STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR; i++) {
+      expect(await charge("user,user_a", T0 + i, STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR)).toEqual({
+        ok: true,
+      });
+    }
+    expect((await charge("user,user_a", T0 + 30, STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR)).ok).toBe(
+      false,
+    );
+  });
+
+  it("refuses when any charge is over, and counts every charge every time", async () => {
+    const store = countingStore();
+    __setWriteBudgetStoreForTests(store);
+    const both = (now: number) =>
+      chargeWriteBudget({
+        scope: "stripeconn",
+        charges: [
+          { key: "org,org_a", limit: 10 },
+          { key: "user,user_a", limit: 20 },
+        ],
+        windowMs: HOUR,
+        now,
+      });
+    for (let i = 0; i < 10; i++) expect((await both(T0 + i)).ok).toBe(true);
+    expect((await both(T0 + 10)).ok).toBe(false);
+    expect(store.keys.get("writebudget:stripeconn|org,org_a")?.count).toBe(11);
+    expect(store.keys.get("writebudget:stripeconn|user,user_a")?.count).toBe(11);
+  });
+
+  it("is not reset by the middleware's per-minute sweep of its shared maps", async () => {
+    // A rejecting store sends every count to the fallback, the one state a
+    // shared-map sweep could reach if the budget lived there.
+    __setWriteBudgetStoreForTests(rejectingStore());
+    const past = Date.now() - 30 * 60 * 1000;
+    for (let i = 0; i < 10; i++) expect((await charge("org,org_b", past)).ok).toBe(true);
+
+    const app = Fastify();
+    await app.register(rateLimitMiddleware, { windowMs: 60_000, perIpPerMinute: 1_000 });
+    app.get("/ping", async () => ({ ok: true }));
+    await app.ready();
+    // 101 requests reach the interval sweep (`evictStaleBuckets`) at least once.
+    for (let i = 0; i < 101; i++) await app.inject({ method: "GET", url: "/ping" });
+    await app.close();
+
+    expect((await charge("org,org_b", past)).ok).toBe(false);
+  });
+
+  it("falls back to a private count capped at MAX_BUCKETS when the store rejects", async () => {
+    __setWriteBudgetStoreForTests(rejectingStore());
+    for (let i = 0; i < MAX_BUCKETS + 5; i++) await charge(`org,org_${i}`, T0);
+    expect(__writeBudgetFallbackCount()).toBe(MAX_BUCKETS);
+    // The newest entry survived the cap, the oldest did not.
+    for (let i = 0; i < 10; i++) await charge(`org,org_${MAX_BUCKETS + 4}`, T0);
+    expect((await charge(`org,org_${MAX_BUCKETS + 4}`, T0)).ok).toBe(false);
+    expect((await charge("org,org_0", T0)).ok).toBe(true);
+  });
+
+  it("uses its own database store even with AILK_RATE_LIMIT_STORE=memory, and never the shared maps", async () => {
+    const before = { DATABASE_URL: process.env.DATABASE_URL, STORE: process.env.AILK_RATE_LIMIT_STORE };
+    process.env.DATABASE_URL = "postgres://budget.invalid/db";
+    process.env.AILK_RATE_LIMIT_STORE = "memory";
+    try {
+      const store = countingStore();
+      mockCreateDatabaseStore.mockReturnValue(store);
+      __setWriteBudgetStoreForTests(undefined);
+      expect((await charge("org,org_c", T0)).ok).toBe(true);
+      expect(mockCreateDatabaseStore).toHaveBeenCalledTimes(1);
+      expect(store.hitKey).toHaveBeenCalledWith("writebudget:stripeconn|org,org_c", T0, HOUR);
+      expect(__bucketCount()).toBe(0);
+    } finally {
+      process.env.DATABASE_URL = before.DATABASE_URL;
+      process.env.AILK_RATE_LIMIT_STORE = before.STORE;
+      if (before.DATABASE_URL === undefined) delete process.env.DATABASE_URL;
+      if (before.STORE === undefined) delete process.env.AILK_RATE_LIMIT_STORE;
+    }
+  });
+});

package/templates/apps/api/src/middleware/auth.ts

@@ -34,9 +34,10 @@
  *      spoke's key (`x-ailk-spoke-key`), only while its grant is unrevoked and
  *      unexpired, its client enabled and its person's email verified, and only
  *      on `HUB_SESSION_ROUTES` — an exact list of METHOD + registered URL
- *      pairs — the credential's own `me` and the member routes, 24 in all
- *      (#8220, #8515); any other route is 404 (never 403, so the account area's
- *      `read()` loads "nothing for this caller"). It acts as its person
+ *      pairs — the credential's own `me`, the member routes and the
+ *      account-agreements pair, 26 in all (#8220, #8515, #8765); any other
+ *      route is 404 (never 403, so the account area's `read()` loads
+ *      "nothing for this caller"). It acts as its person
  *      (`request.userId`) and carries `request.hubSession` — never
  *      `request.sessionTenant` — and its request logger names the spoke
  *      (`spokeId`). Each person is limited, at each spoke, to 60 requests and
@@ -153,12 +154,14 @@ export type HubSession = {
  * The only routes a hub-issued credential reaches (#7894 D6, #8220 D1): an
  * EXACT list of method + registered URL, never a prefix and never computed,
  * so a route added later joins only by a reviewed edit of this list
- * (SEC-7894-3). Five groups, in this order: the credential's own `me` and
+ * (SEC-7894-3). Six groups, in this order: the credential's own `me` and
  * #7877's three member reads; #8169's eight member reads; #8170's six member
  * writes (roadmap §7.2 row order); #8438's member consents read and write;
- * #8515's onboarding read and write — 24 in all.
+ * #8765's account-agreements read and write; #8515's onboarding read and
+ * write — 26 in all.
  * `GET /v1/consent/platform` is not admitted — it is the Admin owner's own
- * consent to Working Theory, on the hub's cookie session. The member profile write IS admitted — it
+ * consent to Working Theory, on the hub's cookie session. Nor is the
+ * anonymous `GET /v1/consent/sign-up` (#8765 D2): it takes no credential. The member profile write IS admitted — it
  * is the person's own account, which roadmap D9 saves through it. Not
  * admitted, deliberately: `GET /v1/waitlist-signups/me`,
  * `GET /v1/flow-checkouts/me`, `GET /v1/subscription/me` and
@@ -191,6 +194,10 @@ export const HUB_SESSION_ROUTES: readonly string[] = Object.freeze([
   // admitted: those are the Admin owner's, on the hub's own cookie session.
   "GET /v1/member/consents",
   "POST /v1/member/consents",
+  // #8765 D5 — the caller's account-level sign-up agreements, so a spoke's
+  // account layout reads and accepts the one grant every site shares.
+  "GET /v1/consent/account",
+  "POST /v1/consent/account",
   // #8515 D13 — the client's onboarding read and write.
   "GET /v1/member/onboarding",
   "POST /v1/member/onboarding",