@cosmicdrift/kumiko-framework 0.159.1 → 0.160.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.159.1",
+  "version": "0.160.0",
   "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,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.159.1",
+    "@cosmicdrift/kumiko-types": "0.160.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.159.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.160.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -28,6 +28,17 @@ const testFeature = defineFeature("test", (r) => {
     async () => [{ id: 1, name: "Test" }],
     { access: { openToAll: true } },
   );
+
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 const registry = createRegistry([testFeature]);
@@ -215,6 +226,60 @@ 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);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: 3 } },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+    const frames = parseSseFrames(await res.text());
+    expect(frames).toEqual([
+      { event: "chunk", data: JSON.stringify({ i: 0 }) },
+      { event: "chunk", data: JSON.stringify({ i: 1 }) },
+      { event: "chunk", data: JSON.stringify({ i: 2 }) },
+      { event: "done", data: "" },
+    ]);
+  });
+
+  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.
+    const headers = await authHeader(guestUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: 1 } },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    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" });
+  });
+});
+
 // --- r.httpRoute (feature-deklarierte HTTP-Routes außerhalb /api/) ---
 
 describe("feature-declared HTTP routes (r.httpRoute)", () => {

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

@@ -37,6 +37,7 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async query(): Promise<unknown> {
       return [];
     },
+    async *stream(): AsyncGenerator<unknown> {},
     async command(): Promise<void> {},
     async batch(): Promise<BatchResult> {
       const ok: BatchResult = { isSuccess: true, results: [] };

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

@@ -0,0 +1,237 @@
+// auth-routes invalid_body + invite-accept success paths — HTTP-layer only,
+// stub Dispatcher (same pattern as auth-routes-mfa-verify.test.ts).
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import type { SessionUser, TenantId } from "../../engine/types";
+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 } from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-routes-invalid-body-invite-secret-min-32-chars";
+const INVITE_ACCEPT_QN = "auth:write:invite-accept";
+const INVITE_LOGIN_QN = "auth:write:invite-accept-with-login";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      const ok: WriteResult = { isSuccess: true, data: { kind: "noop" } };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      return { isSuccess: true, results: [] };
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+    // Stream API added with r.streamHandler (#1446) — stub unused in these routes.
+    async *stream(): AsyncGenerator<unknown> {},
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono; validToken: string }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const validToken = await jwt.sign(TestUsers.user);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    loginHandler: "auth:write:login",
+    loginRateLimit: 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, validToken };
+}
+
+const inviteConfig: AuthRoutesConfig["invite"] = {
+  acceptHandler: INVITE_ACCEPT_QN,
+  acceptWithLoginHandler: INVITE_LOGIN_QN,
+  signupCompleteHandler: "auth:write:invite-signup-complete",
+};
+
+describe("POST /auth/login — invalid_body", () => {
+  test("400 when password field is missing", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return { isSuccess: true, data: { kind: "auth-session", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c" }),
+    });
+    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);
+  });
+});
+
+describe("POST /auth/invite-accept", () => {
+  test("requires JWT — not a public route", async () => {
+    expect(PUBLIC_API_PATHS.has("/api/auth/invite-accept")).toBe(false);
+  });
+
+  test("400 invalid_body before dispatch", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return {
+          isSuccess: true,
+          data: {
+            kind: "invite-accepted",
+            tenantId: TestUsers.otherTenant.tenantId,
+            role: "User",
+            alreadyMember: false,
+          },
+        };
+      },
+    });
+    const { app, validToken } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${validToken}`,
+      },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()) as { isSuccess: boolean; error: string }).toMatchObject({
+      isSuccess: false,
+      error: "invalid_body",
+    });
+    expect(dispatched).toBe(false);
+  });
+
+  test("success returns tenantId, role, alreadyMember", async () => {
+    const tenantId = TestUsers.otherTenant.tenantId as TenantId;
+    let receivedUser: SessionUser | undefined;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload, user): Promise<WriteResult> {
+        expect(qn).toBe(INVITE_ACCEPT_QN);
+        expect(payload).toEqual({ token: "invite-token-abc" });
+        receivedUser = user;
+        return {
+          isSuccess: true,
+          data: {
+            kind: "invite-accepted",
+            tenantId,
+            role: "Editor",
+            alreadyMember: true,
+          },
+        };
+      },
+    });
+    const { app, validToken } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${validToken}`,
+      },
+      body: JSON.stringify({ token: "invite-token-abc" }),
+    });
+    expect(res.status).toBe(200);
+    expect(receivedUser?.id).toBe(TestUsers.user.id);
+    expect(await res.json()).toEqual({
+      isSuccess: true,
+      tenantId,
+      role: "Editor",
+      alreadyMember: true,
+    });
+  });
+});
+
+describe("POST /auth/invite-accept-with-login — invalid_body + success", () => {
+  test("400 when email missing", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return { isSuccess: true, data: { kind: "auth-session", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept-with-login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token: "t", password: "long-enough-pw" }),
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()) as { error: string }).toMatchObject({
+      isSuccess: false,
+      error: "invalid_body",
+    });
+    expect(dispatched).toBe(false);
+  });
+
+  test("success mints JWT + cookies", async () => {
+    const tenantId = TestUsers.otherTenant.tenantId as TenantId;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload): Promise<WriteResult> {
+        expect(qn).toBe(INVITE_LOGIN_QN);
+        expect(payload).toEqual({
+          token: "invite-t",
+          email: "user@example.com",
+          password: "password123",
+        });
+        return {
+          isSuccess: true,
+          data: {
+            kind: "auth-session",
+            session: TestUsers.user,
+            tenantId,
+            role: "User",
+          },
+        };
+      },
+    });
+    const { app } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept-with-login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        token: "invite-t",
+        email: "user@example.com",
+        password: "password123",
+      }),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      isSuccess: boolean;
+      token: string;
+      tenantId: TenantId;
+      role: string;
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.tenantId).toBe(tenantId);
+    expect(body.role).toBe("User");
+    expect(getSetCookies(res).get(AUTH_COOKIE_NAME)).toBeDefined();
+    expect(getSetCookies(res).get(CSRF_COOKIE_NAME)).toBeDefined();
+  });
+});

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

@@ -36,6 +36,7 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async query(): Promise<unknown> {
       return [];
     },
+    async *stream(): AsyncGenerator<unknown> {},
     async command(): Promise<void> {},
     async batch(): Promise<BatchResult> {
       const ok: BatchResult = { isSuccess: true, results: [] };

package/src/api/__tests__/dispatcher-live.integration.test.ts

@@ -48,6 +48,17 @@ const itemFeature = defineFeature("dlive", (r) => {
     },
     { access: { roles: ["Admin"] } },
   );
+
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i, name: `n-${i}` };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 let stack: TestStack;
@@ -215,4 +226,67 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
     const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(0);
   });
+
+  test("stream: yields every chunk then completes (live dispatcher ↔ POST /api/stream)", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    const chunks: Array<{ i: number; name: string }> = [];
+    for await (const chunk of dispatcher.stream<{ i: number; name: string }>(
+      "dlive:stream:item:tail",
+      { count: 3 },
+    )) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks).toEqual([
+      { i: 0, name: "n-0" },
+      { i: 1, name: "n-1" },
+      { i: 2, name: "n-2" },
+    ]);
+  });
+
+  test("stream: access-denied mid-stream throws mapped DispatcherError (HTTP still 200 SSE)", async () => {
+    // Non-Admin JWT — stream handler requires Admin. Gate fires after SSE
+    // headers are flushed, so the client sees an error frame, not HTTP 403.
+    const csrfToken = generateToken();
+    const guestJwt = await stack.jwt.sign(TestUsers.user);
+    const cookieHeader = `kumiko_auth=${guestJwt}; kumiko_csrf=${csrfToken}`;
+    const fetchImpl = (async (url: unknown, init: RequestInit | undefined) => {
+      return stack.app.request(String(url), {
+        ...(init ?? {}),
+        headers: { ...(init?.headers ?? {}), Cookie: cookieHeader },
+      });
+    }) as unknown as typeof fetch;
+    const dispatcher = createLiveDispatcher({ fetch: fetchImpl, readCsrf: () => csrfToken });
+
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("dlive:stream:item:tail", { count: 1 })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "access_denied" });
+  });
+
+  test("stream: validation failure throws mapped DispatcherError from error frame", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("dlive:stream:item:tail", { count: -1 })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "validation_error" });
+  });
+
+  // AbortSignal mid-stream against Hono's in-memory `app.request` is
+  // unreliable (body often fully buffered before abort lands). Abort
+  // mapping for stream is covered in dispatcher-live unit tests.
 });

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

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { createInMemoryLoginRateLimiter } from "../auth-routes";
+
+describe("createInMemoryLoginRateLimiter — sweep + cap", () => {
+  test("sweepExpired drops windows that already reset before accepting a new key", async () => {
+    // Tiny thresholds so the Map hits the sweep path without flooding.
+    const limiter = createInMemoryLoginRateLimiter(10, 50, {
+      maxEntries: 100,
+      sweepThreshold: 2,
+    });
+
+    expect(await limiter.check("a")).toBe(true);
+    expect(await limiter.check("b")).toBe(true);
+    // Wait for both windows to expire, then a third check must sweep a+b
+    // (hits.size >= sweepThreshold) before inserting "c".
+    await Bun.sleep(60);
+    expect(await limiter.check("c")).toBe(true);
+    // Fresh window for "a" after sweep — not rate-limited.
+    expect(await limiter.check("a")).toBe(true);
+  });
+
+  test("enforceCap drops oldest entries when the map exceeds maxEntries", async () => {
+    const limiter = createInMemoryLoginRateLimiter(100, 60_000, {
+      maxEntries: 3,
+      sweepThreshold: 10_000, // never sweep — only the hard cap matters
+    });
+
+    expect(await limiter.check("k1")).toBe(true);
+    expect(await limiter.check("k2")).toBe(true);
+    expect(await limiter.check("k3")).toBe(true);
+    // 4th insert trips enforceCap → drops oldest (k1).
+    expect(await limiter.check("k4")).toBe(true);
+
+    // k1 was dropped — a fresh check starts a new window (allowed).
+    expect(await limiter.check("k1")).toBe(true);
+    // k2/k3/k4 still live in the map (cap=3 after k1 drop + k1 reinsert may
+    // drop another). Reset proves the API still works for survivors.
+    await limiter.reset("k4");
+    expect(await limiter.check("k4")).toBe(true);
+  });
+});

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

@@ -10,6 +10,7 @@ export const Routes = {
   query: "/query",
   command: "/command",
   sse: "/sse",
+  stream: "/stream",
   auth: "/auth",
   authLogin: "/auth/login",
   authMfaVerify: "/auth/mfa/verify",

package/src/api/routes.ts

@@ -1,4 +1,5 @@
 import { type Context, Hono } from "hono";
+import { streamSSE } from "hono/streaming";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import type { SessionUser } from "../engine/types/handlers";
 import {
@@ -16,6 +17,7 @@ import { Routes } from "./api-constants";
 import { getUser } from "./auth-middleware";
 import { patAllows } from "./pat-scope";
 import { requestContext } from "./request-context";
+import { SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route";
 
 export function createApiRoutes(dispatcher: Dispatcher) {
   const api = new Hono();
@@ -121,6 +123,61 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     }
   });
 
+  // Dispatcher-driven SSE, full auth/CSRF/rate-limit chain (unlike the
+  // broker-based /sse route). Frame contract for clients: "chunk" (one per
+  // yielded value, JSON-encoded), "ping" (heartbeat, empty data), "done"
+  // (terminal, empty data), "error" (terminal, JSON error envelope — the
+  // response status stays 200 since SSE headers are already flushed before
+  // dispatch gates run on the generator's first pull).
+  api.post(Routes.stream, async (c) => {
+    const user = getUser(c);
+    const body = await c.req.json<{ type: string; payload: unknown }>();
+    const requestId = requestContext.get()?.requestId;
+
+    try {
+      assertPatAllowed(user, body.type);
+    } catch (e) {
+      return queryErrorResponse(c, toKumiko(e), body.type);
+    }
+
+    return streamSSE(c, async (stream) => {
+      const generator = dispatcher.stream(body.type, body.payload, user);
+      stream.onAbort(() => {
+        void generator.return(undefined);
+      });
+
+      try {
+        let pending = generator.next();
+        while (true) {
+          let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
+          const heartbeat = new Promise<"heartbeat">((resolve) => {
+            heartbeatTimer = setTimeout(() => resolve("heartbeat"), SSE_HEARTBEAT_INTERVAL_MS);
+          });
+          let outcome: Awaited<typeof pending> | "heartbeat";
+          try {
+            outcome = await Promise.race([pending, heartbeat]);
+          } finally {
+            clearTimeout(heartbeatTimer);
+          }
+
+          if (outcome === "heartbeat") {
+            await stream.writeSSE({ event: "ping", data: "" });
+            continue;
+          }
+          if (outcome.done) break;
+          await stream.writeSSE({ event: "chunk", data: stringifyJson(outcome.value) });
+          pending = generator.next();
+        }
+        await stream.writeSSE({ event: "done", data: "" });
+      } catch (e) {
+        const err = toKumiko(e);
+        logServerFault(err, requestId, body.type);
+        const { error } = serializeError(err, requestId);
+        await stream.writeSSE({ event: "error", data: stringifyJson(error) });
+      }
+    });
+  });
+
   return api;
 }