@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -0,0 +1,249 @@
+// auth-routes /auth/mfa/preauth-enable-start — framework-level route
+// mechanics only: body validation, dispatch-without-minting-a-session, and
+// error-status mapping. Uses a stub Dispatcher with a fake handler — the
+// REAL preauthSetupToken verification / secret generation lives in
+// auth-mfa's own handler and is covered there, not here.
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+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,
+  createInMemoryLoginRateLimiter,
+} from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "test-jwt-secret-at-least-32-bytes-long!!";
+const PREAUTH_ENABLE_START_QN = "auth-mfa:write:enable-start-preauth";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      const ok: WriteResult = {
+        isSuccess: true,
+        data: {
+          setupToken: "stub-setup-token",
+          otpauthUri: "otpauth://totp/stub",
+          recoveryCodes: ["AAAA-BBBB"],
+        },
+      };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async *stream(): AsyncGenerator<unknown> {},
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      const ok: BatchResult = { isSuccess: true, results: [] };
+      return ok;
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    mfaPreauthEnableStartHandler: PREAUTH_ENABLE_START_QN,
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(dispatcher, jwt, config));
+  return { app };
+}
+
+function preauthStartRequest(body: unknown): Request {
+  return new Request("http://localhost/api/auth/mfa/preauth-enable-start", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("POST /auth/mfa/preauth-enable-start", () => {
+  test("is public — reachable without a JWT", async () => {
+    expect(PUBLIC_API_PATHS.has("/api/auth/mfa/preauth-enable-start")).toBe(true);
+  });
+
+  test("not mounted when mfaPreauthEnableStartHandler is unset", async () => {
+    const { app } = await buildApp({ mfaPreauthEnableStartHandler: undefined });
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }),
+    );
+    expect(res.status).toBe(404);
+  });
+
+  test("400 on a malformed body, before dispatch", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return {
+          isSuccess: true,
+          data: { setupToken: "x", otpauthUri: "otpauth://totp/x", recoveryCodes: [] },
+        };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(preauthStartRequest({ preauthSetupToken: "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);
+  });
+
+  test("on success: dispatches to the handler, returns setupToken/otpauthUri/recoveryCodes, mints NO session", async () => {
+    let receivedBody: unknown;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload): Promise<WriteResult> {
+        expect(qn).toBe(PREAUTH_ENABLE_START_QN);
+        receivedBody = payload;
+        return {
+          isSuccess: true,
+          data: {
+            setupToken: "secret-carrying-setup-token",
+            otpauthUri: "otpauth://totp/Kumiko:a%40b.c",
+            recoveryCodes: ["AAAA-BBBB", "CCCC-DDDD"],
+          },
+        };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "opaque-preauth-token", accountLabel: "a@b.c" }),
+    );
+    expect(res.status).toBe(200);
+    expect(receivedBody).toEqual({
+      preauthSetupToken: "opaque-preauth-token",
+      accountLabel: "a@b.c",
+    });
+
+    const body = (await res.json()) as {
+      isSuccess: boolean;
+      setupToken: string;
+      otpauthUri: string;
+      recoveryCodes: string[];
+      token?: string;
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(body.setupToken).toBe("secret-carrying-setup-token");
+    expect(body.otpauthUri).toBe("otpauth://totp/Kumiko:a%40b.c");
+    expect(body.recoveryCodes).toEqual(["AAAA-BBBB", "CCCC-DDDD"]);
+    // No JWT minted — unlike /auth/login and /auth/mfa/verify, this route
+    // never establishes a session.
+    expect(body.token).toBeUndefined();
+  });
+
+  test("a handler failure maps through mfaPreauthEnableStartErrorStatusMap", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_challenge_token", {
+            details: { reason: "invalid_challenge_token" },
+          }),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaPreauthEnableStartErrorStatusMap: { invalid_challenge_token: 422 } },
+      dispatcher,
+    );
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }),
+    );
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(false);
+  });
+
+  test("an unmapped handler failure falls back to the error's own httpStatus", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return { isSuccess: false, error: new InternalError({ message: "boom" }) };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(
+      preauthStartRequest({ preauthSetupToken: "t", accountLabel: "a@b.c" }),
+    );
+    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);
+    }
+  });
+});

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

@@ -0,0 +1,202 @@
+// auth-routes /auth/mfa/verify — framework-level route mechanics only:
+// body validation, dispatch-and-mint-on-success, its OWN rate limiter
+// (mfaVerifyRateLimit, distinct from loginRateLimit), and error-status
+// mapping. Uses a stub Dispatcher with a fake mfaVerifyHandler — the REAL
+// challenge-token verification / TOTP check / brute-force cap lives in
+// auth-mfa's own handler and is covered there, not here.
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import { InternalError, UnprocessableError } from "../../errors";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
+import { TestUsers } from "../../stack";
+import { getSetCookies } from "../../testing/http-cookies";
+import { PUBLIC_API_PATHS } from "../api-constants";
+import { AUTH_COOKIE_NAME, authMiddleware, CSRF_COOKIE_NAME } from "../auth-middleware";
+import {
+  type AuthRoutesConfig,
+  createAuthRoutes,
+  createInMemoryLoginRateLimiter,
+} from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-routes-mfa-verify-test-secret-min-32-characters";
+const MFA_VERIFY_QN = "auth-mfa:write:verify";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      const ok: WriteResult = {
+        isSuccess: true,
+        data: { kind: "mfa-verify-success", session: TestUsers.user },
+      };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async *stream(): AsyncGenerator<unknown> {},
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      const ok: BatchResult = { isSuccess: true, results: [] };
+      return ok;
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    mfaVerifyHandler: MFA_VERIFY_QN,
+    mfaVerifyRateLimit: null,
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(dispatcher, jwt, config));
+  return { app };
+}
+
+function verifyRequest(body: unknown): Request {
+  return new Request("http://localhost/api/auth/mfa/verify", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("POST /auth/mfa/verify", () => {
+  test("is public — reachable without a JWT", async () => {
+    expect(PUBLIC_API_PATHS.has("/api/auth/mfa/verify")).toBe(true);
+  });
+
+  test("not mounted when mfaVerifyHandler is unset", async () => {
+    const { app } = await buildApp({ mfaVerifyHandler: undefined });
+    const res = await app.request(verifyRequest({ challengeToken: "t", code: "123456" }));
+    expect(res.status).toBe(404);
+  });
+
+  test("400 on a malformed body, before dispatch or rate-limit", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return { isSuccess: true, data: { kind: "mfa-verify-success", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(verifyRequest({ challengeToken: "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);
+  });
+
+  test("on success: dispatches to mfaVerifyHandler, mints a JWT + cookies", async () => {
+    let receivedBody: unknown;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload): Promise<WriteResult> {
+        expect(qn).toBe(MFA_VERIFY_QN);
+        receivedBody = payload;
+        return { isSuccess: true, data: { kind: "mfa-verify-success", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(
+      verifyRequest({ challengeToken: "opaque-challenge-token", code: "123456" }),
+    );
+    expect(res.status).toBe(200);
+    expect(receivedBody).toEqual({
+      challengeToken: "opaque-challenge-token",
+      code: "123456",
+    });
+
+    const body = (await res.json()) as { isSuccess: boolean; token: string };
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.token.length).toBeGreaterThan(20);
+
+    const cookies = getSetCookies(res);
+    expect(cookies.get(AUTH_COOKIE_NAME)).toBeDefined();
+    expect(cookies.get(CSRF_COOKIE_NAME)).toBeDefined();
+  });
+
+  test("a handler failure maps through mfaVerifyErrorStatusMap", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_totp_code", {
+            details: { reason: "invalid_totp_code" },
+          }),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaVerifyErrorStatusMap: { invalid_totp_code: 422 } },
+      dispatcher,
+    );
+    const res = await app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(false);
+  });
+
+  test("an unmapped handler failure falls back to the error's own httpStatus", async () => {
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return { isSuccess: false, error: new InternalError({ message: "boom" }) };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect(res.status).toBe(500);
+  });
+
+  test("mfaVerifyRateLimit is independent from loginRateLimit — 429 after its own cap", async () => {
+    // A failing dispatcher — reset() only fires on success, so failed
+    // attempts accumulate against the cap instead of clearing it each time.
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        return {
+          isSuccess: false,
+          error: new UnprocessableError("invalid_totp_code"),
+        };
+      },
+    });
+    const { app } = await buildApp(
+      { mfaVerifyRateLimit: createInMemoryLoginRateLimiter(2, 60_000) },
+      dispatcher,
+    );
+    const attempt = () => app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect((await attempt()).status).toBe(422);
+    expect((await attempt()).status).toBe(422);
+    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");
+  });
+
+  test("a successful verify resets the rate-limit counter for that IP", async () => {
+    const { app } = await buildApp({
+      mfaVerifyRateLimit: createInMemoryLoginRateLimiter(1, 60_000),
+    });
+    const attempt = () => app.request(verifyRequest({ challengeToken: "t", code: "000000" }));
+    expect((await attempt()).status).toBe(200);
+    // Without a reset-on-success this would be 429 (cap=1 already spent).
+    expect((await attempt()).status).toBe(200);
+  });
+});

package/src/api/__tests__/auth-routes-trusted-proxy.test.ts

@@ -0,0 +1,135 @@
+// kumiko-framework#1539: `trustedProxyHops` on AuthRoutesConfig. Verifies
+// the client-IP derivation behind /auth/mfa/verify's rate limiter — chosen
+// because it keys on bare IP (no email composite), so a wrong default here
+// is a shared-bucket DoS, not just a spoofing hole. Real Hono app + real
+// in-memory rate limiter, HTTP requests with attacker-shaped headers — no
+// fake dispatcher.
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import { 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,
+  createInMemoryLoginRateLimiter,
+} from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "test-secret-at-least-32-bytes-long-for-hs256";
+const MFA_VERIFY_QN = "auth-mfa:write:verify";
+
+function failingDispatcher(): Dispatcher {
+  return {
+    async write(): Promise<WriteResult> {
+      return { isSuccess: false, error: new UnprocessableError("invalid_totp_code") };
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async *stream(): AsyncGenerator<unknown> {},
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      return { isSuccess: true, results: [] };
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+  };
+}
+
+async function buildApp(overrides: Partial<AuthRoutesConfig> = {}): Promise<Hono> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    mfaVerifyHandler: MFA_VERIFY_QN,
+    mfaVerifyRateLimit: createInMemoryLoginRateLimiter(2, 60_000),
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(failingDispatcher(), jwt, config));
+  return app;
+}
+
+function verifyRequest(xForwardedFor?: string): Request {
+  return new Request("http://localhost/api/auth/mfa/verify", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(xForwardedFor !== undefined ? { "x-forwarded-for": xForwardedFor } : {}),
+    },
+    body: JSON.stringify({ challengeToken: "t", code: "000000" }),
+  });
+}
+
+describe("AuthRoutesConfig.trustedProxyHops", () => {
+  test("rejects a negative trustedProxyHops at construction — fails loud, not into a shared bucket", async () => {
+    await expect(buildApp({ trustedProxyHops: -1 })).rejects.toThrow(/non-negative integer/);
+  });
+
+  test("rejects a non-integer trustedProxyHops at construction", async () => {
+    await expect(buildApp({ trustedProxyHops: 1.5 })).rejects.toThrow(/non-negative integer/);
+  });
+
+  test("hops=1: an attacker rotating the untrusted XFF prefix still hits the real client's bucket", async () => {
+    const app = await buildApp({ trustedProxyHops: 1 });
+    // nginx-style append: "<attacker-claim>, <real-client-as-seen-by-nginx>"
+    // — attacker rotates the left entry per request, last entry stays fixed.
+    const attempt = (n: number) => app.request(verifyRequest(`1.2.3.${n}, 9.9.9.9`));
+    expect((await attempt(1)).status).toBe(422);
+    expect((await attempt(2)).status).toBe(422);
+    const third = await attempt(3);
+    expect(third.status).toBe(429);
+  });
+
+  test("hops=1: two genuinely different clients (differing last entry) get independent buckets", async () => {
+    const app = await buildApp({ trustedProxyHops: 1 });
+    const clientA = () => app.request(verifyRequest("fake, 9.9.9.9"));
+    const clientB = () => app.request(verifyRequest("fake, 8.8.8.8"));
+    expect((await clientA()).status).toBe(422);
+    expect((await clientA()).status).toBe(422);
+    expect((await clientA()).status).toBe(429);
+    // client B is unaffected by client A's cap
+    expect((await clientB()).status).toBe(422);
+  });
+
+  test("hops=0 (default): legacy behavior — trusts the first XFF entry unconditionally", async () => {
+    const app = await buildApp();
+    // No override: two "different" first-entries mean two different buckets,
+    // even though both requests carry the same real backend hop.
+    const clientA = () => app.request(verifyRequest("1.1.1.1, 9.9.9.9"));
+    const clientB = () => app.request(verifyRequest("2.2.2.2, 9.9.9.9"));
+    expect((await clientA()).status).toBe(422);
+    expect((await clientA()).status).toBe(422);
+    expect((await clientA()).status).toBe(429);
+    expect((await clientB()).status).toBe(422);
+  });
+
+  test("hops=2 with a shorter XFF chain than configured collapses distinct clients into the unknown bucket", async () => {
+    const app = await buildApp({ trustedProxyHops: 2 });
+    // Only 1 entry present but 2 hops configured — chain shorter than
+    // expected. Two DIFFERENT single-entry values must still share the cap:
+    // proves the short chain was rejected into "unknown" rather than
+    // extracted per-request (a same-value-only assertion would also pass
+    // for a constant return).
+    const attempt = (xff: string) => app.request(verifyRequest(xff));
+    expect((await attempt("9.9.9.9")).status).toBe(422);
+    expect((await attempt("7.7.7.7")).status).toBe(422);
+    const third = await attempt("6.6.6.6");
+    expect(third.status).toBe(429);
+  });
+
+  test("hops=1 with no XFF header at all falls back to unknown, not a throw", async () => {
+    const app = await buildApp({ trustedProxyHops: 1 });
+    const res = await app.request(verifyRequest(undefined));
+    expect(res.status).toBe(422);
+  });
+});