@cosmicdrift/kumiko-framework 0.190.0 → 0.192.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.190.0",
+  "version": "0.192.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>",
@@ -186,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.190.0",
+    "@cosmicdrift/kumiko-types": "0.192.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.190.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.192.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/derivatives/__tests__/field-variants.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { EntityDefinition, FieldDefinition, Registry } from "../../engine/types";
+import { resolveFieldVariant } from "../field-variants";
+
+// Minimal fake Registry — same pattern as derivatives-context.test.ts's
+// fakeRegistry: only getEntity is exercised by resolveFieldVariant.
+function fakeRegistry(entities: Readonly<Record<string, EntityDefinition>>): Registry {
+  const map = new Map(Object.entries(entities));
+  return {
+    getEntity: (name: string) => map.get(name),
+  } as unknown as Registry;
+}
+
+const THUMB_SPEC: VariantSpec = { maxEdge: 200, format: "webp" };
+
+function photoEntityWith(field: FieldDefinition): Readonly<Record<string, EntityDefinition>> {
+  return {
+    photo: { fields: { avatar: field } },
+  };
+}
+
+describe("resolveFieldVariant", () => {
+  test("returns the declared spec for a known variant name", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, "photo", "avatar", "thumb")).toBe(THUMB_SPEC);
+  });
+
+  test("unknown variant name returns undefined", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, "photo", "avatar", "nope")).toBeUndefined();
+  });
+
+  test("__proto__ as a name returns undefined — the prototype-pollution case Object.hasOwn catches", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, "photo", "avatar", "__proto__")).toBeUndefined();
+  });
+
+  test("null entityType or fieldName returns undefined", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, null, "avatar", "thumb")).toBeUndefined();
+    expect(resolveFieldVariant(registry, "photo", null, "thumb")).toBeUndefined();
+  });
+
+  test("a non-image field returns undefined even when its own value looks variant-shaped", () => {
+    const registry = fakeRegistry(photoEntityWith({ type: "text" }));
+    expect(resolveFieldVariant(registry, "photo", "avatar", "thumb")).toBeUndefined();
+  });
+
+  test("an image field without variants returns undefined", () => {
+    const registry = fakeRegistry(photoEntityWith({ type: "image" }));
+    expect(resolveFieldVariant(registry, "photo", "avatar", "thumb")).toBeUndefined();
+  });
+});

package/src/derivatives/__tests__/variant-key.test.ts

@@ -19,6 +19,12 @@ describe("specHash — key stability", () => {
   test("a changed value produces a different hash — the whole point of hashing the spec", () => {
     expect(specHash({ maxEdge: 512 })).not.toBe(specHash({ maxEdge: 640 }));
   });
+
+  test("different blurRegions produce different hashes — corrected regions need a fresh URL", () => {
+    expect(specHash({ blurRegions: [{ x: 0, y: 0, width: 0.5, height: 0.5 }] })).not.toBe(
+      specHash({ blurRegions: [{ x: 0.5, y: 0.5, width: 0.5, height: 0.5 }] }),
+    );
+  });
 });
 
 describe("variantSuffix", () => {

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

@@ -0,0 +1,169 @@
+// Proves GET /api/files/:id/variant/:name end-to-end: real HTTP calls
+// through the auth+tenant+guard gate, resolveFieldVariant's whitelist, and
+// createDerivativesContext's cache path — same "wiring, not unit logic"
+// rationale as derivatives-context.integration.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import {
+  createEntity,
+  createImageField,
+  defineFeature,
+  EXT_DERIVATIVE_RENDERER,
+} from "../../engine";
+import { createFilesFeature } from "../../files/feature";
+import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
+import { buildMultipartBody, patchFileInstanceofForBunTest } from "../../testing";
+
+const VARIANT_BYTES = new Uint8Array([9, 9, 9]);
+
+let renderCalls = 0;
+const fakeRender: DerivativeRendererPlugin["render"] = async () => {
+  renderCalls++;
+  return VARIANT_BYTES;
+};
+
+const photoEntity = createEntity({
+  table: "variant_route_photos",
+  fields: {
+    avatar: createImageField({ variants: { thumb: { maxEdge: 100, format: "webp" } } }),
+  },
+});
+
+const photoFeature = defineFeature("variantroutetest", (r) => {
+  r.entity("photo", photoEntity);
+  r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, { onRegister: () => {} });
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", { render: fakeRender });
+});
+
+let stack: TestStack;
+const tenantId = testTenantId(1);
+const user = createTestUser({ id: 1, tenantId, roles: ["Admin"] });
+const otherTenantId = testTenantId(2);
+const otherTenantUser = createTestUser({ id: 10, tenantId: otherTenantId, roles: ["Admin"] });
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [createFilesFeature(), photoFeature],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+const DEFAULT_ATTACH = { entityType: "photo", fieldName: "avatar" };
+
+// `null` (not the default-param-triggering `undefined`) is the explicit
+// "unattached upload" sentinel — a caller passing `undefined` here would
+// silently fall back to DEFAULT_ATTACH instead.
+async function uploadFile(
+  asUser = user,
+  attach: { entityType: string; fieldName: string } | null = DEFAULT_ATTACH,
+): Promise<string> {
+  const token = await stack.jwt.sign(asUser);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from([1, 2, 3])], "avatar.jpg", { type: "image/jpeg" }));
+  if (attach !== null) {
+    fd.append("entityType", attach.entityType);
+    fd.append("fieldName", attach.fieldName);
+  }
+  const { body, contentType } = await buildMultipartBody(fd);
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+    body,
+  });
+  expect(res.status).toBe(201);
+  const json = (await res.json()) as { id: string };
+  return json.id;
+}
+
+describe("GET /api/files/:id/variant/:name", () => {
+  test("returns the rendered bytes with the spec's mimeType", async () => {
+    renderCalls = 0;
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/webp");
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(VARIANT_BYTES);
+  });
+
+  test("a second call hits the cache — the renderer runs only once", async () => {
+    renderCalls = 0;
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const first = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const second = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(new Uint8Array(await second.arrayBuffer())).toEqual(VARIANT_BYTES);
+    expect(renderCalls).toBe(1);
+  });
+
+  test("an undeclared variant name returns 404", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/nope`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("__proto__ as the variant name returns 404", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/__proto__`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("an unattached upload has no field to resolve a variant from — 404", async () => {
+    const fileId = await uploadFile(user, null);
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("a user from a different tenant gets 404 — tenant isolation", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(otherTenantUser);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("no Authorization header does not return 200", async () => {
+    const fileId = await uploadFile();
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`);
+
+    expect(res.status).toBe(401);
+  });
+});

package/src/derivatives/field-variants.ts

@@ -0,0 +1,20 @@
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { Registry } from "../engine/types";
+
+// The field definition IS the whitelist: a request carries a variant NAME,
+// never a spec, so no caller can drive an arbitrary render. `hasOwn` and not
+// a plain index — `name` comes off a URL segment, and `__proto__` would
+// otherwise resolve to something truthy that is not a VariantSpec.
+export function resolveFieldVariant(
+  registry: Registry,
+  entityType: string | null,
+  fieldName: string | null,
+  name: string,
+): VariantSpec | undefined {
+  if (entityType === null || fieldName === null) return undefined;
+  const field = registry.getEntity(entityType)?.fields[fieldName];
+  if (field === undefined) return undefined;
+  if (field.type !== "image" && field.type !== "images") return undefined;
+  if (field.variants === undefined || !Object.hasOwn(field.variants, name)) return undefined;
+  return field.variants[name];
+}

package/src/derivatives/index.ts

@@ -1,3 +1,4 @@
 export type { DerivativesContextDeps } from "./derivatives-context";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context";
-export { canonicalJson, specHash, variantSuffix } from "./variant-key";
+export { resolveFieldVariant } from "./field-variants";
+export { canonicalJson, specHash, VARIANT_NAME_PATTERN, variantSuffix } from "./variant-key";

package/src/derivatives/variant-key.ts

@@ -25,7 +25,7 @@ export function specHash(spec: VariantSpec): string {
   return createHash("sha256").update(canonicalJson(spec)).digest("hex").slice(0, 8);
 }
 
-const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;
+export const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;
 
 export function variantSuffix(name: string, spec: VariantSpec): string {
   // `name` ends up in a storage key (see deriveKey) — an unvalidated value

package/src/engine/__tests__/boot-validator.test.ts

@@ -11,6 +11,8 @@ import {
   createEmbeddedListField,
   createEntity,
   createFilesField,
+  createImageField,
+  createImagesField,
   createJsonbField,
   createMultiSelectField,
   createTextField,
@@ -1355,6 +1357,138 @@ describe("boot-validator", () => {
     });
   });
 
+  describe("image variants", () => {
+    test("accepts a valid variant spec", () => {
+      process.env["FILE_STORAGE_PROVIDER"] = "local";
+      try {
+        const features = [
+          defineFeature("profile", (r) => {
+            r.entity(
+              "person",
+              createEntity({
+                fields: {
+                  avatar: createImageField({
+                    variants: {
+                      profile: { fit: "cover", size: { width: 512, height: 512 }, format: "webp" },
+                    },
+                  }),
+                },
+              }),
+            );
+          }),
+        ];
+        expect(() => validateBoot(features)).not.toThrow();
+      } finally {
+        delete process.env["FILE_STORAGE_PROVIDER"];
+      }
+    });
+
+    test("accepts a variant with only `format` — the legitimate format-only case, no size/maxEdge required", () => {
+      process.env["FILE_STORAGE_PROVIDER"] = "local";
+      try {
+        const features = [
+          defineFeature("profile", (r) => {
+            r.entity(
+              "person",
+              createEntity({
+                fields: {
+                  avatar: createImageField({ variants: { web: { format: "webp" } } }),
+                },
+              }),
+            );
+          }),
+        ];
+        expect(() => validateBoot(features)).not.toThrow();
+      } finally {
+        delete process.env["FILE_STORAGE_PROVIDER"];
+      }
+    });
+
+    test("rejects a variant setting both `size` and `maxEdge`", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({
+                  variants: {
+                    both: { size: { width: 100, height: 100 }, maxEdge: 200 },
+                  },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/both/);
+    });
+
+    test("rejects a variant name containing a slash", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { "a/b": { maxEdge: 200 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/must match/);
+    });
+
+    test("rejects maxEdge: 0", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { thumb: { maxEdge: 0 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/maxEdge/);
+    });
+
+    test("rejects quality: 101", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { thumb: { maxEdge: 200, quality: 101 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/quality/);
+    });
+
+    test("the same validation applies to `images` (multi) fields", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                gallery: createImagesField({ variants: { "a/b": { maxEdge: 200 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/must match/);
+    });
+  });
+
   // --- entityList column-renderer form-check ---
   // Validator akzeptiert die `{ react: { __component: "Name" } }`-Form
   // (PlatformComponent → client-side Registry-Lookup) und prüft sie

package/src/engine/boot-validator/entity-handler.ts

@@ -1,3 +1,5 @@
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key";
 import { parseRefTarget } from "../parse-ref-target";
 import type { EmbeddedFieldDef, EntityDefinition, FeatureDefinition } from "../types";
 
@@ -685,6 +687,56 @@ export function validateMultiSelectFields(feature: FeatureDefinition): void {
   }
 }
 
+// --- Image variant validation ---
+
+function isPositiveInt(value: number): boolean {
+  return Number.isInteger(value) && value > 0;
+}
+
+function assertValidVariantSpec(name: string, spec: VariantSpec, where: string): void {
+  if (!VARIANT_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Image variant "${name}" ${where} must match ${VARIANT_NAME_PATTERN.source} — the name becomes part of a storage key and a URL segment.`,
+    );
+  }
+  if (spec.size !== undefined && spec.maxEdge !== undefined) {
+    throw new Error(`Image variant "${name}" ${where} sets both "size" and "maxEdge" — pick one.`);
+  }
+  if (
+    spec.size !== undefined &&
+    !(isPositiveInt(spec.size.width) && isPositiveInt(spec.size.height))
+  ) {
+    throw new Error(
+      `Image variant "${name}" ${where} has a non-positive-integer "size" (${spec.size.width}x${spec.size.height}).`,
+    );
+  }
+  if (spec.maxEdge !== undefined && !isPositiveInt(spec.maxEdge)) {
+    throw new Error(
+      `Image variant "${name}" ${where} has a non-positive-integer "maxEdge" (${spec.maxEdge}).`,
+    );
+  }
+  if (spec.quality !== undefined && !(isPositiveInt(spec.quality) && spec.quality <= 100)) {
+    throw new Error(
+      `Image variant "${name}" ${where} has "quality" ${spec.quality} — must be an integer in 1..100.`,
+    );
+  }
+}
+
+// A bad spec is only visible when someone finally requests that variant —
+// possibly months later, in production. Catch it at boot instead.
+export function validateImageVariants(feature: FeatureDefinition): void {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+      if (field.type !== "image" && field.type !== "images") continue;
+      if (field.variants === undefined) continue;
+      const where = `on "${entityName}.${fieldName}" in feature "${feature.name}"`;
+      for (const [name, spec] of Object.entries(field.variants)) {
+        assertValidVariantSpec(name, spec, where);
+      }
+    }
+  }
+}
+
 // --- Transition validation ---
 
 export function validateTransitions(feature: FeatureDefinition): void {

package/src/engine/boot-validator/index.ts

@@ -25,6 +25,7 @@ import {
   validateExtensionPreSaveWiring,
   validateFileFields,
   validateHandlerAccess,
+  validateImageVariants,
   validateLocatedTimestamps,
   validateMultiSelectFields,
   validateMultiStreamProjections,
@@ -168,6 +169,7 @@ export function validateBoot(
     validateApiExposureMatching(feature, allExposedApis, featureMap);
     validateEmbeddedFields(feature, featureMap);
     validateMultiSelectFields(feature);
+    validateImageVariants(feature);
     validateReferenceFields(feature, featureMap);
     validateTransitions(feature);
     validateExtensionUsages(feature, extensionProviders);

package/src/files/file-routes.ts

@@ -4,9 +4,11 @@ import { getUser } from "../api/auth-middleware";
 import type { DbConnection } from "../db/connection";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { createTenantDb } from "../db/tenant-db";
+import { createDerivativesContext, resolveFieldVariant } from "../derivatives";
 import { isFileField, type Registry, type SessionUser, type TenantId } from "../engine/types";
 import { generateId } from "../utils";
 import { buildContentDispositionHeader } from "./content-disposition";
+import { createFileContext } from "./file-handle";
 import { fileRefEntity } from "./file-ref-entity";
 import { fileRefsTable } from "./file-ref-table";
 import type { FileProviderResolver } from "./provider-resolver";
@@ -235,6 +237,48 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     });
   });
 
+  // GET /files/:id/variant/:name — a named derived version of the file.
+  // Same tenant + guard gate as the download above; the original stays
+  // reachable only through that route. The public, anonymous counterpart is
+  // a separate cut (#1951) and does not go through createFileRoutes.
+  api.get("/files/:id/variant/:name", async (c) => {
+    const user = getUser(c);
+    const id = c.req.param("id");
+    const name = c.req.param("name");
+    const fileRef = await loadFileForTenant(id, user.tenantId);
+    if (!fileRef) return c.json({ error: "not_found" }, 404);
+
+    const decision = await guard({ fileRef, user, operation: "read" });
+    if (decision === "deny") return c.json({ error: "not_found" }, 404);
+
+    // An unknown name and a denied file answer alike, so the route never
+    // confirms what exists. A missing renderer is NOT folded in here — that
+    // throws out of variant() as a 500, because a mount gap is a config
+    // error, not a missing variant.
+    const registry = options.registry;
+    const spec = registry
+      ? resolveFieldVariant(registry, fileRef.entityType, fileRef.fieldName, name)
+      : undefined;
+    if (!registry || !spec) return c.json({ error: "not_found" }, 404);
+
+    // Built per request: createFileContext caches the resolved provider, so
+    // one shared across requests would serve tenant A's store to tenant B.
+    const files = createFileContext(() => options.resolveProvider(user.tenantId));
+    const derivatives = createDerivativesContext({
+      files,
+      registry,
+      db,
+      tenantId: user.tenantId,
+    });
+    const result = await derivatives.variant(id, spec, name);
+    const data = await files.ref(result.storageKey).read();
+    // No Content-Length/Content-Disposition: fileRef.size is the ORIGINAL's
+    // size, and a variant is rendered for display, not for download.
+    return new Response(Buffer.from(data), {
+      headers: { "Content-Type": result.mimeType },
+    });
+  });
+
   // DELETE /files/:id — same guard, "delete" operation. Apps can differentiate
   // read vs delete in their custom guard (e.g. only uploaders delete).
   api.delete("/files/:id", async (c) => {