@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/api/server.ts

@@ -3,6 +3,7 @@ import type { DbConnection, PgClient } from "../db/connection";
 import { createTenantDb } from "../db/tenant-db";
 import { EXT_FILE_PROVIDER } from "../engine/extension-names";
 import { runsInLane } from "../engine/run-in";
+import { createAnonymousUser } from "../engine/system-user";
 import {
   type AppContext,
   isFileField,
@@ -33,6 +34,8 @@ import { createEventDispatcher } from "../pipeline/event-dispatcher";
 import { createLifecycleHooks, type SystemHooks } from "../pipeline/lifecycle-pipeline";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context";
 import {
+  createAccessInvalidationEventConsumer,
+  createJobTriggerEventConsumer,
   createSearchEventConsumer,
   createSseBroadcastEventConsumer,
 } from "../pipeline/system-hooks";
@@ -46,12 +49,13 @@ import {
 import type { SearchAdapter } from "../search/types";
 import { assertUnreachable, generateId } from "../utils";
 import { PUBLIC_API_PATHS } from "./api-constants";
-import { type AnonymousAccessConfig, authMiddleware } from "./auth-middleware";
+import { type AnonymousAccessResolved, authMiddleware, getUser } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
-import { createJwtHelper, type JwtHelper } from "./jwt";
+import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
+import { piiCiphertextResponseGuard } from "./pii-leak-guard";
 import { requestIdMiddleware } from "./request-id-middleware";
 import {
   DEFAULT_MAX_REQUEST_BYTES,
@@ -67,8 +71,13 @@ import { createSseRoute } from "./sse-route";
 export type ServerOptions = {
   registry: Registry;
   context: AppContext;
-  jwtSecret: string;
+  jwtSecret: string | JwtKeyring;
   jwtIssuer?: string;
+  // JWT lifetime in seconds. Explicit always wins. When omitted, the default
+  // depends on `auth.sessionChecker`: wired (revocation possible) keeps the
+  // long-lived 24h default; unwired (stateless JWTs, no revocation) drops to
+  // 1h so a leaked stateless token has a much smaller exposure window.
+  jwtTtl?: number;
   dispatcherOptions?: Omit<DispatcherOptions, "lifecycle">;
   systemHooks?: SystemHooks;
   eventDedup?: EventDedup;
@@ -92,16 +101,25 @@ export type ServerOptions = {
     pollIntervalMs?: number;
     batchSize?: number;
     maxAttempts?: number;
+    rearmCooldownMs?: number;
+    maxRearmCount?: number;
     // Opt out of building the dispatcher even if consumers exist — e.g. ops
     // runs a dedicated dispatcher process, or a test needs to control the
     // consumer lifecycle manually.
     disabled?: boolean;
-    // Opt out of the auto-built system consumers (SSE, Search) while still
-    // running feature r.multiStreamProjection consumers. Useful for tests
-    // that assert only on subscriber behaviour, or for a deployment that
-    // routes SSE via a different transport. Default: both enabled when the
-    // respective dependency (sseBroker / context.searchAdapter) is available.
-    systemConsumers?: { sse?: boolean; search?: boolean };
+    // Opt out of the auto-built system consumers (SSE, Search, Job-Trigger)
+    // while still running feature r.multiStreamProjection consumers. Useful
+    // for tests that assert only on subscriber behaviour, or for a
+    // deployment that routes SSE via a different transport. Default: sse/
+    // search enabled when the respective dependency (sseBroker /
+    // context.searchAdapter) is available; jobTrigger enabled when a
+    // jobRunner is wired via dispatcherOptions.
+    systemConsumers?: {
+      sse?: boolean;
+      search?: boolean;
+      jobTrigger?: boolean;
+      accessInvalidation?: boolean;
+    };
     // Raw postgres.js client for LISTEN/NOTIFY wake-up (Sprint E.4). When
     // present, `.start()` subscribes to EVENTS_PUBSUB_CHANNEL — delivery
     // latency drops from pollIntervalMs to TCP-round-trip. The poll timer
@@ -192,9 +210,10 @@ export type ServerOptions = {
   instanceId?: string;
   // Opt-in: serve unauthenticated requests on handlers that allow
   // roles=["anonymous"]. When omitted, every /api/* request still requires
-  // a valid JWT (status quo). See AnonymousAccessConfig for the resolution
-  // chain (header → cookie → resolver → defaultTenantId).
-  anonymousAccess?: AnonymousAccessConfig;
+  // a valid JWT (status quo). App-facing config is AnonymousAccessConfig
+  // (defaultTenantId only); run{Prod,Dev}App merge auth-foundation tenant
+  // providers into AnonymousAccessResolved before calling buildServer.
+  anonymousAccess?: AnonymousAccessResolved;
 };
 
 export type KumikoServer = {
@@ -236,7 +255,15 @@ export function buildServer(options: ServerOptions): KumikoServer {
     );
   }
 
-  const jwt = createJwtHelper(options.jwtSecret, options.jwtIssuer);
+  // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
+  // TTL than session-backed ones, since a leaked stateless token can't be
+  // revoked and stays valid until it expires. Explicit jwtTtl always wins.
+  const defaultJwtTtl = options.auth?.sessionChecker ? 24 * 60 * 60 : 60 * 60;
+  const jwt = createJwtHelper(
+    options.jwtSecret,
+    options.jwtIssuer,
+    options.jwtTtl ?? defaultJwtTtl,
+  );
   const sseBroker = options.sseBroker ?? createSseBroker();
 
   // Resolve the per-process instance identifier. Prefer explicit
@@ -358,6 +385,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const dispatcher = createDispatcher(options.registry, contextWithObservability, {
     ...options.dispatcherOptions,
     lifecycle,
+    sseBroker,
   });
 
   // Async event-dispatcher — the replacement for the old transactional
@@ -380,6 +408,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
 
   const sseConsumerEnabled = options.eventDispatcher?.systemConsumers?.sse ?? true;
   const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
+  const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
+  const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
 
   const systemConsumers: EventConsumer[] = [];
   if (sseConsumerEnabled) {
@@ -388,6 +418,18 @@ export function buildServer(options: ServerOptions): KumikoServer {
   if (searchConsumerEnabled && searchAdapter) {
     systemConsumers.push(createSearchEventConsumer(searchAdapter, options.registry));
   }
+  if (jobTriggerConsumerEnabled && jobRunnerForTriggers) {
+    systemConsumers.push(createJobTriggerEventConsumer(jobRunnerForTriggers, options.registry));
+  }
+  // Default ON (#1524 global-by-default). Tests that opt out of SSE via
+  // systemConsumers.accessInvalidation=false (test-stack mirrors sse off)
+  // skip the row so retention prune suites are not blocked by a lagging
+  // cursor=0 consumer they never drain.
+  const accessInvalidationEnabled =
+    options.eventDispatcher?.systemConsumers?.accessInvalidation ?? true;
+  if (accessInvalidationEnabled) {
+    systemConsumers.push(createAccessInvalidationEventConsumer(sseBroker));
+  }
 
   // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
   // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but
@@ -553,6 +595,10 @@ export function buildServer(options: ServerOptions): KumikoServer {
     }),
   );
 
+  // Tripwire: a kumiko-pii: ciphertext in a JSON response is always a bug
+  // (raw read leaked past a decrypt) — dev fails loud, prod redacts (#820).
+  app.use("/api/*", piiCiphertextResponseGuard());
+
   // Auth middleware skips public paths (login, health) — those routes need
   // to be callable without a valid JWT. Every other /api/* request requires
   // a token (or, when anonymousAccess is wired, falls through as anonymous).
@@ -560,7 +606,10 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // middleware can reject revoked sids on every request.
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
-    ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
+    ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
+    ...(options.auth?.resolveTenantLifecycleStatus
+      ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
+      : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {
@@ -568,6 +617,33 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return jwtGuard(c, next);
   });
 
+  // PAT rate limiting — runs AFTER the auth guard so the resolved principal is
+  // available. Only PAT-authenticated requests are counted (keyed by token id);
+  // cookie/JWT users pass through untouched. In-memory limiter is per-instance
+  // (see run-prod-app) — a multi-node deployment wanting a shared counter swaps
+  // in a Redis-backed LoginRateLimiter.
+  const patRateLimiter = options.auth?.patRateLimiter;
+  if (patRateLimiter) {
+    app.use("/api/*", async (c, next) => {
+      if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+      const pat = getUser(c)?.pat;
+      if (pat && !(await patRateLimiter.check(pat.tokenId))) {
+        return c.json(
+          {
+            error: {
+              code: "pat_rate_limited",
+              httpStatus: 429,
+              message: "personal access token rate limit exceeded",
+              i18nKey: "auth.errors.patRateLimited",
+            },
+          },
+          429,
+        );
+      }
+      return next();
+    });
+  }
+
   // Origin-allowlist guard — additional CSRF-hardening for deployments that
   // widen the auth cookie across subdomains (auth.cookieDomain). Registered
   // only when allowedOrigins is non-empty, with the same /api/* + public-skip
@@ -634,12 +710,32 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // /api/* immer Vorrang hat — feature-Routes liegen ohnehin außerhalb
   // (Boot-Validator blockt /api-Prefix). deps.app ist die Outer-App, sodass
   // der Handler /api/query intern via app.fetch(...) nutzen kann (gleicher
-  // Auth-Pfad wie ein echter HTTP-Call).
+  // Auth-Pfad wie ein echter HTTP-Call). deps.systemQuery umgeht diesen
+  // Pfad bewusst — für Routes die einen FESTEN Tenant erzwingen müssen
+  // (z.B. legal-pages → immer SYSTEM_TENANT_ID), statt ihn per X-Tenant-
+  // Header vorzutäuschen (das sieht für die anonymousAccess-Auflösung
+  // wie ein normaler Client-Header aus und wird von resolverTrust:
+  // "authoritative"-Configs zurecht als Tenant-Override abgelehnt).
   for (const feature of options.registry.features.values()) {
     for (const route of Object.values(feature.httpRoutes)) {
       // @wrapper-known semantic-alias
       const honoHandler = async (c: import("hono").Context): Promise<Response> =>
-        route.handler(c, { app });
+        route.handler(c, {
+          app,
+          systemQuery: (type, payload, tenantId) =>
+            // createAnonymousUser, NOT createSystemUser: httpRoute handlers
+            // using systemQuery are, by construction, `anonymous: true`
+            // public routes — the synthesized user must clear the SAME
+            // access gate a real anonymous visitor would, no more. The
+            // system role would ALSO satisfy that gate here, but it can
+            // read fields gated to "system" that "anonymous" can't
+            // (filterReadFields is a plain role-in-map check) — a future
+            // systemQuery caller reading a system-gated field would leak
+            // it into a public response. The forced tenant already comes
+            // from bypassing the HTTP layer entirely; no elevated role
+            // is needed or wanted on top of that.
+            dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+        });
       switch (route.method) {
         case "GET":
           app.get(route.path, honoHandler);

package/src/api/sse-broker.ts

@@ -1,3 +1,4 @@
+import { userAccessChannel } from "../engine/constants";
 import { generateId } from "../utils";
 
 export type SseClient = {
@@ -17,10 +18,18 @@ export type SseBroker = {
   pushToChannel(channel: string, event: SseEvent): void;
   getClientCount(channel: string): number;
   getTotalClientCount(): number;
+  // Internal (non-SSE-client) subscription, e.g. dispatch-stream watching
+  // for mid-stream access revocation. Kept separate from addClient/
+  // pushToChannel: those count towards getClientCount/getTotalClientCount
+  // (real SSE connections) and their send/close shape doesn't fit a plain
+  // callback listener. Returns an unsubscribe function.
+  subscribeAccessInvalidation(userId: string, onInvalidate: () => void): () => void;
+  publishAccessInvalidation(userId: string): void;
 };
 
 export function createSseBroker(): SseBroker {
   const channels = new Map<string, Map<string, SseClient>>();
+  const accessInvalidationListeners = new Map<string, Map<string, () => void>>();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {
     let clients = channels.get(channel);
@@ -67,5 +76,35 @@ export function createSseBroker(): SseBroker {
       }
       return total;
     },
+
+    subscribeAccessInvalidation(userId, onInvalidate) {
+      const channel = userAccessChannel(userId);
+      const listenerId = generateId();
+      let listeners = accessInvalidationListeners.get(channel);
+      if (!listeners) {
+        listeners = new Map();
+        accessInvalidationListeners.set(channel, listeners);
+      }
+      listeners.set(listenerId, onInvalidate);
+      return () => {
+        const current = accessInvalidationListeners.get(channel);
+        // skip: already unsubscribed (e.g. stream ended after a publish already fired)
+        if (!current) return;
+        current.delete(listenerId);
+        if (current.size === 0) accessInvalidationListeners.delete(channel);
+      };
+    },
+
+    publishAccessInvalidation(userId) {
+      const channel = userAccessChannel(userId);
+      const listeners = accessInvalidationListeners.get(channel);
+      // skip: no live stream is watching this user right now
+      if (!listeners) return;
+      // Snapshot before iterating — a fired listener unsubscribes itself,
+      // which would mutate `listeners` mid-iteration otherwise.
+      for (const onInvalidate of [...listeners.values()]) {
+        onInvalidate();
+      }
+    },
   };
 }

package/src/bun-db/__tests__/PATTERN.md

@@ -8,7 +8,6 @@ db/postgres-provider.ts      postgres-js Factory (default, stabil)
 db/bun-provider.ts           Bun.SQL Factory (DB_PROVIDER=bun, experimentell)
 stack/db.ts                  createTestDb() — provider-agnostisch via createConnection
 stack/test-stack.ts          setupTestStack() — provider-agnostisch via createTestDb
-bun-db/__tests__/bun-test-stack.ts  Alias: setupBunTestStack → setupTestStack
 bun-db/__tests__/bun-test-db.ts     Alias: createBunTestDb → createTestDb
 ```
 

package/src/bun-db/__tests__/coerce-row-temporal.test.ts

@@ -0,0 +1,41 @@
+// kumiko-framework#1480: instantFromDriver referenced the global `Temporal`
+// without importing it. Bun doesn't expose Temporal as a globalThis property
+// reliably — any storeTable read of a timestamptz column crashed with
+// "Temporal is not defined" unless some other boot path happened to install
+// the polyfill globally first (order-dependent, easy to miss in a fresh
+// process). The fix is a static `import { Temporal } from "temporal-polyfill"`
+// in query.ts, so this test deletes globalThis.Temporal before calling
+// coerceRow — proving the coercion no longer depends on the global at all.
+
+import { describe, expect, test } from "bun:test";
+import { Temporal } from "temporal-polyfill";
+import { coerceRow, type TableInfo } from "../query";
+
+function timestamptzTableInfo(): TableInfo {
+  return {
+    name: "probe",
+    columnOf: (f) => f,
+    pgTypeOf: (c) => (c === "updated_at" ? "timestamptz" : undefined),
+    bigintJsModeOf: () => undefined,
+    fieldOf: (c) => c,
+    hasColumn: () => true,
+  };
+}
+
+describe("coerceRow — timestamptz → Temporal.Instant", () => {
+  test("coerces without relying on a global Temporal", () => {
+    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+    delete (globalThis as { Temporal?: unknown }).Temporal;
+    try {
+      const row = { updated_at: new Date("2026-04-18T10:00:00Z") };
+      const result = coerceRow(row, timestamptzTableInfo());
+      expect(result.updated_at).toBeInstanceOf(Temporal.Instant);
+      expect((result.updated_at as unknown as Temporal.Instant).toString()).toBe(
+        "2026-04-18T10:00:00Z",
+      );
+    } finally {
+      if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
+      else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
+    }
+  });
+});

package/src/bun-db/__tests__/select-many-retry.test.ts

@@ -0,0 +1,79 @@
+// #1163: Bun.SQL can hand out a closed connection under load (AbortError
+// "The connection was closed."). Pure reads retry exactly once on a fresh
+// pool checkout; tx handles, non-matching errors, and genuine user aborts
+// must NOT retry.
+
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "../../db/table-builder";
+import { selectMany } from "../query";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin?: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[], opts: { tx?: boolean } = {}): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [{ id: "r1", title: "ok", tenant_id: "t1", inserted_at: null, updated_at: null }];
+    },
+  };
+  // A top-level pool client has begin(); a transaction handle does not.
+  if (!opts.tx)
+    client.begin = () => {
+      throw new Error("not used in test");
+    };
+  return client;
+}
+
+const table = buildEntityTable("note", {
+  fields: { title: { type: "text", required: true } },
+});
+
+describe("selectMany — closed-connection retry (#1163)", () => {
+  test("retries once on AbortError 'connection was closed' and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()]);
+    const rows = await selectMany(db, table);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.title).toBe("ok");
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()]);
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(2);
+  });
+
+  test("never retries on a transaction handle (no begin)", async () => {
+    const db = fakeClient([closedConnectionError()], { tx: true });
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry a genuine user abort (different message)", async () => {
+    const userAbort = Object.assign(new Error("The operation was aborted."), {
+      name: "AbortError",
+    });
+    const db = fakeClient([userAbort]);
+    await expect(selectMany(db, table)).rejects.toThrow("operation was aborted");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry generic query errors", async () => {
+    const syntax = Object.assign(new Error("syntax error at or near"), { name: "PostgresError" });
+    const db = fakeClient([syntax]);
+    await expect(selectMany(db, table)).rejects.toThrow("syntax error");
+    expect(db.calls).toBe(1);
+  });
+});

package/src/bun-db/__tests__/write-brand.test.ts

@@ -8,6 +8,7 @@
 import { expect, test } from "bun:test";
 import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { buildEntityTable } from "../../db/table-builder";
+import type { TenantDb } from "../../db/tenant-db";
 import { createEntity, createTextField } from "../../engine";
 import { type AnyDb, deleteMany, insertOne, selectMany, updateMany } from "../query";
 
@@ -41,8 +42,28 @@ async function _readAllowsManagedEntity(db: AnyDb): Promise<void> {
   await selectMany(db, brandedEntity, { id: "1" });
 }
 
+// Method-form (ctx.db.insertOne/updateMany/deleteMany) rejects the brand too — a
+// projection written past its event stream is wiped on rebuild whether the write
+// went through the free function or the TenantDb method.
+async function _methodFormRejectsManagedEntity(db: TenantDb): Promise<void> {
+  // @ts-expect-error — managed EntityTable is executor-only; method-form insert is a compile error.
+  await db.insertOne(brandedEntity, { title: "x" });
+  // @ts-expect-error — method-form update on a managed EntityTable is rejected.
+  await db.updateMany(brandedEntity, { title: "y" }, { id: "1" });
+  // @ts-expect-error — method-form delete on a managed EntityTable is rejected.
+  await db.deleteMany(brandedEntity, { id: "1" });
+}
+
+async function _methodFormReadAllowsManagedEntity(db: TenantDb): Promise<void> {
+  // Method-form reads on a managed EntityTable stay fine (reads keep the plain param).
+  await db.selectMany(brandedEntity, { id: "1" });
+  await db.fetchOne(brandedEntity, { id: "1" });
+}
+
 test("ES-write brand: compile-time contracts are wired", () => {
   expect(_writeRejectsManagedEntity).toBeDefined();
   expect(_writeAllowsUnmanagedTable).toBeDefined();
   expect(_readAllowsManagedEntity).toBeDefined();
+  expect(_methodFormRejectsManagedEntity).toBeDefined();
+  expect(_methodFormReadAllowsManagedEntity).toBeDefined();
 });

package/src/bun-db/connection.ts

@@ -6,9 +6,12 @@
 // event-dispatcher.ts. Bun.sql 1.2.20 hat kein listen() (PR oven-sh/bun#25511
 // pending). Nach Landung des Bun-LISTEN-Supports: peer raus.
 
+import type { PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
 
+export type { PgListenClient };
+
 // Bun.SQL ist callable als tagged template `sql\`...\`` PLUS hat methods
 // (.begin / .unsafe / .end / .file / .reserve etc.). DbConnection-Type
 // reflektiert die Instance-Shape.
@@ -21,9 +24,6 @@ export type BunDbTx = BunDbConnection;
 // Beide austauschbar im normalen call-path.
 export type BunDbRunner = BunDbConnection | BunDbTx;
 
-// Postgres-js peer NUR für event-dispatcher LISTEN.
-export type PgListenClient = ReturnType<typeof postgres>;
-
 export type BunDbConnectionOptions = {
   readonly maxConnections?: number;
   readonly idleTimeoutSeconds?: number;

package/src/bun-db/index.ts

@@ -11,6 +11,7 @@ export type {
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection";
 export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query";
 export {
+  asEntityTableMeta,
   asRawClient,
   countWhere,
   type DeleteManyBatchedOptions,
@@ -23,6 +24,7 @@ export {
   incrementCounter,
   insertMany,
   insertOne,
+  runInSavepoint,
   selectMany,
   transaction,
   type UpsertOnConflictOptions,