@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/files/file-routes.js

@@ -0,0 +1,433 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { getUser } from "../api/auth-middleware.js";
+import { requestContext } from "../api/request-context.js";
+import { selectMany } from "../bun-db/index.js";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, } from "../crypto/index.js";
+import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { createTenantDb } from "../db/tenant-db.js";
+import { createDerivativesContext, resolveFieldVariant, resolveRenderer, } from "../derivatives/index.js";
+import { isFileField, isUuid, } from "../engine/types/index.js";
+import { generateId } from "../utils/index.js";
+import { buildContentDispositionHeader } from "./content-disposition.js";
+import { createFileContext } from "./file-handle.js";
+import { fileRefEntity } from "./file-ref-entity.js";
+import { fileRefsTable } from "./file-ref-table.js";
+import { buildStorageKey, parseMaxSize, resolveServedContentType, resolveUploadMimeType, validateFile, validateFileContent, } from "./types.js";
+const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
+// 15 minutes — long enough for a download to start, short enough that a
+// leaked URL (e.g. from a browser history screenshot) isn't a long-lived
+// credential (see "Signed-URL default expiry" in core-files.md).
+const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
+// Default guard: on attached files, allow the uploader or a privileged role.
+// Unattached files are tenant-wide (the tenant boundary is already enforced
+// by the query).
+function createDefaultGuard(privilegedRoles) {
+    return ({ fileRef, user }) => {
+        if (fileRef.entityType === null || fileRef.entityId === null)
+            return "allow";
+        if (fileRef.insertedById === user.id)
+            return "allow";
+        for (const role of privilegedRoles) {
+            if (user.roles.includes(role))
+                return "allow";
+        }
+        return "deny";
+    };
+}
+// entityType/fieldName drive the GDPR-forget decision downstream
+// (fileRefDeleteHook resolves the field's PII annotation from exactly this
+// pairing) — attaching to a field nobody can resolve would leave that
+// decision hanging on an unverified client string. Either both are omitted
+// (unattached upload, allowed) or both must resolve to a real registered
+// field.
+function resolveAttachedField(registry, entityType, fieldName) {
+    if (entityType === undefined && fieldName === undefined)
+        return { kind: "unattached" };
+    const entity = entityType !== undefined ? registry?.getEntity(entityType) : undefined;
+    const fieldDef = entity && fieldName !== undefined ? entity.fields[fieldName] : undefined;
+    if (!entityType || !fieldName || !entity || !fieldDef)
+        return { kind: "unresolvable" };
+    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) {
+    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) {
+    const exp = registry.features.get("files")?.exports;
+    if (exp && typeof exp === "object" && "routeOptions" in exp) {
+        const ro = exp.routeOptions;
+        if (ro && typeof ro === "object") {
+            // @cast-boundary feature-exports: engine-payload (unknown) → known shape
+            return ro;
+        }
+    }
+    return {};
+}
+export function createFileRoutes(options) {
+    const { db } = options;
+    const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
+    const guard = options.accessGuard ?? createDefaultGuard(privilegedRoles);
+    // Standard entity executor for fileRef — self-contained (table + entity),
+    // no registry needed. create/delete emit fileRef.created/deleted and write
+    // file_refs via applyEntityEvent in one tx (read-your-own-write), exactly
+    // like any other entity's lifecycle.
+    const executor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+        entityName: "fileRef",
+    });
+    const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
+    const api = new Hono();
+    function kmsContextFor() {
+        return { requestId: requestContext.get()?.requestId ?? "file-routes" };
+    }
+    // loadFileForTenant is a raw selectMany — unlike executor.detail() (used by
+    // /meta), it never decrypts. Decrypting via detail() here would add its
+    // getStreamVersion/entity-cache overhead to these binary-serving hot
+    // paths, so this calls the same PII cipher directly on the already-
+    // fetched row: one KMS key fetch instead of detail()'s full read path.
+    async function resolveFileName(fileRef) {
+        if (!isPiiCiphertext(fileRef.fileName))
+            return fileRef.fileName;
+        const kms = configuredPiiSubjectKms();
+        if (!kms) {
+            return "download";
+        }
+        const decrypted = await decryptPiiFieldValues({ fileName: fileRef.fileName }, piiSubjectFields, kms, kmsContextFor());
+        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", uploadBodyLimit, async (c) => {
+        const user = getUser(c);
+        const body = await c.req.parseBody();
+        const file = body["file"];
+        if (!file || !(file instanceof File)) {
+            return c.json({ error: "missing_file: expected multipart field 'file'" }, 400);
+        }
+        const entityType = typeof body["entityType"] === "string" ? body["entityType"] : undefined;
+        // Post-ES migration entities use UUID ids; we accept the raw string and
+        // store it in the text entityId column.
+        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],
+        ]) {
+            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 ?? DEFAULT_MAX_UPLOAD_SIZE;
+        let accept;
+        const attachedField = resolveAttachedField(options.registry, entityType, fieldName);
+        if (attachedField.kind === "unresolvable") {
+            return c.json({
+                error: "unresolvable_field: entityType/fieldName must resolve to a registered entity field, or both must be omitted for an unattached upload",
+            }, 400);
+        }
+        if (attachedField.kind === "resolved" && isFileField(attachedField.fieldDef)) {
+            if (attachedField.fieldDef.maxSize)
+                maxSize = attachedField.fieldDef.maxSize;
+            if (attachedField.fieldDef.accept)
+                accept = attachedField.fieldDef.accept;
+        }
+        const validationError = validateFile({ fileName: file.name, mimeType: file.type, size: file.size }, { maxSize, accept });
+        if (validationError) {
+            return c.json({ error: validationError }, 400);
+        }
+        const data = new Uint8Array(await file.arrayBuffer());
+        const contentValidation = validateFileContent(file.name, data, accept);
+        if (contentValidation.kind === "rejected") {
+            return c.json({ error: contentValidation.error }, 400);
+        }
+        // A normalized upload's real type is already known from the sniffed
+        // bytes — resolveUploadMimeType's alias/rewrite step only applies to the
+        // declared mimeType of an unnormalized upload.
+        let mimeType;
+        if (contentValidation.kind === "normalized") {
+            mimeType = contentValidation.mimeType;
+        }
+        else {
+            const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
+            if (mimeTypeResolution.kind === "rejected") {
+                return c.json({ error: mimeTypeResolution.error }, 400);
+            }
+            mimeType = mimeTypeResolution.mimeType;
+        }
+        const fileRefId = generateId();
+        const storageKey = buildStorageKey(user.tenantId, entityType ?? "unattached", entityId ?? "", fieldName ?? "file", file.name, generateId(), contentValidation.kind === "normalized" ? contentValidation.extension : undefined);
+        // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
+        // inside a PG connection's tx window). On DB-tx rollback below the bytes
+        // are orphaned in the provider; cleanup-jobs sweep those later. Losing a
+        // row on append-failure is acceptable; corrupting a committed row with a
+        // missing binary is not.
+        const storageProvider = await options.resolveProvider(user.tenantId);
+        await storageProvider.write(storageKey, data, mimeType);
+        // Create via the standard entity executor: emits fileRef.created +
+        // materialises the file_refs row in one tx (read-your-own-write). id is
+        // explicit so the response + storageKey stay consistent; tenantId,
+        // insertedAt and insertedById are set by applyEntityEvent from the event
+        // metadata. The binary was written above, outside the tx — a create
+        // failure orphans bytes (cleanup-job sweeps) rather than committing a row
+        // whose binary is missing.
+        const result = await executor.create({
+            id: fileRefId,
+            storageKey,
+            fileName: file.name,
+            mimeType,
+            size: file.size,
+            entityType: entityType ?? null,
+            entityId: entityId ?? null,
+            fieldName: fieldName ?? null,
+        }, user, createTenantDb(db, user.tenantId));
+        if (!result.isSuccess) {
+            return c.json({ error: "upload_failed" }, 500);
+        }
+        return c.json({
+            id: fileRefId,
+            fileName: file.name,
+            mimeType,
+            size: file.size,
+            storageKey,
+        }, 201);
+    });
+    // GET /files/:id — download.
+    //
+    // Authorization stack:
+    //   1. tenantId must match (hard isolation, never crossable).
+    //   2. The configured FileAccessGuard decides read access. Default:
+    //      unattached → allow; attached → uploader or privileged role.
+    //      Apps override via options.accessGuard to layer entity-level rules.
+    api.get("/files/:id", 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") {
+            // 404 rather than 403 so the existence of the file isn't confirmed to
+            // an unauthorised caller — matches the tenant-miss response.
+            return c.json({ error: "not_found" }, 404);
+        }
+        const storageProvider = await options.resolveProvider(user.tenantId);
+        const data = await storageProvider.read(fileRef.storageKey);
+        // The stored mimeType is client-declared (file.type off the upload) and
+        // never verified against the bytes — serving it as-is would let a
+        // client label real HTML/SVG as e.g. image/png to slip active content
+        // out under a trusted-looking Content-Type. Sniff the actual bytes
+        // instead; anything that isn't a known-safe binary signature (including
+        // svg/html, which have none) goes out as application/octet-stream.
+        const contentType = resolveServedContentType(data, fileRef.mimeType);
+        return new Response(Buffer.from(data), {
+            headers: {
+                "Content-Type": contentType,
+                "Content-Disposition": buildContentDispositionHeader(await resolveFileName(fileRef)),
+                "Content-Length": String(fileRef.size),
+                "X-Content-Type-Options": "nosniff",
+            },
+        });
+    });
+    // GET /files/:id/variant/:name — a named derived version of the file.
+    // Same tenant + guard gate as the download above; the original stays
+    // reachable only through that route. The public, anonymous counterpart is
+    // a separate cut (#1951) and does not go through createFileRoutes.
+    api.get("/files/:id/variant/:name", async (c) => {
+        const user = getUser(c);
+        const id = c.req.param("id");
+        const name = c.req.param("name");
+        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);
+        // An unknown name and a denied file answer alike, so the route never
+        // confirms what exists.
+        const registry = options.registry;
+        const spec = registry
+            ? resolveFieldVariant(registry, fileRef.entityType, fileRef.fieldName, name)
+            : undefined;
+        if (!registry || !spec)
+            return c.json({ error: "not_found" }, 404);
+        // The file's mimeType comes from the upload (`file.type`) — validateFile
+        // only checks it against the field's `accept` when the field declares
+        // one, so a field without `accept` lets a client upload anything and
+        // then request /variant/*. Without this check, derivatives.variant()
+        // throws for an unsupported source mimeType — an uncaught 500 whose
+        // message lists every registered renderer's extension name.
+        if (!resolveRenderer(registry, fileRef.mimeType)) {
+            return c.json({ error: "unsupported_media_type" }, 415);
+        }
+        // Built per request: createFileContext caches the resolved provider, so
+        // one shared across requests would serve tenant A's store to tenant B.
+        const files = createFileContext(() => options.resolveProvider(user.tenantId));
+        const derivatives = createDerivativesContext({
+            files,
+            registry,
+            db,
+            tenantId: user.tenantId,
+        });
+        const result = await derivatives.variant(id, spec, name);
+        const data = await files.ref(result.storageKey).read();
+        // No Content-Length/Content-Disposition: fileRef.size is the ORIGINAL's
+        // size, and a variant is rendered for display, not for download.
+        // storageKey embeds specHash(spec), so the URL is content-stable until
+        // the spec changes — safe to cache. "private" because the response sits
+        // behind the tenant + guard gate above, not a shared CDN-cacheable asset.
+        return new Response(Buffer.from(data), {
+            headers: {
+                "Content-Type": result.mimeType,
+                "Cache-Control": "private, max-age=31536000, immutable",
+                // Explicit here, not left to the app-wide security-headers default, so the route stays safe standalone.
+                "X-Content-Type-Options": "nosniff",
+            },
+        });
+    });
+    // DELETE /files/:id — same guard, "delete" operation. Apps can differentiate
+    // read vs delete in their custom guard (e.g. only uploaders delete).
+    api.delete("/files/:id", 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: "delete" });
+        if (decision === "deny")
+            return c.json({ error: "not_found" }, 404);
+        // Delete via the standard entity executor: emits fileRef.deleted and
+        // applies it in one tx. fileRef is softDelete → the row is flagged
+        // isDeleted=true (reads filter it out) and stays recoverable; the binary
+        // is intentionally KEPT so a restore can bring the file back. Hard
+        // erasure of row + binary is the job of the forget-flow (Art. 17) and the
+        // generic data-retention cleanup — same lifecycle as any soft-delete
+        // entity, not a files-specific path.
+        const result = await executor.delete({ id }, user, createTenantDb(db, user.tenantId));
+        if (!result.isSuccess) {
+            // NotFound (race between guard and executor) reuses the 404-masking
+            // pattern from the access-deny path above. Everything else (version
+            // conflict 409, ownership 403, validation 422, internal 500) gets the
+            // real status off the error so callers can distinguish recoverable
+            // from terminal — pauschales 404 hier hat genau das verschleiert.
+            const status = result.error.httpStatus;
+            const code = status === 404 ? "not_found" : result.error.code;
+            return c.json({ error: code }, status);
+        }
+        return c.json({ ok: true });
+    });
+    // GET /files/:id/download-url — returns a short-lived provider URL so the
+    // client can download directly (offloads bandwidth from the API, enables
+    // browser caching). Same auth + tenant + guard as GET /files/:id; the
+    // signed URL is only handed out after access is approved.
+    //
+    // Shape: JSON { url, expiresAt } rather than a 302 redirect. Redirects
+    // break browser `fetch()` on cross-origin URLs (CORS preflight semantics)
+    // and hide the expiry from the caller — JSON lets SPAs cache the URL
+    // until `expiresAt` without re-hitting the API.
+    //
+    // 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({
+                error: "signed_urls_not_supported: this provider does not support signed URLs — use GET /files/:id to stream",
+            }, 501);
+        }
+        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
+            // with the original filename instead of the UUID-based storage key.
+            // Sanitised via buildContentDispositionHeader — the same attacker-
+            // controlled fileName reaches the provider's presigned response.
+            contentDisposition: buildContentDispositionHeader(await resolveFileName(fileRef)),
+        });
+        const expiresAt = new Date(Date.now() + expiresInSeconds * 1000).toISOString();
+        return c.json({ url, expiresAt });
+    });
+    // GET /files/:id/meta — metadata without the bytes. Unlike the byte-serving
+    // routes above, this returns fileName as JSON — and fileName is
+    // `personal: "self"` (fw#2423), so it must go through the entity executor's
+    // detail() to decrypt instead of loadFileForTenant's raw, still-encrypted read.
+    api.get("/files/:id/meta", async (c) => {
+        const user = getUser(c);
+        const id = c.req.param("id");
+        // Same 22P02-avoidance as loadFileForTenant — detail() doesn't validate
+        // id shape before it hits the UUID column.
+        if (!isUuid(id))
+            return c.json({ error: "not_found" }, 404);
+        const row = await executor.detail({ id }, user, createTenantDb(db, user.tenantId));
+        if (!row)
+            return c.json({ error: "not_found" }, 404);
+        const fileRef = row; // @cast-boundary db-row (decrypted via executor.detail)
+        // detail()'s "pass"-ownership read widens to tenantId IN (self, SYSTEM)
+        // and doesn't filter isDeleted (list() does, detail() doesn't) — both
+        // narrower in loadFileForTenant's selectMany. Restore that here so meta
+        // doesn't leak reference-tenant or soft-deleted rows.
+        if (fileRef.tenantId !== user.tenantId || fileRef.isDeleted) {
+            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);
+        return c.json({
+            id: fileRef.id,
+            fileName: fileRef.fileName,
+            mimeType: fileRef.mimeType,
+            size: fileRef.size,
+            entityType: fileRef.entityType,
+            entityId: fileRef.entityId,
+            fieldName: fileRef.fieldName,
+        });
+    });
+    async function loadFileForTenant(id, tenantId) {
+        // fileRefsTable.id is a UUID column — a malformed id must fail here, not
+        // at Postgres (22P02 poisons the pooled Bun.SQL connection). 404, not
+        // 400: an authenticated caller sending a bad id must see the same
+        // response as a nonexistent one, no existence-oracle.
+        if (!isUuid(id))
+            return null;
+        // isDeleted:false — soft-deleted (trashed) rows stay recoverable but must
+        // never surface to reads/guards.
+        const [row] = await selectMany(db, fileRefsTable, { id, tenantId, isDeleted: false });
+        return row ?? null; // @cast-boundary db-row
+    }
+    return api;
+}

package/dist/files/in-memory-provider.d.ts

@@ -0,0 +1,7 @@
+import type { FileStorageProvider } from "./types.js";
+export type InMemoryFileProvider = FileStorageProvider & {
+    keys(): readonly string[];
+    mimeTypeOf(key: string): string | undefined;
+    clear(): void;
+};
+export declare function createInMemoryFileProvider(): InMemoryFileProvider;

package/dist/files/in-memory-provider.js

@@ -0,0 +1,82 @@
+// In-memory file provider for unit tests. Not for production: nothing
+// persists across process restarts, and memory grows with every write.
+//
+// Factored out of test-files so any package can opt in (samples, downstream
+// feature tests) without re-inventing a Map-backed mock.
+export function createInMemoryFileProvider() {
+    const store = new Map();
+    return {
+        async write(key, data, mimeType) {
+            // Copy the buffer so the caller can reuse/mutate theirs without
+            // aliasing the stored bytes. Cheap for tests, predictable semantics.
+            store.set(key, { data: new Uint8Array(data), mimeType });
+        },
+        async writeStream(key, source, options) {
+            // In-Memory hat kein "Streaming" im real-physikalischen Sinn —
+            // wir collecten chunks in einen Uint8Array. Test-Tauglich, kein
+            // Production-Pfad.
+            const chunks = [];
+            let total = 0;
+            for await (const chunk of source) {
+                chunks.push(chunk);
+                total += chunk.byteLength;
+            }
+            const data = new Uint8Array(total);
+            let offset = 0;
+            for (const c of chunks) {
+                data.set(c, offset);
+                offset += c.byteLength;
+            }
+            store.set(key, { data, mimeType: options?.mimeType });
+        },
+        async read(key) {
+            const entry = store.get(key);
+            if (!entry)
+                throw new Error(`in-memory file not found: ${key}`);
+            return new Uint8Array(entry.data);
+        },
+        readStream(key) {
+            // In-Memory hat technisch keine Chunks, aber das Surface muss
+            // identisch zu echten Streamern (Local/S3) sein damit Test-Code
+            // den Pfad genauso geht. Wir yielden die Bytes als single-chunk.
+            // Map-lookup ist O(1), also kein Verlust durch eager-resolve.
+            // Throw passiert beim ersten chunk-pull — gleicher Lazy-Pattern
+            // wie S3 (request abgesetzt beim ersten Iterator-Step).
+            const entry = store.get(key);
+            const captured = entry ? new Uint8Array(entry.data) : null;
+            return {
+                async *[Symbol.asyncIterator]() {
+                    if (captured === null) {
+                        throw new Error(`in-memory file not found: ${key}`);
+                    }
+                    yield captured;
+                },
+            };
+        },
+        async delete(key) {
+            store.delete(key);
+        },
+        async exists(key) {
+            return store.has(key);
+        },
+        async list(prefix) {
+            return Array.from(store.keys()).filter((key) => key.startsWith(prefix));
+        },
+        // Deterministic fake URL — encodes the key + expiry so tests can assert
+        // the route wired through without running a real presigner. Shape
+        // (memory://<key>?expires=<seconds>) intentionally differs from any real
+        // provider so leakage into production would be obvious at a glance.
+        async getSignedUrl(key, expiresInSeconds) {
+            return `memory://${key}?expires=${expiresInSeconds}`;
+        },
+        keys() {
+            return Array.from(store.keys());
+        },
+        mimeTypeOf(key) {
+            return store.get(key)?.mimeType;
+        },
+        clear() {
+            store.clear();
+        },
+    };
+}

package/dist/files/index.d.ts

@@ -0,0 +1,17 @@
+export { createFilesFeature } from "./feature.js";
+export type { FileContext, FileHandle } from "./file-handle.js";
+export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";
+export { fileRefEntity } from "./file-ref-entity.js";
+export { fileRefsTable } from "./file-ref-table.js";
+export type { FileAccessDecision, FileAccessGuard, FileRef, FileRoutesOptions, } from "./file-routes.js";
+export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.js";
+export type { InMemoryFileProvider } from "./in-memory-provider.js";
+export { createInMemoryFileProvider } from "./in-memory-provider.js";
+export { createLocalProvider } from "./local-provider.js";
+export type { FileProviderContext, FileProviderPlugin, FileProviderResolver, FileProviderResolverDeps, } from "./provider-resolver.js";
+export { createFileProviderForTenant, isFileProviderPlugin, makeFileProviderResolver, } from "./provider-resolver.js";
+export { fileRefStorageDelta, filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
+export type { FileContentValidationResult, FileMetadata, FileStorageProvider, FileValidationOptions, SignedUrlOptions, UploadMimeTypeResolution, WriteStreamOptions, } from "./types.js";
+export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, parseMaxSize, resolveUploadMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, validateFileContent, } from "./types.js";
+export type { ZipEntry } from "./zip-stream.js";
+export { createZipStream } from "./zip-stream.js";

package/dist/files/index.js

@@ -0,0 +1,13 @@
+export { createFilesFeature } from "./feature.js";
+// `createFileHandle` is an implementation detail — construct handles via
+// `createFileContext(provider).ref(key)`, which is the AppContext surface.
+export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";
+export { fileRefEntity } from "./file-ref-entity.js";
+export { fileRefsTable } from "./file-ref-table.js";
+export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.js";
+export { createInMemoryFileProvider } from "./in-memory-provider.js";
+export { createLocalProvider } from "./local-provider.js";
+export { createFileProviderForTenant, isFileProviderPlugin, makeFileProviderResolver, } from "./provider-resolver.js";
+export { fileRefStorageDelta, filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
+export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, parseMaxSize, resolveUploadMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, validateFileContent, } from "./types.js";
+export { createZipStream } from "./zip-stream.js";

package/dist/files/local-provider.d.ts

@@ -0,0 +1,2 @@
+import { type FileStorageProvider } from "./types.js";
+export declare function createLocalProvider(basePath: string): FileStorageProvider;