@cosmicdrift/kumiko-bundled-features 0.196.0 → 0.197.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.196.0",
+  "version": "0.197.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.196.0",
-    "@cosmicdrift/kumiko-framework": "0.196.0",
-    "@cosmicdrift/kumiko-headless": "0.196.0",
-    "@cosmicdrift/kumiko-renderer": "0.196.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.196.0",
-    "@cosmicdrift/kumiko-types": "0.196.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.197.0",
+    "@cosmicdrift/kumiko-framework": "0.197.0",
+    "@cosmicdrift/kumiko-headless": "0.197.0",
+    "@cosmicdrift/kumiko-renderer": "0.197.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.197.0",
+    "@cosmicdrift/kumiko-types": "0.197.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",

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

@@ -0,0 +1,141 @@
+// Proves #1989/2: DerivativePublicPredicateArgs carries `fieldName` and
+// `variant` (not just entityId/tenantId) through to `isPublic`, so an app
+// can opt individual variants out of public serving instead of every
+// declared variant on an entityType being implicitly public once the
+// entityType-level check passes.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createImageField,
+  defineFeature,
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
+  EXT_DERIVATIVE_RENDERER,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  buildMultipartBody,
+  patchFileInstanceofForBunTest,
+} from "@cosmicdrift/kumiko-framework/testing";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { createConfigFeature } from "../../config";
+import { fileFoundationFeature } from "../../file-foundation";
+import { createFileDerivativesFeature } from "../feature";
+import type { DerivativePublicPredicateArgs } from "../handlers/public-variant.query";
+
+const VARIANT_BYTES = new Uint8Array([9, 9, 9]);
+const fakeRender: DerivativeRendererPlugin["render"] = async () => VARIANT_BYTES;
+
+const ENTITY_ID = "gadget-1";
+const HOST = "gadgets.example.com";
+const TENANT = testTenantId(7);
+
+// Deliberately gates on `variant`, not just entityId — "premium" stays
+// denied even for an entityId the entityType-level check would otherwise
+// allow, proving a predicate can opt a specific variant out.
+let receivedArgs: DerivativePublicPredicateArgs[] = [];
+const gadgetEntity = createEntity({
+  table: "public_variant_predicate_gadgets",
+  fields: {
+    img: createImageField({
+      variants: {
+        thumb: { maxEdge: 160, format: "webp" },
+        premium: { maxEdge: 4096, format: "webp" },
+      },
+    }),
+  },
+});
+
+const gadgetPredicateFeature = defineFeature("publicvariantpredicateargstest", (r) => {
+  r.entity("gadget", gadgetEntity);
+  r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "gadget", {
+    isPublic: (args: DerivativePublicPredicateArgs) => {
+      receivedArgs.push(args);
+      return args.variant !== "premium";
+    },
+  });
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", { render: fakeRender });
+});
+
+const user = createTestUser({ id: 1, tenantId: TENANT, roles: ["Admin"] });
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      fileFoundationFeature,
+      createFilesFeature(),
+      createFileDerivativesFeature({
+        resolveApexTenant: (host) => (host === HOST ? TENANT : null),
+      }),
+      gadgetPredicateFeature,
+    ],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  receivedArgs = [];
+  await stack.redis.flushNamespace();
+});
+
+async function uploadGadgetImage(): Promise<string> {
+  const token = await stack.jwt.sign(user);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from([1, 2, 3])], "img.jpg", { type: "image/jpeg" }));
+  fd.append("entityType", "gadget");
+  fd.append("entityId", ENTITY_ID);
+  fd.append("fieldName", "img");
+  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("file-derivatives :: isPublic receives fieldName + variant", () => {
+  test("isPublic is called with the FileRef's fieldName and the requested variant name", async () => {
+    const fileId = await uploadGadgetImage();
+
+    const res = await stack.app.request(`http://${HOST}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(200);
+    expect(receivedArgs).toHaveLength(1);
+    expect(receivedArgs[0]).toMatchObject({
+      entityId: ENTITY_ID,
+      fieldName: "img",
+      variant: "thumb",
+    });
+  });
+
+  test("a predicate that opts a specific variant out denies exactly that variant, not the whole entity", async () => {
+    const fileId = await uploadGadgetImage();
+
+    const thumbRes = await stack.app.request(`http://${HOST}/media/${fileId}/thumb`);
+    const premiumRes = await stack.app.request(`http://${HOST}/media/${fileId}/premium`);
+
+    expect(thumbRes.status).toBe(200);
+    expect(premiumRes.status).toBe(404);
+    expect(receivedArgs.map((a) => a.variant)).toEqual(["thumb", "premium"]);
+  });
+});

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

@@ -0,0 +1,75 @@
+// Proves #1989/3: publicVariantQuery's `fileRefId` is UUID-validated by the
+// handler's own zod schema, not only by the httpRoute wrapper's
+// FILE_REF_ID_RE pre-check. The generic `/api/query` dispatch path (reachable
+// once resolveApexTenant is configured, see public-variant-query-gating.
+// integration.test.ts for the "not configured" case) skips that httpRoute
+// pre-check entirely and calls `handler.schema.safeParse` directly — before
+// this fix, a non-UUID `fileRefId` sailed through the schema and hit
+// fetchOne(), throwing a Postgres 22P02 (malformed uuid literal) that
+// poisons the pooled Bun.SQL connection, an unauth DoS primitive.
+
+import { describe, expect, test } from "bun:test";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { createConfigFeature } from "../../config";
+import { fileFoundationFeature } from "../../file-foundation";
+import { createFileDerivativesFeature } from "../feature";
+import { PUBLIC_VARIANT_QN } from "../handlers/public-variant.query";
+
+describe("file-derivatives :: publicVariant query fileRefId validation", () => {
+  test("non-UUID fileRefId via /api/query → 400 validation_error, never reaches the DB", async () => {
+    const stack: TestStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        fileFoundationFeature,
+        createFilesFeature(),
+        createFileDerivativesFeature({ resolveApexTenant: () => SYSTEM_TENANT_ID }),
+      ],
+      anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+      files: { storageProvider: createInMemoryFileProvider() },
+    });
+
+    try {
+      const res = await stack.http.raw("POST", "/api/query", {
+        type: PUBLIC_VARIANT_QN,
+        payload: { fileRefId: "not-a-uuid; DROP TABLE file_refs;--", variant: "thumb" },
+      });
+
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { error?: { code?: string } };
+      expect(body.error?.code).toBe("validation_error");
+    } finally {
+      await stack.cleanup();
+    }
+  });
+
+  test("well-formed but unknown UUID fileRefId via /api/query → 200 with null (schema passes, DB lookup just finds nothing)", async () => {
+    const stack: TestStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        fileFoundationFeature,
+        createFilesFeature(),
+        createFileDerivativesFeature({ resolveApexTenant: () => SYSTEM_TENANT_ID }),
+      ],
+      anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+      files: { storageProvider: createInMemoryFileProvider() },
+    });
+
+    try {
+      const res = await stack.http.raw("POST", "/api/query", {
+        type: PUBLIC_VARIANT_QN,
+        payload: { fileRefId: "00000000-0000-4000-8000-000000000000", variant: "thumb" },
+      });
+
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { data: unknown };
+      expect(body.data).toBeNull();
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});

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

@@ -182,6 +182,16 @@ describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
     expect(new Uint8Array(await res.arrayBuffer())).toEqual(VARIANT_BYTES);
   });
 
+  // setupTestStack doesn't wrap with the app-wide security-headers default, so a pass proves the route sets its own.
+  test("sets X-Content-Type-Options: nosniff on the response itself", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
+  });
+
   test("a second call on the same (fileRefId, variant) hits the cache — renderer runs once", async () => {
     const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
 

package/src/file-derivatives/feature.ts

@@ -78,7 +78,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
 
   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 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.",
+      "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. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",
@@ -171,7 +171,12 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
             body: bytes,
             etag,
             cache: { kind: "revalidate", maxAgeSeconds: 60 },
-            headers: { "content-type": result.mimeType, vary: "Host" },
+            // Explicit here, not left to the app-wide security-headers default, so the route stays safe standalone.
+            headers: {
+              "content-type": result.mimeType,
+              vary: "Host",
+              "x-content-type-options": "nosniff",
+            },
           });
         },
       });

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

@@ -10,7 +10,12 @@
 // FileRef that doesn't exist (no existence-leak via distinct status codes).
 //
 // tenantId comes from `query.user.tenantId` ONLY (host-resolved by the
-// httpRoute wrapper's `resolveApexTenant`), never from the payload.
+// httpRoute wrapper's `resolveApexTenant`), never from the payload — true
+// for the httpRoute-wrapper path. Over the generic `/api/query` dispatch
+// (only reachable when this feature is mounted WITH resolveApexTenant, see
+// feature.ts), `ctx.user.tenantId` instead comes from that dispatcher's own
+// `anonymousAccess` resolution — tenant provenance there depends on the
+// consumer's `resolverTrust`/anonymousAccess setup, not the host.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { resolveFieldVariant } from "@cosmicdrift/kumiko-framework/derivatives";
@@ -29,9 +34,15 @@ type FileRefRow = {
   readonly fieldName: string | null;
 };
 
+// A declared variant with no explicit gate in `isPublic` is implicitly
+// public as soon as the entityType-level check returns `true` — `fieldName`
+// and `variant` let a predicate opt individual fields/variants out (e.g. a
+// cheap `thumb` served publicly while an expensive `full` stays gated).
 export type DerivativePublicPredicateArgs = {
   readonly entityId: string;
   readonly tenantId: TenantId;
+  readonly fieldName: string;
+  readonly variant: string;
 };
 
 export type DerivativePublicPredicatePlugin = {
@@ -58,7 +69,7 @@ export const PUBLIC_VARIANT_QN = "file-derivatives:query:public-variant";
 export const publicVariantQuery = defineQueryHandler({
   name: "public-variant",
   schema: z.object({
-    fileRefId: z.string(),
+    fileRefId: z.string().uuid(),
     variant: z.string().min(1).max(64),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
@@ -90,7 +101,10 @@ export const publicVariantQuery = defineQueryHandler({
       );
     }
 
-    const isPublic = await usage.options.isPublic({ entityId, tenantId: ctx.user.tenantId }, ctx);
+    const isPublic = await usage.options.isPublic(
+      { entityId, tenantId: ctx.user.tenantId, fieldName, variant: query.payload.variant },
+      ctx,
+    );
     if (!isPublic) return null;
 
     // ctx.files/ctx.derivatives are optional on HandlerContext (only wired

package/src/file-derivatives/index.ts

@@ -1,3 +1,7 @@
 export type { FileDerivativesOptions, PublicVariantResolveApexTenant } from "./feature";
 export { createFileDerivativesFeature, fileDerivativesFeature } from "./feature";
+export type {
+  DerivativePublicPredicateArgs,
+  DerivativePublicPredicatePlugin,
+} from "./handlers/public-variant.query";
 export { card, full, hero, thumb } from "./presets";

package/src/ledger/index.ts

@@ -35,6 +35,7 @@ export {
   reverseTransactionHandler,
 } from "./handlers/reverse-transaction.write";
 export {
+  findReversedIds,
   type LedgerTxRow,
   mergeScheduleActuals,
   type ProjectedPeriod,