@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/event-store/rebuild-dead-letter.ts

@@ -0,0 +1,111 @@
+// Dead-letter storage for apply-handler failures during projection rebuild.
+//
+// Background: rebuildProjection / rebuildMultiStreamProjection replay the
+// event log through apply handlers inside ONE transaction. A single event
+// whose (possibly years-old) payload makes its apply throw rolls the whole
+// replay back — the projection stays permanently un-rebuildable until the
+// event is repaired by hand. The upcaster dead-letter only quarantines
+// upcast-TRANSFORM failures, not apply failures (#760).
+//
+// Quarantine mode (errorPolicy.skipApplyErrors on RebuildDeps, or
+// MspErrorMode.rebuild.skipApplyErrors on the MSP definition) confines each
+// apply to a savepoint: a throwing apply is rolled back, captured into
+// `kumiko_rebuild_dead_letters`, and the replay continues. Replay-after-fix
+// is a separate ops step — same stance as the upcaster dead-letter.
+
+import type { DbConnection, DbRunner } from "../db/connection";
+import { bigint, index, jsonb, table as pgTable, text, timestamp, uuid } from "../db/dialect";
+import { tableExists } from "../db/schema-inspection";
+import { unsafePushTables } from "../stack";
+import type { StoredEvent } from "./event-store";
+
+export const rebuildDeadLetterTable = pgTable(
+  "kumiko_rebuild_dead_letters",
+  {
+    // Surrogate PK — the same event can land here across multiple rebuild
+    // attempts before the fix ships, without unique-violation noise.
+    id: bigint("id", { mode: "bigint" }).primaryKey().generatedAlwaysAsIdentity(),
+    projectionName: text("projection_name").notNull(),
+    // StoredEvent.id is surfaced as `string` (bigint serialised for JSON
+    // safety) — stored as text to keep the round-trip identity.
+    eventId: text("event_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    aggregateId: text("aggregate_id").notNull(),
+    aggregateType: text("aggregate_type").notNull(),
+    eventType: text("event_type").notNull(),
+    errorMessage: text("error_message").notNull(),
+    payload: jsonb("payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    projectionIdx: index("rebuild_dead_letters_projection_idx").on(t.projectionName),
+    createdAtIdx: index("rebuild_dead_letters_created_at_idx").on(t.createdAt),
+  }),
+);
+
+// Idempotent table-create. The rebuild runners call this before the rebuild
+// tx whenever quarantine mode is active, so the opt-in works on databases
+// provisioned before this table existed.
+export async function createRebuildDeadLetterTable(db: DbConnection): Promise<void> {
+  // skip: table already exists — bootstrap called from multiple paths
+  if (await tableExists(db, "public.kumiko_rebuild_dead_letters")) return;
+  await unsafePushTables(db, { kumikoRebuildDeadLetters: rebuildDeadLetterTable });
+}
+
+export type SkippedApply = {
+  readonly event: StoredEvent;
+  readonly error: unknown;
+};
+
+// Bulk-write, called ONCE at the end of a quarantining rebuild (inside its
+// tx). Unqualified insert — during the rebuild the search_path points at the
+// shadow schema, and this table exists only in public, so it falls through.
+export async function recordRebuildDeadLetters(
+  db: DbRunner,
+  projectionName: string,
+  skipped: readonly SkippedApply[],
+): Promise<void> {
+  const { insertMany } = await import("../bun-db/query");
+  await insertMany(
+    db,
+    rebuildDeadLetterTable,
+    skipped.map(({ event, error }) => ({
+      projectionName,
+      eventId: event.id,
+      tenantId: event.tenantId,
+      aggregateId: event.aggregateId,
+      aggregateType: event.aggregateType,
+      eventType: event.type,
+      errorMessage: error instanceof Error ? error.message : String(error),
+      payload: event.payload,
+    })),
+  );
+}
+
+export type RebuildDeadLetterRow = {
+  readonly id: bigint;
+  readonly projectionName: string;
+  readonly eventId: string;
+  readonly tenantId: string;
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly eventType: string;
+  readonly errorMessage: string;
+  readonly payload: Record<string, unknown>;
+  readonly createdAt: Date;
+};
+
+// Ops-side triage query, optionally scoped to one projection.
+export async function listRebuildDeadLetters(
+  db: DbConnection,
+  options: { projectionName?: string; limit?: number } = {},
+): Promise<readonly RebuildDeadLetterRow[]> {
+  const { selectMany } = await import("../bun-db/query");
+  const limit = options.limit ?? 100;
+  const where =
+    options.projectionName !== undefined ? { projectionName: options.projectionName } : undefined;
+  return selectMany<RebuildDeadLetterRow>(db, rebuildDeadLetterTable, where, {
+    orderBy: { col: "createdAt", direction: "desc" },
+    limit,
+  });
+}

package/src/event-store/snapshot.ts

@@ -1,5 +1,10 @@
 // sql now comes from native dialect
 
+import type {
+  LoadAggregateWithSnapshotOptions,
+  LoadAggregateWithSnapshotResult,
+  SnapshotReducer,
+} from "@cosmicdrift/kumiko-types/snapshot-types";
 import type { DbConnection, DbRunner } from "../db/connection";
 import {
   index,
@@ -12,13 +17,13 @@ import {
   text,
   uuid,
 } from "../db/dialect";
-import { upsertSnapshot } from "../db/queries/event-store";
+import { ensureSnapshotVersionColumn, upsertSnapshot } from "../db/queries/event-store";
 import { selectMany } from "../db/query";
 import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
 import { unsafePushTables } from "../stack";
 import { isStreamArchived } from "./archive";
-import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
+import { loadEventsAfterVersion } from "./event-store";
 
 // Marten-aligned snapshot store. A snapshot is a point-in-time materialised
 // state of an aggregate at a specific version, cached so rehydrating the
@@ -30,18 +35,17 @@ import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
 //   3. loadEventsAfterVersion(aggregate, N) → only the delta
 //   4. reducer(snapshot, delta) → current state
 //
-// Write path: feature authors opt in via ctx.snapshotAggregate. Policy
-// (every N events, every M minutes, on-demand) is a feature-level decision
-// — the framework only offers the storage primitive.
+// Write path: manual via ctx.snapshotAggregate, or automatic via the
+// { snapshotEvery: N } load option — the read path persists a fresh
+// snapshot whenever it folded at least N delta events.
 //
-// Schema-migration policy: NO built-in snapshot versioning. A snapshot stores
-// the aggregate state in the reducer's current shape. When the reducer's
-// shape changes (added field, renamed property, moved compound), invalidate
-// the cache — DELETE from kumiko_snapshots WHERE aggregate_type = '...'.
-// The read path then falls back to full replay (which runs the upcaster
-// chain on events) until the next snapshotAggregate call. Cheaper than a
-// second migration mechanism; snapshots are a perf optimisation, not a
-// source of truth.
+// Schema-migration policy: explicit generations, no reducer hashing. A
+// snapshot stores the aggregate state in the reducer's current shape plus
+// a caller-declared snapshot_version. Bump { snapshotVersion } when the
+// reducer's shape changes — stored snapshots with another generation are
+// ignored (full replay through the upcaster chain on events) and restamped
+// on the next auto-save. Snapshots stay a perf optimisation, not a source
+// of truth.
 //
 // Upcaster interaction: the raw API (loadAggregateWithSnapshot below) does
 // NOT apply the upcaster chain on delta events — same layering as raw
@@ -63,6 +67,9 @@ export const snapshotsTable = pgTable(
     // returns events with version > this value.
     version: integer("version").notNull(),
     state: jsonb("state").$type<Record<string, unknown>>().notNull(),
+    // Reducer-shape generation — snapshots from another generation are
+    // ignored on load. See LoadAggregateWithSnapshotOptions.snapshotVersion.
+    snapshotVersion: integer("snapshot_version").notNull().default(sql`1`),
     createdAt: instant("created_at", { precision: 3 }).notNull().default(sql`now()`),
   },
   (t) => ({
@@ -76,7 +83,13 @@ export const snapshotsTable = pgTable(
 
 export async function createSnapshotsTable(db: DbConnection): Promise<void> {
   // skip: table already exists — idempotent boot + test-setup call
-  if (await tableExists(db, "public.kumiko_snapshots")) return;
+  if (await tableExists(db, "public.kumiko_snapshots")) {
+    // Installs that predate snapshot_version get healed by the same
+    // idempotent ensure that `kumiko schema apply` / test-setup already runs.
+    await ensureSnapshotVersionColumn(db);
+    // skip: table already ensured — only the column heal above was needed
+    return;
+  }
   await unsafePushTables(db, { kumikoSnapshots: snapshotsTable });
 }
 
@@ -86,6 +99,7 @@ export type Snapshot<TState extends Record<string, unknown> = Record<string, unk
   readonly aggregateType: string;
   readonly version: number;
   readonly state: TState;
+  readonly snapshotVersion: number;
   readonly createdAt: Temporal.Instant;
 };
 
@@ -95,6 +109,8 @@ export type SaveSnapshotArgs = {
   readonly aggregateType: string;
   readonly version: number;
   readonly state: Record<string, unknown>;
+  // Reducer-shape generation (default 1) — see LoadAggregateWithSnapshotOptions.
+  readonly snapshotVersion?: number;
 };
 
 // Upsert-style save so re-snapshotting the same (aggregateId, version) is
@@ -108,6 +124,7 @@ export async function saveSnapshot(db: DbRunner, args: SaveSnapshotArgs): Promis
     aggregateType: args.aggregateType,
     version: args.version,
     state: args.state,
+    snapshotVersion: args.snapshotVersion ?? 1,
   });
 }
 
@@ -123,6 +140,7 @@ export async function loadLatestSnapshot<
     aggregateType: string;
     version: number;
     state: unknown;
+    snapshotVersion: number;
     createdAt: Temporal.Instant;
   };
   const rows = await selectMany<SnapRow>(
@@ -139,35 +157,16 @@ export async function loadLatestSnapshot<
     aggregateType: row.aggregateType,
     version: row.version,
     state: row.state as TState, // @cast-boundary engine-payload
+    snapshotVersion: row.snapshotVersion,
     createdAt: row.createdAt,
   };
 }
 
-// Reducer used to fold events onto a state. Kept narrow and pure — the
-// caller supplies the shape and update rules. Mirrors the reducer shape
-// feature authors already write for r.projection.apply.
-export type SnapshotReducer<TState extends Record<string, unknown>> = (
-  state: TState,
-  event: StoredEvent,
-) => TState;
-
-export type LoadAggregateWithSnapshotResult<TState extends Record<string, unknown>> = {
-  readonly state: TState;
-  readonly version: number;
-  readonly snapshotHit: boolean;
-};
-
-export type LoadAggregateWithSnapshotOptions = {
-  // Opt-in: include archived streams in the rehydrate. Default false — same
-  // semantics as loadAggregate / loadAggregateAsOf. Archive check is a
-  // single indexed lookup, so the cost stays negligible on the hot path.
-  readonly includeArchived?: boolean;
-  // Optional upcaster step: every delta event goes through this transform
-  // BEFORE the reducer sees it. The dispatcher wires this up with
-  // r.eventMigration so feature code always sees current-version payloads.
-  // Async to support Marten-style AsyncOnlyEventUpcaster (DB lookups).
-  readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
-};
+export type {
+  LoadAggregateWithSnapshotOptions,
+  LoadAggregateWithSnapshotResult,
+  SnapshotReducer,
+} from "@cosmicdrift/kumiko-types/snapshot-types";
 
 // Snapshot-aware rehydrate. Loads the latest snapshot (if any), applies
 // events strictly newer than snapshot.version, and returns the fold.
@@ -186,13 +185,23 @@ export async function loadAggregateWithSnapshot<TState extends Record<string, un
   initial: TState,
   options?: LoadAggregateWithSnapshotOptions,
 ): Promise<LoadAggregateWithSnapshotResult<TState>> {
+  if (
+    options?.snapshotEvery !== undefined &&
+    (!Number.isInteger(options.snapshotEvery) || options.snapshotEvery < 1)
+  ) {
+    throw new Error(
+      `loadAggregateWithSnapshot: snapshotEvery must be an integer >= 1, got ${String(options.snapshotEvery)}`,
+    );
+  }
   if (!options?.includeArchived) {
     const archived = await isStreamArchived(db, tenantId, aggregateId);
     if (archived) {
       return { state: initial, version: 0, snapshotHit: false };
     }
   }
-  const snapshot = await loadLatestSnapshot<TState>(db, aggregateId, tenantId);
+  const shapeVersion = options?.snapshotVersion ?? 1;
+  const stored = await loadLatestSnapshot<TState>(db, aggregateId, tenantId);
+  const snapshot = stored && stored.snapshotVersion === shapeVersion ? stored : null;
   const baseState = snapshot ? snapshot.state : initial;
   const afterVersion = snapshot ? snapshot.version : 0;
   const delta = await loadEventsAfterVersion(db, aggregateId, tenantId, afterVersion);
@@ -204,6 +213,20 @@ export async function loadAggregateWithSnapshot<TState extends Record<string, un
   }
   const lastDelta = delta[delta.length - 1];
   const latestVersion = lastDelta ? lastDelta.version : afterVersion;
+  if (options?.snapshotEvery !== undefined && lastDelta && delta.length >= options.snapshotEvery) {
+    try {
+      await saveSnapshot(db, {
+        aggregateId,
+        tenantId,
+        aggregateType: lastDelta.aggregateType,
+        version: latestVersion,
+        state,
+        snapshotVersion: shapeVersion,
+      });
+    } catch {
+      // Best-effort cache write — losing it only costs the next load a replay.
+    }
+  }
   return {
     state,
     version: latestVersion,

package/src/event-store/types.ts

@@ -0,0 +1,2 @@
+// Legacy path — re-exported for callers still importing this module directly.
+export type * from "@cosmicdrift/kumiko-types/event-store-types";

package/src/files/__tests__/build-storage-key.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { buildStorageKey } from "../types";
+
+describe("buildStorageKey", () => {
+  test("uses the lowercased extension for a normal filename", () => {
+    const key = buildStorageKey("T1" as never, "invoice", 1, "attachment", "logo.PNG", "u1");
+    expect(key).toBe("T1/invoice/1/attachment/u1.png");
+  });
+
+  test("uses the sole segment as extension when there is no dot", () => {
+    const key = buildStorageKey("T1" as never, "invoice", 1, "attachment", "noext", "u1");
+    expect(key).toBe("T1/invoice/1/attachment/u1.noext");
+  });
+
+  test("rejects a path-traversal filename and falls back to bin instead of leaking the payload", () => {
+    const key = buildStorageKey(
+      "T1" as never,
+      "unattached",
+      "file",
+      "u",
+      "a.b/../../../../evil",
+      "u1",
+    );
+    expect(key).toBe("T1/unattached/file/u/u1.bin");
+    expect(key).not.toContain("..");
+    expect(key.split("/")).toHaveLength(5);
+  });
+});

package/src/files/__tests__/file-ref-entity.test.ts

@@ -32,3 +32,11 @@ describe("fileRefEntity base-column drift", () => {
     expect(insertedById[0]?.notNull).toBe(false);
   });
 });
+
+describe("fileRefEntity — DDL (#1205 regression)", () => {
+  test("size column is bigint, not double precision", () => {
+    const size = col("size");
+    expect(size).toHaveLength(1);
+    expect(size[0]?.pgType).toBe("bigint");
+  });
+});

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__/in-memory-provider.contract.test.ts

@@ -0,0 +1,4 @@
+import { describeFileProviderContract } from "../../testing/file-provider-contract";
+import { createInMemoryFileProvider } from "../in-memory-provider";
+
+describeFileProviderContract("InMemoryFileProvider", () => createInMemoryFileProvider());

package/src/files/__tests__/local-provider.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createLocalProvider } from "../local-provider";
+
+describe("createLocalProvider path-traversal guard", () => {
+  const basePath = join(tmpdir(), `kumiko-local-provider-test-${Date.now()}`);
+  const provider = createLocalProvider(basePath);
+
+  afterEach(async () => {
+    await rm(basePath, { recursive: true, force: true });
+  });
+
+  test("rejects a key with a `..` segment even when it resolves inside basePath", async () => {
+    await expect(
+      provider.write("T1/e/1/f/x.png/../../../../T2/y.png", new Uint8Array([1])),
+    ).rejects.toThrow(/path-traversal/);
+  });
+
+  test("rejects a `..` segment on read/delete too, and exists() reports false instead of throwing", async () => {
+    await expect(provider.read("a/../../etc/passwd")).rejects.toThrow(/path-traversal/);
+    await expect(provider.delete("a/../../etc/passwd")).rejects.toThrow(/path-traversal/);
+    expect(await provider.exists("a/../../etc/passwd")).toBe(false);
+  });
+
+  test("still allows a normal, contained key", async () => {
+    await provider.write("T1/entity/1/field/file.png", new Uint8Array([1, 2, 3]));
+    expect(await provider.exists("T1/entity/1/field/file.png")).toBe(true);
+  });
+});

package/src/files/__tests__/provider-resolver.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { Registry } from "../../engine/types";
+import { makeFileProviderResolver } from "../provider-resolver";
+import type { FileStorageProvider } from "../types";
+
+const fakeProvider = { name: "fake" } as unknown as FileStorageProvider;
+
+function fakeRegistry(): Registry {
+  return {
+    getExtensionUsages: () => [
+      {
+        entityName: "fake",
+        options: { build: async () => fakeProvider },
+      },
+    ],
+  } as unknown as Registry;
+}
+
+// 698/2: resolveProvider must not re-read config + secrets on every call —
+// the provider is effectively static per tenant for the process lifetime.
+describe("makeFileProviderResolver — per-tenant cache", () => {
+  test("a second resolve for the same tenant reuses the cached build, doesn't call configAccessorFactory again", async () => {
+    const configAccessorFactory = mock(() => async (_key: unknown) => "fake");
+    const resolver = makeFileProviderResolver({
+      registry: fakeRegistry(),
+      _configAccessorFactory: configAccessorFactory,
+      db: {} as never,
+    });
+
+    const first = await resolver("tenant-a" as never);
+    const second = await resolver("tenant-a" as never);
+
+    expect(first).toBe(fakeProvider);
+    expect(second).toBe(fakeProvider);
+    expect(configAccessorFactory).toHaveBeenCalledTimes(1);
+  });
+
+  test("different tenants get independent cache entries", async () => {
+    const configAccessorFactory = mock(() => async (_key: unknown) => "fake");
+    const resolver = makeFileProviderResolver({
+      registry: fakeRegistry(),
+      _configAccessorFactory: configAccessorFactory,
+      db: {} as never,
+    });
+
+    await resolver("tenant-a" as never);
+    await resolver("tenant-b" as never);
+
+    expect(configAccessorFactory).toHaveBeenCalledTimes(2);
+  });
+
+  test("a rejected build is evicted — the next call retries instead of staying poisoned", async () => {
+    let calls = 0;
+    const resolver = makeFileProviderResolver({
+      registry: {
+        getExtensionUsages: () => {
+          calls++;
+          if (calls === 1) throw new Error("transient failure");
+          return [{ entityName: "fake", options: { build: async () => fakeProvider } }];
+        },
+      } as unknown as Registry,
+      _configAccessorFactory: () => async (_key: unknown) => "fake",
+      db: {} as never,
+    });
+
+    await expect(resolver("tenant-a" as never)).rejects.toThrow("transient failure");
+    const second = await resolver("tenant-a" as never);
+    expect(second).toBe(fakeProvider);
+  });
+});

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(
+      /path-traversal/,
+    );
+    await expect(provider.read(escapingKey)).rejects.toThrow(/path-traversal/);
+    await expect(provider.delete(escapingKey)).rejects.toThrow(/path-traversal/);
+    // 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-handle.ts

@@ -10,27 +10,10 @@
 // suffix before the file extension — `foo/bar.jpg` + `"medium"` →
 // `foo/bar.medium.jpg`. Stable, reversible, no extra lookup tables.
 
+import type { FileContext, FileHandle } from "@cosmicdrift/kumiko-types/file-handle-types";
 import type { FileStorageProvider } from "./types";
 
-export type FileHandle = {
-  readonly key: string;
-  read(): Promise<Uint8Array>;
-  write(data: Uint8Array, mimeType?: string): Promise<void>;
-  delete(): Promise<void>;
-  exists(): Promise<boolean>;
-  // Produce a handle for a derived key (e.g. a thumbnail). Does not touch
-  // storage; only computes the key. Writing to the derived handle is the
-  // caller's job.
-  derive(suffix: string): FileHandle;
-};
-
-// The `ctx.files` service — a factory that materialises a FileHandle for a
-// storage key. One per request/event, bound to a single tenant: the provider
-// is resolved per-tenant through file-foundation, so uploads, ctx.files and the
-// GDPR jobs all hit the same store by construction.
-export type FileContext = {
-  ref(key: string): FileHandle;
-};
+export type { FileContext, FileHandle };
 
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
 // resolved (config + s3.secretAccessKey secret read) only when a handle method

package/src/files/file-ref-entity.ts

@@ -1,4 +1,4 @@
-import { createEntity, createNumberField, createTextField } from "../engine";
+import { createBigIntField, createEntity, createTextField } from "../engine";
 
 // fileRef — das File-Metadata-Entity. Ganz normales ES-Entity: Upload/Delete
 // laufen über den Standard-Executor (file-routes.ts), die Tabelle `file_refs`
@@ -25,7 +25,7 @@ export const fileRefEntity = createEntity({
     storageKey: createTextField({ required: true }),
     fileName: createTextField({ required: true, pii: true }),
     mimeType: createTextField({ required: true }),
-    size: createNumberField({ required: true }),
+    size: createBigIntField({ required: true }),
     entityType: createTextField(),
     entityId: createTextField(),
     fieldName: createTextField(),

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

@@ -34,6 +34,6 @@ export type {
   SignedUrlOptions,
   WriteStreamOptions,
 } from "./types";
-export { buildStorageKey, parseMaxSize, validateFile } from "./types";
+export { assertSafeStorageKey, buildStorageKey, parseMaxSize, validateFile } from "./types";
 export type { ZipEntry } from "./zip-stream";
 export { createZipStream } from "./zip-stream";