@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/api/__tests__/pii-leak-guard.integration.test.ts

@@ -0,0 +1,103 @@
+// Response-Tripwire (#820): ein kumiko-pii:-Ciphertext in einer JSON-Response
+// ist immer ein Bug (raw-Read am Decrypt vorbei). Dev/Test → 500 (Test wird
+// rot), Prod → redact + Error-Log, ohne KMS → kein Scan (pass-through).
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  resetPiiSubjectKmsForTests,
+} from "../../crypto";
+import { defineFeature } from "../../engine/define-feature";
+import { defineQueryHandler } from "../../engine/define-handler";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+const CIPHERTEXT = "kumiko-pii:v1:user:6b2f4a0e-1c9d-4f3a-9d2e-00000000000a:8e2Rkjj+ww==";
+
+const leakyFeature = defineFeature("leaky", (r) => {
+  r.queryHandler(
+    defineQueryHandler({
+      name: "raw",
+      schema: z.object({}),
+      access: { openToAll: true },
+      handler: async () => ({ email: CIPHERTEXT, note: "plain" }),
+    }),
+  );
+  r.queryHandler(
+    defineQueryHandler({
+      name: "clean",
+      schema: z.object({}),
+      access: { openToAll: true },
+      handler: async () => ({ email: "marc@example.com" }),
+    }),
+  );
+});
+
+let stack: TestStack;
+const originalNodeEnv = process.env["NODE_ENV"];
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [leakyFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  if (originalNodeEnv === undefined) delete process.env["NODE_ENV"];
+  else process.env["NODE_ENV"] = originalNodeEnv;
+});
+
+async function callLeakyQuery(): Promise<Response> {
+  const token = await stack.jwt.sign(TestUsers.admin);
+  return stack.http.raw(
+    "POST",
+    "/api/query",
+    { type: "leaky:query:raw", payload: {} },
+    { Authorization: `Bearer ${token}` },
+  );
+}
+
+describe("piiCiphertextResponseGuard", () => {
+  test("no KMS configured → response passes through unscanned", async () => {
+    const res = await callLeakyQuery();
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain(CIPHERTEXT);
+  });
+
+  test("KMS active, dev: leaking response becomes a loud 500", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const res = await callLeakyQuery();
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error?: { code?: string; message?: string } };
+    expect(body.error?.code).toBe("pii_ciphertext_leak");
+    expect(body.error?.message).toContain("/api/query");
+  });
+
+  test("KMS active, production: leak is redacted, request succeeds", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    process.env["NODE_ENV"] = "production";
+    const res = await callLeakyQuery();
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).not.toContain("kumiko-pii:");
+    expect(text).toContain("[pii-redacted]");
+    expect(text).toContain("plain");
+  });
+
+  test("KMS active, clean response stays untouched", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const token = await stack.jwt.sign(TestUsers.admin);
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "leaky:query:clean", payload: {} },
+      { Authorization: `Bearer ${token}` },
+    );
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("marc@example.com");
+  });
+});

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

@@ -0,0 +1,138 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { createRedisLoginRateLimiter } from "../auth-routes";
+
+let testRedis: TestRedis;
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+beforeEach(async () => {
+  await testRedis.flushNamespace();
+});
+
+describe("createRedisLoginRateLimiter", () => {
+  test("allows exactly maxAttempts checks, then blocks", async () => {
+    const limiter = createRedisLoginRateLimiter(testRedis.redis, 3, 60_000);
+
+    expect(await limiter.check("1.2.3.4|user@test.local")).toBe(true);
+    expect(await limiter.check("1.2.3.4|user@test.local")).toBe(true);
+    expect(await limiter.check("1.2.3.4|user@test.local")).toBe(true);
+    expect(await limiter.check("1.2.3.4|user@test.local")).toBe(false);
+  });
+
+  test("reset clears the counter for that key", async () => {
+    const limiter = createRedisLoginRateLimiter(testRedis.redis, 1, 60_000);
+
+    expect(await limiter.check("k")).toBe(true);
+    expect(await limiter.check("k")).toBe(false);
+
+    await limiter.reset("k");
+    expect(await limiter.check("k")).toBe(true);
+  });
+
+  test("buckets are independent per key", async () => {
+    const limiter = createRedisLoginRateLimiter(testRedis.redis, 1, 60_000);
+
+    expect(await limiter.check("a")).toBe(true);
+    expect(await limiter.check("b")).toBe(true);
+    expect(await limiter.check("a")).toBe(false);
+    expect(await limiter.check("b")).toBe(false);
+  });
+
+  test("namespace keeps two limiter instances from sharing a keyspace", async () => {
+    const login = createRedisLoginRateLimiter(testRedis.redis, 1, 60_000, "login");
+    const mfa = createRedisLoginRateLimiter(testRedis.redis, 1, 60_000, "mfa-verify");
+
+    expect(await login.check("1.2.3.4")).toBe(true);
+    expect(await mfa.check("1.2.3.4")).toBe(true);
+  });
+
+  test("counter resets once windowMs elapses", async () => {
+    const limiter = createRedisLoginRateLimiter(testRedis.redis, 1, 150);
+
+    expect(await limiter.check("k")).toBe(true);
+    expect(await limiter.check("k")).toBe(false);
+
+    await Bun.sleep(200);
+
+    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__/request-id-middleware.test.ts

@@ -70,3 +70,54 @@ describe("requestIdMiddleware — signal propagation", () => {
     expect(captured?.aborted).toBe(true);
   });
 });
+describe("requestIdMiddleware — ip + userAgent capture (603/2)", () => {
+  test("populates ip from x-forwarded-for and userAgent from the User-Agent header", async () => {
+    let captured: { ip: string | undefined; userAgent: string | undefined } = {
+      ip: undefined,
+      userAgent: undefined,
+    };
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware());
+    app.get("/probe", (c) => {
+      const ctx = requestContext.get();
+      captured = { ip: ctx?.ip, userAgent: ctx?.userAgent };
+      return c.text("ok");
+    });
+
+    const res = await app.request(
+      new Request("http://test.local/probe", {
+        method: "GET",
+        headers: {
+          "x-forwarded-for": "203.0.113.7, 10.0.0.1",
+          "user-agent": "Mozilla/5.0 (probe-test)",
+        },
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(captured.ip).toBe("203.0.113.7");
+    expect(captured.userAgent).toBe("Mozilla/5.0 (probe-test)");
+  });
+
+  test("no User-Agent header → userAgent stays undefined, not an empty string", async () => {
+    let captured: string | undefined = "unset";
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware());
+    app.get("/probe", (c) => {
+      captured = requestContext.get()?.userAgent;
+      return c.text("ok");
+    });
+
+    // fetch/undici always add a default User-Agent unless explicitly cleared —
+    // Hono's app.request accepts a raw Request, so an empty-but-present header
+    // simulates a client that sends the header with no value.
+    const res = await app.request(
+      new Request("http://test.local/probe", { method: "GET", headers: {} }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(captured).toBeUndefined();
+  });
+});

package/src/api/__tests__/server-boot-guards.test.ts

@@ -0,0 +1,71 @@
+// buildServer boot-time guards + httpRoute verb wiring (PUT branch).
+
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createFileField,
+  createRegistry,
+  createTextField,
+  defineFeature,
+} from "../../engine";
+import { buildServer } from "../server";
+
+const JWT_SECRET = "server-boot-guards-test-secret-min-32-chars";
+
+describe("buildServer — file-storage provider guard", () => {
+  const fileFieldFeature = defineFeature("needs-files", (r) => {
+    r.entity(
+      "doc",
+      createEntity({
+        table: "boot_guard_docs",
+        fields: { title: createTextField(), attachment: createFileField() },
+      }),
+    );
+  });
+
+  test("throws when registry declares file fields but no provider is mounted", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([fileFieldFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      }),
+    ).toThrow(/no file-storage provider is mounted/);
+  });
+});
+
+describe("buildServer — rateLimit resolver guard", () => {
+  test("throws when L1 global middleware requested without resolver", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+        rateLimit: { global: { limit: 100, windowSeconds: 60 } },
+      }),
+    ).toThrow(/rateLimit middleware requested but no resolver available/);
+  });
+});
+
+describe("buildServer — feature httpRoute PUT mounting", () => {
+  const putFeature = defineFeature("put-route", (r) => {
+    r.httpRoute({
+      method: "PUT",
+      path: "/resource/42",
+      anonymous: true,
+      handler: (c) => c.json({ method: "PUT", ok: true }),
+    });
+  });
+
+  const { app } = buildServer({
+    registry: createRegistry([putFeature]),
+    context: {},
+    jwtSecret: JWT_SECRET,
+  });
+
+  test("PUT /resource/42 reaches the declared handler", async () => {
+    const res = await app.request("/resource/42", { method: "PUT" });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ method: "PUT", ok: true });
+  });
+});

package/src/api/__tests__/server-jwt-ttl.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { createRegistry } from "../../engine";
+import { buildServer } from "../server";
+
+const JWT_SECRET = "x".repeat(40);
+const registry = createRegistry([]);
+
+describe("buildServer — jwtTtl default depends on sessionChecker wiring", () => {
+  test("no auth config → stateless default (1h)", () => {
+    const { jwt } = buildServer({ registry, context: {}, jwtSecret: JWT_SECRET });
+    expect(jwt.ttlSeconds).toBe(60 * 60);
+  });
+
+  test("auth without sessionChecker → stateless default (1h)", () => {
+    const { jwt } = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      auth: { membershipQuery: "unused:query" },
+    });
+    expect(jwt.ttlSeconds).toBe(60 * 60);
+  });
+
+  test("auth with sessionChecker → session-backed default (24h)", () => {
+    const { jwt } = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      auth: {
+        membershipQuery: "unused:query",
+        sessionChecker: async () => "live",
+      },
+    });
+    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+  });
+
+  test("explicit jwtTtl wins regardless of sessionChecker wiring", () => {
+    const withChecker = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      jwtTtl: 42,
+      auth: {
+        membershipQuery: "unused:query",
+        sessionChecker: async () => "live",
+      },
+    });
+    expect(withChecker.jwt.ttlSeconds).toBe(42);
+
+    const withoutChecker = buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      jwtTtl: 42,
+    });
+    expect(withoutChecker.jwt.ttlSeconds).toBe(42);
+  });
+});

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

package/src/api/api-constants.ts

@@ -10,8 +10,12 @@ export const Routes = {
   query: "/query",
   command: "/command",
   sse: "/sse",
+  stream: "/stream",
   auth: "/auth",
   authLogin: "/auth/login",
+  authMfaVerify: "/auth/mfa/verify",
+  authMfaPreauthEnableStart: "/auth/mfa/preauth-enable-start",
+  authMfaPreauthConfirm: "/auth/mfa/preauth-confirm",
   authLogout: "/auth/logout",
   authTenants: "/auth/tenants",
   authSwitchTenant: "/auth/switch-tenant",
@@ -19,6 +23,8 @@ export const Routes = {
   authResetPassword: "/auth/reset-password",
   authRequestEmailVerification: "/auth/request-email-verification",
   authVerifyEmail: "/auth/verify-email",
+  authRequestAccountUnlock: "/auth/request-account-unlock",
+  authConfirmAccountUnlock: "/auth/confirm-account-unlock",
   authSignupRequest: "/auth/signup-request",
   authSignupConfirm: "/auth/signup-confirm",
   // Tenant-Invite (Magic-Link): 3 separate accept-Endpoints für klare
@@ -36,10 +42,15 @@ export const Routes = {
 // The auth middleware skips these paths.
 export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.authLogin}`,
+  `/api${Routes.authMfaVerify}`,
+  `/api${Routes.authMfaPreauthEnableStart}`,
+  `/api${Routes.authMfaPreauthConfirm}`,
   `/api${Routes.authRequestPasswordReset}`,
   `/api${Routes.authResetPassword}`,
   `/api${Routes.authRequestEmailVerification}`,
   `/api${Routes.authVerifyEmail}`,
+  `/api${Routes.authRequestAccountUnlock}`,
+  `/api${Routes.authConfirmAccountUnlock}`,
   `/api${Routes.authSignupRequest}`,
   `/api${Routes.authSignupConfirm}`,
   // invite-accept braucht JWT (logged-in User, Branch 1) — NICHT public.