@cosmicdrift/kumiko-framework 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# @cosmicdrift/kumiko-framework
+
+[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](../../LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+
+Framework core for Kumiko — engine, pipeline, API, DB, event-store, and
+every other bit that makes Kumiko go.
+
+> Multi-tenant, command-based, event-sourced app framework for Bun + Hono +
+> Drizzle. Define features, register entities, write commands — the framework
+> wires dispatch, persistence, projections, async subscribers, and realtime
+> delivery.
+
+See the [monorepo root README](../../README.md) for the broader pitch, the
+[docs/plans](../../docs/plans) directory for architecture, and [samples/](../../samples)
+for runnable examples of every feature.
+
+## Install
+
+```bash
+yarn add @cosmicdrift/kumiko-framework
+# peers you probably already have:
+yarn add drizzle-orm hono ioredis zod
+```
+
+Bun is the intended runtime. Node 20+ works for the CLI and tests.
+
+## At-a-glance
+
+```typescript
+import { defineFeature, createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+export const taskEntity = createEntity({
+  fields: {
+    title: createTextField({ required: true, searchable: true }),
+    done: createTextField(),
+  },
+  softDelete: true,
+});
+
+const taskTable = buildDrizzleTable("task", taskEntity);
+const taskExecutor = createEventStoreExecutor(taskTable, taskEntity, { entityName: "task" });
+
+export const taskFeature = defineFeature("tasks", (r) => {
+  r.entity("task", taskEntity);
+
+  // Write handlers go through createEventStoreExecutor — events + projection in one TX,
+  // optimistic locking, access control, all explicit.
+  r.writeHandler(
+    "task:create",
+    z.object({ title: z.string() }),
+    async (event, ctx) => taskExecutor.create(event.payload, event.user, ctx.db),
+    { access: { roles: ["User"] } },
+  );
+  r.writeHandler(
+    "task:update",
+    z.object({ id: z.uuid(), version: z.number(), changes: z.object({ title: z.string().optional() }) }),
+    async (event, ctx) => taskExecutor.update(event.payload, event.user, ctx.db),
+    { access: { roles: ["User"] } },
+  );
+  r.writeHandler(
+    "task:delete",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => taskExecutor.delete(event.payload, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+  r.queryHandler(
+    "task:list",
+    z.object({}),
+    async (query, ctx) => taskExecutor.list(query.payload, query.user, ctx.db),
+    { access: { openToAll: true } },
+  );
+  r.queryHandler(
+    "task:detail",
+    z.object({ id: z.uuid() }),
+    async (query, ctx) => taskExecutor.detail(query.payload, query.user, ctx.db),
+    { access: { openToAll: true } },
+  );
+
+  // Read-model fed from task events, rebuildable via the CLI
+  r.projection({
+    name: "tasks-per-day",
+    source: "task",
+    table: tasksPerDayTable,
+    apply: {
+      "task.created": async (event, tx) => {
+        /* count++ */
+      },
+    },
+  });
+
+  // Async consumer — runs after commit via the event-dispatcher,
+  // cursor-based, at-least-once, per-consumer dead-letter semantics.
+  // Omit `table` for pure side-effect handlers (mail, webhooks, ...).
+  r.multiStreamProjection({
+    name: "notify-new-task",
+    apply: {
+      "task.created": async (event) => {
+        // e.g. push to an external notification service
+      },
+    },
+  });
+});
+```
+
+## Package exports
+
+| Entry | What's in it |
+|---|---|
+| `@cosmicdrift/kumiko-framework/engine` | `defineFeature`, `createEntity`, field helpers, access rules, registry |
+| `@cosmicdrift/kumiko-framework/db` | Drizzle re-exports, `createEventStoreExecutor`, table builders, tenant-db |
+| `@cosmicdrift/kumiko-framework/event-store` | `events` table, `append`, `loadAggregate`, `loadAggregateAsOf` |
+| `@cosmicdrift/kumiko-framework/pipeline` | Dispatcher, event-dispatcher (AsyncDaemon), projection-rebuild, SSE + search consumers |
+| `@cosmicdrift/kumiko-framework/api` | `buildServer`, auth middleware, SSE route, error contract |
+| `@cosmicdrift/kumiko-framework/auth` | JWT helper, password hashing, session users |
+| `@cosmicdrift/kumiko-framework/search` | `SearchAdapter` interface, in-memory adapter, Meili wrapper |
+| `@cosmicdrift/kumiko-framework/jobs` | BullMQ-backed job runner, cron scheduling |
+| `@cosmicdrift/kumiko-framework/files` | Signed-URL upload/download, tenant-scoped storage |
+| `@cosmicdrift/kumiko-framework/i18n` | i18next setup, per-feature translation registration |
+| `@cosmicdrift/kumiko-framework/ui` | React hooks (Zustand stores, SSE subscription, optimistic mutations) |
+| `@cosmicdrift/kumiko-framework/testing` | `setupTestStack`, `createTestDb`, request helpers |
+| `@cosmicdrift/kumiko-framework/utils` | Safe JSON, qualified-name helpers |
+| `@cosmicdrift/kumiko-framework/errors` | Error classes, `writeFailure`, reason contracts |
+
+## Core concepts
+
+- **Feature as unit of deployment.** `defineFeature` registers entities,
+  write/query handlers, projections, post-event subscribers, lifecycle hooks,
+  access rules, and translations.
+- **Commands in, state out.** Writes are commands dispatched through HTTP;
+  the dispatcher validates, enforces access, runs lifecycle hooks, persists
+  events, and triggers projections in a single TX.
+- **Event-sourced by default.** Every write goes through `createEventStoreExecutor`
+  and appends a domain event to the aggregate stream. Auto-generated CRUD
+  events (`<entity>.created/updated/deleted/restored`) for record writes,
+  explicit `ctx.appendEvent` for domain events with intent. Projections feed
+  off the stream for same-TX read-after-write consistency.
+- **Async side-effects via cursor.** SSE broadcast, search indexing, and
+  feature-registered `r.multiStreamProjection` consumers run on a single
+  cursor-based dispatcher (AsyncDaemon pattern). Per-consumer checkpoints,
+  halt-on-poison, dead-letter after N retries.
+- **Multi-tenant scoping.** Every event, entity, projection, and search
+  index carries `tenantId`. `TenantDb` is a TX-scoped wrapper that refuses
+  writes outside the current tenant.
+- **Optimistic concurrency.** `UNIQUE(aggregate_id, version)` on events
+  gives atomic append + conflict detection; `VersionConflictError` surfaces
+  races as a first-class value.
+- **Idempotency + dedup.** Request-id backed unique index on the events
+  table turns retries into replays. `IdempotencyGuard` caches write
+  outcomes per tenant.
+
+## Status
+
+This framework is pre-1.0 and evolves fast. Every feature has a runnable
+sample under `samples/`; the roadmap lives in [docs/plans/uebersicht.md](../../docs/plans/uebersicht.md).
+
+## License
+
+BUSL-1.1 — see [LICENSE](../../LICENSE).

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@cosmicdrift/kumiko-framework",
+  "version": "0.1.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>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "directory": "packages/framework"
+  },
+  "bugs": {
+    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.so",
+  "keywords": [
+    "framework",
+    "multi-tenant",
+    "realtime",
+    "command-based",
+    "typescript",
+    "hono",
+    "drizzle",
+    "zod"
+  ],
+  "type": "module",
+  "kumiko": {
+    "runtime": "runtime"
+  },
+  "exports": {
+    "./engine": "./src/engine/index.ts",
+    "./engine/types": "./src/engine/types/index.ts",
+    "./errors": "./src/errors/index.ts",
+    "./db": "./src/db/index.ts",
+    "./event-store": "./src/event-store/index.ts",
+    "./event-store/admin-api": "./src/event-store/admin-api.ts",
+    "./pipeline": "./src/pipeline/index.ts",
+    "./api": "./src/api/index.ts",
+    "./i18n": "./src/i18n/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./files": "./src/files/index.ts",
+    "./jobs": "./src/jobs/index.ts",
+    "./migrations": "./src/migrations/index.ts",
+    "./entrypoint": "./src/entrypoint/index.ts",
+    "./random": "./src/random/index.ts",
+    "./redis": "./src/redis/index.ts",
+    "./search": "./src/search/index.ts",
+    "./search/meilisearch": "./src/search/meilisearch-adapter.ts",
+    "./secrets": "./src/secrets/index.ts",
+    "./stack": "./src/stack/index.ts",
+    "./testing": "./src/testing/index.ts",
+    "./testing/handler-context": "./src/testing/handler-context.ts",
+    "./testing/e2e-generator": "./src/testing/e2e-generator.ts",
+    "./time": "./src/time/index.ts",
+    "./ui-types": "./src/ui-types/index.ts",
+    "./utils": "./src/utils/index.ts"
+  },
+  "dependencies": {
+    "bullmq": "^5.73.5",
+    "bun-types": "^1.3.12",
+    "drizzle-kit": "^0.31.10",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.12.12",
+    "i18next": "^26.0.4",
+    "ioredis": "^5.6.0",
+    "jose": "^6.0.11",
+    "meilisearch": "^0.57.0",
+    "pino": "^10.3.1",
+    "postgres": "^3.4.9",
+    "temporal-polyfill": "^0.3.2",
+    "ts-morph": "^28.0.0",
+    "uuid": "^14.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-dispatcher-live": "workspace:*",
+    "@types/uuid": "^11.0.0",
+    "bun-types": "^1.2.9",
+    "drizzle-kit": "^0.31.0",
+    "pino-pretty": "^13.1.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/anonymous-access.integration.ts

@@ -0,0 +1,325 @@
+// Full-stack proof for anonymousAccess: handlers that allow roles=["anonymous"]
+// must be reachable WITHOUT a JWT, while the rest of /api/* still requires
+// authentication. Covers the resolution chain (defaultTenantId, X-Tenant
+// header, kumiko_tenant cookie, custom resolver) plus the rejection paths
+// (no tenant, unknown tenant, openToAll-protected).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../db/event-store-executor";
+import { buildDrizzleTable } from "../db/table-builder";
+import {
+  ANONYMOUS_USER_ID,
+  createEntity,
+  createTextField,
+  defineFeature,
+  type TenantId,
+} from "../engine";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../stack";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+const OTHER_TENANT_ID = "00000000-0000-4000-8000-000000000002" as TenantId;
+
+// --- Feature ---
+
+const productEntity = createEntity({
+  table: "anon_products",
+  fields: {
+    name: createTextField({ required: true }),
+  },
+});
+const productTable = buildDrizzleTable("product", productEntity);
+
+const orderEntity = createEntity({
+  table: "anon_orders",
+  fields: {
+    productName: createTextField({ required: true }),
+    placedBy: createTextField({ default: "" }),
+  },
+});
+const orderTable = buildDrizzleTable("order", orderEntity);
+
+const shopFeature = defineFeature("anonshop", (r) => {
+  r.entity("product", productEntity);
+  r.entity("order", orderEntity);
+
+  // Public listing — anonymous + authenticated customers see it.
+  r.queryHandler(
+    "product:list",
+    z.object({}),
+    async (_event, ctx) => {
+      const rows = await ctx.db.select().from(productTable);
+      return rows;
+    },
+    { access: { roles: ["anonymous", "User", "Admin"] } },
+  );
+
+  // Authenticated-only listing — confirms openToAll still rejects anonymous.
+  r.queryHandler(
+    "product:list-auth-only",
+    z.object({}),
+    async (_event, ctx) => {
+      const rows = await ctx.db.select().from(productTable);
+      return rows;
+    },
+    { access: { openToAll: true } },
+  );
+
+  // Anonymous can place a guest order.
+  r.writeHandler(
+    "order:guest-checkout",
+    z.object({ productName: z.string().min(1) }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
+      return crud.create(
+        { productName: event.payload.productName, placedBy: event.user.id },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: ["anonymous", "User"] } },
+  );
+
+  // Admin-only — confirms role-gated handlers still reject anonymous.
+  r.writeHandler(
+    "product:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(productTable, productEntity, {
+        entityName: "product",
+      });
+      return crud.create({ name: event.payload.name }, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+// --- Suite ---
+
+describe("anonymous access — single-tenant default", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: { defaultTenantId: TENANT_ID },
+    });
+    await createEntityTable(stack.db, productEntity);
+    await createEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  beforeEach(async () => {
+    await stack.db.delete(productTable);
+    await stack.db.delete(orderTable);
+  });
+
+  test("anonymous query succeeds without any auth headers", async () => {
+    // Seed a product with the admin user so the query has data to return.
+    await stack.http.writeOk(
+      "anonshop:write:product:create",
+      { name: "Espresso Beans" },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: Array<{ name: string }> };
+    expect(body.data).toHaveLength(1);
+    expect(body.data[0]?.name).toBe("Espresso Beans");
+  });
+
+  test("anonymous write succeeds and records actor=anonymous", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "anonshop:write:order:guest-checkout",
+      payload: { productName: "Espresso Beans" },
+    });
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(true);
+
+    // Verify the row landed with placedBy=anonymous in the DB. Confirms the
+    // synthesised SessionUser actually flows through to the handler.
+    const rows = await stack.db.select().from(orderTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["placedBy"]).toBe(ANONYMOUS_USER_ID);
+  });
+
+  test("openToAll handler rejects anonymous (regression guard)", async () => {
+    // The advisor-flagged regression: enabling anonymousAccess must NOT
+    // silently expose every existing openToAll endpoint. hasAccess refuses
+    // anonymous on openToAll, so the dispatcher returns AccessDenied.
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list-auth-only",
+      payload: {},
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("access_denied");
+  });
+
+  test("role-gated handler still rejects anonymous", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "anonshop:write:product:create",
+      payload: { name: "Tea Set" },
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("authenticated user with JWT bypasses anonymous path entirely", async () => {
+    const res = await stack.http.query("anonshop:query:product:list", {}, TestUsers.admin);
+    expect(res.status).toBe(200);
+  });
+
+  test("X-Tenant header that disagrees with default → 400 tenant_mismatch", async () => {
+    // Single-tenant mode is locked: a client cannot override defaultTenantId
+    // by sending a different X-Tenant. Silent acceptance would let a
+    // confused client write into the wrong tenant of a single-tenant
+    // deployment that happened to have data for OTHER_TENANT_ID.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": OTHER_TENANT_ID },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_mismatch");
+  });
+
+  test("X-Tenant header matching default → accepted", async () => {
+    // Same default, redundant header — fine.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": TENANT_ID },
+    );
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("anonymous access — header-supplied tenant", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [shopFeature],
+      anonymousAccess: {
+        // No defaultTenantId — every anonymous request must declare its tenant.
+        tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+    await createEntityTable(stack.db, productEntity);
+    await createEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("X-Tenant header resolves the tenant", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": TENANT_ID },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("malformed X-Tenant header → 400 invalid_tenant_format", async () => {
+    // Junk strings (SQL fragments, path traversals, plain typos) must never
+    // reach the pipeline as a TenantId. parseTenantId rejects anything that
+    // isn't a UUID-shape, the middleware turns that into a 400 here.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": "not-a-uuid" },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as {
+      error: { code: string; details: { source: string } };
+    };
+    expect(body.error.code).toBe("invalid_tenant_format");
+    expect(body.error.details.source).toBe("X-Tenant header");
+  });
+
+  test("missing tenant → 400 tenant_required", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string; i18nKey: string } };
+    expect(body.error.code).toBe("tenant_required");
+    expect(body.error.i18nKey).toBe("auth.errors.tenantRequired");
+  });
+
+  test("/api/auth/* without JWT → 401 missing_token (not 400 tenant_required)", async () => {
+    // Auth-routes (tenants, switch-tenant, logout) brauchen einen JWT,
+    // aber keinen Tenant-Resolve. Vor dem Fix fielen sie in handleAnonymous,
+    // das beim resolveTenant ohne X-Tenant 400 tenant_required wirft —
+    // falsche Diagnose, der Caller ist unauthenticated, nicht ohne Tenant.
+    // Login bleibt davon unberührt (in PUBLIC_API_PATHS, skipped vor auth).
+    const res = await stack.http.raw("GET", "/api/auth/tenants");
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string; i18nKey: string } };
+    expect(body.error.code).toBe("missing_token");
+    expect(body.error.i18nKey).toBe("auth.errors.missingToken");
+  });
+
+  test("authenticated request with conflicting X-Tenant header → 400 tenant_mismatch", async () => {
+    // JWT carries tenantId=TENANT_ID, but the client sends X-Tenant for a
+    // different tenant. Silent ignore would let the client think it's
+    // hitting OTHER_TENANT_ID while it's actually on TENANT_ID — defensive
+    // reject, same shape as ambiguous_auth.
+    const token = await stack.jwt.sign(TestUsers.admin);
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { Authorization: `Bearer ${token}`, "X-Tenant": OTHER_TENANT_ID },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_mismatch");
+  });
+
+  test("unknown tenant → 404 tenant_not_found", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { "X-Tenant": "00000000-0000-4000-8000-deadbeefdead" },
+    );
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_not_found");
+  });
+});
+
+describe("anonymous access — disabled by default", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [shopFeature] });
+    await createEntityTable(stack.db, productEntity);
+    await createEntityTable(stack.db, orderEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("missing JWT → 401 (no anonymous fall-through)", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "anonshop:query:product:list",
+      payload: {},
+    });
+    expect(res.status).toBe(401);
+  });
+});