@cosmicdrift/kumiko-framework 0.359.0 → 0.360.0

package/dist/engine/feature-config-events-jobs.js

@@ -1,5 +1,6 @@
 import { escapeHatchGrantsProblem, normalizeEventPiiSubject, } from "@cosmicdrift/kumiko-types/handlers";
 import { ZodObject } from "zod";
+import { isValidIanaTimeZone } from "../time/iana.js";
 import { resolveName } from "./handler-helpers.js";
 import { splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
 import { QnTypes, qn, toKebab } from "./qualified-name.js";
@@ -168,6 +169,13 @@ export function buildConfigEventsJobsMethods(state, name) {
             if (jobGrantsProblem) {
                 throw new Error(`[Feature ${name}] r.job("${jobName}") declares an invalid escapeHatch — ${jobGrantsProblem}`);
             }
+            if ("cron" in jobOptions.trigger && jobOptions.trigger.tz !== undefined) {
+                const tz = jobOptions.trigger.tz;
+                if (!isValidIanaTimeZone(tz)) {
+                    throw new Error(`[Feature ${name}] r.job("${jobName}") declares trigger { cron, tz: ${JSON.stringify(tz)} } — ` +
+                        'tz must be an IANA time zone name such as "Europe/Berlin".');
+                }
+            }
             // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
             // wird zu Array von resolved strings, Single bleibt single string —
             // job-runner unterscheidet anhand Array.isArray.

package/dist/errors/reasons.d.ts

@@ -14,6 +14,7 @@ export declare const FrameworkReasons: {
     readonly irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk";
     readonly instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk";
     readonly subjectErased: "subject_erased";
+    readonly fileRejected: "file_rejected";
 };
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];
 export declare const AgentReasons: {

package/dist/errors/reasons.js

@@ -66,6 +66,9 @@ export const FrameworkReasons = {
     // ConflictError: a write touched a personal-data field of a data subject whose
     // key was erased (crypto-shredding); the subject can no longer receive data.
     subjectErased: "subject_erased",
+    // UnprocessableError: createFileRefFromBytes refused the file (size, type,
+    // content or attach target). `details.error` carries the upload-route error string.
+    fileRejected: "file_rejected",
 };
 // Reason codes the AI-agent runtime surfaces via `details.reason`. Kept as a
 // sister catalog to FrameworkReasons instead of extending it — see the

package/dist/files/bind-pending-file-refs.d.ts

@@ -0,0 +1,8 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+export declare function bindPendingFileRefs(args: {
+    readonly registry: Registry;
+    readonly result: SaveContext;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+}): Promise<void>;

package/dist/files/bind-pending-file-refs.js

@@ -0,0 +1,54 @@
+import { isFileField, isUuid, } from "../engine/types/index.js";
+import { reraiseAsKumikoError } from "../errors/index.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+function fileRefIdsOf(value) {
+    if (typeof value === "string")
+        return isUuid(value) ? [value] : [];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && isUuid(item));
+}
+function isPendingUploadFor(row, entityName, fieldName, user) {
+    return (row["entityId"] === null &&
+        row["entityType"] === entityName &&
+        row["fieldName"] === fieldName &&
+        row["insertedById"] === user.id);
+}
+// A create form uploads before the record exists, so its fileRefs carry
+// entityType + fieldName but no entityId. Binding them in the create's own
+// transaction makes record-bound variants (qr overlay) and record-read file
+// access work for them. Only the caller's own pending uploads for exactly this
+// entity field are bound: naming someone else's upload id in a create payload
+// must not pull that file into a record the caller controls.
+export async function bindPendingFileRefs(args) {
+    const { registry, result, user, db } = args;
+    // skip: only a create can carry still-pending uploads for its own record
+    if (!result.isNew || result.entityName === undefined)
+        return;
+    const entityName = result.entityName;
+    const entity = registry.getEntity(entityName);
+    // skip: saves of unregistered aggregates (custom executors) declare no file fields
+    if (entity === undefined)
+        return;
+    // skip: without the files feature the file_refs table is not part of the schema
+    if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
+        return;
+    const executor = getFileRefExecutor();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        // files/images fields have no projection column, so their ids are only in
+        // the create's input (changes), not in the returned row (data).
+        const namedIds = result.data[fieldName] ?? result.changes[fieldName];
+        for (const fileRefId of fileRefIdsOf(namedIds)) {
+            const row = await executor.detail({ id: fileRefId }, user, db);
+            if (row === null || !isPendingUploadFor(row, entityName, fieldName, user))
+                continue;
+            const version = typeof row["version"] === "number" ? row["version"] : undefined;
+            const bound = await executor.update({ id: fileRefId, version, changes: { entityId: String(result.id) } }, user, db);
+            if (!bound.isSuccess)
+                throw reraiseAsKumikoError(bound.error);
+        }
+    }
+}

package/dist/files/create-file-ref-from-bytes.d.ts

@@ -0,0 +1,22 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import type { Registry, SessionUser, WriteResult } from "../engine/types/index.js";
+import { type CreatedFileRef } from "./create-file-ref.js";
+import type { FileContext } from "./file-handle.js";
+export type { CreatedFileRef };
+export type CreateFileRefContext = {
+    readonly db: TenantDb;
+    readonly files?: FileContext | undefined;
+    readonly registry: Registry;
+    readonly user: SessionUser;
+};
+export type CreateFileRefInput = {
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly data: Uint8Array;
+    readonly attachTo?: {
+        readonly entityType: string;
+        readonly fieldName: string;
+        readonly entityId?: string;
+    };
+};
+export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;

package/dist/files/create-file-ref-from-bytes.js

@@ -0,0 +1,39 @@
+import { FrameworkReasons, InternalError, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, } from "./create-file-ref.js";
+import { readFilesRouteOptions } from "./file-routes.js";
+// Server-side counterpart of POST /files for handlers/jobs that produce bytes
+// themselves (generated PDFs, exports). Same validation, storage layout and
+// fileRef.created event as an upload; the tenant is always ctx.user.tenantId.
+export async function createFileRefFromBytes(ctx, input) {
+    const { files } = ctx;
+    if (!files) {
+        return writeFailure(new InternalError({
+            message: "createFileRefFromBytes: ctx.files is unavailable — mount a file-provider feature to store files",
+        }));
+    }
+    const outcome = await storeFileAsFileRef({
+        user: ctx.user,
+        tenantDb: ctx.db,
+        registry: ctx.registry,
+        defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+        writeBytes: (key, data, mimeType) => files.ref(key).write(data, mimeType),
+        deleteBytes: (key) => files.ref(key).delete(),
+    }, {
+        fileName: input.fileName,
+        declaredMimeType: input.mimeType,
+        data: input.data,
+        entityType: input.attachTo?.entityType,
+        entityId: input.attachTo?.entityId,
+        fieldName: input.attachTo?.fieldName,
+    });
+    switch (outcome.kind) {
+        case "created":
+            return { isSuccess: true, data: outcome.fileRef };
+        case "rejected":
+            return writeFailure(new UnprocessableError(FrameworkReasons.fileRejected, {
+                details: { error: outcome.error },
+            }));
+        case "failed":
+            return outcome.failure;
+    }
+}

package/dist/files/create-file-ref.d.ts

@@ -0,0 +1,50 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.js";
+import type { WriteFailure } from "../errors/index.js";
+export declare const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
+declare function buildFileRefExecutor(): import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+export declare function getFileRefExecutor(): ReturnType<typeof buildFileRefExecutor>;
+type AttachedFieldResolution = {
+    readonly kind: "unattached";
+} | {
+    readonly kind: "resolved";
+    readonly fieldDef: AnyFileFieldDef;
+} | {
+    readonly kind: "unresolvable";
+};
+export declare function resolveAttachedField(registry: Registry | undefined, entityType: string | undefined, fieldName: string | undefined): AttachedFieldResolution;
+export type StoreFileInput = {
+    readonly fileName: string;
+    readonly declaredMimeType: string;
+    readonly data: Uint8Array;
+    readonly entityType?: string | undefined;
+    readonly entityId?: string | undefined;
+    readonly fieldName?: string | undefined;
+};
+export type StoreFileDeps = {
+    readonly user: SessionUser;
+    readonly tenantDb: TenantDb;
+    readonly registry: Registry | undefined;
+    readonly defaultMaxUploadSize: string;
+    readonly writeBytes: (storageKey: string, data: Uint8Array, mimeType: string) => Promise<void>;
+    readonly deleteBytes: (storageKey: string) => Promise<void>;
+};
+export type CreatedFileRef = {
+    readonly id: string;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly storageKey: string;
+};
+export type StoreFileOutcome = {
+    readonly kind: "created";
+    readonly fileRef: CreatedFileRef;
+} | {
+    readonly kind: "rejected";
+    readonly error: string;
+} | {
+    readonly kind: "failed";
+    readonly failure: WriteFailure;
+};
+export declare function storeFileAsFileRef(deps: StoreFileDeps, input: StoreFileInput): Promise<StoreFileOutcome>;
+export {};

package/dist/files/create-file-ref.js

@@ -0,0 +1,135 @@
+import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { isFileField, } from "../engine/types/index.js";
+import { generateId } from "../utils/index.js";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
+import { fileRefsTable } from "./file-ref-table.js";
+import { resolveContentType } from "./resolve-content-type.js";
+import { buildStorageKey, resolveUploadMimeType, validateFile, validateFileContent, } from "./types.js";
+export const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
+// Standard entity executor for fileRef: create/delete emit fileRef.created /
+// fileRef.deleted and write file_refs via applyEntityEvent in one tx
+// (read-your-own-write), exactly like any other entity's lifecycle. Built on
+// first use: the table builder's import graph reaches back into this module.
+let fileRefExecutor;
+function buildFileRefExecutor() {
+    return createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+        entityName: FILE_REF_ENTITY_NAME,
+    });
+}
+export function getFileRefExecutor() {
+    fileRefExecutor ??= buildFileRefExecutor();
+    return fileRefExecutor;
+}
+const SAFE_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
+// 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.
+export 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 || !isFileField(fieldDef))
+        return { kind: "unresolvable" };
+    return { kind: "resolved", fieldDef };
+}
+function acceptFile(deps, input) {
+    const { fileName, declaredMimeType, data, entityType, entityId, fieldName } = input;
+    const rejected = (error) => ({ kind: "rejected", error });
+    // These interpolate directly into the storage key (buildStorageKey) —
+    // reject anything but a safe identifier so a caller 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 && !SAFE_IDENTIFIER.test(value)) {
+            return rejected(`invalid_${field}: must match /^[A-Za-z0-9_-]+$/`);
+        }
+    }
+    let maxSize = deps.defaultMaxUploadSize;
+    let accept;
+    const attachedField = resolveAttachedField(deps.registry, entityType, fieldName);
+    if (attachedField.kind === "unresolvable") {
+        return rejected("unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload");
+    }
+    if (attachedField.kind === "resolved") {
+        if (attachedField.fieldDef.maxSize)
+            maxSize = attachedField.fieldDef.maxSize;
+        if (attachedField.fieldDef.accept)
+            accept = attachedField.fieldDef.accept;
+    }
+    const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
+    if (validationError)
+        return rejected(validationError);
+    const contentValidation = validateFileContent(fileName, data, accept);
+    if (contentValidation.kind === "rejected")
+        return rejected(contentValidation.error);
+    // 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.
+    if (contentValidation.kind === "normalized") {
+        return {
+            kind: "accepted",
+            mimeType: contentValidation.mimeType,
+            extension: contentValidation.extension,
+        };
+    }
+    const mimeTypeResolution = resolveUploadMimeType(fileName, declaredMimeType, data);
+    if (mimeTypeResolution.kind === "rejected")
+        return rejected(mimeTypeResolution.error);
+    return {
+        kind: "accepted",
+        mimeType: resolveContentType({
+            declared: mimeTypeResolution.mimeType,
+            bytes: data,
+            filename: fileName,
+        }),
+        extension: undefined,
+    };
+}
+// The one upload pipeline behind POST /files and createFileRefFromBytes.
+export async function storeFileAsFileRef(deps, input) {
+    const { fileName, data, entityType, entityId, fieldName } = input;
+    const accepted = acceptFile(deps, input);
+    if (accepted.kind === "rejected")
+        return accepted;
+    const { mimeType, extension } = accepted;
+    const fileRefId = generateId();
+    const storageKey = buildStorageKey(deps.user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", fileName, generateId(), extension);
+    // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
+    // inside a PG connection's tx window). A failed create deletes the bytes
+    // again below; a later rollback of an enclosing transaction cannot, so
+    // those are orphaned for the cleanup-jobs to sweep. Losing a row on
+    // append-failure is acceptable; a committed row with a missing binary is not.
+    await deps.writeBytes(storageKey, data, mimeType);
+    // id is explicit so the response + storageKey stay consistent; tenantId,
+    // insertedAt and insertedById are set by applyEntityEvent from the event metadata.
+    const result = await getFileRefExecutor().create({
+        id: fileRefId,
+        storageKey,
+        fileName,
+        mimeType,
+        size: data.byteLength,
+        entityType: entityType ?? null,
+        entityId: entityId ?? null,
+        fieldName: fieldName ?? null,
+    }, deps.user, deps.tenantDb);
+    if (!result.isSuccess) {
+        try {
+            await deps.deleteBytes(storageKey);
+        }
+        catch {
+            // skip: the create failure is the error worth reporting; leftover bytes are swept by cleanup-jobs.
+        }
+        return { kind: "failed", failure: result };
+    }
+    return {
+        kind: "created",
+        fileRef: { id: fileRefId, fileName, mimeType, size: data.byteLength, storageKey },
+    };
+}

package/dist/files/feature.js

@@ -1,5 +1,5 @@
 import { defineFeature } from "../engine/index.js";
-import { fileRefEntity } from "./file-ref-entity.js";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 export { fileRefEntity } from "./file-ref-entity.js";
 // files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
 // den Standard-Entity-Executor (file-routes.ts: executor.create/delete →
@@ -20,7 +20,7 @@ export function createFilesFeature(options = {}) {
             category: "storage",
             recommended: false,
         });
-        r.entity("fileRef", fileRefEntity);
+        r.entity(FILE_REF_ENTITY_NAME, fileRefEntity);
         return { routeOptions: options };
     });
 }

package/dist/files/file-ref-entity.d.ts

@@ -1,3 +1,4 @@
+export declare const FILE_REF_ENTITY_NAME = "fileRef";
 export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     storageKey: {
         readonly type: "text";

package/dist/files/file-ref-entity.js

@@ -17,6 +17,7 @@ import { createBigIntField, createEntity, createTextField } from "../engine/inde
 //     reference: "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf"). The other
 //     fields (storageKey, mimeType, entityType, entityId, fieldName) are
 //     technical references or system metadata, not subject content.
+export const FILE_REF_ENTITY_NAME = "fileRef";
 export const fileRefEntity = createEntity({
     table: "file_refs",
     softDelete: true,

package/dist/files/file-ref-table.js

@@ -1,5 +1,5 @@
 import { buildEntityTable } from "../db/table-builder.js";
-import { fileRefEntity } from "./file-ref-entity.js";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 // `file_refs` ist die read-table des `fileRef`-Entity. Aus der Entity-
 // Definition gebaut (kein hand-gepflegtes pgTable mehr), damit die implizite
 // Entity-Projektion (Rebuild) und der Live-Executor-Write spaltengleich auf
@@ -9,4 +9,4 @@ import { fileRefEntity } from "./file-ref-entity.js";
 // jeder Upload appended `fileRef.created`, jeder Delete `fileRef.deleted`
 // (Standard-Entity-Auto-Verben). UUIDs schließen die Enumeration-Attacke
 // auf /files/:id.
-export const fileRefsTable = buildEntityTable("fileRef", fileRefEntity);
+export const fileRefsTable = buildEntityTable(FILE_REF_ENTITY_NAME, fileRefEntity);

package/dist/files/file-routes.d.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.js";
 import { type Registry, type SessionUser, type TenantId } from "../engine/types/index.js";
 import type { FileProviderResolver } from "./provider-resolver.js";
+import type { RecordReadCheck } from "./record-read-check.js";
 export type FileAccessDecision = "allow" | "deny";
 export type FileRef = {
     id: string;
@@ -27,6 +28,7 @@ export type FileRoutesOptions = {
     readonly maxUploadSize?: string;
     readonly privilegedRoles?: readonly string[];
     readonly accessGuard?: FileAccessGuard;
+    readonly canReadRecord?: RecordReadCheck;
 };
 export declare function resolveMaxUploadBodyBytes(options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">): number;
 export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize">;

package/dist/files/file-routes.js

@@ -4,54 +4,44 @@ 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, PII_ERASED_SENTINEL, } 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 { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
 import { createFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
-import { neutralFileNameForMimeType, resolveContentType } from "./resolve-content-type.js";
-import { buildStorageKey, parseMaxSize, resolveServedContentType, resolveUploadMimeType, validateFile, validateFileContent, } from "./types.js";
+import { neutralFileNameForMimeType } from "./resolve-content-type.js";
+import { parseMaxSize, resolveServedContentType } 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 }) => {
+// Default guard: on attached files, allow the uploader or a privileged role,
+// and for reads also everyone who may read the record. Delete stays with the
+// uploader and privileged roles: reading a record is no right to remove its
+// files. Unattached files are tenant-wide (the tenant boundary is already
+// enforced by the query).
+function createDefaultGuard(privilegedRoles, canReadRecord) {
+    return async ({ fileRef, user, operation }) => {
         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";
+        if (privilegedRoles.some((role) => user.roles.includes(role)))
+            return "allow";
+        if (operation !== "read" || canReadRecord === undefined)
+            return "deny";
+        const recordReadable = await canReadRecord({
+            entityType: fileRef.entityType,
+            entityId: fileRef.entityId,
+            user,
+        });
+        return recordReadable ? "allow" : "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 || !isFileField(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;
@@ -85,14 +75,8 @@ export function readFilesRouteOptions(registry) {
 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).
-    // 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. The registry only feeds custom projections on those events.
-    const executor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
-        entityName: "fileRef",
-    });
+    const guard = options.accessGuard ?? createDefaultGuard(privilegedRoles, options.canReadRecord);
+    const executor = getFileRefExecutor();
     const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
     const api = new Hono();
     const projectionGrants = options.registry ? { projectionRegistry: options.registry } : undefined;
@@ -151,103 +135,29 @@ export function createFileRoutes(options) {
         // 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 file field, or both must be omitted for an unattached upload",
-            }, 400);
-        }
-        if (attachedField.kind === "resolved") {
-            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 = resolveContentType({
-                declared: mimeTypeResolution.mimeType,
-                bytes: data,
-                filename: file.name,
-            });
-        }
-        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, tenantDbFor(user.tenantId));
-        if (!result.isSuccess) {
+        const outcome = await storeFileAsFileRef({
+            user,
+            tenantDb: tenantDbFor(user.tenantId),
+            registry: options.registry,
+            defaultMaxUploadSize: options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+            writeBytes: (key, bytes, mimeType) => storageProvider.write(key, bytes, mimeType),
+            deleteBytes: (key) => storageProvider.delete(key),
+        }, { fileName: file.name, declaredMimeType: file.type, data, entityType, entityId, fieldName });
+        if (outcome.kind === "rejected")
+            return c.json({ error: outcome.error }, 400);
+        if (outcome.kind === "failed")
             return c.json({ error: "upload_failed" }, 500);
-        }
-        return c.json({
-            id: fileRefId,
-            fileName: file.name,
-            mimeType,
-            size: file.size,
-            storageKey,
-        }, 201);
+        return c.json(outcome.fileRef, 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.
+    //      unattached → allow; attached → uploader, privileged role or a
+    //      reader of the record.
     //      Apps override via options.accessGuard to layer entity-level rules.
     api.get("/files/:id", async (c) => {
         const user = getUser(c);

package/dist/files/index.d.ts

@@ -1,3 +1,5 @@
+export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, } from "./create-file-ref-from-bytes.js";
+export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature } from "./feature.js";
 export type { FileContext, FileHandle } from "./file-handle.js";
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";

package/dist/files/index.js

@@ -1,3 +1,4 @@
+export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.