create-ailk 0.11.2 → 0.11.4

package/templates/apps/api/src/lib/auth-email-budget.ts

@@ -34,11 +34,12 @@ import { createHash } from "node:crypto";
 
 import { getClock } from "@working-theory/common";
 
-/** The three fixed message kinds the relay will send. */
+/** The four fixed message kinds the relay will send. */
 export type AuthEmailKind =
   | "password-reset"
   | "email-verification"
-  | "password-changed";
+  | "password-changed"
+  | "magic-link";
 
 /** Sends allowed per (recipient, kind) per hour. */
 export const RECIPIENT_HOURLY_MAX = 3;

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

@@ -13,12 +13,15 @@
  * Spec: docs/internal/specs/draft/ailk-mcp-mvp-pb-b5-rate-limit-spec.md
  */
 
-import Fastify from "fastify";
+import Fastify, { type FastifyInstance } from "fastify";
 import {
   rateLimitMiddleware,
   __resetBuckets,
   __bucketCount,
+  buildTrustedKeyDigests,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
+  resolveRateLimitIdentity,
+  type RateLimitOptions,
 } from "../rate-limit.js";
 
 function buildApp(
@@ -527,3 +530,528 @@ describe("rate-limit warn log — no query-string credential (#5970)", () => {
     }
   });
 });
+
+// #7394 — per-visitor leads limit for a server-to-server spoke
+// (docs/specs/7394-the-leads-rate-limit-scope-spec.md). Every route below is
+// `POST /v1/leads/submit` unless a case says otherwise, so it is in
+// `FORWARDED_VISITOR_ROUTES`. "The key" is one 64-character key passed
+// through `buildTrustedKeyDigests`.
+describe("per-visitor forwarding, scope namespace and per-scope env limit (#7394)", () => {
+  const KEY = "0123456789abcdef".repeat(4); // gitleaks:allow — test fixture, not a credential (#7394)
+  const SPOKE_HOST = "198.51.100.7";
+  const LEADS_SUBMIT = "/v1/leads/submit";
+  const ENV_KEYS = [
+    "AILK_RATE_LIMIT_LEADS_PER_MINUTE",
+    "AILK_RATE_LIMIT_LEADS_PER_KEY_PER_MINUTE",
+    "AILK_RATE_LIMIT_PER_IP_PER_MINUTE",
+  ] as const;
+  const priorEnv = new Map<string, string | undefined>(
+    ENV_KEYS.map((name) => [name, process.env[name]]),
+  );
+
+  const noWarn = () => undefined;
+  const digests = () => buildTrustedKeyDigests(KEY, noWarn);
+
+  let app: FastifyInstance | undefined;
+  let logLines: Array<Record<string, unknown>>;
+
+  function forwardApp(
+    opts: RateLimitOptions,
+    routes: readonly string[] = [LEADS_SUBMIT],
+  ): 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, opts);
+    for (const url of routes) instance.post(url, async () => ({ ok: true }));
+    return instance;
+  }
+
+  function keyed(visitorIp: string, key: string = KEY): Record<string, string> {
+    return {
+      "x-forwarded-for": SPOKE_HOST,
+      "x-ailk-visitor-forward-key": key,
+      "x-ailk-visitor-ip": visitorIp,
+    };
+  }
+
+  async function post(
+    headers: Record<string, string>,
+    url: string = LEADS_SUBMIT,
+  ): Promise<number> {
+    if (!app) throw new Error("no app");
+    const res = await app.inject({ method: "POST", url, headers });
+    return res.statusCode;
+  }
+
+  function rateLimitedLines(): Array<Record<string, unknown>> {
+    return logLines.filter((line) => line["msg"] === "rate_limited");
+  }
+
+  beforeEach(() => {
+    __resetBuckets();
+    logLines = [];
+    for (const name of ENV_KEYS) delete process.env[name];
+  });
+
+  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;
+    }
+  });
+
+  describe("AC-1 — AILK_RATE_LIMIT_<SCOPE>_PER_MINUTE overrides the code value", () => {
+    async function firstRefused(): Promise<number> {
+      const headers = { "x-forwarded-for": "203.0.113.50" };
+      for (let i = 1; i <= 50; i++) {
+        if ((await post(headers)) === 429) return i;
+      }
+      return -1;
+    }
+
+    it("the env var wins over perIpPerMinute", async () => {
+      process.env.AILK_RATE_LIMIT_LEADS_PER_MINUTE = "3";
+      app = forwardApp({ scope: "leads", perIpPerMinute: 10 });
+      await app.ready();
+      expect(await firstRefused()).toBe(4);
+    });
+
+    it("with the env var unset, the code value applies", async () => {
+      app = forwardApp({ scope: "leads", perIpPerMinute: 10 });
+      await app.ready();
+      expect(await firstRefused()).toBe(11);
+    });
+
+    it("an invalid env var is ignored, with one warning naming the variable", async () => {
+      process.env.AILK_RATE_LIMIT_LEADS_PER_MINUTE = "abc";
+      app = forwardApp({ scope: "leads", perIpPerMinute: 10 });
+      await app.ready();
+      expect(await firstRefused()).toBe(11);
+      const warnings = logLines.filter((line) =>
+        String(line["msg"]).includes("AILK_RATE_LIMIT_LEADS_PER_MINUTE"),
+      );
+      expect(warnings).toHaveLength(1);
+    });
+
+    it.each(["0", "-5", "2.5", "1000000"])(
+      "ignores the out-of-range value %s",
+      async (value) => {
+        process.env.AILK_RATE_LIMIT_LEADS_PER_MINUTE = value;
+        app = forwardApp({ scope: "leads", perIpPerMinute: 10 });
+        await app.ready();
+        expect(await firstRefused()).toBe(11);
+      },
+    );
+
+    it("does not read AILK_RATE_LIMIT_PER_IP_PER_MINUTE for a named scope with a code value", async () => {
+      process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE = "2";
+      app = forwardApp({ scope: "leads", perIpPerMinute: 10 });
+      await app.ready();
+      expect(await firstRefused()).toBe(11);
+    });
+  });
+
+  describe("AC-2 — a named scope gets its own bucket namespace", () => {
+    function twoScopes(second: RateLimitOptions): FastifyInstance {
+      const instance = Fastify({ trustProxy: true });
+      instance.register(async (child) => {
+        child.register(rateLimitMiddleware, { perIpPerMinute: 10 });
+        child.post("/a", async () => ({ ok: true }));
+      });
+      instance.register(async (child) => {
+        child.register(rateLimitMiddleware, second);
+        child.post("/b", async () => ({ ok: true }));
+      });
+      return instance;
+    }
+    const headers = { "x-forwarded-for": "203.0.113.60" };
+
+    it("ten /a requests do not spend the leads scope's budget", async () => {
+      app = twoScopes({ scope: "leads", perIpPerMinute: 10 });
+      await app.ready();
+      for (let i = 0; i < 10; i++) expect(await post(headers, "/a")).toBe(200);
+      for (let i = 0; i < 10; i++) expect(await post(headers, "/b")).toBe(200);
+      expect(await post(headers, "/b")).toBe(429);
+    });
+
+    it("two unnamed registrations still share their count, as at the pin", async () => {
+      app = twoScopes({ perIpPerMinute: 10 });
+      await app.ready();
+      for (let i = 0; i < 10; i++) expect(await post(headers, "/a")).toBe(200);
+      expect(await post(headers, "/b")).toBe(429);
+    });
+  });
+
+  describe("AC-3 — a keyed lead write is counted per visitor", () => {
+    it("limits each forwarded visitor separately behind one spoke host", async () => {
+      app = forwardApp({
+        scope: "leads",
+        perIpPerMinute: 10,
+        perKeyPerMinute: 300,
+        trustedKeyDigests: digests(),
+      });
+      await app.ready();
+      for (let i = 0; i < 10; i++) expect(await post(keyed("203.0.113.1"))).toBe(200);
+      expect(await post(keyed("203.0.113.1"))).toBe(429);
+      expect(await post(keyed("203.0.113.2"))).toBe(200);
+    });
+  });
+
+  describe("AC-4 — the visitor header is ignored without the key, or off the lead writes", () => {
+    const WRONG_SAME_LENGTH = "f".repeat(64);
+    const ONE_CHAR_CHANGED = `${KEY.slice(0, -1)}0`;
+
+    async function elevenDistinctVisitors(
+      headersFor: (visitorIp: string) => Record<string, string>,
+      url: string = LEADS_SUBMIT,
+    ): Promise<number[]> {
+      const codes: number[] = [];
+      for (let i = 1; i <= 11; i++) codes.push(await post(headersFor(`203.0.113.${i}`), url));
+      return codes;
+    }
+
+    const base = {
+      scope: "leads",
+      perIpPerMinute: 10,
+      perKeyPerMinute: 300,
+    } as const;
+
+    it.each([
+      [
+        "(i) no key",
+        (ip: string) => ({ "x-forwarded-for": SPOKE_HOST, "x-ailk-visitor-ip": ip }),
+      ],
+      ["(ii) a wrong key of the same length", (ip: string) => keyed(ip, WRONG_SAME_LENGTH)],
+      ["(iii) the right key with one character changed", (ip: string) => keyed(ip, ONE_CHAR_CHANGED)],
+    ])("%s: the eleventh request is 429", async (_label, headersFor) => {
+      app = forwardApp({ ...base, trustedKeyDigests: digests() });
+      await app.ready();
+      const codes = await elevenDistinctVisitors(headersFor);
+      expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+      expect(codes[10]).toBe(429);
+    });
+
+    it("(iv) the valid key, but no trustedKeyDigests passed: the eleventh request is 429", async () => {
+      app = forwardApp(base);
+      await app.ready();
+      const codes = await elevenDistinctVisitors((ip) => keyed(ip));
+      expect(codes[10]).toBe(429);
+    });
+
+    it("(v) the valid key on POST /v1/project-listings in the same scope: the eleventh request is 429", async () => {
+      app = forwardApp({ ...base, trustedKeyDigests: digests() }, [
+        LEADS_SUBMIT,
+        "/v1/project-listings",
+      ]);
+      await app.ready();
+      const codes = await elevenDistinctVisitors((ip) => keyed(ip), "/v1/project-listings");
+      expect(codes.slice(0, 10).every((code) => code === 200)).toBe(true);
+      expect(codes[10]).toBe(429);
+    });
+  });
+
+  describe("AC-5 — visitor IP validation and normalisation", () => {
+    function identityApp(): FastifyInstance {
+      const instance = Fastify({ trustProxy: true });
+      const trusted = digests();
+      instance.post(LEADS_SUBMIT, async (req) => resolveRateLimitIdentity(req, trusted));
+      return instance;
+    }
+
+    async function identityFor(visitorIp: string): Promise<unknown> {
+      if (!app) throw new Error("no app");
+      const res = await app.inject({ method: "POST", url: LEADS_SUBMIT, headers: keyed(visitorIp) });
+      return res.json();
+    }
+
+    it.each(["not-an-ip", "203.0.113.1, 198.51.100.1", "a".repeat(46), "fe80::1%eth0", ""])(
+      "falls back to req.ip for %j",
+      async (visitorIp) => {
+        app = identityApp();
+        await app.ready();
+        expect(await identityFor(visitorIp)).toEqual({ identity: SPOKE_HOST, keyIndex: null });
+      },
+    );
+
+    it("maps an IPv4-mapped IPv6 address to its IPv4 form", async () => {
+      app = identityApp();
+      await app.ready();
+      expect(await identityFor("::ffff:203.0.113.9")).toEqual({
+        identity: "v0,203.0.113.9",
+        keyIndex: 0,
+      });
+    });
+
+    it.each(["2001:db8:1:2::1", "2001:DB8:1:2::ffff"])(
+      "groups the IPv6 address %s by its /64",
+      async (visitorIp) => {
+        app = identityApp();
+        await app.ready();
+        expect(await identityFor(visitorIp)).toEqual({
+          identity: "v0,2001:0db8:0001:0002::/64",
+          keyIndex: 0,
+        });
+      },
+    );
+
+    it("keeps a valid IPv4 address as it is", async () => {
+      app = identityApp();
+      await app.ready();
+      expect(await identityFor(" 203.0.113.10 ")).toEqual({
+        identity: "v0,203.0.113.10",
+        keyIndex: 0,
+      });
+    });
+
+    it("ignores the key on a method other than POST", async () => {
+      const trusted = digests();
+      app = Fastify({ trustProxy: true });
+      app.get(LEADS_SUBMIT, async (req) => resolveRateLimitIdentity(req, trusted));
+      await app.ready();
+      const res = await app.inject({ method: "GET", url: LEADS_SUBMIT, headers: keyed("203.0.113.1") });
+      expect(res.json()).toEqual({ identity: SPOKE_HOST, keyIndex: null });
+    });
+  });
+
+  describe("AC-6 — buildTrustedKeyDigests keeps positions and never logs an entry", () => {
+    it("drops a short entry with one warning, keeps empty slots, and digests the real key", () => {
+      const warn = jest.fn();
+      const slots = buildTrustedKeyDigests(`short, ,${KEY}`, warn);
+      expect(slots).toHaveLength(3);
+      expect(slots[0]).toBeNull();
+      expect(slots[1]).toBeNull();
+      expect(Buffer.isBuffer(slots[2])).toBe(true);
+      expect(warn).toHaveBeenCalledTimes(1);
+      const message = String(warn.mock.calls[0]?.[0]);
+      expect(message).toContain("AILK_VISITOR_FORWARD_KEYS");
+      expect(message).not.toContain("short");
+    });
+
+    it("returns [] and warns nothing when the variable is unset or empty", () => {
+      const warn = jest.fn();
+      expect(buildTrustedKeyDigests(undefined, warn)).toEqual([]);
+      expect(buildTrustedKeyDigests("", warn)).toEqual([]);
+      expect(warn).not.toHaveBeenCalled();
+    });
+
+    it("counts a request presenting the short entry under req.ip", async () => {
+      app = forwardApp({
+        scope: "leads",
+        perIpPerMinute: 1,
+        trustedKeyDigests: buildTrustedKeyDigests(`short, ,${KEY}`, noWarn),
+      });
+      await app.ready();
+      expect(await post(keyed("203.0.113.1", "short"))).toBe(200);
+      expect(await post(keyed("203.0.113.2", "short"))).toBe(429);
+    });
+
+    it("gives the third entry's visitors a v2, identity and their own buckets", async () => {
+      const trusted = buildTrustedKeyDigests(`short, ,${KEY}`, noWarn);
+      app = Fastify({ trustProxy: true });
+      app.register(async (child) => {
+        child.register(rateLimitMiddleware, {
+          scope: "leads",
+          perIpPerMinute: 10,
+          trustedKeyDigests: trusted,
+        });
+        child.post(LEADS_SUBMIT, async (req) => resolveRateLimitIdentity(req, trusted));
+      });
+      await app.ready();
+      const first = await app.inject({ method: "POST", url: LEADS_SUBMIT, headers: keyed("203.0.113.1") });
+      expect((first.json() as { identity: string }).identity).toBe("v2,203.0.113.1");
+      for (let i = 0; i < 9; i++) expect(await post(keyed("203.0.113.1"))).toBe(200);
+      expect(await post(keyed("203.0.113.1"))).toBe(429);
+      expect(await post(keyed("203.0.113.2"))).toBe(200);
+    });
+  });
+
+  describe("AC-10 — the 429 log line names the bucket and key position, never the key", () => {
+    it("logs the namespaced identity, bucket and keyIndex for a visitor-bucket 429", async () => {
+      app = forwardApp({
+        scope: "leads",
+        perIpPerMinute: 10,
+        perKeyPerMinute: 300,
+        trustedKeyDigests: digests(),
+      });
+      await app.ready();
+      for (let i = 0; i < 10; i++) await post(keyed("203.0.113.1"));
+      expect(await post(keyed("203.0.113.1"))).toBe(429);
+
+      const [line] = rateLimitedLines();
+      expect(line?.["ip"]).toBe("v0,203.0.113.1");
+      expect(line?.["bucket"]).toBe("visitor");
+      expect(line?.["keyIndex"]).toBe(0);
+      const text = JSON.stringify(logLines);
+      expect(text).not.toContain(KEY);
+      expect(text).not.toContain("forward-key");
+    });
+  });
+
+  describe("AC-11 — each key has its own ceiling", () => {
+    const options = (): RateLimitOptions => ({
+      scope: "leads",
+      perIpPerMinute: 10,
+      perKeyPerMinute: 5,
+      trustedKeyDigests: digests(),
+    });
+
+    it("refuses the sixth keyed request across distinct visitors, with bucket: key", async () => {
+      app = forwardApp(options());
+      await app.ready();
+      for (let i = 1; i <= 5; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(200);
+      const sixth = await app.inject({
+        method: "POST",
+        url: LEADS_SUBMIT,
+        headers: keyed("203.0.113.6"),
+      });
+      expect(sixth.statusCode).toBe(429);
+      const retryAfter = Number(sixth.headers["retry-after"]);
+      expect(retryAfter).toBeGreaterThanOrEqual(1);
+      expect(retryAfter).toBeLessThanOrEqual(60);
+      const [line] = rateLimitedLines();
+      expect(line?.["bucket"]).toBe("key");
+      expect(line?.["keyIndex"]).toBe(0);
+      expect(line?.["ip"]).toBe("v0,203.0.113.6");
+
+      // A request with no key, from a seventh visitor, is unaffected.
+      expect(await post({ "x-forwarded-for": "203.0.113.7" })).toBe(200);
+    });
+
+    it("reads AILK_RATE_LIMIT_LEADS_PER_KEY_PER_MINUTE over the option", async () => {
+      process.env.AILK_RATE_LIMIT_LEADS_PER_KEY_PER_MINUTE = "7";
+      app = forwardApp(options());
+      await app.ready();
+      for (let i = 1; i <= 7; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(200);
+      expect(await post(keyed("203.0.113.8"))).toBe(429);
+    });
+
+    it("does not read the per-visitor variable for the per-key ceiling", async () => {
+      process.env.AILK_RATE_LIMIT_LEADS_PER_MINUTE = "50";
+      app = forwardApp(options());
+      await app.ready();
+      for (let i = 1; i <= 5; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(200);
+      expect(await post(keyed("203.0.113.6"))).toBe(429);
+    });
+
+    it("visitor churn past maxBuckets cannot evict the key bucket and reset its ceiling", async () => {
+      app = forwardApp({ ...options(), maxBuckets: 3 });
+      await app.ready();
+      for (let i = 1; i <= 5; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(200);
+      // Each refused request still adds a visitor bucket; with maxBuckets 3
+      // the oldest entries are evicted over and over.
+      for (let i = 6; i <= 20; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(429);
+    });
+
+    it("a key over its ceiling opens no new visitor bucket, so it cannot evict another scope's counter (security review R-1)", async () => {
+      app = Fastify({ trustProxy: true });
+      app.register(async (child) => {
+        child.register(rateLimitMiddleware, { perIpPerMinute: 1, maxBuckets: 10 });
+        child.post("/v1/auth/email", async () => ({ ok: true }));
+      });
+      app.register(async (child) => {
+        child.register(rateLimitMiddleware, { ...options(), maxBuckets: 10 });
+        child.post(LEADS_SUBMIT, async () => ({ ok: true }));
+      });
+      await app.ready();
+      const victim = { "x-forwarded-for": "198.51.100.99" };
+      expect(await post(victim, "/v1/auth/email")).toBe(200);
+      expect(await post(victim, "/v1/auth/email")).toBe(429);
+
+      for (let i = 1; i <= 5; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(200);
+      for (let i = 6; i <= 60; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(429);
+
+      // The victim's exhausted counter survived the keyed churn.
+      expect(await post(victim, "/v1/auth/email")).toBe(429);
+    });
+
+    it("a key over its ceiling still counts a visitor whose bucket is already open", async () => {
+      app = forwardApp({ ...options(), perIpPerMinute: 2 });
+      await app.ready();
+      expect(await post(keyed("203.0.113.1"))).toBe(200);
+      for (let i = 2; i <= 5; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(200);
+      // Key now at its ceiling of 5; visitor 1 has an open bucket at count 1.
+      expect(await post(keyed("203.0.113.1"))).toBe(429);
+      const [line] = rateLimitedLines();
+      expect(line?.["bucket"]).toBe("key");
+      // Visitor 1's own bucket was counted (now 2), so a third request trips
+      // the visitor bucket even once the key bucket is ignored.
+      expect(await post(keyed("203.0.113.1"))).toBe(429);
+      expect(rateLimitedLines()[1]?.["bucket"]).toBe("visitor");
+    });
+
+    it("defaults the per-key ceiling to 300 when no option is passed", async () => {
+      app = forwardApp({ scope: "leads", perIpPerMinute: 10, trustedKeyDigests: digests() });
+      await app.ready();
+      const codes: number[] = [];
+      for (let i = 0; i < 301; i++) {
+        codes.push(await post(keyed(`10.${Math.floor(i / 250)}.${i % 250}.1`)));
+      }
+      expect(codes.slice(0, 300).every((code) => code === 200)).toBe(true);
+      expect(codes[300]).toBe(429);
+    });
+  });
+
+  describe("AC-12 — no unkeyed req.ip can reach a keyed bucket", () => {
+    const options = (): RateLimitOptions => ({
+      scope: "leads",
+      perIpPerMinute: 10,
+      perKeyPerMinute: 5,
+      trustedKeyDigests: digests(),
+    });
+
+    it("unkeyed traffic shaped like a keyed bucket key adds nothing to the per-key bucket", async () => {
+      app = forwardApp(options());
+      await app.ready();
+      for (const forwarded of ["key:0", "key", "v0:203.0.113.1", "v0"]) {
+        for (let i = 0; i < 6; i++) await post({ "x-forwarded-for": forwarded });
+      }
+      for (let i = 1; i <= 5; i++) expect(await post(keyed(`203.0.113.${i}`))).toBe(200);
+      expect(await post(keyed("203.0.113.6"))).toBe(429);
+    });
+
+    it("ten unkeyed requests from v0:203.0.113.1 do not stop that keyed visitor", async () => {
+      app = forwardApp(options());
+      await app.ready();
+      for (let i = 0; i < 10; i++) await post({ "x-forwarded-for": "v0:203.0.113.1" });
+      expect(await post(keyed("203.0.113.1"))).toBe(200);
+    });
+  });
+
+  describe("registration guards", () => {
+    it.each(["Leads", "1leads", "le-ads", ""])("rejects the scope name %j", async (scope) => {
+      app = forwardApp({ scope });
+      await expect(app.ready()).rejects.toThrow(/scope/);
+    });
+
+    it("rejects trustedKeyDigests without a scope", async () => {
+      app = forwardApp({ trustedKeyDigests: digests() });
+      await expect(app.ready()).rejects.toThrow(/scope/);
+    });
+
+    it("lets a caller-supplied ipFromRequest win over the forwarded identity", async () => {
+      app = forwardApp({
+        scope: "leads",
+        perIpPerMinute: 1,
+        trustedKeyDigests: digests(),
+        ipFromRequest: () => "fixed",
+      });
+      await app.ready();
+      expect(await post(keyed("203.0.113.1"))).toBe(200);
+      expect(await post(keyed("203.0.113.2"))).toBe(429);
+    });
+  });
+});