@cosmicdrift/kumiko-framework 0.165.0 → 2.0.0

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);
+  });
+});

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

@@ -97,7 +97,7 @@ const itemFeature = defineFeature("batch", (r) => {
     "postSave",
     { allOf: item },
     async (result, ctx) => {
-      if (!ctx.db) return;
+      if (!ctx.db || !("insertOne" in ctx.db)) return;
       await ctx.db.insertOne(auditTable, { action: "item_saved", itemId: result.id });
     },
     { phase: HookPhases.inTransaction },
@@ -407,7 +407,26 @@ describe("POST /api/batch", () => {
 
   test("idempotency: corrupted cache entry is treated as miss and re-runs", async () => {
     const requestId = "batch-rid-corrupt";
-    await stack.redis.redis.set(`${RedisKeys.idempotency}${requestId}`, "{not-json", "EX", 60);
+    const cacheKey = `${RedisKeys.idempotency}${requestId}`;
+
+    // Prove key-coupling first: seed a well-formed cached entry under the
+    // exact manually-built key and confirm the batch short-circuits on it
+    // (no handler run, no DB write) — if the manual key ever drifts from
+    // what the guard actually reads, this half fails loud instead of the
+    // corrupt-JSON half below silently becoming a no-op cache-miss test.
+    const seeded = { isSuccess: true, results: [{ seeded: true }] };
+    await stack.redis.redis.set(cacheKey, JSON.stringify(seeded), "EX", 60);
+    const cachedRes = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "should-not-run" } }],
+      admin,
+      requestId,
+    );
+    expect(await cachedRes.json()).toEqual(seeded);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+    expect(inTxHookLog).toHaveLength(0);
+
+    // Now corrupt the same key and confirm it's treated as a miss.
+    await stack.redis.redis.set(cacheKey, "{not-json", "EX", 60);
 
     const res = await stack.http.batch(
       [{ type: "batch:write:item:create", payload: { name: "after-corrupt" } }],

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

@@ -185,10 +185,36 @@ describe("loadJwtSecretOrKeyring", () => {
     ).toThrow(/not present in the keyring/);
   });
 
-  it("plain JWT_SECRET is ignored once a keyring is present", () => {
+  it("kumiko-framework#1308: plain JWT_SECRET carries over as a verify-only legacy key once a keyring is adopted", () => {
+    // Adopting rotation for the first time doesn't unset JWT_SECRET (it still
+    // signs the separate password-reset/email-verification HMAC family) —
+    // and sessions signed before adoption have no `kid`, so they must keep
+    // verifying against this exact value, not get orphaned the moment
+    // JWT_SECRET_V1 shows up.
+    const PLAIN_SECRET = "pre-rotation-plain-secret-32-chars-long!!";
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: PLAIN_SECRET,
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET, legacy: PLAIN_SECRET }, signKid: "v1" });
+  });
+
+  it("kumiko-framework#1308: legacy JWT_SECRET never becomes the sign key, only ever verify-only", () => {
+    const PLAIN_SECRET = "pre-rotation-plain-secret-32-chars-long!!";
+    const keyring = loadJwtSecretOrKeyring({
+      JWT_SECRET: PLAIN_SECRET,
+      JWT_SECRET_V1: SECRET,
+      JWT_SECRET_CURRENT_VERSION: "1",
+    });
+    expect(typeof keyring).not.toBe("string");
+    expect((keyring as { signKid: string }).signKid).toBe("v1");
+  });
+
+  it("kumiko-framework#1308: no plain JWT_SECRET set alongside a keyring → no legacy key added", () => {
     expect(
       loadJwtSecretOrKeyring({
-        JWT_SECRET: "should-be-ignored-once-keyring-present-aa",
         JWT_SECRET_V1: SECRET,
         JWT_SECRET_CURRENT_VERSION: "1",
       }),
@@ -209,6 +235,30 @@ describe("loadJwtSecretOrKeyring", () => {
       }),
     ).toThrow(/JWT_SECRET_V1 must be ≥32 chars/);
   });
+
+  it("kumiko-framework#1526: short legacy JWT_SECRET is rejected, not silently carried into the keyring", () => {
+    // Auth-bypass: a short JWT_SECRET carried into keys["legacy"] without a
+    // length check would be offline-bruteforceable — an attacker forges
+    // {alg:"HS256", kid:"legacy"} with arbitrary sub/tenantId/roles and
+    // verifyWithKeyring looks the key up by kid straight from the header.
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: "short",
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toThrow(/JWT_SECRET must be ≥32 chars/);
+  });
+
+  it("kumiko-framework#1308: empty JWT_SECRET_V<n> throws instead of silently falling back to single-secret mode", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: SECRET,
+        JWT_SECRET_V1: "",
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toThrow(/JWT_SECRET_V1 is set but empty/);
+  });
 });
 
 describe("createJwtHelper — ttlSeconds", () => {

package/src/api/__tests__/redis-login-rate-limiter.integration.test.ts

@@ -63,4 +63,76 @@ describe("createRedisLoginRateLimiter", () => {
 
     expect(await limiter.check("k")).toBe(true);
   });
+
+  // Regression for the INCR-then-PEXPIRE race: two separate round-trips left
+  // a window for a crash/network blip right after the key is created
+  // (count===1) to skip the PEXPIRE call entirely, leaving the key
+  // permanently without a TTL. The single-eval fix closes that window by
+  // construction (one round-trip, can't be interrupted mid-way). "TTL
+  // exists after check()" alone doesn't distinguish old from new — the old
+  // two-call code also leaves a TTL set on the non-crashing path — so this
+  // pins the actual mechanism instead: exactly one `eval` round-trip, and
+  // `incr`/`pexpire` are never called directly (the only path is atomic).
+  test("check() goes through a single atomic eval — never incr/pexpire directly", async () => {
+    const limiter = createRedisLoginRateLimiter(testRedis.redis, 3, 60_000);
+    const key = "1.2.3.4|ttl-race@test.local";
+
+    // Manual call-counting instrumentation, not a test-library mock: each
+    // wrapper delegates to the real bound method on the real Redis client
+    // (setupTestStack), so behavior is unchanged — this only counts which
+    // wire commands actually went out, without the bun:test spy helper the
+    // integration-mock-guard forbids in *.integration.test.ts files.
+    const origEval = testRedis.redis.eval.bind(testRedis.redis);
+    const origIncr = testRedis.redis.incr.bind(testRedis.redis);
+    const origPexpire = testRedis.redis.pexpire.bind(testRedis.redis);
+    let evalCalls = 0;
+    let incrCalls = 0;
+    let pexpireCalls = 0;
+    testRedis.redis.eval = ((...args: Parameters<typeof origEval>) => {
+      evalCalls++;
+      return origEval(...args);
+    }) as typeof origEval;
+    testRedis.redis.incr = ((...args: Parameters<typeof origIncr>) => {
+      incrCalls++;
+      return origIncr(...args);
+    }) as typeof origIncr;
+    testRedis.redis.pexpire = ((...args: Parameters<typeof origPexpire>) => {
+      pexpireCalls++;
+      return origPexpire(...args);
+    }) as typeof origPexpire;
+    try {
+      expect(await limiter.check(key)).toBe(true);
+
+      expect(evalCalls).toBe(1);
+      expect(incrCalls).toBe(0);
+      expect(pexpireCalls).toBe(0);
+
+      const ttlMs = await testRedis.redis.pttl(`kumiko:auth:ratelimit:login:${key}`);
+      expect(ttlMs).toBeGreaterThan(0);
+    } finally {
+      testRedis.redis.eval = origEval;
+      testRedis.redis.incr = origIncr;
+      testRedis.redis.pexpire = origPexpire;
+    }
+  });
+
+  // kumiko-framework#1522 idx=5: a key that already exists WITHOUT a TTL
+  // (exactly what the pre-fix INCR-then-PEXPIRE race could leave behind)
+  // must get one applied on the very next check(), not stay permanently
+  // uncapped. Simulates the orphan directly via INCR (no TTL) rather than
+  // trying to hit the original race window, which isn't reproducible from
+  // outside the eval script.
+  test("heals a pre-existing key that has no TTL (orphaned by the old two-call race)", async () => {
+    const limiter = createRedisLoginRateLimiter(testRedis.redis, 5, 60_000, "heal-test");
+    const key = "1.2.3.4|orphan@test.local";
+    const redisKey = `kumiko:auth:ratelimit:heal-test:${key}`;
+
+    await testRedis.redis.incr(redisKey);
+    expect(await testRedis.redis.pttl(redisKey)).toBe(-1);
+
+    await limiter.check(key);
+
+    const ttlMs = await testRedis.redis.pttl(redisKey);
+    expect(ttlMs).toBeGreaterThan(0);
+  });
 });

package/src/api/__tests__/sse-broker.test.ts

@@ -55,4 +55,61 @@ describe("SSE broker", () => {
     expect(() => broker.removeClient("unknown", "fake-id")).not.toThrow();
     expect(broker.getClientCount("unknown")).toBe(0);
   });
+
+  test("subscribeAccessInvalidation fires only listeners on the same user's channel", () => {
+    const broker = createSseBroker();
+    const onInvalidateA = mock();
+    const onInvalidateB = mock();
+
+    broker.subscribeAccessInvalidation("user-a", onInvalidateA);
+    broker.subscribeAccessInvalidation("user-b", onInvalidateB);
+
+    broker.publishAccessInvalidation("user-a");
+
+    expect(onInvalidateA).toHaveBeenCalledTimes(1);
+    expect(onInvalidateB).not.toHaveBeenCalled();
+  });
+
+  test("subscribeAccessInvalidation supports multiple listeners on the same user", () => {
+    const broker = createSseBroker();
+    const first = mock();
+    const second = mock();
+
+    broker.subscribeAccessInvalidation("user-a", first);
+    broker.subscribeAccessInvalidation("user-a", second);
+    broker.publishAccessInvalidation("user-a");
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  test("unsubscribe (returned closure) stops further delivery", () => {
+    const broker = createSseBroker();
+    const onInvalidate = mock();
+
+    const unsubscribe = broker.subscribeAccessInvalidation("user-a", onInvalidate);
+    unsubscribe();
+    broker.publishAccessInvalidation("user-a");
+
+    expect(onInvalidate).not.toHaveBeenCalled();
+  });
+
+  test("a fired listener can unsubscribe itself without skipping other listeners", () => {
+    const broker = createSseBroker();
+    let unsubscribeSelf: () => void = () => {};
+    const self = mock(() => unsubscribeSelf());
+    const other = mock();
+
+    unsubscribeSelf = broker.subscribeAccessInvalidation("user-a", self);
+    broker.subscribeAccessInvalidation("user-a", other);
+    broker.publishAccessInvalidation("user-a");
+
+    expect(self).toHaveBeenCalledTimes(1);
+    expect(other).toHaveBeenCalledTimes(1);
+  });
+
+  test("publishAccessInvalidation to a user with no listeners does nothing", () => {
+    const broker = createSseBroker();
+    expect(() => broker.publishAccessInvalidation("nobody-listening")).not.toThrow();
+  });
 });

package/src/api/__tests__/sse-route.test.ts

@@ -27,6 +27,10 @@ function createTrackingBroker(): { broker: SseBroker; subscribedChannel: Promise
     getTotalClientCount() {
       return 0;
     },
+    subscribeAccessInvalidation() {
+      return () => {};
+    },
+    publishAccessInvalidation() {},
   };
 
   return { broker, subscribedChannel };