@cosmicdrift/kumiko-bundled-features 0.308.0 → 0.309.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.308.0",
+  "version": "0.309.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>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.308.0",
-    "@cosmicdrift/kumiko-framework": "0.308.0",
-    "@cosmicdrift/kumiko-headless": "0.308.0",
-    "@cosmicdrift/kumiko-renderer": "0.308.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.308.0",
-    "@cosmicdrift/kumiko-types": "0.308.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.309.0",
+    "@cosmicdrift/kumiko-framework": "0.309.0",
+    "@cosmicdrift/kumiko-headless": "0.309.0",
+    "@cosmicdrift/kumiko-renderer": "0.309.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.309.0",
+    "@cosmicdrift/kumiko-types": "0.309.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.308.0",
-    "@cosmicdrift/kumiko-locale-es": "0.308.0",
+    "@cosmicdrift/kumiko-locale-de": "0.309.0",
+    "@cosmicdrift/kumiko-locale-es": "0.309.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/__tests__/seed-admin-guarded.integration.test.ts

@@ -179,4 +179,35 @@ describe("seedAdminGuarded (offlot#114)", () => {
     expect(await userIds()).toHaveLength(2);
     expect((await userIds()).slice().sort()).toEqual([unrelated.id, admin.id].sort());
   });
+
+  test("a KMS without a blind-index key aborts instead of seeding a blind duplicate", async () => {
+    await seedAdminGuarded(stack.db, seedOptions);
+    resetBlindIndexKeyForTests();
+
+    await expect(seedAdminGuarded(stack.db, seedOptions)).rejects.toThrow(/blind-index key/);
+    expect(await userIds()).toHaveLength(1);
+  });
+
+  test("existing-user branch reconciles emailVerified onto the canonical row", async () => {
+    const first = await seedAdminGuarded(stack.db, seedOptions);
+    await blankBlindIndex();
+
+    const second = await seedAdminGuarded(stack.db, { ...seedOptions, emailVerified: true });
+
+    expect(second.id).toBe(first.id);
+    expect(await userIds()).toEqual([first.id]);
+    const rows = await selectMany<{ id: string; emailVerified: boolean }>(stack.db, userTable);
+    expect(rows.find((r) => r.id === first.id)?.emailVerified).toBe(true);
+  });
+
+  test("without a configured KMS, seeding runs the plaintext path unguarded", async () => {
+    resetPiiSubjectKmsForTests();
+    resetBlindIndexKeyForTests();
+
+    const first = await seedAdminGuarded(stack.db, seedOptions);
+    const second = await seedAdminGuarded(stack.db, seedOptions);
+
+    expect(second.id).toBe(first.id);
+    expect(await userIds()).toEqual([first.id]);
+  });
 });

package/src/auth-email-password/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.309.0",
+    "type": "fix",
+    "title": "Boot admin seed no longer duplicates the admin when the email blind-index lookup misses (fw#3101)",
+    "detail": "runProdApp and runDevApp used to call the unguarded `seedAdmin`, whose idempotency check is a plain email fetchOne that the query layer rewrites into `(email = $plaintext OR email_bidx = $hmac)` once a blind-index key is configured. Under KMS encryption `email` holds per-row ciphertext, so only the bidx arm can ever match — and it misses whenever a row's `email_bidx` is NULL (written before the key existed, or after a subject-key erase), silently inserting a second admin account for the same email. Both boot paths now call `seedAdminGuarded`, which under KMS decrypt-scans the active users for the email and reuses the oldest matching row instead of duplicating it. `seedAdminGuarded` also now aborts with a named error if a PII KMS is configured but no blind-index key is — that combination makes the lookup blind by construction — and reconciles `emailVerified: true` onto the existing row it resolves through the decrypt-scan branch, matching the existing-row reconcile `seedUser` already does on its own idempotency hit."
+  },
   {
     "version": "0.307.0",
     "type": "improvement",

package/src/auth-email-password/seeding.ts

@@ -14,6 +14,7 @@
 
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
+  configuredBlindIndexKey,
   configuredPiiSubjectKms,
   decryptPiiFieldValues,
   type LocalKeyKmsAdapter,
@@ -28,7 +29,7 @@ import { type SeedTenantHooks, seedTenant, seedTenantMembership } from "../tenan
 // kumiko-lint-ignore cross-feature-import signup create-only guard reads the user projection by email
 import { USER_STATUS, userTable } from "../user/schema/user";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
-import { seedUser } from "../user/seeding";
+import { reconcileSeededUserEmailVerified, seedUser } from "../user/seeding";
 
 // Re-export für ergonomische Single-Import-Site in tests/seed-scripts.
 // Das Auth-Feature ist der natürliche Aufrufer für "seed admin user mit
@@ -257,8 +258,8 @@ export async function seedAdmin(
 // seedAdminGuarded is a separate, additive boot-seed guard — NOT a change
 // to seedUser/seedAdmin/provisionSignupAccount, which also run on every
 // real self-signup request and can't afford a decrypt-scan fallback there.
-// Use this only where seedAdmin already runs (dev-boot / sample-server /
-// bootstrap scripts), never as a login or signup hot path.
+// It's what runProdApp/runDevApp call for their admin boot-seed; keep it
+// off the login/signup hot path.
 
 type ActiveUserRow = {
   readonly id: string;
@@ -332,10 +333,22 @@ export async function seedAdminGuarded(
   const kms = configuredPiiSubjectKms();
   if (kms === undefined) return seedAdmin(db, options);
 
+  // Without a bidx key every row seeded here gets a NULL email_bidx, which
+  // neither seedAdmin's lookup nor the partial unique index can ever see.
+  if (configuredBlindIndexKey() === undefined) {
+    throw new Error(
+      "seedAdminGuarded: a PII KMS is configured but no blind-index key — the email lookup would be blind and the seed would insert a duplicate admin. Configure KUMIKO_BLIND_INDEX_KEY.",
+    );
+  }
+
   const existingId = await findExistingUserIdForEmail(db, kms, options.email);
   if (existingId === undefined) return seedAdmin(db, options);
 
   const by = options.by ?? TestUsers.systemAdmin;
+  if (options.emailVerified === true) {
+    const existingRow = await fetchOne(db, userTable, { id: existingId });
+    if (existingRow) await reconcileSeededUserEmailVerified(db, existingRow, by);
+  }
   for (const m of options.memberships) {
     await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
     await seedTenantMembership(db, {

package/src/data-retention/__tests__/retention-cleanup-files.integration.test.ts

@@ -0,0 +1,454 @@
+// kumiko-framework#3089 — hardDelete deletes a row's file/image/files/images
+// bytes (+ derivatives) and fileRef rows, not just the row itself.
+//
+// Verifies the negative cases where a data-loss/leak bug hides:
+//   - fresh rows + other rows' files are NEVER touched
+//   - a fileRef SHARED with another row of the same entity survives (bytes +
+//     row) even though the row that's being purged references it too
+//   - a storage-delete failure fails the row closed (row + fileRef survive,
+//     skipped "file_delete_failed") and converges on the next run
+//   - no file storage wired at all → row stays, skipped "missing_file_storage"
+//   - softDelete/anonymize entities with file fields never touch bytes
+//   - the registered cron handler forwards ctx.files, not just direct calls
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createFilesField,
+  createImageField,
+  createSystemUser,
+  createTextField,
+  defineFeature,
+  type JobContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFileContext,
+  createInMemoryFileProvider,
+  deriveKey,
+  type FileStorageProvider,
+  fileRefEntity,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { createDataRetentionFeature } from "../feature";
+import { runRetentionCleanup } from "../run-retention-cleanup";
+
+// hardDelete entity with BOTH a single (image) and a plural (files) field —
+// covers the column-value path AND the file_refs-lookup path in one entity.
+const docEntity = createEntity({
+  table: "read_c8_doc",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    cover: createImageField(),
+    attachments: createFilesField(),
+  },
+  retention: { keepFor: "30d", strategy: "hardDelete" },
+});
+
+// softDelete entity with a file field — the strategy's own path (mark
+// is_deleted) must never touch bytes; only hardDelete does.
+const softDocEntity = createEntity({
+  table: "read_c8_soft_doc",
+  softDelete: true,
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    cover: createImageField(),
+  },
+  retention: { keepFor: "30d", strategy: "softDelete" },
+});
+
+// anonymize entity with a file field — same guarantee for the anonymize path.
+const anonDocEntity = createEntity({
+  table: "read_c8_anon_doc",
+  fields: {
+    label: {
+      ...createTextField({ required: true, personal: false, reason: "test_fixture" }),
+      anonymize: () => "[ANONYMIZED]",
+    },
+    cover: createImageField(),
+  },
+  retention: { keepFor: "30d", strategy: "anonymize" },
+});
+
+const c8Feature = defineFeature("c8-retention-file-fixtures", (r) => {
+  r.entity("c8-doc", docEntity);
+  r.entity("c8-soft-doc", softDocEntity);
+  r.entity("c8-anon-doc", anonDocEntity);
+});
+
+const noopLogger: JobContext["log"] = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+  child() {
+    return noopLogger;
+  },
+};
+
+const T1 = "33333333-3333-3333-3333-333333333333";
+const T2 = "44444444-4444-4444-4444-444444444444";
+
+let stack: TestStack;
+let provider: ReturnType<typeof createInMemoryFileProvider>;
+let now: ReturnType<ReturnType<typeof getTemporal>["Now"]["instant"]>;
+let pastIso: string;
+let withinIso: string;
+let fileRefCrud: ReturnType<typeof createEventStoreExecutor>;
+
+beforeAll(async () => {
+  provider = createInMemoryFileProvider();
+  stack = await setupTestStack({
+    features: [createDataRetentionFeature(), c8Feature],
+    files: { storageProvider: provider },
+  });
+  for (const e of [docEntity, softDocEntity, anonDocEntity]) {
+    await unsafeCreateEntityTable(stack.db, e);
+  }
+  fileRefCrud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
+  now = getTemporal().Now.instant();
+  pastIso = now.subtract({ hours: 60 * 24 }).toString();
+  withinIso = now.subtract({ hours: 10 * 24 }).toString();
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function filesCtx(p: FileStorageProvider = provider) {
+  return createFileContext(() => Promise.resolve(p));
+}
+
+async function seedDoc(
+  table: string,
+  tenantId: string,
+  label: string,
+  insertedAtIso: string,
+): Promise<string> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${table} (tenant_id, label, inserted_at) VALUES ($1, $2, $3::timestamptz) RETURNING id`,
+    [tenantId, label, insertedAtIso],
+  )) as { id: string | number }[];
+  return String(rows[0]?.id);
+}
+
+async function setCover(table: string, rowId: string, fileRefId: string | null): Promise<void> {
+  await asRawClient(stack.db).unsafe(`UPDATE ${table} SET cover = $1 WHERE id = $2`, [
+    fileRefId,
+    rowId,
+  ]);
+}
+
+async function seedFileRef(args: {
+  readonly tenantId: string;
+  readonly entityName: string | null;
+  readonly entityId: string | null;
+  readonly fieldName: string | null;
+  readonly key: string;
+}): Promise<string> {
+  await provider.write(args.key, new Uint8Array([1, 2, 3]), "application/octet-stream");
+  const tdb = createTenantDb(stack.db, args.tenantId, "system");
+  const systemUser = createSystemUser(args.tenantId);
+  const id = crypto.randomUUID();
+  const res = await fileRefCrud.create(
+    {
+      id,
+      storageKey: args.key,
+      fileName: "f.bin",
+      mimeType: "application/octet-stream",
+      size: 3,
+      entityType: args.entityName,
+      entityId: args.entityId,
+      fieldName: args.fieldName,
+    },
+    systemUser,
+    tdb,
+  );
+  expect(res.isSuccess).toBe(true);
+  return id;
+}
+
+async function fileRefExists(id: string): Promise<boolean> {
+  const rows = await asRawClient(stack.db).unsafe(`SELECT id FROM file_refs WHERE id = $1`, [id]);
+  return (rows as unknown[]).length > 0;
+}
+
+async function labels(table: string, tenantId: string): Promise<string[]> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `SELECT label FROM ${table} WHERE tenant_id = $1 ORDER BY label`,
+    [tenantId],
+  )) as { label: string }[];
+  return rows.map((r) => r.label);
+}
+
+beforeEach(async () => {
+  for (const t of ["read_c8_doc", "read_c8_soft_doc", "read_c8_anon_doc"]) {
+    await asRawClient(stack.db).unsafe(`DELETE FROM ${t}`);
+  }
+  await asRawClient(stack.db).unsafe(`DELETE FROM file_refs`);
+  provider.clear();
+});
+
+describe("runRetentionCleanup :: hardDelete purges file bytes + derivatives + fileRefs", () => {
+  test("expired row: bytes + derivatives + fileRefs (single + plural field) gone; fresh + other-tenant untouched", async () => {
+    const expiredId = await seedDoc("read_c8_doc", T1, "expired", pastIso);
+    const coverKey = "t1/expired/cover/orig.jpg";
+    const coverId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-doc",
+      entityId: expiredId,
+      fieldName: "cover",
+      key: coverKey,
+    });
+    await setCover("read_c8_doc", expiredId, coverId);
+    // Derivative-suffix grammar is "<name>-<16 hex chars>" (variantSuffix),
+    // not a bare variant name — see isDerivativeKeyOf/DERIVATIVE_SUFFIX_PATTERN.
+    const thumbKey = deriveKey(coverKey, "thumb-0123456789abcdef");
+    await provider.write(thumbKey, new Uint8Array([9]), "image/jpeg");
+
+    const attKey = "t1/expired/attachments/a.pdf";
+    const attId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-doc",
+      entityId: expiredId,
+      fieldName: "attachments",
+      key: attKey,
+    });
+
+    const freshId = await seedDoc("read_c8_doc", T1, "fresh", withinIso);
+    const freshCoverKey = "t1/fresh/cover/orig.jpg";
+    const freshCoverId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-doc",
+      entityId: freshId,
+      fieldName: "cover",
+      key: freshCoverKey,
+    });
+    await setCover("read_c8_doc", freshId, freshCoverId);
+
+    const otherTenantId = await seedDoc("read_c8_doc", T2, "expired-t2", pastIso);
+    const otherTenantKey = "t2/expired/cover/orig.jpg";
+    const otherTenantCoverId = await seedFileRef({
+      tenantId: T2,
+      entityName: "c8-doc",
+      entityId: otherTenantId,
+      fieldName: "cover",
+      key: otherTenantKey,
+    });
+    await setCover("read_c8_doc", otherTenantId, otherTenantCoverId);
+
+    const result = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: T1,
+      tenantPreset: null,
+      now,
+      files: filesCtx(),
+    });
+
+    expect(result.hardDeleted).toBe(1);
+    expect(await labels("read_c8_doc", T1)).toEqual(["fresh"]);
+
+    expect(await provider.exists(coverKey)).toBe(false);
+    expect(await provider.exists(thumbKey)).toBe(false);
+    expect(await provider.exists(attKey)).toBe(false);
+    expect(await fileRefExists(coverId)).toBe(false);
+    expect(await fileRefExists(attId)).toBe(false);
+
+    expect(await provider.exists(freshCoverKey)).toBe(true);
+    expect(await fileRefExists(freshCoverId)).toBe(true);
+
+    expect(await provider.exists(otherTenantKey)).toBe(true);
+    expect(await fileRefExists(otherTenantCoverId)).toBe(true);
+    expect(await labels("read_c8_doc", T2)).toEqual(["expired-t2"]);
+  });
+
+  test("shared fileRef (same entity, second row) survives even though its owning row is purged", async () => {
+    const rowA = await seedDoc("read_c8_doc", T1, "expired-shared", pastIso);
+    const rowB = await seedDoc("read_c8_doc", T1, "fresh-shared", withinIso);
+    const sharedKey = "t1/shared/cover/orig.jpg";
+    const sharedId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-doc",
+      entityId: rowA,
+      fieldName: "cover",
+      key: sharedKey,
+    });
+    await setCover("read_c8_doc", rowA, sharedId);
+    await setCover("read_c8_doc", rowB, sharedId);
+
+    const result = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: T1,
+      tenantPreset: null,
+      now,
+      files: filesCtx(),
+    });
+
+    expect(result.hardDeleted).toBe(1);
+    expect(await labels("read_c8_doc", T1)).toEqual(["fresh-shared"]);
+    expect(await provider.exists(sharedKey)).toBe(true);
+    expect(await fileRefExists(sharedId)).toBe(true);
+  });
+
+  test("storage-delete failure fails the row closed; skipped + convergence on retry", async () => {
+    const rowId = await seedDoc("read_c8_doc", T1, "expired-fails", pastIso);
+    const key = "t1/fails/cover/orig.jpg";
+    const fileRefId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-doc",
+      entityId: rowId,
+      fieldName: "cover",
+      key,
+    });
+    await setCover("read_c8_doc", rowId, fileRefId);
+
+    const failingProvider: FileStorageProvider = {
+      ...provider,
+      delete: async (k: string) => {
+        if (k === key) throw new Error("boom");
+        return provider.delete(k);
+      },
+    };
+
+    const failed = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: T1,
+      tenantPreset: null,
+      now,
+      files: filesCtx(failingProvider),
+    });
+
+    expect(failed.hardDeleted).toBe(0);
+    expect(failed.skipped).toContainEqual({ entityName: "c8-doc", reason: "file_delete_failed" });
+    expect(await labels("read_c8_doc", T1)).toEqual(["expired-fails"]);
+    expect(await fileRefExists(fileRefId)).toBe(true);
+    expect(await provider.exists(key)).toBe(true);
+
+    const retried = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: T1,
+      tenantPreset: null,
+      now,
+      files: filesCtx(),
+    });
+    expect(retried.hardDeleted).toBe(1);
+    expect(await labels("read_c8_doc", T1)).toEqual([]);
+    expect(await fileRefExists(fileRefId)).toBe(false);
+    expect(await provider.exists(key)).toBe(false);
+  });
+
+  test("no file storage wired → row stays, skipped missing_file_storage", async () => {
+    const rowId = await seedDoc("read_c8_doc", T1, "expired-no-storage", pastIso);
+    const key = "t1/no-storage/cover/orig.jpg";
+    const fileRefId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-doc",
+      entityId: rowId,
+      fieldName: "cover",
+      key,
+    });
+    await setCover("read_c8_doc", rowId, fileRefId);
+
+    const result = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: T1,
+      tenantPreset: null,
+      now,
+    });
+
+    expect(result.hardDeleted).toBe(0);
+    expect(result.skipped).toContainEqual({
+      entityName: "c8-doc",
+      reason: "missing_file_storage",
+    });
+    expect(await labels("read_c8_doc", T1)).toEqual(["expired-no-storage"]);
+    expect(await fileRefExists(fileRefId)).toBe(true);
+  });
+
+  test("softDelete and anonymize entities with a file field never touch bytes", async () => {
+    const softRowId = await seedDoc("read_c8_soft_doc", T1, "soft-expired", pastIso);
+    const softKey = "t1/soft/cover/orig.jpg";
+    const softFileRefId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-soft-doc",
+      entityId: softRowId,
+      fieldName: "cover",
+      key: softKey,
+    });
+    await setCover("read_c8_soft_doc", softRowId, softFileRefId);
+
+    const anonRowId = await seedDoc("read_c8_anon_doc", T1, "anon-expired", pastIso);
+    const anonKey = "t1/anon/cover/orig.jpg";
+    const anonFileRefId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-anon-doc",
+      entityId: anonRowId,
+      fieldName: "cover",
+      key: anonKey,
+    });
+    await setCover("read_c8_anon_doc", anonRowId, anonFileRefId);
+
+    const result = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: T1,
+      tenantPreset: null,
+      now,
+      files: filesCtx(),
+    });
+
+    expect(result.softDeleted).toBe(1);
+    expect(result.anonymized).toBe(1);
+    expect(await provider.exists(softKey)).toBe(true);
+    expect(await fileRefExists(softFileRefId)).toBe(true);
+    expect(await provider.exists(anonKey)).toBe(true);
+    expect(await fileRefExists(anonFileRefId)).toBe(true);
+  });
+
+  test("the registered job handler forwards ctx.files — bytes gone after the cron runs", async () => {
+    const rowId = await seedDoc("read_c8_doc", T1, "expired-via-job", pastIso);
+    const key = "t1/via-job/cover/orig.jpg";
+    const fileRefId = await seedFileRef({
+      tenantId: T1,
+      entityName: "c8-doc",
+      entityId: rowId,
+      fieldName: "cover",
+      key,
+    });
+    await setCover("read_c8_doc", rowId, fileRefId);
+
+    const job = stack.registry.getJob("data-retention:job:retention-cleanup");
+    expect(job).toBeDefined();
+    if (!job) return;
+
+    const ctx: JobContext = {
+      db: createTenantDb(stack.db, T1, "tenant", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "per-tenant fan-out cleanup using raw helpers" },
+      }),
+      registry: stack.registry,
+      systemUser: { id: "system", tenantId: T1, roles: ["all"] },
+      log: noopLogger,
+      triggeredBy: null,
+      files: filesCtx(),
+      ...bridgeStub(),
+    };
+    await job.handler({}, ctx);
+
+    expect(await labels("read_c8_doc", T1)).toEqual([]);
+    expect(await fileRefExists(fileRefId)).toBe(false);
+    expect(await provider.exists(key)).toBe(false);
+  });
+});

package/src/data-retention/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.309.0",
+    "type": "breaking",
+    "title": "data-retention hardDelete now purges file bytes + fileRef rows, not just the entity row (fw#3089)",
+    "migration": "hardDelete previously deleted only the entity row and left every file/image/files/images field's storage bytes and `file_refs` row behind — a DSGVO Art. 17 gap. As of this release, an expired row's un-shared fileRefs (same tenant, bound to this row, not referenced by another row of the same entity) have their storage bytes deleted (including derivatives/thumbnails), then their `file_refs` row, then the entity row itself. A fileRef still referenced by another row, or bound to a different entity/record, is left untouched. Without a resolvable file-storage provider in the retention cron's job context, an entity with pending file deletions is skipped entirely (`skipped` reason `missing_file_storage`) rather than silently dropping the row with orphaned bytes; a storage-delete failure skips the row too (`file_delete_failed`) and retries on the next run. Before upgrading, a consumer relying on hardDelete NOT touching file storage should: list entities with `retention.strategy: \"hardDelete\"` and at least one file/image/files/images field, count rows already past `keepFor` for each, and confirm the referenced files are safe to delete (not needed elsewhere) before the next cron run."
+  },
   {
     "version": "0.167.1",
     "type": "fix",

package/src/data-retention/feature.ts

@@ -109,6 +109,7 @@ export function createDataRetentionFeature(): FeatureDefinition {
           tenantId,
           tenantPreset,
           now: T.Now.instant(),
+          files: ctx.files,
         });
         if (result.skipped.length > 0) {
           // biome-ignore lint/suspicious/noConsole: operator-visibility for skipped entities

package/src/data-retention/run-retention-cleanup.ts

@@ -6,7 +6,11 @@
 // Strategy auf Rows an deren reference-Timestamp aelter als der keepFor-Cutoff
 // ist:
 //
-//   - hardDelete  → executor.forget pro Row (Event → rebuild-safe hard purge)
+//   - hardDelete  → executor.forget pro Row (Event → rebuild-safe hard purge).
+//                   Entities with file/image/files/images fields: bytes first
+//                   (incl. derivatives), then the fileRef row(s), then the row;
+//                   shared fileRefs (other owner, other row of the same table)
+//                   stay untouched.
 //   - softDelete  → executor.delete pro Row (Event → rebuild-safe soft-delete),
 //                   nur auf noch-nicht-geloeschte (isDeleted:false-Filter)
 //   - anonymize   → executor.update pro Row mit den Werten der per-Feld
@@ -39,14 +43,22 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbRunner,
+  type TenantDb,
   type WhereObject,
 } from "@cosmicdrift/kumiko-framework/db";
+import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   createSystemUser,
   type EntityId,
   type Registry,
+  type SessionUser,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type FileContext,
+  fileRefEntity,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
 import { computeCutoff, type Instant } from "./keep-for";
 import type { RetentionPresetKey } from "./presets";
 import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant";
@@ -76,6 +88,10 @@ export interface RunRetentionCleanupArgs {
   /** Now-Injection — Tests pinnen den Wert ohne Date-Mock (Pattern keep-for.ts). */
   readonly now: Instant;
   readonly batchLimit?: number;
+  /** Storage access for hardDelete entities with file/image/files/images fields.
+   *  Missing while fileRefs are due → the row stays (skipped "missing_file_storage"),
+   *  fail-closed instead of orphaning bytes. */
+  readonly files?: FileContext;
 }
 
 export interface RetentionCleanupSkip {
@@ -83,7 +99,9 @@ export interface RetentionCleanupSkip {
   readonly reason:
     | "missing_reference_column"
     | "missing_softdelete_columns"
-    | "missing_anonymize_fields";
+    | "missing_anonymize_fields"
+    | "missing_file_storage"
+    | "file_delete_failed";
 }
 
 export interface RunRetentionCleanupResult {
@@ -113,6 +131,272 @@ async function purgeMatchingRows(
   return count;
 }
 
+// --- hardDelete + file-fields (kumiko-framework#3089) ---
+
+type FileFieldPlan = {
+  /** type file|image — stores the fileRef-id directly in the entity column. */
+  readonly singleFields: readonly string[];
+  /** type files|images — no entity column, resolved via file_refs. */
+  readonly multiFields: readonly string[];
+};
+
+const NO_FILE_FIELDS: FileFieldPlan = { singleFields: [], multiFields: [] };
+
+// file/image = single-column fields (fileRef-id lives directly in the entity
+// row); files/images = plural, no column, resolved via file_refs. Same set
+// as boot-validator/entity-handler.ts FILE_FIELD_TYPES and engine's
+// isFileField — inlined here rather than importing across the package
+// barrel since this module already needs the single/multi split, not just
+// membership.
+function planFileFields(fields: Readonly<Record<string, unknown>>): FileFieldPlan {
+  const singleFields: string[] = [];
+  const multiFields: string[] = [];
+  for (const [name, field] of Object.entries(fields)) {
+    const type = (field as { readonly type?: unknown }).type; // @cast-boundary schema-walk
+    if (type === "file" || type === "image") singleFields.push(name);
+    else if (type === "files" || type === "images") multiFields.push(name);
+  }
+  return singleFields.length > 0 || multiFields.length > 0
+    ? { singleFields, multiFields }
+    : NO_FILE_FIELDS;
+}
+
+// Every fileRef-id a row's file/image/files/images-fields reference: single
+// fields hold the id in their own column, plural fields have no column and
+// resolve via file_refs (tenantId, entityType, entityId, fieldName).
+async function collectFileRefIds(
+  db: DbRunner,
+  tenantId: TenantId,
+  entityName: string,
+  row: Record<string, unknown>,
+  plan: FileFieldPlan,
+): Promise<readonly string[]> {
+  const ids = new Set<string>();
+  for (const field of plan.singleFields) {
+    const value = row[field];
+    if (typeof value === "string" && value.length > 0) ids.add(value);
+  }
+  if (plan.multiFields.length > 0) {
+    const refRows = await selectMany<{ id: string }>(db, fileRefsTable, {
+      tenantId,
+      entityType: entityName,
+      entityId: String(row["id"]),
+      fieldName: { in: plan.multiFields },
+    });
+    for (const r of refRows) ids.add(r.id);
+  }
+  return Array.from(ids);
+}
+
+// A fileRef is bound to a DIFFERENT entity/record than the row currently
+// being purged — its binding (entityType/entityId), not the row's own
+// single-field column, decides ownership. A single-field value can point at
+// a fileRef uploaded/attached elsewhere; that fileRef's bytes belong to
+// whatever it's actually bound to, not to this row.
+function isFileRefBoundElsewhere(
+  fileRef: Record<string, unknown>,
+  entityName: string,
+  rowId: string,
+): boolean {
+  const entityType = fileRef["entityType"];
+  const entityId = fileRef["entityId"];
+  if (typeof entityType === "string" && entityType !== entityName) return true;
+  if (typeof entityId === "string" && entityId !== rowId) return true;
+  return false;
+}
+
+// A single-field fileRef-id can be shared by more than one row of the SAME
+// table (e.g. a stock-photo re-picked across records). Purging its bytes
+// would corrupt the row that isn't being deleted. Bounded by batchLimit rows
+// per run and singleFields.length queries per fileRef — the same per-row
+// event-cost tradeoff as the rest of this cron (see header).
+async function isFileRefSharedByOtherRow(
+  db: DbRunner,
+  table: Parameters<typeof selectMany>[1],
+  tableHasTenantId: boolean,
+  tenantId: TenantId,
+  rowId: string,
+  singleFields: readonly string[],
+  fileRefId: string,
+): Promise<boolean> {
+  for (const field of singleFields) {
+    const where: WhereObject = { [field]: fileRefId, id: { ne: rowId } };
+    if (tableHasTenantId) where["tenantId"] = tenantId;
+    const others = await selectMany(db, table, where, { limit: 1 });
+    if (others.length > 0) return true;
+  }
+  return false;
+}
+
+// hardDelete for ONE row of an entity that has file/image/files/images
+// fields: delete the un-shared fileRefs' bytes (+ derivatives) first, then
+// their fileRef rows, then the entity row itself — bytes before rows so a
+// crash mid-way leaves an orphaned fileRef pointing at already-gone bytes
+// (safe: a later run's provider.delete is idempotent) rather than a gone
+// fileRef whose bytes leak forever.
+async function purgeHardDeleteRowWithFiles(args: {
+  readonly db: DbRunner;
+  readonly table: Parameters<typeof selectMany>[1];
+  readonly tableHasTenantId: boolean;
+  readonly tenantId: TenantId;
+  readonly entityName: string;
+  readonly row: Record<string, unknown>;
+  readonly plan: FileFieldPlan;
+  readonly files: FileContext | undefined;
+  readonly entityExecutor: ReturnType<typeof createEventStoreExecutor>;
+  readonly fileRefExecutor: ReturnType<typeof createEventStoreExecutor>;
+  readonly systemUser: SessionUser;
+  readonly tdb: TenantDb;
+  readonly onSkip: (reason: "missing_file_storage" | "file_delete_failed") => void;
+}): Promise<boolean> {
+  const rowId = String(args.row["id"]);
+  const fileRefIds = await collectFileRefIds(
+    args.db,
+    args.tenantId,
+    args.entityName,
+    args.row,
+    args.plan,
+  );
+  if (fileRefIds.length === 0) {
+    return (
+      await args.entityExecutor.forget(
+        { id: args.row["id"] as EntityId },
+        args.systemUser,
+        args.tdb,
+      )
+    ).isSuccess;
+  }
+
+  const fileRefRows = await selectMany<Record<string, unknown>>(args.db, fileRefsTable, {
+    id: { in: fileRefIds },
+    tenantId: args.tenantId,
+  });
+
+  const toDelete: Record<string, unknown>[] = [];
+  for (const fileRef of fileRefRows) {
+    if (isFileRefBoundElsewhere(fileRef, args.entityName, rowId)) continue;
+    const shared = await isFileRefSharedByOtherRow(
+      args.db,
+      args.table,
+      args.tableHasTenantId,
+      args.tenantId,
+      rowId,
+      args.plan.singleFields,
+      String(fileRef["id"]),
+    );
+    if (shared) continue;
+    toDelete.push(fileRef);
+  }
+
+  if (toDelete.length === 0) {
+    return (
+      await args.entityExecutor.forget(
+        { id: args.row["id"] as EntityId },
+        args.systemUser,
+        args.tdb,
+      )
+    ).isSuccess;
+  }
+
+  if (!args.files) {
+    args.onSkip("missing_file_storage");
+    return false;
+  }
+  const files = args.files;
+  const store = { list: files.list, delete: (key: string) => files.ref(key).delete() };
+
+  let anyFailed = false;
+  for (const fileRef of toDelete) {
+    const key = fileRef["storageKey"];
+    if (typeof key !== "string" || key.length === 0) continue;
+    const failedKeys = await deleteStoredFileAndDerivatives(
+      key,
+      store,
+      "data-retention:hardDelete",
+    );
+    if (failedKeys.length > 0) {
+      anyFailed = true;
+      // biome-ignore lint/suspicious/noConsole: operator-visibility for storage-cleanup failures
+      console.warn(
+        `[data-retention:hardDelete] tenant=${args.tenantId} entity=${args.entityName} row=${rowId} storage delete failed keys=${failedKeys.join(",")}`,
+      );
+    }
+  }
+  if (anyFailed) {
+    args.onSkip("file_delete_failed");
+    return false;
+  }
+
+  for (const fileRef of toDelete) {
+    const res = await args.fileRefExecutor.forget(
+      { id: fileRef["id"] as EntityId },
+      args.systemUser,
+      args.tdb,
+    );
+    if (!res.isSuccess) {
+      args.onSkip("file_delete_failed");
+      return false;
+    }
+  }
+
+  return (
+    await args.entityExecutor.forget({ id: args.row["id"] as EntityId }, args.systemUser, args.tdb)
+  ).isSuccess;
+}
+
+// hardDelete page for an entity WITH file/image/files/images fields — loads
+// full rows (not just id) so file-field values are available, and reports
+// each skip reason at most once per entity per run (repeat skips would just
+// be noise; the per-row failure is already warned above).
+async function purgeHardDeleteRowsWithFiles(args: {
+  readonly db: DbRunner;
+  readonly table: Parameters<typeof selectMany>[1];
+  readonly tableHasTenantId: boolean;
+  readonly where: WhereObject;
+  readonly batchLimit: number;
+  readonly tenantId: TenantId;
+  readonly entityName: string;
+  readonly plan: FileFieldPlan;
+  readonly files: FileContext | undefined;
+  readonly entityExecutor: ReturnType<typeof createEventStoreExecutor>;
+  readonly fileRefExecutor: ReturnType<typeof createEventStoreExecutor>;
+  readonly systemUser: SessionUser;
+  readonly tdb: TenantDb;
+  readonly skipped: RetentionCleanupSkip[];
+}): Promise<number> {
+  const rows = await selectMany<Record<string, unknown>>(args.db, args.table, args.where, {
+    limit: args.batchLimit,
+  });
+  const reasonsSeen = new Set<RetentionCleanupSkip["reason"]>();
+  const onSkip = (reason: "missing_file_storage" | "file_delete_failed") => {
+    // skip: reason already reported for this entity in this run
+    if (reasonsSeen.has(reason)) return;
+    reasonsSeen.add(reason);
+    args.skipped.push({ entityName: args.entityName, reason });
+  };
+
+  let count = 0;
+  for (const row of rows) {
+    const ok = await purgeHardDeleteRowWithFiles({
+      db: args.db,
+      table: args.table,
+      tableHasTenantId: args.tableHasTenantId,
+      tenantId: args.tenantId,
+      entityName: args.entityName,
+      row,
+      plan: args.plan,
+      files: args.files,
+      entityExecutor: args.entityExecutor,
+      fileRefExecutor: args.fileRefExecutor,
+      systemUser: args.systemUser,
+      tdb: args.tdb,
+      onSkip,
+    });
+    if (ok) count++;
+  }
+  return count;
+}
+
 // PiiAnnotations.anonymize — structural view, avoids reaching into the
 // engine's field-type internals from here.
 type AnonymizeCapableField = { readonly anonymize?: () => unknown | Promise<unknown> };
@@ -244,9 +528,32 @@ export async function runRetentionCleanup(
     switch (policy.strategy) {
       case "hardDelete": {
         const executor = createEventStoreExecutor(proj.table, entity, { entityName });
-        hardDeleted += await purgeMatchingRows(db, proj.table, where, batchLimit, (id) =>
-          executor.forget({ id }, systemUser, tdb),
-        );
+        const filePlan = planFileFields(entity.fields);
+        if (filePlan.singleFields.length === 0 && filePlan.multiFields.length === 0) {
+          hardDeleted += await purgeMatchingRows(db, proj.table, where, batchLimit, (id) =>
+            executor.forget({ id }, systemUser, tdb),
+          );
+          break;
+        }
+        const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+          entityName: "fileRef",
+        });
+        hardDeleted += await purgeHardDeleteRowsWithFiles({
+          db,
+          table: proj.table,
+          tableHasTenantId: table["tenantId"] !== undefined,
+          where,
+          batchLimit,
+          tenantId,
+          entityName,
+          plan: filePlan,
+          files: args.files,
+          entityExecutor: executor,
+          fileRefExecutor,
+          systemUser,
+          tdb,
+          skipped,
+        });
         break;
       }
       case "softDelete": {

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;
 }