@cosmicdrift/kumiko-framework 0.1.0

package/src/api/__tests__/nested-write.integration.ts

@@ -0,0 +1,213 @@
+import { eq } from "drizzle-orm";
+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 { createEntity, createTextField, defineFeature } from "../../engine";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+// Two entities in a 1:N relation. The relation is declared with
+// `nestedWrite: true`, which opts the framework into expanding
+// `{ tasks: [...] }` inside a project:create payload into a child-write
+// per entry — all in the same TX as the parent.
+const projectEntity = createEntity({
+  table: "nested_projects",
+  fields: { name: createTextField({ required: true }) },
+});
+const projectTable = buildDrizzleTable("project", projectEntity);
+
+const taskEntity = createEntity({
+  table: "nested_tasks",
+  fields: {
+    projectId: createTextField({ required: true }),
+    title: createTextField({ required: true }),
+  },
+});
+const taskTable = buildDrizzleTable("task", taskEntity);
+
+const nestedFeature = defineFeature("nested", (r) => {
+  r.entity("project", projectEntity);
+  r.entity("task", taskEntity);
+
+  r.relation("project", "tasks", {
+    type: "hasMany",
+    target: "task",
+    foreignKey: "projectId",
+    nestedWrite: true,
+  });
+
+  r.writeHandler(
+    "project:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(projectTable, projectEntity, {
+        entityName: "project",
+      });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "task:create",
+    z.object({
+      projectId: z.string().uuid(),
+      title: z.string().min(1),
+    }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(taskTable, taskEntity, {
+        entityName: "task",
+      });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [nestedFeature] });
+  await createEntityTable(stack.db, projectEntity);
+  await createEntityTable(stack.db, taskEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.db.delete(taskTable);
+  await stack.db.delete(projectTable);
+});
+
+describe("POST /api/write — nested-write (Welle M1)", () => {
+  test("project:create with nested tasks: parent + children atomic, response carries both", async () => {
+    const res = await stack.http.write(
+      "nested:write:project:create",
+      {
+        name: "P1",
+        tasks: [{ title: "t1" }, { title: "t2" }],
+      },
+      admin,
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+
+    // Handlers built on the CRUD executor wrap the row in a SaveContext
+    // (`{ kind: "save", data: <row>, ... }`). Nested children land on the
+    // inner `data` object, mirroring the nested shape the client sent up.
+    const parent = body.data.data;
+    expect(parent.id).toBeDefined();
+    expect(parent.name).toBe("P1");
+    expect(Array.isArray(parent.tasks)).toBe(true);
+    expect(parent.tasks).toHaveLength(2);
+    expect(parent.tasks[0].projectId).toBe(parent.id);
+    expect(parent.tasks[0].title).toBe("t1");
+    expect(parent.tasks[1].projectId).toBe(parent.id);
+    expect(parent.tasks[1].title).toBe("t2");
+
+    // DB reflects both writes.
+    const dbProjects = await stack.db.select().from(projectTable);
+    const dbTasks = await stack.db
+      .select()
+      .from(taskTable)
+      .where(eq(taskTable["projectId"], parent.id));
+    expect(dbProjects).toHaveLength(1);
+    expect(dbTasks).toHaveLength(2);
+  });
+
+  test("sub-write failure rolls back parent: neither project nor sibling tasks persist", async () => {
+    // Second task fails zod validation (empty title). The whole batch —
+    // parent + any prior sub — must roll back.
+    const res = await stack.http.write(
+      "nested:write:project:create",
+      {
+        name: "P2",
+        tasks: [{ title: "ok" }, { title: "" }],
+      },
+      admin,
+    );
+
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+
+    // DB empty — prior sub-task and parent both rolled back.
+    const dbProjects = await stack.db.select().from(projectTable);
+    const dbTasks = await stack.db.select().from(taskTable);
+    expect(dbProjects).toHaveLength(0);
+    expect(dbTasks).toHaveLength(0);
+  });
+
+  test("sub-write validation error paths are prefixed with `<relKey>.<index>`", async () => {
+    // A zod failure on a nested item (empty title) must surface with a
+    // client-mappable path. The form-controller (Block 2) keys error
+    // messages off this path to highlight the right sub-line's field.
+    const res = await stack.http.write(
+      "nested:write:project:create",
+      {
+        name: "P4",
+        tasks: [{ title: "ok" }, { title: "" }],
+      },
+      admin,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe("validation_error");
+    const paths = (body.error.details.fields as Array<{ path: string }>).map((f) => f.path);
+    // At least one field issue points at tasks.1.title (index-1, empty title).
+    expect(paths.some((p) => p === "tasks.1.title")).toBe(true);
+  });
+
+  test("non-array value under a nested-write key is rejected (invalid_type)", async () => {
+    // Zod's default semantics would silently strip a malformed `tasks` value
+    // (e.g. a string or null) — the client would then see a 200 with no
+    // indication their data was dropped. Fail loud instead.
+    const res = await stack.http.write(
+      "nested:write:project:create",
+      { name: "P-shape", tasks: "not-an-array" },
+      admin,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe("validation_error");
+    expect(body.error.details.fields[0].path).toBe("tasks");
+    expect(body.error.details.fields[0].code).toBe("invalid_type");
+
+    // Parent did not persist — the pre-flight check runs before the parent
+    // write, so the TX never opened on a malformed nested key.
+    const dbProjects = await stack.db.select().from(projectTable);
+    expect(dbProjects).toHaveLength(0);
+  });
+
+  test("explicit foreign key in sub-payload is rejected", async () => {
+    // Security rail: a client trying to hang a nested task onto a different
+    // project id by smuggling `projectId` into the sub-payload must be
+    // refused up-front, not silently overwritten. The framework sets the
+    // fk itself from the parent's new id.
+    const res = await stack.http.write(
+      "nested:write:project:create",
+      {
+        name: "P3",
+        tasks: [{ title: "x", projectId: "00000000-0000-0000-0000-000000000001" }],
+      },
+      admin,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.code).toBe("validation_error");
+    expect(body.error.details.fields[0].path).toMatch(/tasks\.0\.projectId/);
+
+    // DB empty.
+    const dbProjects = await stack.db.select().from(projectTable);
+    expect(dbProjects).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "vitest";
+import { createReadinessProbe, type ReadinessCheck } from "../readiness";
+
+function okCheck(name: string, delayMs = 0): ReadinessCheck {
+  return {
+    name,
+    run: async () => {
+      if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+    },
+  };
+}
+
+function failCheck(name: string, message: string): ReadinessCheck {
+  return {
+    name,
+    run: async () => {
+      throw new Error(message);
+    },
+  };
+}
+
+function hangCheck(name: string): ReadinessCheck {
+  return {
+    name,
+    run: () => new Promise(() => {}),
+  };
+}
+
+describe("createReadinessProbe", () => {
+  test("all checks pass → ok=true", async () => {
+    const probe = createReadinessProbe([okCheck("a"), okCheck("b")]);
+    const result = await probe();
+    expect(result.ok).toBe(true);
+    expect(result.checks).toHaveLength(2);
+    expect(result.checks.every((c) => c.ok)).toBe(true);
+  });
+
+  test("one failing check drags the whole probe down", async () => {
+    const probe = createReadinessProbe([okCheck("db"), failCheck("redis", "ECONNREFUSED")]);
+    const result = await probe();
+    expect(result.ok).toBe(false);
+    expect(result.checks).toHaveLength(2);
+    const redis = result.checks.find((c) => c.name === "redis");
+    expect(redis?.ok).toBe(false);
+    expect(redis?.error).toContain("ECONNREFUSED");
+  });
+
+  test("hung check is aborted at timeoutMs and surfaces as failure", async () => {
+    const probe = createReadinessProbe([hangCheck("slow"), okCheck("fast")], { timeoutMs: 50 });
+    const start = performance.now();
+    const result = await probe();
+    const elapsed = performance.now() - start;
+    expect(elapsed).toBeLessThan(500); // far below the hang's infinity
+    expect(result.ok).toBe(false);
+    const slow = result.checks.find((c) => c.name === "slow");
+    expect(slow?.ok).toBe(false);
+    expect(slow?.error).toMatch(/timeout/i);
+  });
+
+  test("checks run in parallel — total latency ≈ slowest, not sum", async () => {
+    const probe = createReadinessProbe([okCheck("a", 80), okCheck("b", 80), okCheck("c", 80)]);
+    const start = performance.now();
+    const result = await probe();
+    const elapsed = performance.now() - start;
+    expect(result.ok).toBe(true);
+    // Parallel: ~80ms total. Sequential would be ~240ms. Generous margin for CI.
+    expect(elapsed).toBeLessThan(200);
+  });
+
+  test("empty check list → ok=true, empty results", async () => {
+    const probe = createReadinessProbe([]);
+    const result = await probe();
+    expect(result.ok).toBe(true);
+    expect(result.checks).toHaveLength(0);
+  });
+});

package/src/api/__tests__/request-id-middleware.test.ts

@@ -0,0 +1,72 @@
+import { Hono } from "hono";
+import { describe, expect, test } from "vitest";
+import { requestContext } from "../request-context";
+import { requestIdMiddleware } from "../request-id-middleware";
+
+describe("requestIdMiddleware — signal propagation", () => {
+  test("AbortSignal from c.req.raw lands in requestContext.signal", async () => {
+    let captured: { signal: AbortSignal | undefined; requestId: string | undefined } = {
+      signal: undefined,
+      requestId: undefined,
+    };
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware());
+    app.get("/probe", (c) => {
+      const ctx = requestContext.get();
+      captured = { signal: ctx?.signal, requestId: ctx?.requestId };
+      return c.text("ok");
+    });
+
+    const controller = new AbortController();
+    // Hono's app.request takes a Request OR a string + RequestInit. Pass
+    // a real Request so AbortSignal flows the way it does in production.
+    const res = await app.request(
+      new Request("http://test.local/probe", {
+        method: "GET",
+        signal: controller.signal,
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(captured.requestId).toBeDefined();
+    expect(captured.signal).toBeInstanceOf(AbortSignal);
+    expect(captured.signal?.aborted).toBe(false);
+  });
+
+  test("abort during handler execution flips ctx.signal.aborted to true", async () => {
+    // Handler holds the request open via a small delay. We fire abort()
+    // in the middle of that delay so the handler is guaranteed to be
+    // running when the signal flips — proves real propagation, not just
+    // "the field exists".
+    let captured: AbortSignal | undefined;
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware());
+    app.get("/probe", async (c) => {
+      captured = requestContext.get()?.signal;
+      await new Promise((resolve) => setTimeout(resolve, 60));
+      return c.text("ok");
+    });
+
+    const controller = new AbortController();
+    const fetchPromise = app.request(
+      new Request("http://test.local/probe", {
+        method: "GET",
+        signal: controller.signal,
+      }),
+    );
+    // Fire abort while the handler is awaiting the timeout.
+    setTimeout(() => controller.abort(), 20);
+
+    try {
+      await fetchPromise;
+    } catch {
+      // node may surface the abort as a thrown AbortError on the outer
+      // promise; we only care about the handler's view via captured.
+    }
+
+    expect(captured).toBeDefined();
+    expect(captured?.aborted).toBe(true);
+  });
+});

package/src/api/__tests__/sse-broker.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test, vi } from "vitest";
+import { createSseBroker, type SseEvent } from "../sse-broker";
+
+describe("SSE broker", () => {
+  test("adds client and tracks count", () => {
+    const broker = createSseBroker();
+    broker.addClient("ch1", vi.fn(), vi.fn());
+    broker.addClient("ch1", vi.fn(), vi.fn());
+    broker.addClient("ch2", vi.fn(), vi.fn());
+
+    expect(broker.getClientCount("ch1")).toBe(2);
+    expect(broker.getClientCount("ch2")).toBe(1);
+    expect(broker.getTotalClientCount()).toBe(3);
+  });
+
+  test("pushToChannel sends to all clients on channel", () => {
+    const broker = createSseBroker();
+    const send1 = vi.fn();
+    const send2 = vi.fn();
+    const sendOther = vi.fn();
+
+    broker.addClient("users", send1, vi.fn());
+    broker.addClient("users", send2, vi.fn());
+    broker.addClient("other", sendOther, vi.fn());
+
+    const event: SseEvent = { type: "user.created", data: { id: 1 } };
+    broker.pushToChannel("users", event);
+
+    expect(send1).toHaveBeenCalledWith(event);
+    expect(send2).toHaveBeenCalledWith(event);
+    expect(sendOther).not.toHaveBeenCalled();
+  });
+
+  test("removeClient stops delivery", () => {
+    const broker = createSseBroker();
+    const send = vi.fn();
+
+    const clientId = broker.addClient("ch", send, vi.fn());
+    broker.removeClient("ch", clientId);
+
+    broker.pushToChannel("ch", { type: "test", data: {} });
+    expect(send).not.toHaveBeenCalled();
+    expect(broker.getClientCount("ch")).toBe(0);
+  });
+
+  test("pushToChannel to empty channel does nothing", () => {
+    const broker = createSseBroker();
+    // Should not throw
+    broker.pushToChannel("empty", { type: "test", data: {} });
+    expect(broker.getClientCount("empty")).toBe(0);
+  });
+
+  test("removeClient from unknown channel does nothing", () => {
+    const broker = createSseBroker();
+    expect(() => broker.removeClient("unknown", "fake-id")).not.toThrow();
+    expect(broker.getClientCount("unknown")).toBe(0);
+  });
+});

package/src/api/__tests__/sse-route.test.ts

@@ -0,0 +1,112 @@
+import { Hono } from "hono";
+import { describe, expect, test } from "vitest";
+import { TestUsers } from "../../stack";
+import { authMiddleware } from "../auth-middleware";
+import { createJwtHelper } from "../jwt";
+import type { SseBroker, SseEvent } from "../sse-broker";
+import { createSseRoute } from "../sse-route";
+
+const JWT_SECRET = "sse-route-unit-test-secret-at-least-32-characters";
+
+function createTrackingBroker(): { broker: SseBroker; subscribedChannel: Promise<string> } {
+  let resolveChannel!: (channel: string) => void;
+  const subscribedChannel = new Promise<string>((resolve) => {
+    resolveChannel = resolve;
+  });
+
+  const broker: SseBroker = {
+    addClient(channel, _send, _close) {
+      resolveChannel(channel);
+      return "test-client-id";
+    },
+    removeClient() {},
+    pushToChannel(_channel: string, _event: SseEvent) {},
+    getClientCount() {
+      return 0;
+    },
+    getTotalClientCount() {
+      return 0;
+    },
+  };
+
+  return { broker, subscribedChannel };
+}
+
+async function buildSseApp(broker: SseBroker): Promise<{ app: Hono; token: string }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const token = await jwt.sign(TestUsers.user); // tenantId = 1
+
+  const app = new Hono();
+  app.use("/api/*", authMiddleware(jwt));
+  app.route("/api", createSseRoute(broker));
+  return { app, token };
+}
+
+describe("sse-route security", () => {
+  test("subscribes to authenticated tenant channel, ignores client query-param", async () => {
+    const { broker, subscribedChannel } = createTrackingBroker();
+    const { app, token } = await buildSseApp(broker);
+
+    const controller = new AbortController();
+    // Stream keeps the request open — fire without awaiting, then abort.
+    // Promise.resolve() normalises Response | Promise<Response> to a thenable.
+    void Promise.resolve(
+      app.request("/api/sse?channel=tenant:999", {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: controller.signal,
+      }),
+    ).catch(() => {
+      // Aborted — expected.
+    });
+
+    const channel = await subscribedChannel;
+    controller.abort();
+
+    expect(channel).toBe("tenant:00000000-0000-4000-8000-000000000001");
+    expect(channel).not.toBe("tenant:999");
+  });
+
+  test("subscribes to authenticated tenant channel even without any query-param", async () => {
+    const { broker, subscribedChannel } = createTrackingBroker();
+    const { app, token } = await buildSseApp(broker);
+
+    const controller = new AbortController();
+    void Promise.resolve(
+      app.request("/api/sse", {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: controller.signal,
+      }),
+    ).catch(() => {});
+
+    const channel = await subscribedChannel;
+    controller.abort();
+
+    expect(channel).toBe("tenant:00000000-0000-4000-8000-000000000001");
+  });
+
+  test("rejects request without Bearer token", async () => {
+    const { broker } = createTrackingBroker();
+    const { app } = await buildSseApp(broker);
+
+    const res = await app.request("/api/sse");
+    expect(res.status).toBe(401);
+  });
+
+  test("cross-tenant injection attempt: user in tenant 1 cannot subscribe to tenant 2", async () => {
+    const { broker, subscribedChannel } = createTrackingBroker();
+    const { app, token } = await buildSseApp(broker); // token: tenantId 1
+
+    const controller = new AbortController();
+    void Promise.resolve(
+      app.request("/api/sse?channel=tenant:2&channel=tenant:3", {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: controller.signal,
+      }),
+    ).catch(() => {});
+
+    const channel = await subscribedChannel;
+    controller.abort();
+
+    expect(channel).toBe("tenant:00000000-0000-4000-8000-000000000001");
+  });
+});

package/src/api/anonymous-cookie.ts

@@ -0,0 +1,60 @@
+// Server-side helper for the kumiko_tenant cookie used by the anonymous-
+// access flow. Apps call setTenantCookie(c, tenantId) once a tenantResolver
+// has determined the visitor's tenant, so subsequent requests skip the
+// resolver (which usually does DB / cache lookups). deleteTenantCookie
+// pairs with a switch-tenant or logout flow.
+//
+// The cookie is HttpOnly: the only consumer is the server-side auth-
+// middleware on the next request — no client-side JS needs to read it,
+// and not exposing it to JS keeps it out of XSS reach.
+
+import type { Context } from "hono";
+import { deleteCookie, setCookie } from "hono/cookie";
+import type { TenantId } from "../engine/types";
+import { TENANT_COOKIE_NAME } from "./api-constants";
+
+// 30 days. The tenant assignment is stable for the lifetime of the
+// visitor's relationship with the deployment — re-running the resolver
+// on every visit would just hit the DB for no new information.
+const DEFAULT_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+
+// Cookies marked Secure are dropped by browsers on http:// — locked off in
+// dev/test so localhost works without TLS, on in prod where http would be
+// a deployment bug we want to fail loud about (no cookie ⇒ resolver runs
+// every request and the misconfiguration is visible in latency dashboards).
+function cookieSecure(): boolean {
+  return process.env["NODE_ENV"] === "production";
+}
+
+export type SetTenantCookieOptions = {
+  // Override the default 30-day lifetime. Use shorter values for previews,
+  // longer for stable installations.
+  readonly maxAgeSeconds?: number;
+  // SameSite policy. Default "Lax" matches auth-cookie behaviour and
+  // permits cross-site GET-navigation (e.g. inbound link from a search
+  // result lands the visitor on the right tenant via the cookie).
+  readonly sameSite?: "Lax" | "Strict";
+};
+
+// Stamps the kumiko_tenant cookie on the response. Idempotent — calling it
+// twice in the same request just overwrites with the latest value.
+export function setTenantCookie(
+  c: Context,
+  tenantId: TenantId,
+  options: SetTenantCookieOptions = {},
+): void {
+  setCookie(c, TENANT_COOKIE_NAME, tenantId, {
+    httpOnly: true,
+    secure: cookieSecure(),
+    sameSite: options.sameSite ?? "Lax",
+    path: "/",
+    maxAge: options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS,
+  });
+}
+
+// Removes the kumiko_tenant cookie. Use on switch-tenant flows or when
+// the resolver no longer recognises the visitor's tenant — leaving a
+// stale cookie behind would keep them pointed at a deleted tenant.
+export function deleteTenantCookie(c: Context): void {
+  deleteCookie(c, TENANT_COOKIE_NAME, { path: "/" });
+}

package/src/api/api-constants.ts

@@ -0,0 +1,64 @@
+// API-internal constants. Features should never need these —
+// they register handlers, the framework handles routing.
+
+export const Routes = {
+  health: "/health",
+  healthReady: "/health/ready",
+  version: "/version",
+  write: "/write",
+  batch: "/batch",
+  query: "/query",
+  command: "/command",
+  sse: "/sse",
+  auth: "/auth",
+  authLogin: "/auth/login",
+  authLogout: "/auth/logout",
+  authTenants: "/auth/tenants",
+  authSwitchTenant: "/auth/switch-tenant",
+  authRequestPasswordReset: "/auth/request-password-reset",
+  authResetPassword: "/auth/reset-password",
+  authRequestEmailVerification: "/auth/request-email-verification",
+  authVerifyEmail: "/auth/verify-email",
+  authSignupRequest: "/auth/signup-request",
+  authSignupConfirm: "/auth/signup-confirm",
+  // Tenant-Invite (Magic-Link): 3 separate accept-Endpoints für klare
+  // Branch-Separation. Plus invite-info als public-readable details
+  // damit das Frontend "Du wirst eingeladen zu Tenant X als Role Y"
+  // anzeigen kann bevor der User submitted.
+  authInviteAccept: "/auth/invite-accept",
+  authInviteAcceptWithLogin: "/auth/invite-accept-with-login",
+  authInviteSignupComplete: "/auth/invite-signup-complete",
+  authInviteInfo: "/auth/invite-info",
+  files: "/files",
+} as const;
+
+// Routes that must be reachable WITHOUT a valid JWT.
+// The auth middleware skips these paths.
+export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
+  `/api${Routes.authLogin}`,
+  `/api${Routes.authRequestPasswordReset}`,
+  `/api${Routes.authResetPassword}`,
+  `/api${Routes.authRequestEmailVerification}`,
+  `/api${Routes.authVerifyEmail}`,
+  `/api${Routes.authSignupRequest}`,
+  `/api${Routes.authSignupConfirm}`,
+  // invite-accept braucht JWT (logged-in User, Branch 1) — NICHT public.
+  // invite-accept-with-login (Branch 2) und invite-signup-complete
+  // (Branch 3) sind anonymous, brauchen public-skip.
+  `/api${Routes.authInviteAcceptWithLogin}`,
+  `/api${Routes.authInviteSignupComplete}`,
+  `/api${Routes.authInviteInfo}`,
+  `/api${Routes.health}`,
+  `/api${Routes.healthReady}`,
+  `/api${Routes.version}`,
+]);
+
+// Tenant transports for unauthenticated callers on public endpoints. JWT
+// users carry tenantId in the signed token; anonymous callers must declare
+// the tenant out-of-band — header for SPA/mobile, cookie for browser-direct
+// access. The middleware reads header first, then cookie, then falls back to
+// `anonymousAccess.tenantResolver` and finally `anonymousAccess.defaultTenantId`.
+export const TENANT_HEADER_NAME = "X-Tenant";
+export const TENANT_COOKIE_NAME = "kumiko_tenant";
+
+export type Route = (typeof Routes)[keyof typeof Routes];