@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.157.2",
+  "version": "0.159.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>",
@@ -147,6 +147,10 @@
       "types": "./src/schema-cli.ts",
       "default": "./src/schema-cli.ts"
     },
+    "./consumer-cli": {
+      "types": "./src/consumer-cli.ts",
+      "default": "./src/consumer-cli.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"
@@ -178,6 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@cosmicdrift/kumiko-types": "0.159.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -193,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.157.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.159.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -0,0 +1,110 @@
+// Integration test for `runConsumerCli` (kumiko-framework#1351).
+//
+// Recovery semantics themselves are already covered by
+// event-dispatcher-recovery — this only exercises the CLI layer: argv
+// parsing, DB-connection handling, exit codes, output formatting.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../bun-db/__tests__/bun-test-db";
+import { type ConsumerCliOut, runConsumerCli } from "../consumer-cli";
+import { insertConsumerIfAbsent, markConsumerRebuildFailed } from "../db/queries/event-consumer";
+import { asRawClient } from "../db/query";
+import { createEventConsumerStateTable } from "../pipeline";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+const SHARED = "__shared__";
+
+let testDb: BunTestDb;
+let testUrl: string;
+let prevDbUrl: string | undefined;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  const baseUrl = process.env["TEST_DATABASE_URL"];
+  if (!baseUrl) throw new Error("TEST_DATABASE_URL not set — required for this test file");
+  testUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+afterEach(async () => {
+  await asRawClient(testDb.db).unsafe(`TRUNCATE TABLE "kumiko_event_consumers"`);
+  if (prevDbUrl === undefined) delete process.env["DATABASE_URL"];
+  else process.env["DATABASE_URL"] = prevDbUrl;
+});
+
+function captureOut(): { out: ConsumerCliOut; lines: string[] } {
+  const lines: string[] = [];
+  return {
+    out: { log: (l: string) => lines.push(l), err: (l: string) => lines.push(`ERR ${l}`) },
+    lines,
+  };
+}
+
+describe("runConsumerCli status", () => {
+  test("unknown consumer → exit 1, not-found message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "no-such-consumer"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not found");
+  });
+
+  test("known consumer → exit 0, reports status/cursor/attempts", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:foo", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:foo"], out);
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain("test:consumer:foo");
+    expect(joined).toContain("status:      idle");
+  });
+
+  test("missing <name> → exit 1, usage message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Usage:");
+  });
+
+  test("missing DATABASE_URL → exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    delete process.env["DATABASE_URL"];
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "whatever"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("DATABASE_URL not set");
+  });
+});
+
+describe("runConsumerCli restart", () => {
+  test("dead consumer → idle, exit 0", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:bar", SHARED);
+    await markConsumerRebuildFailed(testDb.db, "test:consumer:bar", SHARED, "boom");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:bar"], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("→ idle");
+  });
+
+  test("non-dead consumer → propagated error, exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:baz", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:baz"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not dead");
+  });
+});

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -52,8 +52,11 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
 async function buildApp(
   overrides: Partial<AuthRoutesConfig> = {},
   dispatcher: Dispatcher = createStubDispatcher(),
+  ttlSeconds?: number,
 ): Promise<{ app: Hono; validToken: string }> {
-  const jwt = createJwtHelper(JWT_SECRET);
+  const jwt = ttlSeconds
+    ? createJwtHelper(JWT_SECRET, undefined, ttlSeconds)
+    : createJwtHelper(JWT_SECRET);
   const validToken = await jwt.sign(TestUsers.user);
   const config: AuthRoutesConfig = {
     membershipQuery: "tenant:query:memberships",
@@ -128,6 +131,18 @@ describe("auth-routes cookie behaviour on /auth/login", () => {
     expect(typeof body.token).toBe("string");
     expect(body.token.length).toBeGreaterThan(20);
   });
+
+  test("cookie maxAge tracks the jwt helper's ttlSeconds, not a hardcoded default", async () => {
+    const customTtl = 60 * 60; // 1h — distinct from the 24h default
+    const { app } = await buildApp({}, undefined, customTtl);
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+  });
 });
 
 describe("auth-routes cookie behaviour on /auth/logout", () => {

package/src/api/__tests__/csrf-constants-sync.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CSRF_COOKIE_NAME as DISPATCHER_CSRF_COOKIE_NAME,
+  CSRF_HEADER_NAME as DISPATCHER_CSRF_HEADER_NAME,
+} from "@cosmicdrift/kumiko-dispatcher-live";
+import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "../auth-middleware";
+
+// dispatcher-live keeps its own literal copies of these two constants
+// (see packages/dispatcher-live/src/csrf.ts) because it must stay
+// server-dep-free for browser/React Native bundles. This test is the
+// guardrail that catches drift in CI instead of at runtime.
+describe("CSRF constant sync between framework and dispatcher-live", () => {
+  test("cookie name matches", () => {
+    expect(DISPATCHER_CSRF_COOKIE_NAME).toBe(CSRF_COOKIE_NAME);
+  });
+
+  test("header name matches", () => {
+    expect(DISPATCHER_CSRF_HEADER_NAME).toBe(CSRF_HEADER_NAME);
+  });
+});

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

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import * as jose from "jose";
 import type { SessionUser } from "../../engine/types";
-import { createJwtHelper } from "../jwt";
+import { createJwtHelper, loadJwtSecretOrKeyring } from "../jwt";
 
 const SECRET = "test-secret-at-least-32-characters-long-aa";
 const TENANT = "11111111-1111-4111-8111-111111111111";
@@ -83,3 +83,152 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
     await expect(jwt.verify(token)).rejects.toThrow(/sub/);
   });
 });
+
+describe("createJwtHelper — keyring form", () => {
+  it("sets kid in the protected header when signing from a keyring", async () => {
+    const jwt = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await jwt.sign(user);
+    expect(jose.decodeProtectedHeader(token).kid).toBe("v1");
+  });
+
+  it("verifies a keyring-signed token against a string-form helper on the same secret", async () => {
+    const keyringSigner = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await keyringSigner.sign(user);
+
+    const stringVerifier = createJwtHelper(SECRET);
+    const payload = await stringVerifier.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("omits kid when signing from a plain secret (string form)", async () => {
+    const jwt = createJwtHelper(SECRET);
+    const token = await jwt.sign(user);
+    expect(jose.decodeProtectedHeader(token).kid).toBeUndefined();
+  });
+
+  it("verifies a token signed under an old kid after rotating signKid", async () => {
+    const OLD_SECRET = "old-secret-at-least-32-characters-long-aa";
+    const before = createJwtHelper({ keys: { v1: OLD_SECRET }, signKid: "v1" });
+    const token = await before.sign(user);
+
+    const after = createJwtHelper({ keys: { v1: OLD_SECRET, v2: SECRET }, signKid: "v2" });
+    const payload = await after.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("verifies a legacy no-kid token against a multi-key keyring", async () => {
+    const legacy = createJwtHelper(SECRET);
+    const token = await legacy.sign(user);
+
+    const rotated = createJwtHelper({
+      keys: { v1: "unrelated-secret-32-characters-longg", v2: SECRET },
+      signKid: "v2",
+    });
+    const payload = await rotated.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("rejects a token whose kid is not in the keyring", async () => {
+    const signer = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await signer.sign(user);
+
+    const verifier = createJwtHelper({ keys: { v2: SECRET }, signKid: "v2" });
+    await expect(verifier.verify(token)).rejects.toThrow(/kid/);
+  });
+
+  it("throws at creation when signKid is not present in the keyring", () => {
+    expect(() => createJwtHelper({ keys: { v1: SECRET }, signKid: "v2" })).toThrow(/signKid/);
+  });
+});
+
+describe("loadJwtSecretOrKeyring", () => {
+  it("no JWT_SECRET_V<n> → falls back to plain JWT_SECRET", () => {
+    expect(loadJwtSecretOrKeyring({ JWT_SECRET: SECRET })).toBe(SECRET);
+  });
+
+  it("neither JWT_SECRET_V<n> nor JWT_SECRET set → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({})).toThrow(/JWT_SECRET not set/);
+  });
+
+  it("JWT_SECRET_V1 + JWT_SECRET_CURRENT_VERSION=1 → single-key keyring, signKid v1", () => {
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET }, signKid: "v1" });
+  });
+
+  it("rotation: two versions, current-version picks the sign key, both stay verifiable", () => {
+    const OLD_SECRET = "old-secret-at-least-32-characters-long!!";
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: OLD_SECRET,
+        JWT_SECRET_V2: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "2",
+      }),
+    ).toEqual({ keys: { v1: OLD_SECRET, v2: SECRET }, signKid: "v2" });
+  });
+
+  it("JWT_SECRET_V<n> present but JWT_SECRET_CURRENT_VERSION missing → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({ JWT_SECRET_V1: SECRET })).toThrow(
+      /JWT_SECRET_CURRENT_VERSION not set/,
+    );
+  });
+
+  it("JWT_SECRET_CURRENT_VERSION points at a version with no matching JWT_SECRET_V<n> → throws", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "2",
+      }),
+    ).toThrow(/not present in the keyring/);
+  });
+
+  it("plain JWT_SECRET is ignored once a keyring is present", () => {
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: "should-be-ignored-once-keyring-present-aa",
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET }, signKid: "v1" });
+  });
+
+  it("plain JWT_SECRET under 32 chars → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({ JWT_SECRET: "too-short" })).toThrow(
+      /JWT_SECRET must be ≥32 chars/,
+    );
+  });
+
+  it("JWT_SECRET_V<n> under 32 chars → throws (bypasses the env-schema check otherwise)", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: "too-short",
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toThrow(/JWT_SECRET_V1 must be ≥32 chars/);
+  });
+});
+
+describe("createJwtHelper — ttlSeconds", () => {
+  it("defaults to 24h", () => {
+    const jwt = createJwtHelper(SECRET);
+    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+  });
+
+  it("exposes a custom ttlSeconds", () => {
+    const jwt = createJwtHelper(SECRET, ISSUER, 60 * 60);
+    expect(jwt.ttlSeconds).toBe(60 * 60);
+  });
+
+  it("signs a token whose exp - iat exactly equals ttlSeconds", async () => {
+    const ttlSeconds = 60 * 60;
+    const jwt = createJwtHelper(SECRET, ISSUER, ttlSeconds);
+    const token = await jwt.sign(user);
+    const claims = jose.decodeJwt(token);
+    expect(claims.exp).toBeDefined();
+    expect(claims.iat).toBeDefined();
+    expect(claims.exp! - claims.iat!).toBe(ttlSeconds);
+  });
+});

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

@@ -0,0 +1,66 @@
+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);
+  });
+});

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/api-constants.ts

@@ -20,6 +20,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
@@ -42,6 +44,8 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/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.