@cosmicdrift/kumiko-framework 0.163.2 → 0.163.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.163.2",
+  "version": "0.163.3",
   "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.163.3",
     "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.163.3",
     "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/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/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;