@cosmicdrift/kumiko-framework 0.399.0 → 0.401.0

package/dist/files/bind-referenced-files.write.js

@@ -1,9 +1,8 @@
 import * as z from "zod";
-import { isFileField } from "../engine/field-helpers.js";
 import { defineWriteHandler, SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/index.js";
 import { ValidationError } from "../errors/index.js";
-import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
+import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 import { loadFileRefRows } from "./load-save-file-refs.js";
 import { findImplicitEntityTable } from "./record-write-check.js";
@@ -36,7 +35,7 @@ function resolveFileBearingEntity(registry, entityType) {
     if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
         throw invalidEntityType();
     const fileFieldNames = Object.entries(entity.fields)
-        .filter(([, fieldDef]) => isFileField(fieldDef))
+        .filter(([, fieldDef]) => holdsFileRefs(fieldDef))
         .map(([fieldName]) => fieldName);
     if (fileFieldNames.length === 0)
         throw invalidEntityType();
@@ -83,14 +82,15 @@ export const bindReferencedFilesWrite = defineWriteHandler({
         const { entityType, entityIds, limit } = event.payload;
         const { fileFieldNames, ...source } = resolveFileBearingEntity(ctx.registry, entityType);
         const records = await loadRecordPage(ctx.db, source, event.payload);
-        const referencedIds = records.flatMap((record) => fileFieldNames.flatMap((fieldName) => fileRefIdsOf(record[fieldName])));
+        const fileRefIdsOfRecordField = (record, fieldName) => fileRefIdsInField(source.entity.fields[fieldName], record[fieldName]);
+        const referencedIds = records.flatMap((record) => fileFieldNames.flatMap((fieldName) => fileRefIdsOfRecordField(record, fieldName)));
         const fileRefRows = await loadFileRefRows(ctx.db, referencedIds, event.user.tenantId);
         const executor = getFileRefExecutor();
         let bound = 0;
         let skipped = 0;
         for (const record of records) {
             for (const fieldName of fileFieldNames) {
-                for (const fileRefId of fileRefIdsOf(record[fieldName])) {
+                for (const fileRefId of fileRefIdsOfRecordField(record, fieldName)) {
                     const row = fileRefRows.get(fileRefId);
                     if (row === undefined ||
                         !isBindableToRecord(row, {

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

@@ -19,6 +19,8 @@ export type CreateFileRefInput = {
     readonly attachTo?: {
         readonly entityType: string;
         readonly fieldName: string;
+        /** File sub-field of the embedded `fieldName`, like POST /files' `subField` part. */
+        readonly subField?: string;
         readonly entityId?: string;
     };
     /** Byte limit replacing the configured default upload limit; a file field's own maxSize still applies first. */

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

@@ -42,6 +42,7 @@ export async function createFileRefFromBytes(ctx, input) {
         entityType: input.attachTo?.entityType,
         entityId: input.attachTo?.entityId,
         fieldName: input.attachTo?.fieldName,
+        subField: input.attachTo?.subField,
     });
     switch (outcome.kind) {
         case "created":
@@ -82,6 +83,7 @@ export async function uploadFileBytesBeforeTransaction(ctx, input) {
         entityType: input.attachTo?.entityType,
         entityId: input.attachTo?.entityId,
         fieldName: input.attachTo?.fieldName,
+        subField: input.attachTo?.subField,
     });
     if (outcome.kind === "rejected")
         return fileRejectedFailure(outcome.error);

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

@@ -30,6 +30,8 @@ export type StoreFileInput = {
     readonly entityType?: string | undefined;
     readonly entityId?: string | undefined;
     readonly fieldName?: string | undefined;
+    /** File sub-field of the embedded `fieldName`; the stored row keeps the top-level `fieldName`. */
+    readonly subField?: string | undefined;
     /** Qualified name of a registered actionForm screen; `fieldName` then names one of its files
      *  fields and the upload is stored as pending (entityType = the screen QN, no entityId). */
     readonly actionForm?: string | undefined;

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

@@ -27,36 +27,32 @@ const ACTION_FORM_STORAGE_SEGMENT = "action-form";
 const SAFE_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
 class AttachTargetLockedError extends Error {
 }
-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).
+// 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).
+function invalidIdentifierError(input) {
+    const { entityType, entityId, fieldName, subField } = input;
     for (const [field, value] of [
         ["entityType", entityType],
         ["entityId", entityId],
         ["fieldName", fieldName],
+        ["subField", subField],
     ]) {
         if (value !== undefined && !SAFE_IDENTIFIER.test(value)) {
-            return rejected(`invalid_${field}: must match /^[A-Za-z0-9_-]+$/`);
+            return `invalid_${field}: must match /^[A-Za-z0-9_-]+$/`;
         }
     }
-    const field = resolveUploadField(deps.registry, input, deps.attachTargets);
-    if (field.kind === "rejected")
-        return field;
-    if (field.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 (subField !== undefined && (entityType === undefined || fieldName === undefined)) {
+        return "invalid_sub_field: subField requires entityType and fieldName";
     }
-    const fieldDef = field.kind === "resolved" ? field.fieldDef : undefined;
-    const maxSize = fieldDef?.maxSize || deps.defaultMaxUploadSize;
-    const accept = fieldDef?.accept;
-    const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
-    if (validationError)
-        return rejected(validationError);
+    return undefined;
+}
+function acceptFileContent(input, accept) {
+    const { fileName, declaredMimeType, data } = input;
     const contentValidation = validateFileContent(fileName, data, accept);
-    if (contentValidation.kind === "rejected")
-        return rejected(contentValidation.error);
+    if (contentValidation.kind === "rejected") {
+        return { kind: "rejected", error: 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.
@@ -68,8 +64,9 @@ function acceptFile(deps, input) {
         };
     }
     const mimeTypeResolution = resolveUploadMimeType(fileName, declaredMimeType, data);
-    if (mimeTypeResolution.kind === "rejected")
-        return rejected(mimeTypeResolution.error);
+    if (mimeTypeResolution.kind === "rejected") {
+        return { kind: "rejected", error: mimeTypeResolution.error };
+    }
     return {
         kind: "accepted",
         mimeType: resolveContentType({
@@ -80,6 +77,26 @@ function acceptFile(deps, input) {
         extension: undefined,
     };
 }
+function acceptFile(deps, input) {
+    const { fileName, declaredMimeType, data } = input;
+    const rejected = (error) => ({ kind: "rejected", error });
+    const identifierError = invalidIdentifierError(input);
+    if (identifierError !== undefined)
+        return rejected(identifierError);
+    const field = resolveUploadField(deps.registry, input, deps.attachTargets);
+    if (field.kind === "rejected")
+        return field;
+    if (field.kind === "unresolvable") {
+        return rejected("unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload");
+    }
+    const fieldDef = field.kind === "resolved" ? field.fieldDef : undefined;
+    const maxSize = fieldDef?.maxSize || deps.defaultMaxUploadSize;
+    const accept = fieldDef?.accept;
+    const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
+    if (validationError)
+        return rejected(validationError);
+    return acceptFileContent(input, accept);
+}
 // Upload step: validates and writes the binary. Outside any transaction on purpose — network/disk
 // I/O doesn't belong inside a PG connection's tx window.
 export async function writeAcceptedFileBytes(deps, input) {

package/dist/files/dispose-removed-file-refs.js

@@ -1,7 +1,6 @@
-import { isFileField } from "../engine/field-helpers.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
-import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
+import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 // The bound fieldName may differ from the field the id was removed from: an id
 // moved A -> B stays bound to A (binding never re-targets).
@@ -10,15 +9,13 @@ function isBoundToRecord(row, entityName, entityId, fileFields) {
     return (row["entityType"] === entityName &&
         row["entityId"] === entityId &&
         typeof boundField === "string" &&
-        isFileField(fileFields[boundField]));
+        holdsFileRefs(fileFields[boundField]));
 }
 // Across all file fields: an id moved from one field to another is still in use.
 function fileRefIdsStoredInAnyField(fields, data) {
     const ids = new Set();
     for (const [fieldName, fieldDef] of Object.entries(fields)) {
-        if (!isFileField(fieldDef))
-            continue;
-        for (const fileRefId of fileRefIdsOf(data[fieldName]))
+        for (const fileRefId of fileRefIdsInField(fieldDef, data[fieldName]))
             ids.add(fileRefId);
     }
     return ids;
@@ -50,9 +47,9 @@ export async function disposeRemovedFileRefs(args) {
     const executor = getFileRefExecutor();
     const keptAnywhere = fileRefIdsStoredInAnyField(entity.fields, result.data);
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-        if (!isFileField(fieldDef) || !(fieldName in result.changes))
+        if (!holdsFileRefs(fieldDef) || !(fieldName in result.changes))
             continue;
-        for (const fileRefId of fileRefIdsOf(result.previous[fieldName])) {
+        for (const fileRefId of fileRefIdsInField(fieldDef, result.previous[fieldName])) {
             if (keptAnywhere.has(fileRefId))
                 continue;
             const row = await executor.detail({ id: fileRefId }, user, db);

package/dist/files/file-field-slots.d.ts

@@ -0,0 +1,10 @@
+import type { EmbeddedFileSubFieldDef, EmbeddedSubFieldDef, FieldDefinition } from "../engine/types/fields.ts";
+export declare function fileRefIdsOf(value: unknown): readonly string[];
+export declare function isFileSubField(sub: EmbeddedSubFieldDef): sub is EmbeddedFileSubFieldDef;
+/** A field whose value carries FileRef ids: a file field itself, or an embedded field with file sub-fields. */
+export declare function holdsFileRefs(def: FieldDefinition | undefined): boolean;
+/** FileRef ids a field value names. `file_refs.fieldName` stays the top-level field, never the sub-field. */
+export declare function fileRefIdsInField(def: FieldDefinition | undefined, value: unknown): string[];
+/** FileRef ids per file sub-field of an embedded field value, pooled over all rows. */
+export declare function fileRefIdsBySubField(def: FieldDefinition | undefined, value: unknown): ReadonlyMap<string, readonly string[]>;
+export declare function resolveFileSubField(def: FieldDefinition | undefined, subField: string): EmbeddedFileSubFieldDef | undefined;

package/dist/files/file-field-slots.js

@@ -0,0 +1,53 @@
+import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { isFileField } from "../engine/field-helpers.js";
+export 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));
+}
+export function isFileSubField(sub) {
+    return sub.type === "images" || sub.type === "files";
+}
+function fileSubFieldNames(def) {
+    return Object.entries(def.schema).flatMap(([name, sub]) => (isFileSubField(sub) ? [name] : []));
+}
+/** A field whose value carries FileRef ids: a file field itself, or an embedded field with file sub-fields. */
+export function holdsFileRefs(def) {
+    if (def === undefined)
+        return false;
+    if (isFileField(def))
+        return true;
+    return def.type === "embedded" && Object.values(def.schema).some(isFileSubField);
+}
+/** FileRef ids a field value names. `file_refs.fieldName` stays the top-level field, never the sub-field. */
+export function fileRefIdsInField(def, value) {
+    if (def === undefined)
+        return [];
+    if (isFileField(def))
+        return [...fileRefIdsOf(value)];
+    if (def.type !== "embedded")
+        return [];
+    const subNames = fileSubFieldNames(def);
+    const rows = Array.isArray(value) ? value : [value];
+    return rows.flatMap((row) => isPlainObject(row) ? subNames.flatMap((name) => fileRefIdsOf(row[name])) : []);
+}
+/** FileRef ids per file sub-field of an embedded field value, pooled over all rows. */
+export function fileRefIdsBySubField(def, value) {
+    const bySubField = new Map();
+    if (def?.type !== "embedded")
+        return bySubField;
+    const rows = Array.isArray(value) ? value : [value];
+    for (const name of fileSubFieldNames(def)) {
+        bySubField.set(name, rows.flatMap((row) => (isPlainObject(row) ? fileRefIdsOf(row[name]) : [])));
+    }
+    return bySubField;
+}
+export function resolveFileSubField(def, subField) {
+    if (def?.type !== "embedded")
+        return undefined;
+    const sub = def.schema[subField];
+    return sub !== undefined && isFileSubField(sub) ? sub : undefined;
+}

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

@@ -19,7 +19,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly default?: number;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly entityType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {

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

@@ -18,7 +18,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly default?: number;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly entityType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {

package/dist/files/file-routes.js

@@ -17,6 +17,7 @@ import { listActionFormFileFields, mayUseActionForm } from "./action-form-upload
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
 import { createDefaultGuard, DEFAULT_PRIVILEGED_ROLES } from "./default-file-guard.js";
+import { isFileSubField } from "./file-field-slots.js";
 import { createFileContext, createTenantFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
@@ -48,6 +49,12 @@ const BATCH_META_CONCURRENCY = 10;
 // Multipart framing plus the small entityType/entityId/fieldName parts
 // riding alongside the file.
 const MULTIPART_OVERHEAD_MARGIN_BYTES = 64 * 1024;
+function fileFieldMaxSizes(field) {
+    if (field.type === "embedded") {
+        return Object.values(field.schema).flatMap((sub) => isFileSubField(sub) && sub.maxSize ? [sub.maxSize] : []);
+    }
+    return isFileField(field) && field.maxSize ? [field.maxSize] : [];
+}
 // 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.
@@ -55,8 +62,8 @@ 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));
+            for (const maxSize of fileFieldMaxSizes(field)) {
+                maxBytes = Math.max(maxBytes, parseMaxSize(maxSize));
             }
         }
     }
@@ -162,6 +169,7 @@ 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;
+        const subField = typeof body["subField"] === "string" ? body["subField"] : undefined;
         const actionForm = typeof body["actionForm"] === "string" ? body["actionForm"] : undefined;
         if (isAnonymous &&
             !isAnonymousPendingUploadAllowed(options.registry, {
@@ -197,7 +205,7 @@ export function createFileRoutes(options) {
             const decision = options.registry !== undefined && options.registry.getEntity(entityType) === undefined
                 ? RecordWriteDecisions.writable
                 : options.canWriteRecord
-                    ? await options.canWriteRecord({ entityType, entityId, fieldName, user })
+                    ? await options.canWriteRecord({ entityType, entityId, fieldName, subField, user })
                     : RecordWriteDecisions.forbidden;
             switch (decision) {
                 case RecordWriteDecisions.writable:
@@ -235,6 +243,7 @@ export function createFileRoutes(options) {
             entityType,
             entityId,
             fieldName,
+            subField,
             actionForm,
         });
         if (outcome.kind === "rejected")

package/dist/files/index.d.ts

@@ -8,6 +8,7 @@ export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytes
 export { createDefaultGuard } from "./default-file-guard.ts";
 export { deleteFileRefsBoundToRecord } from "./delete-record-file-refs.ts";
 export { createFilesFeature, FILES_FEATURE } from "./feature.ts";
+export { holdsFileRefs } from "./file-field-slots.ts";
 export type { FileContext } from "./file-handle.ts";
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.ts";
 export { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.ts";
@@ -19,6 +20,8 @@ export { createInMemoryFileProvider } from "./in-memory-provider.ts";
 export { createLocalProvider } from "./local-provider.ts";
 export type { FileProviderContext, FileProviderPlugin, FileProviderResolver, } from "./provider-resolver.ts";
 export { createFileProviderForTenant, isFileProviderPlugin, } from "./provider-resolver.ts";
+export type { FileRefOwner, RebindFileRefContext, RebindFileRefOutcome, } from "./rebind-file-ref.ts";
+export { rebindFileRef } from "./rebind-file-ref.ts";
 export { filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.ts";
 export type { FileStorageProvider, SignedUrlOptions, } from "./types.ts";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.ts";

package/dist/files/index.js

@@ -5,6 +5,7 @@ export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytes
 export { createDefaultGuard } from "./default-file-guard.js";
 export { deleteFileRefsBoundToRecord } from "./delete-record-file-refs.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";
+export { holdsFileRefs } from "./file-field-slots.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.js";
@@ -14,6 +15,7 @@ export { configuredMaxUploadBytes, readFilesRouteOptions, resolveMaxUploadBodyBy
 export { createInMemoryFileProvider } from "./in-memory-provider.js";
 export { createLocalProvider } from "./local-provider.js";
 export { createFileProviderForTenant, isFileProviderPlugin, } from "./provider-resolver.js";
+export { rebindFileRef } from "./rebind-file-ref.js";
 export { filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.js";
 export { fileUploadLedgerTable, withUploadLedger, } from "./upload-ledger.js";

package/dist/files/load-save-file-refs.js

@@ -1,8 +1,7 @@
 import { selectMany } from "../db/query.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
-import { isFileField } from "../engine/field-helpers.js";
 import { getStreamVersions } from "../event-store/event-store.js";
-import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 // One query for every fileRef a save names, restricted to the writer's own tenant and live
@@ -19,9 +18,9 @@ export async function loadSaveFileRefs(args) {
         return new Map();
     const ids = new Set();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-        if (!isFileField(fieldDef))
+        if (!holdsFileRefs(fieldDef))
             continue;
-        for (const id of fileRefIdsOf(result.changes[fieldName]))
+        for (const id of fileRefIdsInField(fieldDef, result.changes[fieldName]))
             ids.add(id);
     }
     return loadFileRefRows(db, [...ids], user.tenantId);

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

@@ -0,0 +1,41 @@
+import type { TenantDb } from "../db/tenant-db.ts";
+import type { Registry, SessionUser } from "../engine/types/index.ts";
+import { type CanReadFileRefContext } from "./can-caller-read-file-ref.ts";
+export type RebindFileRefContext = {
+    readonly db: TenantDb;
+    readonly registry: Registry;
+    readonly user: SessionUser;
+    readonly dispatch?: CanReadFileRefContext["dispatch"];
+};
+export type FileRefOwner = {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly fieldName: string;
+};
+export type RebindFileRefOutcome = "rebound" | "not-found" | "moved" | "version-conflict";
+/**
+ * Moves a bound file from one record's file field to another's, for a record that takes over a
+ * file uploaded elsewhere (an upload record, a mail attachment). Server code only; pending uploads
+ * go through bindPendingFileRef.
+ *
+ * Only files of the caller's tenant are found ("not-found" otherwise, as for unknown ids). The
+ * file must still sit at `from`; "moved" means it does not (any more), for example because a
+ * parallel rebind took it first. A file already at `to` answers "rebound" without a write. The
+ * target must be a registered file field whose accept/maxSize the file fits (InternalError /
+ * UnprocessableError). Unless the caller is the framework system user, the caller must be able
+ * to read the file and to write both the source record and field (it must not be locked, and an
+ * entity without update handler leaves the move to the system user) and the target record and
+ * field (AccessDeniedError, RecordLockedError); the system user skips these checks, and only the
+ * target record has to exist (NotFoundError). The update is checked against the file's stream
+ * version read here, so a bind committing in between returns "version-conflict"; the source row
+ * stays locked until the surrounding transaction commits, so a lock set on `from` in between is
+ * either seen or waits. Rebind first, then save the id into
+ * the target field: the save accepts a file already bound to that record, and the source record
+ * no longer disposes of it when its field is cleared or the record is deleted.
+ * A handler passes its ctx; a job passes `{ db, registry, user: ctx.systemUser }`.
+ */
+export declare function rebindFileRef(ctx: RebindFileRefContext, args: {
+    readonly fileRefId: string;
+    readonly from: FileRefOwner;
+    readonly to: FileRefOwner;
+}): Promise<RebindFileRefOutcome>;

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

@@ -0,0 +1,170 @@
+import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
+import { isFrameworkSystemUser } from "../db/lock-guard.js";
+import { selectRowForUpdateById } from "../db/queries/entity-read.js";
+import { asEntityTableMeta } from "../db/table-introspection.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { RecordLockedError } from "../errors/classes.js";
+import { AccessDeniedError, InternalError, NotFoundError, reraiseAsKumikoError, } from "../errors/index.js";
+import { assertRowFitsBindTarget } from "./bind-pending-file-refs.js";
+import { canCallerReadFileRef } from "./can-caller-read-file-ref.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { loadFileRefRows } from "./load-save-file-refs.js";
+import { createRecordReadCheck } from "./record-read-check.js";
+import { createRecordWriteCheck, findImplicitEntityTable, RecordWriteDecisions, } from "./record-write-check.js";
+const CONCURRENT_WRITE_ERROR_CODES = ["version_conflict", "unique_violation"];
+function nullableString(value) {
+    return value === null || typeof value === "string";
+}
+// The file guard (and an app's accessGuard) reads these columns; a row missing one is corrupt.
+async function loadRow(ctx, fileRefId) {
+    if (!isUuid(fileRefId))
+        return undefined;
+    const row = (await loadFileRefRows(ctx.db, [fileRefId], ctx.user.tenantId)).get(fileRefId);
+    if (row === undefined)
+        return undefined;
+    const { tenantId, storageKey, fileName, mimeType, size, entityType, entityId, fieldName } = row;
+    const { insertedById, version } = row;
+    if (typeof tenantId !== "string" ||
+        typeof storageKey !== "string" ||
+        typeof fileName !== "string" ||
+        typeof mimeType !== "string" ||
+        typeof size !== "number" ||
+        typeof version !== "number" ||
+        !nullableString(entityType) ||
+        !nullableString(entityId) ||
+        !nullableString(fieldName) ||
+        !nullableString(insertedById)) {
+        return undefined;
+    }
+    return {
+        fileRef: {
+            id: fileRefId,
+            tenantId,
+            storageKey,
+            fileName,
+            mimeType,
+            size,
+            entityType,
+            entityId,
+            fieldName,
+            insertedById,
+        },
+        version,
+    };
+}
+function isOwnedBy(fileRef, owner) {
+    return (fileRef.entityType === owner.entityType &&
+        fileRef.entityId === owner.entityId &&
+        fileRef.fieldName === owner.fieldName);
+}
+// Holds the source row until commit, so a lock or ownership change committed by another
+// transaction is either seen by the write check below or waits for this rebind to finish.
+async function lockSourceRow(ctx, from) {
+    const table = findImplicitEntityTable(ctx.registry, from.entityType);
+    const tableName = asEntityTableMeta(table)?.tableName;
+    // skip: no stored row to lock; the write check below answers not_found for it
+    if (tableName === undefined)
+        return;
+    await selectRowForUpdateById(tenantDbRunner(ctx.db), tableName, from.entityId);
+}
+// A caller other than the system job must be able to read the file today and must be able to
+// write both records as a save of them would: the source it takes the file from (unlocked, and
+// with an update handler the caller passes; without one only the system job may move the file),
+// and the target field it puts the file into.
+async function assertCallerMayMove(ctx, fileRef, from, to) {
+    if (!(await canCallerReadFileRef(ctx, fileRef))) {
+        throw new AccessDeniedError({ message: `rebindFileRef: file ${fileRef.id} is not readable` });
+    }
+    const canWriteRecord = createRecordWriteCheck({
+        registry: ctx.registry,
+        canReadRecord: createRecordReadCheck(ctx.registry, (qn, payload) => ctx.dispatch.query(qn, payload)),
+        tenantDbFor: () => ctx.db,
+    });
+    await lockSourceRow(ctx, from);
+    const sourceDecision = await canWriteRecord({ ...from, user: ctx.user });
+    if (sourceDecision === RecordWriteDecisions.locked) {
+        throw new RecordLockedError({ entityName: from.entityType, entityId: from.entityId });
+    }
+    if (sourceDecision !== RecordWriteDecisions.writable) {
+        throw new AccessDeniedError({
+            message: `rebindFileRef: source ${from.entityType}.${from.fieldName} of ${from.entityId} is not writable`,
+            details: { decision: sourceDecision },
+        });
+    }
+    const decision = await canWriteRecord({ ...to, user: ctx.user });
+    if (decision !== RecordWriteDecisions.writable) {
+        throw new AccessDeniedError({
+            message: `rebindFileRef: ${to.entityType}.${to.fieldName} of ${to.entityId} is not writable`,
+            details: { decision },
+        });
+    }
+}
+// The caller checks find the target as a side effect; the system path needs its own lookup so a
+// job cannot point a file at a record that does not exist in its tenant.
+async function assertTargetRecordExists(ctx, to) {
+    const entity = ctx.registry.getEntity(to.entityType);
+    const table = findImplicitEntityTable(ctx.registry, to.entityType);
+    const row = entity === undefined || table === undefined
+        ? undefined
+        : await ctx.db.fetchOne(table, {
+            id: to.entityId,
+            ...(entity.softDelete === true && { isDeleted: false }),
+        });
+    if (row === undefined)
+        throw new NotFoundError(to.entityType, to.entityId);
+}
+/**
+ * Moves a bound file from one record's file field to another's, for a record that takes over a
+ * file uploaded elsewhere (an upload record, a mail attachment). Server code only; pending uploads
+ * go through bindPendingFileRef.
+ *
+ * Only files of the caller's tenant are found ("not-found" otherwise, as for unknown ids). The
+ * file must still sit at `from`; "moved" means it does not (any more), for example because a
+ * parallel rebind took it first. A file already at `to` answers "rebound" without a write. The
+ * target must be a registered file field whose accept/maxSize the file fits (InternalError /
+ * UnprocessableError). Unless the caller is the framework system user, the caller must be able
+ * to read the file and to write both the source record and field (it must not be locked, and an
+ * entity without update handler leaves the move to the system user) and the target record and
+ * field (AccessDeniedError, RecordLockedError); the system user skips these checks, and only the
+ * target record has to exist (NotFoundError). The update is checked against the file's stream
+ * version read here, so a bind committing in between returns "version-conflict"; the source row
+ * stays locked until the surrounding transaction commits, so a lock set on `from` in between is
+ * either seen or waits. Rebind first, then save the id into
+ * the target field: the save accepts a file already bound to that record, and the source record
+ * no longer disposes of it when its field is cleared or the record is deleted.
+ * A handler passes its ctx; a job passes `{ db, registry, user: ctx.systemUser }`.
+ */
+export async function rebindFileRef(ctx, args) {
+    const { fileRefId, from, to } = args;
+    const loaded = await loadRow(ctx, fileRefId);
+    if (loaded === undefined)
+        return "not-found";
+    const { fileRef, version } = loaded;
+    if (isOwnedBy(fileRef, to))
+        return "rebound";
+    if (!isOwnedBy(fileRef, from))
+        return "moved";
+    assertRowFitsBindTarget(ctx.registry, { entityName: to.entityType, fieldName: to.fieldName }, fileRef);
+    if (isFrameworkSystemUser(ctx.user)) {
+        await assertTargetRecordExists(ctx, to);
+    }
+    else {
+        const { dispatch } = ctx;
+        if (dispatch === undefined) {
+            throw new InternalError({
+                message: "rebindFileRef: a caller other than the system user needs ctx.dispatch.query",
+            });
+        }
+        await assertCallerMayMove({ ...ctx, dispatch }, fileRef, from, to);
+    }
+    const moved = await getFileRefExecutor().update({
+        id: fileRefId,
+        version,
+        changes: { entityType: to.entityType, entityId: to.entityId, fieldName: to.fieldName },
+    }, ctx.user, ctx.db);
+    if (moved.isSuccess)
+        return "rebound";
+    if (CONCURRENT_WRITE_ERROR_CODES.includes(moved.error.code))
+        return "version-conflict";
+    throw reraiseAsKumikoError(moved.error);
+}