@cosmicdrift/kumiko-bundled-features 0.308.0 → 0.310.0

package/src/file-derivatives/feature.ts

@@ -18,6 +18,10 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { RateLimitError } from "@cosmicdrift/kumiko-framework/errors";
 import { PUBLIC_VARIANT_QN, publicVariantQuery } from "./handlers/public-variant.query";
+import {
+  PUBLIC_VARIANT_BY_FILE_REF_QN,
+  publicVariantByFileRefQuery,
+} from "./handlers/public-variant-by-file-ref.query";
 
 const FEATURE_NAME = "file-derivatives";
 
@@ -42,6 +46,8 @@ export type PublicVariantResolveApexTenant = (
   host: string,
 ) => Promise<TenantId | null> | TenantId | null;
 
+export type PublicVariantTenantResolution = "host" | "fileRef";
+
 export type FileDerivativesOptions = {
   /** Host → tenantId for the anonymous `/media/:fileRefId/:variant` route.
    *  Without this option, neither the httpRoute NOR the `publicVariant`
@@ -52,6 +58,14 @@ export type FileDerivativesOptions = {
   readonly resolveApexTenant?: PublicVariantResolveApexTenant;
   /** Base path of the public variant route. Default "/media". */
   readonly basePath?: string;
+  /** How the route picks the tenant a variant is read from. "host" (default):
+   *  tenant = resolveApexTenant(host). "fileRef": resolveApexTenant still
+   *  gates the host (an unknown host still 404s), but the variant itself is
+   *  read from the FileRef row's own tenant — a single shared platform host
+   *  then serves every tenant's public variants. The FileRef-tenant's own
+   *  `isPublic` predicate remains the default-deny gate either way; requires
+   *  `resolveApexTenant`. */
+  readonly publicTenantResolution?: PublicVariantTenantResolution;
 };
 
 // Raw handler-return of publicVariantQuery — systemQuery dispatches
@@ -73,13 +87,22 @@ type PublicVariantQueryResult = {
 // — 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.
+// `resolveApexTenant`, NEVER read from the request payload — in
+// `publicTenantResolution: "fileRef"` mode the tenant instead comes from the
+// FileRef row matching `fileRefId` (never from the payload either), and the
+// by-file-ref handler is reachable over `/api` independently of any Host,
+// but still only returns a variant its FileRef-tenant's `isPublic` allows.
 export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}): FeatureDefinition {
   const basePath = opts.basePath ?? "/media";
+  if (opts.publicTenantResolution !== undefined && !opts.resolveApexTenant) {
+    throw new Error(
+      "createFileDerivativesFeature: publicTenantResolution requires resolveApexTenant — it only changes which tenant a variant is read from, resolveApexTenant still gates the host.",
+    );
+  }
 
   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. 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. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
+      "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. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",
@@ -127,8 +150,18 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
     // `resolveApexTenant` enforces.
     if (opts.resolveApexTenant) {
       const resolveApexTenant = opts.resolveApexTenant;
+      const byFileRef = opts.publicTenantResolution === "fileRef";
+      const routeQn = byFileRef ? PUBLIC_VARIANT_BY_FILE_REF_QN : PUBLIC_VARIANT_QN;
 
       r.queryHandler(publicVariantQuery);
+      // publicVariantByFileRefQuery is the ONLY way "fileRef" mode is
+      // reachable — registered ONLY in that mode for the same reason
+      // publicVariantQuery is gated above: registering it unconditionally
+      // would expose its unsafeRaw, cross-tenant FileRef lookup via the
+      // generic `/api` query dispatch even in default "host" mode.
+      if (byFileRef) {
+        r.queryHandler(publicVariantByFileRefQuery);
+      }
 
       r.httpRoute({
         method: "GET",
@@ -156,9 +189,10 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
           let result: PublicVariantQueryResult;
           try {
             // @cast-boundary engine-payload — shape comes from
-            // publicVariantQuery's return type.
+            // publicVariantQuery's return type (publicVariantByFileRefQuery
+            // returns exactly that, or null, never its own shape).
             result = (await systemQuery(
-              PUBLIC_VARIANT_QN,
+              routeQn,
               { fileRefId, variant },
               tenantId,
             )) as PublicVariantQueryResult;

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

@@ -0,0 +1,40 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createAnonymousUser,
+  defineQueryHandler,
+  isUuid,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { PUBLIC_VARIANT_QN, publicVariantPayloadSchema } from "./public-variant.query";
+
+type FileRefTenantRow = {
+  readonly tenantId: TenantId;
+};
+
+const BY_FILE_REF_ESCAPE_HATCH_REASON =
+  "shared public host serves every tenant's public variants; the FileRef row names the tenant, and publicVariantQuery's isPublic gate still runs inside that tenant via queryAs";
+
+// Full QN this handler is registered under, mirrors PUBLIC_VARIANT_QN.
+export const PUBLIC_VARIANT_BY_FILE_REF_QN = "file-derivatives:query:public-variant-by-file-ref";
+
+export const publicVariantByFileRefQuery = defineQueryHandler({
+  name: "public-variant-by-file-ref",
+  schema: publicVariantPayloadSchema,
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  agent: { expose: false },
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
+  escapeHatch: {
+    reason: BY_FILE_REF_ESCAPE_HATCH_REASON,
+  },
+  handler: async (query, ctx) => {
+    const row = await fetchOne<FileRefTenantRow>(
+      ctx.db.unsafeRaw(BY_FILE_REF_ESCAPE_HATCH_REASON),
+      fileRefsTable,
+      { id: query.payload.fileRefId, isDeleted: false },
+    );
+    if (!row || !isUuid(row.tenantId)) return null;
+
+    return ctx.queryAs(createAnonymousUser(row.tenantId), PUBLIC_VARIANT_QN, query.payload);
+  },
+});

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

@@ -16,6 +16,11 @@
 // 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.
+//
+// In `publicTenantResolution: "fileRef"` mode, this handler is also the
+// `ctx.queryAs(createAnonymousUser(fileRefTenantId), ...)` target of
+// publicVariantByFileRefQuery — tenantId there comes from the FileRef row,
+// but this handler's own isPublic gate runs exactly the same either way.
 
 import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
@@ -72,15 +77,19 @@ declare module "@cosmicdrift/kumiko-framework/engine" {
 // def itself — mirrors managed-pages' BY_SLUG_QN.
 export const PUBLIC_VARIANT_QN = "file-derivatives:query:public-variant";
 
+// Shared with publicVariantByFileRefQuery — same payload shape, both routes
+// forward `{ fileRefId, variant }` unchanged.
+export const publicVariantPayloadSchema = z.object({
+  // Loose, version-agnostic UUID shape (same as isUuid/TENANT_ID_REGEX in
+  // packages/types) — not zod's `.uuid()`, which is stricter than this
+  // repo's convention and would reject valid v7/nil ids the DB accepts.
+  fileRefId: z.string().refine(isUuid, "invalid fileRefId"),
+  variant: z.string().min(1).max(64),
+});
+
 export const publicVariantQuery = defineQueryHandler({
   name: "public-variant",
-  schema: z.object({
-    // Loose, version-agnostic UUID shape (same as isUuid/TENANT_ID_REGEX in
-    // packages/types) — not zod's `.uuid()`, which is stricter than this
-    // repo's convention and would reject valid v7/nil ids the DB accepts.
-    fileRefId: z.string().refine(isUuid, "invalid fileRefId"),
-    variant: z.string().min(1).max(64),
-  }),
+  schema: publicVariantPayloadSchema,
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
   agent: { expose: false },
   // ponytail: "ip" trusts the first x-forwarded-for hop (buildRequestContextData

package/src/file-derivatives/index.ts

@@ -1,4 +1,8 @@
-export type { FileDerivativesOptions, PublicVariantResolveApexTenant } from "./feature";
+export type {
+  FileDerivativesOptions,
+  PublicVariantResolveApexTenant,
+  PublicVariantTenantResolution,
+} from "./feature";
 export { createFileDerivativesFeature, fileDerivativesFeature } from "./feature";
 export type {
   DerivativePublicPredicateArgs,

package/src/tenant-lifecycle/__tests__/tenant-lifecycle.integration.test.ts

@@ -16,8 +16,6 @@ import {
   type TestStack,
   TestUsers,
   testTenantId,
-  unsafeCreateEntityTable,
-  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import {
   createTestEnvelopeCipher,
@@ -27,18 +25,16 @@ import {
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import {
   createComplianceProfilesFeature,
-  tenantComplianceProfileEntity,
   tenantComplianceProfileTable,
 } from "../../compliance-profiles";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
-import { configValuesTable } from "../../config/table";
 import { createSessionsFeature } from "../../sessions";
-import { userSessionEntity, userSessionTable } from "../../sessions/schema/user-session";
-import { tenantMembershipEntity, tenantMembershipsTable } from "../../tenant";
+import { userSessionTable } from "../../sessions/schema/user-session";
+import { tenantMembershipsTable } from "../../tenant";
 import { TenantHandlers, TenantQueries } from "../../tenant/constants";
 import { createTenantFeature } from "../../tenant/feature";
-import { tenantEntity, tenantTable } from "../../tenant/schema/tenant";
+import { tenantTable } from "../../tenant/schema/tenant";
 import { seedTenantMembership } from "../../tenant/testing";
 import { createUserFeature } from "../../user/feature";
 import {
@@ -85,12 +81,6 @@ beforeAll(async () => {
     } as import("@cosmicdrift/kumiko-framework/api").AuthRoutesConfig,
   });
   db = stack.db;
-
-  await unsafeCreateEntityTable(db, tenantEntity);
-  await unsafeCreateEntityTable(db, userSessionEntity);
-  await unsafeCreateEntityTable(db, tenantComplianceProfileEntity);
-  await unsafeCreateEntityTable(db, tenantMembershipEntity);
-  await unsafePushTables(db, { configValuesTable });
 });
 
 afterAll(async () => {
@@ -175,6 +165,11 @@ describe("tenant-lifecycle :: request / cancel / 410 gate", () => {
     const err = await stack.http.writeErr(REQUEST, {}, member);
     expect(err.httpStatus).toBe(403);
   });
+
+  test("authenticated read against an unseeded tenant doesn't 500 on a missing read_tenants table (fw#3102)", async () => {
+    const res = await stack.http.query(TenantQueries.me, {}, tenantAdmin);
+    expect(res.status).toBe(200);
+  });
 });
 
 function createPoisonTenantDataFeature() {
@@ -210,9 +205,6 @@ describe("tenant-lifecycle :: pipeline abandon / destroyFailed", () => {
         },
       } as import("@cosmicdrift/kumiko-framework/api").AuthRoutesConfig,
     });
-    await unsafeCreateEntityTable(poisonStack.db, tenantEntity);
-    await unsafeCreateEntityTable(poisonStack.db, tenantComplianceProfileEntity);
-    await unsafePushTables(poisonStack.db, { configValuesTable });
   });
 
   afterAll(async () => {
@@ -416,9 +408,6 @@ describe("tenant-lifecycle :: sweep isolates one tenant's failure from another's
       ],
       extraContext: { configResolver: resolver, configEncryption: encryption },
     });
-    await unsafeCreateEntityTable(isolationStack.db, tenantEntity);
-    await unsafeCreateEntityTable(isolationStack.db, tenantComplianceProfileEntity);
-    await unsafePushTables(isolationStack.db, { configValuesTable });
   });
 
   afterAll(async () => {
@@ -483,11 +472,6 @@ describe("tenant-lifecycle :: 410 gate derived from the mounted provider", () =>
       ],
       extraContext: { configResolver: resolver, configEncryption: encryption },
     });
-    await unsafeCreateEntityTable(derivedStack.db, tenantEntity);
-    await unsafeCreateEntityTable(derivedStack.db, userSessionEntity);
-    await unsafeCreateEntityTable(derivedStack.db, tenantComplianceProfileEntity);
-    await unsafeCreateEntityTable(derivedStack.db, tenantMembershipEntity);
-    await unsafePushTables(derivedStack.db, { configValuesTable });
   });
 
   afterAll(async () => {

package/src/user/seeding.ts

@@ -71,26 +71,8 @@ export async function seedUser(
   // liefert die Projection-Row als Record<string, unknown>.
   if (existing) {
     const id = existing["id"] as string;
-    // Reconcile emailVerified on an already-seeded row: a persistent dev DB
-    // (or a re-run bootstrap) can carry a User seeded before this flag
-    // existed or before it flipped to true — without this, "seed with
-    // emailVerified: true" only ever takes effect on the very first insert
-    // and the flag silently does nothing on every re-run after (#1687).
-    // Goes through the executor (a real `.updated` event), never a direct
-    // write.
-    if (options.emailVerified === true && existing["emailVerified"] !== true) {
-      const result = await userExecutor.update(
-        { id, version: existing["version"] as number, changes: { emailVerified: true } },
-        by,
-        tdb,
-      );
-      // version_conflict = a concurrent write already changed the row —
-      // fine for a seed helper, don't fail the whole seed run over it.
-      if (!result.isSuccess && result.error.code !== "version_conflict") {
-        throw new Error(
-          `seedUser emailVerified reconcile failed: ${result.error.code} — ${JSON.stringify(result.error.details ?? {})}`,
-        );
-      }
+    if (options.emailVerified === true) {
+      await reconcileSeededUserEmailVerified(db, existing, by);
     }
     return { id };
   }
@@ -116,6 +98,33 @@ export async function seedUser(
   return { id: extractId(result.data, "seedUser") };
 }
 
+// A re-run seed onto a row created before emailVerified flipped to true must
+// still set it (#1687) — via the executor, so it lands as a real `.updated` event.
+export async function reconcileSeededUserEmailVerified(
+  db: DbConnection,
+  existingRow: Record<string, unknown>,
+  by: SessionUser,
+): Promise<void> {
+  // skip: already verified, nothing to reconcile
+  if (existingRow["emailVerified"] === true) return;
+  // @cast-boundary db-row: users.id ist uuid-Spalte (string), fetchOne
+  // liefert die Projection-Row als Record<string, unknown>.
+  const id = existingRow["id"] as string;
+  const tdb = createTenantDb(db, by.tenantId, "system");
+  const result = await userExecutor.update(
+    { id, version: existingRow["version"] as number, changes: { emailVerified: true } },
+    by,
+    tdb,
+  );
+  // version_conflict = a concurrent write already changed the row —
+  // fine for a seed helper, don't fail the whole seed run over it.
+  if (!result.isSuccess && result.error.code !== "version_conflict") {
+    throw new Error(
+      `reconcileSeededUserEmailVerified failed: ${result.error.code} — ${JSON.stringify(result.error.details ?? {})}`,
+    );
+  }
+}
+
 // Extrahiert die `id`-Spalte aus dem executor.create-Result. Der
 // Executor liefert ein Record<string, unknown> (die Projection-Row), in
 // das die DB die Aggregat-id reinschreibt — wir prüfen runtime statt

package/src/user-data-rights-defaults/hooks/file-ref.userdata-hook.ts

@@ -1,5 +1,5 @@
 import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { derivativeListPrefix, isDerivativeKeyOf } from "@cosmicdrift/kumiko-framework/derivatives";
+import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   createSystemUser,
   type FieldDefinition,
@@ -10,13 +10,11 @@ import {
   type UserDataHookCtx,
   type UserDataStorageProvider,
 } from "@cosmicdrift/kumiko-framework/engine";
-import {
-  assertSafeStorageKey,
-  fileRefEntity,
-  fileRefsTable,
-} from "@cosmicdrift/kumiko-framework/files";
+import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import { assertErased } from "../../shared";
 
+const ERROR_CONTEXT = "user-data-rights-defaults:fileRef";
+
 // Forget writes go through the executor (events), not deleteMany/updateMany:
 // a projection rebuild replays the events, so the erasure survives. Eventless
 // writes are wiped/resurrected on rebuild — the Art.17 hole this fixes. Bounded:
@@ -174,52 +172,12 @@ function isPersonalFileRow(registry: Registry, row: Record<string, unknown>): bo
   return isPersonalPiiField(fieldDef);
 }
 
-// Derivatives (thumbnails/resized variants — see derivatives-context.ts) are
-// never tracked anywhere but the storage layer: they're rendered under a
-// deterministic key (deriveKey + variantSuffix) computed from the original's
-// key + a render spec, on demand, and nothing writes that key back onto the
-// FileRef row. List the original's key-prefix and keep only candidates whose
-// suffix matches the derivative grammar, anchored to the original's own
-// basename AND extension — a same-directory sibling original (a different
-// file, possibly another user's) shares the same list prefix but fails the
-// extension/suffix check and is never touched.
-async function listDerivativeKeys(
-  originalKey: string,
-  provider: UserDataStorageProvider,
-): Promise<readonly string[]> {
-  let candidates: readonly string[];
-  try {
-    candidates = await provider.list(derivativeListPrefix(originalKey));
-  } catch (err) {
-    // Wrap rather than let a raw provider error (e.g. S3 AccessDenied) surface
-    // unexplained — list() is a NEW requirement this hook added on top of
-    // delete(); a bucket policy granting only s3:DeleteObject now fails forget
-    // every run instead of just leaving derivatives behind. Name the likely
-    // cause so an operator doesn't have to guess.
-    throw new Error(
-      `[user-data-rights-defaults:fileRef] provider.list() failed while looking up derivatives of key=${originalKey} — forget/erasure requires list permission on the storage bucket (e.g. s3:ListBucket), not just delete. Original error: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-  const derivativeKeys: string[] = [];
-  for (const candidate of candidates) {
-    if (!isDerivativeKeyOf(originalKey, candidate)) continue;
-    try {
-      assertSafeStorageKey(candidate);
-    } catch {
-      // ponytail: a listing hit that fails the storage-key grammar can't be
-      // a real derivative (every derivative is written via a validated
-      // write()) — skip rather than pass a malformed key to delete().
-      continue;
-    }
-    derivativeKeys.push(candidate);
-  }
-  return derivativeKeys;
-}
-
 // Delete every row's binary (original + any derivatives) via the provider.
 // Returns the keys whose delete threw — the caller fails closed on a
 // non-empty list so the sub-tx rolls back and the next forget run retries
-// (delete is idempotent → converges).
+// (delete is idempotent → converges). Derivative-listing + per-key delete
+// lives in the shared derivatives helper (also used by data-retention's
+// hardDelete cleanup) so this hook no longer carries its own copy.
 async function deleteBinaries(
   rows: readonly Record<string, unknown>[],
   provider: UserDataStorageProvider,
@@ -228,18 +186,7 @@ async function deleteBinaries(
   for (const row of rows) {
     const key = row["storageKey"]; // @cast-boundary db-row
     if (typeof key !== "string" || key.length === 0) continue;
-    const keysToDelete = [key, ...(await listDerivativeKeys(key, provider))];
-    for (const k of keysToDelete) {
-      try {
-        await provider.delete(k);
-      } catch (err) {
-        // biome-ignore lint/suspicious/noConsole: operator-visibility for binary-cleanup-failure
-        console.warn(
-          `[user-data-rights-defaults:fileRef] storage delete failed key=${k} err=${err instanceof Error ? err.message : String(err)}`,
-        );
-        failedKeys.push(k);
-      }
-    }
+    failedKeys.push(...(await deleteStoredFileAndDerivatives(key, provider, ERROR_CONTEXT)));
   }
   return failedKeys;
 }