@cosmicdrift/kumiko-framework 0.1.0

package/src/api/__tests__/body-limit.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { buildServer } from "../server";
+
+const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
+
+const testFeature = defineFeature("blob", (r) => {
+  r.entity("note", createEntity({ table: "Notes", fields: { body: createTextField() } }));
+  r.writeHandler(
+    "note:create",
+    z.object({ body: z.string() }),
+    async (event) => ({ isSuccess: true, data: { body: event.payload.body } }),
+    { access: { openToAll: true } },
+  );
+});
+
+function buildApp(maxRequestBytes?: number) {
+  const registry = createRegistry([testFeature]);
+  return buildServer({
+    registry,
+    context: {},
+    jwtSecret: JWT_SECRET,
+    maxRequestBytes,
+  }).app;
+}
+
+function postJson(app: ReturnType<typeof buildApp>, path: string, bytes: number) {
+  const body = JSON.stringify({ body: "x".repeat(bytes) });
+  return app.request(path, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Content-Length": String(body.length),
+    },
+    body,
+  });
+}
+
+describe("request body limit", () => {
+  test("rejects POST with body larger than maxRequestBytes with 413", async () => {
+    const app = buildApp(1024);
+    const res = await postJson(app, "/api/write", 2048);
+    expect(res.status).toBe(413);
+  });
+
+  test("accepts POST with body within the limit (reaches auth layer)", async () => {
+    const app = buildApp(10_000);
+    const res = await postJson(app, "/api/write", 100);
+    // No JWT → 401. Point is: NOT 413.
+    expect(res.status).toBe(401);
+  });
+
+  test("default limit rejects absurdly large payloads", async () => {
+    const app = buildApp(); // default 1 MB
+    const res = await postJson(app, "/api/write", 2_000_000); // 2 MB
+    expect(res.status).toBe(413);
+  });
+
+  test("default limit accepts small payloads", async () => {
+    const app = buildApp();
+    const res = await postJson(app, "/api/write", 500);
+    expect(res.status).toBe(401); // auth required, but size is fine
+  });
+
+  test("limit is not applied to /api/files (uploads have their own cap)", async () => {
+    // /api/files isn't mounted on this test app (no storageProvider), so a POST
+    // results in 404 — the point is: NOT 413. A payload that exceeds the JSON
+    // cap must still reach the route layer for the files router to decide.
+    const app = buildApp(1024);
+    const body = JSON.stringify({ body: "x".repeat(4096) });
+    const res = await app.request("/api/files", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": String(body.length),
+      },
+      body,
+    });
+    expect(res.status).not.toBe(413);
+  });
+
+  test("maxRequestBytes=0 disables the cap entirely", async () => {
+    const app = buildApp(0);
+    const res = await postJson(app, "/api/write", 50_000);
+    expect(res.status).toBe(401); // passes body-limit, reaches auth
+  });
+});

package/src/api/__tests__/csrf-middleware.test.ts

@@ -0,0 +1,97 @@
+// csrf-middleware: double-submit token check against a Hono app that
+// layers authMiddleware → csrfMiddleware → handler. Covers the paths that
+// matter in production: cookie + state-changing, cookie + safe, bearer.
+
+import { Hono } from "hono";
+import { describe, expect, test } from "vitest";
+import { TestUsers } from "../../stack";
+import {
+  AUTH_COOKIE_NAME,
+  authMiddleware,
+  CSRF_COOKIE_NAME,
+  CSRF_HEADER_NAME,
+} from "../auth-middleware";
+import { csrfMiddleware } from "../csrf-middleware";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "csrf-middleware-test-secret-min-32-characters-long";
+const CSRF = "csrf-token-fixed-for-test";
+
+async function buildApp(): Promise<{ app: Hono; token: string }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const token = await jwt.sign(TestUsers.user);
+  const app = new Hono();
+  app.use("/api/*", authMiddleware(jwt));
+  app.use("/api/*", csrfMiddleware());
+  app.get("/api/ping", (c) => c.json({ ok: true }));
+  app.post("/api/write", (c) => c.json({ ok: true }));
+  return { app, token };
+}
+
+describe("csrf-middleware", () => {
+  test("bearer transport skips csrf check even on POST", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("cookie transport + GET → no csrf check (safe method)", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/ping", {
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}` },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("cookie transport + POST + matching csrf → ok", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: {
+        Cookie: `${AUTH_COOKIE_NAME}=${token}; ${CSRF_COOKIE_NAME}=${CSRF}`,
+        [CSRF_HEADER_NAME]: CSRF,
+      },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("cookie transport + POST + missing header → 403", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: {
+        Cookie: `${AUTH_COOKIE_NAME}=${token}; ${CSRF_COOKIE_NAME}=${CSRF}`,
+      },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("csrf_token_mismatch");
+  });
+
+  test("cookie transport + POST + wrong header → 403", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: {
+        Cookie: `${AUTH_COOKIE_NAME}=${token}; ${CSRF_COOKIE_NAME}=${CSRF}`,
+        [CSRF_HEADER_NAME]: "wrong-value",
+      },
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("cookie transport + POST + missing csrf cookie → 403", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/write", {
+      method: "POST",
+      headers: {
+        Cookie: `${AUTH_COOKIE_NAME}=${token}`,
+        [CSRF_HEADER_NAME]: CSRF,
+      },
+    });
+    expect(res.status).toBe(403);
+  });
+});

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

@@ -0,0 +1,216 @@
+import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { generateToken } from "../../api/tokens";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { generateId } from "../../utils";
+
+// End-to-end: UI code would call `dispatcher.write("feat:write:item:create", ...)`.
+// This test wires dispatcher-live against the real Kumiko HTTP stack via
+// Hono's `app.request()` (in-memory, no port) and proves the whole path:
+//   dispatcher-live → JSON body + headers → Hono route → dispatcher →
+//   write-handler → crud-executor → DB → response → dispatcher-live →
+//   typed WriteResult.
+//
+// Server-side CSRF middleware is enabled by the normal server config, so
+// the dispatcher must carry X-CSRF-Token correctly or these writes would
+// land as 403. The test proves that wiring end-to-end.
+
+const itemEntity = createEntity({
+  table: "dispatcher_live_items",
+  fields: { name: createTextField({ required: true }) },
+});
+const itemTable = buildDrizzleTable("item", itemEntity);
+
+const itemFeature = defineFeature("dlive", (r) => {
+  r.entity("item", itemEntity);
+
+  r.writeHandler(
+    "item:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(itemTable, itemEntity, { entityName: "item" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.queryHandler(
+    "item:list",
+    z.object({}).optional(),
+    async (_event, ctx) => {
+      return ctx.db.select().from(itemTable);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+// Wire dispatcher-live's `fetch` to Hono's in-memory `app.request`. Also
+// synthesizes the auth + CSRF cookies a real browser would send: the stack
+// exposes the Hono app, but the normal login-flow-based session-cookie
+// setup isn't in play here — we sign a JWT directly and set both the
+// `kumiko_auth` (HttpOnly JWT) and `kumiko_csrf` cookies by hand. A
+// real browser login does the same server-side via auth-routes.ts.
+//
+// GAP: this means the real POST /auth/login round-trip (Set-Cookie
+// headers, CSRF-cookie generation on the server, SameSite/HttpOnly
+// flags as actually emitted) is NOT exercised here. If we ever change
+// the login endpoint's cookie-setting code, this file will not catch
+// regressions — the dedicated auth-routes integration test owns that
+// coverage. Keep this test focused on dispatcher-live's request-side
+// behaviour (envelope parsing, error mapping, CSRF-header echo).
+//
+// The fetch wrapper echoes the csrf cookie back into the X-CSRF-Token
+// header — that's the real dispatcher-live code path; the test just
+// stages the cookies first.
+async function buildFetch(): Promise<{
+  readonly fetch: typeof fetch;
+  readonly csrfToken: string;
+  readonly authJwt: string;
+}> {
+  const authJwt = await stack.jwt.sign(admin);
+  const csrfToken = generateToken();
+  const cookieHeader = `kumiko_auth=${authJwt}; kumiko_csrf=${csrfToken}`;
+
+  // Cast via unknown: the native fetch interface (Bun's typing) includes a
+  // `preconnect` method we don't need and can't meaningfully implement
+  // against Hono's in-memory request handler. dispatcher-live calls the
+  // functional shape only — preconnect is a hint, not load-bearing.
+  const fetchImpl = (async (url: unknown, init: RequestInit | undefined) => {
+    const reqInit: RequestInit = {
+      ...(init ?? {}),
+      headers: {
+        ...(init?.headers ?? {}),
+        Cookie: cookieHeader,
+      },
+    };
+    return stack.app.request(String(url), reqInit);
+  }) as unknown as typeof fetch;
+  return { fetch: fetchImpl, csrfToken, authJwt };
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [itemFeature] });
+  await createEntityTable(stack.db, itemEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.db.delete(itemTable);
+});
+
+describe("dispatcher-live (integration) — full path against Kumiko server", () => {
+  test("write: dispatches HTTP, server persists, response maps to typed WriteResult", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({
+      fetch,
+      readCsrf: () => csrfToken,
+    });
+
+    const result = await dispatcher.write<{ data?: { name?: string } }>("dlive:write:item:create", {
+      name: "hello-live",
+    });
+
+    expect(result.isSuccess).toBe(true);
+
+    // Prove the server actually persisted.
+    const rows = await stack.db.select().from(itemTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["name"]).toBe("hello-live");
+  });
+
+  test("write: validation failure surfaces as typed DispatcherError with field issues", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    const result = await dispatcher.write("dlive:write:item:create", { name: "" });
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("validation_error");
+      const fieldPaths = (result.error.details?.fields ?? []).map((f) => f.path);
+      expect(fieldPaths).toContain("name");
+    }
+  });
+
+  test("missing CSRF token: server rejects — exercises Vorarbeit-A wiring", async () => {
+    const { fetch } = await buildFetch();
+    // Dispatcher with no csrf reader — the header won't be sent.
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => undefined });
+
+    const result = await dispatcher.write("dlive:write:item:create", { name: "no-csrf" });
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      // The CSRF middleware raises with code "csrf_token_mismatch".
+      expect(result.error.code).toBe("csrf_token_mismatch");
+    }
+  });
+
+  test("query: dispatches GET-style-POST (Kumiko uses POST for query too), returns data", async () => {
+    // Seed a row first.
+    await stack.db.insert(itemTable).values({
+      id: generateId(),
+      tenantId: admin.tenantId,
+      name: "seed",
+    });
+
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    const result = await dispatcher.query<unknown[]>("dlive:query:item:list", {});
+
+    expect(result.isSuccess).toBe(true);
+    if (result.isSuccess) {
+      expect(Array.isArray(result.data)).toBe(true);
+      expect(result.data).toHaveLength(1);
+    }
+  });
+
+  test("batch: multiple writes go through one HTTP call, atomic on the server", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    const result = await dispatcher.batch([
+      { type: "dlive:write:item:create", payload: { name: "a" } },
+      { type: "dlive:write:item:create", payload: { name: "b" } },
+      { type: "dlive:write:item:create", payload: { name: "c" } },
+    ]);
+
+    expect(result.isSuccess).toBe(true);
+
+    const rows = await stack.db.select().from(itemTable);
+    expect(rows).toHaveLength(3);
+    const names = rows.map((r) => r["name"]).sort();
+    expect(names).toEqual(["a", "b", "c"]);
+  });
+
+  test("batch: mid-batch failure rolls back the prior writes — atomic guarantee preserved", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    const result = await dispatcher.batch([
+      { type: "dlive:write:item:create", payload: { name: "ok-1" } },
+      { type: "dlive:write:item:create", payload: { name: "" } }, // fails validation
+      { type: "dlive:write:item:create", payload: { name: "never-runs" } },
+    ]);
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.failedIndex).toBe(1);
+    }
+
+    // DB must be empty — prior success within a failed batch rolls back.
+    const rows = await stack.db.select().from(itemTable);
+    expect(rows).toHaveLength(0);
+  });
+});

package/src/api/__tests__/metrics-endpoint.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "vitest";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import {
+  createNoopProvider,
+  createPrometheusMeter,
+  type ObservabilityProvider,
+} from "../../observability";
+import { buildServer } from "../server";
+
+const JWT = "metrics-endpoint-test-secret-minimum-32-chars!!";
+
+const noopFeature = defineFeature("m", (r) => {
+  r.entity("widget", createEntity({ table: "Widgets", fields: { name: createTextField() } }));
+});
+
+// Swap the NoopProvider's meter for a PrometheusMeter. Tracer + lifecycle
+// stay noop — /metrics only reads the meter.
+function makeProvider(): {
+  provider: ObservabilityProvider;
+  meter: ReturnType<typeof createPrometheusMeter>;
+} {
+  const meter = createPrometheusMeter();
+  const base = createNoopProvider();
+  const provider: ObservabilityProvider = { ...base, meter };
+  return { provider, meter };
+}
+
+function makeApp(opts: {
+  metrics?: { token?: string; path?: string };
+  meter?: ReturnType<typeof createPrometheusMeter>;
+  provider?: ObservabilityProvider;
+}) {
+  const registry = createRegistry([noopFeature]);
+  const build = opts.provider
+    ? { provider: opts.provider, meter: opts.meter ?? null }
+    : makeProvider();
+  const args = {
+    registry,
+    context: {},
+    jwtSecret: JWT,
+    observability: build.provider,
+    ...(opts.metrics ? { metrics: opts.metrics } : {}),
+  };
+  return { ...buildServer(args), meter: build.meter };
+}
+
+describe("/metrics endpoint", () => {
+  test("returns 404 when `metrics` option is not wired (opt-in)", async () => {
+    const { app } = makeApp({});
+    const res = await app.request("/metrics");
+    expect(res.status).toBe(404);
+  });
+
+  test("returns OpenMetrics text when wired and meter is a PrometheusMeter", async () => {
+    const { app, meter } = makeApp({ metrics: {} });
+    if (!meter) throw new Error("meter missing");
+    // Seed a single metric so the output isn't empty.
+    meter.registerMetric({
+      name: "kumiko_test_total",
+      type: "counter",
+      description: "probe counter",
+    });
+    meter.counter("kumiko_test_total").inc(3);
+
+    const res = await app.request("/metrics");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toMatch(/openmetrics-text/);
+    const body = await res.text();
+    expect(body).toContain("# HELP kumiko_test_total probe counter");
+    expect(body).toContain("# TYPE kumiko_test_total counter");
+    expect(body).toContain("kumiko_test_total 3");
+    expect(body).toMatch(/# EOF\n$/);
+  });
+
+  test("token-protected: rejects missing header with 401", async () => {
+    const { app } = makeApp({ metrics: { token: "scrape-secret-xyz" } });
+    const res = await app.request("/metrics");
+    expect(res.status).toBe(401);
+  });
+
+  test("token-protected: rejects wrong token with 401", async () => {
+    const { app } = makeApp({ metrics: { token: "scrape-secret-xyz" } });
+    const res = await app.request("/metrics", {
+      headers: { Authorization: "Bearer wrong-token" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("token-protected: accepts matching Bearer token", async () => {
+    const { app, meter } = makeApp({ metrics: { token: "scrape-secret-xyz" } });
+    if (!meter) throw new Error("meter missing");
+    meter.registerMetric({ name: "kumiko_probe", type: "counter" });
+    meter.counter("kumiko_probe").inc();
+
+    const res = await app.request("/metrics", {
+      headers: { Authorization: "Bearer scrape-secret-xyz" },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("custom path: /internal/metrics", async () => {
+    const { app, meter } = makeApp({ metrics: { path: "/internal/metrics" } });
+    if (!meter) throw new Error("meter missing");
+    meter.registerMetric({ name: "kumiko_probe", type: "counter" });
+
+    const atDefault = await app.request("/metrics");
+    expect(atDefault.status).toBe(404);
+
+    const atCustom = await app.request("/internal/metrics");
+    expect(atCustom.status).toBe(200);
+  });
+
+  test("503 when meter lacks snapshot() (misconfig — non-Prometheus provider)", async () => {
+    // Build a provider whose meter is a raw non-Prometheus implementation —
+    // pretend it's a ConsoleProvider or an OTLP bridge without snapshot().
+    const { createNoopProvider } = await import("../../observability");
+    const provider = createNoopProvider();
+    // NoopProvider is "empty by design", register a metric so definitions
+    // isn't hollow, but snapshot() is still absent on the meter shape.
+    provider.meter.registerMetric({ name: "kumiko_noop", type: "counter" });
+    const { app } = makeApp({ provider, metrics: {} });
+    const res = await app.request("/metrics");
+    expect(res.status).toBe(503);
+    expect(await res.text()).toContain("PrometheusMeter");
+  });
+});