@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/__tests__/schema-cli.integration.test.ts

@@ -177,6 +177,27 @@ describe("runSchemaCli — validate (static CI gate, no DB)", () => {
     const code = await runSchemaCli(["validate"], appCwd, cap.out);
     expect(code).toBe(0);
     expect(cap.log.join("\n")).toContain("migrations match");
+    expect(cap.log.join("\n")).toContain("table/column names match .snapshot.json");
+  });
+
+  // Reproduces the kumiko-studio 0016 incident: a migration file gets
+  // hand-edited (or copy-pasted from another file) after `generate` wrote
+  // it — the snapshot still matches ENTITY_METAS (layer 1 stays green), but
+  // the .sql content no longer produces what the snapshot claims.
+  test("migration file edited after generate to not match its snapshot entry → drift, exit 1", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    writeFileSync(
+      join(appCwd, "kumiko/migrations/0001_init.sql"),
+      `-- oops: hand-edited to the wrong table name after the snapshot was written
+CREATE TABLE IF NOT EXISTS "read_widgets_v2" ("id" uuid PRIMARY KEY);
+`,
+    );
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("migration-content drift");
+    expect(cap.err.join("\n")).toContain("read_widgets");
   });
 
   test("no FEATURES export → validateBoot skipped (drift still checked)", async () => {
@@ -204,6 +225,35 @@ export const FEATURES = [];
     expect(code).toBe(0);
     expect(cap.log.join("\n")).toContain("feature configuration is valid");
   });
+
+  test("FEATURES with a bad nav→screen ref → validateBoot fails, exit 1 (512/1)", async () => {
+    // Absolute file import (not the package name): appCwd is a bare tmpdir
+    // with no node_modules of its own — a real app resolves
+    // "@cosmicdrift/kumiko-framework/engine" via its own install, but this
+    // synthetic fixture needs a resolvable path regardless of cwd.
+    const engineSrc = join(import.meta.dir, "../engine/index.ts");
+    writeFileSync(
+      join(appCwd, "kumiko/schema.ts"),
+      `import { defineFeature } from "${engineSrc}";
+export const ENTITY_METAS = [
+  { tableName: "read_widgets", source: "unmanaged", indexes: [],
+    columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true, defaultSql: "gen_random_uuid()" }] },
+];
+export const FEATURES = [
+  defineFeature("probe", (r) => {
+    r.nav({ id: "nav-ghost", label: "Ghost", screen: "probe:screen:ghost" });
+  }),
+];
+`,
+    );
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("boot:");
+    expect(cap.err.join("\n")).toContain("probe:screen:ghost");
+    expect(cap.err.join("\n")).toContain("is not registered");
+  });
 });
 
 describe("runSchemaCli — DB-backed paths", () => {

package/src/__tests__/store-table.integration.test.ts

@@ -0,0 +1,93 @@
+// Integration test for r.storeTable() — proves the full boot path:
+// defineFeature declares a store table → setupTestStack auto-pushes it →
+// INSERT/SELECT against the real DB roundtrip. Plan reference:
+// kumiko-platform/docs/plans/architecture/table-ddl-guard.md (Stufe 3).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineUnmanagedTable } from "../db/entity-table-meta";
+import { asRawClient, insertOne, selectMany } from "../db/query";
+import { defineFeature } from "../engine";
+import { setupTestStack, type TestStack, unsafePushTables } from "../stack";
+
+// External-system payload cache — the textbook r.storeTable() use case:
+// write-only by an integration handler, read-only by a query, never
+// event-sourced (the data isn't a domain fact, it's a side-effect
+// snapshot).
+const stripeWebhookCacheMeta = defineUnmanagedTable({
+  tableName: "rt_int_stripe_webhook_cache",
+  columns: [
+    { name: "event_id", pgType: "text", notNull: true, primaryKey: true },
+    { name: "payload", pgType: "text", notNull: true },
+    { name: "received_at", pgType: "timestamptz", notNull: true, defaultSql: "now()" },
+  ],
+});
+
+const webhookCacheFeature = defineFeature("webhook-cache", (r) => {
+  r.storeTable(stripeWebhookCacheMeta, {
+    reason: "external Stripe webhook payload cache — write-only by webhook handler",
+  });
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [webhookCacheFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("r.storeTable — DB roundtrip via setupTestStack", () => {
+  test("table is auto-pushed and accepts INSERT + SELECT", async () => {
+    const eventId = "evt_test_123";
+    const payload = JSON.stringify({ type: "invoice.paid", amount: 4200 });
+
+    await insertOne(stack.db, stripeWebhookCacheMeta, { eventId, payload });
+
+    const rows = await selectMany(stack.db, stripeWebhookCacheMeta, { eventId: eventId });
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.payload).toBe(payload);
+    expect(rows[0]?.receivedAt).toBeInstanceOf(Temporal.Instant);
+  });
+
+  test("registry exposes the store table with its reason and featureName", () => {
+    const all = stack.registry.getAllStoreTables();
+    const entry = all.get("rt_int_stripe_webhook_cache");
+    expect(entry).toBeDefined();
+    expect(entry?.featureName).toBe("webhook-cache");
+    expect(entry?.reason).toContain("Stripe webhook payload cache");
+    expect(entry?.meta).toBe(stripeWebhookCacheMeta);
+  });
+
+  test("INSERT bypasses the event store — no kumiko_events row produced", async () => {
+    // Proves that the storeTable lives outside the event-sourcing graph:
+    // a write to it shouldn't append anything to kumiko_events. If a
+    // future regression accidentally routed store-table writes through
+    // the executor, a row would show up here.
+    const before = await asRawClient(stack.db).unsafe<{ count: string }>(
+      `SELECT COUNT(*)::text AS count FROM kumiko_events`,
+    );
+    const beforeCount = Number(before[0]?.count ?? 0);
+
+    await insertOne(stack.db, stripeWebhookCacheMeta, {
+      eventId: "evt_no_event_emitted",
+      payload: "{}",
+    });
+
+    const after = await asRawClient(stack.db).unsafe<{ count: string }>(
+      `SELECT COUNT(*)::text AS count FROM kumiko_events`,
+    );
+    const afterCount = Number(after[0]?.count ?? 0);
+
+    expect(afterCount).toBe(beforeCount);
+  });
+
+  test("a second push on the same storeTable is idempotent — CREATE IF NOT EXISTS", async () => {
+    // unsafePushTables uses CREATE TABLE IF NOT EXISTS — idempotent by design.
+    await expect(
+      unsafePushTables(stack.db, { idem: stripeWebhookCacheMeta }),
+    ).resolves.toBeUndefined();
+  });
+});

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

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { parseSseFrames } from "@cosmicdrift/kumiko-dispatcher-live";
+import { Hono } from "hono";
 import { z } from "zod";
 import {
   createEntity,
@@ -7,7 +9,10 @@ import {
   defineFeature,
   type TenantId,
 } from "../../engine";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
 import { createTestUser, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
+import { createApiRoutes, pumpStream, StreamFrame } from "../routes";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -28,6 +33,38 @@ const testFeature = defineFeature("test", (r) => {
     async () => [{ id: 1, name: "Test" }],
     { access: { openToAll: true } },
   );
+
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.streamHandler(
+    "item:tail-fail-mid",
+    z.object({}),
+    async function* () {
+      yield { i: 0 };
+      yield { i: 1 };
+      throw new Error("boom");
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.streamHandler(
+    "item:tail-fail-first",
+    z.object({}),
+    // biome-ignore lint/correctness/useYield: deliberately throws before any yield — tests the pre-pull failure path
+    async function* () {
+      throw new Error("boom");
+    },
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 const registry = createRegistry([testFeature]);
@@ -199,6 +236,138 @@ describe("POST /api/command", () => {
   });
 });
 
+// --- pumpStream (SSE pull loop) ---
+
+function fakeSseWriter() {
+  const frames: Array<{ event: string; data: string }> = [];
+  return {
+    frames,
+    async writeSSE(message: { event: string; data: string }) {
+      frames.push(message);
+    },
+  };
+}
+
+async function* delayedGenerator(values: readonly unknown[], delayMsByIndex: readonly number[]) {
+  for (let i = 0; i < values.length; i++) {
+    const delay = delayMsByIndex[i] ?? 0;
+    if (delay > 0) await Bun.sleep(delay);
+    yield values[i];
+  }
+}
+
+describe("pumpStream", () => {
+  test("emits a ping when the handler is slow, then still delivers the pending chunk (no loss)", async () => {
+    const writer = fakeSseWriter();
+    // heartbeatMs (10) fires before the 40ms-delayed second chunk resolves.
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }], [0, 40]);
+
+    await pumpStream(writer, gen, 10);
+
+    const events = writer.frames.map((f) => f.event);
+    expect(events[0]).toBe("chunk");
+    expect(events).toContain("ping");
+    expect(events.at(-1)).toBe("done");
+    // Both chunks arrive despite the ping in between — no chunk dropped.
+    const chunkData = writer.frames.filter((f) => f.event === "chunk").map((f) => f.data);
+    expect(chunkData).toEqual([JSON.stringify({ i: 0 }), JSON.stringify({ i: 1 })]);
+  });
+
+  test("no heartbeat fires when the handler is faster than heartbeatMs — chunks then done", async () => {
+    const writer = fakeSseWriter();
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }, { i: 2 }], [0, 0, 0]);
+
+    await pumpStream(writer, gen, 1000);
+
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk", "chunk", "chunk", "done"]);
+  });
+
+  test("a handler generator that throws propagates the error instead of swallowing it", async () => {
+    const writer = fakeSseWriter();
+    async function* throwing() {
+      yield { i: 0 };
+      throw new Error("handler-boom");
+    }
+
+    await expect(pumpStream(writer, throwing(), 1000)).rejects.toThrow("handler-boom");
+    // The chunk before the throw still made it out.
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk"]);
+  });
+
+  test("closes the generator when writeSSE throws mid-loop (e.g. client disconnected on a ping)", async () => {
+    let cleanedUp = false;
+    async function* gen() {
+      try {
+        await Bun.sleep(50);
+        yield { i: 0 };
+      } finally {
+        cleanedUp = true;
+      }
+    }
+    const frames: Array<{ event: string; data: string }> = [];
+    const writer = {
+      frames,
+      async writeSSE(message: { event: string; data: string }) {
+        if (message.event === StreamFrame.ping) throw new Error("client disconnected");
+        frames.push(message);
+      },
+    };
+
+    await expect(pumpStream(writer, gen(), 5)).rejects.toThrow("client disconnected");
+    // Fire-and-forget cleanup (kumiko-framework#1547): pumpStream's finally
+    // no longer awaits generator.return() — it can't, since a still-pending
+    // .next() would make that await hang — so cleanedUp flips asynchronously
+    // after pumpStream's own rejection, not synchronously before it.
+    await waitFor(() => {
+      expect(cleanedUp).toBe(true);
+    });
+  });
+
+  test("does not hang when writeSSE throws while a .next() pull is still in flight", async () => {
+    // kumiko-framework#1547: generator.return() queues behind an in-flight
+    // .next() (V8 semantics) — an `await generator.return(undefined)` in the
+    // finally block would hang for as long as the handler's .next() never
+    // settles, which a dead Redis/DB subscription can do indefinitely.
+    // `never` intentionally never resolves — the fire-and-forget fix must
+    // not need it to.
+    const never = new Promise<never>(() => {});
+    async function* gen() {
+      await never;
+      yield { i: 0 };
+    }
+    const writer = {
+      frames: [] as Array<{ event: string; data: string }>,
+      async writeSSE(message: { event: string; data: string }) {
+        if (message.event === StreamFrame.ping) throw new Error("client disconnected");
+        this.frames.push(message);
+      },
+    };
+
+    const TIMEOUT = Symbol("timeout");
+    const outcome = await Promise.race([
+      pumpStream(writer, gen(), 5).then(
+        () => "resolved",
+        (e) => e,
+      ),
+      Bun.sleep(500).then(() => TIMEOUT),
+    ]);
+    expect(outcome).not.toBe(TIMEOUT);
+    expect(outcome).toBeInstanceOf(Error);
+    expect((outcome as Error).message).toBe("client disconnected");
+  });
+
+  test("serializes an undefined yielded value as an explicit null chunk instead of an invalid frame", async () => {
+    const writer = fakeSseWriter();
+    async function* gen() {
+      yield undefined;
+    }
+
+    await pumpStream(writer, gen(), 1000);
+
+    expect(writer.frames[0]).toEqual({ event: StreamFrame.chunk, data: "null" });
+  });
+});
+
 // --- SSE ---
 
 describe("GET /api/sse", () => {
@@ -215,6 +384,210 @@ describe("GET /api/sse", () => {
   });
 });
 
+// --- Stream (dispatcher-driven SSE) ---
+
+describe("POST /api/stream", () => {
+  test("dispatches stream handler and yields chunk frames then done", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: 3 } },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+    const frames = parseSseFrames(await res.text());
+    expect(frames).toEqual([
+      { event: "chunk", data: JSON.stringify({ i: 0 }) },
+      { event: "chunk", data: JSON.stringify({ i: 1 }) },
+      { event: "chunk", data: JSON.stringify({ i: 2 }) },
+      { event: "done", data: "" },
+    ]);
+  });
+
+  test("access-denied gate surfaces as a real 403, not an HTTP 200 error frame", async () => {
+    // Dispatch gates (feature/rate-limit/access/validation) run on the
+    // generator's first pull, which the route now performs BEFORE opening
+    // the SSE response — so a gate failure maps to its real HTTP status
+    // instead of a flushed-200 error frame (framework#1517).
+    const headers = await authHeader(guestUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: 1 } },
+      headers,
+    );
+
+    expect(res.status).toBe(403);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+    const body = await res.json();
+    expect(body.error).toMatchObject({ code: "access_denied" });
+  });
+
+  test("returns 404 for unknown stream handler", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req("POST", "/api/stream", { type: "nope", payload: {} }, headers);
+
+    expect(res.status).toBe(404);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+  });
+
+  test("returns 400 for schema validation failure", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: -1 } },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+  });
+
+  test("handler failure after chunks already sent stays HTTP 200 with an error frame", async () => {
+    // Boundary between the pre-pull fix and the still-open SSE stream: a
+    // failure that happens AFTER the first chunk (headers already flushed)
+    // must keep surfacing as a 200 + "error" frame, not a real HTTP status.
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail-fail-mid", payload: {} },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+    const frames = parseSseFrames(await res.text());
+    expect(frames).toHaveLength(3);
+    expect(frames.slice(0, 2)).toEqual([
+      { event: "chunk", data: JSON.stringify({ i: 0 }) },
+      { event: "chunk", data: JSON.stringify({ i: 1 }) },
+    ]);
+    expect(frames[2]?.event).toBe("error");
+    expect(JSON.parse(frames[2]?.data ?? "{}")).toMatchObject({ code: "internal_error" });
+  });
+
+  test("handler failure before the first yield surfaces as a real HTTP 500, not an SSE error frame", async () => {
+    // Contract-pin for routes.ts's "error frames only reachable once the
+    // stream is already open" comment: a generator that throws before its
+    // first yield is caught by the same pre-pull gate as feature/access/
+    // rate-limit/validation failures — the client sees 500 + JSON, not a
+    // 200 with an SSE error frame.
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail-fail-first", payload: {} },
+      headers,
+    );
+
+    expect(res.status).toBe(500);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+    const body = await res.json();
+    expect(body.error).toMatchObject({ code: "internal_error" });
+  });
+});
+
+// --- POST /api/stream pre-pull race (framework#1547) ---
+// Mount createApiRoutes with a short sseHeartbeatMs so the pre-pull heartbeat
+// race is testable without waiting for the production 15s interval.
+
+describe("POST /api/stream pre-pull race", () => {
+  const user = createTestUser({ roles: ["Admin"] });
+
+  function stubDispatcher(streamImpl: Dispatcher["stream"]): Dispatcher {
+    return {
+      async write(): Promise<WriteResult> {
+        return { isSuccess: true, data: {} };
+      },
+      async query(): Promise<unknown> {
+        return [];
+      },
+      stream: streamImpl,
+      async command(): Promise<void> {},
+      async batch(): Promise<BatchResult> {
+        return { isSuccess: true, results: [] };
+      },
+      async resolveAuthClaims(): Promise<Record<string, unknown>> {
+        return {};
+      },
+    };
+  }
+
+  function mountStreamApp(dispatcher: Dispatcher, sseHeartbeatMs: number) {
+    const app = new Hono<{ Variables: { pipelineUser: typeof user } }>();
+    app.use("/api/*", async (c, next) => {
+      c.set("pipelineUser", user);
+      await next();
+    });
+    app.route("/api", createApiRoutes(dispatcher, { sseHeartbeatMs }));
+    return app;
+  }
+
+  test("slow first next() opens 200 SSE with ping frames instead of hanging as HTTP error", async () => {
+    // First .next() takes longer than heartbeatMs → settledInTime=false →
+    // streamSSE opens immediately and pumpStream emits ping until the chunk
+    // arrives (framework#1547 route-level contract).
+    const dispatcher = stubDispatcher(async function* () {
+      await Bun.sleep(60);
+      yield { i: 0 };
+    });
+    const app = mountStreamApp(dispatcher, 20);
+    const res = await app.request(
+      new Request("http://localhost/api/stream", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ type: "any:stream:tail", payload: {} }),
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+    const frames = parseSseFrames(await res.text());
+    const events = frames.map((f) => f.event);
+    expect(events).toContain("ping");
+    expect(events).toContain("chunk");
+    expect(events.at(-1)).toBe("done");
+  });
+
+  test("client abort during pre-pull returns 499 and runs generator cleanup", async () => {
+    // Finite sleep (not a never-resolving await): V8 queues .return() behind an
+    // in-flight .next(), so cleanup only runs once the pending pull settles.
+    // Abort before heartbeatMs so the route hits the 499 branch; sleep then
+    // completes and the queued return drains the generator's finally.
+    let cleanedUp = false;
+    const dispatcher = stubDispatcher(async function* () {
+      try {
+        await Bun.sleep(80);
+        yield { i: 0 };
+      } finally {
+        cleanedUp = true;
+      }
+    });
+    const app = mountStreamApp(dispatcher, 40);
+    const ac = new AbortController();
+    const pending = app.request(
+      new Request("http://localhost/api/stream", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ type: "any:stream:tail", payload: {} }),
+        signal: ac.signal,
+      }),
+    );
+    // Abort while firstPull is still racing the heartbeat timer.
+    await Bun.sleep(5);
+    ac.abort();
+    const res = await pending;
+    expect(res.status).toBe(499);
+    await waitFor(() => {
+      expect(cleanedUp).toBe(true);
+    });
+  });
+});
+
 // --- r.httpRoute (feature-deklarierte HTTP-Routes außerhalb /api/) ---
 
 describe("feature-declared HTTP routes (r.httpRoute)", () => {

package/src/api/__tests__/auth-middleware-anonymous-access-boot.test.ts

@@ -0,0 +1,40 @@
+// authMiddleware boots eagerly (not per-request) so a tenantResolver
+// declared without resolverTrust is an ambiguous trust decision that fails
+// loud at startup, instead of silently letting a client-set tenant header
+// override a host-derived resolver at request time (#1452).
+
+import { describe, expect, test } from "bun:test";
+import { authMiddleware } from "../auth-middleware";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-middleware-anon-access-boot-test-secret-32ch";
+
+describe("authMiddleware anonymousAccess boot guard", () => {
+  test("throws at construction when tenantResolver is set without resolverTrust", () => {
+    const jwt = createJwtHelper(JWT_SECRET);
+    expect(() =>
+      authMiddleware(jwt, {
+        anonymousAccess: {
+          tenantResolver: () => "t1" as never,
+        },
+      }),
+    ).toThrow(/resolverTrust/);
+  });
+
+  test("does not throw when resolverTrust is declared", () => {
+    const jwt = createJwtHelper(JWT_SECRET);
+    expect(() =>
+      authMiddleware(jwt, {
+        anonymousAccess: {
+          tenantResolver: () => "t1" as never,
+          resolverTrust: "authoritative",
+        },
+      }),
+    ).not.toThrow();
+  });
+
+  test("does not throw when no tenantResolver is configured", () => {
+    const jwt = createJwtHelper(JWT_SECRET);
+    expect(() => authMiddleware(jwt, {})).not.toThrow();
+  });
+});

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -37,6 +37,7 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async query(): Promise<unknown> {
       return [];
     },
+    async *stream(): AsyncGenerator<unknown> {},
     async command(): Promise<void> {},
     async batch(): Promise<BatchResult> {
       const ok: BatchResult = { isSuccess: true, results: [] };
@@ -52,8 +53,11 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
 async function buildApp(
   overrides: Partial<AuthRoutesConfig> = {},
   dispatcher: Dispatcher = createStubDispatcher(),
+  ttlSeconds?: number,
 ): Promise<{ app: Hono; validToken: string }> {
-  const jwt = createJwtHelper(JWT_SECRET);
+  const jwt = ttlSeconds
+    ? createJwtHelper(JWT_SECRET, undefined, ttlSeconds)
+    : createJwtHelper(JWT_SECRET);
   const validToken = await jwt.sign(TestUsers.user);
   const config: AuthRoutesConfig = {
     membershipQuery: "tenant:query:memberships",
@@ -128,6 +132,18 @@ describe("auth-routes cookie behaviour on /auth/login", () => {
     expect(typeof body.token).toBe("string");
     expect(body.token.length).toBeGreaterThan(20);
   });
+
+  test("cookie maxAge tracks the jwt helper's ttlSeconds, not a hardcoded default", async () => {
+    const customTtl = 60 * 60; // 1h — distinct from the 24h default
+    const { app } = await buildApp({}, undefined, customTtl);
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+  });
 });
 
 describe("auth-routes cookie behaviour on /auth/logout", () => {