@cosmicdrift/kumiko-bundled-features 0.193.0 → 0.194.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.193.0",
+  "version": "0.194.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -125,12 +125,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.193.0",
-    "@cosmicdrift/kumiko-framework": "0.193.0",
-    "@cosmicdrift/kumiko-headless": "0.193.0",
-    "@cosmicdrift/kumiko-renderer": "0.193.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.193.0",
-    "@cosmicdrift/kumiko-types": "0.193.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.194.0",
+    "@cosmicdrift/kumiko-framework": "0.194.0",
+    "@cosmicdrift/kumiko-headless": "0.194.0",
+    "@cosmicdrift/kumiko-renderer": "0.194.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.194.0",
+    "@cosmicdrift/kumiko-types": "0.194.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",

package/src/channel-email/smtp-transport.ts

@@ -35,10 +35,10 @@ export type SmtpTransportOptions = {
     readonly user: string;
     readonly pass: string;
   };
-  /** Default From-Adresse, app-weit. Eine einzelne Mail kann sie über
-   *  `EmailMessage.from` überschreiben (Reply aus einem bestimmten
-   *  Postfach); ohne Override greift diese. Format akzeptiert beides:
-   *  "noreply@ex.com" oder "Name <noreply@ex.com>". */
+  /** App-wide default From. A single send can override it via
+   *  `EmailMessage.from` (reply from a specific mailbox); without an
+   *  override this applies. Accepts both "noreply@ex.com" and
+   *  "Name <noreply@ex.com>". */
   readonly from: string;
 };
 

package/src/derivatives-sharp/__tests__/render.test.ts

@@ -216,6 +216,25 @@ describe("renderImage — validation", () => {
     const meta = await sharp(output).metadata();
     expect(meta.format).toBe("webp");
   });
+
+  test("a sourceMimeType matching an inherited Object.prototype key throws instead of using it as an encoder", async () => {
+    // Plain-object lookup on SOURCE_FORMAT_ENCODERS would resolve
+    // "constructor" to Object (an inherited key, not a real entry) without
+    // an Object.hasOwn guard — proving the throw path, not a silent pass-through.
+    const input = await unmappedFormatFixture(50, 50);
+    await expect(renderImage(input, {}, "constructor")).rejects.toThrow(/no output encoder/);
+  });
+
+  test("image/png ignores spec.quality instead of switching into lossy palette quantization", async () => {
+    const input = await pngFixture(50, 50);
+    const withQuality = await renderImage(input, { quality: 10 }, "image/png");
+    const withoutQuality = await renderImage(input, {}, "image/png");
+    const withQualityMeta = await sharp(withQuality).metadata();
+    // A quality-driven palette encode would quantize to a small color count;
+    // an ignored quality keeps the full-color (non-palette) PNG.
+    expect(withQualityMeta.format).toBe("png");
+    expect(Buffer.compare(withQuality, withoutQuality)).toBe(0);
+  });
 });
 
 describe("imageMetadata", () => {

package/src/derivatives-sharp/render.ts

@@ -98,7 +98,10 @@ const SOURCE_FORMAT_ENCODERS: Record<string, (pipeline: Sharp, quality?: number)
   // The upload whitelist admits the sloppy-but-common image/jpg alias
   "image/jpg": (pipeline, quality) =>
     pipeline.jpeg(quality !== undefined ? { quality } : undefined),
-  "image/png": (pipeline, quality) => pipeline.png(quality !== undefined ? { quality } : undefined),
+  // sharp's PngOptions.quality doesn't mean JPEG/WebP-style compression —
+  // it switches PNG into palette quantization (lossless -> color-reduced,
+  // banding instead of a softer/smaller image). Ignore it, same as gif.
+  "image/png": (pipeline) => pipeline.png(),
   "image/webp": (pipeline, quality) =>
     pipeline.webp(quality !== undefined ? { quality } : undefined),
   "image/avif": (pipeline, quality) =>
@@ -125,7 +128,7 @@ function applyEncoder(pipeline: Sharp, spec: VariantSpec, sourceMimeType: string
   }
 
   const encode = SOURCE_FORMAT_ENCODERS[sourceMimeType];
-  if (!encode) {
+  if (!Object.hasOwn(SOURCE_FORMAT_ENCODERS, sourceMimeType) || encode === undefined) {
     throw new Error(
       `derivatives-sharp: no output encoder for source mimeType "${sourceMimeType}" — set spec.format to pick an explicit output format.`,
     );

package/src/file-derivatives/__tests__/public-variant-route.integration.test.ts

@@ -1,13 +1,15 @@
 // Proves GET {basePath}/:fileRefId/:variant end-to-end: anonymous, no
 // Authorization header, tenant resolved ONLY from Host (never the payload),
 // default-deny when no `derivativePublicPredicate` is registered for the
-// FileRef's entityType (or it returns false), the fixed preset-name
-// pre-check running BEFORE any DB/systemQuery work, and the Step-1
-// requestContext fix that makes `rateLimit: {per: "ip"}` actually gate an
-// r.httpRoute handler invoked via systemQuery (#1951).
+// FileRef's entityType (or it returns false), the variant spec resolving
+// from the FileRef's field declaration (not a fixed preset map, #1985), and
+// the Step-1 requestContext fix that makes `rateLimit: {per: "ip"}` actually
+// gate an r.httpRoute handler invoked via systemQuery (#1951).
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import {
+  createEntity,
+  createImageField,
   defineFeature,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
   EXT_DERIVATIVE_RENDERER,
@@ -26,7 +28,10 @@ import {
   buildMultipartBody,
   patchFileInstanceofForBunTest,
 } from "@cosmicdrift/kumiko-framework/testing";
-import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type {
+  DerivativeRendererPlugin,
+  VariantSpec,
+} from "@cosmicdrift/kumiko-types/derivatives-types";
 import { createConfigFeature } from "../../config";
 import { fileFoundationFeature } from "../../file-foundation";
 import { createFileDerivativesFeature } from "../feature";
@@ -35,16 +40,43 @@ import type { DerivativePublicPredicateArgs } from "../handlers/public-variant.q
 const VARIANT_BYTES = new Uint8Array([7, 7, 7]);
 
 let renderCalls = 0;
-const fakeRender: DerivativeRendererPlugin["render"] = async () => {
+let lastRenderSpec: VariantSpec | null = null;
+const fakeRender: DerivativeRendererPlugin["render"] = async (_input, spec) => {
   renderCalls++;
+  lastRenderSpec = spec;
   return VARIANT_BYTES;
 };
 
 const PUBLIC_WIDGET_ID = "widget-public";
 const OTHER_WIDGET_ID = "widget-other";
 
+// `full` deliberately overrides the built-in preset's maxEdge (2560) — this
+// is what proves the route resolves the spec from the field declaration
+// (#1985), not from the frozen preset constants. `plan` is a name with no
+// preset counterpart at all — the exact motivating case from #1985 (an app
+// declaring its own variant name). `heroWide` uses characters (uppercase,
+// underscore-adjacent camelCase) outside a naive `[a-z0-9-]` guard — the
+// `variants` map has no runtime charset constraint, so the route's
+// syntactic pre-check must not narrow it. `plain` has no variants at all,
+// for the "field declares no variants" 404 case.
+const widgetEntity = createEntity({
+  table: "public_variant_widgets",
+  fields: {
+    img: createImageField({
+      variants: {
+        thumb: { maxEdge: 160, format: "webp" },
+        full: { maxEdge: 4096, format: "webp" },
+        plan: { maxEdge: 4096, format: "webp" },
+        heroWide: { maxEdge: 3200, format: "webp" },
+      },
+    }),
+    plain: createImageField(),
+  },
+});
+
 let predicateCalls = 0;
 const widgetPredicateFeature = defineFeature("publicvariantroutetest", (r) => {
+  r.entity("widget", widgetEntity);
   r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "widget", {
     isPublic: (args: DerivativePublicPredicateArgs) => {
       predicateCalls++;
@@ -91,6 +123,7 @@ afterAll(async () => {
 
 beforeEach(async () => {
   renderCalls = 0;
+  lastRenderSpec = null;
   predicateCalls = 0;
   // Fresh rate-limit bucket per test — no carry-over.
   await stack.redis.flushNamespace();
@@ -99,13 +132,14 @@ beforeEach(async () => {
 async function uploadFile(
   asUser: typeof userA,
   attach: { entityType: string; entityId: string },
+  fieldName = "img",
 ): Promise<string> {
   const token = await stack.jwt.sign(asUser);
   const fd = new FormData();
   fd.append("file", new File([Buffer.from([1, 2, 3])], "img.jpg", { type: "image/jpeg" }));
   fd.append("entityType", attach.entityType);
   fd.append("entityId", attach.entityId);
-  fd.append("fieldName", "img");
+  fd.append("fieldName", fieldName);
   const { body, contentType } = await buildMultipartBody(fd);
   const res = await stack.app.request("/api/files", {
     method: "POST",
@@ -174,21 +208,84 @@ describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
     expect(await revalidate.arrayBuffer()).toEqual(new ArrayBuffer(0));
   });
 
-  test("invalid variant name → 404, pre-check runs before any DB/systemQuery work", async () => {
+  test("syntactically malformed variant names → 404, pre-check runs before any DB/systemQuery work", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+    // Well-formed-looking but unregistered names (e.g. "not-a-preset") now
+    // reach the DB — the pre-check is purely syntactic since #1985, not a
+    // name list. Only pathological input is rejected here.
+    const malformedNames = [
+      "a".repeat(65), // over the 64-char cap
+      "foo%2Fbar", // decodes to a path separator
+      "foo..bar", // "." isn't in the allowed charset either
+      "foo%20bar", // decodes to a space
+    ];
+
+    for (const name of malformedNames) {
+      const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/${name}`);
+      expect(res.status).toBe(404);
+    }
+    expect(predicateCalls).toBe(0);
+    expect(renderCalls).toBe(0);
+  });
+
+  test("the field's own spec is used, not the built-in preset — proves resolution comes from the field declaration (#1985)", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/full`);
+
+    expect(res.status).toBe(200);
+    // widgetEntity's "img" field declares maxEdge:4096 for "full" — the
+    // built-in `full` preset (presets.ts) is maxEdge:2560. Getting 4096 here
+    // proves the spec came from the field, not the frozen preset constant.
+    expect(lastRenderSpec?.maxEdge).toBe(4096);
+  });
+
+  test("a field-declared name with no preset counterpart is served end-to-end — the exact case #1985 reported", async () => {
     const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
 
-    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/not-a-preset`);
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/plan`);
+
+    expect(res.status).toBe(200);
+    expect(lastRenderSpec?.maxEdge).toBe(4096);
+  });
+
+  test("a declared name outside [a-z0-9-] (camelCase) is still reachable — the syntactic gate isn't a narrower name list", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/heroWide`);
+
+    expect(res.status).toBe(200);
+    expect(lastRenderSpec?.maxEdge).toBe(3200);
+  });
+
+  test("a preset name the field doesn't declare in its variants → 404", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    // widgetEntity's "img" field declares only thumb/full — "card" and
+    // "hero" aren't in its variants map.
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/card`);
 
     expect(res.status).toBe(404);
-    expect(predicateCalls).toBe(0);
+    expect(predicateCalls).toBeGreaterThan(0);
+    expect(renderCalls).toBe(0);
+  });
+
+  test("a FileRef whose field declares no variants at all → 404", async () => {
+    const fileId = await uploadFile(
+      userA,
+      { entityType: "widget", entityId: PUBLIC_WIDGET_ID },
+      "plain",
+    );
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(404);
+    expect(predicateCalls).toBeGreaterThan(0);
     expect(renderCalls).toBe(0);
   });
 
   test("unknown fileRefId → 404", async () => {
-    // Valid UUID shape (the id column's type) but no matching row — a
-    // malformed/non-UUID id is a separate concern shared with the
-    // already-merged #1950 route (same fetchOne-by-id pattern), out of
-    // scope here.
+    // Valid UUID shape (the id column's type) but no matching row.
     const res = await stack.app.request(
       `http://${HOST_A}/media/00000000-0000-4000-8000-000000000000/thumb`,
     );
@@ -196,6 +293,17 @@ describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
     expect(res.status).toBe(404);
   });
 
+  test("malformed fileRefId → 404, pre-check runs before any DB/systemQuery work", async () => {
+    // Unlike #1950 (auth-gated), this route is anonymous — a non-UUID id
+    // reaching fetchOne() would throw Postgres 22P02 on an unauthenticated
+    // request, an unauth DoS primitive. Must 404 at the httpRoute pre-check.
+    const res = await stack.app.request(`http://${HOST_A}/media/not-a-uuid/thumb`);
+
+    expect(res.status).toBe(404);
+    expect(predicateCalls).toBe(0);
+    expect(renderCalls).toBe(0);
+  });
+
   test("cross-tenant: FileRef under tenant A, request resolves to tenant B → 404", async () => {
     const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
 

package/src/file-derivatives/feature.ts

@@ -16,13 +16,27 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { RateLimitError } from "@cosmicdrift/kumiko-framework/errors";
 import { PUBLIC_VARIANT_QN, publicVariantQuery } from "./handlers/public-variant.query";
-import { PRESET_VARIANT_NAMES } from "./presets";
 
 const FEATURE_NAME = "file-derivatives";
 
-// Widened from the readonly-tuple type of PRESET_VARIANT_NAMES so
-// `.includes(variant)` accepts a plain `string` param without an `as` cast.
-const VALID_VARIANT_NAMES: readonly string[] = PRESET_VARIANT_NAMES;
+// fileRefsTable.id is a UUID column — a malformed id must fail here, not at
+// the DB. Without this, an anonymous, internet-facing caller can throw a
+// Postgres 22P02 on every request (Bun.SQL pools the failed connection),
+// a DoS primitive with no auth required.
+const FILE_REF_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// Syntactic only, no registry/name-list lookup: a valid preset name plus a
+// random UUID reaches the same DB read anyway, so an allow-list of known
+// names defends nothing a determined caller can't route around — it only
+// blocks the cheaper of two equally-costly attacks. What a name actually
+// resolves to is decided by the field declaration in publicVariantQuery;
+// this just keeps pathological input (path separators, `..`, oversized
+// strings) out before that DB round-trip. `variants` keys have no runtime
+// charset constraint (`Readonly<Record<string, VariantSpec>>`), so this
+// stays permissive rather than guessing a convention — narrower than this
+// would silently 404 a legitimately declared name again. Do not reintroduce
+// a name list here "for safety" — see #1985.
+const VARIANT_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 
 export type PublicVariantResolveApexTenant = (
   host: string,
@@ -46,21 +60,23 @@ type PublicVariantQueryResult = {
 } | null;
 
 // file-derivatives — derive-on-first-use file variants (thumbnails,
-// resized/reformatted images) plus an opt-in ANONYMOUS route that serves
-// one of 4 fixed presets (thumb/card/hero/full) for a FileRef whose
+// resized/reformatted images) plus an opt-in ANONYMOUS route that serves any
+// variant an app declared on the FileRef's field (`createImageField({
+// variants: {...} })`, including but not limited to the `thumb`/`card`/
+// `hero`/`full` presets exported from `./presets`), for a FileRef whose
 // entityType has a registered, default-deny `derivativePublicPredicate`.
 //
 // The route never serves the original and never accepts a free VariantSpec
-// — only a preset name from the fixed list, and only after the app's
-// registered `isPublic` predicate for the FileRef's entityType says yes.
-// tenantId is resolved from the request Host via `resolveApexTenant`, NEVER
-// read from the request payload.
+// — only a name, resolved against the field's own `variants` declaration —
+// and only after the app's registered `isPublic` predicate for the FileRef's
+// entityType says yes. tenantId is resolved from the request Host via
+// `resolveApexTenant`, NEVER read from the request payload.
 export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}): FeatureDefinition {
   const basePath = opts.basePath ?? "/media";
 
   return defineFeature(FEATURE_NAME, (r) => {
     r.describe(
-      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves ONE of the 4 fixed presets (thumb/card/hero/full) for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef.",
+      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",
@@ -100,12 +116,14 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
           // template, so Hono can't infer the param type from a literal.
           const fileRefId = c.req.param("fileRefId");
           const variant = c.req.param("variant");
-          // Pre-check against the FIXED preset list before systemQuery runs
-          // at all — stops a caller from burning rate-limit budget/DB
-          // lookups on arbitrary variant names (thumb-a, thumb-b, ...).
-          // 404, not 400 — an invalid name and "doesn't exist" must answer
-          // identically, no name-oracle.
-          if (!fileRefId || !variant || !VALID_VARIANT_NAMES.includes(variant)) {
+          // 404, not 400 — a syntactically bad name and "doesn't exist" must
+          // answer identically, no name-oracle.
+          if (
+            !fileRefId ||
+            !variant ||
+            !VARIANT_NAME_RE.test(variant) ||
+            !FILE_REF_ID_RE.test(fileRefId)
+          ) {
             return c.text("not found", 404);
           }
 

package/src/file-derivatives/handlers/public-variant.query.ts

@@ -1,7 +1,9 @@
-// Public-Read of a derived FileRef variant (thumbnail/card/hero/full) — the
-// anonymous counterpart to GET /files/:id/variant/:name (#1950, auth-gated,
-// field-declared variants). This route never serves the original, never
-// accepts a free VariantSpec, and only serves one of the 4 fixed presets.
+// Public-Read of a derived FileRef variant — the anonymous counterpart to
+// GET /files/:id/variant/:name (#1950, auth-gated). Both routes resolve the
+// same way: the variant spec comes from the FileRef's field declaration
+// (`createImageField({ variants: {...} })`), not a fixed list — an app that
+// declares its own variant name gets it served here too. This route never
+// serves the original and never accepts a free VariantSpec, only a name.
 // Default-deny: an entityType with no `EXT_DERIVATIVE_PUBLIC_PREDICATE`
 // registration, or a predicate that returns false, both answer `null` —
 // the httpRoute wrapper in feature.ts turns that into a 404, same as a
@@ -11,6 +13,7 @@
 // httpRoute wrapper's `resolveApexTenant`), never from the payload.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { resolveFieldVariant } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   defineQueryHandler,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
@@ -19,13 +22,11 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import { z } from "zod";
-import { card, full, hero, PRESET_VARIANT_NAMES, thumb } from "../presets";
-
-const VARIANT_SPECS = { thumb, card, hero, full } as const;
 
 type FileRefRow = {
   readonly entityType: string | null;
   readonly entityId: string | null;
+  readonly fieldName: string | null;
 };
 
 export type DerivativePublicPredicateArgs = {
@@ -58,7 +59,7 @@ export const publicVariantQuery = defineQueryHandler({
   name: "public-variant",
   schema: z.object({
     fileRefId: z.string(),
-    variant: z.enum(PRESET_VARIANT_NAMES),
+    variant: z.string().min(1).max(64),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
   // ponytail: "ip" trusts the first x-forwarded-for hop (buildRequestContextData
@@ -76,8 +77,8 @@ export const publicVariantQuery = defineQueryHandler({
       isDeleted: false,
     });
     if (!row) return null;
-    const { entityType, entityId } = row;
-    if (entityType === null || entityId === null) return null;
+    const { entityType, entityId, fieldName } = row;
+    if (entityType === null || entityId === null || fieldName === null) return null;
 
     const usage = ctx.registry
       .getExtensionUsages(EXT_DERIVATIVE_PUBLIC_PREDICATE)
@@ -103,7 +104,8 @@ export const publicVariantQuery = defineQueryHandler({
       );
     }
 
-    const spec = VARIANT_SPECS[query.payload.variant];
+    const spec = resolveFieldVariant(ctx.registry, entityType, fieldName, query.payload.variant);
+    if (!spec) return null;
     const result = await derivatives.variant(query.payload.fileRefId, spec, query.payload.variant);
     const bytes = await files.ref(result.storageKey).read();
 

package/src/file-derivatives/index.ts

@@ -1,3 +1,3 @@
 export type { FileDerivativesOptions, PublicVariantResolveApexTenant } from "./feature";
 export { createFileDerivativesFeature, fileDerivativesFeature } from "./feature";
-export { card, full, hero, PRESET_VARIANT_NAMES, thumb } from "./presets";
+export { card, full, hero, thumb } from "./presets";

package/src/file-derivatives/presets.ts

@@ -1,13 +1,10 @@
 import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
 
+// Ready-made specs to spread into a field's own `variants` declaration
+// (`createImageField({ variants: { thumb, full: { ...full, maxEdge: 4096 } } })`)
+// — not an allow-list. Which names a route serves is decided entirely by
+// what a field declares (#1985), these are just common defaults.
 export const thumb = { maxEdge: 160, fit: "cover", format: "webp" } as const satisfies VariantSpec;
 export const card = { maxEdge: 640, fit: "inside", format: "webp" } as const satisfies VariantSpec;
 export const hero = { maxEdge: 1600, fit: "inside", format: "webp" } as const satisfies VariantSpec;
 export const full = { maxEdge: 2560, fit: "inside", format: "webp" } as const satisfies VariantSpec;
-
-// Single source of truth for the 4 preset variant names — the public
-// variant route (#1951) validates its `:variant` path param against this
-// list BEFORE any DB lookup or systemQuery dispatch, and the query
-// handler's Zod schema enums against it too. Keep in sync with the
-// preset exports above.
-export const PRESET_VARIANT_NAMES = ["thumb", "card", "hero", "full"] as const;

package/src/form-draft/__tests__/cleanup.integration.test.ts

@@ -120,6 +120,20 @@ async function backdate(draftKey: string, daysAgo: number): Promise<void> {
   );
 }
 
+// applyEntityEvent only stamps modified_at on updated/deleted/restored, never
+// on created (framework/src/db/apply-entity-event.ts) — a draft saved exactly
+// once has modified_at IS NULL, which is the real-world case the cleanup
+// query's COALESCE(modified_at, inserted_at) fallback exists for.
+async function backdateInsertedOnly(draftKey: string, daysAgo: number): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `UPDATE "read_form_drafts"
+     SET "inserted_at" = now() - ($1::int * interval '1 day'),
+         "modified_at" = NULL
+     WHERE "draft_key" = $2`,
+    [daysAgo, draftKey],
+  );
+}
+
 async function backdateFileRef(storageKey: string, daysAgo: number): Promise<void> {
   await asRawClient(stack.db).unsafe(
     `UPDATE "file_refs" SET "inserted_at" = now() - ($1::int * interval '1 day')
@@ -190,6 +204,19 @@ describe("form-draft cleanup job", () => {
     });
     expect(await draftExists("wizard:three-days-old")).toBe(true);
   });
+
+  test("deletes a draft saved exactly once (modified_at IS NULL), falling back to inserted_at", async () => {
+    await saveDraft("wizard:once-saved");
+    await backdateInsertedOnly("wizard:once-saved", 31);
+    await saveDraft("wizard:fresh-once-saved");
+    await backdateInsertedOnly("wizard:fresh-once-saved", 1);
+    await dispatchCleanup();
+
+    await waitFor(async () => {
+      expect(await draftExists("wizard:once-saved")).toBe(false);
+    });
+    expect(await draftExists("wizard:fresh-once-saved")).toBe(true);
+  });
 });
 
 describe("form-draft cleanup job — FileRef release (#1915)", () => {

package/src/form-draft/__tests__/form-draft.integration.test.ts

@@ -184,13 +184,22 @@ describe("form-draft integration — ownership isolation", () => {
 describe("form-draft integration — list", () => {
   test("list returns open drafts for a screenId, newest first, without the blob's values", async () => {
     await saveDraft("wizard:a", { name: "First" }, 0);
+    // savedAt is a millisecond stamp (#1960) — sleep is best-effort only;
+    // under CI load two saves can still tie, so assert the comparator
+    // contract (savedAt desc, then id desc) rather than a fixed key order.
+    await Bun.sleep(20);
     await saveDraft("wizard:b", { name: "Second" }, 1);
 
     const { drafts } = await listDrafts("wizard");
-    expect(drafts.map((d) => d.draftKey)).toEqual(["wizard:b", "wizard:a"]);
-    expect(drafts[0]?.stepIndex).toBe(1);
-    expect(drafts[0]?.savedAt).toBeTruthy();
-    expect(drafts[0]).not.toHaveProperty("values");
+    expect(drafts).toHaveLength(2);
+    expect(new Set(drafts.map((d) => d.draftKey))).toEqual(new Set(["wizard:a", "wizard:b"]));
+    const [first, second] = drafts;
+    expect(first?.savedAt).toBeTruthy();
+    expect(first).not.toHaveProperty("values");
+    const byTime = second!.savedAt.localeCompare(first!.savedAt);
+    const byId = second!.id.localeCompare(first!.id);
+    expect(byTime < 0 || (byTime === 0 && byId < 0)).toBe(true);
+    if (first!.draftKey === "wizard:b") expect(first!.stepIndex).toBe(1);
   });
 
   test("list excludes a draft whose screenId is only a prefix, not a full segment match", async () => {
@@ -209,6 +218,22 @@ describe("form-draft integration — list", () => {
     expect(drafts.map((d) => d.draftKey)).toEqual(["scr%en:a"]);
   });
 
+  test("a screenId containing an underscore is matched literally, not as a single-char wildcard", async () => {
+    await saveDraft("wizar_:a", {}, 0);
+    await saveDraft("wizardX:a", {}, 0);
+
+    const { drafts } = await listDrafts("wizar_");
+    expect(drafts.map((d) => d.draftKey)).toEqual(["wizar_:a"]);
+  });
+
+  test("a screenId containing a literal backslash is matched literally", async () => {
+    await saveDraft("wiz\\ard:a", {}, 0);
+    await saveDraft("wizard:a", {}, 0);
+
+    const { drafts } = await listDrafts("wiz\\ard");
+    expect(drafts.map((d) => d.draftKey)).toEqual(["wiz\\ard:a"]);
+  });
+
   test("list resolves an empty array when nothing was ever saved for the screenId", async () => {
     expect((await listDrafts("no-such-screen")).drafts).toEqual([]);
   });

package/src/form-draft/entity.ts

@@ -24,7 +24,7 @@ export const formDraftEntity = createEntity({
     // feeds the GDPR-hook-coverage boot guard (it's a plain FK into `user`,
     // not content of its own) — see ../form-draft-user-data for the
     // required export/delete hook coverage.
-    ownerId: createTextField({ subjectRef: true }),
+    ownerId: createTextField({ subjectRef: true, required: true }),
     draftKey: createTextField({ required: true, maxLength: FORM_DRAFT_KEY_MAX_LENGTH }),
     // The blob shape is fixed by issue #1889, not left to the caller:
     // { values: Record<string, unknown>, stepIndex: number, savedAt: string }.

package/src/form-draft/feature.ts

@@ -13,7 +13,6 @@ import { discardDraftWrite } from "./handlers/discard.write";
 import { getDraftQuery } from "./handlers/get.query";
 import { listDraftsQuery } from "./handlers/list.query";
 import { saveDraftWrite } from "./handlers/save.write";
-import { FORM_DRAFT_FEATURE_I18N } from "./i18n";
 
 function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>): void {
   r.describe(
@@ -41,8 +40,6 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
 
   r.config({ keys: { retentionDays: formDraftRetentionDaysConfig } });
   r.job("cleanup", { trigger: { cron: "0 3 * * *" }, concurrency: "skip" }, cleanupDraftsJob);
-
-  r.translations({ keys: FORM_DRAFT_FEATURE_I18N });
 }
 
 export const formDraftFeature = defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft);

package/src/form-draft/handlers/__tests__/list.query.test.ts

@@ -0,0 +1,26 @@
+// byNewestFirst — the sort issue #1960 traced the flake to: form-draft.integration.test.ts
+// creates two drafts fast enough to land on the same millisecond savedAt, and the query had
+// no ORDER BY at all, so ties fell back to Postgres' undefined row order. These cases can't be
+// forced through the integration stack (no clock control on the real save path, and seeding a
+// row directly would bypass the event store), so the comparator is unit-tested directly here.
+
+import { describe, expect, test } from "bun:test";
+import { byNewestFirst } from "../list.query";
+
+function draft(id: string, savedAt: string) {
+  return { id, draftKey: `wizard:${id}`, stepIndex: 0, savedAt };
+}
+
+describe("byNewestFirst", () => {
+  test("a later savedAt sorts before an earlier one", () => {
+    const older = draft("a", "2026-01-01T00:00:00.000Z");
+    const newer = draft("b", "2026-01-01T00:00:00.001Z");
+    expect([older, newer].sort(byNewestFirst)).toEqual([newer, older]);
+  });
+
+  test("a tied savedAt still sorts deterministically, regardless of input order", () => {
+    const a = draft("aaaa", "2026-01-01T00:00:00.000Z");
+    const b = draft("bbbb", "2026-01-01T00:00:00.000Z");
+    expect([a, b].sort(byNewestFirst)).toEqual([b, a].sort(byNewestFirst));
+  });
+});

package/src/form-draft/handlers/cleanup.job.ts

@@ -57,18 +57,21 @@ async function releaseRowFileRefs(
     return;
   }
 
+  // Only storageKeys with a real file_refs row owned by this row's draft
+  // owner are releasable — `draft.values` is free-form JSON the owning user
+  // controls, so an unverified key could target someone else's file (see
+  // db/queries/owned-file-refs.ts). Not wrapped in try/catch: a query
+  // failure here (pool exhaustion, missing table) is a real error, not the
+  // "no provider resolvable" case below — let it propagate so the job retries.
+  const ownedKeys = await filterOwnedStorageKeys(
+    db,
+    row.tenantId,
+    row.ownerId,
+    keys,
+    row.insertedAt,
+  );
+
   try {
-    // Only storageKeys with a real file_refs row owned by this row's
-    // draft owner are releasable — `draft.values` is free-form JSON the
-    // owning user controls, so an unverified key could target someone
-    // else's file (see db/queries/owned-file-refs.ts).
-    const ownedKeys = await filterOwnedStorageKeys(
-      db,
-      row.tenantId,
-      row.ownerId,
-      keys,
-      row.insertedAt,
-    );
     const provider = await fileProviderResolver(row.tenantId);
     await releaseDraftFileRefs(ownedKeys, (key) => provider.delete(key), log);
   } catch (err) {

package/src/form-draft/handlers/list.query.ts

@@ -12,6 +12,15 @@ export type ListDraftsResult = {
   }[];
 };
 
+type DraftListItem = ListDraftsResult["drafts"][number];
+
+// Two saves landing in the same millisecond tie on savedAt — there's no
+// knowable "true" order between them, so `id` only buys a deterministic,
+// repeatable result, not chronological accuracy.
+export function byNewestFirst(a: DraftListItem, b: DraftListItem): number {
+  return b.savedAt.localeCompare(a.savedAt) || b.id.localeCompare(a.id);
+}
+
 // list — the fallback path for resuming a draft whose draftId the client
 // lost (new tab, cleared storage, another device): returns just enough to
 // pick one (id, draftKey, stepIndex, savedAt), never the blob's `values`.
@@ -34,7 +43,7 @@ export const listDraftsQuery = defineQueryHandler({
         stepIndex: row.draft.stepIndex,
         savedAt: row.draft.savedAt,
       }))
-      .sort((a, b) => b.savedAt.localeCompare(a.savedAt));
+      .sort(byNewestFirst);
     return { drafts };
   },
 });

package/src/template-resolver/feature.ts

@@ -44,9 +44,9 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
     r.describe(
       [
         "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail-html`, `document-pdf`, `ai-prompt`, `text-block`, `image-snapshot`).",
-        "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes.",
+        "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers.",
         "Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.",
-        "How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links). Both offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format and wins over the built-in one.",
+        "How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).",
         'A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.',
         "Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
       ].join("\n\n"),

package/src/template-resolver/web/__tests__/client-plugin.test.tsx

@@ -1,6 +1,66 @@
 import { afterEach, describe, expect, mock, test } from "bun:test";
+// mock.module replaces imports for all consumers — static imports before
+// mock.module still see the mocked version because Bun intercepts at the
+// loader level (same pattern as editor-read-only.test.tsx).
+import { useShellUser } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
 import type { TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  CONTENT_EDITOR_ELEMENT_ID,
+  type ContentEditorComponent,
+  ContentEditorsProvider,
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives, PlainContentEditor } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
 import { textBlocksClient } from "../client-plugin";
+import { defaultTranslations } from "../i18n";
+
+mock.module("@cosmicdrift/kumiko-bundled-features/auth-email-password/web", () => ({
+  useShellUser: mock(),
+}));
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useDispatcher: mock(() => ({ write: mock(), query: mock() })),
+  useQuery: mock(() => ({
+    data: {
+      slug: "reminder",
+      locale: "de",
+      title: "Reminder",
+      content: "Hi",
+      contentFormat: "plain",
+      folder: null,
+    },
+    loading: false,
+    error: null,
+    refetch: mock(),
+  })),
+  useAppFeatures: mock(() => [
+    {
+      featureName: "mail",
+      contentCollections: [
+        {
+          id: "prompts",
+          kind: "ai-prompt",
+          contentFormat: "plain",
+          variableSchema: { customerName: "Jane" },
+          nav: { label: "mail:nav.prompts" },
+        },
+        {
+          id: "richDocs",
+          kind: "mail-html",
+          contentFormat: "rich",
+          variableSchema: {},
+          nav: { label: "mail:nav.richDocs" },
+        },
+      ],
+    },
+  ]),
+}));
 
 // Covers the three new migration paths (advisor gap): navId attach + SSE
 // entities, no-leak without navId (conditional spread), and the unwrap (the
@@ -192,3 +252,83 @@ describe("textBlocksClient — content collections", () => {
     expect(sentType).toBe("template-resolver:query:by-tenant");
   });
 });
+
+describe("textBlocksClient — plain contentFormat editor wiring", () => {
+  const localeResolver = createStaticLocaleResolver({ locale: "de" });
+
+  function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+    return (
+      <LocaleProvider resolver={localeResolver} fallbackBundles={[defaultTranslations]}>
+        <PrimitivesProvider value={defaultPrimitives}>
+          <ContentEditorsProvider value={textBlocksClient().contentEditors ?? {}}>
+            {children}
+          </ContentEditorsProvider>
+        </PrimitivesProvider>
+      </LocaleProvider>
+    );
+  }
+
+  test("contentEditors.plain is registered as PlainContentEditor", () => {
+    expect(textBlocksClient().contentEditors?.["plain"]).toBe(PlainContentEditor);
+  });
+
+  // Deleting the registry line would leave useContentEditor("markdown")
+  // silently falling back to TextareaContentEditor — chips gone, suite green.
+  test("contentEditors.markdown is registered as PlainContentEditor", () => {
+    expect(textBlocksClient().contentEditors?.["markdown"]).toBe(PlainContentEditor);
+  });
+
+  test("a collection's variableSchema renders as chip placeholders on its plain editor", () => {
+    // biome-ignore lint/suspicious/noExplicitAny: Bun mock function
+    (useShellUser as any).mockReturnValue({ id: "u1", roles: ["TenantAdmin"] });
+    const Editor = textBlocksClient().resolvers?.["template-resolver:edit"];
+    if (Editor === undefined) throw new Error("Editor not registered");
+
+    const target = {
+      featureId: "template-resolver",
+      action: "edit",
+      args: { slug: "reminder", locale: "de", collectionId: "prompts" },
+    } as const;
+    render(<Editor target={target} onClose={() => {}} />, { wrapper: Wrapper });
+
+    // A typo in the registry key or a field rename on contentCollections
+    // silently falls back to variables={[]} — no chip renders, no red test.
+    expect(screen.getByText("{{customerName}}")).toBeTruthy();
+  });
+});
+
+describe("textBlocksClient — findContentFormat resolves collectionId to the registered editor", () => {
+  const localeResolver = createStaticLocaleResolver({ locale: "de" });
+  const RichStub: ContentEditorComponent = () => <div data-testid="rich-stub-editor" />;
+
+  function RichStubWrapper({ children }: { readonly children: ReactNode }): ReactNode {
+    return (
+      <LocaleProvider resolver={localeResolver} fallbackBundles={[defaultTranslations]}>
+        <PrimitivesProvider value={defaultPrimitives}>
+          <ContentEditorsProvider value={{ rich: RichStub }}>{children}</ContentEditorsProvider>
+        </PrimitivesProvider>
+      </LocaleProvider>
+    );
+  }
+
+  test("a collection declared with contentFormat 'rich' renders the registered rich editor, not the textarea fallback", () => {
+    // biome-ignore lint/suspicious/noExplicitAny: Bun mock function
+    (useShellUser as any).mockReturnValue({ id: "u1", roles: ["TenantAdmin"] });
+    const Editor = textBlocksClient().resolvers?.["template-resolver:edit"];
+    if (Editor === undefined) throw new Error("Editor not registered");
+
+    const target = {
+      featureId: "template-resolver",
+      action: "edit",
+      args: { slug: "reminder", locale: "de", collectionId: "richDocs" },
+    } as const;
+    render(<Editor target={target} onClose={() => {}} />, { wrapper: RichStubWrapper });
+
+    // A broken collectionId → contentFormat mapping (wrong field name,
+    // array-vs-record drift on the schema) resolves contentFormat to
+    // undefined, and useContentEditor's own fallback silently swaps in the
+    // plain textarea instead — no red test without this assertion.
+    expect(screen.getByTestId("rich-stub-editor")).toBeTruthy();
+    expect(document.getElementById(CONTENT_EDITOR_ELEMENT_ID)).toBeNull();
+  });
+});

package/src/template-resolver/web/client-plugin.tsx

@@ -206,44 +206,38 @@ function makeTreeProvider(tenantIdOverride?: string, collectionId?: string): Tre
   };
 }
 
-// contentFormat lives on the collection the node came from, not on the
-// entity — a node without a collectionId (the hand-wired text-block tree)
-// has none, useContentEditor then falls back to "plain" on its own.
-function findContentFormat(
+type ContentCollectionSchema = NonNullable<FeatureSchema["contentCollections"]>[number];
+
+// A node without a collectionId (the hand-wired text-block tree) has no
+// collection to look up — contentFormat/variableSchema then fall back to
+// their own callers' defaults.
+function findCollection(
   features: readonly FeatureSchema[],
   collectionId?: string,
-): string | undefined {
+): ContentCollectionSchema | undefined {
   if (collectionId === undefined) return undefined;
   for (const feature of features) {
     const match = feature.contentCollections?.find((c) => c.id === collectionId);
-    if (match !== undefined) return match.contentFormat;
+    if (match !== undefined) return match;
   }
   return undefined;
 }
 
-// Same lookup as findContentFormat, for the collection's fixed variable
-// names (ContentCollectionDefinition.variableSchema) — the chip bar's data
-// source. A node without a collectionId gets no chips: the hand-wired
-// text-block tree has no collection to declare variables on.
-function findVariableSchema(
+function findContentFormat(
   features: readonly FeatureSchema[],
   collectionId?: string,
-): readonly string[] {
-  return Object.keys(findVariableExamples(features, collectionId));
+): string | undefined {
+  return findCollection(features, collectionId)?.contentFormat;
 }
 
-// Same lookup, for the example values the Preview substitutes in for
-// `{{name}}` — the values half of the same variableSchema map.
+// The collection's fixed variable names (ContentCollectionDefinition.
+// variableSchema) — the chip bar's data source and, keyed, the example
+// values the Preview substitutes in for `{{name}}`.
 function findVariableExamples(
   features: readonly FeatureSchema[],
   collectionId?: string,
 ): Readonly<Record<string, string>> {
-  if (collectionId === undefined) return {};
-  for (const feature of features) {
-    const match = feature.contentCollections?.find((c) => c.id === collectionId);
-    if (match !== undefined) return match.variableSchema ?? {};
-  }
-  return {};
+  return findCollection(features, collectionId)?.variableSchema ?? {};
 }
 
 // Edit form: loads the current values via by-slug, lets TenantAdmin and
@@ -311,8 +305,8 @@ function TextBlockEditor({
   const t = useTranslation();
   const features = useAppFeatures();
   const contentFormat = findContentFormat(features, collectionId);
-  const variables = findVariableSchema(features, collectionId);
   const variableExamples = findVariableExamples(features, collectionId);
+  const variables = Object.keys(variableExamples);
   const ContentEditor = useContentEditor(contentFormat);
   const canWrite =
     user?.roles.includes("TenantAdmin") === true || user?.roles.includes("SystemAdmin") === true;

package/src/tenant/handlers/invitations.query.ts

@@ -11,15 +11,13 @@ import { INVITATION_STATUS, tenantInvitationsTable } from "../invitation-table";
 // sequential loop caps concurrency at 1 and leaves 3 pool slots idle.
 const KMS_POOL_CONCURRENCY = 4;
 
-// Pending-Invitations-Liste für den aktuellen Tenant. Admin-only.
-// Filter: status="pending" — accepted/cancelled/expired sind für die
-// UI uninteressant (UI zeigt nur "ausstehende Einladungen"; Audit-Log
-// für historische gehört in ein separates Audit-Feature).
+// Pending invitations for the current tenant, admin-only, filtered to
+// status="pending" — accepted/cancelled/expired don't belong in this UI
+// (historical entries belong in a separate audit feature).
 //
-// SQL-side filter (vorher JS-side .filter): bei Tenants mit vielen
-// historischen invitations lädt die Query sonst alle Rows in den
-// Node-process um die meisten wegzuwerfen — DB indexed das auf den
-// (tenantId, …)-key, JS-filter ist redundant.
+// SQL-side filter (was JS-side .filter): a tenant with many historical
+// invitations would otherwise load every row into the node process just to
+// discard most of them — the DB indexes on (tenantId, …), a JS filter is redundant.
 export const invitationsQuery = defineQueryHandler({
   name: "invitations",
   schema: z.object({}),

package/src/user-data-rights/__tests__/boot-checks.test.ts

@@ -80,7 +80,7 @@ describe("GDPR-storage boot guards V2-V4 (via r.bootCheck)", () => {
     ).not.toThrow();
   });
 
-  test("form-draft mounted WITHOUT form-draft-user-data → V3 throws (userOwned draft field has no hook)", () => {
+  test("form-draft mounted WITHOUT form-draft-user-data → V3 throws (subjectRef ownerId has no EXT_USER_DATA hook)", () => {
     expect(() => validateBoot([...baseFeatures(), formDraftFeature])).toThrow(
       /EXT_USER_DATA hook.*Art\.17 gap/,
     );

package/src/user-data-rights/__tests__/run-user-export.integration.test.ts

@@ -26,7 +26,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, type UserDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
-import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
   type TestStack,
@@ -48,6 +48,7 @@ import { createSessionsFeature, userSessionEntity } from "../../sessions";
 import { createTenantFeature, tenantInvitationEntity, tenantInvitationsTable } from "../../tenant";
 import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
 import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defaults";
+import { fileRefExportHook } from "../../user-data-rights-defaults/hooks/file-ref.userdata-hook";
 import { tenantInvitationExportHook } from "../../user-data-rights-defaults/hooks/tenant-invitation.userdata-hook";
 import { createUserDataRightsFeature } from "../feature";
 import { runUserExport } from "../run-user-export";
@@ -396,12 +397,33 @@ describe("runUserExport :: tenant-invitation PII export (#1937)", () => {
     // KMS + bidx MUST be configured before the executor write so the row
     // lands encrypted with a real blind index, matching the KMS-active
     // production shape (order matches anonymous-deletion-kms.integration.test.ts).
-    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
     configureBlindIndexKey(BIDX_KEY);
 
     await seedUser(ALICE_ID, { email: INVITE_EMAIL, displayName: "Alice Invite" });
     await seedMembership(ALICE_ID, TENANT_A);
 
+    // seedUser/seedRow does not encrypt — encrypt the user row's email the
+    // same way an executor write would, so resolveUserEmail's decryptStoredPii
+    // branch runs over real ciphertext, not plaintext it happens to pass through.
+    const encryptedUser = await encryptPiiFieldValues(
+      { id: ALICE_ID, email: INVITE_EMAIL },
+      userEntity,
+      ["email"],
+      kms,
+      { requestId: "test" },
+    );
+    await asRawClient(stack.db).unsafe(`UPDATE read_users SET email = $1 WHERE id = $2`, [
+      String(encryptedUser["email"]),
+      ALICE_ID,
+    ]);
+    const userRow = await asRawClient(stack.db).unsafe<Record<string, unknown>>(
+      `SELECT email FROM read_users WHERE id = $1`,
+      [ALICE_ID],
+    );
+    expect(isPiiCiphertext(userRow[0]?.["email"])).toBe(true);
+
     // Real executor write path — the same one tenantInvitationExportHook's
     // sibling delete hook and the invite-create handler use — so the row
     // carries genuine ciphertext + a real email_bidx, not a hand-seeded stand-in.
@@ -435,6 +457,38 @@ describe("runUserExport :: tenant-invitation PII export (#1937)", () => {
     expect(isPiiCiphertext(rawRows[0]?.["email"])).toBe(true);
     expect(String(rawRows[0]?.["email_bidx"])).toStartWith("kumiko-bidx:v1:");
 
+    // Cross-user isolation: a foreign invitee's invite in the same tenant
+    // must not leak into Alice's export via the entity-wide selectMany.
+    const foreignInviteeResult = await invitationExecutor.create(
+      {
+        email: "bob.invite@example.com",
+        role: "Member",
+        status: "pending",
+        invitedBy: ALICE_ID,
+        expiresAt: NOW().add({ seconds: 7 * 24 * 60 * 60 }),
+      },
+      systemUser,
+      tenantDb,
+    );
+    expect(foreignInviteeResult.isSuccess).toBe(true);
+
+    // Cross-tenant isolation: Alice's own email invited in a different
+    // tenant must land in that tenant's section, not TENANT_A's.
+    const foreignTenantSystemUser = createSystemUser(TENANT_B);
+    const foreignTenantDb = createTenantDb(stack.db, TENANT_B, "system");
+    const foreignTenantResult = await invitationExecutor.create(
+      {
+        email: INVITE_EMAIL,
+        role: "Member",
+        status: "pending",
+        invitedBy: ALICE_ID,
+        expiresAt: NOW().add({ seconds: 7 * 24 * 60 * 60 }),
+      },
+      foreignTenantSystemUser,
+      foreignTenantDb,
+    );
+    expect(foreignTenantResult.isSuccess).toBe(true);
+
     // Pins the hook boundary directly: tenantInvitationExportHook itself must
     // hand back ciphertext, not plaintext — decryption is the central sweep's
     // job (decryptSnippetFields in run-user-export.ts), not the hook's. If the
@@ -463,7 +517,80 @@ describe("runUserExport :: tenant-invitation PII export (#1937)", () => {
     // mean the hook found nothing and the bidx hypothesis is wrong.
     const invitationSnippet = tenantA?.entities.find((e) => e.entity === "tenant-invitation");
     expect(invitationSnippet).toBeDefined();
+    // Isolation: neither the foreign-email invite in the same tenant nor
+    // Alice's own email invited in TENANT_B leak into TENANT_A's snippet.
     expect(invitationSnippet?.rows).toHaveLength(1);
     expect(invitationSnippet?.rows[0]?.["email"]).toBe(INVITE_EMAIL);
+    expect(JSON.stringify(bundle)).not.toContain("bob.invite@example.com");
+  });
+});
+
+describe("runUserExport :: fileRef PII export via the fileRefs side-channel (#1955)", () => {
+  afterEach(() => {
+    resetPiiSubjectKmsForTests();
+  });
+
+  test("bundle.fileRefs carries plaintext fileName + a readable zipPath, even though the hook returns ciphertext", async () => {
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+
+    await seedUser(ALICE_ID, { email: "alice.fileref@example.com" });
+    await seedMembership(ALICE_ID, TENANT_A);
+
+    const fileRefId = uuid(401);
+    const PLAINTEXT_NAME = "alice-cv.pdf";
+    // fileRefEntity.fileName is `pii: true` with no `userOwned` override, so
+    // resolveSubjectForField treats the row itself as the subject (its own
+    // `id`), not `insertedById`. Encrypting with that subject reproduces the
+    // real write-path ciphertext shape.
+    const encrypted = await encryptPiiFieldValues(
+      { id: fileRefId, fileName: PLAINTEXT_NAME },
+      fileRefEntity,
+      ["fileName"],
+      kms,
+      { requestId: "test" },
+    );
+    await asRawClient(stack.db).unsafe(
+      `
+      INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size, inserted_by_id)
+      VALUES ($1, $2, $3, $4, 'application/pdf', 2048, $5)
+      ON CONFLICT (id) DO NOTHING
+    `,
+      [fileRefId, TENANT_A, `storage/${fileRefId}`, String(encrypted["fileName"]), ALICE_ID],
+    );
+
+    // Pins the hook boundary directly: fileRefExportHook must still hand
+    // back ciphertext in the fileRefs side-channel — decryption is the
+    // central sweep's job (decryptSnippetFields in run-user-export.ts), not
+    // the hook's. If the hook ever started decrypting fileRefs locally, this
+    // assertion would catch it even though the runUserExport() assertions
+    // below would stay green either way.
+    const hookCtx: UserDataHookCtx = {
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: TENANT_A,
+      userId: ALICE_ID,
+    };
+    const rawSnippet = await fileRefExportHook(hookCtx);
+    expect(isPiiCiphertext(rawSnippet?.fileRefs?.[0]?.fileName)).toBe(true);
+
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: ALICE_ID,
+      now: NOW(),
+    });
+
+    expect(bundle.fileRefs).toHaveLength(1);
+    const ref = bundle.fileRefs[0];
+    // Bug #1955: this used to be the raw `kumiko-pii:v2:...` ciphertext
+    // string instead of the person's actual file name.
+    expect(ref?.fileName).toBe(PLAINTEXT_NAME);
+    // Bug #1955 effect 2: buildFileRefZipPath sanitized the ciphertext into
+    // a garbled underscore-mangled path — the ZIP entry must carry the
+    // readable name instead.
+    expect(ref?.zipPath).toContain("alice-cv");
+    expect(ref?.zipPath).not.toContain("kumiko-pii");
+    expect(JSON.stringify(bundle)).not.toContain("kumiko-pii:");
   });
 });

package/src/user-data-rights/run-user-export.ts

@@ -223,36 +223,35 @@ export async function runUserExport(args: RunUserExportArgs): Promise<UserExport
 // base64-Blob als "Wert" auszuliefern (leak-by-confusion).
 const ENCRYPTED_UNAVAILABLE = "[encrypted:unavailable]";
 
-async function decryptSnippetFields(
-  registry: Registry,
-  hookEntityName: string,
-  snippet: UserDataExportSnippet,
-): Promise<UserDataExportSnippet> {
-  let rows = snippet.rows;
+// Shared decrypt sweep, used for both `snippet.rows` and `snippet.fileRefs`
+// (#1955) — `encryptedFields` is keyed by field NAME, so it stays a no-op
+// for today's `fileRef` entity but covers a future generically-encrypted
+// side-channel field too.
+async function decryptRecords(
+  records: ReadonlyArray<Record<string, unknown>>,
+  encryptedFields: ReadonlySet<string>,
+  kms: ReturnType<typeof configuredPiiSubjectKms>,
+): Promise<Record<string, unknown>[]> {
+  let rows: Record<string, unknown>[] = [...records];
 
-  const entity = registry.getEntity(snippet.entity) ?? registry.getEntity(hookEntityName);
-  if (entity) {
-    const encryptedFields = collectEncryptedFieldNames(entity);
-    if (encryptedFields.size > 0) {
-      const cipher = configuredEntityFieldEncryption();
-      rows = await Promise.all(
-        rows.map(async (row) => {
-          if (cipher) return decryptEntityFieldValues(row, encryptedFields, cipher);
-          const out = { ...row };
-          for (const name of encryptedFields) {
-            if (typeof out[name] === "string") out[name] = ENCRYPTED_UNAVAILABLE;
-          }
-          return out;
-        }),
-      );
-    }
+  if (encryptedFields.size > 0) {
+    const cipher = configuredEntityFieldEncryption();
+    rows = await Promise.all(
+      rows.map(async (row) => {
+        if (cipher) return decryptEntityFieldValues(row, encryptedFields, cipher);
+        const out = { ...row };
+        for (const name of encryptedFields) {
+          if (typeof out[name] === "string") out[name] = ENCRYPTED_UNAVAILABLE;
+        }
+        return out;
+      }),
+    );
   }
 
-  // PII-Subject-Ciphertexte (kumiko-pii:) sind self-describing — kein
-  // Entity-Kontext noetig, deckt jeden heutigen und kuenftigen Hook ab.
-  // Erased Subject → Sentinel (ehrlich: der Wert ist geshreddet).
-  const kms = configuredPiiSubjectKms();
-  rows = await Promise.all(
+  // PII-subject ciphertexts (kumiko-pii:) are self-describing — no entity
+  // context needed, covers every hook past and future. Erased subject →
+  // sentinel (honest: the value is shredded).
+  return Promise.all(
     rows.map(async (row) => {
       const piiKeys = Object.keys(row).filter((k) => isPiiCiphertext(row[k]));
       if (piiKeys.length === 0) return row;
@@ -266,7 +265,31 @@ async function decryptSnippetFields(
       });
     }),
   );
-  return { ...snippet, rows };
+}
+
+async function decryptSnippetFields(
+  registry: Registry,
+  hookEntityName: string,
+  snippet: UserDataExportSnippet,
+): Promise<UserDataExportSnippet> {
+  const entity = registry.getEntity(snippet.entity) ?? registry.getEntity(hookEntityName);
+  const encryptedFields = entity ? collectEncryptedFieldNames(entity) : new Set<string>();
+  const kms = configuredPiiSubjectKms();
+
+  const rows = await decryptRecords(snippet.rows, encryptedFields, kms);
+
+  if (!snippet.fileRefs || snippet.fileRefs.length === 0) {
+    return { ...snippet, rows };
+  }
+
+  const decryptedFileRefs = await decryptRecords(snippet.fileRefs, encryptedFields, kms);
+  const fileRefs = decryptedFileRefs.map((r) => ({
+    fileRefId: String(r["fileRefId"]),
+    storageKey: String(r["storageKey"]),
+    fileName: String(r["fileName"]),
+  }));
+
+  return { ...snippet, rows, fileRefs };
 }
 
 // Pseudo-Tenant fuer User ohne aktive Memberships. Identisch zum

package/src/form-draft/i18n.ts

@@ -1,3 +0,0 @@
-type LocalizedString = { readonly de: string; readonly en: string };
-
-export const FORM_DRAFT_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {};