@cosmicdrift/kumiko-framework 0.1.0

package/src/api/sse-broker.ts

@@ -0,0 +1,71 @@
+import { generateId } from "../utils";
+
+export type SseClient = {
+  id: string;
+  send: (event: SseEvent) => void;
+  close: () => void;
+};
+
+export type SseEvent = {
+  type: string;
+  data: Record<string, unknown>;
+};
+
+export type SseBroker = {
+  addClient(channel: string, send: (event: SseEvent) => void, close: () => void): string;
+  removeClient(channel: string, clientId: string): void;
+  pushToChannel(channel: string, event: SseEvent): void;
+  getClientCount(channel: string): number;
+  getTotalClientCount(): number;
+};
+
+export function createSseBroker(): SseBroker {
+  const channels = new Map<string, Map<string, SseClient>>();
+
+  function getOrCreateChannel(channel: string): Map<string, SseClient> {
+    let clients = channels.get(channel);
+    if (!clients) {
+      clients = new Map();
+      channels.set(channel, clients);
+    }
+    return clients;
+  }
+
+  return {
+    addClient(channel, send, close) {
+      const clientId = generateId();
+      const clients = getOrCreateChannel(channel);
+      clients.set(clientId, { id: clientId, send, close });
+      return clientId;
+    },
+
+    removeClient(channel, clientId) {
+      const clients = channels.get(channel);
+      // skip: channel was never registered or already cleaned up
+      if (!clients) return;
+      clients.delete(clientId);
+      if (clients.size === 0) channels.delete(channel);
+    },
+
+    pushToChannel(channel, event) {
+      const clients = channels.get(channel);
+      // skip: no listeners on this channel, event has no audience
+      if (!clients) return;
+      for (const client of clients.values()) {
+        client.send(event);
+      }
+    },
+
+    getClientCount(channel) {
+      return channels.get(channel)?.size ?? 0;
+    },
+
+    getTotalClientCount() {
+      let total = 0;
+      for (const clients of channels.values()) {
+        total += clients.size;
+      }
+      return total;
+    },
+  };
+}

package/src/api/sse-route.ts

@@ -0,0 +1,62 @@
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { tenantChannel } from "../engine/constants";
+import { Routes } from "./api-constants";
+import { getUser } from "./auth-middleware";
+import type { SseBroker } from "./sse-broker";
+
+/**
+ * Heartbeat-Cadence für SSE-Streams.
+ *
+ * Spec: muss UNTER jedem realistischen Idle-Timeout der Hop-by-Hop-Layer
+ * liegen, sonst killt einer davon die Connection und der Browser sieht
+ * ERR_HTTP2_PROTOCOL_ERROR. Bekannte Limits:
+ *   - Bun.serve default: 10 s (lokal disabled via idleTimeout: 0,
+ *     aber Spec-konform auch ohne Override)
+ *   - Caddy reverse_proxy: kein default-Timeout für SSE (auto-detect
+ *     via Content-Type), aber langlebige idle Streams können von
+ *     Connection-Tracking dichtgemacht werden
+ *   - Cloudflare Edge: 100 s
+ *   - AWS ALB: 60 s
+ *
+ * 15 s liegt komfortabel unter allen davon. Server-side Cost ist
+ * marginal (1 Frame pro Client alle 15 s).
+ *
+ * Spec-Test in __tests__/sse-route-spec.test.ts pinst diesen Wert
+ * gegen versehentliches Hochsetzen.
+ */
+export const SSE_HEARTBEAT_INTERVAL_MS = 15_000;
+
+export function createSseRoute(broker: SseBroker) {
+  const route = new Hono();
+
+  route.get(Routes.sse, async (c) => {
+    const user = getUser(c);
+    // Channel is server-derived from authenticated user — never trust client input.
+    // Allowing ?channel=... would let any authenticated user subscribe to other tenants' feeds.
+    const channel = tenantChannel(user.tenantId);
+
+    return streamSSE(c, async (stream) => {
+      const clientId = broker.addClient(
+        channel,
+        (event) => {
+          stream.writeSSE({ event: event.type, data: JSON.stringify(event.data) });
+        },
+        () => stream.close(),
+      );
+
+      stream.onAbort(() => {
+        broker.removeClient(channel, clientId);
+      });
+
+      // Keep connection alive with heartbeat — siehe SSE_HEARTBEAT_INTERVAL_MS
+      // header für die Layer-für-Layer-Begründung der 15s-Cadence.
+      while (true) {
+        await stream.writeSSE({ event: "ping", data: "" });
+        await stream.sleep(SSE_HEARTBEAT_INTERVAL_MS);
+      }
+    });
+  });
+
+  return route;
+}

package/src/api/tokens.ts

@@ -0,0 +1,16 @@
+import { randomBytes } from "node:crypto";
+
+// Security tokens (CSRF cookie, one-shot correlation tokens that must
+// not be guessable from wall-clock time). Backend-only — imports
+// `node:crypto` and must not be pulled into a Metro/Expo-Web bundle.
+//
+// Unlike `generateId` (v7), this must not leak the creation timestamp:
+// a CSRF value whose first 6 bytes are "the millisecond the login
+// happened" is predictable. Every bit here is unpredictable.
+//
+// 32 bytes = 256 bits — session-class strength. base64url = 43 chars,
+// cookie- and URL-safe, matches the encoding of JWT segments / OAuth
+// state / WebAuthn challenges.
+export function generateToken(): string {
+  return randomBytes(32).toString("base64url");
+}

package/src/db/__tests__/apply-entity-event-tenant.integration.ts

@@ -0,0 +1,159 @@
+// Direkte Tests für applyEntityEvent's tenantId-Defaulting. Zwei
+// Branches (siehe apply-entity-event.ts:created):
+//
+//   - payload.tenantId GESETZT → wins (z.B. seedTenantMembership-Pfad
+//     wo Operator tenantId und Ziel-tenantId divergieren)
+//   - payload.tenantId NICHT gesetzt → Fallback auf event.tenantId
+//     (Replay-Fall für entity-Tabellen ohne tenantId-Feld)
+//
+// Beide Branches werden indirekt durch andere Tests berührt
+// (seedTenantMembership-Integration für A, Live==Rebuild für B), aber
+// kein expliziter Test pinst das exakte Verhalten von applyEntityEvent.
+// Wenn jemand die Spread-Reihenfolge im values()-Object umdreht
+// (`...event.payload, tenantId: event.tenantId` statt
+// `tenantId: event.tenantId, ...event.payload`), würde Branch A still
+// zerbrechen — der bestehende seed-Test wäre der einzige Catcher, und
+// der lief vor dem Refactor durch Zufall grün.
+
+import { eq, sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createEntity, createTextField } from "../../engine/factories";
+import type { TenantId } from "../../engine/types";
+import type { StoredEvent } from "../../event-store";
+import { createEventsTable } from "../../event-store";
+import { createTestDb, type TestDb } from "../../stack";
+import { applyEntityEvent } from "../apply-entity-event";
+import { buildDrizzleTable } from "../table-builder";
+
+const entity = createEntity({
+  table: "read_apply_tenant_check",
+  fields: {
+    name: createTextField({ required: true }),
+  },
+});
+const table = buildDrizzleTable("apply-tenant-check", entity);
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+  await testDb.db.execute(sql`
+    CREATE TABLE read_apply_tenant_check (
+      id uuid PRIMARY KEY,
+      tenant_id uuid NOT NULL,
+      version integer NOT NULL DEFAULT 1,
+      inserted_at timestamptz NOT NULL DEFAULT now(),
+      modified_at timestamptz,
+      inserted_by_id text,
+      modified_by_id text,
+      name text NOT NULL
+    )
+  `);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`TRUNCATE read_apply_tenant_check`);
+});
+
+const TENANT_OPERATOR = "11111111-1111-1111-1111-111111111111" as TenantId;
+const TENANT_TARGET = "22222222-2222-2222-2222-222222222222" as TenantId;
+
+function syntheticCreateEvent(payload: Record<string, unknown>): StoredEvent {
+  return {
+    id: "evt-1",
+    aggregateId: "33333333-3333-3333-3333-333333333333",
+    aggregateType: "apply-tenant-check",
+    tenantId: TENANT_OPERATOR,
+    version: 1,
+    type: "apply-tenant-check.created",
+    eventVersion: 1,
+    payload,
+    metadata: { userId: "u-1" },
+    createdAt: { toString: () => "2026-04-27T00:00:00Z" } as never,
+    createdBy: "u-1",
+  };
+}
+
+describe("applyEntityEvent — tenantId-Defaulting", () => {
+  test("payload OHNE tenantId → row.tenantId fällt auf event.tenantId zurück (Replay-Default)", async () => {
+    const event = syntheticCreateEvent({ name: "without-tenantId-in-payload" });
+    const result = await applyEntityEvent(event, table, entity, testDb.db);
+    expect(result.kind).toBe("applied");
+
+    const [row] = await testDb.db.select().from(table).where(eq(table["id"], event.aggregateId));
+    expect(row?.["tenantId"]).toBe(TENANT_OPERATOR);
+    expect(row?.["name"]).toBe("without-tenantId-in-payload");
+  });
+
+  test("payload MIT tenantId überschreibt event.tenantId (seed-Override-Case)", async () => {
+    // seedTenantMembership-Realität: Operator (event.tenantId =
+    // OPERATOR) schreibt eine Membership in den Ziel-Tenant (payload
+    // .tenantId = TARGET). Der Row gehört in den Ziel-Tenant.
+    const event = syntheticCreateEvent({
+      name: "tenantId-override",
+      tenantId: TENANT_TARGET,
+    });
+    const result = await applyEntityEvent(event, table, entity, testDb.db);
+    expect(result.kind).toBe("applied");
+
+    const [row] = await testDb.db.select().from(table).where(eq(table["id"], event.aggregateId));
+    expect(row?.["tenantId"]).toBe(TENANT_TARGET);
+    expect(row?.["tenantId"]).not.toBe(TENANT_OPERATOR);
+  });
+
+  test("payload.tenantId === '' (empty string) → wirft (fail-loud, kein silent fallback)", async () => {
+    // Tenant-isolation-kritisch: silent fallback auf event.tenantId
+    // würde eine Bug-payload (Form-Input ohne Trim-Check, defekter
+    // Hook etc.) in den Operator-Tenant schreiben, obwohl der
+    // Caller-Code die Row in irgendeinen Ziel-Tenant routen wollte.
+    // Cross-Tenant-Drift. Fail-loud ist die einzige Wahl.
+    const event = syntheticCreateEvent({
+      name: "empty-tenantId",
+      tenantId: "",
+    });
+    await expect(applyEntityEvent(event, table, entity, testDb.db)).rejects.toThrow(
+      /payload\.tenantId set but invalid/,
+    );
+  });
+
+  test("payload.tenantId === null → wirft (fail-loud)", async () => {
+    // Spiegel-Case. JSON-Payload kann literal null tragen (Hook der
+    // einen Wert auf null gesetzt hat statt zu unsetten). Auch hier
+    // kein silent fallback — tenant-isolation-kritisch.
+    const event = syntheticCreateEvent({
+      name: "null-tenantId",
+      tenantId: null,
+    });
+    await expect(applyEntityEvent(event, table, entity, testDb.db)).rejects.toThrow(
+      /payload\.tenantId set but invalid/,
+    );
+  });
+
+  test("Spread-Reihenfolge: payload-Felder bleiben erhalten, framework-Defaults nicht überschrieben", async () => {
+    // Negative-Anchor: id/version/insertedAt/insertedById dürfen NICHT
+    // aus dem payload kommen (kommen vom event). Wenn jemand die
+    // Reihenfolge im values() umstellt, würde dieser Test fangen.
+    const event = syntheticCreateEvent({
+      name: "spread-order-check",
+      // Diese Felder im payload müssen vom framework überschrieben werden:
+      id: "00000000-0000-0000-0000-000000000000",
+      version: 999,
+      insertedById: "fake-user",
+    });
+    const result = await applyEntityEvent(event, table, entity, testDb.db);
+    expect(result.kind).toBe("applied");
+
+    const [row] = await testDb.db.select().from(table).where(eq(table["id"], event.aggregateId));
+    // event.aggregateId wins, nicht payload.id
+    expect(row?.["id"]).toBe(event.aggregateId);
+    // event.version wins, nicht payload.version
+    expect(row?.["version"]).toBe(event.version);
+    // event.createdBy wins, nicht payload.insertedById
+    expect(row?.["insertedById"]).toBe(event.createdBy);
+  });
+});

package/src/db/__tests__/compound-types.test.ts

@@ -0,0 +1,114 @@
+// Tests für die Compound-Type-Pipeline.
+// Garantien die wir prüfen:
+//   - Identity bei leerem Payload / keinen Compound-Feldern
+//   - Beide Konverter werden gerufen wenn beide Field-Types vorkommen
+//   - Reihenfolge ist deterministisch + Konverter überlappen nicht
+//   - Pure (kein input-mutate)
+
+import { describe, expect, test } from "vitest";
+import {
+  createEntity,
+  createLocatedTimestampField,
+  createMoneyField,
+  createTextField,
+} from "../../engine";
+import type { EntityDefinition } from "../../engine/types";
+import { flattenCompoundTypes, rehydrateCompoundTypes } from "../compound-types";
+
+const mixedEntity: EntityDefinition = createEntity({
+  defaultCurrency: "EUR",
+  fields: {
+    label: createTextField(),
+    pickup: createLocatedTimestampField(),
+    buyingPrice: createMoneyField(),
+  },
+});
+
+describe("flattenCompoundTypes — Pipeline", () => {
+  test("identity bei Payload ohne Compound-Felder", () => {
+    const payload = { label: "ACME-001" };
+    const flat = flattenCompoundTypes(payload, mixedEntity);
+    expect(flat).toEqual({ label: "ACME-001" });
+  });
+
+  test("identity bei leerem Payload", () => {
+    expect(flattenCompoundTypes({}, mixedEntity)).toEqual({});
+  });
+
+  test("alle Konverter laufen wenn alle Compound-Types im Payload sind", () => {
+    const flat = flattenCompoundTypes(
+      {
+        label: "ACME",
+        pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" },
+        buyingPrice: { amount: 45_000, currency: "EUR" },
+      },
+      mixedEntity,
+    );
+    // Beide Compound-Konverter müssen gefeuert haben.
+    // Sprint F: pickupUtc ist jetzt Temporal.Instant — vergleichen via .toString().
+    expect(flat["label"]).toBe("ACME");
+    expect((flat["pickupUtc"] as Temporal.Instant).toString()).toBe("2026-04-15T09:00:00Z");
+    expect(flat["pickupTz"]).toBe("Europe/Lisbon");
+    expect(flat["buyingPrice"]).toBe(45_000);
+    expect(flat["buyingPriceCurrency"]).toBe("EUR");
+  });
+
+  test("ist pure — input wird nicht mutiert", () => {
+    const input = {
+      pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" },
+      buyingPrice: { amount: 100, currency: "EUR" },
+    };
+    const before = JSON.stringify(input);
+    flattenCompoundTypes(input, mixedEntity);
+    expect(JSON.stringify(input)).toBe(before);
+  });
+});
+
+describe("rehydrateCompoundTypes — Pipeline", () => {
+  test("identity bei Row ohne Compound-Felder", () => {
+    expect(rehydrateCompoundTypes({ label: "ACME" }, mixedEntity)).toEqual({ label: "ACME" });
+  });
+
+  test("alle Konverter rehydraten parallel", () => {
+    const out = rehydrateCompoundTypes(
+      {
+        label: "ACME",
+        pickupUtc: "2026-04-15T09:00:00Z",
+        pickupTz: "Europe/Lisbon",
+        buyingPrice: 45_000,
+        buyingPriceCurrency: "EUR",
+      },
+      mixedEntity,
+    );
+    expect(out).toEqual({
+      label: "ACME",
+      pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon", utc: "2026-04-15T09:00:00Z" },
+      buyingPrice: { amount: 45_000, currency: "EUR" },
+    });
+  });
+
+  test("Round-Trip: flatten → rehydrate ergibt identisches API-Object (utc wird im Read addiert)", () => {
+    const original = {
+      label: "ACME",
+      pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" },
+      buyingPrice: { amount: 100, currency: "EUR" },
+    };
+    const round = rehydrateCompoundTypes(flattenCompoundTypes(original, mixedEntity), mixedEntity);
+    // pickup bekommt utc dazu beim Read (war beim Insert nicht gesetzt)
+    expect((round["pickup"] as { utc: string }).utc).toBe("2026-04-15T09:00:00Z");
+    expect(round["buyingPrice"]).toEqual({ amount: 100, currency: "EUR" });
+    expect(round["label"]).toBe("ACME");
+  });
+
+  test("ist pure — input wird nicht mutiert", () => {
+    const input = {
+      pickupUtc: "2026-04-15T09:00:00Z",
+      pickupTz: "Europe/Lisbon",
+      buyingPrice: 100,
+      buyingPriceCurrency: "EUR",
+    };
+    const before = JSON.stringify(input);
+    rehydrateCompoundTypes(input, mixedEntity);
+    expect(JSON.stringify(input)).toBe(before);
+  });
+});

package/src/db/__tests__/connection-options.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import { dbConnectionOptionsFromEnv } from "../connection";
+
+// createDbConnection itself opens a real postgres.js socket, so it's
+// exercised in the DB-integration suite. The env-parsing + validation
+// logic is pure and worth pinning as a unit — misconfig at boot is the
+// whole point of parsing strictly.
+
+describe("dbConnectionOptionsFromEnv", () => {
+  test("empty env → empty options (falls back to postgres.js defaults)", () => {
+    expect(dbConnectionOptionsFromEnv({})).toEqual({});
+  });
+
+  test("reads all three supported keys", () => {
+    const opts = dbConnectionOptionsFromEnv({
+      DATABASE_POOL_MAX: "25",
+      DATABASE_POOL_IDLE_TIMEOUT: "60",
+      DATABASE_POOL_CONNECT_TIMEOUT: "5",
+    });
+    expect(opts).toEqual({
+      maxConnections: 25,
+      idleTimeoutSeconds: 60,
+      connectTimeoutSeconds: 5,
+    });
+  });
+
+  test("empty string is treated as unset", () => {
+    const opts = dbConnectionOptionsFromEnv({
+      DATABASE_POOL_MAX: "",
+      DATABASE_POOL_IDLE_TIMEOUT: "30",
+    });
+    expect(opts).toEqual({ idleTimeoutSeconds: 30 });
+  });
+
+  test("zero is allowed (idle_timeout=0 disables idle eviction in postgres.js)", () => {
+    const opts = dbConnectionOptionsFromEnv({
+      DATABASE_POOL_IDLE_TIMEOUT: "0",
+    });
+    expect(opts).toEqual({ idleTimeoutSeconds: 0 });
+  });
+
+  test("negative number → throws (misconfig catches at boot)", () => {
+    expect(() => dbConnectionOptionsFromEnv({ DATABASE_POOL_MAX: "-5" })).toThrow(
+      /DATABASE_POOL_MAX="-5".*non-negative/i,
+    );
+  });
+
+  test("non-numeric → throws", () => {
+    expect(() => dbConnectionOptionsFromEnv({ DATABASE_POOL_CONNECT_TIMEOUT: "five" })).toThrow(
+      /DATABASE_POOL_CONNECT_TIMEOUT="five"/,
+    );
+  });
+
+  test("decimal → throws (postgres.js expects integer seconds)", () => {
+    expect(() => dbConnectionOptionsFromEnv({ DATABASE_POOL_IDLE_TIMEOUT: "1.5" })).toThrow(
+      /DATABASE_POOL_IDLE_TIMEOUT="1.5".*integer/i,
+    );
+  });
+
+  test("unrelated env vars are ignored", () => {
+    const opts = dbConnectionOptionsFromEnv({
+      HOME: "/home/user",
+      PATH: "/usr/bin",
+      DATABASE_POOL_MAX: "10",
+    });
+    expect(opts).toEqual({ maxConnections: 10 });
+  });
+});

package/src/db/__tests__/cursor.test.ts

@@ -0,0 +1,41 @@
+// Cursor encoding pinst dass UUID + Integer-IDs beide den gleichen
+// Pfad nehmen — vorher hat decodeCursor mit Number.parseInt versucht
+// einen UUID zu number zu casten und zurück NaN gegeben, der DB-WHERE-
+// Clause hat dann auf "id > NaN" gequeryt → Postgres-Crash. UUIDs
+// sind aktuell der Default (Sprint F idType=uuid), also war cursor-
+// Pagination strukturell broken vor diesem Fix.
+
+import { describe, expect, test } from "vitest";
+import { decodeCursor, encodeCursor } from "../cursor";
+
+describe("encodeCursor + decodeCursor", () => {
+  test("UUIDv7-Roundtrip: encoded → decoded gibt denselben UUID-String", () => {
+    const uuid = "019dcd94-d6b9-742c-9a3c-43d7972f6243";
+    expect(decodeCursor(encodeCursor(uuid))).toBe(uuid);
+  });
+
+  test("Integer-Roundtrip: encoded → decoded gibt String-Form (kompatibel)", () => {
+    // String/number als Input erlaubt; output ist immer String. PG
+    // castet beim WHERE id > '42' selbst auf integer-Spalten korrekt.
+    expect(decodeCursor(encodeCursor(42))).toBe("42");
+  });
+
+  test("encoded String ist URL-safe base64 (kein /, +, =)", () => {
+    const encoded = encodeCursor("019dcd94-d6b9-742c-9a3c-43d7972f6243");
+    expect(encoded).not.toMatch(/[/+=]/);
+  });
+
+  test("Leerer Cursor (corrupted base64): wirft Invalid-cursor-Error", () => {
+    expect(() => decodeCursor("")).toThrow(/Invalid cursor/);
+  });
+
+  test("UUIDs sind lexikografisch sort-stabil (UUIDv7-Voraussetzung)", () => {
+    // Cursor-Pagination erwartet dass `gt(id, last-id)` die nächste Seite
+    // liefert. Bei UUIDv7 ist das time-ordered, also lexikografisch
+    // monoton mit Insert-Reihenfolge. Hier nur eine String-Compare-
+    // Sanity-Check — die DB-Seite glaubt das default-mäßig.
+    const a = "019dcd94-0000-742c-0000-000000000001";
+    const b = "019dcd95-0000-742c-0000-000000000002";
+    expect(b > a).toBe(true);
+  });
+});