@cosmicdrift/kumiko-bundled-features 0.82.0 → 0.83.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.82.0",
+  "version": "0.83.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>",
@@ -85,11 +85,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.82.0",
-    "@cosmicdrift/kumiko-framework": "0.82.0",
-    "@cosmicdrift/kumiko-headless": "0.82.0",
-    "@cosmicdrift/kumiko-renderer": "0.82.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.82.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.83.0",
+    "@cosmicdrift/kumiko-framework": "0.83.0",
+    "@cosmicdrift/kumiko-headless": "0.83.0",
+    "@cosmicdrift/kumiko-renderer": "0.83.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.83.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/user-data-rights/__tests__/tenant-model-erasure.integration.test.ts

@@ -0,0 +1,201 @@
+// Configurable tenant-occupancy model for GDPR forget (Art. 17).
+//
+// A tenant-scoped contributor (e.g. credit) has no per-user column to anonymize,
+// so per-user erasure of tenant data is only safe when the tenant has exactly
+// one user. The app declares that via the `tenantModel` config; the forget
+// pipeline refines it per-tenant with a runtime sole-member check before handing
+// `ctx.tenantModel` to each delete-hook.
+//
+// This drives the REAL config resolution (appOverride → resolveAppTenantModel)
+// and the REAL forget pipeline (sole-member refinement → ctx.tenantModel →
+// contributor delete) — NOT a hand-set ctx, which would prove the hook's `if`
+// but not that the config string + system-scope resolution actually carry the
+// value (the failure mode that shipped the ctx.config export bug).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  EXT_USER_DATA,
+  SYSTEM_USER_ID,
+  type UserDataDeleteHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValueEntity } from "../../config/table";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature, userEntity } from "../../user";
+import { TENANT_MODEL_CONFIG_KEY } from "../constants";
+import { createUserDataRightsFeature } from "../feature";
+import { resolveAppTenantModel } from "../lib/resolve-tenant-model";
+import { runForgetCleanup } from "../run-forget-cleanup";
+import {
+  createForgetSeeders,
+  nowInstant,
+  READ_TENANT_MEMBERSHIPS_DDL,
+} from "./forget-test-helpers";
+
+const TENANT = "00000000-0000-4000-8000-0000000000c1";
+const FORGET_USER = "cccccccc-cccc-4ccc-8ccc-0000000000c1";
+const CO_MEMBER = "cccccccc-cccc-4ccc-8ccc-0000000000c2";
+const TABLE = "read_dsgvo_tenant_scoped";
+
+// Tenant-scoped contributor with NO per-user column — deletes by tenant only,
+// and ONLY when this tenant is effectively single-user (mirrors credit).
+const tenantScopedDeleteHook: UserDataDeleteHook = async (ctx) => {
+  if (ctx.tenantModel !== "single-user") return; // shared tenant: erasing would hit co-members
+  await asRawClient(ctx.db).unsafe(`DELETE FROM ${TABLE} WHERE tenant_id = $1`, [ctx.tenantId]);
+};
+
+const scopedEntity = createEntity({
+  table: TABLE,
+  fields: { name: createTextField({ required: true }) },
+});
+
+const contributorFeature = defineFeature("dsgvo-tenant-scoped", (r) => {
+  r.entity("tenant-scoped", scopedEntity);
+  r.useExtension(EXT_USER_DATA, "tenant-scoped", {
+    export: async () => null,
+    delete: tenantScopedDeleteHook,
+  });
+});
+
+let stack: TestStack;
+const seed = (db: unknown) =>
+  // biome-ignore lint/suspicious/noExplicitAny: dummy writer; this contributor has no binaries.
+  createForgetSeeders(db as any, { write: async () => {} });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createSessionsFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      createConfigFeature(),
+      createUserDataRightsFeature(),
+      contributorFeature,
+    ],
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
+  await unsafeCreateEntityTable(stack.db, configValueEntity);
+  await unsafeCreateEntityTable(stack.db, scopedEntity);
+  await createEventsTable(stack.db);
+  await asRawClient(stack.db).unsafe(READ_TENANT_MEMBERSHIPS_DDL);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetEventStore(stack);
+  await asRawClient(stack.db).unsafe(`DELETE FROM ${TABLE}`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM read_tenant_memberships`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM read_users`);
+});
+
+async function seedScopedRow(rowId: string): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${TABLE} (id, tenant_id, name) VALUES ($1, $2, 'loan')`,
+    [rowId, TENANT],
+  );
+}
+
+async function rowCount(): Promise<number> {
+  const rows = await asRawClient(stack.db).unsafe(`SELECT id FROM ${TABLE} WHERE tenant_id = $1`, [
+    TENANT,
+  ]);
+  return (rows as ReadonlyArray<unknown>).length;
+}
+
+describe("tenant-model config resolution (seam)", () => {
+  test("appOverride single-user resolves through the real config resolver", async () => {
+    const model = await resolveAppTenantModel({
+      registry: stack.registry,
+      configResolver: createConfigResolver({
+        appOverrides: new Map([[TENANT_MODEL_CONFIG_KEY, "single-user"]]),
+      }),
+      db: stack.db,
+      userId: SYSTEM_USER_ID,
+    });
+    expect(model).toBe("single-user");
+  });
+
+  test("no override falls back to the feature default (multi-user)", async () => {
+    const model = await resolveAppTenantModel({
+      registry: stack.registry,
+      configResolver: createConfigResolver({ appOverrides: new Map() }),
+      db: stack.db,
+      userId: SYSTEM_USER_ID,
+    });
+    expect(model).toBe("multi-user");
+  });
+});
+
+describe("forget pipeline honours the effective tenant model", () => {
+  test("single-user + sole member → tenant-scoped rows erased", async () => {
+    await seedScopedRow("dddddddd-dddd-4ddd-8ddd-0000000000c1");
+    await seed(stack.db).seedForgetUser(FORGET_USER);
+    await seed(stack.db).seedMembership(FORGET_USER, TENANT);
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: nowInstant(),
+      tenantModel: "single-user",
+    });
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.processedUserIds).toContain(FORGET_USER);
+    expect(await rowCount()).toBe(0);
+  });
+
+  test("single-user but a co-member exists → rows preserved (sole-member guard)", async () => {
+    await seedScopedRow("dddddddd-dddd-4ddd-8ddd-0000000000c2");
+    await seed(stack.db).seedForgetUser(FORGET_USER);
+    await seed(stack.db).seedMembership(FORGET_USER, TENANT);
+    await seed(stack.db).seedMembership(CO_MEMBER, TENANT);
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: nowInstant(),
+      tenantModel: "single-user",
+    });
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.processedUserIds).toContain(FORGET_USER);
+    // A stray invite made the config's claim false at runtime — the co-member's
+    // loan book must survive even though the user was forgotten.
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("multi-user → tenant-scoped rows preserved", async () => {
+    await seedScopedRow("dddddddd-dddd-4ddd-8ddd-0000000000c3");
+    await seed(stack.db).seedForgetUser(FORGET_USER);
+    await seed(stack.db).seedMembership(FORGET_USER, TENANT);
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: nowInstant(),
+      tenantModel: "multi-user",
+    });
+
+    expect(result.errors).toHaveLength(0);
+    expect(await rowCount()).toBe(1);
+  });
+});

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

@@ -16,6 +16,13 @@ export const UserDataRightsQueries = {
   downloadByJob: "user-data-rights:query:download-by-job",
 } as const;
 
+// App-level config: tenant-occupancy model. "single-user" tells the forget
+// pipeline that each tenant has exactly one user, so tenant-scoped contributors
+// (e.g. credit) may erase the tenant's data as that user's personal data.
+// Default "multi-user" (declared in feature.ts). Apps set it via appOverrides:
+// `overrides.set(TENANT_MODEL_CONFIG_KEY, "single-user")`.
+export const TENANT_MODEL_CONFIG_KEY = "user-data-rights:config:tenant-model" as const;
+
 export const UserDataRightsHandlers = {
   requestExport: "user-data-rights:write:request-export",
   requestDeletion: "user-data-rights:write:request-deletion",

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

@@ -1,4 +1,5 @@
 import {
+  createSystemConfig,
   defineFeature,
   EXT_USER_DATA,
   type FeatureDefinition,
@@ -24,6 +25,7 @@ import {
 import { requestExportWrite } from "./handlers/request-export.write";
 import { restrictAccountWrite } from "./handlers/restrict-account.write";
 import { createRunForgetCleanupHandler } from "./handlers/run-forget-cleanup.write";
+import { resolveAppTenantModel } from "./lib/resolve-tenant-model";
 import { makeTenantStorageProviderResolver } from "./lib/storage-provider-resolver";
 import {
   runExportJobs,
@@ -126,6 +128,21 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
 
     r.extendsRegistrar(EXT_USER_DATA, {});
 
+    // App-level tenant-occupancy model. Default "multi-user" → tenant-scoped
+    // contributors (e.g. credit) NEVER erase tenant data on a per-user forget
+    // (would harm co-members). An app with one user per tenant sets this to
+    // "single-user" via appOverrides (TENANT_MODEL_CONFIG_KEY) so the forget
+    // pipeline may erase the tenant's data as that user's personal data — still
+    // gated by a runtime sole-member check in run-forget-cleanup.
+    r.config({
+      keys: {
+        tenantModel: createSystemConfig("select", {
+          default: "multi-user",
+          options: ["single-user", "multi-user"],
+        }),
+      },
+    });
+
     // S2.U3 Atom 1b — ExportJob-Lifecycle-Entity.
     r.entity("export-job", exportJobEntity);
 
@@ -321,10 +338,17 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
         const forgetUserId = ctx._userId ?? SYSTEM_USER_ID;
         const forgetDb = ctx.db as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator
+        const tenantModel = await resolveAppTenantModel({
+          registry: ctx.registry,
+          configResolver: ctx.configResolver,
+          db: forgetDb,
+          userId: forgetUserId,
+        });
         await runForgetCleanup({
           db: forgetDb,
           registry: ctx.registry,
           now: T.Now.instant(),
+          tenantModel,
           // Same per-tenant provider resolution as the export cron — forget
           // deletes binaries from the store upload + export use.
           buildStorageProvider: makeTenantStorageProviderResolver({

package/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -15,6 +15,7 @@ import { access, defineWriteHandler, SYSTEM_USER_ID } from "@cosmicdrift/kumiko-
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { z } from "zod";
+import { resolveAppTenantModel } from "../lib/resolve-tenant-model";
 import { makeTenantStorageProviderResolver } from "../lib/storage-provider-resolver";
 import { runForgetCleanup, type SendDeletionExecutedEmailFn } from "../run-forget-cleanup";
 
@@ -45,10 +46,17 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
       // them, so a row-only delete here would permanently leak the binaries.
       // Resolve through the same file-foundation path the cron uses.
       const forgetDb = ctx.db.raw as DbConnection; // @cast-boundary db-operator: config reads tolerate the outer tx
+      const tenantModel = await resolveAppTenantModel({
+        registry: ctx.registry,
+        configResolver: ctx.configResolver,
+        db: forgetDb,
+        userId: ctx._userId ?? SYSTEM_USER_ID,
+      });
       const result = await runForgetCleanup({
         db: ctx.db.raw,
         registry: ctx.registry,
         now: T.Now.instant(),
+        tenantModel,
         buildStorageProvider: makeTenantStorageProviderResolver({
           registry: ctx.registry,
           configResolver: ctx.configResolver,

package/src/user-data-rights/lib/resolve-tenant-model.ts

@@ -0,0 +1,34 @@
+// Resolves the app-level `tenantModel` config once for a forget run. The
+// forget cron + manual handler both call this and pass the scalar into the
+// pure pipeline (which refines it per-tenant with a sole-member check). The key
+// is system-scoped, so the tenantId used for resolution is irrelevant —
+// SYSTEM_TENANT_ID reads the system/appOverride value.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ConfigResolver,
+  type Registry,
+  SYSTEM_TENANT_ID,
+  type TenantUserModel,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createConfigAccessor } from "../../config";
+import { TENANT_MODEL_CONFIG_KEY } from "../constants";
+
+export async function resolveAppTenantModel(args: {
+  readonly registry: Registry;
+  readonly configResolver: ConfigResolver | undefined;
+  readonly db: DbConnection;
+  readonly userId: string;
+}): Promise<TenantUserModel> {
+  // No resolver (e.g. a unit context) → safe default: never erase tenant-scoped data.
+  if (!args.configResolver) return "multi-user";
+  const config = createConfigAccessor(
+    args.registry,
+    args.configResolver,
+    SYSTEM_TENANT_ID,
+    args.userId,
+    args.db,
+  );
+  const raw = await config(TENANT_MODEL_CONFIG_KEY);
+  return raw === "single-user" ? "single-user" : "multi-user";
+}

package/src/user-data-rights/run-forget-cleanup.ts

@@ -39,6 +39,7 @@ import {
   EXT_USER_DATA_ORDER,
   type Registry,
   type TenantId,
+  type TenantUserModel,
   type UserDataDeleteHook,
   type UserDataDeleteStrategy,
   type UserDataStorageProvider,
@@ -96,6 +97,15 @@ export interface RunForgetCleanupArgs {
   readonly buildStorageProvider?: (
     tenantId: TenantId,
   ) => Promise<UserDataStorageProvider | undefined>;
+
+  /**
+   * App-level tenant-occupancy model (resolved from the `tenantModel` config by
+   * the cron/handler). The pipeline refines it PER TENANT with a sole-member
+   * check before handing `tenantModel` to each delete-hook, so tenant-scoped
+   * erasure only happens where it's actually safe. Omitted → `"multi-user"`
+   * (no tenant-scoped erasure).
+   */
+  readonly tenantModel?: TenantUserModel;
 }
 
 export interface ForgetCleanupError {
@@ -131,6 +141,7 @@ export async function runForgetCleanup(
   args: RunForgetCleanupArgs,
 ): Promise<RunForgetCleanupResult> {
   const { db, registry, now, sendDeletionExecutedEmail, buildStorageProvider } = args;
+  const appTenantModel: TenantUserModel = args.tenantModel ?? "multi-user";
 
   // Step 1: Find users with expired grace period.
   const dueUsers = await selectUsersDueForForgetCleanup(
@@ -173,6 +184,7 @@ export async function runForgetCleanup(
       userId: user.id,
       hookEntries,
       buildStorageProvider,
+      appTenantModel,
     });
     hookCallsAttempted += userResult.hookCallsAttempted;
     errors.push(...userResult.errors);
@@ -229,8 +241,9 @@ async function processUser(args: {
   userId: string;
   hookEntries: readonly HookEntry[];
   buildStorageProvider?: (tenantId: TenantId) => Promise<UserDataStorageProvider | undefined>;
+  appTenantModel: TenantUserModel;
 }): Promise<ProcessUserResult> {
-  const { db, registry, userId, hookEntries, buildStorageProvider } = args;
+  const { db, registry, userId, hookEntries, buildStorageProvider, appTenantModel } = args;
   const errors: ForgetCleanupError[] = [];
   let hookCallsAttempted = 0;
 
@@ -276,6 +289,10 @@ async function processUser(args: {
     await runInSubTransaction(db, async (tx) => {
       for (const tenantId of tenantList) {
         currentTenantId = tenantId;
+        // Refine the app-level model to THIS tenant: "single-user" only if the
+        // tenant truly has one member, so a stray invite can't let a per-user
+        // forget erase a co-member's tenant-scoped data (money-path safety).
+        const tenantModel = await resolveEffectiveTenantModel(tx, tenantId, appTenantModel);
         for (const entry of hookEntries) {
           currentEntityName = entry.entityName;
           const policy = await resolveRetentionPolicyForTenant({
@@ -287,7 +304,10 @@ async function processUser(args: {
           const strategy = policyToStrategy(policy.policy?.strategy ?? null);
 
           hookCallsAttempted++;
-          await entry.deleteHook({ db: tx, tenantId, userId, buildStorageProvider }, strategy);
+          await entry.deleteHook(
+            { db: tx, tenantId, userId, buildStorageProvider, tenantModel },
+            strategy,
+          );
         }
       }
 
@@ -362,6 +382,21 @@ async function runInSubTransaction(
 // User-Row und ignorieren tenantId.
 const SYSTEM_TENANT_ID_FOR_ORPHANS = "00000000-0000-0000-0000-000000000000" as TenantId;
 
+// "single-user" requires BOTH the app config AND a runtime sole-member check —
+// the config asserts the deployment model, the count guards against a stray
+// invite that would make a per-user forget delete a co-member's tenant-scoped
+// data. Only queried when the app opted into "single-user" (multi-user apps
+// never reach the destructive path, so no extra query for them).
+async function resolveEffectiveTenantModel(
+  db: DbRunner,
+  tenantId: TenantId,
+  appTenantModel: TenantUserModel,
+): Promise<TenantUserModel> {
+  if (appTenantModel !== "single-user") return "multi-user";
+  const members = await selectMany<{ userId: string }>(db, tenantMembershipsTable, { tenantId });
+  return members.length === 1 ? "single-user" : "multi-user";
+}
+
 // Mapping retention.strategy → user-data-rights.UserDataDeleteStrategy.
 //   - "anonymize" / "blockDelete" → "anonymize" (Aufbewahrungs-Pflicht
 //     blockDelete: Daten muessen physisch bleiben, nur Personen-Bezug raus)