@cosmicdrift/kumiko-framework 0.1.0

package/src/__tests__/transition-guard.integration.ts

@@ -0,0 +1,340 @@
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../db/event-store-executor";
+import { buildDrizzleTable } from "../db/table-builder";
+import {
+  createBooleanField,
+  createEntity,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "../engine";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../stack";
+import { expectErrorIncludes } from "../testing";
+
+// Two entities, both with a field named `status`, but different transitions.
+// Before the fix, the dispatcher cached the transition map by `fieldName`
+// alone — so whichever entity ran through the pipeline first would poison
+// the cache, and the other entity would be validated against the wrong map.
+
+const invoiceEntity = createEntity({
+  table: "tg_invoices",
+  fields: {
+    title: createTextField({ required: true }),
+    status: createSelectField({ options: ["draft", "sent", "paid"] as const, default: "draft" }),
+  },
+  transitions: {
+    status: {
+      draft: ["sent"],
+      sent: ["paid"],
+      paid: [],
+    },
+  },
+});
+
+const orderEntity = createEntity({
+  table: "tg_orders",
+  fields: {
+    title: createTextField({ required: true }),
+    status: createSelectField({
+      options: ["open", "shipped", "delivered"] as const,
+      default: "open",
+    }),
+  },
+  transitions: {
+    status: {
+      open: ["shipped"],
+      shipped: ["delivered"],
+      delivered: [],
+    },
+  },
+});
+
+// A soft-deletable entity to verify the auto-guard skips isDeleted rows.
+const ticketEntity = createEntity({
+  table: "tg_tickets",
+  fields: {
+    title: createTextField({ required: true }),
+    status: createSelectField({ options: ["open", "closed"] as const, default: "open" }),
+    isDeleted: createBooleanField({ default: false }),
+  },
+  softDelete: true,
+  transitions: {
+    status: {
+      open: ["closed"],
+      closed: [],
+    },
+  },
+});
+
+const invoiceTable = buildDrizzleTable("invoice", invoiceEntity);
+const orderTable = buildDrizzleTable("order", orderEntity);
+const ticketTable = buildDrizzleTable("ticket", ticketEntity);
+
+const feature = defineFeature("txguard", (r) => {
+  r.entity("invoice", invoiceEntity);
+  r.entity("order", orderEntity);
+  r.entity("ticket", ticketEntity);
+
+  r.writeHandler(
+    "invoice:create",
+    z.object({ title: z.string(), status: z.string().optional() }),
+    async (event, ctx) =>
+      createEventStoreExecutor(invoiceTable, invoiceEntity, { entityName: "invoice" }).create(
+        event.payload,
+        event.user,
+        ctx.db,
+      ),
+    { access: { openToAll: true } },
+  );
+
+  r.writeHandler(
+    "invoice:update",
+    z.object({
+      id: z.uuid(),
+      version: z.number().optional(),
+      changes: z.record(z.string(), z.unknown()),
+    }),
+    async (event, ctx) =>
+      createEventStoreExecutor(invoiceTable, invoiceEntity, { entityName: "invoice" }).update(
+        event.payload,
+        event.user,
+        ctx.db,
+      ),
+    { access: { openToAll: true } },
+  );
+
+  r.writeHandler(
+    "order:create",
+    z.object({ title: z.string(), status: z.string().optional() }),
+    async (event, ctx) =>
+      createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" }).create(
+        event.payload,
+        event.user,
+        ctx.db,
+      ),
+    { access: { openToAll: true } },
+  );
+
+  r.writeHandler(
+    "order:update",
+    z.object({
+      id: z.uuid(),
+      version: z.number().optional(),
+      changes: z.record(z.string(), z.unknown()),
+    }),
+    async (event, ctx) =>
+      createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" }).update(
+        event.payload,
+        event.user,
+        ctx.db,
+      ),
+    { access: { openToAll: true } },
+  );
+
+  r.writeHandler(
+    "ticket:create",
+    z.object({ title: z.string() }),
+    async (event, ctx) =>
+      createEventStoreExecutor(ticketTable, ticketEntity, { entityName: "ticket" }).create(
+        event.payload,
+        event.user,
+        ctx.db,
+      ),
+    { access: { openToAll: true } },
+  );
+
+  r.writeHandler(
+    "ticket:delete",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) =>
+      createEventStoreExecutor(ticketTable, ticketEntity, { entityName: "ticket" }).delete(
+        event.payload,
+        event.user,
+        ctx.db,
+      ),
+    { access: { openToAll: true } },
+  );
+
+  r.writeHandler(
+    "ticket:update",
+    z.object({
+      id: z.uuid(),
+      version: z.number().optional(),
+      changes: z.record(z.string(), z.unknown()),
+    }),
+    async (event, ctx) =>
+      createEventStoreExecutor(ticketTable, ticketEntity, { entityName: "ticket" }).update(
+        event.payload,
+        event.user,
+        ctx.db,
+      ),
+    { access: { openToAll: true } },
+  );
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  await createEntityTable(stack.db, invoiceEntity);
+  await createEntityTable(stack.db, orderEntity);
+  await createEntityTable(stack.db, ticketEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("auto transition guard: per-entity transition map (cache key includes entity)", () => {
+  test("entity A's transitions don't leak to entity B when both have `status`", async () => {
+    // Create both rows in their default states (draft / open)
+    const invoice = await stack.http.writeOk<{ id: number }>(
+      "txguard:write:invoice:create",
+      { title: "Inv-1" },
+      admin,
+    );
+    const order = await stack.http.writeOk<{ id: number }>(
+      "txguard:write:order:create",
+      { title: "Ord-1" },
+      admin,
+    );
+
+    // Invoice: draft → sent is ALLOWED by invoice transitions.
+    // If the cache collided with order's map (open→shipped), the dispatcher
+    // would reject "sent" as not a valid target from any known state.
+    const invoiceResult = await stack.http.writeOk<{ data: { status: string } }>(
+      "txguard:write:invoice:update",
+      { id: invoice["id"], changes: { status: "sent" }, version: 1 },
+      admin,
+    );
+    expect(invoiceResult.data.status).toBe("sent");
+
+    // Order: open → shipped is ALLOWED by order transitions.
+    // If the cache now holds invoice's map, this would be rejected.
+    const orderResult = await stack.http.writeOk<{ data: { status: string } }>(
+      "txguard:write:order:update",
+      { id: order["id"], changes: { status: "shipped" }, version: 1 },
+      admin,
+    );
+    expect(orderResult.data.status).toBe("shipped");
+  });
+
+  test("invalid transition on entity A still rejects (guard actually fires)", async () => {
+    const invoice = await stack.http.writeOk<{ id: number }>(
+      "txguard:write:invoice:create",
+      { title: "Inv-2" },
+      admin,
+    );
+
+    // draft → paid is NOT allowed (only draft → sent, sent → paid)
+    const err = await stack.http.writeErr(
+      "txguard:write:invoice:update",
+      { id: invoice["id"], changes: { status: "paid" }, version: 1 },
+      admin,
+    );
+    expectErrorIncludes(err, "Invalid transition");
+    expectErrorIncludes(err, "draft");
+    expectErrorIncludes(err, "paid");
+  });
+
+  test("invalid transition uses entity B's own map, not a leaked one", async () => {
+    const order = await stack.http.writeOk<{ id: number }>(
+      "txguard:write:order:create",
+      { title: "Ord-2" },
+      admin,
+    );
+
+    // open → delivered is NOT allowed (only open → shipped, shipped → delivered)
+    const err = await stack.http.writeErr(
+      "txguard:write:order:update",
+      { id: order["id"], changes: { status: "delivered" }, version: 1 },
+      admin,
+    );
+    expectErrorIncludes(err, "Invalid transition");
+    expectErrorIncludes(err, "open");
+    expectErrorIncludes(err, "delivered");
+  });
+
+  test("soft-deleted rows bypass the guard (no state-machine enforcement on zombies)", async () => {
+    const ticket = await stack.http.writeOk<{ id: string }>(
+      "txguard:write:ticket:create",
+      { title: "T-1" },
+      admin,
+    );
+
+    // Raw-DB-mark-deleted — we need a soft-deleted row whose status is a
+    // terminal state. If the guard fired, any status write would throw
+    // "Invalid transition: closed → <x>". We want it silently skipped.
+    const { eq } = await import("drizzle-orm");
+    await stack.db
+      .update(ticketTable)
+      .set({ status: "closed", isDeleted: true })
+      .where(eq(ticketTable["id"], ticket["id"]));
+
+    // Attempting to move a deleted ticket to "open" would normally violate
+    // "closed → []" (no allowed targets). With the softDelete skip, the
+    // guard steps aside and the request only fails because CrudExecutor
+    // filters deleted rows from updates — giving a `not_found`, not a
+    // transition error. That distinction proves the guard skipped.
+    const err = await stack.http.writeErr(
+      "txguard:write:ticket:update",
+      { id: ticket["id"], changes: { status: "open" }, version: 1 },
+      admin,
+    );
+    // Guard was skipped → we don't see "Invalid transition", we see a different
+    // failure (soft-deleted row is filtered out of the lookup, so "not_found").
+    expect(JSON.stringify(err)).not.toContain("Invalid transition");
+    expectErrorIncludes(err, "not_found");
+  });
+
+  test("concurrent writes on the same row serialize via SELECT FOR UPDATE", async () => {
+    // Two parallel requests both trying to move the SAME invoice from draft.
+    // One legal: draft → sent. One deliberately stale (would also be legal
+    // draft → sent, but since we hold the row lock, the second caller sees
+    // the updated state `sent` when its turn comes and must fail — either
+    // via the transition guard (sent → sent is not defined) or version
+    // conflict. Without the FOR UPDATE both could snapshot `draft` under
+    // READ COMMITTED and race past the guard; the second UPDATE would then
+    // fail only via the optimistic lock, losing the specific error signal.
+    const invoice = await stack.http.writeOk<{ id: number }>(
+      "txguard:write:invoice:create",
+      { title: "Concurrent-1" },
+      admin,
+    );
+
+    const [res1, res2] = await Promise.all([
+      stack.http.write(
+        "txguard:write:invoice:update",
+        { id: invoice["id"], changes: { status: "sent" }, version: 1 },
+        admin,
+      ),
+      stack.http.write(
+        "txguard:write:invoice:update",
+        { id: invoice["id"], changes: { status: "sent" }, version: 1 },
+        admin,
+      ),
+    ]);
+
+    const body1 = (await res1.json()) as { isSuccess: boolean; error?: unknown };
+    const body2 = (await res2.json()) as { isSuccess: boolean; error?: unknown };
+
+    // Exactly one of the two must win. If both succeeded, the row lock
+    // didn't serialize — both wrote draft→sent using a stale snapshot.
+    const successes = [body1, body2].filter((b) => b.isSuccess);
+    const failures = [body1, body2].filter((b) => !b.isSuccess);
+    expect(successes).toHaveLength(1);
+    expect(failures).toHaveLength(1);
+
+    // The loser saw state `sent` on its (now serialized) guard read and
+    // rejected the transition — NOT a version_conflict, which would be the
+    // optimistic-lock fallback if the guard had race-passed.
+    // The loser's UnprocessableError carries reason "invalid_transition" plus
+    // the from/to states for debugging.
+    const loser = failures[0]?.error as { code: string; details: { reason: string; from: string } };
+    expect(loser.code).toBe("unprocessable");
+    expect(loser.details.reason).toBe("invalid_transition");
+    expect(loser.details.from).toBe("sent");
+  });
+});

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

@@ -0,0 +1,337 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import {
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineFeature,
+  type TenantId,
+} from "../../engine";
+import { createTestUser, TestUsers } from "../../stack";
+import { buildServer } from "../server";
+
+const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
+
+const testFeature = defineFeature("test", (r) => {
+  r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+
+  r.writeHandler(
+    "item:create",
+    z.object({ name: z.string().min(1) }),
+    async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.queryHandler(
+    "item:list",
+    z.object({ search: z.string().optional() }),
+    async () => [{ id: 1, name: "Test" }],
+    { access: { openToAll: true } },
+  );
+});
+
+const registry = createRegistry([testFeature]);
+const { app, jwt } = buildServer({ registry, context: {}, jwtSecret: JWT_SECRET });
+
+const adminUser = TestUsers.admin;
+const guestUser = createTestUser({ id: 2, roles: ["Guest"] });
+
+async function authHeader(user: {
+  id: string;
+  tenantId: TenantId;
+  roles: readonly string[];
+}): Promise<Record<string, string>> {
+  const token = await jwt.sign(user);
+  return { Authorization: `Bearer ${token}` };
+}
+
+function req(method: string, path: string, body?: unknown, headers?: Record<string, string>) {
+  const init: RequestInit = {
+    method,
+    headers: { "Content-Type": "application/json", ...headers },
+  };
+  if (body) init.body = JSON.stringify(body);
+  return app.request(path, init);
+}
+
+// --- Health ---
+
+describe("health", () => {
+  test("GET /health returns ok", async () => {
+    const res = await req("GET", "/health");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: "ok" });
+  });
+});
+
+// --- Auth ---
+
+describe("auth middleware", () => {
+  test("rejects request without token", async () => {
+    const res = await req("POST", "/api/write", {
+      type: "test:write:item:create",
+      payload: { name: "x" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("rejects invalid token", async () => {
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: { name: "x" } },
+      {
+        Authorization: "Bearer invalid.token.here",
+      },
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("accepts valid token", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: { name: "Test" } },
+      headers,
+    );
+    expect(res.status).toBe(200);
+  });
+});
+
+// --- Write ---
+
+describe("POST /api/write", () => {
+  test("dispatches write and returns result", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: { name: "Hello" } },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+    expect(body.data.name).toBe("Hello");
+  });
+
+  test("returns 400 for validation error", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: { name: "" } },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toMatchObject({ code: "validation_error", i18nKey: expect.any(String) });
+  });
+
+  test("returns 403 for access denied", async () => {
+    const headers = await authHeader(guestUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: { name: "Test" } },
+      headers,
+    );
+
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toMatchObject({ code: "access_denied" });
+  });
+});
+
+// --- Query ---
+
+describe("POST /api/query", () => {
+  test("dispatches query and returns data", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/query",
+      { type: "test:query:item:list", payload: {} },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.data).toEqual([{ id: 1, name: "Test" }]);
+  });
+
+  test("returns 404 for unknown query", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req("POST", "/api/query", { type: "nope", payload: {} }, headers);
+    expect(res.status).toBe(404);
+  });
+});
+
+// --- Command ---
+
+describe("POST /api/command", () => {
+  test("dispatches command and returns 202", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/command",
+      { type: "test:write:item:create", payload: { name: "Fire" } },
+      headers,
+    );
+
+    expect(res.status).toBe(202);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+  });
+
+  test("returns 403 for access denied", async () => {
+    const headers = await authHeader(guestUser);
+    const res = await req(
+      "POST",
+      "/api/command",
+      { type: "test:write:item:create", payload: { name: "x" } },
+      headers,
+    );
+    expect(res.status).toBe(403);
+  });
+});
+
+// --- SSE ---
+
+describe("GET /api/sse", () => {
+  test("rejects without auth", async () => {
+    const res = await app.request("/api/sse");
+    expect(res.status).toBe(401);
+  });
+
+  test("returns event stream with auth", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await app.request("/api/sse", { headers });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+  });
+});
+
+// --- r.httpRoute (feature-deklarierte HTTP-Routes außerhalb /api/) ---
+
+describe("feature-declared HTTP routes (r.httpRoute)", () => {
+  // Eigenes buildServer-Setup mit einem Feature das eine Route deklariert.
+  // Pinst die Verdrahtung end-to-end: r.httpRoute → registry → buildServer
+  // → Hono-app.{get,post}(path) → Response. deps.app erlaubt internal-call
+  // an /api/* (gleicher Auth-Pfad wie ein echter HTTP-Call).
+  const routeFeature = defineFeature("routes", (r) => {
+    r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+    r.queryHandler("item:list", z.object({}), async () => [{ id: 7 }], {
+      access: { openToAll: true },
+    });
+    r.httpRoute({
+      method: "GET",
+      path: "/version",
+      anonymous: true,
+      handler: (c) => c.json({ version: "1.2.3" }),
+    });
+    r.httpRoute({
+      method: "GET",
+      path: "/probe-deps",
+      anonymous: true,
+      handler: (c, deps) => {
+        // Beweist dass deps.app die Hono-App-Instanz ist — Handler kann
+        // sie für internal app.fetch(...)-Calls nutzen (typischer
+        // Use-Case: feed.xml ruft /api/query intern auf).
+        return c.json({
+          hasApp: typeof deps.app === "object" && typeof deps.app.fetch === "function",
+        });
+      },
+    });
+  });
+  const routeRegistry = createRegistry([routeFeature]);
+  const { app: routeApp } = buildServer({
+    registry: routeRegistry,
+    context: {},
+    jwtSecret: JWT_SECRET,
+  });
+
+  test("GET /version returnt deklarierten JSON-Response", async () => {
+    const res = await routeApp.request("/version");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ version: "1.2.3" });
+  });
+
+  test("Handler bekommt deps.app — Hono-Instance für internal-fetch", async () => {
+    const res = await routeApp.request("/probe-deps");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { hasApp: boolean };
+    expect(body.hasApp).toBe(true);
+  });
+
+  test("Handler kann via deps.app intern /api/query aufrufen (anonymous + defaultTenantId)", async () => {
+    // Realistischer Use-Case (publicstatus feed.xml): die r.httpRoute
+    // baut eine View aus internen /api/query-Daten. Anonymous-Access mit
+    // defaultTenantId macht den inner-Call ohne Bearer-Token möglich;
+    // pinst dass deps.app.fetch identisch zu einem echten HTTP-Call läuft.
+    const inner = defineFeature("inner", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      // Bewusst "anonymous" — openToAll schließt anonymous-User explizit
+      // aus (siehe access.ts), damit das Aktivieren von anonymousAccess
+      // nicht versehentlich jeden openToAll-Handler public macht.
+      r.queryHandler("item:list", z.object({}), async () => [{ id: 42, name: "hello" }], {
+        access: { roles: ["anonymous"] },
+      });
+      r.httpRoute({
+        method: "GET",
+        path: "/feed",
+        anonymous: true,
+        handler: async (c, deps) => {
+          const queryRes = await deps.app.fetch(
+            new Request(`${new URL(c.req.url).origin}/api/query`, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ type: "inner:query:item:list", payload: {} }),
+            }),
+          );
+          const body = (await queryRes.json()) as { data?: unknown };
+          return c.json({ status: queryRes.status, items: body.data });
+        },
+      });
+    });
+    const innerRegistry = createRegistry([inner]);
+    const { app: innerApp } = buildServer({
+      registry: innerRegistry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      anonymousAccess: {
+        defaultTenantId: "00000000-0000-4000-8000-000000000000" as TenantId,
+      },
+    });
+
+    const res = await innerApp.request("/feed");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: number; items: unknown };
+    expect(body.status).toBe(200);
+    expect(body.items).toEqual([{ id: 42, name: "hello" }]);
+  });
+
+  test("Boot-Validator: Route auf /api/* ist verboten", () => {
+    expect(() =>
+      defineFeature("bad", (r) => {
+        r.httpRoute({
+          method: "GET",
+          path: "/api/forbidden",
+          handler: (c) => c.text("nope"),
+        });
+      }),
+    ).toThrow(/\/api\/\* namespace.*reserved/);
+  });
+
+  test("Boot-Validator: doppelte method+path-Combo wird abgelehnt", () => {
+    expect(() =>
+      defineFeature("dup", (r) => {
+        r.httpRoute({ method: "GET", path: "/x", handler: (c) => c.text("a") });
+        r.httpRoute({ method: "GET", path: "/x", handler: (c) => c.text("b") });
+      }),
+    ).toThrow(/already registered/);
+  });
+});