@cosmicdrift/kumiko-framework 0.98.0 → 0.100.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.98.0",
+  "version": "0.100.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.98.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.100.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/jwt.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+import * as jose from "jose";
+import type { SessionUser } from "../../engine/types";
+import { createJwtHelper } from "../jwt";
+
+const SECRET = "test-secret-at-least-32-characters-long-aa";
+const TENANT = "11111111-1111-4111-8111-111111111111";
+const ISSUER = "kumiko";
+
+const user: SessionUser = {
+  id: "22222222-2222-4222-8222-222222222222",
+  tenantId: TENANT,
+  roles: ["TenantAdmin"],
+};
+
+// Sign a token with arbitrary claims using the SAME secret (valid signature, fully
+// controlled payload). This is how a leaked-secret / hand-crafted token looks, and it is
+// exactly what verify() must reject on claim shape — not just on a bad signature.
+function forge(claims: Record<string, unknown>): Promise<string> {
+  return new jose.SignJWT(claims)
+    .setProtectedHeader({ alg: "HS256" })
+    .setSubject(user.id)
+    .setIssuer(ISSUER)
+    .setIssuedAt()
+    .setExpirationTime("1h")
+    .sign(new TextEncoder().encode(SECRET));
+}
+
+describe("createJwtHelper.verify — payload validation (KF-2)", () => {
+  const jwt = createJwtHelper(SECRET);
+
+  it("round-trips a well-formed token", async () => {
+    const payload = await jwt.verify(await jwt.sign(user));
+    expect(payload.sub).toBe(user.id);
+    expect(payload.tenantId).toBe(TENANT);
+    expect(payload.roles).toEqual(["TenantAdmin"]);
+  });
+
+  it("rejects a validly-signed token whose tenantId is malformed", async () => {
+    const token = await forge({ tenantId: "not-a-uuid", roles: ["TenantAdmin"] });
+    await expect(jwt.verify(token)).rejects.toThrow(/tenantId/);
+  });
+
+  it("rejects a token with no tenantId claim", async () => {
+    const token = await forge({ roles: ["TenantAdmin"] });
+    await expect(jwt.verify(token)).rejects.toThrow(/tenantId/);
+  });
+
+  it("rejects a token whose roles claim is not an array", async () => {
+    const token = await forge({ tenantId: TENANT, roles: "TenantAdmin" });
+    await expect(jwt.verify(token)).rejects.toThrow(/roles/);
+  });
+
+  it("rejects a token whose roles array contains a non-string", async () => {
+    const token = await forge({ tenantId: TENANT, roles: ["ok", 7] });
+    await expect(jwt.verify(token)).rejects.toThrow(/roles/);
+  });
+});

package/src/api/jwt.ts

@@ -1,6 +1,7 @@
 import * as jose from "jose";
 import type { DbRow } from "../db/connection";
 import type { SessionUser, TenantId } from "../engine/types";
+import { parseTenantId } from "../engine/types";
 
 export type JwtPayload = {
   // JWT `sub` is a string per RFC 7519. Matches SessionUser.id — a UUID-string
@@ -48,10 +49,31 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
 
     async verify(token) {
       const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
+
+      // Defence in depth: a valid signature does not guarantee well-formed claims. A
+      // leaked secret, key confusion, or a hand-crafted token can still carry junk —
+      // validate the claim shape and reject (verify() throws → 401 in auth-middleware)
+      // instead of casting blindly.
+      const tenantId = parseTenantId(payload["tenantId"]);
+      if (tenantId === null) {
+        throw new Error("JWT payload validation failed: tenantId claim is missing or malformed");
+      }
+      const rawRoles = payload["roles"];
+      if (!Array.isArray(rawRoles)) {
+        throw new Error("JWT payload validation failed: roles claim must be an array");
+      }
+      const roles: string[] = [];
+      for (const role of rawRoles) {
+        if (typeof role !== "string") {
+          throw new Error("JWT payload validation failed: roles must contain only strings");
+        }
+        roles.push(role);
+      }
+
       const result: JwtPayload = {
         sub: String(payload.sub),
-        tenantId: payload["tenantId"] as string, // @cast-boundary dynamic-key
-        roles: payload["roles"] as string[], // @cast-boundary dynamic-key
+        tenantId,
+        roles,
       };
       const claims = payload["claims"];
       if (claims && typeof claims === "object") {

package/src/api/server.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import type { DbConnection, PgClient } from "../db/connection";
 import { createTenantDb } from "../db/tenant-db";
+import { EXT_FILE_PROVIDER } from "../engine/extension-names";
 import { runsInLane } from "../engine/run-in";
 import {
   type AppContext,
@@ -12,6 +13,7 @@ import {
 import { createFileContext } from "../files/file-handle";
 import type { FileRoutesOptions } from "../files/file-routes";
 import { createFileRoutes } from "../files/file-routes";
+import { makeFileProviderResolver } from "../files/provider-resolver";
 import type { Lifecycle } from "../lifecycle";
 import {
   createNoopProvider,
@@ -72,7 +74,11 @@ export type ServerOptions = {
   eventDedup?: EventDedup;
   sseBroker?: SseBroker;
   auth?: AuthRoutesConfig;
-  files?: Omit<FileRoutesOptions, "db"> & { db?: FileRoutesOptions["db"] };
+  // No `files` option: file-storage is wired by mounting `file-foundation` +
+  // a `file-provider-*` feature. Upload routes, ctx.files and the GDPR jobs
+  // resolve the provider per-tenant through that single source (issue #608).
+  // Upload-route policy (accessGuard/privilegedRoles/maxUploadSize) lives on
+  // `createFilesFeature(opts?)`.
   // Async event-dispatcher config. The dispatcher is created automatically
   // when (a) context.db is a DbConnection AND (b) at least one consumer is
   // wired — SSE (iff sseBroker), Search (iff context.searchAdapter), or
@@ -211,14 +217,22 @@ export type KumikoServer = {
 };
 
 export function buildServer(options: ServerOptions): KumikoServer {
-  // Hard-fail when the registry declares file/image fields but no storage
-  // provider is wired. Boot-validator checks the env shape; here we prove the
-  // runtime actually has somewhere to put the bytes. Without this, uploads
-  // would fail at the first request instead of at boot.
-  if (!options.files?.storageProvider && registryDeclaresFileFields(options.registry)) {
+  // File-storage is resolved per-tenant through file-foundation: a mounted
+  // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for
+  // uploads, ctx.files and the GDPR jobs.
+  const hasFileProvider = options.registry.getExtensionUsages(EXT_FILE_PROVIDER).length > 0;
+  // A test/advanced caller may inject the resolver directly on the context
+  // (e.g. a static in-memory provider) instead of mounting a provider plugin.
+  const hasInjectedResolver = options.context._fileProviderResolver !== undefined;
+  // Hard-fail when the registry declares file/image fields but no provider
+  // plugin is mounted — uploads would otherwise fail at the first request
+  // instead of at boot. Proves a plugin is mounted, not that each tenant
+  // selected one; per-tenant misconfig surfaces via createFileProviderForTenant.
+  if (registryDeclaresFileFields(options.registry) && !hasFileProvider && !hasInjectedResolver) {
     throw new Error(
-      "Features declare file/image fields but no storageProvider was registered — " +
-        "pass `files: { storageProvider, db }` to buildServer().",
+      "Features declare file/image fields but no file-storage provider is mounted — " +
+        "mount `file-foundation` + a `file-provider-*` feature (inmemory/s3/s3-env) and " +
+        "select one per tenant via the 'file-foundation:config:provider' config-key.",
     );
   }
 
@@ -288,12 +302,20 @@ export function buildServer(options: ServerOptions): KumikoServer {
     shouldWrapRedis && redisCtx ? wrapRedisClient(redisCtx, observability.tracer) : redisCtx;
 
   // Inject tracer + meter into the AppContext so the dispatcher can propagate
-  // them into every HandlerContext it builds. If a file storage provider was
-  // registered, wrap it in a FileContext so handlers/hooks can resolve
-  // `ctx.files.ref(key)` without reaching for the raw provider.
-  const fileCtx = options.files?.storageProvider
-    ? createFileContext(options.files.storageProvider)
-    : undefined;
+  // them into every HandlerContext it builds. Build the per-tenant file-provider
+  // resolver once (when a provider plugin is mounted) — the dispatcher uses it
+  // to materialise `ctx.files`, the upload routes + MSP-applies share it. The
+  // resolver reads config + the s3.secretAccessKey secret under SYSTEM identity.
+  const fileProviderResolver =
+    options.context._fileProviderResolver ??
+    (hasFileProvider
+      ? makeFileProviderResolver({
+          registry: options.registry,
+          _configAccessorFactory: options.context._configAccessorFactory,
+          secrets: options.context.secrets,
+          db: options.context.db,
+        })
+      : undefined);
   // Auto-wire the rate-limit resolver, but ONLY when at least one
   // handler actually declared a rateLimit option. Apps that don't use
   // L3 pay zero cost: no resolver instance, no Lua-script registration
@@ -313,7 +335,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const contextWithObservability: AppContext = {
     ...options.context,
     ...(wrappedRedis ? { redis: wrappedRedis } : {}),
-    ...(fileCtx ? { files: fileCtx } : {}),
+    ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
     ...(rateLimitResolver ? { rateLimit: rateLimitResolver } : {}),
     // Propagate the feature-toggle resolver to the context so the event-
     // dispatcher (and any future context-reading consumer) sees the same
@@ -429,7 +451,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
         tenantId: event.tenantId,
         userId: event.metadata.userId,
         ...(mspOwner && { callerFeature: mspOwner }),
-        ...(fileCtx && { files: fileCtx }),
+        ...(fileProviderResolver && {
+          files: createFileContext(() => fileProviderResolver(event.tenantId)),
+        }),
       });
       await applyFn(event, rawRunner, applyCtx);
       // Keep ctx reachable to satisfy the EventConsumerHandler signature.
@@ -583,15 +607,25 @@ export function buildServer(options: ServerOptions): KumikoServer {
   app.route("/api", createApiRoutes(dispatcher));
   app.route("/api", createSseRoute(sseBroker));
 
-  if (options.files) {
-    const fileDb = options.files.db ?? (options.context.db as FileRoutesOptions["db"]); // @cast-boundary engine-bridge
-    if (!fileDb) throw new Error("files option requires db in context or files.db");
+  // Mount upload/download routes whenever a file provider is resolvable (a
+  // file-provider plugin is mounted, or a resolver was injected). They resolve
+  // the provider per-tenant through file-foundation — no `files` option; route
+  // policy comes from createFilesFeature(opts?). Gating on the resolver (not on
+  // declared file fields) keeps unattached uploads working and matches the old
+  // "files option present → routes" behavior.
+  if (fileProviderResolver) {
+    const fileDb = options.context.db as FileRoutesOptions["db"]; // @cast-boundary engine-bridge
+    if (!fileDb) throw new Error("file routes require db in context");
+    const routeOptions = readFilesRouteOptions(options.registry);
     app.route(
       "/api",
       createFileRoutes({
-        ...options.files,
         db: fileDb,
         registry: options.registry,
+        resolveProvider: fileProviderResolver,
+        ...(routeOptions.accessGuard ? { accessGuard: routeOptions.accessGuard } : {}),
+        ...(routeOptions.privilegedRoles ? { privilegedRoles: routeOptions.privilegedRoles } : {}),
+        ...(routeOptions.maxUploadSize ? { maxUploadSize: routeOptions.maxUploadSize } : {}),
       }),
     );
   }
@@ -663,3 +697,20 @@ function registryDeclaresFileFields(registry: Registry): boolean {
   }
   return false;
 }
+
+// Upload-route policy carried by createFilesFeature(opts?) — read from the
+// feature's exports so buildServer applies it without a parallel ServerOptions
+// surface. Absent feature / opts → defaults in createFileRoutes.
+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 {};
+}

package/src/engine/__tests__/boot-validator.test.ts

@@ -1158,6 +1158,45 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- entityList virtual (labeled) columns ---
+  // A column whose `field` is not an entity field is allowed IF it carries a
+  // `label` — a presentational column drawn by a columnRenderer component (e.g.
+  // tag chips). Without a label an unknown field stays a boot error (typo guard).
+  describe("entityList virtual labeled column", () => {
+    function noteFeature(column: unknown) {
+      return defineFeature("notes", (r) => {
+        r.entity("note", createEntity({ fields: { title: createTextField() } }));
+        r.screen({
+          id: "note-list",
+          type: "entityList",
+          entity: "note",
+          // kumiko-lint-ignore as-cast test fixture pins valid + invalid column forms
+          columns: ["title", column as never],
+        });
+      });
+    }
+
+    test("labeled component column on a non-field → kein Throw", () => {
+      expect(() =>
+        validateBoot([
+          noteFeature({
+            field: "tags",
+            label: "Tags",
+            renderer: { react: { __component: "TagsCell" } },
+          }),
+        ]),
+      ).not.toThrow();
+    });
+
+    test("unlabeled column on a non-field → Throw (unknown field)", () => {
+      expect(() =>
+        validateBoot([
+          noteFeature({ field: "tags", renderer: { react: { __component: "TagsCell" } } }),
+        ]),
+      ).toThrow(/tags/);
+    });
+  });
+
   // --- entityList: pagination + sort validation ---
   // Author-Fehler vor Production fangen, damit "Screen lädt nichts /
   // sortiert falsch / crasht beim Pager-Klick" nicht erst zur Laufzeit

package/src/engine/boot-validator/screens-nav.ts

@@ -338,7 +338,11 @@ export function validateScreens(
       }
       for (const col of screen.columns) {
         const normalized = normalizeListColumn(col);
-        if (!columnFieldNames.has(normalized.field)) {
+        // A labeled column whose field is not an entity field is a *virtual*
+        // presentational column (drawn by a columnRenderer component from the
+        // row, e.g. tag chips) — its `field` is just a column key. Only an
+        // unlabeled unknown field is an author typo worth failing the boot.
+        if (!columnFieldNames.has(normalized.field) && normalized.label === undefined) {
           throw new Error(
             buildUnknownFieldMessage(
               feature.name,

package/src/engine/extension-names.ts

@@ -66,6 +66,27 @@ export const EXT_TENANT_DATA = "tenantData" as const;
  */
 export const EXT_STORAGE_PROVIDER = "storageProvider" as const;
 
+/**
+ * `fileProvider` — File-Storage-Provider-Plugin-Selection (file-foundation).
+ *
+ * Provider-Features (file-provider-s3, -inmemory, -s3-env) registrieren eine
+ * Implementierung via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
+ * der per-Tenant Config-Key `provider` waehlt zur Runtime eine aus. Der
+ * Framework-Resolver (`createFileProviderForTenant`) liest das, damit Upload-
+ * Routes, `ctx.files` UND die DSGVO-Jobs denselben Store treffen.
+ *
+ * Framework-seitig besessen, damit kein String-Drift entsteht — file-
+ * foundation MUSS Extension-Point + Config-Key unter genau diesen Namen
+ * registrieren.
+ */
+export const EXT_FILE_PROVIDER = "fileProvider" as const;
+
+// Qualifizierter Config-Key, den das file-foundation-Feature registriert
+// (Format `<feature>:config:<key>`). Akzeptierte Kopplung: der Framework-
+// Resolver liegt UNTER dem Feature und liest den Key per String. Umbenennen
+// des file-foundation-Features MUSS diese Konstante mitziehen.
+export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider" as const;
+
 /**
  * `searchAdapter` — Search-Adapter-Forget-Hooks (Meilisearch-Index-Cleanup
  * bei User-Forget oder Tenant-Destroy).

package/src/engine/index.ts

@@ -73,12 +73,14 @@ export { emitEvent, typedPayload } from "./event-helpers";
 export type { KumikoExtensionName } from "./extension-names";
 export {
   EXT_EXTERNAL_RESOURCE,
+  EXT_FILE_PROVIDER,
   EXT_INFRA_RESOURCE,
   EXT_SEARCH_ADAPTER,
   EXT_STORAGE_PROVIDER,
   EXT_TENANT_DATA,
   EXT_USER_DATA,
   EXT_USER_DATA_ORDER,
+  FILE_PROVIDER_CONFIG_KEY,
 } from "./extension-names";
 export type {
   TenantUserModel,

package/src/engine/types/handlers.ts

@@ -3,6 +3,7 @@ import type { ZodType } from "zod";
 import type { DbConnection } from "../../db/connection";
 import type { TenantDb } from "../../db/tenant-db";
 import type { FileContext } from "../../files/file-handle";
+import type { FileProviderResolver } from "../../files/provider-resolver";
 import type { Logger } from "../../logging/types";
 import type { Meter, MetricsHandle, Tracer } from "../../observability/types";
 import type { EntityCache } from "../../pipeline/entity-cache";
@@ -230,11 +231,16 @@ type SharedContextFields = {
   // rejected at boot to surface the misconfig early.
   readonly rateLimit?: import("../../rate-limit").RateLimitResolver;
   readonly searchAdapter?: SearchAdapter;
-  // Binary storage, wrapped around the registered FileStorageProvider.
-  // Optional at the AppContext level — present when the app booted with
-  // `files.storageProvider`. Hooks/handlers use ctx.files.ref(key) instead
-  // of receiving binaries in payloads.
+  // Binary storage. The dispatcher builds this per-call, bound to the caller's
+  // tenant, from `_fileProviderResolver` (below) — so uploads, ctx.files and the
+  // GDPR jobs all resolve through the same file-foundation provider. Hooks/
+  // handlers use ctx.files.ref(key) instead of receiving binaries in payloads.
   readonly files?: FileContext;
+  // Boot-built, per-tenant file-provider resolver. Set by buildServer when a
+  // `file-provider-*` plugin is mounted; the dispatcher reads it to materialise
+  // ctx.files (and the upload routes + MSP-applies use the same resolver).
+  // Resolution runs under system identity for the s3.secretAccessKey read.
+  readonly _fileProviderResolver?: FileProviderResolver;
   readonly entityCache?: EntityCache;
   readonly notify?: NotifyFn;
   readonly _notifyFactory?: NotifyFactory;

package/src/engine/types/index.ts

@@ -192,7 +192,7 @@ export type {
 } from "./http-route";
 // Domain-identifier type aliases — see identifiers.ts for rationale.
 export type { EntityId, TenantId } from "./identifiers";
-export { isSystemTenant, SYSTEM_TENANT_ID } from "./identifiers";
+export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./identifiers";
 export type { NavDefinition } from "./nav";
 export type {
   MspErrorMode,

package/src/engine/types/screen.ts

@@ -78,6 +78,16 @@ export type ListColumnSpec =
   | {
       readonly field: string;
       readonly renderer?: FieldRenderer;
+      /** Optional header, overriding the default
+       *  `<feature>:entity:<entity>:field:<field>` i18n convention. Resolved
+       *  through `translate` like any header — an i18n key, or a plain literal
+       *  shown verbatim if it isn't a key. Also the way to declare a *virtual*
+       *  column whose `field` is NOT an entity field — a presentational column
+       *  drawn entirely by a `columnRenderer` component that reads the `row`
+       *  (e.g. a tag-chips cell), not a stored value. Such a column needs a
+       *  label; without one it is rejected at boot as an unknown field. `field`
+       *  is then just a stable column key (pick any unique slug). */
+      readonly label?: string;
     };
 
 // Pagination-Modi für entityList:

package/src/entrypoint/index.ts

@@ -38,7 +38,6 @@ import { buildServer } from "../api/server";
 import type { SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import type { AppContext, JobRunIn, Registry, RunIn } from "../engine/types";
-import type { FileRoutesOptions } from "../files/file-routes";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner";
 import { createJobRunner } from "../jobs/job-runner";
 import type { Lifecycle } from "../lifecycle";
@@ -81,7 +80,6 @@ export type ApiEntrypointOptions = BaseEntrypointOptions & {
   readonly auth?: AuthRoutesConfig;
   readonly anonymousAccess?: ServerOptions["anonymousAccess"];
   readonly sseBroker?: SseBroker;
-  readonly files?: Omit<FileRoutesOptions, "db"> & { db?: FileRoutesOptions["db"] };
   readonly rateLimit?: ServerOptions["rateLimit"];
   readonly maxRequestBytes?: ServerOptions["maxRequestBytes"];
   readonly readiness?: ServerOptions["readiness"];
@@ -201,7 +199,6 @@ function buildApiServer(
     jwtIssuer: opts.jwtIssuer,
     auth: opts.auth,
     anonymousAccess: opts.anonymousAccess,
-    files: opts.files,
     sseBroker: opts.sseBroker,
     rateLimit: opts.rateLimit,
     maxRequestBytes: opts.maxRequestBytes,

package/src/files/__tests__/file-handle.test.ts

@@ -27,7 +27,7 @@ describe("deriveKey", () => {
 describe("FileHandle", () => {
   test("read/write round-trip through the provider", async () => {
     const provider = createInMemoryFileProvider();
-    const handle = createFileHandle("tenant/x.jpg", provider);
+    const handle = createFileHandle("tenant/x.jpg", () => Promise.resolve(provider));
 
     const payload = new Uint8Array([1, 2, 3, 4]);
     await handle.write(payload, "image/jpeg");
@@ -38,7 +38,7 @@ describe("FileHandle", () => {
 
   test("exists reflects write/delete state", async () => {
     const provider = createInMemoryFileProvider();
-    const handle = createFileHandle("tenant/x.jpg", provider);
+    const handle = createFileHandle("tenant/x.jpg", () => Promise.resolve(provider));
 
     expect(await handle.exists()).toBe(false);
     await handle.write(new Uint8Array([9]));
@@ -49,7 +49,7 @@ describe("FileHandle", () => {
 
   test("derive produces an independent handle at the derived key", async () => {
     const provider = createInMemoryFileProvider();
-    const original = createFileHandle("tenant/photo.jpg", provider);
+    const original = createFileHandle("tenant/photo.jpg", () => Promise.resolve(provider));
     const thumb = original.derive("thumb");
 
     expect(thumb.key).toBe("tenant/photo.thumb.jpg");
@@ -66,7 +66,7 @@ describe("FileHandle", () => {
 
   test("writes copy the buffer — caller mutations don't corrupt stored data", async () => {
     const provider = createInMemoryFileProvider();
-    const handle = createFileHandle("tenant/x.bin", provider);
+    const handle = createFileHandle("tenant/x.bin", () => Promise.resolve(provider));
 
     const buf = new Uint8Array([1, 2, 3]);
     await handle.write(buf);
@@ -80,7 +80,7 @@ describe("FileHandle", () => {
 describe("createFileContext", () => {
   test("ref returns a handle bound to the given key", async () => {
     const provider = createInMemoryFileProvider();
-    const files = createFileContext(provider);
+    const files = createFileContext(() => Promise.resolve(provider));
 
     const h = files.ref("tenant/foo.pdf");
     expect(h.key).toBe("tenant/foo.pdf");

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

@@ -27,6 +27,7 @@ import {
   expectErrorIncludes,
   patchFileInstanceofForBunTest,
 } from "../../testing";
+import { createFilesFeature } from "../feature";
 import { fileRefsTable } from "../file-ref-table";
 import type { FileRoutesOptions } from "../file-routes";
 import { createInMemoryFileProvider } from "../in-memory-provider";
@@ -83,9 +84,8 @@ beforeAll(async () => {
 
   const server = buildServer({
     registry,
-    context: { db: testDb.db },
+    context: { db: testDb.db, _fileProviderResolver: () => Promise.resolve(storageProvider) },
     jwtSecret: JWT_SECRET,
-    files: { db: testDb.db, storageProvider },
   });
   app = server.app;
   jwt = server.jwt;
@@ -397,7 +397,7 @@ describe("custom file access guard", () => {
   // body inside try/finally so the DB and tmpdir are cleaned up even if
   // assertions fail.
   async function withIsolatedFileServer(
-    options: Omit<FileRoutesOptions, "db" | "storageProvider"> & {
+    options: Omit<FileRoutesOptions, "db" | "resolveProvider"> & {
       // Overrides the default local-filesystem provider. Needed for tests
       // that exercise optional provider methods (e.g. getSignedUrl) which
       // the local provider deliberately doesn't implement.
@@ -416,12 +416,13 @@ describe("custom file access guard", () => {
     await unsafeCreateEntityTable(isolatedDb.db, testTenantEntity);
     const storagePath = await mkdtemp(join(tmpdir(), "kumiko-files-custom-"));
     const provider = providerOverride ?? createLocalProvider(storagePath);
-    const isolatedRegistry = createRegistry([tenantFeature]);
+    // Route policy (accessGuard/privilegedRoles/maxUploadSize) now rides on the
+    // files feature; the provider is injected as the per-tenant resolver.
+    const isolatedRegistry = createRegistry([tenantFeature, createFilesFeature(routeOptions)]);
     const isolatedServer = buildServer({
       registry: isolatedRegistry,
-      context: { db: isolatedDb.db },
+      context: { db: isolatedDb.db, _fileProviderResolver: () => Promise.resolve(provider) },
       jwtSecret: JWT_SECRET,
-      files: { db: isolatedDb.db, storageProvider: provider, ...routeOptions },
     });
 
     try {
@@ -736,9 +737,8 @@ describe("download-url endpoint", () => {
     const isolatedRegistry = createRegistry([tenantFeature]);
     const isolatedServer = buildServer({
       registry: isolatedRegistry,
-      context: { db: isolatedDb.db },
+      context: { db: isolatedDb.db, _fileProviderResolver: () => Promise.resolve(storageProvider) },
       jwtSecret: JWT_SECRET,
-      files: { db: isolatedDb.db, storageProvider },
     });
 
     try {

package/src/files/feature.ts

@@ -1,8 +1,22 @@
 import { defineFeature, type FeatureDefinition } from "../engine";
 import { fileRefEntity } from "./file-ref-entity";
+import type { FileAccessGuard } from "./file-routes";
 
 export { fileRefEntity } from "./file-ref-entity";
 
+// Upload-route policy. buildServer reads these off the `files` feature's
+// exports (no parallel ServerOptions surface) and applies them to the
+// /api/files routes. Storage itself is wired by mounting a `file-provider-*`
+// feature — these options only tune authorization + size limits.
+export type FilesFeatureOptions = {
+  // Replaces the default owner-or-privileged guard entirely.
+  readonly accessGuard?: FileAccessGuard;
+  // Roles that bypass the default owner-check on entity-attached files.
+  readonly privilegedRoles?: readonly string[];
+  // Global upload size default (per-field `maxSize` still wins). e.g. "10mb".
+  readonly maxUploadSize?: string;
+};
+
 // files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
 // den Standard-Entity-Executor (file-routes.ts: executor.create/delete →
 // `fileRef.created`/`fileRef.deleted` → applyEntityEvent materialisiert
@@ -14,16 +28,17 @@ export { fileRefEntity } from "./file-ref-entity";
 // userData/tenantData-Extensions sichtbar und registriert die implizite
 // Entity-Projektion (für rebuildProjection). Liegt im Framework neben
 // file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
-export function createFilesFeature(): FeatureDefinition {
+export function createFilesFeature(options: FilesFeatureOptions = {}): FeatureDefinition {
   return defineFeature("files", (r) => {
     r.describe(
-      "Exposes the `fileRef` entity and `createFilesFeature` from the framework core so that uploaded files \u2014 tracked in the `file_refs` table by `createFileRoutes` \u2014 participate in cross-feature hooks: `user-data-rights-defaults` automatically includes file blobs in GDPR exports and forget flows, and future tenant-lifecycle cleanup will delete all refs on tenant destroy. This feature does not add upload or download routes; those remain in the server bootstrap via the `options.files` parameter.",
+      "Exposes the `fileRef` entity from the framework core so that uploaded files — tracked in the `file_refs` table by `createFileRoutes` — participate in cross-feature hooks: `user-data-rights-defaults` automatically includes file blobs in GDPR exports and forget flows, and tenant-lifecycle cleanup deletes all refs on tenant destroy. Upload/download routes are registered by the server bootstrap when a `file-provider-*` feature is mounted; this feature carries their access/size policy via `createFilesFeature(opts?)`.",
     );
     r.uiHints({
-      displayLabel: "Files \u00b7 Metadata",
+      displayLabel: "Files · Metadata",
       category: "storage",
       recommended: false,
     });
     r.entity("fileRef", fileRefEntity);
+    return { routeOptions: options };
   });
 }

package/src/files/file-handle.ts

@@ -25,26 +25,43 @@ export type FileHandle = {
 };
 
 // The `ctx.files` service — a factory that materialises a FileHandle for a
-// storage key. One per app, wrapped around whichever FileStorageProvider the
-// app boot registered.
+// 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 function createFileHandle(key: string, provider: FileStorageProvider): FileHandle {
+// `getProvider` is a lazily-resolved, memoized accessor — the provider is
+// resolved (config + s3.secretAccessKey secret read) only when a handle method
+// actually does I/O, never on every request that merely builds a ctx.
+export function createFileHandle(
+  key: string,
+  getProvider: () => Promise<FileStorageProvider>,
+): FileHandle {
   return {
     key,
-    read: () => provider.read(key),
-    write: (data, mimeType) => provider.write(key, data, mimeType),
-    delete: () => provider.delete(key),
-    exists: () => provider.exists(key),
-    derive: (suffix) => createFileHandle(deriveKey(key, suffix), provider),
+    read: async () => (await getProvider()).read(key),
+    write: async (data, mimeType) => (await getProvider()).write(key, data, mimeType),
+    delete: async () => (await getProvider()).delete(key),
+    exists: async () => (await getProvider()).exists(key),
+    derive: (suffix) => createFileHandle(deriveKey(key, suffix), getProvider),
   };
 }
 
-export function createFileContext(provider: FileStorageProvider): FileContext {
+// `resolve` is a tenant-bound thunk (the caller binds the tenant). The result
+// is memoized for this FileContext's lifetime and shared across every handle it
+// produces — never a process-global cache, since each FileContext is bound to a
+// single request/event tenant; sharing would leak one tenant's provider (and
+// its bucket/credentials) to another.
+export function createFileContext(resolve: () => Promise<FileStorageProvider>): FileContext {
+  let cached: Promise<FileStorageProvider> | undefined;
+  const getProvider = () => {
+    cached ??= resolve();
+    return cached;
+  };
   return {
-    ref: (key) => createFileHandle(key, provider), // @wrapper-known semantic-alias
+    ref: (key) => createFileHandle(key, getProvider),
   };
 }
 

package/src/files/file-routes.ts

@@ -9,7 +9,7 @@ import { generateId } from "../utils";
 import { buildContentDispositionHeader } from "./content-disposition";
 import { fileRefEntity } from "./file-ref-entity";
 import { fileRefsTable } from "./file-ref-table";
-import type { FileStorageProvider } from "./types";
+import type { FileProviderResolver } from "./provider-resolver";
 import { buildStorageKey, validateFile } from "./types";
 
 // Decision returned by a FileAccessGuard — distinct from boolean so callers
@@ -47,7 +47,11 @@ export type FileAccessGuard = (args: {
 
 export type FileRoutesOptions = {
   readonly db: DbConnection;
-  readonly storageProvider: FileStorageProvider;
+  // Per-tenant provider resolver — resolves through file-foundation so uploads,
+  // ctx.files and the GDPR jobs all hit the same store. Resolution runs under
+  // system identity for the secret-read; request-user authorization is the
+  // accessGuard's job below.
+  readonly resolveProvider: FileProviderResolver;
   readonly registry?: Registry;
   readonly maxUploadSize?: string; // global default, e.g. "10mb"
   // Roles that bypass the default owner-check on entity-attached files.
@@ -80,7 +84,7 @@ function createDefaultGuard(privilegedRoles: readonly string[]): FileAccessGuard
 }
 
 export function createFileRoutes(options: FileRoutesOptions): Hono {
-  const { db, storageProvider } = options;
+  const { db } = options;
   const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
   const guard: FileAccessGuard = options.accessGuard ?? createDefaultGuard(privilegedRoles);
   // Standard entity executor for fileRef — self-contained (table + entity),
@@ -147,6 +151,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     // row on append-failure is acceptable; corrupting a committed row with a
     // missing binary is not.
     const data = new Uint8Array(await file.arrayBuffer());
+    const storageProvider = await options.resolveProvider(user.tenantId);
     await storageProvider.write(storageKey, data, file.type);
 
     // Create via the standard entity executor: emits fileRef.created +
@@ -206,6 +211,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       return c.json({ error: "not_found" }, 404);
     }
 
+    const storageProvider = await options.resolveProvider(user.tenantId);
     const data = await storageProvider.read(fileRef.storageKey);
     return new Response(Buffer.from(data), {
       headers: {
@@ -261,6 +267,17 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
   // 501 when the wired provider doesn't support signed URLs (filesystem
   // dev providers). Clients should fall back to the streaming endpoint.
   api.get("/files/:id/download-url", async (c) => {
+    const user = getUser(c);
+    const id = c.req.param("id");
+    const fileRef = await loadFileForTenant(id, user.tenantId);
+    if (!fileRef) return c.json({ error: "not_found" }, 404);
+
+    const decision = await guard({ fileRef, user, operation: "read" });
+    if (decision === "deny") return c.json({ error: "not_found" }, 404);
+
+    // Resolve after access-check: tenant-scoped provider, and capability
+    // disclosure (501) stays behind the auth+guard gate.
+    const storageProvider = await options.resolveProvider(user.tenantId);
     if (!storageProvider.getSignedUrl) {
       return c.json(
         {
@@ -271,14 +288,6 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       );
     }
 
-    const user = getUser(c);
-    const id = c.req.param("id");
-    const fileRef = await loadFileForTenant(id, user.tenantId);
-    if (!fileRef) return c.json({ error: "not_found" }, 404);
-
-    const decision = await guard({ fileRef, user, operation: "read" });
-    if (decision === "deny") return c.json({ error: "not_found" }, 404);
-
     const expiresInSeconds = SIGNED_URL_DEFAULT_EXPIRY_SECONDS;
     const url = await storageProvider.getSignedUrl(fileRef.storageKey, expiresInSeconds, {
       // Hint the provider to set Content-Disposition so the browser prompts

package/src/files/index.ts

@@ -15,6 +15,17 @@ export { createFileRoutes } from "./file-routes";
 export type { InMemoryFileProvider } from "./in-memory-provider";
 export { createInMemoryFileProvider } from "./in-memory-provider";
 export { createLocalProvider } from "./local-provider";
+export type {
+  FileProviderContext,
+  FileProviderPlugin,
+  FileProviderResolver,
+  FileProviderResolverDeps,
+} from "./provider-resolver";
+export {
+  createFileProviderForTenant,
+  isFileProviderPlugin,
+  makeFileProviderResolver,
+} from "./provider-resolver";
 export { filesStorageTrackingFeature, tenantStorageUsageTable } from "./storage-tracking";
 export type {
   FileMetadata,

package/src/files/provider-resolver.ts

@@ -0,0 +1,158 @@
+// File-provider resolution — lives in the framework so the upload routes,
+// `ctx.files`, AND the GDPR export/forget jobs resolve their FileStorageProvider
+// through ONE path. Divergence (uploads writing one store, erasure deleting
+// another) is structurally impossible: there is a single resolver.
+//
+// The framework owns the resolution but NOT the storage backends. The
+// `fileProvider` extension point + the per-tenant `provider` config key are
+// declared by the `file-foundation` bundled feature; the concrete stores live
+// in `file-provider-*` plugins. The framework only consumes what features
+// registered in the registry — it never imports bundled-features upward.
+//
+// file-foundation re-exports `createFileProviderForTenant` + the plugin types
+// (moved here from there) so existing imports keep working.
+
+import type { DbConnection } from "../db/connection";
+import type { TenantDb } from "../db/tenant-db";
+import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY } from "../engine/extension-names";
+import { SYSTEM_USER_ID } from "../engine/system-user";
+import type { ConfigAccessor, ConfigAccessorFactory, Registry, TenantId } from "../engine/types";
+import type { SecretsContext } from "../secrets";
+import type { FileStorageProvider } from "./types";
+
+const FEATURE_NAME = "file-foundation";
+
+/**
+ * Schmaler Surface-Type fuer Provider-Plugins. HandlerContext ist zu fett
+ * (haelt tx, actor, signal etc.) — Provider sollen sich auf die read-Felder
+ * beschraenken die fuer Tenant-Config + Secret-Lookup gebraucht werden.
+ *
+ * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job) gibt es keinen
+ * request-bezogenen `tx`/`actor`/`signal`. Wenn ein Provider `ctx.tx` lesen
+ * wuerde, wuerde der ganze Worker-Pfad zur Runtime brechen — und das wuerde NUR
+ * mit S3 und nur in production auffallen. Die schmale Surface zwingt Provider
+ * zur expliziten Erweiterung statt silent ctx-feld-ausnutzen.
+ *
+ * **Felder:**
+ *   config  — fuer tenant-config-reads (bucket/region/endpoint/...)
+ *   registry — fuer extension-Lookup in der Factory (nicht Plugin-intern)
+ *   secrets — fuer tenant-secret-reads (s3.secretAccessKey)
+ *   _userId — Audit-/Authority-Identity fuer secret-reads. Der Framework-
+ *             Resolver setzt das auf SYSTEM_USER_ID — der s3-Provider liest
+ *             `s3.secretAccessKey`, was Nicht-Admin-Request-User nicht duerfen;
+ *             die Request-User-Autorisierung bleibt am Route-accessGuard.
+ */
+export type FileProviderContext = {
+  readonly config?: ConfigAccessor;
+  readonly registry?: Registry;
+  readonly secrets?: SecretsContext;
+  readonly _userId?: string | undefined;
+};
+
+/**
+ * File-Storage-Plugin contract. Each provider-feature (file-provider-s3,
+ * file-provider-inmemory, ...) registers an implementation via
+ * `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`.
+ *
+ * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein FileProviderContext, nicht
+ * ein voller HandlerContext. Felder ausserhalb der schmalen Surface (z.B.
+ * `ctx.tx`, `ctx.actor`, `ctx.signal`) sind im Worker-Pfad NICHT vorhanden.
+ * Cast `ctx as unknown as HandlerContext` fliegt zur Runtime im Worker — der
+ * Crash kommt erst in production mit dem ersten S3-Tenant. Braucht ein Plugin
+ * Felder ausserhalb FileProviderContext: lieber FileProviderContext explizit
+ * erweitern (sichtbarer breaking change) als ctx-cast.
+ */
+export type FileProviderPlugin = {
+  readonly build: (ctx: FileProviderContext, tenantId: string) => Promise<FileStorageProvider>;
+};
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind.
+export function isFileProviderPlugin(o: unknown): o is FileProviderPlugin {
+  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
+}
+
+// Looks up the per-tenant selected provider plugin + delegates to its build().
+export async function createFileProviderForTenant(
+  ctx: FileProviderContext,
+  tenantId: string,
+  handlerName = "file-foundation:provider-factory",
+): Promise<FileStorageProvider> {
+  const ctxConfig = ctx.config;
+  if (!ctxConfig) {
+    throw new Error(
+      `${handlerName}: ctx.config is missing — feature requires the config-feature mounted in the registry`,
+    );
+  }
+  if (!ctx.registry) {
+    throw new Error(
+      `${handlerName}: ctx.registry is missing — required to look up registered file-provider plugins`,
+    );
+  }
+
+  const raw = await ctxConfig(FILE_PROVIDER_CONFIG_KEY);
+  const provider = typeof raw === "string" ? raw : raw == null ? "" : String(raw);
+  if (provider.length === 0) {
+    const usages = ctx.registry.getExtensionUsages(EXT_FILE_PROVIDER);
+    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+    throw new Error(
+      `${FEATURE_NAME}: no provider selected — set the '${FILE_PROVIDER_CONFIG_KEY}' config-key to one of: ${known}. ` +
+        `Mount a file-provider-* feature first if no plugins are registered.`,
+    );
+  }
+
+  const usages = ctx.registry.getExtensionUsages(EXT_FILE_PROVIDER);
+  const usage = usages.find((u) => u.entityName === provider);
+  if (!usage) {
+    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+    throw new Error(
+      `${FEATURE_NAME}: provider "${provider}" not registered. Known: ${known}. ` +
+        `Mount the matching file-provider-${provider} feature.`,
+    );
+  }
+
+  if (!isFileProviderPlugin(usage.options)) {
+    throw new Error(
+      `${FEATURE_NAME}: provider "${provider}" registered without a build() — ` +
+        `extension options must be a FileProviderPlugin.`,
+    );
+  }
+  return usage.options.build(ctx, tenantId);
+}
+
+// A bound, per-tenant provider resolver. One instance serves all tenants
+// (tenantId is the call argument) — the single spine shared by upload routes,
+// ctx.files and the GDPR jobs.
+export type FileProviderResolver = (tenantId: TenantId) => Promise<FileStorageProvider>;
+
+export type FileProviderResolverDeps = {
+  readonly registry?: Registry;
+  readonly _configAccessorFactory?: ConfigAccessorFactory;
+  readonly secrets?: SecretsContext;
+  readonly db?: DbConnection | TenantDb;
+};
+
+// Builds the resolver from the ambient AppContext fields — the framework-side
+// equivalent of the GDPR `makeTenantStorageProviderResolver`. The config
+// accessor (and therefore the s3.secretAccessKey secret-read) runs under
+// SYSTEM identity: provider construction is an infra read, distinct from the
+// request user's authorization which stays at the route accessGuard.
+export function makeFileProviderResolver(deps: FileProviderResolverDeps): FileProviderResolver {
+  return async (tenantId) => {
+    if (!deps.registry || !deps._configAccessorFactory || !deps.db) {
+      throw new Error(
+        "makeFileProviderResolver: registry/_configAccessorFactory/db missing — " +
+          "mount the config + file-foundation features and wire context.db",
+      );
+    }
+    const config = deps._configAccessorFactory({
+      user: { id: SYSTEM_USER_ID, tenantId },
+      db: deps.db,
+      secrets: deps.secrets,
+    });
+    return createFileProviderForTenant(
+      { config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID },
+      tenantId,
+    );
+  };
+}

package/src/pipeline/dispatcher.ts

@@ -25,6 +25,7 @@ import type {
 } from "../engine/types";
 import { HookPhases } from "../engine/types";
 import type { TenantId } from "../engine/types/identifiers";
+import { createFileContext } from "../files/file-handle";
 import { createFallbackLogger } from "../logging/utils";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
@@ -285,6 +286,14 @@ export function createDispatcher(
             secrets: context.secrets,
           })
         : undefined;
+    // ctx.files resolved per-tenant through file-foundation (lazy — the
+    // provider is only resolved when a handle actually does I/O). Boot wires
+    // _fileProviderResolver when a file-provider plugin is mounted; falls back
+    // to a statically-injected context.files (tests).
+    const fileResolver = context._fileProviderResolver;
+    const files = fileResolver
+      ? createFileContext(() => fileResolver(user.tenantId))
+      : context.files;
 
     // Observability — feature-bound metrics handle, so ctx.metrics.inc("foo")
     // resolves to kumiko_<feature>_foo. Unknown feature falls back to noop
@@ -558,6 +567,7 @@ export function createDispatcher(
       log,
       notify,
       ...(config && { config }),
+      ...(files && { files }),
       tracer,
       metrics,
       tz,

package/src/stack/test-stack.ts

@@ -258,6 +258,15 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
   const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
 
+  // A static `files.storageProvider` is wired as the per-tenant resolver — the
+  // framework test seam that doesn't require mounting config + file-foundation.
+  // (Bundled GDPR tests mount the real provider features instead.)
+  let fileProviderResolver: import("../files").FileProviderResolver | undefined;
+  if (options.files) {
+    const provider = options.files.storageProvider;
+    fileProviderResolver = () => Promise.resolve(provider);
+  }
+
   const server = buildServer({
     registry,
     context: {
@@ -267,6 +276,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       entityCache,
       registry,
       ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
+      ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
       ...(typeof options.extraContext === "function"
         ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
         : options.extraContext),
@@ -318,11 +328,6 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
               : options.anonymousAccess,
         }
       : {}),
-    // Wire the upload routes + ctx.files only when the caller registered a
-    // provider. Tests that don't touch files skip both without extra setup.
-    ...(options.files
-      ? { files: { db: testDb.db, storageProvider: options.files.storageProvider } }
-      : {}),
   });
 
   const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;