@cosmicdrift/kumiko-bundled-features 0.192.0 → 0.193.1

package/package.json

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

package/src/auth-email-password/__tests__/invite-flow-kms.integration.test.ts

@@ -33,7 +33,7 @@ import { createDeliveryFeature, createDeliveryTestContext } from "../../delivery
 import { notificationPreferencesTable } from "../../delivery/tables";
 import { createRendererFoundationFeature } from "../../renderer-foundation/feature";
 import { createRendererSimpleFeature, simpleRenderer } from "../../renderer-simple";
-import { hashPassword } from "../../shared";
+import { decryptStoredPii, hashPassword } from "../../shared";
 import { createTemplateResolverFeature } from "../../template-resolver/feature";
 import { createTenantFeature } from "../../tenant";
 import { tenantInvitationEntity, tenantInvitationsTable } from "../../tenant/invitation-table";
@@ -42,6 +42,7 @@ import { tenantEntity, tenantTable } from "../../tenant/schema/tenant";
 import { seedTenant, seedTenantMembership } from "../../tenant/seeding";
 import { createUserFeature } from "../../user/feature";
 import { userEntity, userTable } from "../../user/schema/user";
+import { tenantInvitationDeleteHook } from "../../user-data-rights-defaults";
 import { AuthHandlers } from "../constants";
 import { createAuthEmailPasswordFeature } from "../feature";
 import { seedUser } from "../seeding";
@@ -298,4 +299,45 @@ describe("auth flows with active KMS + blind index", () => {
     expect(isPiiCiphertext(list[0]?.invitedBy)).toBe(false);
     expect(list[0]?.invitedBy).toBe(aliceId);
   });
+
+  // fw-review #7: the inviter-forget arm compared a plaintext userId against
+  // the encrypted `invitedBy` column via selectMany's equality filter — with
+  // no lookupable/blind-index column on `invitedBy`, that filter matched
+  // zero rows under active KMS, so Alice's Art.17 forget never anonymized
+  // rows for invitations she sent. Fixed by loading the tenant's invitations
+  // and decrypting `invitedBy` per row for comparison instead.
+  test("Art.17 forget anonymizes invitedBy for an invite the requester sent, even under active KMS", async () => {
+    await inviteEmail(CAROL_EMAIL, "Editor");
+
+    const [rawBefore] = await asRawClient(stack.db).unsafe<Record<string, unknown>>(
+      `SELECT * FROM "${tenantInvitationsTable.tableName}" WHERE tenant_id = $1`,
+      [TENANT_A_ID],
+    );
+    if (!rawBefore) throw new Error("no invitation row seeded");
+    expect(isPiiCiphertext(rawBefore["invited_by"])).toBe(true);
+
+    await tenantInvitationDeleteHook(
+      { db: stack.db, registry: stack.registry, tenantId: TENANT_A_ID, userId: aliceId },
+      "delete",
+    );
+
+    const [rawAfter] = await asRawClient(stack.db).unsafe<Record<string, unknown>>(
+      `SELECT * FROM "${tenantInvitationsTable.tableName}" WHERE tenant_id = $1`,
+      [TENANT_A_ID],
+    );
+    if (!rawAfter)
+      throw new Error("invitation row disappeared — inviter-forget only severs the link");
+    // The invitee link is untouched — this row belongs to Carol, not Alice.
+    expect(isPiiCiphertext(rawAfter["email"])).toBe(true);
+    // invitedBy is re-encrypted on write, so assert on the decrypted value —
+    // the sentinel itself lives as INVITED_BY_ANONYMIZED in the hook file.
+    expect(isPiiCiphertext(rawAfter["invited_by"])).toBe(true);
+    const decryptedInvitedBy = await decryptStoredPii(
+      String(rawAfter["invited_by"]),
+      "invitedBy",
+      "test",
+    );
+    expect(decryptedInvitedBy).toBe("anonymized");
+    expect(decryptedInvitedBy).not.toBe(aliceId);
+  });
 });

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

@@ -0,0 +1,237 @@
+// 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).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  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([7, 7, 7]);
+
+let renderCalls = 0;
+const fakeRender: DerivativeRendererPlugin["render"] = async () => {
+  renderCalls++;
+  return VARIANT_BYTES;
+};
+
+const PUBLIC_WIDGET_ID = "widget-public";
+const OTHER_WIDGET_ID = "widget-other";
+
+let predicateCalls = 0;
+const widgetPredicateFeature = defineFeature("publicvariantroutetest", (r) => {
+  r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "widget", {
+    isPublic: (args: DerivativePublicPredicateArgs) => {
+      predicateCalls++;
+      return args.entityId === PUBLIC_WIDGET_ID;
+    },
+  });
+  // EXT_DERIVATIVE_RENDERER itself is already declared by
+  // createFileDerivativesFeature — only register a plugin under it here.
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", { render: fakeRender });
+});
+
+const TENANT_A = testTenantId(1);
+const TENANT_B = testTenantId(2);
+const HOST_A = "tenant-a.example.com";
+const HOST_B = "tenant-b.example.com";
+
+const userA = createTestUser({ id: 1, tenantId: TENANT_A, roles: ["Admin"] });
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      fileFoundationFeature,
+      createFilesFeature(),
+      createFileDerivativesFeature({
+        resolveApexTenant: (host) => {
+          if (host === HOST_A) return TENANT_A;
+          if (host === HOST_B) return TENANT_B;
+          return null;
+        },
+      }),
+      widgetPredicateFeature,
+    ],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  renderCalls = 0;
+  predicateCalls = 0;
+  // Fresh rate-limit bucket per test — no carry-over.
+  await stack.redis.flushNamespace();
+});
+
+async function uploadFile(
+  asUser: typeof userA,
+  attach: { entityType: string; entityId: string },
+): 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");
+  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 /media/:fileRefId/:variant (anonymous, default-deny)", () => {
+  test("no predicate registered for the FileRef's entityType → 404", async () => {
+    const fileId = await uploadFile(userA, { entityType: "unregistered-type", entityId: "x" });
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(404);
+    expect(renderCalls).toBe(0);
+  });
+
+  test("predicate registered but returns false → 404", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: OTHER_WIDGET_ID });
+
+    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("predicate returns true → 200 with rendered bytes, mimeType, Vary: Host", 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("Content-Type")).toBe("image/webp");
+    expect(res.headers.get("Vary")).toBe("Host");
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(VARIANT_BYTES);
+  });
+
+  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 });
+
+    const first = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+    const second = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(renderCalls).toBe(1);
+  });
+
+  test("If-None-Match with a matching ETag → 304, no body", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    const first = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+    const etag = first.headers.get("ETag");
+    expect(etag).toBeTruthy();
+
+    const revalidate = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`, {
+      headers: { "if-none-match": etag ?? "" },
+    });
+
+    expect(revalidate.status).toBe(304);
+    expect(await revalidate.arrayBuffer()).toEqual(new ArrayBuffer(0));
+  });
+
+  test("invalid variant name → 404, pre-check runs before any DB/systemQuery work", 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`);
+
+    expect(res.status).toBe(404);
+    expect(predicateCalls).toBe(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.
+    const res = await stack.app.request(
+      `http://${HOST_A}/media/00000000-0000-4000-8000-000000000000/thumb`,
+    );
+
+    expect(res.status).toBe(404);
+  });
+
+  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 });
+
+    const res = await stack.app.request(`http://${HOST_B}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(404);
+  });
+
+  test("resolveApexTenant returns null for an unknown host → 404", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    const res = await stack.app.request(`http://unknown.example.com/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(404);
+  });
+
+  test("more than `limit` requests from the same IP within the window → 429 (Step-1 regression)", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+    const xff = "203.0.113.9";
+
+    // publicVariantQuery's rateLimit is {per: "ip", limit: 60, windowSeconds: 60}
+    // — 60 calls must succeed, the 61st must be blocked. Without the Step-1
+    // fix (requestContext.run wrapping systemQuery in server.ts) `ip` is
+    // never populated for an r.httpRoute-invoked handler, enforceRateLimit's
+    // bucket resolves to "skip", and this test would fail — every call
+    // would return 200.
+    for (let i = 0; i < 60; i++) {
+      const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`, {
+        headers: { "x-forwarded-for": xff },
+      });
+      expect(res.status).toBe(200);
+    }
+
+    const blocked = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`, {
+      headers: { "x-forwarded-for": xff },
+    });
+    expect(blocked.status).toBe(429);
+  }, 20000);
+});

package/src/file-derivatives/feature.ts

@@ -6,28 +6,149 @@
 // configurable, so this feature has no `r.config` and no
 // `r.extensionSelector`.
 
-import { defineFeature, EXT_DERIVATIVE_RENDERER } from "@cosmicdrift/kumiko-framework/engine";
+import { cachedResponse, computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
+import {
+  defineFeature,
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
+  EXT_DERIVATIVE_RENDERER,
+  type FeatureDefinition,
+  type TenantId,
+} 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";
 
-export const fileDerivativesFeature = 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.",
-  );
-  r.uiHints({
-    displayLabel: "File Derivatives",
-    category: "storage",
-    recommended: false,
-  });
-  // Needs a storage provider to read the original + write the variant —
-  // without file-foundation there's nothing to derive from or write to.
-  r.requires("file-foundation");
-
-  r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
-    onRegister: () => {
-      // No side-effects at register-time — resolution (exact MIME match,
-      // then `<type>/*` wildcard) happens at request-time in
-      // resolveRenderer, mirrors file-foundation's fileProvider point.
-    },
+// 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;
+
+export type PublicVariantResolveApexTenant = (
+  host: string,
+) => Promise<TenantId | null> | TenantId | null;
+
+export type FileDerivativesOptions = {
+  /** Host → tenantId for the anonymous `/media/:fileRefId/:variant` route.
+   *  Without this option the route is NOT mounted — existing consumers that
+   *  only need `ctx.derivatives` are unaffected. */
+  readonly resolveApexTenant?: PublicVariantResolveApexTenant;
+  /** Base path of the public variant route. Default "/media". */
+  readonly basePath?: string;
+};
+
+// Raw handler-return of publicVariantQuery — systemQuery dispatches
+// directly against the handler, no `{data}` wire envelope.
+type PublicVariantQueryResult = {
+  readonly dataBase64: string;
+  readonly mimeType: string;
+  readonly storageKey: string;
+} | 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
+// 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.
+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.",
+    );
+    r.uiHints({
+      displayLabel: "File Derivatives",
+      category: "storage",
+      recommended: false,
+    });
+    // Needs a storage provider to read the original + write the variant —
+    // without file-foundation there's nothing to derive from or write to.
+    r.requires("file-foundation");
+
+    r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
+      onRegister: () => {
+        // No side-effects at register-time — resolution (exact MIME match,
+        // then `<type>/*` wildcard) happens at request-time in
+        // resolveRenderer, mirrors file-foundation's fileProvider point.
+      },
+    });
+    r.extendsRegistrar(EXT_DERIVATIVE_PUBLIC_PREDICATE, {
+      onRegister: () => {
+        // No side-effects at register-time — resolution happens at
+        // request-time in publicVariantQuery, keyed by the FileRef's
+        // entityType.
+      },
+    });
+
+    const queries = { publicVariant: r.queryHandler(publicVariantQuery) };
+
+    if (opts.resolveApexTenant) {
+      const resolveApexTenant = opts.resolveApexTenant;
+
+      r.httpRoute({
+        method: "GET",
+        path: `${basePath}/:fileRefId/:variant`,
+        anonymous: true,
+        handler: async (c, { systemQuery }) => {
+          // `param(...)` is string|undefined here — `path` is a computed
+          // 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)) {
+            return c.text("not found", 404);
+          }
+
+          const host = c.req.header("host") ?? new URL(c.req.url).host;
+          const tenantId = await resolveApexTenant(host);
+          if (!tenantId) return c.text("not found", 404);
+
+          let result: PublicVariantQueryResult;
+          try {
+            // @cast-boundary engine-payload — shape comes from
+            // publicVariantQuery's return type.
+            result = (await systemQuery(
+              PUBLIC_VARIANT_QN,
+              { fileRefId, variant },
+              tenantId,
+            )) as PublicVariantQueryResult;
+          } catch (err) {
+            if (err instanceof RateLimitError) {
+              return c.text("rate limited", 429);
+            }
+            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, no logger wired into HttpRouteHandlerDeps
+            console.error(
+              `file-derivatives: public-variant query failed for fileRefId="${fileRefId}" variant="${variant}"`,
+              err,
+            );
+            return c.text("variant unavailable", 503);
+          }
+          if (!result) return c.text("not found", 404);
+
+          const bytes = Buffer.from(result.dataBase64, "base64");
+          const etag = computeRevisionEtag([tenantId, fileRefId, variant, result.storageKey]);
+          return cachedResponse(c.req.raw, {
+            body: bytes,
+            etag,
+            cache: { kind: "revalidate", maxAgeSeconds: 60 },
+            headers: { "content-type": result.mimeType, vary: "Host" },
+          });
+        },
+      });
+    }
+
+    return { queries };
   });
-});
+}
+
+export const fileDerivativesFeature = createFileDerivativesFeature();

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

@@ -0,0 +1,122 @@
+// 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.
+// 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
+// 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.
+
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  defineQueryHandler,
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
+  type HandlerContext,
+  type TenantId,
+} 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;
+};
+
+export type DerivativePublicPredicateArgs = {
+  readonly entityId: string;
+  readonly tenantId: TenantId;
+};
+
+export type DerivativePublicPredicatePlugin = {
+  readonly isPublic: (
+    args: DerivativePublicPredicateArgs,
+    ctx: HandlerContext,
+  ) => boolean | Promise<boolean>;
+};
+
+// extension-usage `options` is engine-payload (unknown) — structurally
+// validate instead of casting blind, same pattern as
+// isDerivativeRendererPlugin in derivatives-context.ts.
+function isDerivativePublicPredicatePlugin(o: unknown): o is DerivativePublicPredicatePlugin {
+  return typeof o === "object" && o !== null && "isPublic" in o && typeof o.isPublic === "function";
+}
+
+// Full QN this handler is registered under once mounted into the
+// "file-derivatives" feature (short name below + registry qualification —
+// see qualifyEntityName). Kept as a separate literal, not derived, so
+// feature.ts's systemQuery call doesn't need a code import of the handler
+// def itself — mirrors managed-pages' BY_SLUG_QN.
+export const PUBLIC_VARIANT_QN = "file-derivatives:query:public-variant";
+
+export const publicVariantQuery = defineQueryHandler({
+  name: "public-variant",
+  schema: z.object({
+    fileRefId: z.string(),
+    variant: z.enum(PRESET_VARIANT_NAMES),
+  }),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  // ponytail: "ip" trusts the first x-forwarded-for hop (buildRequestContextData
+  // in request-id-middleware.ts) — this is the ONLY throttle on an anonymous,
+  // internet-facing render/storage-cost route, so it assumes the deployment's
+  // ingress overwrites (not appends to) x-forwarded-for. A direct-to-origin
+  // deployment lets a caller rotate the header per request and bypass this.
+  // Upgrade path if that assumption doesn't hold: trusted-proxy-count config
+  // on buildRequestContextData, same fix point as every other /api/* route.
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
+  handler: async (query, ctx) => {
+    const row = await fetchOne<FileRefRow>(ctx.db, fileRefsTable, {
+      id: query.payload.fileRefId,
+      tenantId: ctx.user.tenantId,
+      isDeleted: false,
+    });
+    if (!row) return null;
+    const { entityType, entityId } = row;
+    if (entityType === null || entityId === null) return null;
+
+    const usage = ctx.registry
+      .getExtensionUsages(EXT_DERIVATIVE_PUBLIC_PREDICATE)
+      .find((u) => u.entityName === entityType);
+    if (!usage) return null;
+    if (!isDerivativePublicPredicatePlugin(usage.options)) {
+      throw new Error(
+        `file-derivatives: "${usage.entityName}" registered ${EXT_DERIVATIVE_PUBLIC_PREDICATE} without an isPublic(args, ctx) — extension options must be a DerivativePublicPredicatePlugin.`,
+      );
+    }
+
+    const isPublic = await usage.options.isPublic({ entityId, tenantId: ctx.user.tenantId }, ctx);
+    if (!isPublic) return null;
+
+    // ctx.files/ctx.derivatives are optional on HandlerContext (only wired
+    // when file-foundation resolved a provider) — narrow via a plain guard,
+    // never `!`/`as`, and surface a real config error (not a silent deny)
+    // when the feature isn't actually wired.
+    const { files, derivatives } = ctx;
+    if (!files || !derivatives) {
+      throw new Error(
+        "file-derivatives requires ctx.files/ctx.derivatives — is file-foundation mounted?",
+      );
+    }
+
+    const spec = VARIANT_SPECS[query.payload.variant];
+    const result = await derivatives.variant(query.payload.fileRefId, spec, query.payload.variant);
+    const bytes = await files.ref(result.storageKey).read();
+
+    // ponytail: fully buffered (no streaming), +33% over the wire from
+    // base64 — HttpRouteHandlerDeps only exposes {app, systemQuery} (no
+    // direct ctx.files access from the Hono handler itself), and the local
+    // dev storage provider has no getSignedUrl (a redirect design wouldn't
+    // work in dev). Upgrade path: a binary-passthrough dispatcher primitive
+    // would be its own, larger issue.
+    return {
+      dataBase64: Buffer.from(bytes).toString("base64"),
+      mimeType: result.mimeType,
+      storageKey: result.storageKey,
+    };
+  },
+});

package/src/file-derivatives/index.ts

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

package/src/file-derivatives/presets.ts

@@ -4,3 +4,10 @@ export const thumb = { maxEdge: 160, fit: "cover", format: "webp" } as const sat
 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;