@cosmicdrift/kumiko-framework 0.163.1 → 0.163.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.163.1",
+  "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.1",
+    "@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.1",
+    "@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/__tests__/replay-migration-sql.test.ts

@@ -72,6 +72,54 @@ CREATE INDEX IF NOT EXISTS "read_accounts_tenant_id_idx" ON "read_accounts" ("te
     }
   });
 
+  // Regression: publicstatus#0007_fix-secrets-table-columns adds three
+  // columns in ONE statement (comma-separated ADD COLUMN clauses) — the
+  // replay used to only pick up the first, reporting "metadata" and
+  // "last_rotated_at" as missing even though the migration creates them.
+  test("multiple ADD COLUMN clauses in a single ALTER TABLE statement all extend the table", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(
+        dir,
+        "0002_add-cols.sql",
+        `ALTER TABLE "read_a"
+  ADD COLUMN IF NOT EXISTS "envelope" jsonb NOT NULL,
+  ADD COLUMN IF NOT EXISTS "metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
+  ADD COLUMN IF NOT EXISTS "last_rotated_at" timestamp with time zone DEFAULT now() NOT NULL;`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual([
+        "envelope",
+        "id",
+        "last_rotated_at",
+        "metadata",
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("mixed ADD + DROP COLUMN clauses in one statement apply in order", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "legacy" text);`,
+      );
+      write(
+        dir,
+        "0002_migrate-cols.sql",
+        `ALTER TABLE "read_a" DROP COLUMN IF EXISTS "legacy", ADD COLUMN IF NOT EXISTS "title" text;`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("DROP COLUMN IF EXISTS (hand-edited) still removes the column", () => {
     const dir = tmpMigrationsDir();
     try {

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/replay-migration-sql.ts

@@ -54,37 +54,40 @@ function applyStatement(schema: Map<string, { columns: Set<string> }>, statement
   const create = statement.match(
     /^CREATE TABLE\s+(?:IF NOT EXISTS\s+)?"([^"]+)"\s*\(([\s\S]*)\);?\s*$/i,
   );
-  const createTableName = create?.[1];
-  const createBody = create?.[2];
-
-  const addColumn = statement.match(
-    /^ALTER TABLE\s+"([^"]+)"\s+ADD COLUMN\s+(?:IF NOT EXISTS\s+)?"([^"]+)"/i,
-  );
-  const addColumnTable = addColumn?.[1];
-  const addColumnName = addColumn?.[2];
+  if (create?.[1] !== undefined && create[2] !== undefined) {
+    schema.set(create[1], { columns: parseColumnNames(create[2]) });
+    // skip: CREATE TABLE fully handled above, no other clause can also match
+    return;
+  }
 
   const dropTable = statement.match(/^DROP TABLE\s+(?:IF EXISTS\s+)?"([^"]+)"/i);
-  const dropTableName = dropTable?.[1];
-
-  const dropColumn = statement.match(
-    /^ALTER TABLE\s+"([^"]+)"\s+DROP COLUMN\s+(?:IF EXISTS\s+)?"([^"]+)"/i,
-  );
-  const dropColumnTable = dropColumn?.[1];
-  const dropColumnName = dropColumn?.[2];
+  if (dropTable?.[1] !== undefined) {
+    schema.delete(dropTable[1]);
+    // skip: DROP TABLE fully handled above, no other clause can also match
+    return;
+  }
 
-  if (createTableName !== undefined && createBody !== undefined) {
-    schema.set(createTableName, { columns: parseColumnNames(createBody) });
-  } else if (addColumnTable !== undefined && addColumnName !== undefined) {
-    const table = schema.get(addColumnTable);
-    if (table) table.columns.add(addColumnName);
-    else schema.set(addColumnTable, { columns: new Set([addColumnName]) });
-  } else if (dropTableName !== undefined) {
-    schema.delete(dropTableName);
-  } else if (dropColumnTable !== undefined && dropColumnName !== undefined) {
-    schema.get(dropColumnTable)?.columns.delete(dropColumnName);
+  // A single ALTER TABLE statement can carry multiple comma-separated
+  // ADD/DROP COLUMN clauses (e.g. migration 0007_fix-secrets-table-columns'
+  // three-column fix in one statement) — matchAll over the whole body
+  // instead of matching only the first clause, in statement order so an
+  // add-then-drop of the same column (unusual, but not impossible) resolves
+  // correctly.
+  const alterTable = statement.match(/^ALTER TABLE\s+"([^"]+)"\s+([\s\S]*?);?\s*$/i);
+  const alterTableName = alterTable?.[1];
+  const alterBody = alterTable?.[2];
+  if (alterTableName !== undefined && alterBody !== undefined) {
+    const table = schema.get(alterTableName) ?? { columns: new Set<string>() };
+    schema.set(alterTableName, table);
+    const clauseRe = /(ADD|DROP)\s+COLUMN\s+(?:IF (?:NOT )?EXISTS\s+)?"([^"]+)"/gi;
+    for (const [, verb, name] of alterBody.matchAll(clauseRe)) {
+      if (verb === undefined || name === undefined) continue;
+      if (verb.toUpperCase() === "ADD") table.columns.add(name);
+      else table.columns.delete(name);
+    }
   }
-  // else: CREATE INDEX, ALTER COLUMN (TYPE/DEFAULT/NOT NULL) and everything
-  // else don't change the table/column shape this replay tracks.
+  // else: CREATE INDEX and everything else don't change the table/column
+  // shape this replay tracks.
 }
 
 // Reads `<migrationsDir>/*.sql` in sequence order and replays every

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;