@cosmicdrift/kumiko-framework 0.358.0 → 0.360.0

package/dist/engine/build-app-schema.js

@@ -281,7 +281,16 @@ function projectScreens(featureName, screens, registry, urlPrefillFieldsByScreen
                 ...entityEditWriteExcludedFields(featureName, screen.entity, registry),
             };
         }
-        if (screen.type === "actionForm" || screen.type === "secretMint") {
+        if (screen.type === "actionForm") {
+            const { writeExcludedFields: _authoredExclusions, ...authoredScreen } = screen;
+            const excluded = registry.getWriteHandler(screen.handler)?.excludedFields;
+            return {
+                ...authoredScreen,
+                urlPrefillFields: sortedUrlPrefillFields(urlPrefillFieldsByScreenQn.get(qualifyEntityName(featureName, "screen", shortId))),
+                ...(excluded !== undefined && { writeExcludedFields: excluded }),
+            };
+        }
+        if (screen.type === "secretMint") {
             return {
                 ...screen,
                 urlPrefillFields: sortedUrlPrefillFields(urlPrefillFieldsByScreenQn.get(qualifyEntityName(featureName, "screen", shortId))),
@@ -514,7 +523,7 @@ function projectField(fieldDef) {
     // date/timestamp/locatedTimestamp: display/parsing locale override (fw#2497).
     if (typeof def["locale"] === "string")
         out["locale"] = def["locale"];
-    // image: which camera a mobile capture opens (fw#2497).
+    // image/images: which camera a mobile capture opens (fw#2497).
     if (typeof def["capture"] === "string")
         out["capture"] = def["capture"];
     // number: display-only suffix, static or read from a sibling field of the row.

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">;