@cosmicdrift/kumiko-bundled-features 0.23.1 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.23.1",
+  "version": "0.24.1",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

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

@@ -236,6 +236,43 @@ describe("scenario 5: change-password success", () => {
   });
 });
 
+describe("scenario 5b: change-password when the aggregate stream tenant != session tenant (sysadmin pattern)", () => {
+  test("user whose stream lives in a non-session tenant still changes password", async () => {
+    // Sysadmin pattern: created via systemAdmin (stream = systemAdmin.tenantId),
+    // only membership on a different tenant → the session/membership tenant
+    // diverges from where the aggregate actually lives. change-password writes
+    // as the session tenant; without recovering the real stream tenant it
+    // version_conflicts against an empty stream and the operator is locked out
+    // of rotating their own password.
+    const membershipTenant = testTenantId(2);
+    const seed = await seedLoginUser({
+      email: "sysadmin-cp@example.com",
+      password: "old-sysadmin-pw",
+      tenantId: membershipTenant,
+    });
+
+    const streamRows = (await asRawClient(stack.db).unsafe(
+      `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
+      [seed.id, "user"],
+    )) as ReadonlyArray<{ t: string }>;
+    expect(streamRows[0]?.t).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.t).not.toBe(membershipTenant);
+
+    const signedIn = createTestUser({ id: seed.id, tenantId: seed.tenantId, roles: ["User"] });
+    await stack.http.writeOk(
+      AuthHandlers.changePassword,
+      { oldPassword: "old-sysadmin-pw", newPassword: "new-sysadmin-pw-long" },
+      signedIn,
+    );
+
+    const newRes = await stack.http.raw("POST", "/api/auth/login", {
+      email: "sysadmin-cp@example.com",
+      password: "new-sysadmin-pw-long",
+    });
+    expect(newRes.status).toBe(200);
+  });
+});
+
 // --- Scenario 6: logout is reachable for authenticated users ---
 
 describe("scenario 6: logout", () => {

package/src/auth-email-password/__tests__/email-verification.integration.test.ts

@@ -322,3 +322,35 @@ describe("login with strict email-verification", () => {
     expect(body.error?.details?.reason).toBe(AuthErrors.invalidCredentials);
   });
 });
+
+describe("verify-email — aggregate stream in a non-membership tenant (sysadmin pattern)", () => {
+  test("user whose aggregate stream lives in a tenant they are NOT a member of still verifies", async () => {
+    // Prod sysadmin repro: the user aggregate is created via `systemAdmin`,
+    // so its event stream lives in systemAdmin.tenantId (…0001), while the
+    // user's ONLY membership is on a different tenant (…0002). resolveStream-
+    // Tenants must discover the real stream tenant from the event log — if it
+    // only tried membership tenants, every write would target …0002, get a
+    // version_conflict, collapse to all_conflicts → invalid_verification_token.
+    const membershipTenant = "00000000-0000-4000-8000-000000000002" as TenantId;
+    const seed = await seedUser({
+      email: "sysadmin-pattern@example.com",
+      password: "pw-sysadmin-pat-1234",
+      tenantId: membershipTenant,
+    });
+
+    const streamRows = (await asRawClient(stack.db).unsafe(
+      `SELECT "tenant_id", "aggregate_type" FROM "kumiko_events" WHERE "aggregate_id" = $1 ORDER BY "version" LIMIT 1`,
+      [seed.id],
+    )) as ReadonlyArray<{ tenant_id: string; aggregate_type: string }>;
+    expect(streamRows[0]?.aggregate_type).toBe("user");
+    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.tenant_id).not.toBe(membershipTenant);
+
+    const { token } = signVerificationToken(seed.id, 60, verifySecret);
+    const res = await post("/api/auth/verify-email", { token });
+    expect(res.status).toBe(200);
+
+    const row = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    expect(row?.["emailVerified"]).toBe(true);
+  });
+});

package/src/auth-email-password/__tests__/password-reset.integration.test.ts

@@ -303,6 +303,37 @@ describe("POST /auth/reset-password", () => {
     const body = await second.json();
     expect(body.error?.details?.reason).toBe(AuthErrors.invalidResetToken);
   });
+
+  test("user whose aggregate stream lives in a tenant they are NOT a member of can still reset", async () => {
+    // Mirror of the verify-email sysadmin repro: aggregate stream in …0001
+    // (created via systemAdmin), only membership on …0002. The reset must
+    // target the real stream tenant, not the membership tenant.
+    const membershipTenant = "00000000-0000-4000-8000-000000000002" as TenantId;
+    const seed = await seedUser({
+      email: "sysadmin-reset@example.com",
+      password: "pw-old-sysadmin-1234",
+      tenantId: membershipTenant,
+    });
+
+    const streamRows = (await asRawClient(stack.db).unsafe(
+      `SELECT "tenant_id", "aggregate_type" FROM "kumiko_events" WHERE "aggregate_id" = $1 ORDER BY "version" LIMIT 1`,
+      [seed.id],
+    )) as ReadonlyArray<{ tenant_id: string; aggregate_type: string }>;
+    expect(streamRows[0]?.aggregate_type).toBe("user");
+    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.tenant_id).not.toBe(membershipTenant);
+
+    const { token } = signResetToken(seed.id, 15, resetSecret);
+    const res = await post("/api/auth/reset-password", {
+      token,
+      newPassword: "pw-new-sysadmin-1234",
+    });
+    expect(res.status).toBe(200);
+
+    const row = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    const valid = await verifyPassword(row?.["passwordHash"] as string, "pw-new-sysadmin-1234");
+    expect(valid).toBe(true);
+  });
 });
 
 // --- session auto-revoke (H.3 cross-feature hook) -------------------------

package/src/auth-email-password/handlers/change-password.write.ts

@@ -1,7 +1,8 @@
 import { access, createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { getAggregateStreamTenant } from "@cosmicdrift/kumiko-framework/event-store";
 import { z } from "zod";
-import { UserHandlers, UserQueries } from "../../user";
+import { USER_FEATURE, UserHandlers, UserQueries } from "../../user";
 import { AuthErrors } from "../constants";
 import { hashPassword, verifyPassword } from "../password-hashing";
 
@@ -43,10 +44,19 @@ export const changePasswordWrite = defineWriteHandler({
 
     const newHash = await hashPassword(event.payload.newPassword);
 
+    // The user aggregate is r.systemScope(): its event stream can live in a
+    // tenant that isn't the session tenant (a platform operator's stream sits
+    // in the seed executor's tenant, not their membership). Write against the
+    // real stream tenant so optimistic locking targets the right stream instead
+    // of version_conflict-ing against an empty one. Falls back to the session
+    // tenant when the lookup finds nothing (fresh/unknown stream).
+    const streamTenant = await getAggregateStreamTenant(ctx.db.raw, event.user.id, USER_FEATURE);
+    const writer = createSystemUser(streamTenant ?? event.user.tenantId);
+
     // Apply via user feature's update handler — writeAs(system) satisfies
     // the privileged-only write rule on passwordHash. Pass the current version
     // through so optimistic locking still applies end-to-end.
-    const writeRes = await ctx.writeAs(systemUser, UserHandlers.update, {
+    const writeRes = await ctx.writeAs(writer, UserHandlers.update, {
       id: me.id,
       version: me.version,
       changes: { passwordHash: newHash },

package/src/auth-email-password/handlers/confirm-token-flow.ts

@@ -29,8 +29,9 @@ import {
   type WriteFailure,
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
+import { getAggregateStreamTenant } from "@cosmicdrift/kumiko-framework/event-store";
 import type Redis from "ioredis";
-import { UserHandlers, UserQueries } from "../../user";
+import { USER_FEATURE, UserHandlers, UserQueries } from "../../user";
 import type { AuthUserRow } from "../auth-user-row";
 import { parseAuthUserRow } from "../auth-user-row";
 import { orderTenantsByPreference } from "../stream-tenant";
@@ -153,7 +154,21 @@ async function resolveStreamTenants(
   const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
     userId: me.id,
   })) as Array<{ tenantId: TenantId }>; // @cast-boundary db-runner
-  return orderTenantsByPreference(memberships, me.lastActiveTenantId);
+  const ordered = orderTenantsByPreference(memberships, me.lastActiveTenantId);
+  if (ordered.length === 0) return [];
+
+  // The user aggregate is r.systemScope(): its event stream lives in whichever
+  // tenant the creating executor used, which need NOT be a membership tenant.
+  // A platform operator seeded under a fixture/platform tenant is the live case
+  // — its stream tenant is absent from `ordered`, so a membership-only search
+  // rejects every write and collapses to invalid_token. Recover the real stream
+  // tenant from the event log and try it first; memberships stay as fallback,
+  // and an empty/unknown lookup degrades to the prior membership-only behaviour.
+  const streamTenant = await getAggregateStreamTenant(ctx.db.raw, me.id, USER_FEATURE);
+  if (streamTenant && !ordered.includes(streamTenant)) {
+    return [streamTenant, ...ordered];
+  }
+  return ordered;
 }
 
 // Discriminated result for the write-across-tenants loop.

package/src/compliance-profiles/__tests__/parse-override.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { parseComplianceProfileOverride } from "../_internal/parse-override";
+
+describe("parseComplianceProfileOverride", () => {
+  test("empty / whitespace / null → undefined, no warning", () => {
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(parseComplianceProfileOverride(null, "t1", "seed")).toBeUndefined();
+      expect(parseComplianceProfileOverride("", "t1", "seed")).toBeUndefined();
+      expect(parseComplianceProfileOverride("   ", "t1", "seed")).toBeUndefined();
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test("valid JSON object is returned verbatim", () => {
+    expect(parseComplianceProfileOverride('{"region":"eu"}', "t1", "seed")).toEqual({
+      region: "eu",
+    });
+  });
+
+  test("literal JSON null → undefined (no override), no warning", () => {
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(parseComplianceProfileOverride("null", "t1", "seed")).toBeUndefined();
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test("corrupt JSON warns WITH the parser reason and returns undefined (not a silent swallow)", () => {
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const result = parseComplianceProfileOverride(
+        "{not valid json",
+        "tenant-9",
+        "resolve-for-tenant",
+      );
+      expect(result).toBeUndefined();
+      expect(warn).toHaveBeenCalledTimes(1);
+      const msg = String(warn.mock.calls[0]?.[0]);
+      expect(msg).toContain("tenant-9");
+      expect(msg).toContain("resolve-for-tenant");
+      // The point of the fix: the parser's own failure reason is preserved,
+      // not flattened to a generic "is not valid JSON".
+      expect(msg).toContain("Reason:");
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/compliance-profiles/_internal/parse-override.ts

@@ -1,5 +1,5 @@
 import type { ComplianceProfileOverride } from "@cosmicdrift/kumiko-framework/compliance";
-import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 
 export function parseComplianceProfileOverride(
   raw: string | null,
@@ -7,13 +7,14 @@ export function parseComplianceProfileOverride(
   callerLabel: string,
 ): ComplianceProfileOverride | undefined {
   if (!raw || raw.trim() === "") return undefined;
-  const parsed = parseJsonSafe<ComplianceProfileOverride | null>(raw, null);
-  if (parsed === null) {
+  let parsed: ComplianceProfileOverride | null;
+  try {
+    parsed = parseJsonOrThrow<ComplianceProfileOverride | null>(raw, "compliance override");
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
     // biome-ignore lint/suspicious/noConsole: operator visibility for DB-corruption edge-case
-    console.warn(
-      `[${callerLabel}] tenant ${tenantId}: stored override is not valid JSON, ignoring.`,
-    );
+    console.warn(`[${callerLabel}] tenant ${tenantId}: stored override ignored. Reason: ${reason}`);
     return undefined;
   }
-  return parsed;
+  return parsed ?? undefined;
 }

package/src/custom-fields/__tests__/cross-tenant-set-write.integration.test.ts

@@ -0,0 +1,178 @@
+// Regression: a custom-field set/clear must only touch the calling tenant's own
+// row. aggregateId is a globally-unique row UUID, so without a tenant_id filter
+// on the projection UPDATE, tenant A could overwrite or clear tenant B's
+// customFields just by passing B's known row UUID as entityId. The set/clear
+// projection writes now scope to the event's own tenant (same guard the
+// fieldDefinition-delete path already uses).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createEntityExecutor,
+  createTextField,
+  defineEntityListHandler,
+  defineFeature,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  testUserId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { fieldDefinitionEntity } from "../entity";
+import { createCustomFieldsFeature } from "../feature";
+import { customFieldsField, wireCustomFieldsFor } from "../wire-for-entity";
+
+const propertyEntity = createEntity({
+  table: "read_xt_set_properties",
+  fields: {
+    name: createTextField({ required: true }),
+    customFields: customFieldsField(),
+  },
+});
+const propertyTable = buildEntityTable("property", propertyEntity);
+
+const propertyFeature = defineFeature("property-xt-set", (r) => {
+  r.entity("property", propertyEntity);
+  r.requires("custom-fields");
+  wireCustomFieldsFor(r, "property", propertyTable);
+
+  const { executor: propertyExecutor } = createEntityExecutor("property", propertyEntity);
+  r.writeHandler({
+    name: "property:create",
+    schema: z.object({ id: z.string(), name: z.string() }),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (event, ctx) => {
+      const payload = event.payload as { id: string; name: string };
+      return propertyExecutor.create(
+        { id: payload.id, name: payload.name, customFields: {} },
+        event.user,
+        ctx.db,
+      );
+    },
+  });
+
+  r.queryHandler(
+    defineEntityListHandler("property", propertyEntity, { access: { roles: ["TenantAdmin"] } }),
+  );
+});
+
+const customFieldsFeature = createCustomFieldsFeature();
+
+let stack: TestStack;
+
+const adminA = createTestUser({
+  id: testUserId(1),
+  tenantId: testTenantId(1),
+  roles: ["TenantAdmin"],
+});
+const adminB = createTestUser({
+  id: testUserId(10),
+  tenantId: testTenantId(2),
+  roles: ["TenantAdmin"],
+});
+
+const PROP_A = "aaaaaaaa-aaaa-4000-8000-000000000001";
+const PROP_B = "bbbbbbbb-bbbb-4000-8000-000000000002";
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [customFieldsFeature, propertyFeature] });
+  await unsafeCreateEntityTable(stack.db, fieldDefinitionEntity);
+  await unsafeCreateEntityTable(stack.db, propertyEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function defineField(user: SessionUser, fieldKey: string) {
+  return stack.http.writeOk(
+    "custom-fields:write:define-tenant-field",
+    {
+      entityName: "property",
+      fieldKey,
+      serializedField: { type: "text" },
+      required: false,
+      searchable: false,
+      displayOrder: 0,
+    },
+    user,
+  );
+}
+
+async function setField(user: SessionUser, entityId: string, fieldKey: string, value: unknown) {
+  return stack.http.writeOk(
+    "custom-fields:write:set-custom-field",
+    { entityName: "property", entityId, fieldKey, value },
+    user,
+  );
+}
+
+async function clearField(user: SessionUser, entityId: string, fieldKey: string) {
+  return stack.http.writeOk(
+    "custom-fields:write:clear-custom-field",
+    { entityName: "property", entityId, fieldKey },
+    user,
+  );
+}
+
+async function createProperty(user: SessionUser, id: string, name: string) {
+  return stack.http.writeOk("property-xt-set:write:property:create", { id, name }, user);
+}
+
+async function priorityOf(user: SessionUser, id: string): Promise<unknown> {
+  const { rows } = (await stack.http.queryOk("property-xt-set:query:property:list", {}, user)) as {
+    rows: Array<Record<string, unknown>>;
+  };
+  return rows.find((r) => r["id"] === id)?.["priority"];
+}
+
+describe("custom-fields cross-tenant isolation — set/clear write", () => {
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe(`DELETE FROM kumiko_events`);
+    await asRawClient(stack.db).unsafe(`DELETE FROM read_xt_set_properties`);
+    await asRawClient(stack.db).unsafe(`DELETE FROM read_custom_field_definitions`);
+
+    // Both tenants independently define their own "priority" field and own a row.
+    await defineField(adminA, "priority");
+    await defineField(adminB, "priority");
+    await createProperty(adminA, PROP_A, "A-Prop");
+    await createProperty(adminB, PROP_B, "B-Prop");
+    await setField(adminA, PROP_A, "priority", "A-value");
+    await setField(adminB, PROP_B, "priority", "B-value");
+    await stack.eventDispatcher?.runOnce();
+    expect(await priorityOf(adminB, PROP_B)).toBe("B-value");
+  });
+
+  test("tenant A cannot overwrite tenant B's row via a known entityId (set)", async () => {
+    // The set-handler runs as A (its own field-definition + RBAC pass) and emits
+    // on A's stream; the projection's tenant filter must keep it off B's row.
+    await setField(adminA, PROP_B, "priority", "HACKED");
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await priorityOf(adminB, PROP_B)).toBe("B-value");
+  });
+
+  test("tenant A cannot clear tenant B's row via a known entityId (clear)", async () => {
+    await clearField(adminA, PROP_B, "priority");
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await priorityOf(adminB, PROP_B)).toBe("B-value");
+  });
+
+  test("a tenant's own set still applies (filter does not block the legitimate path)", async () => {
+    await setField(adminA, PROP_A, "priority", "A-updated");
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await priorityOf(adminA, PROP_A)).toBe("A-updated");
+    expect(await priorityOf(adminB, PROP_B)).toBe("B-value");
+  });
+});

package/src/custom-fields/__tests__/field-access.integration.test.ts

@@ -266,3 +266,62 @@ describe("T1.5b: per-field fieldAccess.write rejects users without required role
     expect(err.code).toBe("not_found");
   });
 });
+
+// A row whose serialized_field is corrupt (DB corruption / partial write)
+// must NOT silently drop the per-field write gate. Before the fix the access
+// check fell open ({ ok: true }) and the write went through unvalidated; now
+// it fails closed with a distinct reason.
+describe("fail-closed on corrupt serialized_field", () => {
+  async function corruptStoredDefinition(fieldKey: string) {
+    await asRawClient(stack.db).unsafe(
+      `UPDATE read_custom_field_definitions SET serialized_field = '{not valid json' WHERE field_key = $1`,
+      [fieldKey],
+    );
+  }
+
+  test("set: corrupt definition row → unprocessable field_definition_corrupt (not silent allow)", async () => {
+    const propertyId = "77777777-7777-4000-8000-000000000007";
+    await defineField("corruptField", { type: "text", fieldAccess: { write: ["TenantAdmin"] } });
+    await corruptStoredDefinition("corruptField");
+    await stack.http.writeOk(
+      "property-t15b:write:property:create",
+      { id: propertyId, name: "Corrupt" },
+      tenantAdmin,
+    );
+
+    const err = await stack.http.writeErr(
+      "custom-fields:write:set-custom-field",
+      { entityName: "property", entityId: propertyId, fieldKey: "corruptField", value: "X-42" },
+      tenantAdmin,
+    );
+
+    expect(err.code).toBe("unprocessable");
+    expect(err.details).toMatchObject({
+      reason: "field_definition_corrupt",
+      fieldKey: "corruptField",
+    });
+  });
+
+  test("clear: corrupt definition row → unprocessable field_definition_corrupt", async () => {
+    const propertyId = "88888888-8888-4000-8000-000000000008";
+    await defineField("corruptField", { type: "boolean" });
+    await corruptStoredDefinition("corruptField");
+    await stack.http.writeOk(
+      "property-t15b:write:property:create",
+      { id: propertyId, name: "Corrupt2" },
+      tenantAdmin,
+    );
+
+    const err = await stack.http.writeErr(
+      "custom-fields:write:clear-custom-field",
+      { entityName: "property", entityId: propertyId, fieldKey: "corruptField" },
+      tenantAdmin,
+    );
+
+    expect(err.code).toBe("unprocessable");
+    expect(err.details).toMatchObject({
+      reason: "field_definition_corrupt",
+      fieldKey: "corruptField",
+    });
+  });
+});

package/src/custom-fields/__tests__/value-schema.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { buildCustomFieldValueSchema } from "../lib/value-schema";
+
+describe("buildCustomFieldValueSchema — type-shape only", () => {
+  test("strips top-level constraint keys (required/maxLength/format)", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "text",
+      required: true,
+      maxLength: 5,
+      format: "email",
+    });
+    expect(schema).not.toBeNull();
+    expect(schema?.safeParse("").success).toBe(true);
+    expect(schema?.safeParse("not-an-email-and-way-too-long").success).toBe(true);
+    expect(schema?.safeParse(42).success).toBe(false);
+  });
+
+  test("embedded validates sub-field TYPE only — sub-field `required` is stripped", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "embedded",
+      schema: { city: { type: "text", required: true } },
+    });
+    expect(schema).not.toBeNull();
+    // type-valid objects pass, regardless of the sub-field `required` flag
+    expect(schema?.safeParse({ city: "Bonn" }).success).toBe(true);
+    expect(schema?.safeParse({}).success).toBe(true);
+    expect(schema?.safeParse({ city: "" }).success).toBe(true);
+    // type-mismatches still rejected: non-object, and wrong sub-field type
+    expect(schema?.safeParse("not-an-object").success).toBe(false);
+    expect(schema?.safeParse({ city: 123 }).success).toBe(false);
+  });
+
+  test("embedded strip applies to non-text sub-types too (number)", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "embedded",
+      schema: { age: { type: "number", required: true } },
+    });
+    expect(schema).not.toBeNull();
+    expect(schema?.safeParse({ age: 7 }).success).toBe(true);
+    // required stripped → missing key passes (pre-fix the non-optional number
+    // sub-field rejected it)
+    expect(schema?.safeParse({}).success).toBe(true);
+    // type-mismatch still rejected
+    expect(schema?.safeParse({ age: "not-a-number" }).success).toBe(false);
+  });
+
+  test("embedded with an unsupported sub-type → null (skip validation)", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "embedded",
+      schema: { blob: { type: "json" } },
+    });
+    expect(schema).toBeNull();
+  });
+});

package/src/custom-fields/db/queries/projection.ts

@@ -13,19 +13,22 @@ function bindJsonbParam(value: unknown): { sql: string; bound: unknown } {
   return { sql: "$1::jsonb", bound: value };
 }
 
+// Security invariant: aggregateId is a global row UUID, so without the tenant_id
+// filter tenant A could mutate tenant B's row by its UUID (cf. removeCustomFieldKeyForTenant).
 export async function setCustomFieldValue(
   db: DbRunner,
   tableName: string,
   fieldKey: string,
   value: unknown,
   aggregateId: string,
+  tenantId: string,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   const escapedKey = fieldKey.replace(/'/g, "''");
   const jsonb = bindJsonbParam(value);
   await asRawClient(db).unsafe(
-    `UPDATE ${tbl} SET custom_fields = jsonb_set(custom_fields, '{${escapedKey}}', ${jsonb.sql}, true) WHERE id = $2`,
-    [jsonb.bound, aggregateId],
+    `UPDATE ${tbl} SET custom_fields = jsonb_set(custom_fields, '{${escapedKey}}', ${jsonb.sql}, true) WHERE id = $2 AND tenant_id = $3`,
+    [jsonb.bound, aggregateId, tenantId],
   );
 }
 
@@ -34,11 +37,12 @@ export async function clearCustomFieldKey(
   tableName: string,
   fieldKey: string,
   aggregateId: string,
+  tenantId: string,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   await asRawClient(db).unsafe(
-    `UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE id = $2`,
-    [fieldKey, aggregateId],
+    `UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE id = $2 AND tenant_id = $3`,
+    [fieldKey, aggregateId, tenantId],
   );
 }
 

package/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -36,6 +36,9 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
       if (accessCheck.reason === "field_definition_not_found") {
         return failNotFound("fieldDefinition", payload.fieldKey);
       }
+      if (accessCheck.reason === "field_definition_corrupt") {
+        return failUnprocessable("field_definition_corrupt", { fieldKey: payload.fieldKey });
+      }
       return failUnprocessable("field_access_denied", {
         fieldKey: payload.fieldKey,
         requiredRoles: accessCheck.requiredRoles ?? [],

package/src/custom-fields/handlers/set-custom-field.write.ts

@@ -13,7 +13,11 @@ export const setCustomFieldPayloadSchema = z.object({
     .min(1)
     .max(64)
     .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
-  value: z.unknown(),
+  // z.unknown() is implicitly optional; reject a missing value here (clearing is
+  // clear-custom-field's job) so the projection never binds JSON.stringify(undefined).
+  value: z
+    .unknown()
+    .refine((v) => v !== undefined, "value is required (use clear-custom-field to remove a value)"),
 });
 export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 
@@ -57,6 +61,9 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     if (!loaded.found) {
       return failNotFound("fieldDefinition", payload.fieldKey);
     }
+    if (loaded.field === null) {
+      return failUnprocessable("field_definition_corrupt", { fieldKey: payload.fieldKey });
+    }
 
     const deniedRoles = fieldWriteAccessDeniedRoles(loaded.field, event.user.roles);
     if (deniedRoles) {

package/src/custom-fields/lib/field-access.ts

@@ -10,15 +10,15 @@ export type FieldAccessCheckResult =
   | { ok: true }
   | {
       ok: false;
-      reason: "field_definition_not_found" | "field_access_denied";
+      reason: "field_definition_not_found" | "field_definition_corrupt" | "field_access_denied";
       requiredRoles?: ReadonlyArray<string>;
     };
 
 export type LoadedFieldDefinition =
   | { found: false }
-  // `field` is null when the row exists but its serialized_field is corrupt —
-  // callers treat that as "no restriction / no schema" (lenient), distinct
-  // from `found: false` (no definition → 404).
+  // `field` is null when the row exists but its serialized_field is corrupt.
+  // A write access-gate treats this fail-closed (secure-by-default): a corrupt
+  // definition must not silently drop a per-field write restriction.
   | { found: true; field: SerializedFieldShape | null };
 
 export async function loadFieldDefinition(
@@ -54,6 +54,7 @@ export async function checkFieldAccessForWrite(
 ): Promise<FieldAccessCheckResult> {
   const loaded = await loadFieldDefinition(db, tenantId, entityName, fieldKey);
   if (!loaded.found) return { ok: false, reason: "field_definition_not_found" };
+  if (loaded.field === null) return { ok: false, reason: "field_definition_corrupt" };
 
   const deniedRoles = fieldWriteAccessDeniedRoles(loaded.field, userRoles);
   if (!deniedRoles) return { ok: true };

package/src/custom-fields/lib/value-schema.ts

@@ -47,20 +47,32 @@ export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny
   // Embedded sub-fields: pre-check the sub-type set so we surface unknown
   // sub-types as "skip validation" (return null) rather than letting
   // fieldToZod's assertUnreachable throw and the catch swallow real bugs.
+  // Build a constraint-stripped copy of each sub-field in the same pass —
+  // symmetric with the top-level strip below. Without it a sub-field's
+  // `required` folds into z.string().min(1) + non-optional, re-enforcing a
+  // constraint the contract ("type-mismatches and ONLY type-mismatches")
+  // drops everywhere else.
+  let strippedSubSchema: Record<string, Record<string, unknown>> | undefined;
   if (rawType === "embedded") {
     const schema = obj["schema"];
     if (!schema || typeof schema !== "object") return null;
-    for (const sub of Object.values(schema)) {
+    strippedSubSchema = {};
+    for (const [subKey, sub] of Object.entries(schema)) {
       if (!sub || typeof sub !== "object") return null;
-      const subType = (sub as Record<string, unknown>)["type"];
+      const subObj = sub as Record<string, unknown>;
+      const subType = subObj["type"];
       if (typeof subType !== "string" || !SUPPORTED_EMBEDDED_SUB_TYPES.has(subType)) {
         return null;
       }
+      const strippedSub = { ...subObj };
+      for (const k of CONSTRAINT_KEYS) delete strippedSub[k];
+      strippedSubSchema[subKey] = strippedSub;
     }
   }
 
   const fieldDef: Record<string, unknown> = { ...obj };
   for (const k of CONSTRAINT_KEYS) delete fieldDef[k];
+  if (strippedSubSchema !== undefined) fieldDef["schema"] = strippedSubSchema;
   if (rawType === "enum") {
     fieldDef["type"] = "select";
     fieldDef["options"] = obj["values"] ?? obj["options"] ?? [];

package/src/custom-fields/wire-for-entity.ts

@@ -114,6 +114,7 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
           payload.fieldKey,
           payload.value,
           event.aggregateId,
+          event.tenantId,
         );
       },
       [clearedEventType]: async (event, tx) => {
@@ -124,7 +125,13 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
 
         // jsonb minus operator (`-`) entfernt key aus jsonb-object.
         const tableName = getTableName(entityTable);
-        await clearCustomFieldKey(tx, tableName, payload.fieldKey, event.aggregateId);
+        await clearCustomFieldKey(
+          tx,
+          tableName,
+          payload.fieldKey,
+          event.aggregateId,
+          event.tenantId,
+        );
       },
       [fieldDefDeletedType]: async (event, tx) => {
         // fieldDefinition.deleted fires nur einmal pro fieldDef-delete

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

@@ -14,6 +14,7 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient, deleteMany, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineUnmanagedTable } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineFeature,
   EXT_USER_DATA,
@@ -60,17 +61,16 @@ type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 const NOW = (): Instant => getTemporal().Now.instant();
 const PAST = (): Instant => getTemporal().Instant.fromEpochMilliseconds(Date.now() - 60_000);
 
-const KUMIKO_NAME = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS = Symbol.for("kumiko:schema:Columns");
-
-/** Minimal bun-db table descriptor for the synthetic test_notes table. */
-const testNotesTable = {
-  [KUMIKO_NAME]: "test_notes",
-  [KUMIKO_COLUMNS]: {
-    tenantId: { name: "tenant_id", getSQLType: () => "uuid" },
-    authorId: { name: "author_id", getSQLType: () => "text" },
-  },
-};
+// Synthetic third-party "note" table — unmanaged (no entity-system base
+// columns). deleteMany only filters on tenant_id + author_id, so those are the
+// only columns the query layer needs to know about.
+const testNotesTable = defineUnmanagedTable({
+  tableName: "test_notes",
+  columns: [
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "author_id", pgType: "text", notNull: true },
+  ],
+});
 
 // Synthetic third-party Domain-Feature: "note" mit export- + delete-Hook.
 // Stellvertretend fuer App-spezifische Entities (Chat-Message, Blog-Post

package/src/user-data-rights/__tests__/file-binary-forget-cleanup.integration.test.ts

@@ -0,0 +1,178 @@
+// Forget-Hook binary-Cleanup Integration-Test.
+//
+// Beweist, dass der `fileRef`-Forget-Hook bei strategy="delete" die
+// Storage-Binaries via `storageProvider.delete()` entfernt, BEVOR die
+// row hard-gelöscht wird — ohne provider leakt sonst jede gelöschte
+// Datei ihre Bytes dauerhaft auf Disk (Issue gefunden im Review zu #177).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createInMemoryFileProvider,
+  fileRefsTable,
+  type InMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { createFilesFeature } from "../../files";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defaults";
+import { createUserDataRightsFeature } from "../feature";
+import { runForgetCleanup } from "../run-forget-cleanup";
+
+let stack: TestStack;
+let db: DbConnection;
+let provider: InMemoryFileProvider;
+
+const TENANT = "00000000-0000-4000-8000-00000000000c";
+const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
+
+function uuid(suffix: number): string {
+  return `bbbbbbbb-bbbb-4bbb-8bbb-${suffix.toString(16).padStart(12, "0")}`;
+}
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+const NOW = (): Instant => getTemporal().Now.instant();
+const pastInstant = (): Instant => getTemporal().Instant.fromEpochMilliseconds(Date.now() - 60_000);
+
+beforeAll(async () => {
+  provider = createInMemoryFileProvider();
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createFilesFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      createSessionsFeature(),
+      createUserDataRightsFeature(),
+      createUserDataRightsDefaultsFeature({ storageProvider: provider }),
+    ],
+    files: { storageProvider: provider },
+  });
+  db = stack.db;
+
+  await unsafeCreateEntityTable(db, userEntity);
+  await unsafeCreateEntityTable(db, tenantRetentionOverrideEntity);
+  await unsafePushTables(db, { fileRefsTable });
+  await asRawClient(db).unsafe(`
+    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      tenant_id UUID NOT NULL,
+      user_id TEXT NOT NULL,
+      version INTEGER NOT NULL DEFAULT 0,
+      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      inserted_by_id TEXT,
+      modified_by_id TEXT,
+      is_deleted BOOLEAN NOT NULL DEFAULT false,
+      deleted_at TIMESTAMPTZ,
+      deleted_by_id TEXT,
+      roles TEXT NOT NULL DEFAULT '[]',
+      UNIQUE(user_id, tenant_id)
+    )
+  `);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  provider.clear();
+  await resetTestTables(db, [userTable, "read_tenant_memberships", fileRefsTable]);
+});
+
+async function seedForgetUser(id: string): Promise<void> {
+  await insertOne(db, userTable, {
+    id,
+    tenantId: TENANT_SYSTEM,
+    email: `user-${id}@example.com`,
+    passwordHash: "hashed",
+    displayName: `User ${id}`,
+    locale: "de",
+    emailVerified: true,
+    roles: '["Member"]',
+    status: USER_STATUS.DeletionRequested,
+    gracePeriodEnd: pastInstant(),
+  });
+}
+
+async function seedMembership(userId: string, tenantId: string): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
+     VALUES ($1, $2, '["Member"]') ON CONFLICT (user_id, tenant_id) DO NOTHING`,
+    [tenantId, userId],
+  );
+}
+
+async function seedFile(id: string, tenantId: string, insertedById: string): Promise<string> {
+  const storageKey = `storage/${id}`;
+  await provider.write(storageKey, new Uint8Array([1, 2, 3, 4]), "application/pdf");
+  await asRawClient(db).unsafe(
+    `INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size, inserted_by_id)
+     VALUES ($1, $2, $3, $4, 'application/pdf', 4, $5) ON CONFLICT (id) DO NOTHING`,
+    [id, tenantId, storageKey, `${id}.pdf`, insertedById],
+  );
+  return storageKey;
+}
+
+describe("forget-binary-cleanup :: storage.delete fires before row hard-delete", () => {
+  test("Forget deletes the binary from the storage provider", async () => {
+    const userId = uuid(1);
+    await seedForgetUser(userId);
+    await seedMembership(userId, TENANT);
+    const key = await seedFile(uuid(101), TENANT, userId);
+    expect(await provider.exists(key)).toBe(true);
+
+    const result = await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+
+    expect(result.processedUserIds).toContain(userId);
+    expect(await provider.exists(key)).toBe(false);
+    expect(provider.keys()).not.toContain(key);
+  });
+
+  test("Multiple files from the same user — all binaries cleaned up", async () => {
+    const userId = uuid(2);
+    await seedForgetUser(userId);
+    await seedMembership(userId, TENANT);
+    const keys = await Promise.all([
+      seedFile(uuid(201), TENANT, userId),
+      seedFile(uuid(202), TENANT, userId),
+      seedFile(uuid(203), TENANT, userId),
+    ]);
+    expect(provider.keys()).toHaveLength(3);
+
+    await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+
+    for (const key of keys) {
+      expect(await provider.exists(key)).toBe(false);
+    }
+    expect(provider.keys()).toHaveLength(0);
+  });
+
+  test("Other tenants' files stay untouched", async () => {
+    const userId = uuid(3);
+    const otherTenant = "00000000-0000-4000-8000-00000000000d";
+    await seedForgetUser(userId);
+    await seedMembership(userId, TENANT);
+    const myKey = await seedFile(uuid(301), TENANT, userId);
+    const otherKey = await seedFile(uuid(302), otherTenant, "another-user");
+    // The other-tenant file is owned by a different user; the forget run for
+    // userId must NOT touch it.
+
+    await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+
+    expect(await provider.exists(myKey)).toBe(false);
+    expect(await provider.exists(otherKey)).toBe(true);
+  });
+});

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

@@ -3,9 +3,20 @@ import {
   EXT_USER_DATA,
   type FeatureDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { fileRefDeleteHook, fileRefExportHook } from "./hooks/file-ref.userdata-hook";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { createFileRefDeleteHook, fileRefExportHook } from "./hooks/file-ref.userdata-hook";
 import { userDeleteHook, userExportHook } from "./hooks/user.userdata-hook";
 
+export interface UserDataRightsDefaultsOptions {
+  /**
+   * Wired into the fileRef delete-hook: on strategy="delete" the hook
+   * calls `storageProvider.delete(key)` per row before hard-deleting
+   * the row. Without it, file binaries leak on forget (Art. 17) — the
+   * hook logs a one-shot warning so misconfiguration stays visible.
+   */
+  readonly storageProvider?: FileStorageProvider;
+}
+
 // user-data-rights-defaults — Default-Hooks für die Core-Entities
 // `user` (S2.H1) und `fileRef` (S2.H2).
 //
@@ -23,7 +34,10 @@ import { userDeleteHook, userExportHook } from "./hooks/user.userdata-hook";
 // Pattern matched file-foundation + file-provider-s3 (separate Plugin-
 // Feature), nicht user/files schreiben ihre eigenen Hooks selbst weil
 // das circular-requires waere.
-export function createUserDataRightsDefaultsFeature(): FeatureDefinition {
+export function createUserDataRightsDefaultsFeature(
+  options: UserDataRightsDefaultsOptions = {},
+): FeatureDefinition {
+  const fileRefDeleteHook = createFileRefDeleteHook(options.storageProvider);
   return defineFeature("user-data-rights-defaults", (r) => {
     r.requires("user", "files", "user-data-rights");
 

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

@@ -1,6 +1,6 @@
 import { deleteMany, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
-import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { type FileStorageProvider, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 
 // userData-Hook fuer fileRef-entity (S2.H2).
 //
@@ -9,10 +9,9 @@ import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 // NICHT direkt — sie werden via signed-Download-URLs separat ins ZIP
 // gepackt (S2.U3 Export-Job-Pipeline orchestriert das).
 //
-// Delete-Hook entfernt FileRef-Zeile + Storage-Binary. Plan-Roadmap
-// docs/plans/datenschutz/storage-encryption.md hat das Subject-
-// Resolver-Pattern fuer File-Encryption als Sprint 4 — bis dahin:
-//   "delete":    Row hard-delete + storageProvider.delete() pro File
+// Delete-Hook entfernt FileRef-Zeile via factory
+// `createFileRefDeleteHook(storageProvider)`:
+//   "delete":    storageProvider.delete() pro File (best-effort) + Row hard-delete
 //   "anonymize": insertedById=null, Row + binary bleiben (FK-Refs
 //                koennen weiter zeigen; Personenbezug raus)
 //
@@ -22,12 +21,17 @@ import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 // idempotent, KEIN globaler Rollback — wenn ein File-Delete failt,
 // bleibt der User-Row trotzdem anonymisiert.
 //
-// Storage-Provider kommt aus dem App-Bootstrap (createBunServer-
-// options.files.storageProvider). Wir greifen darauf via ctx — der
-// Hook-ctx hat aktuell nur db/tenantId/userId, also fuer Storage-
-// Calls braucht es eine Erweiterung. S2.U3 Export-Job-Pipeline regelt
-// das (Job-ctx hat ctx.files.ref(key)). Hier lassen wir Storage-
-// Cleanup als TODO und faellen das in S2.U5 nochmal an.
+// `storageProvider` ist optional. App-Author wired es beim
+// Feature-Mount rein (`createUserDataRightsDefaultsFeature({
+// storageProvider })`). Ohne Provider macht der Hook row-only-delete,
+// die Bytes leaken — der Caller bekommt EINEN Warn beim ersten Lauf
+// pro Process, damit die Konfiguration sichtbar fehlerhaft ist.
+//
+// Caveat: hard-delete via deleteMany emittiert KEIN fileRef.deleted —
+// die storage-tracking-MSP dekrementiert nicht. Wenn die zu loeschenden
+// Files vorher nicht soft-deleted waren, bleibt `tenant_storage_usage`
+// inflated. Forget-Flows sind selten (per-User-Art.-17) und damit
+// bounded; ein executor.purge-API folgt mit dem trashed-files-GC.
 
 export const fileRefExportHook: UserDataExportHook = async (ctx) => {
   // isDeleted:false — soft-deleted (trashed) Files gehören nicht ins
@@ -76,22 +80,54 @@ export const fileRefExportHook: UserDataExportHook = async (ctx) => {
   };
 };
 
-export const fileRefDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
-  if (strategy === "delete") {
-    // Hard-delete der FileRef-Rows fuer diesen User in diesem Tenant.
-    // Storage-Binary-Cleanup folgt in S2.U5 wenn der Forget-Job-Ctx
-    // den Storage-Provider exposed.
-    await deleteMany(ctx.db, fileRefsTable, { tenantId: ctx.tenantId, insertedById: ctx.userId });
-  } else {
-    // anonymize: insertedById=null, FileRef + binary bleiben.
-    // Use-case: shared chat-Attachment in einem Multi-User-Channel —
-    // Author-Identifikation raus, Datei bleibt fuer andere User
-    // sichtbar.
-    await updateMany(
-      ctx.db,
-      fileRefsTable,
-      { insertedById: null },
-      { tenantId: ctx.tenantId, insertedById: ctx.userId },
-    );
-  }
-};
+let missingStorageWarned = false;
+
+export function createFileRefDeleteHook(
+  storageProvider: FileStorageProvider | undefined,
+): UserDataDeleteHook {
+  return async (ctx, strategy) => {
+    if (strategy === "delete") {
+      if (storageProvider) {
+        const rows = await selectMany(ctx.db, fileRefsTable, {
+          tenantId: ctx.tenantId,
+          insertedById: ctx.userId,
+        });
+        for (const row of rows) {
+          const key = (row as Record<string, unknown>)["storageKey"]; // @cast-boundary db-row
+          if (typeof key !== "string" || key.length === 0) continue;
+          try {
+            await storageProvider.delete(key);
+          } catch (err) {
+            // biome-ignore lint/suspicious/noConsole: operator-visibility for binary-cleanup-failure
+            console.warn(
+              `[user-data-rights-defaults:fileRef] storage delete failed key=${key} err=${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+        }
+      } else if (!missingStorageWarned) {
+        missingStorageWarned = true;
+        // biome-ignore lint/suspicious/noConsole: misconfiguration visibility — disk-leak in forget-flow
+        console.warn(
+          "[user-data-rights-defaults:fileRef] no storageProvider configured — file binaries are NOT deleted on forget. Pass createUserDataRightsDefaultsFeature({ storageProvider }) to fix.",
+        );
+      }
+      await deleteMany(ctx.db, fileRefsTable, { tenantId: ctx.tenantId, insertedById: ctx.userId });
+    } else {
+      // anonymize: insertedById=null, FileRef + binary bleiben.
+      // Use-case: shared chat-Attachment in einem Multi-User-Channel —
+      // Author-Identifikation raus, Datei bleibt fuer andere User
+      // sichtbar.
+      await updateMany(
+        ctx.db,
+        fileRefsTable,
+        { insertedById: null },
+        { tenantId: ctx.tenantId, insertedById: ctx.userId },
+      );
+    }
+  };
+}
+
+// Legacy export: storage-less hook for callers that haven't migrated.
+// Binaries are NOT cleaned up — disk leak. Migrate to
+// createUserDataRightsDefaultsFeature({ storageProvider }).
+export const fileRefDeleteHook: UserDataDeleteHook = createFileRefDeleteHook(undefined);