@cosmicdrift/kumiko-framework 0.163.2 → 0.164.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.163.2",
+  "version": "0.164.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.163.2",
+    "@cosmicdrift/kumiko-types": "0.164.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.163.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.164.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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/query.ts

@@ -24,6 +24,9 @@ import type {
   WhereObject,
   WhereOperator,
 } from "@cosmicdrift/kumiko-types/where-clause-types";
+// Static import, not the ambient global: Bun doesn't expose Temporal on
+// globalThis, so instantFromDriver crashed on timestamptz reads (#1480).
+import { Temporal } from "temporal-polyfill";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";

package/src/db/__tests__/dialect-instant.test.ts

@@ -11,11 +11,8 @@
 // die invalid-Probe (echte Garbage muss weiterhin throwen — kein silent
 // swallowing).
 
-import { ensureTemporalPolyfill } from "../../time/polyfill";
-
-await ensureTemporalPolyfill();
-
 import { describe, expect, test } from "bun:test";
+import { Temporal } from "temporal-polyfill";
 import { instantToDriver as toDriver } from "../dialect";
 
 describe("instant() customType — toDriver", () => {

package/src/db/__tests__/instant-to-driver-temporal.test.ts

@@ -0,0 +1,21 @@
+// kumiko-framework#1480 twin bug: instantToDriver referenced the global
+// `Temporal` the same way instantFromDriver in bun-db/query.ts did. Fixed
+// the same way — static `import { Temporal } from "temporal-polyfill"` in
+// dialect.ts. This test deletes globalThis.Temporal before calling it,
+// proving the write path no longer depends on the global either.
+
+import { describe, expect, test } from "bun:test";
+import { instantToDriver } from "../dialect";
+
+describe("instantToDriver — without a global Temporal", () => {
+  test("coerces an ISO string without relying on a global Temporal", () => {
+    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+    delete (globalThis as { Temporal?: unknown }).Temporal;
+    try {
+      expect(instantToDriver("2026-04-18T10:00:00Z")).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/db/dialect.ts

@@ -12,6 +12,9 @@
 //
 // The framework no longer imports drizzle-orm at runtime — schema-files
 // use only this module.
+//
+// Static import, not the ambient global: Bun doesn't expose Temporal on
+// globalThis, so instantToDriver crashed on timestamptz writes (#1480).
 
 import {
   type ColumnHandle,
@@ -19,6 +22,7 @@ import {
   KUMIKO_NAME_SYMBOL,
   type SchemaTable,
 } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { Temporal } from "temporal-polyfill";
 import type {
   ColumnMeta,
   CompositePrimaryKeyMeta,

package/src/db/pg-error.ts

@@ -3,7 +3,7 @@
 // unwrap both layers so callers don't have to know which layer produced the
 // error. Used by the event-store to distinguish a unique-violation on the
 // aggregate-version index (optimistic-concurrency conflict) from the one on
-// the request-id idempotency index (replay signal).
+// the idempotency-key index (caller-side replay signal).
 
 export type PgErrorInfo = {
   readonly code: string | undefined;

package/src/db/queries/event-store.ts

@@ -6,6 +6,20 @@ export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void>
   await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
 }
 
+// Tenant-scoped partial unique index over metadata.idempotencyKey.
+// Expression index straight on the jsonb column — no dedicated key column,
+// so it needs no INSERT-path change and covers admin-api's raw appends too
+// (same metadata jsonb). CREATE ... IF NOT EXISTS makes this safe to call
+// on every boot, same "ensure" pattern as ensureSnapshotVersionColumn: heals
+// installs that predate the index without a table rebuild.
+export async function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "events_idempotency_uq" ON "kumiko_events" ` +
+      `("tenant_id", (("metadata"->>'idempotencyKey'))) ` +
+      `WHERE "metadata"->>'idempotencyKey' IS NOT NULL`,
+  );
+}
+
 export type SubsequentEventInsertParams = {
   readonly aggregateId: string;
   readonly aggregateType: string;

package/src/engine/extensions/user-data.ts

@@ -145,11 +145,19 @@ export type UserDataExportHook = (ctx: UserDataHookCtx) => Promise<UserDataExpor
  *
  * Idempotent — wenn der Job zweimal läuft (Crash-Recovery), darf der
  * Hook nicht crashen.
+ *
+ * Return additive to `void`: a hook can return `{status:"ok"}` or
+ * `{status:"incomplete", reason}` to signal a partial success to the
+ * cleanup runner (e.g. an external provider call failed) without
+ * throwing/rolling back the sub-transaction. Existing `void` returners
+ * stay valid unchanged.
  */
 export type UserDataDeleteHook = (
   ctx: UserDataHookCtx,
   strategy: UserDataDeleteStrategy,
-) => Promise<void>;
+) => Promise<
+  undefined | { readonly status: "ok" } | { readonly status: "incomplete"; readonly reason: string }
+>;
 
 /**
  * Komplette Hook-Tafel für EXT_USER_DATA. Sprint 2 user-data-rights

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

@@ -6,6 +6,7 @@ import { generateId as uuid } from "../../utils";
 import {
   append,
   createEventsTable,
+  IdempotentAppendConflictError,
   loadAggregate,
   loadAggregateAsOf,
   loadAllEventsByType,
@@ -93,6 +94,129 @@ describe("event-store: append + load", () => {
   });
 });
 
+describe("event-store: idempotency-key conflict", () => {
+  test("second append with a reused idempotencyKey (new aggregate+version) throws IdempotentAppendConflictError", async () => {
+    const first = uuid();
+    const second = uuid();
+    const key = uuid();
+
+    await append(testDb.db, {
+      aggregateId: first,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Orig" },
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    // A retried command that re-runs after the Redis idempotency guard
+    // missed its window: different aggregate, fresh expectedVersion=0 — the
+    // aggregate-version unique index has nothing to say about this pair, so
+    // only the idempotency-key index catches the duplicate.
+    await expect(
+      append(testDb.db, {
+        aggregateId: second,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { title: "Retry" },
+        metadata: { userId: userA, idempotencyKey: key },
+      }),
+    ).rejects.toThrow(IdempotentAppendConflictError);
+
+    const events = await loadAggregate(testDb.db, second, tenantA);
+    expect(events).toHaveLength(0);
+  });
+
+  test("subsequent-event append (expectedVersion > 0) also enforces the idempotency key", async () => {
+    const aggregateId = uuid();
+    const key = uuid();
+
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Orig" },
+      metadata: { userId: userA },
+    });
+
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 1,
+      type: "task.updated",
+      payload: { title: "V2" },
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    // Retry of the v2 update: goes through insertSubsequentEventRow's raw
+    // INSERT ... SELECT ... WHERE EXISTS path, not insertFirstEvent — the
+    // idempotency index must catch it there too.
+    await expect(
+      append(testDb.db, {
+        aggregateId,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 2,
+        type: "task.updated",
+        payload: { title: "V3-retry" },
+        metadata: { userId: userA, idempotencyKey: key },
+      }),
+    ).rejects.toThrow(IdempotentAppendConflictError);
+
+    const events = await loadAggregate(testDb.db, aggregateId, tenantA);
+    expect(events).toHaveLength(2);
+  });
+
+  test("same idempotencyKey on a different tenant does not conflict", async () => {
+    const key = uuid();
+
+    const a = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+    const b = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantB,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    expect(a.version).toBe(1);
+    expect(b.version).toBe(1);
+  });
+
+  test("omitting idempotencyKey allows unlimited appends, unchanged from before", async () => {
+    const events = await Promise.all(
+      Array.from({ length: 3 }, () =>
+        append(testDb.db, {
+          aggregateId: uuid(),
+          aggregateType: "task",
+          tenantId: tenantA,
+          expectedVersion: 0,
+          type: "task.created",
+          payload: {},
+          metadata: { userId: userA },
+        }),
+      ),
+    );
+    expect(events).toHaveLength(3);
+  });
+});
+
 describe("event-store: optimistic concurrency", () => {
   test("wrong expectedVersion throws VersionConflictError (no write)", async () => {
     const aggregateId = uuid();

package/src/event-store/event-store.ts

@@ -1,7 +1,7 @@
 import type { EventMetadata, StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
 import { encryptEventPayloadPii } from "../crypto/event-pii";
 import type { DbRunner } from "../db";
-import { isUniqueViolation } from "../db/pg-error";
+import { constraintOf, isUniqueViolation } from "../db/pg-error";
 import {
   insertSubsequentEventRow,
   notifyPgChannel,
@@ -13,7 +13,7 @@ import {
 import { insertOne, selectMany } from "../db/query";
 import type { TenantId } from "../engine/types";
 import { isStreamArchived } from "./archive";
-import { VersionConflictError } from "./errors";
+import { IdempotentAppendConflictError, VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
 import { toStoredEvent } from "./row-to-stored-event";
 
@@ -91,10 +91,15 @@ export async function append(db: DbRunner, event: EventToAppend): Promise<Stored
     return buildStoredEvent(toStore, newVersion, eventVersion, row);
   } catch (e) {
     if (isUniqueViolation(e)) {
-      // Only constraint left on the events table: events_aggregate_version_uq
-      // on (tenant_id, aggregate_id, version). A unique violation here always
-      // means a concurrent writer in the same tenant won the race to the
-      // next version — retry-able conflict.
+      // Two unique constraints on this table: events_aggregate_version_uq
+      // (tenant_id, aggregate_id, version) — a concurrent writer won the
+      // race to the next version — and events_idempotency_uq (tenant_id,
+      // metadata->>'idempotencyKey') — the caller reused an idempotency key.
+      // constraintOf() tells them apart; unknown/renamed constraint falls
+      // back to VersionConflictError, the pre-existing behaviour.
+      if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {
+        throw new IdempotentAppendConflictError(event.tenantId, event.metadata.idempotencyKey);
+      }
       throw new VersionConflictError(event.aggregateId, event.expectedVersion);
     }
     throw e;

package/src/event-store/events-schema.ts

@@ -12,6 +12,7 @@ import {
   uniqueIndex,
   uuid,
 } from "../db/dialect";
+import { ensureIdempotencyKeyIndex } from "../db/queries/event-store";
 import { unsafePushTables } from "../stack";
 import { createArchivedStreamsTable } from "./archive";
 import { createSnapshotsTable } from "./snapshot";
@@ -22,9 +23,11 @@ import type { EventMetadata } from "./types";
 // INSERT ... SELECT ... WHERE EXISTS isn't ergonomic in the typed builder.
 //
 // HTTP-level retry idempotency is handled by pipeline/idempotency.ts
-// (Redis-backed check + cached-response replay). The event-store itself
-// imposes no idempotency index — a single HTTP request may write N events
-// freely, metadata.requestId is purely a trace marker.
+// (Redis-backed check + cached-response replay); metadata.requestId is
+// purely a trace marker (no uniqueness constraint — one request may write
+// N events). Callers that need a hard per-event guarantee as a second line
+// of defense set metadata.idempotencyKey, enforced by the tenant-scoped
+// partial unique index ensureIdempotencyKeyIndex() creates below.
 
 export const eventsTable = pgTable(
   "kumiko_events",
@@ -77,6 +80,10 @@ export async function createEventsTable(db: DbConnection): Promise<void> {
   if (!(await tableExists(db, "public.kumiko_events"))) {
     await unsafePushTables(db, { kumikoEvents: eventsTable });
   }
+  // Runs unconditionally (both fresh + already-existing table) so installs
+  // that predate the idempotency-key index get healed the same way
+  // ensureSnapshotVersionColumn heals kumiko_snapshots.
+  await ensureIdempotencyKeyIndex(db);
   await createArchivedStreamsTable(db);
   await createSnapshotsTable(db);
 }

package/src/event-store/index.ts

@@ -12,7 +12,7 @@ export {
   isStreamArchived,
   restoreStream,
 } from "./archive";
-export { ArchivedStreamError, VersionConflictError } from "./errors";
+export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError } from "./errors";
 export {
   append,
   EVENTS_PUBSUB_CHANNEL,

package/src/files/__tests__/files.integration.test.ts

@@ -593,6 +593,30 @@ describe("error handling", () => {
     expect(body.error).toContain("invalid_file_type");
   });
 
+  test("upload with path-traversal entityType is rejected before it reaches storage", async () => {
+    const pngContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const res = await uploadFile(adminUser, "logo.png", pngContent, "image/png", {
+      entityType: "../../tenantB",
+      entityId: "1",
+      fieldName: "logo",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("invalid_entityType");
+  });
+
+  test("upload with path-traversal fieldName is rejected before it reaches storage", async () => {
+    const pngContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const res = await uploadFile(adminUser, "logo.png", pngContent, "image/png", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "../../escape",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("invalid_fieldName");
+  });
+
   test("upload without auth returns 401", async () => {
     const formData = new FormData();
     formData.append("file", new File([new Uint8Array(10)], "test.png", { type: "image/png" }));

package/src/files/__tests__/write-stream.test.ts

@@ -147,6 +147,19 @@ describe("FileStorageProvider.writeStream — local-filesystem", () => {
     const data = await provider.read("k");
     expect(Array.from(data)).toEqual([2, 2, 2]);
   });
+
+  test("write/read/delete reject a key that escapes basePath; exists reports false", async () => {
+    const provider = createLocalProvider(basePath);
+    const escapingKey = "../../etc/passwd";
+
+    await expect(provider.write(escapingKey, new Uint8Array([1]))).rejects.toThrow(
+      /escapes basePath/,
+    );
+    await expect(provider.read(escapingKey)).rejects.toThrow(/escapes basePath/);
+    await expect(provider.delete(escapingKey)).rejects.toThrow(/escapes basePath/);
+    // exists() treats any stat failure (missing file, escaping key) as "not there".
+    expect(await provider.exists(escapingKey)).toBe(false);
+  });
 });
 
 describe("FileStorageProvider.writeStream — Streaming-Property", () => {

package/src/files/file-routes.ts

@@ -112,6 +112,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     const entityId = typeof body["entityId"] === "string" ? body["entityId"] : undefined;
     const fieldName = typeof body["fieldName"] === "string" ? body["fieldName"] : undefined;
 
+    // These interpolate directly into the storage key (buildStorageKey below) —
+    // reject anything but a safe identifier so a client can't path-traverse
+    // out of its tenant's storage prefix (../.. segments, absolute paths).
+    for (const [field, value] of [
+      ["entityType", entityType],
+      ["entityId", entityId],
+      ["fieldName", fieldName],
+    ] as const) {
+      if (value !== undefined && !/^[A-Za-z0-9_-]+$/.test(value)) {
+        return c.json({ error: `invalid_${field}: must match /^[A-Za-z0-9_-]+$/` }, 400);
+      }
+    }
+
     // Validate against entity field definition if available.
     let maxSize = options.maxUploadSize ?? "10mb";
     let accept: readonly string[] | undefined;

package/src/files/local-provider.ts

@@ -1,6 +1,6 @@
 import { createReadStream, createWriteStream } from "node:fs";
 import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import type { FileStorageProvider } from "./types";
 
@@ -8,9 +8,23 @@ import type { FileStorageProvider } from "./types";
 // pick an object-store provider (S3/R2/…). mimeType is ignored here; the
 // filesystem tracks no metadata beyond what the caller stores on FileRef.
 export function createLocalProvider(basePath: string): FileStorageProvider {
+  const resolvedBase = resolve(basePath);
+
+  // Callers are expected to only ever pass keys built by buildStorageKey(),
+  // but the storage layer shouldn't rely solely on that — this resolves the
+  // real path and rejects anything that escapes basePath (e.g. a `..`
+  // segment that slipped past an upstream check), regardless of the key's
+  // source.
+  function resolveContainedPath(key: string): string {
+    const filePath = resolve(join(basePath, key));
+    if (filePath !== resolvedBase && !filePath.startsWith(resolvedBase + sep)) {
+      throw new Error(`storage key escapes basePath: "${key}"`);
+    }
+    return filePath;
+  }
   return {
     async write(key: string, data: Uint8Array, _mimeType?: string): Promise<void> {
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       await mkdir(dirname(filePath), { recursive: true });
       await writeFile(filePath, data);
     },
@@ -26,7 +40,7 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
       // Hygiene; ein periodischer cron-cleanup auf alten `.tmp`-Files
       // ist die saubere Loesung wenn das in Production realistisch
       // greift.
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
       await mkdir(dirname(filePath), { recursive: true });
       try {
@@ -41,7 +55,7 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
     },
 
     async read(key: string): Promise<Uint8Array> {
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       return readFile(filePath);
     },
 
@@ -55,7 +69,7 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
       // (z.B. ENOENT bei Missing-File faellt erst beim ersten chunk-
       // pull, nicht beim readStream-Aufruf — gleiches Lazy-Verhalten
       // wie inmemory + S3).
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       const stream = createReadStream(filePath);
       return {
         async *[Symbol.asyncIterator]() {
@@ -76,13 +90,13 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
     },
 
     async delete(key: string): Promise<void> {
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       await rm(filePath, { force: true });
     },
 
     async exists(key: string): Promise<boolean> {
       try {
-        await stat(join(basePath, key));
+        await stat(resolveContainedPath(key));
         return true;
       } catch {
         return false;