@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

package/src/engine/steps/webhook-send.ts

@@ -25,9 +25,11 @@ export {
 
 type WebhookHttpMethod = "POST" | "PUT" | "PATCH";
 
+// Name inside the tenant-owned secrets namespace
+// `step-dispatcher:webhook-auth.<secret>` (secrets feature).
 type WebhookAuth =
-  | { readonly kind: "bearer"; readonly secretRef: string }
-  | { readonly kind: "header"; readonly name: string; readonly secretRef: string };
+  | { readonly kind: "bearer"; readonly secret: string }
+  | { readonly kind: "header"; readonly name: string; readonly secret: string };
 
 type WebhookSendArgs = {
   readonly url: StepResolver<string>;

package/src/engine/types/handlers.ts

@@ -1,3 +1,3 @@
 // Legacy path — re-exported for callers still importing this module directly.
 export type * from "@cosmicdrift/kumiko-types/handlers";
-export { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
+export { isOpenToAllGranted, isUiAccessGranted } from "@cosmicdrift/kumiko-types/handlers";

package/src/engine/types/index.ts

@@ -218,7 +218,11 @@ export type {
   WriteHandlerFn,
   WriteResult,
 } from "@cosmicdrift/kumiko-types/handlers";
-export { isOpenToAllGranted, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
+export {
+  isOpenToAllGranted,
+  isRateLimitDisabled,
+  isUiAccessGranted,
+} from "@cosmicdrift/kumiko-types/handlers";
 export type {
   DeleteContext,
   EntityHookMap,

package/src/entrypoint/index.ts

@@ -17,7 +17,18 @@
 //   const entry = createApiEntrypoint(opts);
 //   attachSignalHandlers(entry.lifecycle);
 //   await entry.start();
-//   serve({ fetch: entry.app.fetch, port: 3000 });
+//   serve({
+//     fetch: (req, server) => entry.app.fetch(req, server.requestIP(req)?.address),
+//     port: 3000,
+//   });
+//
+// `entry.app.fetch` alone (without the 2nd arg) loses the caller's real
+// socket address — the client-ip resolver then sees no env, falls back to
+// "unknown", and every caller shares one IP-keyed rate-limit bucket (see
+// api/client-ip.ts). @cosmicdrift/kumiko-server-runtime's
+// `buildBunServeOptions(port, entry.app.fetch)` wires this same pattern
+// plus the SSE-safe idleTimeout default, for consumers that already
+// depend on that package.
 //
 // The `lifecycle` handle drives graceful-shutdown LIFO; the framework
 // registers its own shutdown hooks (eventDispatcher.stop, jobRunner.stop)
@@ -107,6 +118,7 @@ export type ApiEntrypointOptions = BaseEntrypointOptions & {
   readonly eventDispatcher?: ServerOptions["eventDispatcher"] & {
     readonly runLocal?: boolean;
   };
+  readonly trustedProxyHops?: ServerOptions["trustedProxyHops"];
 };
 
 export type WorkerEntrypointOptions = BaseEntrypointOptions &
@@ -231,6 +243,7 @@ function buildApiServer(
     processLane,
     jwtIssuer: opts.jwtIssuer,
     auth: opts.auth,
+    trustedProxyHops: opts.trustedProxyHops,
     anonymousAccess: opts.anonymousAccess,
     sseBroker: opts.sseBroker,
     rateLimit: opts.rateLimit,

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

@@ -0,0 +1,236 @@
+// transferAggregateStreams — the event store's own tenant-transfer primitive.
+// Pins: events, snapshots and the archive marker all move together; a system
+// aggregate.transferred event lands per moved aggregate; an empty id list is
+// a no-op; an id with no events under the given tenant/aggregateType is left
+// untouched; an aggregate belonging to an unrelated third tenant is never
+// touched by another tenant's move; an archive marker for a DIFFERENT
+// aggregate type sharing the same aggregate id stays behind.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
+import type { TenantId } from "../../engine/types";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { generateId as uuid } from "../../utils";
+import {
+  AGGREGATE_TRANSFER_STREAM_TYPE,
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  append,
+  archiveStream,
+  isStreamArchived,
+  loadAggregate,
+  loadLatestSnapshot,
+  saveSnapshot,
+  transferAggregateStreams,
+} from "../index";
+
+let bun: BunTestDb;
+const sourceTenant = uuid() as TenantId;
+const destinationTenant = uuid() as TenantId;
+const otherTenant = uuid() as TenantId;
+const userId = uuid();
+const transferredBy = uuid();
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  bun = await createTestDb();
+});
+
+afterAll(async () => {
+  await bun.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(bun.db).unsafe(
+    `TRUNCATE kumiko_events, kumiko_snapshots, kumiko_archived_streams RESTART IDENTITY`,
+  );
+});
+
+async function seedAggregate(tenantId: TenantId, aggregateType = "counter"): Promise<string> {
+  const aggregateId = uuid();
+  await append(bun.db, {
+    aggregateId,
+    aggregateType,
+    tenantId,
+    expectedVersion: 0,
+    type: "counter.incremented",
+    payload: { by: 1 },
+    metadata: { userId },
+  });
+  return aggregateId;
+}
+
+// Each `aggregate.transferred` event lives on its OWN fresh stream (see
+// transfer.ts) — the row's own `aggregate_id` column is that stream's id,
+// not the moved aggregate's. The moved aggregate's id is in the payload.
+async function transferredEvents(tenantId: TenantId): Promise<readonly Record<string, unknown>[]> {
+  const rows = (await asRawClient(bun.db).unsafe(
+    `SELECT payload FROM kumiko_events WHERE tenant_id = $1 AND aggregate_type = $2 AND type = $3`,
+    [tenantId, AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE],
+  )) as ReadonlyArray<{ payload: Record<string, unknown> }>;
+  return rows.map((row) => row.payload);
+}
+
+describe("transferAggregateStreams", () => {
+  test("moves events, drops the snapshot, carries the archive marker, and emits one aggregate.transferred event per moved aggregate", async () => {
+    const first = await seedAggregate(sourceTenant);
+    const second = await seedAggregate(sourceTenant);
+    await saveSnapshot(bun.db, {
+      aggregateId: first,
+      tenantId: sourceTenant,
+      aggregateType: "counter",
+      version: 1,
+      state: { count: 1 },
+    });
+    await archiveStream(bun.db, {
+      tenantId: sourceTenant,
+      aggregateId: first,
+      aggregateType: "counter",
+      archivedBy: "ops",
+    });
+
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [first, second],
+      transferredBy,
+    });
+    expect(movedCount).toBe(2);
+
+    // Events: gone from the source tenant, present under the destination.
+    expect(
+      await loadAggregate(bun.db, first, sourceTenant, { includeArchived: true }),
+    ).toHaveLength(0);
+    expect(await loadAggregate(bun.db, second, sourceTenant)).toHaveLength(0);
+    const firstEvents = await loadAggregate(bun.db, first, destinationTenant, {
+      includeArchived: true,
+    });
+    expect(firstEvents.some((e) => e.type === "counter.incremented")).toBe(true);
+    const secondEvents = await loadAggregate(bun.db, second, destinationTenant);
+    expect(secondEvents.some((e) => e.type === "counter.incremented")).toBe(true);
+
+    // Snapshot dropped from the source tenant, not recreated anywhere.
+    expect(await loadLatestSnapshot(bun.db, first, sourceTenant)).toBeNull();
+    expect(await loadLatestSnapshot(bun.db, first, destinationTenant)).toBeNull();
+
+    // Archive marker moved with the stream.
+    expect(await isStreamArchived(bun.db, sourceTenant, first)).toBe(false);
+    expect(await isStreamArchived(bun.db, destinationTenant, first)).toBe(true);
+    expect(await isStreamArchived(bun.db, destinationTenant, second)).toBe(false);
+
+    // One system event per moved aggregate, in the destination tenant.
+    const events = await transferredEvents(destinationTenant);
+    expect(events).toHaveLength(2);
+    const byAggregateId = new Map(events.map((payload) => [payload["aggregateId"], payload]));
+    expect(byAggregateId.get(first)).toMatchObject({
+      aggregateType: "counter",
+      aggregateId: first,
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+    });
+    expect(byAggregateId.get(second)).toMatchObject({
+      aggregateType: "counter",
+      aggregateId: second,
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+    });
+  });
+
+  test("an empty id list is a no-op", async () => {
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [],
+      transferredBy,
+    });
+    expect(movedCount).toBe(0);
+    expect(await transferredEvents(destinationTenant)).toHaveLength(0);
+  });
+
+  test("an id with no events under this tenant/aggregateType is left untouched and gets no event", async () => {
+    const untouched = uuid();
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [untouched],
+      transferredBy,
+    });
+    expect(movedCount).toBe(0);
+    expect(await loadAggregate(bun.db, untouched, sourceTenant)).toHaveLength(0);
+    expect(await loadAggregate(bun.db, untouched, destinationTenant)).toHaveLength(0);
+    expect(await transferredEvents(destinationTenant)).toHaveLength(0);
+  });
+
+  test("an aggregate under an unrelated third tenant with the same id is untouched", async () => {
+    const sharedId = uuid();
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: otherTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: sourceTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+
+    await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [sharedId],
+      transferredBy,
+    });
+
+    const otherTenantEvents = await loadAggregate(bun.db, sharedId, otherTenant);
+    expect(otherTenantEvents).toHaveLength(1);
+    expect(await loadAggregate(bun.db, sharedId, sourceTenant)).toHaveLength(0);
+  });
+
+  test("an archived marker for a different aggregate type sharing the moved aggregate's id stays in the source tenant", async () => {
+    const sharedId = uuid();
+    // `append()` shares its version-conflict check across the plain
+    // aggregateId, so a real "widget" stream can't coexist with a real
+    // "counter" stream under the same id/tenant — fabricate the archived
+    // marker directly (the primary verifier of the event-store primitive,
+    // same reasoning as guard-event-store-writes' own __tests__ exclusion)
+    // to prove the WHERE clause's aggregate_type filter, not the stream's
+    // version-numbering.
+    await asRawClient(bun.db).unsafe(
+      `INSERT INTO "kumiko_archived_streams" ("tenant_id", "aggregate_id", "aggregate_type", "archived_by") VALUES ($1, $2, $3, $4)`,
+      [sourceTenant, sharedId, "widget", "ops"],
+    );
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: sourceTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [sharedId],
+      transferredBy,
+    });
+    expect(movedCount).toBe(1);
+
+    expect(await isStreamArchived(bun.db, sourceTenant, sharedId)).toBe(true);
+    expect(await isStreamArchived(bun.db, destinationTenant, sharedId)).toBe(false);
+  });
+});

package/src/event-store/index.ts

@@ -53,6 +53,12 @@ export {
   saveSnapshot,
   snapshotsTable,
 } from "./snapshot";
+export {
+  AGGREGATE_TRANSFER_STREAM_TYPE,
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  type TransferAggregateStreamsArgs,
+  transferAggregateStreams,
+} from "./transfer";
 export {
   type EventUpcasters,
   makeUpcastCtx,

package/src/event-store/transfer.ts

@@ -0,0 +1,84 @@
+// The event store's own tenant-transfer primitive: the ONE place allowed to
+// move a stream across the tenant boundary (enforced by
+// guard-event-store-writes' allowlist). Each move leaves an audit event in
+// the destination tenant.
+//
+// Runs entirely on the caller-supplied DbRunner, so the move rides whatever
+// transaction the caller is already inside (tenant-handover's claim handler
+// commits it together with the root row's ownership write — see
+// move-entity-graph.ts's file header for why that matters).
+
+import type { DbRunner } from "../db";
+import {
+  deleteSnapshotsForAggregates,
+  transferArchivedStreamRows,
+  transferEventRows,
+} from "../db/queries/event-store-transfer";
+import type { TenantId } from "../engine/types";
+import { SYSTEM_EVENT_PREFIX } from "../pipeline/append-event-core";
+import { generateId } from "../utils/ids";
+import { append } from "./event-store";
+
+export const AGGREGATE_TRANSFER_STREAM_TYPE = "aggregate-transfer";
+export const AGGREGATE_TRANSFERRED_EVENT_TYPE = `${SYSTEM_EVENT_PREFIX}aggregate.transferred`;
+
+export type TransferAggregateStreamsArgs = {
+  readonly sourceTenantId: TenantId;
+  readonly destinationTenantId: TenantId;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+  readonly transferredBy: string;
+};
+
+// Moves one aggregate type's event history, drops its cached snapshots, and
+// carries any archive marker across the tenant boundary. Returns the number
+// of aggregates that actually had events (and therefore moved) — an id in
+// `aggregateIds` with no events under `sourceTenantId`/`aggregateType`
+// contributes nothing and gets no follow-up event.
+export async function transferAggregateStreams(
+  db: DbRunner,
+  args: TransferAggregateStreamsArgs,
+): Promise<number> {
+  if (args.aggregateIds.length === 0) return 0;
+
+  const movedAggregateIds = await transferEventRows(db, {
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+    aggregateType: args.aggregateType,
+    aggregateIds: args.aggregateIds,
+  });
+  if (movedAggregateIds.length === 0) return 0;
+
+  await deleteSnapshotsForAggregates(db, {
+    tenantId: args.sourceTenantId,
+    aggregateIds: movedAggregateIds,
+  });
+  await transferArchivedStreamRows(db, {
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+    aggregateType: args.aggregateType,
+    aggregateIds: movedAggregateIds,
+  });
+
+  for (const aggregateId of movedAggregateIds) {
+    // A fresh, own stream — not an append onto the moved aggregate's own
+    // stream — so the marker never bumps the moved aggregate's version or
+    // shows up when a projection replays that aggregate's history.
+    await append(db, {
+      aggregateId: generateId(),
+      aggregateType: AGGREGATE_TRANSFER_STREAM_TYPE,
+      tenantId: args.destinationTenantId,
+      expectedVersion: 0,
+      type: AGGREGATE_TRANSFERRED_EVENT_TYPE,
+      payload: {
+        aggregateType: args.aggregateType,
+        aggregateId,
+        sourceTenantId: args.sourceTenantId,
+        destinationTenantId: args.destinationTenantId,
+      },
+      metadata: { userId: args.transferredBy },
+    });
+  }
+
+  return movedAggregateIds.length;
+}

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

@@ -33,7 +33,7 @@ import {
 import { createFilesFeature } from "../feature";
 import { fileRefsTable } from "../file-ref-table";
 import type { FileRoutesOptions } from "../file-routes";
-import { createInMemoryFileProvider } from "../in-memory-provider";
+import { createInMemoryFileProvider, type InMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 import type { FileStorageProvider, SignedUrlOptions } from "../types";
 import {
@@ -1643,3 +1643,107 @@ describe("byte-serving routes with field-encrypted fileName", () => {
     }
   });
 });
+
+describe("upload body-size limit", () => {
+  // Small on purpose: the pre-parseBody body limit is maxUploadSize + a
+  // fixed multipart margin regardless of scale, so a tiny maxUploadSize
+  // keeps the over-limit payloads (and this suite) fast.
+  const SMALL_MAX_UPLOAD_SIZE = "1kb";
+  const OVER_LIMIT_FILE_BYTES = 200 * 1024;
+
+  async function withSizeLimitedServer(
+    body: (args: { app: Hono; jwt: JwtHelper; provider: InMemoryFileProvider }) => Promise<void>,
+  ): Promise<void> {
+    const isolatedDb = await createTestDb();
+    await unsafePushTables(isolatedDb.db, { fileRefsTable });
+    const provider = createInMemoryFileProvider();
+    const isolatedRegistry = createRegistry([
+      createFilesFeature({ maxUploadSize: SMALL_MAX_UPLOAD_SIZE }),
+    ]);
+    const isolatedServer = buildServer({
+      registry: isolatedRegistry,
+      context: { db: isolatedDb.db, _fileProviderResolver: () => Promise.resolve(provider) },
+      jwtSecret: JWT_SECRET,
+    });
+    try {
+      await body({ app: isolatedServer.app, jwt: isolatedServer.jwt, provider });
+    } finally {
+      await isolatedDb.cleanup();
+    }
+  }
+
+  async function buildUnattachedMultipartBody(
+    fileSizeBytes: number,
+  ): Promise<{ body: Uint8Array; contentType: string }> {
+    const fd = new FormData();
+    const content = new Uint8Array(fileSizeBytes);
+    content.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]); // PNG magic bytes
+    fd.append("file", new File([Buffer.from(content)], "big.png", { type: "image/png" }));
+    const { body, contentType } = await buildMultipartBody(fd);
+    return { body: body as Uint8Array, contentType };
+  }
+
+  test("Content-Length above the limit is rejected without writing to storage", async () => {
+    await withSizeLimitedServer(async ({ app, jwt, provider }) => {
+      const token = await jwt.sign(adminUser);
+      const { body, contentType } = await buildUnattachedMultipartBody(OVER_LIMIT_FILE_BYTES);
+      const res = await app.request("/api/files", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+        body: body as unknown as BodyInit,
+      });
+      expect(res.status).toBe(413);
+      const json = (await res.json()) as { error: string };
+      expectErrorIncludes(json.error, "request_too_large");
+      expect(provider.keys()).toEqual([]);
+    });
+  });
+
+  test("a chunked body without Content-Length above the limit is rejected while streaming", async () => {
+    await withSizeLimitedServer(async ({ app, jwt, provider }) => {
+      const token = await jwt.sign(adminUser);
+      const { body, contentType } = await buildUnattachedMultipartBody(OVER_LIMIT_FILE_BYTES);
+      // Feeding the buffer through a ReadableStream (instead of handing it to
+      // fetch directly) means no Content-Length can be inferred — this drives
+      // bodyLimit's streaming/counting branch instead of its Content-Length
+      // shortcut.
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const chunkSize = 8 * 1024;
+          for (let offset = 0; offset < body.length; offset += chunkSize) {
+            controller.enqueue(body.subarray(offset, offset + chunkSize));
+          }
+          controller.close();
+        },
+      });
+      const req = new Request("http://localhost/api/files", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+        body: stream,
+        duplex: "half",
+      } as RequestInit);
+      // A stream body has no known length — confirms this exercises
+      // bodyLimit's streaming/counting branch, not its Content-Length shortcut.
+      expect(req.headers.get("content-length")).toBeNull();
+      const res = await app.request(req);
+      expect(res.status).toBe(413);
+      const json = (await res.json()) as { error: string };
+      expectErrorIncludes(json.error, "request_too_large");
+      expect(provider.keys()).toEqual([]);
+    });
+  });
+
+  test("an upload within the limit still succeeds", async () => {
+    await withSizeLimitedServer(async ({ app, jwt, provider }) => {
+      const token = await jwt.sign(adminUser);
+      const { body, contentType } = await buildUnattachedMultipartBody(128);
+      const res = await app.request("/api/files", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+        body: body as unknown as BodyInit,
+      });
+      expect(res.status).toBe(201);
+      expect(provider.keys().length).toBe(1);
+    });
+  });
+});

package/src/files/file-routes.ts

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
 import { getUser } from "../api/auth-middleware";
 import { requestContext } from "../api/request-context";
 import {
@@ -29,6 +30,7 @@ import { fileRefsTable } from "./file-ref-table";
 import type { FileProviderResolver } from "./provider-resolver";
 import {
   buildStorageKey,
+  parseMaxSize,
   resolveServedContentType,
   resolveUploadMimeType,
   validateFile,
@@ -130,6 +132,45 @@ function resolveAttachedField(
   return { kind: "resolved", fieldDef };
 }
 
+const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
+
+// Multipart framing plus the small entityType/entityId/fieldName parts
+// riding alongside the file.
+const MULTIPART_OVERHEAD_MARGIN_BYTES = 64 * 1024;
+
+// entityType/fieldName (and therefore the field's own maxSize) are only
+// known after the body is parsed, so this covers the largest configured
+// field, not just the global default.
+export function resolveMaxUploadBodyBytes(
+  options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">,
+): number {
+  let maxBytes = parseMaxSize(options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE);
+  for (const entity of options.registry?.getAllEntities().values() ?? []) {
+    for (const field of Object.values(entity.fields)) {
+      if (isFileField(field) && field.maxSize) {
+        maxBytes = Math.max(maxBytes, parseMaxSize(field.maxSize));
+      }
+    }
+  }
+  return maxBytes + MULTIPART_OVERHEAD_MARGIN_BYTES;
+}
+
+// Upload-route policy carried by createFilesFeature(opts?) — read from the
+// feature's exports so callers apply it without a parallel options surface.
+export function readFilesRouteOptions(
+  registry: Registry,
+): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize"> {
+  const exp = registry.features.get("files")?.exports;
+  if (exp && typeof exp === "object" && "routeOptions" in exp) {
+    const ro = (exp as { routeOptions?: unknown }).routeOptions;
+    if (ro && typeof ro === "object") {
+      // @cast-boundary feature-exports: engine-payload (unknown) → known shape
+      return ro as Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize">;
+    }
+  }
+  return {};
+}
+
 export function createFileRoutes(options: FileRoutesOptions): Hono {
   const { db } = options;
   const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
@@ -168,8 +209,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     return typeof decrypted["fileName"] === "string" ? decrypted["fileName"] : "download";
   }
 
+  // Runs before parseBody buffers the request below: checks Content-Length
+  // upfront, counts chunked bodies while streaming.
+  const uploadBodyLimit = bodyLimit({
+    maxSize: resolveMaxUploadBodyBytes(options),
+    onError: (c) =>
+      c.json(
+        { error: "request_too_large: request body exceeds the maximum allowed upload size" },
+        413,
+      ),
+  });
+
   // POST /files — multipart upload.
-  api.post("/files", async (c) => {
+  api.post("/files", uploadBodyLimit, async (c) => {
     const user = getUser(c);
     const body = await c.req.parseBody();
     const file = body["file"];
@@ -198,7 +250,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     }
 
     // Validate against entity field definition if available.
-    let maxSize = options.maxUploadSize ?? "10mb";
+    let maxSize = options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
     let accept: readonly string[] | undefined;
 
     const attachedField = resolveAttachedField(options.registry, entityType, fieldName);

package/src/files/index.ts

@@ -11,7 +11,7 @@ export type {
   FileRef,
   FileRoutesOptions,
 } from "./file-routes";
-export { createFileRoutes } from "./file-routes";
+export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes } from "./file-routes";
 export type { InMemoryFileProvider } from "./in-memory-provider";
 export { createInMemoryFileProvider } from "./in-memory-provider";
 export { createLocalProvider } from "./local-provider";

package/src/http/index.ts

@@ -1,2 +1,10 @@
-export type { EgressPolicy } from "@cosmicdrift/kumiko-http";
-export { egress, isPublicHost } from "@cosmicdrift/kumiko-http";
+export type { EgressPolicy, ResolvedHost } from "@cosmicdrift/kumiko-http";
+export {
+  BlockedHostError,
+  buildPinnedRequest,
+  egress,
+  HostResolutionError,
+  isPublicHost,
+  resolvePublicHost,
+  resolvePublicHostname,
+} from "@cosmicdrift/kumiko-http";