@cosmicdrift/kumiko-framework 0.358.0 → 0.360.0

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.

package/dist/files/record-read-check.d.ts

@@ -0,0 +1,9 @@
+import type { Registry, SessionUser } from "../engine/types/index.js";
+export type RecordReadCheck = (args: {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly user: SessionUser;
+}) => Promise<boolean>;
+type QueryAsUser = (type: string, payload: unknown, user: SessionUser) => Promise<unknown>;
+export declare function createRecordReadCheck(registry: Registry, query: QueryAsUser): RecordReadCheck;
+export {};

package/dist/files/record-read-check.js

@@ -0,0 +1,49 @@
+import { toKebab } from "../engine/qualified-name.js";
+import { isKumikoError } from "../errors/index.js";
+import { createFallbackLogger } from "../logging/index.js";
+const log = createFallbackLogger("files");
+// Only the "<entity>:detail" handler counts: other "<entity>:...:detail"
+// queries map to the same entity but may return a different shape or scope.
+// Entity names are globally unique and only the owning feature maps handlers
+// to its entity, so at most one QN matches per entity.
+function isEntityDetailQuery(qn, entityName) {
+    return qn.endsWith(`:query:${toKebab(entityName)}:detail`);
+}
+function buildDetailQueryIndex(registry) {
+    const detailQueryByEntity = new Map();
+    for (const qn of registry.getAllQueryHandlers().keys()) {
+        const entityName = registry.getHandlerEntity(qn);
+        if (entityName !== undefined && isEntityDetailQuery(qn, entityName)) {
+            detailQueryByEntity.set(entityName, qn);
+        }
+    }
+    return detailQueryByEntity;
+}
+// "May this user read the record?" is answered by the entity's own detail
+// query run as that user: handler access, row ownership and parent visibility
+// all apply, exactly as when the record is opened. null (not found or not
+// visible) and access errors mean no. Entities without a detail query never
+// grant access this way.
+export function createRecordReadCheck(registry, query) {
+    let detailQueryByEntity;
+    return async ({ entityType, entityId, user }) => {
+        detailQueryByEntity ??= buildDetailQueryIndex(registry);
+        const detailQuery = detailQueryByEntity.get(entityType);
+        if (detailQuery === undefined)
+            return false;
+        try {
+            const record = await query(detailQuery, { id: entityId }, user);
+            return record !== null && record !== undefined;
+        }
+        catch (error) {
+            if (!isKumikoError(error) || error.httpStatus >= 500) {
+                log.error("record read check failed; file access denied", {
+                    entityType,
+                    detailQuery,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return false;
+        }
+    };
+}

package/dist/jobs/cron-repeat-options.d.ts

@@ -0,0 +1,9 @@
+export type CronTrigger = {
+    readonly cron: string;
+    readonly tz?: string | undefined;
+};
+export type CronRepeatOptions = {
+    readonly pattern: string;
+    readonly tz?: string;
+};
+export declare function cronRepeatOptions(trigger: CronTrigger): CronRepeatOptions;

package/dist/jobs/cron-repeat-options.js

@@ -0,0 +1,5 @@
+export function cronRepeatOptions(trigger) {
+    return trigger.tz === undefined
+        ? { pattern: trigger.cron }
+        : { pattern: trigger.cron, tz: trigger.tz };
+}

package/dist/jobs/job-runner.js

@@ -17,6 +17,7 @@ import { RedisKeys } from "../pipeline/redis-keys.js";
 import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
 import { buildPersonalDataGate, isPersonalDataGated, parseWriteOrigin, } from "../pipeline/write-origin.js";
 import { bridgeStub } from "../testing/handler-context.js";
+import { cronRepeatOptions } from "./cron-repeat-options.js";
 // Shape-checked after the BullMQ/Redis JSON round-trip. Unlike `_writeOrigin`
 // (a security-relevant escape hatch that must fail the run closed), a
 // malformed `_triggerEvent` only costs an idempotency-key convenience — the
@@ -1154,7 +1155,7 @@ export function createJobRunner(options) {
                 if ("cron" in jobDef.trigger) {
                     const schedulerId = schedulerIdForJobName(name);
                     expectedSchedulerIds.add(schedulerId);
-                    await consumerQueue.upsertJobScheduler(schedulerId, { pattern: jobDef.trigger.cron }, {
+                    await consumerQueue.upsertJobScheduler(schedulerId, cronRepeatOptions(jobDef.trigger), {
                         name: jobDef.perTenant ? `_perTenant:${name}` : name,
                         data: {},
                         // Queue-level defaultJobOptions (jobRetentionOpts) covers

package/dist/pipeline/dispatch-write.js

@@ -8,6 +8,7 @@ import { checkWriteFieldOwnership, maskWriteOnlyFields } from "../engine/field-a
 import { defineTransitions, guardTransition } from "../engine/state-machine.js";
 import { HookPhases } from "../engine/types/index.js";
 import { AccessDeniedError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, NotFoundError, ValidationError, writeFailure, } from "../errors/index.js";
+import { bindPendingFileRefs } from "../files/bind-pending-file-refs.js";
 import { CACHE_SYNC_TOPICS } from "../redis/cache-sync-topics.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
@@ -111,6 +112,12 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
     // keeps projection state consistent with what the hooks observe.
     await runProjections(result, handlerContext.registry, runner);
     if (result.kind === "save") {
+        await bindPendingFileRefs({
+            registry: handlerContext.registry,
+            result,
+            user,
+            db: handlerContext.db,
+        });
         await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
             const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.358.0",
+  "version": "0.360.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -210,8 +210,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.358.0",
-    "@cosmicdrift/kumiko-types": "0.358.0",
+    "@cosmicdrift/kumiko-http": "0.360.0",
+    "@cosmicdrift/kumiko-types": "0.360.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,7 +227,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.358.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.360.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "0.360.0",
+    "type": "breaking",
+    "title": "Secure host-only session cookies use the __Host- prefix",
+    "detail": "Auth, csrf and tenant cookies are named __Host-kumiko_auth, __Host-kumiko_csrf and __Host-kumiko_tenant when they are written Secure and without a Domain (the tenant cookie is always host-only). With auth.cookieDomain or without Secure the auth and csrf names stay kumiko_auth and kumiko_csrf. New auth option secureCookies forces Secure (default NODE_ENV === \"production\"). Login deletes the legacy unprefixed host-only cookies, logout and deleteTenantCookie delete the prefixed and the legacy names. The server reads only the resolved names, so a request that carries only the legacy kumiko_auth is anonymous. AUTH_COOKIE_NAME, CSRF_COOKIE_NAME and TENANT_COOKIE_NAME are removed from the framework and dispatcher-live; the base names and sessionCookieName() are exported from @cosmicdrift/kumiko-types/session-cookies and @cosmicdrift/kumiko-framework/api, getSessionCookies(c) returns the resolved names of a request. The testing package's CSRF_COOKIE_NAME stays and resolves to the unprefixed name (e2e servers run without Secure).",
+    "migration": "Every user logs in once after the deploy, because the old kumiko_auth cookie is no longer read. Custom clients, proxies or scripts that read or forward the cookies by literal name break: read the names through sessionCookieName() / resolveSessionCookieNames() (types package) or getSessionCookies(c) on the server, and handle both the prefixed and the plain name in browser code (readCsrfToken() already does). Replace imports of AUTH_COOKIE_NAME, CSRF_COOKIE_NAME and TENANT_COOKIE_NAME with AUTH_COOKIE_BASE, CSRF_COOKIE_BASE and TENANT_COOKIE_BASE plus sessionCookieName(); e2e helpers that imported CSRF_COOKIE_NAME from @cosmicdrift/kumiko-dispatcher-live import it from @cosmicdrift/kumiko-testing/e2e instead (known: solon e2e/_helpers/api.ts and e2e/session-ended.spec.ts, kumiko-enterprise ai-agent-live-transcription.integration.test.ts uses AUTH_COOKIE_NAME). A reverse proxy that strips or rewrites cookie names must pass the __Host- names unchanged. Staging or preview deployments over plain http need no change (Secure is off there); set auth.secureCookies (also accepted by runProdApp) explicitly when TLS terminates before the app and NODE_ENV is not \"production\". A standalone createAuthRoutes mount outside buildServer must also mount sessionCookiesMiddleware with the same resolved names, otherwise the readers fall back to the domain-less default."
+  },
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "Duplicate session cookie names end the cookie session",
+    "detail": "When the Cookie header carries the resolved auth or csrf cookie name more than once, authMiddleware ignores the cookie transport and expires every variant (prefixed host-only, legacy host-only, the cookieDomain variant and retired domains). With anonymousAccess the request continues as anonymous, otherwise it gets 401 missing_token; a Bearer token on the same request still authenticates. A prefixed and a legacy name side by side are not a duplicate. The cookie clearing moved from the auth routes into clearSessionCookies in session-cookies.ts; ResolvedSessionCookies carries domain and retiredDomains."
+  },
+  {
+    "version": "0.360.0",
+    "type": "breaking",
+    "title": "Origin guard defaults on when the public app URL is known",
+    "detail": "New auth option publicOrigin. Without allowedOrigins, cookieDomain and unsafeSkipOriginCheck, buildServer mounts the Origin guard for cookie-authenticated state-changing /api requests and admits publicOrigin plus the request's own host (Host header). runProdApp sets publicOrigin from auth.publicOrigin, then auth.mail.baseUrl, then the APP_BASE_URL env (origin only, path dropped); with none of them in production it logs a warning that the Origin guard is off and boots anyway. allowedOrigins keeps its strict meaning, and the WebSocket check and the anonymous downgrade still use only allowedOrigins.",
+    "migration": "Cookie-authenticated POST, PUT, PATCH or DELETE requests from a page on another origin than the public app URL and than the API host itself now get 403 origin_not_allowed in runProdApp deployments that set auth.mail.baseUrl or APP_BASE_URL. A web client served from a different host than the API (for example a sibling subdomain) must list its origin in auth.allowedOrigins. Same-host setups, custom domains served by the same server and Bearer clients need no change."
+  },
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "createFileRefFromBytes creates FileRefs from handler- or job-produced bytes",
+    "detail": "createFileRefFromBytes({ db, files, registry, user }, { fileName, mimeType, data, attachTo? }) shares one pipeline with POST /api/files, so identifier checks, field-level maxSize/accept, content sniffing, MIME resolution, the tenant-prefixed storage key and the fileRef.created event are identical. The tenant always comes from ctx.user. A rejected file returns a 422 write failure with reason file_rejected and the upload error string in details.error. The FileRef's insertedById is the passed user, so the default access guard lets only that user and privileged roles read files attached to an entity."
+  },
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "Cron jobs with an IANA time zone, images fields with capture",
+    "detail": "A cron trigger accepts tz (IANA name; without it the server process zone applies) and is scheduled in that zone, DST included. r.job() throws at boot for an invalid zone. createImagesField accepts capture (\"environment\" | \"user\") like createImageField, and the edit view model carries it for images fields."
+  },
+  {
+    "version": "0.360.0",
+    "type": "breaking",
+    "title": "Uploads from an update form are attached to the record",
+    "detail": "computeEditViewModel accepts entityId (the record being edited, update mode only) and sets it on the hints of file, image, files and images fields; RenderEdit passes the id it was mounted with and the file input sends it as the entityId multipart part of POST /api/files. Create forms send no entityId; after a successful create the write pipeline binds the caller's own pending uploads named in the record's file fields (same entityType and fieldName, entityId null, insertedById = caller) to the new record via a fileRef.updated event in the same transaction, for single and plural file fields alike, when the files feature (fileRef entity) is mounted. Behaviour change: such files are now attached to the record. The default file access guard allows read on an attached file to the uploader, privilegedRoles (default Admin/SystemAdmin) and everyone whose run of the entity's <entity>:detail query returns the record; delete stays uploader and privilegedRoles only. A qr-overlay variant of an image field no longer throws for a file uploaded from an update or create form. Write-form sections send no entityId. EmbeddedListInput has a new required actionsLabel prop.",
+    "migration": "Files attached through forms now follow the record's read access instead of being tenant-wide: anyone who cannot read the record no longer reads the file, anyone who can read it does. Check image, images, file and files fields whose files must be visible beyond the record's readers (for example an avatar shown in lists to users without detail access) and add those roles to privilegedRoles or set accessGuard in the files feature options. An entity without a detail query falls back to uploader plus privilegedRoles. Files uploaded before the update keep their old attachment. Custom primitive sets that implement EmbeddedListInput accept the new actionsLabel prop and render it as the actions column header; custom file/image Input primitives forward entityId into the upload and offer a remove control that calls onChange(null)."
+  },
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "images and files fields get an edit widget; required is allowed",
+    "detail": "NO_WIDGET_FIELD_TYPES now holds only jsonb and embedded. required true on an images or files field passes boot validation and the client-side check treats an empty array as missing. The edit view model carries maxCount for files and images fields."
+  },
+  {
+    "version": "0.359.0",
+    "type": "improvement",
+    "title": "actionForm screens honour the called handler's excludedFields",
+    "detail": "buildAppSchema projects the handler's excludedFields onto actionForm screens as writeExcludedFields (a flat list, unlike entityEdit's per-verb object). The form shows these fields read-only, not required and never in the payload.",
+    "migration": "Drop a hand-written readOnly lock on an actionForm field once the handler it calls declares excludedFields for it."
+  },
   {
     "version": "0.358.0",
     "type": "fix",