@cosmicdrift/kumiko-bundled-features 0.286.0 → 0.288.0

package/src/user-data-rights/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "export-cleanup cron now emits an export_cleanup_backlog_age gauge to surface stalled runs",
+    "detail": "storageCleanupPass deletes expired export bundles via provider.delete, but the storage provider only exposes list() (no timestamps), so a silent failure left unencrypted PII bundles sitting in the bucket with no signal. runExportJobs now accepts an optional MetricsHandle and, after the cleanup loop, reports the age in seconds of the oldest done-status job whose expiresAt+grace has passed while downloadStorageKey is still set (0 if none) via the new EXPORT_CLEANUP_BACKLOG_AGE_METRIC (\"export_cleanup_backlog_age\", a gauge — no _total/_seconds suffix per validateMetricName, unit: \"seconds\" carried in the r.metric() definition instead). feature.ts's job handler builds the handle itself with createMetricsHandle(ctx.meter, \"user-data-rights\") since JobContext has no bound ctx.metrics (that only exists on HandlerContext, built per write/query dispatch) — falls back to createNoopMetricsHandle() when ctx.meter is unset. Metric emission is wrapped in try/catch so an observability hiccup never fails an otherwise-successful cleanup pass. Scope is deliberately done-status only; failed-status cleanup candidates have no expiresAt/TTL."
+  },
+  {
+    "version": "0.287.0",
+    "type": "fix",
+    "title": "GDPR forget only hard-deletes files that are PII of the forgotten person",
+    "detail": "fileRefDeleteHook picked rows via insertedById (who uploaded the file) and treated every matched row the same on strategy=\"delete\", so forgetting an uploader hard-deleted third-party business files they had merely uploaded (e.g. a dealer's vehicle photos uploaded by an employee). FileFieldDef/ImageFieldDef/FilesFieldDef/ImagesFieldDef now support \"& ResolvedPiiFlags\" like every other field type (createFileField/createImageField/createFilesField/createImagesField thread personal/reason through expandPersonalAnnotations), and fileRefDeleteHook's strategy=\"delete\" branch splits rows per-row via the new isPersonalFileRow/isPersonalPiiField predicates: pii/userOwned/recordOwned fields take the existing hard-delete path (storageProvider.delete() + derivatives + row), every other row (explicit personal:false, tenantOwned, subjectRef, no annotation, or an unresolvable entity/field) goes through severPersonLink instead, same as the existing strategy=\"anonymize\" path. Unattached uploads (no entityType/fieldName) still hard-delete. Derivatives have no own file_refs row, so they keep following their original's decision (the #2461 \"GDPR derivatives survive forget\" test stays green). POST /files now resolves entityType/fieldName against the registry and rejects the upload with 400 when they're set but don't resolve to a real field, closing the gap that let a client attach a file to a field the forget-hook could never look up; both unset (unattached upload) still passes. No new column or migration — the decision uses the entityType/fieldName file_refs already stores."
+  },
   {
     "version": "0.285.2",
     "type": "fix",

package/src/user-data-rights/deletion-token.ts

@@ -1,62 +1,56 @@
-// Thin wrapper around the shared HMAC-signed-token primitive, pinning the
-// purpose to "deletion-request". Mirrors auth-email-password/reset-token.ts —
-// email-verified account deletion is an auth-adjacent proof-of-email-ownership
-// flow, so it reuses the same self-contained token mechanism (no DB row, no
-// Redis: the userId + expiry are baked into the signed token).
+// Email-verified account deletion, expressed as a row-bound grant: the
+// subject is the user, the anchor is the pending request id stored on the
+// user row. Minting and verification both run through
+// shared/row-bound-grant, so a token from a cancelled cycle (id nulled) or a
+// superseded one (row holds a newer id) fails verification — see #354/1.
 //
-// Replay-after-cancel (#354/1): the per-request `requestId` is folded INTO the
-// HMAC purpose (`deletion-request:<requestId>`), not carried in the token body.
-// The same id is stored on the user row when the request is minted and nulled
-// on cancel. confirm recomputes the HMAC with the row's CURRENT id, so a token
-// from a cancelled cycle (row id nulled) or a superseded one (row holds a newer
-// id) fails verification — the bounded-TTL replay window is closed without
-// touching the shared signToken/verifyToken primitive.
+// The purpose string and the anchoring are unchanged from the hand-rolled
+// version this replaced, so tokens stay byte-compatible.
 
 import type { Temporal } from "temporal-polyfill";
-import { signToken, verifyToken } from "../auth-email-password";
+import { type RowBoundGrantResult, redeemRowBoundGrant, signRowBoundGrant } from "../shared";
 
 const DELETION_REQUEST_PURPOSE = "deletion-request";
 
-export type VerifyResult =
-  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
-  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
-
-function deletionPurpose(requestId: string): string {
-  return `${DELETION_REQUEST_PURPOSE}:${requestId}`;
-}
-
 export function signDeletionToken(
   userId: string,
   requestId: string,
   ttlMinutes: number,
   secret: string,
   now?: Temporal.Instant,
-): { token: string; expiresAt: Temporal.Instant } {
-  return signToken(userId, deletionPurpose(requestId), ttlMinutes, secret, now);
+): { readonly token: string; readonly expiresAt: Temporal.Instant } {
+  return signRowBoundGrant({
+    subject: userId,
+    purpose: DELETION_REQUEST_PURPOSE,
+    anchor: requestId,
+    ttlMinutes,
+    secret,
+    now,
+  });
 }
 
-export function verifyDeletionToken(
-  token: string,
-  requestId: string,
-  secret: string,
-  now?: Temporal.Instant,
-): VerifyResult {
-  return verifyToken(token, deletionPurpose(requestId), secret, now);
-}
-
-// Reads the userId from the token body WITHOUT verifying the HMAC — used only
-// to look up the row's current requestId, which is itself an input to the
-// verification below. The signature is still the gate; this peek never grants
-// trust. Token format is `<userId>.<expiresAtMs>.<sig>`.
-//
-// Mirrors verifyToken's structural malformed-checks so an obviously-bogus token
-// returns null here (→ generic reject) instead of reaching the DB lookup.
-export function peekDeletionTokenUserId(token: string): string | null {
-  const parts = token.split(".");
-  if (parts.length !== 3) return null;
-  const [userId, expiresAtRaw, sig] = parts;
-  if (!userId || !expiresAtRaw || !sig) return null;
-  const expiresAtMs = Number(expiresAtRaw);
-  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) return null;
-  return userId;
+export function redeemDeletionToken(args: {
+  readonly token: string;
+  readonly secret: string | undefined;
+  readonly loadPendingRequestId: (userId: string) => Promise<string | null>;
+  readonly now?: Temporal.Instant;
+}): Promise<RowBoundGrantResult> {
+  return redeemRowBoundGrant({
+    token: args.token,
+    purpose: DELETION_REQUEST_PURPOSE,
+    secret: args.secret,
+    loadAnchor: args.loadPendingRequestId,
+    commitAnchor: {
+      unsafeSkip: {
+        reason:
+          "pendingDeletionRequestId may only be changed through updateUserLifecycle — a " +
+          "conditional UPDATE would bypass the user.updated event and lose the field on a " +
+          "projection rebuild (see update-user-lifecycle.ts). The concurrent-redeem window " +
+          "this leaves open predates row-bound grants: startDeletionGracePeriod already " +
+          "read-then-writes the Active check. Closing it needs an atomic lifecycle " +
+          "transition, which is its own change.",
+      },
+    },
+    now: args.now,
+  });
 }

package/src/user-data-rights/feature.ts

@@ -7,6 +7,10 @@ import {
   i18nKey,
   SYSTEM_USER_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createMetricsHandle,
+  createNoopMetricsHandle,
+} from "@cosmicdrift/kumiko-framework/observability";
 import { validateGdprHookCompleteness, validateGdprPiiHookCoverage } from "./boot-checks";
 import {
   EXPORT_SECTION_EXTENSION_NAME,
@@ -49,6 +53,7 @@ import { makeTenantMailTransportResolver } from "./lib/mail-transport-resolver";
 import { resolveAppTenantModel } from "./lib/resolve-tenant-model";
 import { makeTenantStorageProviderResolver } from "./lib/storage-provider-resolver";
 import {
+  EXPORT_CLEANUP_BACKLOG_AGE_METRIC,
   runExportJobs,
   type SendExportFailedEmailFn,
   type SendExportReadyEmailFn,
@@ -528,6 +533,21 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       },
     });
 
+    // Surfaces a stalled export-cleanup cron: if the daily
+    // pass stops running, done-status export bundles keep sitting in
+    // storage past their TTL+grace with downloadStorageKey still set
+    // (unencrypted PII at rest). Emitted from the same job that cleans up
+    // (see handler below) — a dead cron makes the metric go stale too,
+    // which an `absent()` alert catches without a second liveness signal.
+    // Scope: Done-status bundles only — Failed-status cleanup candidates
+    // have no expiresAt/TTL (immediate cleanup, see storageCleanupPass).
+    r.metric(EXPORT_CLEANUP_BACKLOG_AGE_METRIC, {
+      type: "gauge",
+      unit: "seconds",
+      description:
+        "Age in seconds of the oldest done-status export bundle whose expiresAt+grace has passed but downloadStorageKey is still set. 0 when the storage-cleanup pass has no backlog.",
+    });
+
     // S2.U3 Atom 3b — Worker fuer Async Export-Pipeline. Cron-getriggert.
     const RUN_EXPORT_JOBS_REASON = "processes pending export jobs across every tenant";
     r.job({
@@ -548,6 +568,12 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           RUN_EXPORT_JOBS_REASON,
         ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const exportRegistry = ctx.registry;
+        // JobContext carries ctx.meter (raw), not ctx.metrics — that bound
+        // handle only exists on HandlerContext (built per write/query call
+        // in dispatch-shared.ts). Build the same handle explicitly here.
+        const exportMetrics = ctx.meter
+          ? createMetricsHandle(ctx.meter, "user-data-rights")
+          : createNoopMetricsHandle();
 
         // C6 — ohne eigene send*Email-Opts aber mit gemountetem mail-transport
         // versendet der Cron die Export-Notifications selbst (Default-Templates).
@@ -612,6 +638,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           }),
           escapeHatchAuditSink: ctx._escapeHatchAuditSink,
           actor: ctx.systemUser.id,
+          metrics: exportMetrics,
         });
       },
     });

package/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -7,7 +7,7 @@ import {
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
-import { peekDeletionTokenUserId, verifyDeletionToken } from "../deletion-token";
+import { redeemDeletionToken } from "../deletion-token";
 import { startDeletionGracePeriod } from "./deletion-grace-period";
 
 export type ConfirmDeletionByTokenOptions = {
@@ -66,24 +66,14 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
     agent: { expose: false },
     rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {
-      if (!opts.deletionTokenSecret) return writeFailure(invalidToken());
-
-      const peekedUserId = peekDeletionTokenUserId(event.payload.token);
-      if (!peekedUserId) return writeFailure(invalidToken());
-
-      // Die requestId der Row ist Teil des Verify-Keys (HMAC-Purpose). Kein
-      // offener Antrag (null) → das Token gehört zu einem abgebrochenen Zyklus
-      // → Reject ohne weitere Signal-Preisgabe (gleicher generischer 422). Der
-      // peekedUserId ist unverifizierte Angreifer-Eingabe — ein Lookup-Fehler
-      // (z.B. typfremde id) wird zu demselben generischen 422, nie zu einem 500.
-      const requestId = await readPendingDeletionRequestId(ctx, peekedUserId);
-      if (!requestId) return writeFailure(invalidToken());
-
-      const verified = verifyDeletionToken(
-        event.payload.token,
-        requestId,
-        opts.deletionTokenSecret,
-      );
+      // The row's requestId is part of the verify key, so a token from a
+      // cancelled or superseded cycle fails. Every error path ends in the same
+      // generic 422.
+      const verified = await redeemDeletionToken({
+        token: event.payload.token,
+        secret: opts.deletionTokenSecret,
+        loadPendingRequestId: (userId) => readPendingDeletionRequestId(ctx, userId),
+      });
       if (!verified.ok) return writeFailure(invalidToken());
 
       // @cast-boundary engine-payload — queryAs returns unknown, narrowed to
@@ -95,7 +85,7 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
       )) as { profile: { userRights: { gracePeriod: DurationSpec } } };
       const res = await startDeletionGracePeriod(
         ctx,
-        verified.userId,
+        verified.subject,
         profile.profile.userRights.gracePeriod,
         ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
       );

package/src/user-data-rights/run-export-jobs.ts

@@ -61,6 +61,7 @@ import {
   tenantExportPrefix,
   type ZipEntry,
 } from "@cosmicdrift/kumiko-framework/files";
+import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { resolveProfileForTenant } from "../compliance-profiles";
 import { decryptStoredPii } from "../shared";
@@ -73,6 +74,12 @@ import { generateDownloadToken } from "./token-helpers";
 
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
+// Gauge short name (feature.ts registers it via r.metric + resolves ctx.meter
+// into a MetricsHandle — jobs get no bound ctx.metrics, see feature.ts).
+// No "_seconds"/"_total" suffix: validateMetricName rejects both on a gauge.
+// Unit lives in the r.metric() `unit: "seconds"` declaration instead.
+export const EXPORT_CLEANUP_BACKLOG_AGE_METRIC = "export_cleanup_backlog_age";
+
 const crud = createEventStoreExecutor(exportJobsTable, exportJobEntity, {
   entityName: "export-job",
 });
@@ -165,6 +172,12 @@ export interface RunExportJobsArgs {
   // systemUser.id); threaded into runUserExport's per-hook TenantDb.
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
+
+  /**
+   * Reports EXPORT_CLEANUP_BACKLOG_AGE_METRIC after the storage-cleanup
+   * pass. Optional so callers without an observability provider still work.
+   */
+  readonly metrics?: MetricsHandle;
 }
 
 export interface ExportJobError {
@@ -302,6 +315,7 @@ export async function runExportJobs(args: RunExportJobsArgs): Promise<RunExportJ
     db,
     buildStorageProvider,
     now,
+    metrics: args.metrics,
   });
 
   return {
@@ -621,8 +635,9 @@ async function storageCleanupPass(args: {
   db: DbConnection;
   buildStorageProvider: (tenantId: TenantId) => Promise<FileStorageProvider>;
   now: Instant;
+  metrics?: MetricsHandle;
 }): Promise<readonly string[]> {
-  const { db, buildStorageProvider, now } = args;
+  const { db, buildStorageProvider, now, metrics } = args;
 
   // Zwei Cleanup-Pfade:
   //
@@ -659,6 +674,13 @@ async function storageCleanupPass(args: {
   );
 
   const cleaned: string[] = [];
+  // Done-status candidates past expiresAt+grace, keyed by that due-instant —
+  // used below to report how far cleanup has fallen behind if a candidate
+  // is still standing (delete threw, or the version-checked null-out lost
+  // a race) once the pass is done. Failed-status jobs have no expiresAt
+  // (immediate cleanup, no TTL) so they're out of scope for this signal —
+  // see EXPORT_CLEANUP_BACKLOG_AGE_METRIC's r.metric() description.
+  const overdueDoneCleanupAfterMs = new Map<string, number>();
   for (const c of candidates) {
     if (!c.downloadStorageKey) continue;
 
@@ -674,6 +696,7 @@ async function storageCleanupPass(args: {
         c.expiresAt.epochMilliseconds +
         profile.profile.userRights.exportStorageCleanupGraceHours * 60 * 60 * 1000;
       if (now.epochMilliseconds < cleanupAfter) continue;
+      overdueDoneCleanupAfterMs.set(c.id, cleanupAfter);
     }
     // Failed-Job-Branch: kein TTL-Check, sofort cleanup.
 
@@ -696,9 +719,54 @@ async function storageCleanupPass(args: {
     );
     if (result.isSuccess) cleaned.push(c.id);
   }
+
+  reportOldestOverdueAge(metrics, overdueDoneCleanupAfterMs, cleaned, now);
+
   return cleaned;
 }
 
+// Seconds since the longest-overdue Done-status bundle should have been
+// deleted (expiresAt+grace passed) but still isn't — 0 when the pass
+// cleaned everything that was due, or nothing was due.
+function oldestOverdueAgeSeconds(
+  overdueDoneCleanupAfterMs: ReadonlyMap<string, number>,
+  cleanedIds: readonly string[],
+  now: Instant,
+): number {
+  const cleaned = new Set(cleanedIds);
+  let oldestAgeSeconds = 0;
+  for (const [id, cleanupAfterMs] of overdueDoneCleanupAfterMs) {
+    if (cleaned.has(id)) continue;
+    const ageSeconds = (now.epochMilliseconds - cleanupAfterMs) / 1000;
+    if (ageSeconds > oldestAgeSeconds) oldestAgeSeconds = ageSeconds;
+  }
+  return oldestAgeSeconds;
+}
+
+// Best-effort like the email callbacks above: an observability hiccup
+// (metric not yet registered on this meter, provider misconfig) must not
+// fail a pass that otherwise cleaned up fine.
+function reportOldestOverdueAge(
+  metrics: MetricsHandle | undefined,
+  overdueDoneCleanupAfterMs: ReadonlyMap<string, number>,
+  cleanedIds: readonly string[],
+  now: Instant,
+): void {
+  // skip: no meter configured means there is nothing to report — the cleanup pass itself already ran to completion.
+  if (!metrics) return;
+  try {
+    metrics.set(
+      EXPORT_CLEANUP_BACKLOG_AGE_METRIC,
+      oldestOverdueAgeSeconds(overdueDoneCleanupAfterMs, cleanedIds, now),
+    );
+  } catch (err) {
+    // biome-ignore lint/suspicious/noConsole: operator-visibility for observability-emit-failure
+    console.warn(
+      `[user-data-rights:run-export-jobs] metrics.set(${EXPORT_CLEANUP_BACKLOG_AGE_METRIC}) failed err=${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 // Wrapper: crud.update braucht TenantDb. ExportJob ist tenant-agnostisch
 // (1 Job pro userId), aber der event-store-Stream-Lookup erwartet einen
 // Tenant-Context. system-mode TenantDb bypassed den auto-tenant-filter

package/src/user-data-rights-defaults/__tests__/user-data-rights-defaults.integration.test.ts

@@ -15,7 +15,13 @@ import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { variantSuffix } from "@cosmicdrift/kumiko-framework/derivatives";
-import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createFileField,
+  createImageField,
+  defineFeature,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
 import {
   createInMemoryFileProvider,
   deriveKey,
@@ -29,7 +35,9 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
 import { createDataRetentionFeature } from "../../data-retention";
+import { fileFoundationFeature } from "../../file-foundation";
 import { createFilesFeature } from "../../files";
 import { createSessionsFeature } from "../../sessions";
 import {
@@ -46,15 +54,50 @@ import { fileRefDeleteHook, fileRefExportHook, userDeleteHook, userExportHook }
 
 let stack: TestStack;
 
+// #3005 fixture: a business entity with file fields covering the three
+// field-annotation shapes fileRefDeleteHook must branch on — explicitly
+// non-personal (dealer's own business data), personal (self), and no
+// annotation at all (the conservative "no annotation" case).
+const vehicleEntity = createEntity({
+  table: "test_vehicles",
+  fields: {
+    dealerPhoto: createImageField({
+      personal: false,
+      reason: "dealer_business_data_test_fixture",
+    }),
+    driverSelfie: createImageField({ personal: "self" }),
+    unannotatedDoc: createFileField(),
+  },
+});
+
+const vehicleFeature = defineFeature("testVehicleFileFields", (r) => {
+  r.entity("vehicle", vehicleEntity);
+});
+
+// The vehicle fixture's image/file fields make server.ts's boot guard require
+// a mounted file-storage provider (registryDeclaresFileFields). The hook
+// tests below never resolve a provider through the registry — each passes
+// its own `buildStorageProvider` directly — so this one only exists to
+// satisfy that boot check.
+const bootGuardFileProvider = createInMemoryFileProvider();
+const testFileProviderFeature = defineFeature("testFileProviderBootGuard", (r) => {
+  r.requires("file-foundation");
+  r.useExtension("fileProvider", "test", { build: async () => bootGuardFileProvider });
+});
+
 const features = [
   createUserFeature(),
+  createConfigFeature(),
   createFilesFeature(),
+  fileFoundationFeature,
+  testFileProviderFeature,
   createDataRetentionFeature(),
   createComplianceProfilesFeature(),
   authFoundationFeature,
   createSessionsFeature(),
   createUserDataRightsFeature(),
   createUserDataRightsDefaultsFeature(),
+  vehicleFeature,
 ];
 
 beforeAll(async () => {
@@ -119,6 +162,35 @@ async function seedFileRef(
   );
 }
 
+// #3005: seeds a fileRef attached to an entity/field, for testing the
+// per-row PII-vs-business-data decision in fileRefDeleteHook.
+async function seedFileRefWithField(
+  id: string,
+  tenantId: string,
+  insertedById: string,
+  entityType: string | null,
+  fieldName: string | null,
+  fileName: string,
+): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `
+    INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size, entity_type, entity_id, field_name, inserted_by_id)
+    VALUES ($1, $2, $3, $4, 'image/jpeg', 1024, $5, $6, $7, $8)
+    ON CONFLICT (id) DO NOTHING
+  `,
+    [
+      id,
+      tenantId,
+      `storage/${id}`,
+      fileName,
+      entityType,
+      entityType !== null ? "1" : null,
+      fieldName,
+      insertedById,
+    ],
+  );
+}
+
 async function fetchUser(id: string) {
   const result = await asRawClient(stack.db).unsafe(
     `
@@ -409,6 +481,131 @@ describe("S2.H2 :: fileRefDeleteHook", () => {
   });
 });
 
+describe("S2.H2 :: fileRefDeleteHook — per-row PII decision (issue #3005)", () => {
+  test('strategy="delete" — field explicitly non-personal (dealer business data): binary + row survive, insertedById=null', async () => {
+    const userId = "user-dealer-photo";
+    await seedFileRefWithField(
+      uuid(601),
+      TENANT_A,
+      userId,
+      "vehicle",
+      "dealerPhoto",
+      "vehicle-front.jpg",
+    );
+
+    await fileRefDeleteHook(
+      {
+        db: createTenantDb(stack.db, TENANT_A, "tenant"),
+        registry: stack.registry,
+        tenantId: TENANT_A,
+        userId,
+      },
+      "delete",
+    );
+
+    const ownedAfter = await fetchFileRefs(TENANT_A, userId);
+    expect(ownedAfter).toHaveLength(0);
+    const anonymized = await fetchFileRefs(TENANT_A, null);
+    const row = anonymized.find((f: { id: string }) => f.id === uuid(601));
+    expect(row).toBeDefined();
+    expect(row.inserted_by_id).toBeNull();
+  });
+
+  test('strategy="delete" — field marked personal (self): binary + row are gone', async () => {
+    const userId = "user-driver-selfie";
+    await seedFileRefWithField(
+      uuid(602),
+      TENANT_A,
+      userId,
+      "vehicle",
+      "driverSelfie",
+      "selfie.jpg",
+    );
+
+    await fileRefDeleteHook(
+      {
+        db: createTenantDb(stack.db, TENANT_A, "tenant"),
+        registry: stack.registry,
+        tenantId: TENANT_A,
+        userId,
+      },
+      "delete",
+    );
+
+    const remaining = await fetchFileRefs(TENANT_A);
+    expect(remaining.find((f: { id: string }) => f.id === uuid(602))).toBeUndefined();
+  });
+
+  test('strategy="delete" — unattached upload (entityType/fieldName both null): hard-deleted', async () => {
+    const userId = "user-unattached-hard";
+    await seedFileRefWithField(uuid(603), TENANT_A, userId, null, null, "loose-file.pdf");
+
+    await fileRefDeleteHook(
+      {
+        db: createTenantDb(stack.db, TENANT_A, "tenant"),
+        registry: stack.registry,
+        tenantId: TENANT_A,
+        userId,
+      },
+      "delete",
+    );
+
+    const remaining = await fetchFileRefs(TENANT_A);
+    expect(remaining.find((f: { id: string }) => f.id === uuid(603))).toBeUndefined();
+  });
+
+  test('strategy="delete" — field exists but carries no annotation: anonymized, not hard-deleted', async () => {
+    const userId = "user-unannotated-field";
+    await seedFileRefWithField(uuid(604), TENANT_A, userId, "vehicle", "unannotatedDoc", "doc.pdf");
+
+    await fileRefDeleteHook(
+      {
+        db: createTenantDb(stack.db, TENANT_A, "tenant"),
+        registry: stack.registry,
+        tenantId: TENANT_A,
+        userId,
+      },
+      "delete",
+    );
+
+    const ownedAfter = await fetchFileRefs(TENANT_A, userId);
+    expect(ownedAfter).toHaveLength(0);
+    const anonymized = await fetchFileRefs(TENANT_A, null);
+    const row = anonymized.find((f: { id: string }) => f.id === uuid(604));
+    expect(row).toBeDefined();
+    expect(row.inserted_by_id).toBeNull();
+  });
+
+  test('strategy="delete" — entityType not resolvable in the registry: anonymized, never a silent hard-delete', async () => {
+    const userId = "user-unresolvable-entity";
+    await seedFileRefWithField(
+      uuid(605),
+      TENANT_A,
+      userId,
+      "no-such-entity",
+      "somefield",
+      "orphaned.pdf",
+    );
+
+    await fileRefDeleteHook(
+      {
+        db: createTenantDb(stack.db, TENANT_A, "tenant"),
+        registry: stack.registry,
+        tenantId: TENANT_A,
+        userId,
+      },
+      "delete",
+    );
+
+    const ownedAfter = await fetchFileRefs(TENANT_A, userId);
+    expect(ownedAfter).toHaveLength(0);
+    const anonymized = await fetchFileRefs(TENANT_A, null);
+    const row = anonymized.find((f: { id: string }) => f.id === uuid(605));
+    expect(row).toBeDefined();
+    expect(row.inserted_by_id).toBeNull();
+  });
+});
+
 describe("S2.H2 :: fileRefDeleteHook — GDPR derivatives survive forget (issue #2461)", () => {
   async function seedFileRefWithKey(
     id: string,