Limits you can see coming

rate_limited: "too many requests",

const count = await redis.incr(key);
if (count === 1) await redis.pexpire(key, windowMs);

// The fixed-window arithmetic (research R1).
//
// FIXED WINDOW, NOT A TOKEN BUCKET, and the SAD's own row is why the question
// arose: §6.3 lists `rl:{env}:{bucket}` as "Token buckets" with a TTL of
// "window", which are two different algorithms. The TTL column wins, for three
// reasons in order of weight.
//
// `X-RateLimit-Reset` decides it. The header names the moment an allowance
// returns, and a fixed window has exactly one. A continuously refilling bucket
// does not — the honest answer to "when do I have my full allowance back" is a
// curve, and the header is an integer. A limiter whose reset header is a lie
// fails FR-RTL-02 in the way that matters, because that requirement exists so a
// client can schedule against it.
//
// Then atomicity: `INCR` returns the new value on its own and `EXPIRE` on the
// first increment gives the window. Two commands, no Lua, no read-modify-write
// race between api instances.
//
// Then cleanup: the key expires when its window ends, so nothing accumulates.
// That matters more than it sounds — the deduplication chapter spent a baseline on four suites
// that broke because a shared store grew without bound, and this chapter's own
// baseline found a fifth.
//
// THE COST, stated rather than hidden: up to twice the limit across a boundary.
// 600 in the last instant of one window and 600 in the first instant of the next
// is 1,200 inside two minutes. The limit bounds sustained load; it does not
// smooth instantaneous rate. `bucket.test.ts` asserts it so the claim is checked
// rather than merely written down.
//
// Everything here is pure and takes the instant it should reason about. Nothing
// reads a clock, so a boundary is a test rather than a wait.
 
/** The window an instant belongs to, floored — and the key's own suffix.
 *
 * Two api instances compute this from the same wall clock and agree without
 * talking to each other, which is what closes the clock-skew case by
 * construction. A stored reset time would be a value they could disagree about,
 * and `Retry-After` is exactly where that disagreement would surface. */
export function windowStart(nowMs: number, windowMs: number): number {
  return Math.floor(nowMs / windowMs) * windowMs;
}
 
/** When the allowance returns: the end of the current window, in milliseconds.
 *
 * One moment, which is the whole argument for this algorithm over a bucket that
 * refills. Never in the past — the window an instant belongs to always ends
 * after it. */
export function resetAt(nowMs: number, windowMs: number): number {
  return windowStart(nowMs, windowMs) + windowMs;
}
 
/** How many operations are left, after counting the one in hand.
 *
 * Clamped at zero. A limit lowered while a window is open — an operator dropping
 * an environment from 600 to 2 with forty already counted — would otherwise
 * produce `-38`, and a client would parse that as a number and act on it. Zero
 * is both true and safe. */
export function remaining(count: number, limit: number): number {
  return Math.max(0, limit - count);
}

-- Per-environment rate limit policy (FR-RTL-04).
--
-- NULLABLE, AND NULL IS NOT ZERO. A null column means "no override, use the
-- documented default", resolved at read time. A zero means "refuse everything",
-- which has to stay expressible — an environment can be switched off
-- deliberately — so the absent state and the refuse-everything state cannot
-- share a representation.
--
-- ON `environments` RATHER THAN IN A TABLE OF ITS OWN. FR-RTL-04's independence
-- is per environment, there is exactly one row per environment with no history
-- and no versioning, and a separate table would be a join for a value read on
-- every request.
--
-- The shape has a slot for an environment and NONE FOR A ROUTE, which forecloses
-- SRS Appendix C question 5 — whether the dev-token endpoint should be limited
-- more aggressively than the rest of its environment. That question stays open
-- and this is why (research R30).
 
ALTER TABLE environments
  ADD COLUMN rest_limit_per_minute    integer,
  ADD COLUMN send_limit_per_minute    integer,
  ADD COLUMN connect_limit_per_minute integer;
 
ALTER TABLE environments
  ADD CONSTRAINT environments_rest_limit_non_negative
    CHECK (rest_limit_per_minute IS NULL OR rest_limit_per_minute >= 0),
  ADD CONSTRAINT environments_send_limit_non_negative
    CHECK (send_limit_per_minute IS NULL OR send_limit_per_minute >= 0),
  ADD CONSTRAINT environments_connect_limit_non_negative
    CHECK (connect_limit_per_minute IS NULL OR connect_limit_per_minute >= 0);

quotaConfig: jsonb("quota_config").notNull().default({}),

const address = clientAddress(req);
if (await this.authLimiter.isOverThreshold(address)) {
  req[OVER_AUTH_THRESHOLD] = true;
}
const principal = await resolvePrincipal(this.db, credential);
if (principal !== null) {
  req.principal = principal;
} else {
  await this.authLimiter.recordFailure(address);
}

export function operationsFor(method: string, path: string): LimitedOperation[] {
  if (!path.startsWith(PUBLIC_PREFIX)) return [];
  if (method === "POST" && SEND_PATH.test(path)) return ["rest", "send"];
  return ["rest"];
}

{"time":"2026-08-20T03:48:30.986Z","level":"error","service":"api",
 "msg":"limits.auth_degraded",
 "detail":"counter store unreachable; counting failed authentications in process",
 "tracked":0}

if (decision.over) {
  refuseUpgrade(socket, decision);   // 429 · Retry-After · the three headers
  return;
}
wss.handleUpgrade(req, socket, head, (ws) => { … });

limits: z.strictObject({
  connect: z.number().int().nonnegative(),
  send: z.number().int().nonnegative(),
}),

import { spawn, type ChildProcess } from "node:child_process";
import { randomUUID } from "node:crypto";
import { existsSync } from "node:fs";
import { createRequire } from "node:module";
import { dirname, join } from "node:path";
import type { Server } from "node:http";
import type { AddressInfo } from "node:net";
import { fileURLToPath } from "node:url";
 
import { docsUrl } from "@relay/protocol";
import { createLogger, serve, type Logger } from "@relay/service-kit";
import { Redis } from "ioredis";
import { WebSocket } from "ws";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 
import { createApiClient } from "./api-client.js";
import { createGatewayLimits, type GatewayLimits } from "./limits.js";
import { attachSessions } from "./session.js";
 
// The claim no single-process test can make: that the api and the
// gateway increment ONE counter.
//
// Everything else about the limits is provable cheaper. The arithmetic is pure
// and unit-tested; the socket's two refusals are unit-tested with a stub
// counter; the api's headers are covered by its own integration suite. What
// none of those can show is the property the whole design rests on — a socket
// send and a REST send spend the same budget, because the budget lives in Redis
// and neither process can see the other's memory. A test that stubs the store
// would pass with two separate counters.
//
//   docker compose up -d --wait postgres redis
//   pnpm build
//   RELAY_POSTGRES_PORT=… RELAY_REDIS_PORT=… \
//     pnpm --filter @relay/gateway test:integration
//
// The api runs as a CHILD PROCESS for the reason session.itest.ts gives: the
// gateway is not allowed to know how the api is built (ADR-05), and importing
// it would make that dependency real in order to deny it.
 
const silent: Logger = createLogger("gateway", () => {});
const REDIS_URL = `redis://localhost:${process.env.RELAY_REDIS_PORT ?? "6379"}`;
 
const HERE = dirname(fileURLToPath(import.meta.url));
const REPO = join(HERE, "..", "..", "..");
const require_ = createRequire(import.meta.url);
 
interface Seeded {
  environmentId: string;
  credential: string;
  channelId: string;
}
 
interface ApiUnderTest extends Seeded {
  url: string;
  /** Configure this environment's policy. Plain SQL through the api's pool: the
   * columns are three nullable integers and there is no admin API for them yet,
   * so inventing one for a test would be inventing product. */
  setLimits: (limits: {
    rest?: number | null;
    send?: number | null;
    connect?: number | null;
  }) => Promise<void>;
  stop: () => void;
}
 
async function waitForHealth(url: string): Promise<void> {
  const deadline = Date.now() + 30_000;
  for (;;) {
    try {
      if ((await fetch(url)).ok) return;
    } catch {
      // not up yet
    }
    if (Date.now() > deadline) throw new Error("api never became healthy");
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
}
 
async function startApi(): Promise<ApiUnderTest> {
  const dist = join(REPO, "services", "api", "dist");
  if (!existsSync(join(dist, "main.js"))) {
    throw new Error(
      "the api is not built — run `pnpm build` before this lane " +
        "(the suite talks to the real service, not a stub)",
    );
  }
  const client = require_(join(dist, "db", "client.js")) as {
    createDb: (pool: unknown) => unknown;
    createPool: () => Pool;
  };
  const seeder = require_(join(dist, "db", "repository.js")) as {
    createEnvironment: (
      db: unknown,
      input: { name: string },
    ) => Promise<{ id: string }>;
    createApiKey: (
      db: unknown,
      input: { environmentId: string },
    ) => Promise<{ credential: string }>;
    Repository: new (
      db: unknown,
      environmentId: string,
    ) => {
      createUser: (externalId: string, name?: string) => Promise<{ id: string }>;
      createChannel: (
        externalId: string,
        type: string,
      ) => Promise<{ id: string }>;
      addMember: (channelId: string, userId: string) => Promise<boolean>;
      upsertUser: (
        externalId: string,
        profile: { display_name?: string; kind?: string; description?: string },
      ) => Promise<{ user: { id: string } }>;
    };
  };
  const pool = client.createPool();
  const db = client.createDb(pool);
 
  const environment = await seeder.createEnvironment(db, {
    name: `limits-itest-${randomUUID().slice(0, 8)}`,
  });
  const repo = new seeder.Repository(db, environment.id);
  const user = await repo.createUser("tuan", "Tuan");
  const channel = await repo.createChannel("fleet", "public");
  await repo.addMember(channel.id, user.id);
  // AND A BOT FOR THE REST HALF. The socket half sends as `tuan` through a user
  // token; the REST half presents an APPLICATION credential, which carries no user
  // of its own — so it must name a sender and that sender must be a BOT. A person
  // named by a key is 403, an unknown name 400, and neither is a 429.
  //
  // Seeded here rather than per send, because this file's whole subject is how many
  // requests fit under one limit: an extra call per send would move every number in
  // it and leave the assertions passing for the wrong reason. No channel membership
  // — measured, not assumed: the suite is green without it.
  await repo.upsertUser("meter", {
    display_name: "Meter",
    kind: "bot",
    description: "spends this suite's REST budget",
  });
  const key = await seeder.createApiKey(db, { environmentId: environment.id });
 
  // `PORT: "0"` AND THE PORT READ OFF THE CHILD'S OWN LOG LINE, which is what the
  // three sibling suites in this directory already do. Published's version of this
  // file hand-allocated `RELAY_LIMITS_ITEST_API_PORT ?? 4124`, and a hand-maintained
  // port table is the failure that cannot be checked: 4124 sits inside the band this
  // chapter would have claimed, and NATS runs on 4222 inside the same band. The
  // failure is silent in both directions — the child cannot bind, and the health
  // check gets its answer from whatever DOES hold the port.
  const child: ChildProcess = spawn("node", [join(dist, "main.js")], {
    env: {
      ...process.env,
      PORT: "0",
      RELAY_OUTBOX_RELAY: "off",
      // Nor the notification relay: this suite counts requests, and a background
      // loop sending mail is one more thing that can make a count wander.
      RELAY_NOTIFICATION_RELAY: "off",
      RELAY_REDIS_URL: REDIS_URL,
    },
    stdio: ["ignore", "pipe", "pipe"],
  });
  const port = await new Promise<number>((resolve, reject) => {
    const timer = setTimeout(() => reject(new Error("api never reported a port")), 30_000);
    let buffered = "";
    child.stdout?.on("data", (chunk: Buffer) => {
      buffered += chunk.toString();
      for (const line of buffered.split("\n")) {
        if (!line.trim()) continue;
        try {
          const parsed = JSON.parse(line) as { msg?: string; port?: number };
          if (parsed.msg === "listening" && typeof parsed.port === "number") {
            clearTimeout(timer);
            resolve(parsed.port);
            return;
          }
        } catch {
          /* a partial line; the next chunk completes it */
        }
      }
    });
    child.on("exit", (code) => {
      clearTimeout(timer);
      reject(new Error(`api exited before listening (code ${String(code)})`));
    });
  });
  const url = `http://127.0.0.1:${port}`;
  await waitForHealth(`${url}/healthz`);
 
  return {
    url,
    environmentId: environment.id,
    credential: key.credential,
    channelId: channel.id,
    setLimits: async ({ rest = null, send = null, connect = null }) => {
      await pool.query(
        "UPDATE environments SET rest_limit_per_minute = $2, " +
          "send_limit_per_minute = $3, connect_limit_per_minute = $4 " +
          "WHERE id = $1",
        [environment.id, rest, send, connect],
      );
    },
    stop: () => {
      child.kill();
      void pool.end();
    },
  };
}
 
interface Pool {
  query: (text: string, values?: unknown[]) => Promise<unknown>;
  end: () => Promise<void>;
}
 
function firstFrame(socket: WebSocket, type: string): Promise<unknown> {
  return new Promise((resolve, reject) => {
    socket.on("message", (raw) => {
      const frame = JSON.parse(raw.toString()) as { type: string };
      if (frame.type === type) resolve(frame);
    });
    socket.on("close", (code) => reject(new Error(`closed ${code}`)));
    setTimeout(() => reject(new Error(`no ${type} within 5s`)), 5_000);
  });
}
 
describe("one counter, two services", () => {
  let api: ApiUnderTest;
  let server: Server;
  let limits: GatewayLimits;
  let redis: Redis;
  let url: string;
  const sockets: WebSocket[] = [];
 
  /** The key the api and the gateway are both supposed to be incrementing.
   * Spelled out here rather than imported, because a test that computed it with
   * the code under test would agree with a wrong answer. */
  const key = (operation: string, atMs: number = Date.now()) =>
    `rl:${api.environmentId}:${operation}:` +
    `${Math.floor(atMs / 60_000) * 60_000}`;
 
  /** THE WINDOW IS WALL-CLOCK, SO A TEST CAN SPAN TWO OF THEM.
   *
   * `limits.ts:115` keys on `Math.floor(now / 60_000) * 60_000`. The bucket rolls at the
   * top of every minute whatever the suite is doing, so ten sends either side of the
   * boundary write two keys — and reading one of them reports `7` where the test means
   * `10`, which looks exactly like a limiter dropping increments.
   *
   * Measured, twice: run 1 of feature 043's second battery and run 2 of its third.
   * Nothing in either failure named a clock.
   *
   * SUMMING RATHER THAN SLEEPING, and the first attempt did sleep. Waiting for the next
   * boundary made the test correct and blew its 5-second timeout the moment the guard
   * actually fired — a fix whose failure mode is worse than the fault, because a timeout
   * says nothing about what it was waiting for. This asserts the same number without
   * spending any time: ten sends are ten sends however the minute falls across them. */
  const windowsSince = (sinceMs: number): number[] => {
    const first = Math.floor(sinceMs / 60_000) * 60_000;
    const last = Math.floor(Date.now() / 60_000) * 60_000;
    const out: number[] = [];
    for (let w = first; w <= last; w += 60_000) out.push(w);
    return out;
  };
 
  let testStartedAt = Date.now();
 
  const count = async (operation: string): Promise<number> => {
    let total = 0;
    for (const w of windowsSince(testStartedAt)) {
      total += Number((await redis.get(key(operation, w))) ?? 0);
    }
    return total;
  };
 
  const mintToken = async (user = "tuan") => {
    const res = await fetch(`${api.url}/auth/dev-token`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        authorization: `Bearer ${api.credential}`,
      },
      body: JSON.stringify({ user, ttl_seconds: 3600 }),
    });
    if (!res.ok) throw new Error(`dev-token: ${res.status}`);
    return ((await res.json()) as { token: string }).token;
  };
 
  const connect = async (token: string) => {
    const socket = new WebSocket(`${url}/v1/ws?token=${token}`);
    sockets.push(socket);
    await firstFrame(socket, "connection.ack");
    return socket;
  };
 
  const frameSend = async (socket: WebSocket, text: string) => {
    socket.send(
      JSON.stringify({
        type: "message.send",
        payload: { channel: api.channelId, text, idem_key: randomUUID() },
      }),
    );
  };
 
  const restSend = (text: string) =>
    fetch(`${api.url}/v1/channels/${api.channelId}/messages`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        authorization: `Bearer ${api.credential}`,
        "idempotency-key": randomUUID(),
      },
      body: JSON.stringify({ text, user: "meter" }),
    });
 
  beforeAll(async () => {
    api = await startApi();
    limits = createGatewayLimits(REDIS_URL);
    redis = new Redis(REDIS_URL);
    server = serve({
      service: "gateway",
      health: () => ({}),
      logger: silent,
      // REQUIRED IN THIS TREE. The error-registry chapter made `serve` take the
      // not-found link from `docsUrl` rather than spelling it, and it is upstream of
      // this chapter here where it was downstream in the published order.
      notFoundDocsUrl: docsUrl("not_found"),
    });
    attachSessions({
      server,
      api: createApiClient(api.url),
      logger: silent,
      limits,
    });
    await new Promise<void>((resolve) => server.listen(0, resolve));
    url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}`;
  }, 60_000);
 
  beforeEach(() => {
    // Where `count()` starts summing, and where `afterEach` starts deleting.
    testStartedAt = Date.now();
  });
 
  beforeEach(() => {
    // Where `count()` starts summing, and where `afterEach` starts deleting.
    testStartedAt = Date.now();
  });
 
  afterEach(async () => {
    for (const socket of sockets.splice(0)) socket.close();
    // Every test starts from an empty bucket and the documented defaults.
    // Otherwise the first test's traffic is the second test's head start, and
    // the window is a minute long.
    await redis.del(key("rest"), key("send"), key("connect"));
    await api.setLimits({});
  });
 
  afterAll(async () => {
    server.close();
    await limits.close();
    redis.disconnect();
    api.stop();
  });
 
  it("counts a socket send ONCE, against the api's own key (FR-RTL-01)", async () => {
    // Not twice — the gateway's internal call to `/v1/... ` is exempt BY ROUTE,
    // so the frame is counted by the gateway and not again when its HTTP hop
    // lands. And not zero times, which is what an exemption applied one layer
    // too broadly would produce.
    //
    // FR-RTL-01 is the clause: the limit is PER TENANT, and the gateway's hop is
    // the platform's own traffic on the tenant's behalf. (An id sweep put
    // `FR-WHK-05` here — *"webhook delivery shall be asynchronous"* — which is a
    // real clause about something else entirely. A mechanical substitution that
    // has no id to map to picks the nearest one it does have.)
    const socket = await connect(await mintToken());
    const before = await count("send");
    await frameSend(socket, "one");
    await firstFrame(socket, "message.ack");
    expect(await count("send")).toBe(before + 1);
  });
 
  it("spends ONE budget across both transports (FR-RTL-01, research R11)", async () => {
    // Five over REST and five over the socket. If the two services were
    // counting separately this would read 5 and 5.
    const socket = await connect(await mintToken());
    for (let i = 0; i < 5; i += 1) {
      const res = await restSend(`rest-${i}`);
      expect(res.status).toBe(201);
    }
    for (let i = 0; i < 5; i += 1) {
      await frameSend(socket, `frame-${i}`);
      await firstFrame(socket, "message.ack");
    }
    expect(await count("send")).toBe(10);
    // The REQUEST budget saw only the five REST calls: a frame is not an HTTP
    // request, and the gateway's hop to the api does not count as one either.
    // THE ASYMMETRY IS THE WHOLE TEST, and only two transports can show it: on one
    // transport alone the two counters move together, and a limiter counting
    // requests is indistinguishable from one counting messages (FR-RTL-01).
    expect(await count("rest")).toBe(5);
  });
 
  it("reports the budget with FEWER remaining, not the one that was asked about", async () => {
    // Two budgets, one set of headers. A client that saw only the request
    // budget would be told it had 595 left while the send budget it is actually
    // spending had 590 — an answer that is true and useless.
    await api.setLimits({ rest: 100, send: 20 });
    const socket = await connect(await mintToken());
    for (let i = 0; i < 5; i += 1) {
      await frameSend(socket, `frame-${i}`);
      await firstFrame(socket, "message.ack");
    }
    const res = await restSend("rest-after-frames");
    expect(res.status).toBe(201);
    // send: 5 frames + this one = 6 of 20, so 14 left. rest: 1 of 100, 99 left.
    expect(res.headers.get("x-ratelimit-limit")).toBe("20");
    expect(res.headers.get("x-ratelimit-remaining")).toBe("14");
  });
 
  it("names the limit that was reached when it refuses (FR-RTL-01)", async () => {
    await api.setLimits({ rest: 100, send: 2 });
    await restSend("one");
    await restSend("two");
    const refused = await restSend("three");
    expect(refused.status).toBe(429);
    const body = (await refused.json()) as { code: string; message: string };
    expect(body.code).toBe("rate_limited");
    // "you are rate limited" leaves a developer guessing which dial to turn.
    // The wording names the UNIT rather than the column: "too many messages"
    // says slow down, "too many requests" says batch. This traffic was three
    // sends against a send limit of two, so it has to be the first.
    expect(body.message).toMatch(/too many messages/);
    expect(body.message).not.toMatch(/too many requests/);
  });
 
  it("lets the gateway through an environment that is at its REST limit (FR-RTL-01)", async () => {
    // The exemption cannot key off the principal: the gateway forwards the END
    // USER's token, so its session and send calls resolve to `kind: "user"`
    // exactly like customer traffic. A rule that exempted only the platform
    // credential would refuse them — and the socket would go down for a REST
    // budget it never spends (research R17).
    await api.setLimits({ rest: 1 });
    expect((await restSend("the one allowed request")).status).toBe(201);
    expect((await restSend("over")).status).toBe(429);
 
    // The environment is over its REST limit. The socket still opens…
    const socket = await connect(await mintToken());
    // …and still sends, because a frame spends the SEND budget and the
    // gateway's hop to the api spends nothing.
    await frameSend(socket, "through the closed door");
    expect(await firstFrame(socket, "message.ack")).toMatchObject({
      type: "message.ack",
    });
  });
});

@@ -139,29 +139,57 @@ describe("every fabric createServer builds is injected", () => {
   // a property of the text — every module built above the call appears inside it.
   const SOURCE = readFileSync(
     join(import.meta.dirname, "main.ts"),
     "utf8",
   );
 
-  /** `const x = createY({` — the fabrics, derived rather than listed, so a fifth
-   * arrives here without anyone remembering. */
+  /** `const x = createY(` — the fabrics, derived rather than listed, so a sixth
+   * arrives here without anyone remembering.
+   *
+   * TWO CHANGES, AND THE FIRST ONE MISSED A MODULE. The pattern required an OBJECT
+   * ARGUMENT — `create[A-Z]\w*\(\{` — and the counter store takes none:
+   * `createGatewayLimits()` reads its url from the environment. So the ninth Redis
+   * client in this file was invisible to the check written to make exactly that
+   * impossible, and it was invisible in the direction that passes. Measured: the old
+   * pattern derives five names, the new one six.
+   *
+   * SCOPED TO `createServer`'S BODY, which is what this describe's title always
+   * claimed. Dropping the `{` widens the match to `createLogger` and `createServer`
+   * in the `import.meta.main` block below the function — neither a fabric, both
+   * `const x = createY(`. Slicing to the text between the function and the call it
+   * has to appear in is the honest boundary; an exclusion list would be the thing
+   * this file exists instead of. */
   function built(): string[] {
-    return [...SOURCE.matchAll(/\bconst (\w+) = create[A-Z]\w*\(\{/g)].map((m) => m[1]!);
+    const start = SOURCE.indexOf("export function createServer");
+    const end = SOURCE.indexOf("attachSessions({", start);
+    return [...SOURCE.slice(start, end).matchAll(/\bconst (\w+) = create[A-Z]\w*\(/g)]
+      .map((m) => m[1]!);
   }
 
   /** The object literal `attachSessions` is called with. */
   function injected(): string {
     const open = SOURCE.indexOf("attachSessions({");
     const close = SOURCE.indexOf("\n  });", open);
     return SOURCE.slice(open, close);
   }
 
   it("derives the fabrics and the call, and finds both", () => {
     // THE POSITIVE CONTROL. Every assertion below is about which names are missing,
     // and a derivation that found nothing satisfies all of them.
-    expect(built().length, "no `const x = createY({` found in main.ts").toBeGreaterThan(1);
+    expect(built().length, "no `const x = createY(` found in main.ts").toBeGreaterThan(1);
+    // AND THE COUNT, because "more than one" was satisfied by a pattern that found
+    // five of six. A number here goes red when a fabric is added without a thought
+    // about this file, which is the moment to have it.
+    expect(built(), "the fabrics createServer builds").toEqual([
+      "fanout",
+      "presence",
+      "membership",
+      "typing",
+      "connections",
+      "limits",
+    ]);
     expect(injected(), "no attachSessions call found").toContain("server,");
   });
 
   it("passes each one into attachSessions", () => {
     const call = injected();
     const missing = built().filter(

for (const text of source) {
  expect(text).not.toMatch(/close\(\s*400[89]/);
}
expect(source.join("")).toMatch(/close\(\s*400[12]/);

expect(await foreign.json()).toEqual(await missing.json());

@@ -9,17 +9,32 @@
  * freeze today's status choices into a test, so a considered change to a status breaks
  * a security suite for no security reason. It would say nothing about the body. And it
  * would PASS AN ENDPOINT THAT LEAKS THROUGH ITS PROSE — an error message that echoes
  * the identifier back makes the foreign answer differ from the absent one while both
  * are 404, which is exactly the leak constitution I is about.
  *
- * So status and whole body are compared. There is nothing to exclude from the
- * comparison yet: the error envelope is `code`, `message` and `docs_url`, all three of
- * which must match. When a per-request field joins it, the chapter that adds it owns
- * the decision to drop it here — and it will have to argue that the field reveals
- * nothing about the resource. */
+ * So status and body are compared — and ONE FIELD IS EXCLUDED, which the paragraph
+ * this replaces asked the next chapter to argue for. It said: *"There is nothing to
+ * exclude from the comparison yet … when a per-request field joins it, the chapter
+ * that adds it owns the decision to drop it here — and it will have to argue that the
+ * field reveals nothing about the resource."*
+ *
+ * THE ARGUMENT. `request_id` is minted per request, so two requests never carry the
+ * same one and a whole-body comparison of any two answers fails for a reason that has
+ * nothing to do with tenancy. It is also the one field in the envelope that is not
+ * derived from the resource at all: `code`, `message` and `docs_url` are answers about
+ * what was asked for, and the id is an answer about the asking. Dropping it removes no
+ * leak, because there is nothing in it to leak.
+ *
+ * AND THE INSTRUCTION IS WHY THIS WAS ONE LINE RATHER THAN A DEBUGGING SESSION. The
+ * field's arrival turned twenty-two attacks and one channel-surface test red at once,
+ * every one of them with two identical bodies and two different ids. The file that
+ * broke had already written down what to do about it, in the place the reader of the
+ * failure would land. */
+
+import { withoutRequestId } from "./compare";
 
 export interface AttackRequest {
   method: string;
   /** Path with identifiers already substituted — `/v1/channels/<uuid>/messages`. */
   path: string;
   body?: unknown;
@@ -73,14 +88,17 @@ export async function send(
  * `classifyRow`: an instrument that has never fired is an untested instrument. */
 export function comparePair(foreign: Answer, absent: Answer): string[] {
   const differences: string[] = [];
   if (foreign.status !== absent.status) {
     differences.push(`status ${foreign.status} (foreign) vs ${absent.status} (absent)`);
   }
-  const f = JSON.stringify(foreign.body);
-  const a = JSON.stringify(absent.body);
+  const f = JSON.stringify(withoutRequestId(foreign.body));
+  const a = JSON.stringify(withoutRequestId(absent.body));
+  // REPORTED WITHOUT THE ID TOO, not merely compared without it. A message that
+  // printed the raw bodies would show two ids differing on every real failure and
+  // send the reader after the field this function has just decided to ignore.
   if (f !== a) differences.push(`body ${f} (foreign) vs ${a} (absent)`);
   return differences;
 }
 
 /** A read of another tenant's resource must answer as a read of nothing. */
 /** A list's correct answer to "nothing of yours here" is an EMPTY RESULT, and that

@@ -197,17 +197,19 @@ describe("the public channel surface", () => {
 
     it("answers a foreign channel id exactly as an absent one (FR-018)", async () => {
       const absent = "00000000-0000-4000-8000-000000000000";
       const foreign = await addMembers(foreignChannelId, { user_ids: ["intruder"] });
       const nowhere = await addMembers(absent, { user_ids: ["intruder"] });
       expect(foreign.status).toBe(nowhere.status);
-      // COMPARED WHOLE. The envelope is `code`, `message` and `docs_url`, and all
-      // three must match for a foreign channel to be indistinguishable from an absent
-      // one. Nothing here is per-request yet, so nothing is excluded.
-      expect(await foreign.json()).toEqual(
-        await nowhere.json(),
+      // COMPARED WHOLE EXCEPT THE ID, and this line asked for that in advance: it read
+      // *"nothing here is per-request yet, so nothing is excluded"* until the limits
+      // chapter put `request_id` in the envelope. `code`, `message` and `docs_url` are
+      // answers about the resource and all three must match; the id is an answer about
+      // the request and never matches.
+      expect(withoutRequestId(await foreign.json())).toEqual(
+        withoutRequestId(await nowhere.json()),
       );
       // And the other tenant's channel gained nobody. Read through ITS OWN
       // repository — a repository scoped to the empty string is not a scope, it is
       // a query that fails on an invalid uuid, which is how this line read first.
       expect(await foreignRepo.listMembers(foreignChannelId)).toEqual([]);
     });

@@ -20,12 +20,13 @@ import { createLogger, serve, type Logger } from "@relay/service-kit";
 import { Redis } from "ioredis";
 import { afterEach, describe, expect, it } from "vitest";
 import { WebSocket } from "ws";
 
 import type { ApiClient } from "./api-client.js";
 import { createFanout } from "./fanout.js";
+import type { Decision, GatewayLimits } from "./limits.js";
 import { createMembership, type Membership } from "./membership.js";
 import { createPresence } from "./presence.js";
 import { attachSessions } from "./session.js";
 import { createTyping, type Typing } from "./typing.js";
 
 // The typing chapter's fabric, against a REAL Redis.
@@ -85,12 +86,16 @@ async function boot(options: {
   /** Points this instance's fabric at a proxy instead of Redis, so a test can
    * sever the connection without touching anything shared. */
   redisUrl?: string;
   /** T072 only: the other three fabrics, so one watcher can receive all four
    * kinds over the same channel. */
   allFabrics?: boolean;
+  /** T048b only: a RECORDING double for the send limiter, so a test can assert
+   * which operations the session layer asked it to spend. Not wired by default —
+   * every other test in this file is about delivery. */
+  limits?: GatewayLimits;
 }): Promise<Instance> {
   const environment = options.environment ?? "env-1";
   const logger =
     options.lines === undefined
       ? silent
       : createLogger("gateway", (line: string) => {
@@ -107,12 +112,16 @@ async function boot(options: {
     session: async () => ({
       environment_id: environment,
       user: options.user,
       banned: false,
       channel_ids: options.channels,
       revisions: {},
+      // The limits ride this response as of the limits chapter, and this fixture is
+      // generous on purpose: T048b below asserts that a typing signal spends NO send
+      // budget, and a tight number here would make that pass for the wrong reason.
+      limits: { connect: 3_000, send: 600 },
     }),
     memberships: async () => options.channels,
     backfill: async () => {
       if (options.backfillDelayMs !== undefined) {
         await new Promise((r) => setTimeout(r, options.backfillDelayMs));
       }
@@ -137,12 +146,13 @@ async function boot(options: {
     ...(fanout === undefined ? {} : { fanout }),
     ...(presence === undefined ? {} : { presence }),
     ...(membership === undefined ? {} : { membership }),
     ...(options.renewalIntervalMs === undefined
       ? {}
       : { renewalIntervalMs: options.renewalIntervalMs }),
+    ...(options.limits === undefined ? {} : { limits: options.limits }),
   });
   await new Promise<void>((resolve) => server.listen(0, resolve));
   const { port } = server.address() as AddressInfo;
   return {
     url: `ws://127.0.0.1:${port}/v1/ws`,
     typing,
@@ -627,12 +637,65 @@ describe("a typing signal on its way out", () => {
     expect(frames).toHaveLength(afterSignal);
 
     // And the fabric is still alive, so the silence above was a decision.
     signaller.send(JSON.stringify({ type: "typing.send", payload: { channel } }));
     expect(await untilTyping(frames, channel, 2)).toHaveLength(2);
   }, 15_000);
+
+  /** T048b. A TYPING SIGNAL SPENDS NO MESSAGE QUOTA (FR-014).
+   *
+   * **Moved out of US3 by analysis pass 1**, and the reason is worth keeping:
+   * leaving it in a P2 story meant stopping after the MVP could ship a cosmetic
+   * feature able to exhaust a customer's message budget. A client holding a key
+   * down is not sending messages, and a limiter that thought otherwise would let
+   * an indicator empty a budget the customer pays for.
+   *
+   * **ASSERTED ON THE LIMITER, NOT ON A COUNTER.** The requirement is that the
+   * typing branch never REACHES `limits.spend` — it returns above it — and a
+   * recording double says exactly that. A counter read out of Redis would also
+   * pass against a branch that spent and then refunded, which satisfies "the
+   * count did not move" and not "the call was never made".
+   *
+   * **AND IN THIS ORDER THE PROPERTY WAS TRUE BEFORE IT WAS TESTABLE.**
+   * `session.ts` has returned from `typing.send` above everything for nine
+   * chapters; until the limiter arrived underneath it there was nothing below to
+   * reach. So this test does not merely arrive late — it is the first moment the
+   * early return can be said to matter, and it is what stands between a typing
+   * indicator and a customer's message budget from here on. */
+  it("never reaches the send limiter, however many signals arrive", async () => {
+    const channel = randomUUID();
+    const spends: string[] = [];
+    const limits: GatewayLimits = {
+      spend: async (_environmentId, operation): Promise<Decision> => {
+        spends.push(operation);
+        return {
+          over: false,
+          limit: 600,
+          remaining: 599,
+          resetSeconds: Math.floor(Date.now() / 1000) + 60,
+          retryAfterSeconds: 1,
+        };
+      },
+      close: async () => {},
+    };
+    const instance = await boot({ user: "tuan", channels: [channel], limits });
+    open.push(instance.close);
+
+    const socket = connect(instance);
+    await acked(socket);
+    // The handshake spends `connect`, and recording it here is what makes the
+    // assertion below a claim about `send` rather than about an unwired double.
+    expect(spends).toEqual(["connect"]);
+
+    for (let i = 0; i < 5; i += 1) {
+      socket.send(JSON.stringify({ type: "typing.send", payload: { channel } }));
+    }
+    await settle();
+
+    expect(spends.filter((op) => op === "send")).toEqual([]);
+  });
   /** T048c. THE MID-CONNECTION JOIN (FR-004a).
    *
    * **The obvious test — a member who was in the channel at connect — passes
    * against an implementation that never touches the membership-revocation chapter's `added`
    * branch.** So this one connects first, joins second, and signals third.
    *

{ "error": { "code": "…", "message": "…", "docs_url": "…" } }

// The limit policy: what each environment is allowed, and what each number rests
// on (research R26).
//
// R4 chose all four of these by judgement and checked none of them against a
// document stating this platform's scale. The fourteenth analysis pass read the
// SRS's NFR tables and found that one of them made a P1 requirement unreachable,
// so all four were re-derived rather than the broken one patched.
//
// WHAT WENT WRONG IS WORTH KEEPING. The connect limit was 60/min, on the
// reasoning that "sixty establishments a minute per environment is a client
// reconnecting hard, not a client working". True of a client. The limit is per
// ENVIRONMENT, and an environment is a tenant — NFR-SCL-01 puts ten thousand
// concurrent connections on one gateway instance and FR-RTM-09 allows five per
// user, so filling one instance from cold would have taken 167 minutes.
//
// Each number below names what it rests on, including the one that rests on
// nothing. That is the actual fix; the new value is a consequence of it.
 
/** Per environment, per minute. Overridable per environment (FR-RTL-04);
 * these apply when a column is null, which means "no override" and never zero —
 * refuse-everything has to stay expressible. */
export const DEFAULT_LIMITS = {
  /** NO ANCHOR, and recorded as such. No SRS requirement caps a tenant's request
   * rate; NFR-PRF-02's p95 under 150 ms is a latency target, not a throughput
   * bound. Matched to the send limit because a REST send consumes both budgets
   * (FR-RTL-01), and two different ceilings on one operation would mean a client
   * hitting one while the other says it has room. */
  rest: 600,
 
  /** 1% of NFR-SCL-03's stated 1,000 messages per second aggregate — 60,000 a
   * minute across the platform. So a hundred environments at their ceiling
   * saturate it, and the hundred-and-first is what this protects. */
  send: 600,
 
  /** NFR-SCL-01's ten thousand connections per gateway instance, divided by
   * FR-RTM-09's five per user, re-established inside one window so a deploy stays
   * one reconnection cycle (NFR-REL-03).
   *
   * IT IS STILL A LIMIT. Its job is to stop a client reconnecting in a tight
   * loop, which does thousands a minute and is refused well before a legitimate
   * fleet is. It is not there to shape a tenant's capacity, and the old number
   * had those two jobs confused. */
  connect: 3_000,
} as const;
 
export type LimitedOperation = keyof typeof DEFAULT_LIMITS;
 
/** Failed authentications per source address per minute.
 *
 * NOT a per-environment column: the caller has not proved which environment they
 * are, which is the point of the limiter. Configuration, and configuration the
 * lane has to be able to raise — the api's own integration suites assert `401`
 * twenty-six times from one loopback address inside about 110 seconds, so a
 * threshold nothing could lift would refuse this project's own tests
 * (research R15).
 *
 * THE DEFAULT ENFORCES. THE RETRY-AND-DISABLE CHAPTER'S `RELAY_DISABLE_SWEEP` states the rule: a
 * flag whose default disabled a requirement would be a requirement nobody had
 * built.
 *
 * THE COST IT CARRIES, which R4 did not name: shared egress. An office behind one
 * NAT is one source address, so ten failed logins a minute is a whole building's
 * budget — and the refusal is deliberately indistinguishable from a wrong
 * credential (EIR-API-04), so they will experience it as a broken login. Kept anyway;
 * the alternative is a threshold high enough to be worthless against the attack
 * it exists for. */
export const DEFAULT_AUTH_FAILURES_PER_MINUTE = 10;
 
export function authFailureThreshold(): number {
  const raw = process.env["RELAY_AUTH_FAILURES_PER_MINUTE"];
  if (raw === undefined) return DEFAULT_AUTH_FAILURES_PER_MINUTE;
  const parsed = Number.parseInt(raw, 10);
  return Number.isFinite(parsed) && parsed > 0
    ? parsed
    : DEFAULT_AUTH_FAILURES_PER_MINUTE;
}
 
/** The window every counter uses. One minute, because every limit above is
 * expressed per minute and a second unit would be a second thing to reason
 * about. */
export const WINDOW_MS = 60_000;

// The in-process counter the AUTH limiter falls back to when Redis is gone
// (research R3).
//
// THE TENANT LIMITER FAILS OPEN AND THIS ONE MUST NOT, and that asymmetry is the
// chapter's whole argument. Both are the same mechanism; what differs is what is
// on the other side of the limit. The tenant limiter protects Relay's capacity
// from a customer's traffic, and over-serving a paying customer for the length of
// a cache outage costs some capacity. This one protects a customer's credentials
// from an attacker, and over-serving an attacker costs the customer their
// account.
//
// So neither of the two obvious answers is right. Failing open is unbounded — a
// hole rather than a degradation. Failing closed converts a Redis restart into an
// authentication outage, which is worse than the attack it prevents for every
// customer who is not being attacked. The third answer is this: count in memory,
// same threshold, and let the guarantee weaken from "N per window across the
// fleet" to "N per window per instance". Three api instances give an attacker
// three times the attempts for the duration of the outage — a small multiple
// rather than infinity.
//
// THE CAP IS PART OF THE DECISION, NOT A DETAIL. A map keyed by
// attacker-controlled source address is a memory-exhaustion vector if it is
// unbounded, and a fallback that closed a brute-force hole by opening a worse one
// would not be worth having.
//
// AND IT STOPS ADMITTING RATHER THAN EVICTING. An eviction policy on this map is
// a policy the attacker drives: fill it, evict the entry that was counting them,
// start again. Refusing new keys degrades to "addresses already being tracked
// stay tracked", which is the safe direction.
 
interface Entry {
  count: number;
  windowStart: number;
}
 
export interface FallbackCounter {
  /** Count one failure against a key, returning the new count — or `null` when
   * the key could not be admitted because the map is full. A caller that gets
   * `null` has learned nothing about that address and must not treat it as
   * "under the threshold". */
  increment(key: string, nowMs: number): number | null;
  /** The current count for a key WITHOUT adding to it, or `null` when the key is
   * not tracked and the map is full.
   *
   * `null` and `0` are different answers and the caller must tell them apart:
   * zero means "tracked, nothing counted", null means "we have no idea". While
   * degraded, refusing an address we cannot track is the safe direction, and the
   * cap makes that a bounded population rather than everybody. */
  peek(key: string, nowMs: number): number | null;
  /** Live keys. Exposed for the test that proves the bound holds. */
  size(): number;
}
 
export function createFallbackCounter({
  windowMs,
  maxKeys,
}: {
  windowMs: number;
  maxKeys: number;
}): FallbackCounter {
  const entries = new Map<string, Entry>();
 
  return {
    increment(key, nowMs) {
      const start = Math.floor(nowMs / windowMs) * windowMs;
      const existing = entries.get(key);
 
      if (existing !== undefined) {
        if (existing.windowStart === start) {
          existing.count += 1;
          return existing.count;
        }
        // Same key, new window: reuse the slot rather than counting against the
        // cap twice.
        existing.count = 1;
        existing.windowStart = start;
        return 1;
      }
 
      if (entries.size >= maxKeys) {
        // Sweep what the current window has already outlived before refusing.
        // The cap is on LIVE keys, not on keys ever seen — an outage lasting
        // hours must not permanently refuse to count anybody new.
        for (const [k, v] of entries) {
          if (v.windowStart !== start) entries.delete(k);
        }
      }
      if (entries.size >= maxKeys) return null;
 
      entries.set(key, { count: 1, windowStart: start });
      return 1;
    },
 
    peek(key, nowMs) {
      const start = Math.floor(nowMs / windowMs) * windowMs;
      const existing = entries.get(key);
      if (existing === undefined) {
        return entries.size >= maxKeys ? null : 0;
      }
      return existing.windowStart === start ? existing.count : 0;
    },
 
    size() {
      return entries.size;
    },
  };
}

import { Redis } from "ioredis";
 
import { WINDOW_MS } from "./policy";
 
// The counter store (research R1).
//
// THE ONLY MODULE IN THE API PERMITTED TO HOLD A REDIS CLIENT, enforced by
// `no-restricted-imports` in `eslint.config.mjs` — the same confinement the
// database driver has, for the same stated reason. The keys are per environment,
// so an unrestricted client would let any handler read or write another tenant's
// counter, and constitution I makes that a correctness property rather than a
// convention.
//
// TWO COMMANDS, NO LUA. `INCR` returns the new value atomically on its own, and
// `EXPIRE` is set only when the increment returns 1 — the first write of a
// window. A token bucket would need read-timestamp-compute-write, which across
// instances needs a script, which is a second language in the request path
// (constitution VII).
//
// The TTL does the cleanup: a key dies when its window ends and nothing
// accumulates. The deduplication chapter's baseline and this chapter's own both found suites
// broken by shared stores that grew without bound, so a counter that tidies
// itself is worth the sentence.
 
export interface CounterStore {
  /** Count one operation against a key, returning the new count — or `null` when
   * the store could not be reached.
   *
   * NULL IS NOT ZERO AND NOT AN ERROR. It means "we are not counting", and each
   * caller decides what that is worth: the tenant limiter serves the request
   * (SAD §6.3, Redis is not a source of truth), and the auth limiter falls back to
   * counting in memory rather than letting an attacker through (FR-AUT-12). Same
   * signal, opposite conclusions, which is the chapter's argument in one return
   * type. */
  increment(key: string, nowMs: number): Promise<number | null>;
  /** The current count without adding to it, or `null` when the store could not
   * be reached. Asking "is this address over the threshold" must not itself push
   * it over — a limiter whose check is also a write refuses on its own
   * questions. */
  get(key: string): Promise<number | null>;
  close(): Promise<void>;
}
 
export const DEFAULT_REDIS_URL = "redis://localhost:6379";
 
/** The key. `rl:` is the prefix the SAD's cache-keys table names; the operation and the
 * window's start are appended so one `INCR` reaches the right counter and the key
 * expires itself.
 *
 * That EXTENDS the SAD's three-segment `rl:{env}:{bucket}` rather than matching
 * it, and the extension is what makes the TTL do the cleanup. */
export function counterKey(
  scope: string,
  operation: string,
  windowStartMs: number,
): string {
  return `rl:${scope}:${operation}:${windowStartMs}`;
}
 
/** The auth counter's key, keyed by source address rather than environment.
 *
 * A SEPARATE PREFIX, not an `operation` value on the tenant key, because it is
 * keyed by something else entirely and because the two have opposite failure
 * behaviour. Sharing a prefix would invite sharing a code path, and the whole
 * point is that they must not.
 *
 * THE PREFIX IS OVERRIDABLE, and that is test isolation rather than
 * configuration. The integration lane runs files in PARALLEL — only the coverage
 * config sets `fileParallelism: false` — so every suite asserting a `401` from
 * loopback lands in one bucket. Raising a threshold survives that; a suite that
 * needs a LOW threshold needs its own key, or it compares a count filled by other
 * workers against a deliberately small number and refuses requests that had
 * nothing to do with it (research R21).
 *
 * The same pattern `attempts.itest.ts` uses for its durable name, and for the
 * same reason. */
export function authKey(
  address: string,
  windowStartMs: number,
  prefix: string = process.env["RELAY_AUTH_KEY_PREFIX"] ?? "rlauth",
): string {
  return `${prefix}:${address}:${windowStartMs}`;
}
 
export function createCounterStore(
  url: string = process.env["RELAY_REDIS_URL"] ?? DEFAULT_REDIS_URL,
): CounterStore {
  // `lazyConnect` so constructing the store never blocks start-up.
  //
  // THE OFFLINE QUEUE STAYS ON, and the first draft had it off. With it off, the
  // very first command is rejected because the lazy connection has not been
  // established yet — so the first request an api instance ever serves reports no
  // count, degrades, and looks like a Redis outage. The integration suite caught
  // it as `expected null to be '599'` on the first test and three passes after
  // it.
  //
  // Failing fast on a store that is genuinely down is then `maxRetriesPerRequest:
  // 0` and a short `connectTimeout`: a queued command rejects as soon as the
  // connection attempt fails rather than waiting out a retry schedule. A limiter
  // that waits is worse than one that does not count, because the request it is
  // holding is a customer's.
  const redis = new Redis(url, {
    lazyConnect: true,
    maxRetriesPerRequest: 0,
    connectTimeout: 1_000,
  });
 
  // FAILING OPEN IS NOT FREE IF IT FAILS SLOWLY, and the first version of this
  // file was slow. With the store gone, every command waits out its connect
  // timeout before giving up — so each request paid a second or more, twice,
  // and the integration test for the degraded path timed out rather than
  // asserting anything.
  //
  // That is worse than it looks. The tenant limiter fails open so a cache outage
  // does not refuse paid traffic; an outage that instead adds seconds to every
  // request has refused it in a slower way, and NFR-PRF-02 asks for a p95 under
  // 150 ms.
  //
  // So a known-down store is not retried on the request path. The first failure
  // opens a window; while it is open every call answers `null` immediately, which
  // is the same signal the caller already handles. One probe per window is what
  // notices the store coming back.
  const DOWN_WINDOW_MS = 5_000;
  let downUntil = 0;
 
  const guard = async <T>(op: () => Promise<T>): Promise<T | null> => {
    if (Date.now() < downUntil) return null;
    try {
      const result = await op();
      downUntil = 0;
      return result;
    } catch {
      downUntil = Date.now() + DOWN_WINDOW_MS;
      return null;
    }
  };
  // A dead store is an expected state here, not an exception. Without a listener
  // ioredis emits `error` on an EventEmitter with none attached, which Node turns
  // into an unhandled exception and the api dies for the thing it was designed to
  // survive.
  redis.on("error", () => {});
 
  return {
    async increment(key, nowMs) {
      void nowMs;
      return guard(async () => {
        const count = await redis.incr(key);
        if (count === 1) {
          await redis.pexpire(key, WINDOW_MS);
        }
        return count;
      });
    },
 
    async get(key) {
      return guard(async () => {
        const raw = await redis.get(key);
        return raw === null ? 0 : Number.parseInt(raw, 10);
      });
    },
 
    async close() {
      redis.disconnect();
    },
  };
}

import type { RequestWithPrincipal } from "../auth/principal";
 
// Whose failure was that? (FR-AUT-12, research R14.)
//
// THE API SEES THE GATEWAY, not the client. A WebSocket handshake is
// authenticated by the gateway forwarding the end user's token to
// `/internal/session`, so the TCP peer is the gateway for every customer at
// once. Counting the peer would put every customer's failed handshakes in one
// bucket, and one attacker would exhaust a threshold that then refused
// everybody.
//
// A FIELD ON THE INTERNAL CONTRACT, NOT A HEADER. A header the caller asserts is
// a header the caller can forge — the exact pattern the credentials chapter removed when it
// retired the two identity headers the gateway used to send. This one is
// accepted only from a caller already trusted enough to reach the internal
// routes, and it is trusted for exactly one thing: naming who was on the other
// end. The same request is trusted enough not to be throttled and not trusted to
// be the origin.
 
/** The field the gateway sets on its internal calls. Read from the parsed body
 * rather than a header, so an ordinary customer cannot set it. */
export const CLIENT_ADDRESS_FIELD = "client_address";
 
export function clientAddress(
  req: RequestWithPrincipal & {
    socket?: { remoteAddress?: string | undefined };
    body?: unknown;
  },
): string {
  const body = req.body;
  if (typeof body === "object" && body !== null) {
    const forwarded = (body as Record<string, unknown>)[CLIENT_ADDRESS_FIELD];
    if (typeof forwarded === "string" && forwarded.length > 0) {
      return forwarded;
    }
  }
  return req.socket?.remoteAddress ?? "unknown";
}

import { Inject, Injectable } from "@nestjs/common";
import type { Logger } from "@relay/service-kit";
 
import { LOGGER } from "../logger";
import { windowStart } from "./bucket";
import { createFallbackCounter } from "./fallback";
import { COUNTER_STORE } from "./limits.module";
import { authFailureThreshold, WINDOW_MS } from "./policy";
import { authKey, type CounterStore } from "./store";
 
// The limiter that counts FAILED AUTHENTICATIONS by source address
// (FR-AUT-12, research R3).
//
// THE ONE THAT MUST NOT FAIL OPEN, and that is the chapter's whole argument. The
// tenant limiter serves the request when Redis is gone, because Redis is not a
// source of truth and a cache outage is not a reason to refuse paid traffic. Run
// the same reasoning here and it gives the opposite answer: an unlimited window
// on failed logins is not a degradation, it is a hole.
//
// FAILING CLOSED IS NOT THE ANSWER EITHER — it turns a Redis restart into an
// authentication outage, which is worse than the attack it prevents for every
// customer who is not being attacked. So: an in-process fallback at the same
// threshold, weakening the guarantee from N per window across the fleet to N per
// window per instance. A small multiple rather than infinity.
//
// WHOSE ADDRESS. The client's, not the caller's. A handshake authenticated
// through the gateway reaches the api FROM the gateway, so counting the caller
// would put every customer's failures in one bucket and let one attacker exhaust
// a threshold that then refuses everybody (research R14).
 
/** Bounded, and the bound is the decision rather than a detail: this map is keyed
 * by attacker-controlled input, so unbounded it would be a memory-exhaustion
 * vector — a fallback that closed a brute-force hole by opening a worse one. */
const FALLBACK_MAX_KEYS = 10_000;
 
@Injectable()
export class AuthLimiter {
  private readonly fallback = createFallbackCounter({
    windowMs: WINDOW_MS,
    maxKeys: FALLBACK_MAX_KEYS,
  });
 
  private lastDegradationLog = 0;
 
  constructor(
    @Inject(COUNTER_STORE) private readonly store: CounterStore,
    @Inject(LOGGER) private readonly logger: Logger,
  ) {}
 
  /** Count one failed authentication. */
  async recordFailure(address: string): Promise<void> {
    const now = Date.now();
    const key = authKey(address, windowStart(now, WINDOW_MS));
    if ((await this.store.increment(key, now)) === null) {
      this.degradation();
      this.fallback.increment(address, now);
    }
  }
 
  /** Has this address already spent its allowance?
   *
   * READS WITHOUT COUNTING. A check that also writes would refuse on its own
   * questions, and this one runs on every request that presents a credential —
   * including the valid ones.
   *
   * When the shared store is unreachable it answers from the in-process count,
   * which is the whole point: the guarantee gets weaker, not absent. A key the
   * fallback could not admit answers `true` — refusing an address we cannot track
   * is the safe direction while degraded, and the cap makes that a bounded
   * population rather than everybody. */
  async isOverThreshold(address: string): Promise<boolean> {
    const now = Date.now();
    const threshold = authFailureThreshold();
    const shared = await this.store.get(
      authKey(address, windowStart(now, WINDOW_MS)),
    );
    if (shared !== null) return shared >= threshold;
 
    this.degradation();
    const local = this.fallback.peek(address, now);
    return local === null ? true : local >= threshold;
  }
 
  /** One line, rate limited at the logger. A Redis outage under load would
   * otherwise emit one per attempt, which is how one outage becomes two. No
   * credential and no address (NFR-SEC-06); the count of tracked addresses is
   * what an operator actually needs. */
  private degradation(): void {
    const now = Date.now();
    if (now - this.lastDegradationLog < 10_000) return;
    this.lastDegradationLog = now;
    this.logger.log("error", "limits.auth_degraded", {
      detail:
        "counter store unreachable; counting failed authentications in process",
      tracked: this.fallback.size(),
    });
  }
}

import type { IncomingMessage, ServerResponse } from "node:http";
 
import { Inject, Injectable, type NestMiddleware } from "@nestjs/common";
import type { Logger } from "@relay/service-kit";
 
import type { Db } from "../db/client";
import { environmentLimits } from "../db/repository";
import type { RequestWithPrincipal } from "../auth/principal";
import { LOGGER } from "../logger";
import { remaining, resetAt, windowStart } from "./bucket";
import { clientAddress } from "./client-address";
import { COUNTER_STORE, LIMITS_DB } from "./limits.module";
import { authFailureThreshold, WINDOW_MS, type LimitedOperation } from "./policy";
import { authKey, counterKey, type CounterStore } from "./store";
 
/** Read once per call site so a test that freezes time sees one instant. */
const now0 = (): number => Date.now();
 
// The tenant limiter (FR-RTL-01…04).
//
// MIDDLEWARE, NOT A GUARD, for two reasons. The credentials chapter's: Nest constructs
// request-scoped providers before the enhancer chain, so a guard cannot be the
// thing that resolves tenant scope. And one of its own: FR-RTL-02 wants the three
// headers on SUCCESSFUL responses, and a guard that returns `true` has no natural
// place to set a header on a response the handler has not produced yet.
//
// AFTER `AuthenticateMiddleware`, and the order is forced: the counters are keyed
// by environment and the environment comes from the credential.
//
// COUNT EACH OPERATION ONCE, AT THE DOOR IT ENTERED (research R17). The exemption
// cannot key off the principal, because the gateway forwards the END USER's token
// on all three of its api calls — `/internal/session`, `/internal/backfill`,
// `/internal/messages` are all `@Accepts("user")` and resolve exactly like
// customer traffic. Only the dispatcher carries the platform credential. So the
// route decides, not the caller:
//
//   /v1/…            counted. A message send decrements both budgets (FR-RTL-01).
//   /internal/…      not counted. The gateway already counted the handshake
//                    against `connect` and the frame against `send`; counting
//                    again here would charge the socket twice and make a
//                    reconnect storm eat a customer's request budget.
//   /healthz         never limited. Docker polls it every five seconds and
//                    `up -d --wait` depends on the answer; a limiter that can
//                    refuse it can stop a deployment.
 
const PUBLIC_PREFIX = "/v1/";
const SEND_PATH = /^\/v1\/channels\/[^/]+\/messages\/?$/;
/** Account creation, by ANALOGY with FR-AUT-12 rather than under it — that clause
 * is about failed AUTHENTICATION, and a signup is not an authentication at all. Same
 * key shape, same threshold, no clause of its own. Limited per SOURCE ADDRESS, because it has no
 * tenant to key on — that is the point of it — and an unlimited
 * account-creation route is not acceptable in a platform that limits everything
 * else. It also has no guard, so T027a's refusal cannot reach it. */
const SIGNUP_PATH = /^\/auth\/[^/]+\/(start|callback)\/?$/;
 
interface Decision {
  operation: LimitedOperation;
  limit: number;
  remaining: number;
  resetSeconds: number;
  refused: boolean;
  counted: boolean;
}
 
/** Which budgets a path spends. Empty means the route is not counted at all. */
export function operationsFor(
  method: string,
  path: string,
): LimitedOperation[] {
  if (!path.startsWith(PUBLIC_PREFIX)) return [];
  if (method === "POST" && SEND_PATH.test(path)) return ["rest", "send"];
  return ["rest"];
}
 
@Injectable()
export class RateLimitMiddleware implements NestMiddleware {
  constructor(
    @Inject(LIMITS_DB) private readonly db: Db,
    @Inject(COUNTER_STORE) private readonly store: CounterStore,
    @Inject(LOGGER) private readonly logger: Logger,
  ) {}
 
  async use(
    req: RequestWithPrincipal & IncomingMessage,
    res: ServerResponse,
    next: () => void,
  ): Promise<void> {
    // `originalUrl`, NOT `url`. Express rewrites `req.url` relative to the mount
    // point, and a middleware applied through `forRoutes("{*path}")` is mounted
    // at the match — so `req.url` is `/` for every request and the route rules
    // below would never match anything. Found by probe at implementation, and
    // the same read is why the request log recorded `/` for every request from
    // chapter 2.2 until this chapter fixed it.
    const raw =
      (req as unknown as { originalUrl?: string }).originalUrl ?? req.url ?? "/";
    const path = raw.split("?")[0] ?? "/";
    const operations = operationsFor(req.method ?? "GET", path);
    const principal = req.principal;
 
    // Account creation first: no tenant, no guard, so it is neither counted like
    // customer traffic nor refusable by `CredentialGuard`. Same counter family
    // and same threshold as failed authentication (FR-AUT-12, research R17).
    if (SIGNUP_PATH.test(path)) {
      const address = clientAddress(req);
      const count = await this.store.increment(
        authKey(address, windowStart(now0(), WINDOW_MS)) + ":signup",
        now0(),
      );
      if (count !== null && count > authFailureThreshold()) {
        res.statusCode = 429;
        res.setHeader("Retry-After", "60");
        res.setHeader("content-type", "application/json");
        res.end(
          JSON.stringify({
            code: "rate_limited",
            message: "too many sign-up attempts from this address; retry shortly",
            docs_url: "https://relay.example/docs/errors/rate_limited",
            request_id: String(res.getHeader("X-Request-Id") ?? ""),
          }),
        );
        return;
      }
      next();
      return;
    }
 
    // An environment to key on, or nothing to do. A platform principal has none
    // by construction — the dispatcher's credential belongs to a deployment, not
    // a tenant — and an absent principal means the guard is about to refuse this
    // or the route is pre-credential.
    const environmentId =
      principal !== undefined && "environmentId" in principal
        ? principal.environmentId
        : undefined;
    if (operations.length === 0 || environmentId === undefined) {
      next();
      return;
    }
 
    const limits = await environmentLimits(this.db, environmentId);
    if (limits === null) {
      next();
      return;
    }
 
    const now = Date.now();
    const start = windowStart(now, WINDOW_MS);
    const resetSeconds = Math.ceil(resetAt(now, WINDOW_MS) / 1000);
    const decisions: Decision[] = [];
 
    for (const operation of operations) {
      const limit = limits[operation];
      const count = await this.store.increment(
        counterKey(environmentId, operation, start),
        now,
      );
      decisions.push({
        operation,
        limit,
        remaining: count === null ? limit : remaining(count, limit),
        resetSeconds,
        refused: count !== null && count > limit,
        counted: count !== null,
      });
    }
 
    const refusal = decisions.find((d) => d.refused);
 
    // THE HEADERS DESCRIBE WHICHEVER HAS FEWER REMAINING, because that is the one
    // that will refuse first and the only value a client can schedule against. A
    // client with 400 request-slots and 12 send-slots needs to hear 12; reporting
    // 400 would be a header that lies by omission. A tie reports the first, which
    // is `rest` (research R11).
    //
    // EXCEPT WHEN ONE OF THEM ACTUALLY REFUSED, and that exception was found by
    // capturing the transcript rather than by a test. Both budgets can reach
    // zero remaining in the same request while only one of them is over: with
    // `rest` at 3 and `send` at 2, the third send leaves both at zero remaining
    // and only `send` refused. "Fewest remaining" then picks `rest` on the tie,
    // and the response says `X-RateLimit-Limit: 3` above a body reading "too many
    // messages" — two numbers describing different budgets in one refusal
    // (research R41). A refusal describes the budget that refused.
    const nearest =
      refusal ?? decisions.reduce((a, b) => (b.remaining < a.remaining ? b : a));
    const degraded = decisions.some((d) => !d.counted);
 
    res.setHeader("X-RateLimit-Limit", String(nearest.limit));
    if (degraded) {
      // `Limit` only. It is policy read from Postgres and is not degraded; the
      // other two exist only because something was counting, and inventing them
      // is the failure FR-RTL-02 forbids. NOT a sentinel — a client that does not
      // know `-1` would parse it as a number and conclude it was over its limit
      // (research R6).
      this.degradation(environmentId, req);
    } else {
      res.setHeader("X-RateLimit-Remaining", String(nearest.remaining));
      res.setHeader("X-RateLimit-Reset", String(nearest.resetSeconds));
    }
 
    if (refusal !== undefined) {
      const retryAfter = Math.max(1, refusal.resetSeconds - Math.floor(now / 1000));
      res.setHeader("Retry-After", String(retryAfter));
      res.setHeader("X-RateLimit-Remaining", "0");
      // The message names WHICH limit was reached: "too many requests" and "too
      // many messages" are different problems, one saying batch and the other
      // saying slow down. Neither names a credential (NFR-SEC-06).
      const what =
        refusal.operation === "send" ? "messages" : "requests";
      res.statusCode = 429;
      res.setHeader("content-type", "application/json");
      res.end(
        JSON.stringify({
          code: "rate_limited",
          message: `too many ${what} for this environment; retry after ${retryAfter} seconds`,
          docs_url: "https://relay.example/docs/errors/rate_limited",
          request_id: String(res.getHeader("X-Request-Id") ?? ""),
        }),
      );
      return;
    }
 
    next();
  }
 
  private lastDegradationLog = 0;
 
  /** One line, rate limited at the logger. A Redis outage under load would
   * otherwise emit one per request, which is how one outage becomes two. Carries
   * the request id and the environment — NFR-OBS-01 asks for request id, tenant
   * id and correlation id, and the platform mints no correlation id yet. Carries
   * no credential (NFR-SEC-06). */
  private degradation(environmentId: string, req: IncomingMessage): void {
    const now = Date.now();
    if (now - this.lastDegradationLog < 10_000) return;
    this.lastDegradationLog = now;
    void req;
    // `error`, not `info`: the limiter is doing the right thing by serving, and
    // an unreachable store is still an operational fault somebody should see.
    // The logger's two levels are the service-kit's, unchanged since 1.4.
    this.logger.log("error", "limits.degraded", {
      environment_id: environmentId,
      detail: "counter store unreachable; serving without counting",
    });
  }
}

import { Redis } from "ioredis";
 
// The gateway's counter (research R12, R20).
//
// ITS OWN CLIENT, not fanout's, and that is forced rather than preferred.
// `Fanout` is a closed interface — `onDelivery`, `publish`, `subscribe`,
// `unsubscribe`, `close` — and exposes neither of the two clients it holds. One
// of them is a SUBSCRIBER, and a Redis connection in subscribe mode cannot run
// `INCR`. And `fanout` is optional in the session server, so a limiter riding its
// lifecycle would vanish in every configuration that has no fabric — which is
// every chapter-2.5 test.
//
// So: one more client, and a `close()` the session server calls. `fanout.ts`
// already sets that precedent for this service.
//
// THE SAME KEYS THE API USES. Two services increment one bucket, which is why
// the counter lives in Redis rather than in either process: neither can see the
// other's memory, and a socket send has to count against the same `send` budget a
// REST send does or a client could double its allowance by opening a socket
// (research R11).
 
export const DEFAULT_REDIS_URL = "redis://localhost:6379";
 
/** The window an instant belongs to. Floored, so two instances agree without
 * coordinating — the same arithmetic as the api's, deliberately duplicated
 * rather than shared: a package for two small functions would be an abstraction
 * constitution VII asks to be justified, and this one could not be. */
export function windowStartFor(nowMs: number, windowMs: number): number {
  return Math.floor(nowMs / windowMs) * windowMs;
}
 
/** Is this count past the allowance?
 *
 * `null` — the store could not be reached — is NOT over. Both of the gateway's
 * limits are tenant limits, so they fail open like the api's: Redis is not a
 * source of truth, and a cache outage is not a reason to refuse a paying
 * customer's traffic. */
export function overLimit(count: number | null, limit: number): boolean {
  if (count === null) return false;
  return count > limit;
}
 
/** What one counted operation decided, and everything a refusal has to say.
 *
 * The api reports the same four numbers in three headers plus `Retry-After`;
 * the gateway needs them for the handshake refusal, which IS an HTTP response
 * and can carry headers. The frame refusal cannot — there is nowhere on an
 * `error` frame to put them — which is why the socket's two refusals do not
 * look alike (research R7). */
export interface Decision {
  over: boolean;
  limit: number;
  remaining: number;
  /** Unix seconds, matching `X-RateLimit-Reset`. */
  resetSeconds: number;
  /** Whole seconds until the window turns over, for `Retry-After`. At least 1:
   * `Retry-After: 0` invites an immediate retry that is certain to fail. */
  retryAfterSeconds: number;
}
 
/** The arithmetic, with no store in it — so a window boundary is a test rather
 * than a wait. A `null` count means the store could not be reached. */
export function decide(
  count: number | null,
  limit: number,
  nowMs: number,
  windowMs: number,
): Decision {
  const reset = windowStartFor(nowMs, windowMs) + windowMs;
  return {
    over: overLimit(count, limit),
    limit,
    remaining: Math.max(0, limit - (count ?? 0)),
    resetSeconds: Math.ceil(reset / 1_000),
    retryAfterSeconds: Math.max(1, Math.ceil((reset - nowMs) / 1_000)),
  };
}
 
export interface GatewayLimits {
  /** Count one operation and report what that decided. */
  spend(
    environmentId: string,
    operation: "connect" | "send",
    limit: number,
  ): Promise<Decision>;
  close(): Promise<void>;
}
 
const WINDOW_MS = 60_000;
const DOWN_WINDOW_MS = 5_000;
 
export function createGatewayLimits(
  url: string = process.env["RELAY_REDIS_URL"] ?? DEFAULT_REDIS_URL,
): GatewayLimits {
  const redis = new Redis(url, {
    lazyConnect: true,
    maxRetriesPerRequest: 0,
    connectTimeout: 1_000,
  });
  // A dead store is an expected state, not an exception. Without a listener
  // ioredis emits `error` on an EventEmitter with none attached and Node turns
  // that into an unhandled exception — the gateway would die for the thing it is
  // designed to survive.
  redis.on("error", () => {});
 
  // A known-down store is not retried on the connect path. Waiting out a connect
  // timeout per handshake would turn a cache outage into a slow one, and
  // NFR-PRF-04 asks for a handshake under a second (research R34).
  let downUntil = 0;
 
  return {
    async spend(environmentId, operation, limit) {
      const now = Date.now();
      if (now < downUntil) return decide(null, limit, now, WINDOW_MS);
      const key = `rl:${environmentId}:${operation}:${windowStartFor(now, WINDOW_MS)}`;
      try {
        const count = await redis.incr(key);
        if (count === 1) await redis.pexpire(key, WINDOW_MS);
        downUntil = 0;
        return decide(count, limit, now, WINDOW_MS);
      } catch {
        downUntil = now + DOWN_WINDOW_MS;
        return decide(null, limit, now, WINDOW_MS);
      }
    },
 
    async close() {
      redis.disconnect();
    },
  };
}

import { Inject, Injectable, Module, type OnModuleDestroy } from "@nestjs/common";
 
import { createDb, createPool, type Db } from "../db/client";
import { apiLogger, LOGGER } from "../logger";
import { createCounterStore, type CounterStore } from "./store";
 
// The counter store's home.
//
// It is a module for one reason: the client has to be closed. Every long-lived
// resource in this api closes through `OnModuleDestroy` — the outbox relay, the
// delivery relay, the event consumer — `main.ts` enables shutdown hooks, and
// every api integration suite ends `await app.close()`.
//
// An ioredis client holds the event loop open. Without the hook the suites would
// HANG AFTER THEIR ASSERTIONS PASS, which is the worst shape available: green
// tests and a lane that never returns, in a project that has spent three chapters
// clearing one (research R20).
 
export const COUNTER_STORE = "COUNTER_STORE";
/** The limiter's own pool. Its own rather than the auth middleware's, because a
 * middleware that had to be handed another middleware's connection would couple
 * two things that only share a request. */
export const LIMITS_DB = "LIMITS_DB";
 
@Injectable()
export class CounterStoreLifecycle implements OnModuleDestroy {
  constructor(@Inject(COUNTER_STORE) private readonly store: CounterStore) {}
 
  async onModuleDestroy(): Promise<void> {
    await this.store.close();
  }
}
 
@Module({
  providers: [
    { provide: COUNTER_STORE, useFactory: (): CounterStore => createCounterStore() },
    { provide: LIMITS_DB, useFactory: (): Db => createDb(createPool()) },
    // Exported so the auth limiter can be constructed inside `AuthModule`, which
    // imports this one. `AppModule` provides the same token for everything else;
    // the factory is shared so both are the same kind of logger, and the DI
    // bargain ADR-15 buys — a test swaps the sink by overriding one provider —
    // holds in both places.
    { provide: LOGGER, useFactory: apiLogger },
    CounterStoreLifecycle,
  ],
  exports: [COUNTER_STORE, LIMITS_DB, LOGGER],
})
export class LimitsModule {}

import { describe, expect, it } from "vitest";
 
import { remaining, resetAt, windowStart } from "./bucket";
 
// The fixed-window arithmetic (research R1). Pure: no store, no
// clock of its own — every function takes the instant it should reason about,
// which is what lets a boundary be tested rather than waited for.
 
const MINUTE = 60_000;
 
describe("windowStart", () => {
  it("floors an instant to the window it belongs to", () => {
    expect(windowStart(90_000, MINUTE)).toBe(60_000);
    expect(windowStart(60_000, MINUTE)).toBe(60_000);
    expect(windowStart(59_999, MINUTE)).toBe(0);
  });
 
  it("is the key's own suffix, which is why nothing stores a reset time", () => {
    // Two instances computing this from the same clock agree without talking.
    // A stored reset time is a value they could disagree about — the clock-skew
    // edge case, closed by construction rather than by agreement.
    expect(windowStart(119_999, MINUTE)).toBe(windowStart(60_000, MINUTE));
  });
});
 
describe("resetAt", () => {
  it("is the end of the current window, not a refill curve", () => {
    // The deciding reason for a fixed window over a token bucket (R1):
    // `X-RateLimit-Reset` has to name one moment, and this is it.
    expect(resetAt(90_000, MINUTE)).toBe(120_000);
  });
 
  it("never lands in the past", () => {
    for (const now of [0, 1, 59_999, 60_000, 60_001]) {
      expect(resetAt(now, MINUTE)).toBeGreaterThan(now - 1);
    }
  });
});
 
describe("remaining", () => {
  it("counts down from the limit as the count rises", () => {
    expect(remaining(1, 600)).toBe(599);
    expect(remaining(600, 600)).toBe(0);
  });
 
  it("A COUNTER THAT HAS NEVER BEEN WRITTEN returns a full allowance", () => {
    // The `INCR`-returns-1 path, which is also where `EXPIRE` is set. A brand-new
    // environment's first request must not look like an exhausted one.
    expect(remaining(1, 600)).toBe(599);
    expect(remaining(0, 600)).toBe(600);
  });
 
  it("A LIMIT LOWERED MID-WINDOW yields zero, never a negative", () => {
    // An operator drops an environment from 600 to 2 while 40 requests are
    // already counted. `Remaining: -38` is a number a client would parse and act
    // on; zero is the truth.
    expect(remaining(40, 2)).toBe(0);
  });
 
  it("is zero at the limit, so a refusal reports zero rather than one", () => {
    expect(remaining(600, 600)).toBe(0);
    expect(remaining(601, 600)).toBe(0);
  });
});
 
describe("the boundary burst, which is the cost of a fixed window", () => {
  it("permits up to twice the limit across one window edge", () => {
    // R1 accepted this rather than hiding it: 600 in the last instant of one
    // window and 600 in the first instant of the next is 1,200 inside two
    // minutes. Asserted so the chapter's claim is a test rather than a comment.
    const limit = 600;
    const firstWindow = windowStart(59_999, MINUTE);
    const secondWindow = windowStart(60_000, MINUTE);
    expect(firstWindow).not.toBe(secondWindow);
    expect(remaining(limit, limit) + limit).toBe(limit);
    // Two distinct keys, each allowing `limit`, one millisecond apart.
    expect(remaining(1, limit)).toBe(limit - 1);
  });
});

import { afterEach, describe, expect, it } from "vitest";
 
import {
  DEFAULT_AUTH_FAILURES_PER_MINUTE,
  DEFAULT_LIMITS,
  WINDOW_MS,
  authFailureThreshold,
} from "./policy";
 
// The numbers, and what happens when someone fat-fingers the one that is
// configurable.
 
describe("authFailureThreshold", () => {
  const previous = process.env["RELAY_AUTH_FAILURES_PER_MINUTE"];
  afterEach(() => {
    if (previous === undefined) delete process.env["RELAY_AUTH_FAILURES_PER_MINUTE"];
    else process.env["RELAY_AUTH_FAILURES_PER_MINUTE"] = previous;
  });
 
  const withEnv = (value: string) => {
    process.env["RELAY_AUTH_FAILURES_PER_MINUTE"] = value;
    return authFailureThreshold();
  };
 
  it("uses the documented default when nothing is set", () => {
    delete process.env["RELAY_AUTH_FAILURES_PER_MINUTE"];
    expect(authFailureThreshold()).toBe(DEFAULT_AUTH_FAILURES_PER_MINUTE);
  });
 
  it("honours a configured threshold", () => {
    expect(withEnv("3")).toBe(3);
  });
 
  it("FALLS BACK TO THE DEFAULT for anything that is not a positive number", () => {
    // The failure mode this is protecting against is not exotic. `parseInt`
    // returns NaN for "ten" and 0 for "0", and either would be silently
    // catastrophic in a different direction: NaN makes every comparison false,
    // so the limiter never triggers; 0 makes it trigger on the first failed
    // auth, locking out an address that mistyped a password once.
    //
    // A misconfigured security control that fails silently is worse than one
    // that is absent, because nobody looks for it.
    for (const bad of ["ten", "", "0", "-1", "NaN"]) {
      expect(withEnv(bad)).toBe(DEFAULT_AUTH_FAILURES_PER_MINUTE);
    }
  });
});
 
describe("the defaults themselves", () => {
  it("are the numbers the chapter derived, not round ones", () => {
    // Pinned so a change has to be deliberate. Each was re-derived against
    // NFR-SCL and NFR-PRF (research R26); the chapter states the derivation and
    // this asserts the result.
    expect(DEFAULT_LIMITS).toEqual({ rest: 600, send: 600, connect: 3_000 });
    expect(DEFAULT_AUTH_FAILURES_PER_MINUTE).toBe(10);
    // One minute, because every limit above is stated per minute and a window
    // that did not match the unit would need a second number to explain it.
    expect(WINDOW_MS).toBe(60_000);
  });
});