@cosmicdrift/kumiko-framework 0.164.0 → 0.165.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.164.0",
+  "version": "0.165.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,6 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.164.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -197,8 +196,11 @@
     "uuid": "^14.0.0",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "@cosmicdrift/kumiko-types": "^0.165.1"
+  },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.164.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.165.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/consumer-cli.integration.test.ts

@@ -84,6 +84,68 @@ describe("runConsumerCli status", () => {
     expect(code).toBe(1);
     expect(lines.join("\n")).toContain("DATABASE_URL not set");
   });
+
+  test("--instance-id flag → status looks up the per-instance consumer, not shared", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:inst", "inst-1");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(
+      ["status", "test:consumer:inst", "--instance-id", "inst-1"],
+      out,
+    );
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain('instance_id="inst-1"');
+  });
+
+  test("--instance-id=<id> form is recognised (#1412)", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:eq", "inst-2");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:eq", "--instance-id=inst-2"], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain('instance_id="inst-2"');
+  });
+
+  test("--instance-id before the name still parses the name correctly (#1412)", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:order", "inst-3");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(
+      ["status", "--instance-id", "inst-3", "test:consumer:order"],
+      out,
+    );
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain('instance_id="inst-3"');
+  });
+
+  test("--instance-id with a missing value errors instead of silently falling back to shared (#1412)", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:foo", "--instance-id"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("--instance-id braucht einen Wert");
+  });
+});
+
+describe("runConsumerCli — unknown/empty subcommand exit codes", () => {
+  test("no subcommand at all → exit 0 (usage, not an error)", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli([], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
+
+  test("an unrecognized subcommand → exit 1", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["bogus"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
 });
 
 describe("runConsumerCli restart", () => {

package/src/__tests__/schema-cli.integration.test.ts

@@ -177,7 +177,7 @@ describe("runSchemaCli — validate (static CI gate, no DB)", () => {
     const code = await runSchemaCli(["validate"], appCwd, cap.out);
     expect(code).toBe(0);
     expect(cap.log.join("\n")).toContain("migrations match");
-    expect(cap.log.join("\n")).toContain("committed SQL matches .snapshot.json");
+    expect(cap.log.join("\n")).toContain("table/column names match .snapshot.json");
   });
 
   // Reproduces the kumiko-studio 0016 incident: a migration file gets

package/src/api/__tests__/api.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { parseSseFrames } from "@cosmicdrift/kumiko-dispatcher-live";
+import { Hono } from "hono";
 import { z } from "zod";
 import {
   createEntity,
@@ -7,7 +9,10 @@ import {
   defineFeature,
   type TenantId,
 } from "../../engine";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
 import { createTestUser, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
+import { createApiRoutes, pumpStream, StreamFrame } from "../routes";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -39,6 +44,27 @@ const testFeature = defineFeature("test", (r) => {
     },
     { access: { roles: ["Admin"] } },
   );
+
+  r.streamHandler(
+    "item:tail-fail-mid",
+    z.object({}),
+    async function* () {
+      yield { i: 0 };
+      yield { i: 1 };
+      throw new Error("boom");
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.streamHandler(
+    "item:tail-fail-first",
+    z.object({}),
+    // biome-ignore lint/correctness/useYield: deliberately throws before any yield — tests the pre-pull failure path
+    async function* () {
+      throw new Error("boom");
+    },
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 const registry = createRegistry([testFeature]);
@@ -210,6 +236,138 @@ describe("POST /api/command", () => {
   });
 });
 
+// --- pumpStream (SSE pull loop) ---
+
+function fakeSseWriter() {
+  const frames: Array<{ event: string; data: string }> = [];
+  return {
+    frames,
+    async writeSSE(message: { event: string; data: string }) {
+      frames.push(message);
+    },
+  };
+}
+
+async function* delayedGenerator(values: readonly unknown[], delayMsByIndex: readonly number[]) {
+  for (let i = 0; i < values.length; i++) {
+    const delay = delayMsByIndex[i] ?? 0;
+    if (delay > 0) await Bun.sleep(delay);
+    yield values[i];
+  }
+}
+
+describe("pumpStream", () => {
+  test("emits a ping when the handler is slow, then still delivers the pending chunk (no loss)", async () => {
+    const writer = fakeSseWriter();
+    // heartbeatMs (10) fires before the 40ms-delayed second chunk resolves.
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }], [0, 40]);
+
+    await pumpStream(writer, gen, 10);
+
+    const events = writer.frames.map((f) => f.event);
+    expect(events[0]).toBe("chunk");
+    expect(events).toContain("ping");
+    expect(events.at(-1)).toBe("done");
+    // Both chunks arrive despite the ping in between — no chunk dropped.
+    const chunkData = writer.frames.filter((f) => f.event === "chunk").map((f) => f.data);
+    expect(chunkData).toEqual([JSON.stringify({ i: 0 }), JSON.stringify({ i: 1 })]);
+  });
+
+  test("no heartbeat fires when the handler is faster than heartbeatMs — chunks then done", async () => {
+    const writer = fakeSseWriter();
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }, { i: 2 }], [0, 0, 0]);
+
+    await pumpStream(writer, gen, 1000);
+
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk", "chunk", "chunk", "done"]);
+  });
+
+  test("a handler generator that throws propagates the error instead of swallowing it", async () => {
+    const writer = fakeSseWriter();
+    async function* throwing() {
+      yield { i: 0 };
+      throw new Error("handler-boom");
+    }
+
+    await expect(pumpStream(writer, throwing(), 1000)).rejects.toThrow("handler-boom");
+    // The chunk before the throw still made it out.
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk"]);
+  });
+
+  test("closes the generator when writeSSE throws mid-loop (e.g. client disconnected on a ping)", async () => {
+    let cleanedUp = false;
+    async function* gen() {
+      try {
+        await Bun.sleep(50);
+        yield { i: 0 };
+      } finally {
+        cleanedUp = true;
+      }
+    }
+    const frames: Array<{ event: string; data: string }> = [];
+    const writer = {
+      frames,
+      async writeSSE(message: { event: string; data: string }) {
+        if (message.event === StreamFrame.ping) throw new Error("client disconnected");
+        frames.push(message);
+      },
+    };
+
+    await expect(pumpStream(writer, gen(), 5)).rejects.toThrow("client disconnected");
+    // Fire-and-forget cleanup (kumiko-framework#1547): pumpStream's finally
+    // no longer awaits generator.return() — it can't, since a still-pending
+    // .next() would make that await hang — so cleanedUp flips asynchronously
+    // after pumpStream's own rejection, not synchronously before it.
+    await waitFor(() => {
+      expect(cleanedUp).toBe(true);
+    });
+  });
+
+  test("does not hang when writeSSE throws while a .next() pull is still in flight", async () => {
+    // kumiko-framework#1547: generator.return() queues behind an in-flight
+    // .next() (V8 semantics) — an `await generator.return(undefined)` in the
+    // finally block would hang for as long as the handler's .next() never
+    // settles, which a dead Redis/DB subscription can do indefinitely.
+    // `never` intentionally never resolves — the fire-and-forget fix must
+    // not need it to.
+    const never = new Promise<never>(() => {});
+    async function* gen() {
+      await never;
+      yield { i: 0 };
+    }
+    const writer = {
+      frames: [] as Array<{ event: string; data: string }>,
+      async writeSSE(message: { event: string; data: string }) {
+        if (message.event === StreamFrame.ping) throw new Error("client disconnected");
+        this.frames.push(message);
+      },
+    };
+
+    const TIMEOUT = Symbol("timeout");
+    const outcome = await Promise.race([
+      pumpStream(writer, gen(), 5).then(
+        () => "resolved",
+        (e) => e,
+      ),
+      Bun.sleep(500).then(() => TIMEOUT),
+    ]);
+    expect(outcome).not.toBe(TIMEOUT);
+    expect(outcome).toBeInstanceOf(Error);
+    expect((outcome as Error).message).toBe("client disconnected");
+  });
+
+  test("serializes an undefined yielded value as an explicit null chunk instead of an invalid frame", async () => {
+    const writer = fakeSseWriter();
+    async function* gen() {
+      yield undefined;
+    }
+
+    await pumpStream(writer, gen(), 1000);
+
+    expect(writer.frames[0]).toEqual({ event: StreamFrame.chunk, data: "null" });
+  });
+});
+
 // --- SSE ---
 
 describe("GET /api/sse", () => {
@@ -228,17 +386,6 @@ describe("GET /api/sse", () => {
 
 // --- Stream (dispatcher-driven SSE) ---
 
-function parseSseFrames(text: string): Array<{ event: string; data: string }> {
-  return text
-    .split("\n\n")
-    .filter((frame) => frame.trim().length > 0)
-    .map((frame) => {
-      const event = /^event: (.*)$/m.exec(frame)?.[1] ?? "";
-      const data = /^data: (.*)$/m.exec(frame)?.[1] ?? "";
-      return { event, data };
-    });
-}
-
 describe("POST /api/stream", () => {
   test("dispatches stream handler and yields chunk frames then done", async () => {
     const headers = await authHeader(adminUser);
@@ -260,10 +407,11 @@ describe("POST /api/stream", () => {
     ]);
   });
 
-  test("access-denied gate surfaces as an error frame, not an HTTP error status", async () => {
-    // Dispatch gates (feature/rate-limit/access/validation) fire on the
-    // generator's first pull, which happens after SSE headers are already
-    // flushed — so an access-denied mid-stream stays HTTP 200.
+  test("access-denied gate surfaces as a real 403, not an HTTP 200 error frame", async () => {
+    // Dispatch gates (feature/rate-limit/access/validation) run on the
+    // generator's first pull, which the route now performs BEFORE opening
+    // the SSE response — so a gate failure maps to its real HTTP status
+    // instead of a flushed-200 error frame (framework#1517).
     const headers = await authHeader(guestUser);
     const res = await req(
       "POST",
@@ -272,11 +420,171 @@ describe("POST /api/stream", () => {
       headers,
     );
 
+    expect(res.status).toBe(403);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+    const body = await res.json();
+    expect(body.error).toMatchObject({ code: "access_denied" });
+  });
+
+  test("returns 404 for unknown stream handler", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req("POST", "/api/stream", { type: "nope", payload: {} }, headers);
+
+    expect(res.status).toBe(404);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+  });
+
+  test("returns 400 for schema validation failure", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: -1 } },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+  });
+
+  test("handler failure after chunks already sent stays HTTP 200 with an error frame", async () => {
+    // Boundary between the pre-pull fix and the still-open SSE stream: a
+    // failure that happens AFTER the first chunk (headers already flushed)
+    // must keep surfacing as a 200 + "error" frame, not a real HTTP status.
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail-fail-mid", payload: {} },
+      headers,
+    );
+
     expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
     const frames = parseSseFrames(await res.text());
-    expect(frames).toHaveLength(1);
-    expect(frames[0]?.event).toBe("error");
-    expect(JSON.parse(frames[0]?.data ?? "{}")).toMatchObject({ code: "access_denied" });
+    expect(frames).toHaveLength(3);
+    expect(frames.slice(0, 2)).toEqual([
+      { event: "chunk", data: JSON.stringify({ i: 0 }) },
+      { event: "chunk", data: JSON.stringify({ i: 1 }) },
+    ]);
+    expect(frames[2]?.event).toBe("error");
+    expect(JSON.parse(frames[2]?.data ?? "{}")).toMatchObject({ code: "internal_error" });
+  });
+
+  test("handler failure before the first yield surfaces as a real HTTP 500, not an SSE error frame", async () => {
+    // Contract-pin for routes.ts's "error frames only reachable once the
+    // stream is already open" comment: a generator that throws before its
+    // first yield is caught by the same pre-pull gate as feature/access/
+    // rate-limit/validation failures — the client sees 500 + JSON, not a
+    // 200 with an SSE error frame.
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail-fail-first", payload: {} },
+      headers,
+    );
+
+    expect(res.status).toBe(500);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+    const body = await res.json();
+    expect(body.error).toMatchObject({ code: "internal_error" });
+  });
+});
+
+// --- POST /api/stream pre-pull race (framework#1547) ---
+// Mount createApiRoutes with a short sseHeartbeatMs so the pre-pull heartbeat
+// race is testable without waiting for the production 15s interval.
+
+describe("POST /api/stream pre-pull race", () => {
+  const user = createTestUser({ roles: ["Admin"] });
+
+  function stubDispatcher(streamImpl: Dispatcher["stream"]): Dispatcher {
+    return {
+      async write(): Promise<WriteResult> {
+        return { isSuccess: true, data: {} };
+      },
+      async query(): Promise<unknown> {
+        return [];
+      },
+      stream: streamImpl,
+      async command(): Promise<void> {},
+      async batch(): Promise<BatchResult> {
+        return { isSuccess: true, results: [] };
+      },
+      async resolveAuthClaims(): Promise<Record<string, unknown>> {
+        return {};
+      },
+    };
+  }
+
+  function mountStreamApp(dispatcher: Dispatcher, sseHeartbeatMs: number) {
+    const app = new Hono<{ Variables: { pipelineUser: typeof user } }>();
+    app.use("/api/*", async (c, next) => {
+      c.set("pipelineUser", user);
+      await next();
+    });
+    app.route("/api", createApiRoutes(dispatcher, { sseHeartbeatMs }));
+    return app;
+  }
+
+  test("slow first next() opens 200 SSE with ping frames instead of hanging as HTTP error", async () => {
+    // First .next() takes longer than heartbeatMs → settledInTime=false →
+    // streamSSE opens immediately and pumpStream emits ping until the chunk
+    // arrives (framework#1547 route-level contract).
+    const dispatcher = stubDispatcher(async function* () {
+      await Bun.sleep(60);
+      yield { i: 0 };
+    });
+    const app = mountStreamApp(dispatcher, 20);
+    const res = await app.request(
+      new Request("http://localhost/api/stream", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ type: "any:stream:tail", payload: {} }),
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+    const frames = parseSseFrames(await res.text());
+    const events = frames.map((f) => f.event);
+    expect(events).toContain("ping");
+    expect(events).toContain("chunk");
+    expect(events.at(-1)).toBe("done");
+  });
+
+  test("client abort during pre-pull returns 499 and runs generator cleanup", async () => {
+    // Finite sleep (not a never-resolving await): V8 queues .return() behind an
+    // in-flight .next(), so cleanup only runs once the pending pull settles.
+    // Abort before heartbeatMs so the route hits the 499 branch; sleep then
+    // completes and the queued return drains the generator's finally.
+    let cleanedUp = false;
+    const dispatcher = stubDispatcher(async function* () {
+      try {
+        await Bun.sleep(80);
+        yield { i: 0 };
+      } finally {
+        cleanedUp = true;
+      }
+    });
+    const app = mountStreamApp(dispatcher, 40);
+    const ac = new AbortController();
+    const pending = app.request(
+      new Request("http://localhost/api/stream", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ type: "any:stream:tail", payload: {} }),
+        signal: ac.signal,
+      }),
+    );
+    // Abort while firstPull is still racing the heartbeat timer.
+    await Bun.sleep(5);
+    ac.abort();
+    const res = await pending;
+    expect(res.status).toBe(499);
+    await waitFor(() => {
+      expect(cleanedUp).toBe(true);
+    });
   });
 });
 

package/src/api/__tests__/auth-middleware-anonymous-access-boot.test.ts

@@ -0,0 +1,40 @@
+// authMiddleware boots eagerly (not per-request) so a tenantResolver
+// declared without resolverTrust is an ambiguous trust decision that fails
+// loud at startup, instead of silently letting a client-set tenant header
+// override a host-derived resolver at request time (#1452).
+
+import { describe, expect, test } from "bun:test";
+import { authMiddleware } from "../auth-middleware";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-middleware-anon-access-boot-test-secret-32ch";
+
+describe("authMiddleware anonymousAccess boot guard", () => {
+  test("throws at construction when tenantResolver is set without resolverTrust", () => {
+    const jwt = createJwtHelper(JWT_SECRET);
+    expect(() =>
+      authMiddleware(jwt, {
+        anonymousAccess: {
+          tenantResolver: () => "t1" as never,
+        },
+      }),
+    ).toThrow(/resolverTrust/);
+  });
+
+  test("does not throw when resolverTrust is declared", () => {
+    const jwt = createJwtHelper(JWT_SECRET);
+    expect(() =>
+      authMiddleware(jwt, {
+        anonymousAccess: {
+          tenantResolver: () => "t1" as never,
+          resolverTrust: "authoritative",
+        },
+      }),
+    ).not.toThrow();
+  });
+
+  test("does not throw when no tenantResolver is configured", () => {
+    const jwt = createJwtHelper(JWT_SECRET);
+    expect(() => authMiddleware(jwt, {})).not.toThrow();
+  });
+});

package/src/api/__tests__/auth-routes-invalid-body-invite.test.ts

@@ -92,6 +92,22 @@ describe("POST /auth/login — invalid_body", () => {
 describe("POST /auth/invite-accept", () => {
   test("requires JWT — not a public route", async () => {
     expect(PUBLIC_API_PATHS.has("/api/auth/invite-accept")).toBe(false);
+
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return { isSuccess: true, data: { kind: "noop" } };
+      },
+    });
+    const { app } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ inviteToken: "t" }),
+    });
+    expect(res.status).toBe(401);
+    expect(dispatched).toBe(false);
   });
 
   test("400 invalid_body before dispatch", async () => {

package/src/api/__tests__/auth-routes-mfa-preauth-confirm.test.ts

@@ -81,6 +81,11 @@ function preauthConfirmRequest(body: unknown): Request {
 describe("POST /auth/mfa/preauth-confirm", () => {
   test("is public — reachable without a JWT", async () => {
     expect(PUBLIC_API_PATHS.has("/api/auth/mfa/preauth-confirm")).toBe(true);
+    const { app } = await buildApp();
+    const res = await app.request(preauthConfirmRequest({ setupToken: "t", code: "123456" }));
+    // No Authorization header sent at all — if the route required a JWT,
+    // authMiddleware would reject with 401 before the handler ever runs.
+    expect(res.status).toBe(200);
   });
 
   test("not mounted when mfaPreauthConfirmHandler is unset", async () => {
@@ -100,12 +105,24 @@ describe("POST /auth/mfa/preauth-confirm", () => {
         };
       },
     });
-    const { app } = await buildApp({}, dispatcher);
+    // An active limiter, not null — "before rate-limit" is only checkable
+    // when there's a rate-limit to (not) consume.
+    const { app } = await buildApp(
+      { mfaPreauthConfirmRateLimit: createInMemoryLoginRateLimiter(2, 60_000) },
+      dispatcher,
+    );
     const res = await app.request(preauthConfirmRequest({ setupToken: "t" }));
     expect(res.status).toBe(400);
     const body = (await res.json()) as { isSuccess: boolean; error: string };
     expect(body.error).toBe("invalid_body");
     expect(dispatched).toBe(false);
+
+    // The limiter's cap (2) must still be fully available — a malformed
+    // body must not have consumed an attempt.
+    for (let i = 0; i < 5; i++) {
+      const retry = await app.request(preauthConfirmRequest({ setupToken: "t" }));
+      expect(retry.status).toBe(400);
+    }
   });
 
   test("on success: dispatches to mfaPreauthConfirmHandler, mints a JWT + cookies", async () => {

package/src/api/__tests__/auth-routes-mfa-preauth-enable-start.test.ts

@@ -11,7 +11,11 @@ import { InternalError, UnprocessableError } from "../../errors";
 import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
 import { PUBLIC_API_PATHS } from "../api-constants";
 import { authMiddleware } from "../auth-middleware";
-import { type AuthRoutesConfig, createAuthRoutes } from "../auth-routes";
+import {
+  type AuthRoutesConfig,
+  createAuthRoutes,
+  createInMemoryLoginRateLimiter,
+} from "../auth-routes";
 import { createJwtHelper } from "../jwt";
 
 const JWT_SECRET = "test-jwt-secret-at-least-32-bytes-long!!";
@@ -183,4 +187,63 @@ describe("POST /auth/mfa/preauth-enable-start", () => {
     );
     expect(res.status).toBe(500);
   });
+
+  // #1466: this route inherited zero rate-limiting — a preauthSetupToken is
+  // valid (and not single-use) for its whole TTL, so an unrated-limited
+  // replay is a memory-hard CPU amplifier (8 argon2id recovery-code hashes
+  // per hit). Mirrors mfaPreauthConfirmRateLimit's own regression test.
+  test("mfaPreauthEnableStartRateLimit caps replays — 429 after its own limit", async () => {
+    const { app } = await buildApp({
+      mfaPreauthEnableStartRateLimit: createInMemoryLoginRateLimiter(2, 60_000),
+    });
+    const attempt = () =>
+      app.request(preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }));
+    expect((await attempt()).status).toBe(200);
+    expect((await attempt()).status).toBe(200);
+    const third = await attempt();
+    expect(third.status).toBe(429);
+    const body = (await third.json()) as { isSuccess: boolean; error: string };
+    expect(body.error).toBe("rate_limited");
+  });
+
+  // #1522 / #1545: the IP axis alone is bypassable by rotating
+  // x-forwarded-for. The second check keys on a sha256 of the
+  // preauthSetupToken — prove rotating IPs still hit 429 on the same
+  // token, and that a different token does not share that bucket.
+  test("preauthSetupToken rate-limit axis survives x-forwarded-for rotation", async () => {
+    const { app } = await buildApp({
+      mfaPreauthEnableStartRateLimit: createInMemoryLoginRateLimiter(2, 60_000),
+    });
+    const attempt = (token: string, forwardedFor: string) =>
+      app.request(
+        new Request("http://localhost/api/auth/mfa/preauth-enable-start", {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-forwarded-for": forwardedFor,
+          },
+          body: JSON.stringify({ preauthSetupToken: token, accountLabel: "a@b.c" }),
+        }),
+      );
+
+    expect((await attempt("shared-token", "10.0.0.1")).status).toBe(200);
+    expect((await attempt("shared-token", "10.0.0.2")).status).toBe(200);
+    const blocked = await attempt("shared-token", "10.0.0.3");
+    expect(blocked.status).toBe(429);
+    const body = (await blocked.json()) as { isSuccess: boolean; error: string };
+    expect(body.error).toBe("rate_limited");
+
+    // Distinct token → independent bucket; rotating IP must not inherit the
+    // prior token's exhaustion.
+    expect((await attempt("other-token", "10.0.0.4")).status).toBe(200);
+  });
+
+  test("mfaPreauthEnableStartRateLimit: null disables rate-limiting", async () => {
+    const { app } = await buildApp({ mfaPreauthEnableStartRateLimit: null });
+    const attempt = () =>
+      app.request(preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }));
+    for (let i = 0; i < 15; i++) {
+      expect((await attempt()).status).toBe(200);
+    }
+  });
 });