@cosmicdrift/kumiko-bundled-features 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.25.0",
+  "version": "0.26.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>",

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

@@ -1,6 +1,11 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { asRawClient, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  asRawClient,
+  insertOne,
+  selectMany,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -204,27 +209,86 @@ describe("POST /auth/verify-email", () => {
   });
 
   test("verify that fails before the write is retryable (burn released on failure)", async () => {
-    // Symmetric to the reset-password retry test: if the confirm-flow
-    // fails AFTER burning (here: no memberships → empty tenantOrder),
-    // the finally-block in runConfirmTokenFlow releases the burn so
-    // the user can click the same link again once ops restores state.
+    // Symmetric to the reset-password retry test: if the confirm-flow fails
+    // AFTER burning, the finally-block in runConfirmTokenFlow releases the
+    // burn so the user can click the same link again once ops restores state.
+    //
+    // Trigger: delete the user READ-MODEL row (kumiko_events untouched) →
+    // loadValidatedUser returns null after the burn → invalidToken + unburn.
+    // Re-insert the same row verbatim → retry with the SAME token succeeds.
+    //
+    // (Membership-deletion no longer fails: the stream lives in
+    // systemAdmin.tenantId and is recovered with zero memberships — see the
+    // zero-membership-sysadmin test below.)
     const seed = await seedUser({ email: "retry@example.com", password: "pw-retry-1234" });
     const { token } = signVerificationToken(seed.id, 60, verifySecret);
 
-    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+    const userRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    if (!userRow) throw new Error("seeded user row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}" WHERE id = $1`, [
+      seed.id,
+    ]);
+
     const firstAttempt = await post("/api/auth/verify-email", { token });
     expect(firstAttempt.status).toBe(422);
 
-    await seedTenantMembership(stack.db, {
-      userId: seed.id,
-      tenantId: seed.tenantId,
-      roles: ["User"],
-    });
+    await insertOne(stack.db, userTable, userRow);
 
     const secondAttempt = await post("/api/auth/verify-email", { token });
     expect(secondAttempt.status).toBe(200);
   });
 
+  test("zero-membership sysadmin can still verify (stream recovered without any membership)", async () => {
+    // 205#1: a systemScope user whose stream lives in systemAdmin.tenantId
+    // (…0001) but who holds NO membership must still resolve. The stream-
+    // tenant recovery runs BEFORE the empty-membership check, so verify
+    // targets …0001 and lands instead of collapsing to invalid_token.
+    const seed = await seedUser({ email: "lonely-admin@example.com", password: "pw-lonely-1234" });
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    const streamRows = (await asRawClient(stack.db).unsafe(
+      `SELECT "tenant_id" FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = 'user' ORDER BY "version" LIMIT 1`,
+      [seed.id],
+    )) as ReadonlyArray<{ tenant_id: string }>;
+    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+
+    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);
+  });
+
+  test("direct-inserted user with no stream + no membership → 422 (recovery stays bounded)", async () => {
+    // 205#1 "strikt sicher" boundary: a user inserted straight into the read
+    // model (no create-event → no event stream) with no membership has
+    // nothing to recover → invalidToken. Proves the fix only gains "empty
+    // memberships + recoverable stream", never blanket-opens zero-membership.
+    // Build a fully-populated user row with NO event stream: seed a normal
+    // user (gets all NOT-NULL columns), capture its row, then re-key it to a
+    // fresh id + email. getAggregateStreamTenant(orphanId) finds no events
+    // (the stream lives under the original id), and no membership is seeded
+    // → tenantOrder is empty.
+    const donor = await seedUser({ email: "donor@example.com", password: "donor-pw-1234" });
+    const donorRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === donor.id);
+    if (!donorRow) throw new Error("donor row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    const orphanId = "00000000-0000-4000-8000-0000000000ff";
+    await insertOne(stack.db, userTable, {
+      ...donorRow,
+      id: orphanId,
+      email: "orphan@example.com",
+    });
+
+    const { token } = signVerificationToken(orphanId, 60, verifySecret);
+    const res = await post("/api/auth/verify-email", { token });
+    expect(res.status).toBe(422);
+    const body = await res.json();
+    expect(body.error?.details?.reason).toBe(AuthErrors.invalidVerificationToken);
+  });
+
   test("cross-purpose burn isolation: consuming a reset-token doesn't block a verify-token for the same user+expiry", async () => {
     // The burn-store key includes purpose ("reset" vs "verify"). Tokens
     // signed with the SAME userId + expiresAtMs but different purpose

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

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -251,31 +251,39 @@ describe("POST /auth/reset-password", () => {
 
   test("reset that fails before the write is retryable (burn is released on failure)", async () => {
     // The burn marker goes down BEFORE the state change so a racing replay
-    // can't slip through. But if the state change itself fails — e.g. no
-    // memberships in the row, every tenant stream rejected, DB error —
-    // the token was never actually consumed. The handler releases the
-    // burn in those branches so the user can click the link again
-    // without hitting a stuck "already-used".
+    // can't slip through. But if the state change itself fails — DB error,
+    // user-row vanished, every tenant stream rejected — the token was never
+    // actually consumed. The handler releases the burn in those branches so
+    // the user can click the link again once ops restores state.
     //
-    // Repro: drop the user's membership → tenantOrder is empty →
-    // invalidToken + unburn. Re-insert membership → second attempt
-    // with the same token succeeds (proves the burn was released).
+    // Repro: delete the user READ-MODEL row (kumiko_events untouched) →
+    // loadValidatedUser returns null AFTER the burn → invalidToken + unburn.
+    // Re-insert the same row verbatim (restores version → optimistic write
+    // still matches the untouched event stream) → second attempt with the
+    // SAME token succeeds, proving the burn was released.
+    //
+    // (Deleting the membership no longer works as a failure trigger: the
+    // user aggregate stream lives in systemAdmin.tenantId and is recovered
+    // by resolveStreamTenants even with zero memberships — see the
+    // zero-membership-sysadmin test below.)
     const seed = await seedUser({ email: "retry@example.com", password: "pw-retry-1234" });
     const { token } = signResetToken(seed.id, 15, resetSecret);
 
-    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+    const userRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    if (!userRow) throw new Error("seeded user row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}" WHERE id = $1`, [
+      seed.id,
+    ]);
+
     const firstAttempt = await post("/api/auth/reset-password", {
       token,
       newPassword: "never-lands-1234",
     });
     expect(firstAttempt.status).toBe(422);
 
-    // Re-insert the membership. Same userId, same token still valid.
-    await seedTenantMembership(stack.db, {
-      userId: seed.id,
-      tenantId: seed.tenantId,
-      roles: ["User"],
-    });
+    // Re-insert the captured row verbatim. Same userId, same version, same
+    // token still valid.
+    await insertOne(stack.db, userTable, userRow);
 
     const secondAttempt = await post("/api/auth/reset-password", {
       token,
@@ -284,6 +292,68 @@ describe("POST /auth/reset-password", () => {
     expect(secondAttempt.status).toBe(200);
   });
 
+  test("zero-membership sysadmin can still reset (stream recovered without any membership)", async () => {
+    // 205#1: a systemScope user whose stream lives in systemAdmin.tenantId
+    // (…0001) but who holds NO membership must still resolve. The stream-
+    // tenant recovery in resolveStreamTenants runs BEFORE the empty-
+    // membership check, so the reset targets …0001 and lands — instead of
+    // collapsing to invalid_token. Mirrors change-password's unconditional
+    // recovery.
+    const seed = await seedUser({ email: "lonely-admin@example.com", password: "pw-old-lonely!" });
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    // Confirm the stream tenant the recovery must find: the user aggregate
+    // was created via systemAdmin, so its stream lives in …0001.
+    const streamRows = (await asRawClient(stack.db).unsafe(
+      `SELECT "tenant_id" FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = 'user' ORDER BY "version" LIMIT 1`,
+      [seed.id],
+    )) as ReadonlyArray<{ tenant_id: string }>;
+    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+
+    const { token } = signResetToken(seed.id, 15, resetSecret);
+    const res = await post("/api/auth/reset-password", {
+      token,
+      newPassword: "pw-new-lonely-1234",
+    });
+    expect(res.status).toBe(200);
+
+    const row = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    expect(await verifyPassword(row?.["passwordHash"] as string, "pw-new-lonely-1234")).toBe(true);
+  });
+
+  test("direct-inserted user with no stream + no membership → 422 (recovery stays bounded)", async () => {
+    // 205#1 "strikt sicher" boundary: a user inserted straight into the read
+    // model (no create-event → no event stream) with no membership has
+    // nothing to recover. resolveStreamTenants returns [] → invalidToken.
+    // Proves the fix only gains "empty memberships + recoverable stream",
+    // never blanket-opens zero-membership.
+    // Build a fully-populated user row with NO event stream: seed a normal
+    // user (gets all NOT-NULL columns), capture its row, then re-key it to a
+    // fresh id + email. getAggregateStreamTenant(orphanId) finds no events
+    // (the stream lives under the original id), and no membership is seeded
+    // → tenantOrder is empty.
+    const donor = await seedUser({ email: "donor@example.com", password: "donor-pw-1234" });
+    const donorRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === donor.id);
+    if (!donorRow) throw new Error("donor row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    const orphanId = "00000000-0000-4000-8000-0000000000ff";
+    await insertOne(stack.db, userTable, {
+      ...donorRow,
+      id: orphanId,
+      email: "orphan@example.com",
+    });
+
+    const { token } = signResetToken(orphanId, 15, resetSecret);
+    const res = await post("/api/auth/reset-password", {
+      token,
+      newPassword: "should-not-land-1234",
+    });
+    expect(res.status).toBe(422);
+    const body = await res.json();
+    expect(body.error?.details?.reason).toBe(AuthErrors.invalidResetToken);
+  });
+
   test("replayed reset-token → 422 invalid_reset_token (single-use burn)", async () => {
     // Reset tokens are single-use: the handler burns them in Redis via
     // SETNX before the state change. First click wins; replay within TTL

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

@@ -141,11 +141,14 @@ async function loadValidatedUser(
   return { ...me, version: me.version };
 }
 
-// Loads the user's memberships and returns a prioritised tenant list.
-// Empty when the user has no memberships at all — the caller treats that
-// as invalid_token (a user without memberships can't own a usable auth
-// flow anyway, and a deterministic early-return is cleaner than
-// discovering it at write time).
+// Loads the user's memberships and returns a prioritised tenant list, with the
+// aggregate's real stream tenant recovered from the event log prepended.
+//
+// Empty only when the user has NO memberships AND no recoverable stream tenant
+// — the caller treats that as invalid_token. A zero-membership systemScope user
+// whose stream lives outside any membership (a platform operator seeded under a
+// fixture/SYSTEM tenant) still resolves, because the stream-tenant lookup runs
+// before the empty check rather than being short-circuited by it.
 async function resolveStreamTenants(
   ctx: HandlerContext,
   systemUser: SessionUser,
@@ -155,15 +158,16 @@ async function resolveStreamTenants(
     userId: me.id,
   })) as Array<{ tenantId: TenantId }>; // @cast-boundary db-runner
   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.
+  // tenant from the event log and try it first; memberships stay as fallback.
+  // Pulled BEFORE the empty-membership check so a zero-membership operator whose
+  // stream lives in SYSTEM_TENANT is recoverable instead of collapsing to
+  // invalid_token — mirrors change-password.write.ts's unconditional recovery.
   const streamTenant = await getAggregateStreamTenant(ctx.db.raw, me.id, USER_FEATURE);
   if (streamTenant && !ordered.includes(streamTenant)) {
     return [streamTenant, ...ordered];

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

@@ -1,22 +1,33 @@
-// T1.5c — user-data-rights wiring for custom-fields.
+// T1.5c — user-data-rights wiring for custom-fields, exercised through the
+// REAL export/forget runners (runUserExport / runForgetCleanup), not by
+// calling the registered hooks in isolation.
 //
-// Verifies the full DSGVO loop for custom-field values on a user-owned
-// host entity:
+// What the real runners prove that direct hook calls cannot:
 //
-//   * Export (Art. 15+20): every row owned by the user contributes its
-//     customFields jsonb into the user's export bundle under
-//     `<entity>.customFields`.
+//   * runUserExport actually picks up the custom-fields export hook from the
+//     registry and folds its snippet into the user's cross-tenant bundle.
 //
-//   * Forget strategy=anonymize (Art. 17 with retention obligation):
-//     sensitive customFields keys are stripped from the jsonb; non-
-//     sensitive keys stay so co-tenants / co-authors keep useful data.
+//   * runForgetCleanup fires BOTH the host EXT_USER_DATA hook (owner-nulling
+//     anonymize) AND the custom-fields strip hook, in the order their declared
+//     `order` demands. The strip declares order -100 so it redacts sensitive
+//     jsonb keyed on `inserted_by_id` BEFORE the host hook nulls that column.
+//     If the ordering regressed, the host hook would null inserted_by_id first,
+//     the strip's `WHERE inserted_by_id = userId` would match 0 rows, and
+//     sensitive PII would silently survive (Art. 17 violation). Calling the
+//     hooks by hand never exercised this interaction.
 //
-//   * Forget strategy=delete: no-op — the host entity's own user-data-
-//     rights hook handles the row delete, jsonb travels with the row.
+//   * The anonymize-vs-delete strategy comes from the data-retention policy:
+//     no override → strategy "delete" (custom-fields strip is a no-op, host
+//     deletes the row); per-tenant anonymize override → strategy "anonymize"
+//     (strip runs, host nulls the owner).
 
 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 { asRawClient, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createEntityExecutor,
@@ -32,19 +43,28 @@ import {
   resetEventStore,
   setupTestStack,
   type TestStack,
+  TestUsers,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { z } from "zod";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
-import { createDataRetentionFeature } from "../../data-retention";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { tenantRetentionOverrideTable } from "../../data-retention/schema/tenant-retention-override";
 import { createSessionsFeature } from "../../sessions";
-import { createUserFeature, userEntity } from "../../user";
+import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
 import { createUserDataRightsFeature } from "../../user-data-rights";
+import { runForgetCleanup } from "../../user-data-rights/run-forget-cleanup";
+import { runUserExport } from "../../user-data-rights/run-user-export";
 import { fieldDefinitionEntity } from "../entity";
 import { createCustomFieldsFeature } from "../feature";
 import { customFieldsField, wireCustomFieldsFor } from "../wire-for-entity";
 import { wireCustomFieldsUserDataRightsFor } from "../wire-user-data-rights";
 
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+const NOW = (): Instant => getTemporal().Now.instant();
+const PAST = (): Instant => getTemporal().Instant.fromEpochMilliseconds(Date.now() - 60_000);
+
 const propertyEntity = createEntity({
   table: "read_t15c_properties",
   fields: {
@@ -55,15 +75,12 @@ const propertyEntity = createEntity({
 const propertyTable = buildEntityTable("property", propertyEntity);
 
 // Host entity gets its own EXT_USER_DATA-registration too — that's the
-// canonical setup (host bundle handles row-anonymize/delete, custom-fields
-// adds its strip-sensitive-jsonb layer on top). Both hooks fire in the
-// same cleanup-run.
+// canonical setup. The host's anonymize hook NULLS inserted_by_id (default
+// order 0); the custom-fields strip (order -100) must run first. Both fire in
+// the same runForgetCleanup sub-transaction.
 const hostExportHook: UserDataExportHook = async (ctx) => {
   const rows = await asRawClient(ctx.db).unsafe(
-    `
-    SELECT id, name FROM read_t15c_properties
-    WHERE inserted_by_id = $1 AND tenant_id = $2
-  `,
+    `SELECT id, name FROM read_t15c_properties WHERE inserted_by_id = $1 AND tenant_id = $2`,
     [ctx.userId, ctx.tenantId],
   );
   const list = rows as ReadonlyArray<Record<string, unknown>>;
@@ -77,19 +94,15 @@ const hostExportHook: UserDataExportHook = async (ctx) => {
 const hostDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
   if (strategy === "delete") {
     await asRawClient(ctx.db).unsafe(
-      `
-      DELETE FROM read_t15c_properties
-      WHERE inserted_by_id = $1 AND tenant_id = $2
-    `,
+      `DELETE FROM read_t15c_properties WHERE inserted_by_id = $1 AND tenant_id = $2`,
       [ctx.userId, ctx.tenantId],
     );
   } else {
-    // anonymize: clear owner, keep row + non-sensitive customFields
+    // anonymize: clear owner, keep row + non-sensitive customFields. Runs AFTER
+    // the custom-fields strip (order -100 < 0) — if it ran first, the strip's
+    // owner-keyed WHERE would match nothing.
     await asRawClient(ctx.db).unsafe(
-      `
-      UPDATE read_t15c_properties SET inserted_by_id = NULL
-      WHERE inserted_by_id = $1 AND tenant_id = $2
-    `,
+      `UPDATE read_t15c_properties SET inserted_by_id = NULL WHERE inserted_by_id = $1 AND tenant_id = $2`,
       [ctx.userId, ctx.tenantId],
     );
   }
@@ -125,8 +138,10 @@ const propertyFeature = defineFeature("property-t15c", (r) => {
 
 const customFieldsFeature = createCustomFieldsFeature();
 const admin = createTestUser({ id: 1, roles: ["TenantAdmin"] });
+const TENANT = admin.tenantId;
 
 let stack: TestStack;
+let overrideExecutor: ReturnType<typeof createEventStoreExecutor>;
 
 beforeAll(async () => {
   stack = await setupTestStack({
@@ -143,7 +158,34 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, userEntity);
   await unsafeCreateEntityTable(stack.db, fieldDefinitionEntity);
   await unsafeCreateEntityTable(stack.db, propertyEntity);
+  await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
   await createEventsTable(stack.db);
+
+  // runForgetCleanup + runUserExport iterate the user's memberships. Provide a
+  // minimal membership read-model (same shape the user-data-rights suite uses).
+  await asRawClient(stack.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)
+    )
+  `);
+
+  overrideExecutor = createEventStoreExecutor(
+    tenantRetentionOverrideTable,
+    tenantRetentionOverrideEntity,
+    { entityName: "tenant-retention-override" },
+  );
 });
 
 afterAll(async () => {
@@ -154,6 +196,9 @@ beforeEach(async () => {
   await resetEventStore(stack);
   await asRawClient(stack.db).unsafe(`DELETE FROM read_t15c_properties`);
   await asRawClient(stack.db).unsafe(`DELETE FROM read_custom_field_definitions`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM read_tenant_memberships`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantRetentionOverrideTable.tableName}"`);
 });
 
 async function defineField(fieldKey: string, serializedField: Record<string, unknown>) {
@@ -185,43 +230,78 @@ async function setField(entityId: string, fieldKey: string, value: unknown) {
 
 async function readRow(id: string): Promise<Record<string, unknown> | undefined> {
   const rows = await asRawClient(stack.db).unsafe(
-    `SELECT id, custom_fields FROM read_t15c_properties WHERE id = $1`,
+    `SELECT id, custom_fields, inserted_by_id FROM read_t15c_properties WHERE id = $1`,
     [id],
   );
   const list = rows as ReadonlyArray<Record<string, unknown>>;
   return list[0];
 }
 
-async function callExportHook(userId: string, tenantId: string) {
-  const usages = stack.registry.getExtensionUsages(EXT_USER_DATA);
-  const customFieldsUsage = usages.find(
-    (u) =>
-      u.entityName === "property" &&
-      (u.options as { export?: unknown })?.export &&
-      u.options !== undefined &&
-      (u.options as Record<string, unknown>)["export"] !== hostExportHook,
+// Seed the acting admin as a normal active user with a membership in TENANT so
+// the export runner iterates their data. Status active = NOT picked up by
+// runForgetCleanup.
+async function seedActiveUserWithMembership(): Promise<void> {
+  await insertOne(stack.db, userTable, {
+    id: admin.id,
+    tenantId: TENANT,
+    email: `admin@example.com`,
+    passwordHash: "hashed",
+    displayName: "Admin",
+    locale: "de",
+    emailVerified: true,
+    roles: '["TenantAdmin"]',
+    status: USER_STATUS.Active,
+  });
+  await seedMembership();
+}
+
+// Seed the acting admin as DeletionRequested + grace expired so
+// runForgetCleanup picks them up, with a membership in TENANT.
+async function seedForgetUserWithMembership(): Promise<void> {
+  await insertOne(stack.db, userTable, {
+    id: admin.id,
+    tenantId: TENANT,
+    email: `admin@example.com`,
+    passwordHash: "hashed",
+    displayName: "Admin",
+    locale: "de",
+    emailVerified: true,
+    roles: '["TenantAdmin"]',
+    status: USER_STATUS.DeletionRequested,
+    gracePeriodEnd: PAST(),
+  });
+  await seedMembership();
+}
+
+async function seedMembership(): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
+     VALUES ($1, $2, '["TenantAdmin"]') ON CONFLICT (user_id, tenant_id) DO NOTHING`,
+    [TENANT, admin.id],
   );
-  if (!customFieldsUsage) throw new Error("custom-fields user-data-rights export hook not found");
-  const hook = (customFieldsUsage.options as { export: UserDataExportHook }).export;
-  return hook({ db: stack.db, tenantId, userId });
 }
 
-async function callDeleteHook(userId: string, tenantId: string, strategy: "anonymize" | "delete") {
-  const usages = stack.registry.getExtensionUsages(EXT_USER_DATA);
-  const customFieldsUsage = usages.find(
-    (u) =>
-      u.entityName === "property" &&
-      (u.options as { delete?: unknown })?.delete &&
-      u.options !== undefined &&
-      (u.options as Record<string, unknown>)["delete"] !== hostDeleteHook,
+// Set a per-tenant retention override for the property entity through the same
+// event-store path the forget resolver reads — no test-only shortcut.
+async function seedPropertyAnonymizeOverride(): Promise<void> {
+  const by = { ...TestUsers.systemAdmin, tenantId: TENANT };
+  const result = await overrideExecutor.create(
+    {
+      entityName: "property",
+      config: JSON.stringify({ keepFor: "30d", strategy: "anonymize" }),
+      reason: "test",
+      tenantId: TENANT,
+    },
+    by,
+    createTenantDb(stack.db, TENANT, "system"),
   );
-  if (!customFieldsUsage) throw new Error("custom-fields user-data-rights delete hook not found");
-  const hook = (customFieldsUsage.options as { delete: UserDataDeleteHook }).delete;
-  return hook({ db: stack.db, tenantId, userId }, strategy);
+  if (!result.isSuccess)
+    throw new Error(`seedPropertyAnonymizeOverride failed: ${JSON.stringify(result)}`);
 }
 
-describe("T1.5c: user-data-rights wiring for custom-fields", () => {
-  test("export: customFields jsonb travels into the user's export snippet", async () => {
+describe("T1.5c: custom-fields user-data-rights through the real runners", () => {
+  test("export: customFields jsonb lands in the user's export bundle", async () => {
+    await seedActiveUserWithMembership();
     const propertyId = "11111111-1111-4000-8000-000000000001";
     await defineField("email", { type: "text", sensitive: true });
     await defineField("vipFlag", { type: "boolean" });
@@ -230,17 +310,27 @@ describe("T1.5c: user-data-rights wiring for custom-fields", () => {
     await setField(propertyId, "vipFlag", true);
     await stack.eventDispatcher?.runOnce();
 
-    const snippet = await callExportHook(String(admin.id), admin.tenantId);
-    expect(snippet).not.toBeNull();
-    expect(snippet?.entity).toBe("property.customFields");
-    expect(snippet?.rows).toHaveLength(1);
-    expect(snippet?.rows[0]?.["customFields"]).toMatchObject({
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: admin.id,
+      now: NOW(),
+    });
+
+    const tenantSection = bundle.tenants.find((t) => t.tenantId === TENANT);
+    expect(tenantSection).toBeDefined();
+    const cfSnippet = tenantSection?.entities.find((e) => e.entity === "property.customFields");
+    expect(cfSnippet).toBeDefined();
+    expect(cfSnippet?.rows).toHaveLength(1);
+    expect(cfSnippet?.rows[0]?.["customFields"]).toMatchObject({
       email: "alice@example.com",
       vipFlag: true,
     });
   });
 
-  test("forget anonymize: sensitive keys stripped, non-sensitive keys kept", async () => {
+  test("forget anonymize: strip runs BEFORE host owner-nulling → sensitive key gone, non-sensitive kept", async () => {
+    await seedForgetUserWithMembership();
+    await seedPropertyAnonymizeOverride();
     const propertyId = "22222222-2222-4000-8000-000000000002";
     await defineField("email", { type: "text", sensitive: true });
     await defineField("vipFlag", { type: "boolean" });
@@ -249,50 +339,81 @@ describe("T1.5c: user-data-rights wiring for custom-fields", () => {
     await setField(propertyId, "vipFlag", true);
     await stack.eventDispatcher?.runOnce();
 
-    await callDeleteHook(String(admin.id), admin.tenantId, "anonymize");
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: NOW(),
+    });
+    expect(result.processedUserIds).toContain(admin.id);
+    expect(result.errors).toHaveLength(0);
 
     const row = await readRow(propertyId);
+    // Host hook ran (owner nulled), and the strip ran BEFORE it (sensitive
+    // key removed despite the owner-keyed WHERE — proof of the -100 ordering).
+    expect(row?.["inserted_by_id"]).toBeNull();
     const customFields = row?.["custom_fields"] as Record<string, unknown> | undefined;
     expect(customFields).toBeDefined();
     expect(customFields).not.toHaveProperty("email");
     expect(customFields).toMatchObject({ vipFlag: true });
   });
 
-  test("forget delete: no-op on customFields (host hook removes the row)", async () => {
+  test("forget delete (no override → strategy delete): host removes the row, strip is a no-op", async () => {
+    await seedForgetUserWithMembership();
+    // No retention override → policyToStrategy(null) = "delete".
     const propertyId = "33333333-3333-4000-8000-000000000003";
     await defineField("email", { type: "text", sensitive: true });
     await createProperty(propertyId, "Delete-Me");
     await setField(propertyId, "email", "alice@example.com");
     await stack.eventDispatcher?.runOnce();
 
-    // call only the custom-fields delete hook (strategy=delete) — verify
-    // it doesn't mutate the row (the host hook would handle the actual
-    // row delete; we're proving custom-fields stays out of the way).
-    await callDeleteHook(String(admin.id), admin.tenantId, "delete");
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: NOW(),
+    });
+    expect(result.processedUserIds).toContain(admin.id);
 
-    const row = await readRow(propertyId);
-    const customFields = row?.["custom_fields"] as Record<string, unknown> | undefined;
-    expect(customFields).toMatchObject({ email: "alice@example.com" });
+    // Host delete-hook removed the row; custom-fields strip stayed out of the
+    // way (it returns early on strategy=delete).
+    expect(await readRow(propertyId)).toBeUndefined();
   });
 
   test("export: rows without customFields are not included in the snippet", async () => {
+    await seedActiveUserWithMembership();
     const propertyId = "44444444-4444-4000-8000-000000000004";
     await createProperty(propertyId, "NoCustomFields");
+    await stack.eventDispatcher?.runOnce();
 
-    const snippet = await callExportHook(String(admin.id), admin.tenantId);
-    expect(snippet).toBeNull();
+    const bundle = await runUserExport({
+      db: stack.db,
+      registry: stack.registry,
+      userId: admin.id,
+      now: NOW(),
+    });
+
+    const tenantSection = bundle.tenants.find((t) => t.tenantId === TENANT);
+    const cfSnippet = tenantSection?.entities.find((e) => e.entity === "property.customFields");
+    expect(cfSnippet).toBeUndefined();
   });
 
-  test("anonymize without sensitive fields defined is a no-op (everything kept)", async () => {
+  test("forget anonymize without sensitive fields defined → all customFields kept", async () => {
+    await seedForgetUserWithMembership();
+    await seedPropertyAnonymizeOverride();
     const propertyId = "55555555-5555-4000-8000-000000000005";
     await defineField("nonSensitive", { type: "text" });
     await createProperty(propertyId, "AllStay");
     await setField(propertyId, "nonSensitive", "still-here");
     await stack.eventDispatcher?.runOnce();
 
-    await callDeleteHook(String(admin.id), admin.tenantId, "anonymize");
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: NOW(),
+    });
+    expect(result.processedUserIds).toContain(admin.id);
 
     const row = await readRow(propertyId);
+    expect(row?.["inserted_by_id"]).toBeNull();
     expect((row?.["custom_fields"] as Record<string, unknown>)?.["nonSensitive"]).toBe(
       "still-here",
     );

package/src/custom-fields/db/queries/field-access.ts

@@ -11,6 +11,6 @@ export async function selectSerializedFieldDefinition(
     "SELECT serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND field_key = $2 AND tenant_id = $3 LIMIT 1",
     [entityName, fieldKey, tenantId],
   );
-  const first = (rows as ReadonlyArray<Record<string, unknown>>)[0];
+  const first = (rows as ReadonlyArray<Record<string, unknown>>)[0]; // @cast-boundary db-row
   return first ? (first["serialized_field"] ?? null) : null;
 }

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

@@ -6,7 +6,7 @@ export async function countTenantFieldDefinitions(db: TenantDb, tenantId: string
     "SELECT COUNT(*)::int AS n FROM read_custom_field_definitions WHERE tenant_id = $1",
     [tenantId],
   );
-  const rows = rowsResult as ReadonlyArray<Record<string, unknown>>;
+  const rows = rowsResult as ReadonlyArray<Record<string, unknown>>; // @cast-boundary db-row
   const first = rows[0];
   if (!first) return 0;
   const n = first["n"];

package/src/file-provider-inmemory/__tests__/feature.test.ts

@@ -1,6 +1,7 @@
 // feature.ts contract tests for file-provider-inmemory.
 
 import { describe, expect, test } from "bun:test";
+import type { FileProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
 import { clearStorage, fileProviderInMemoryFeature, listKeys } from "../feature";
 
 describe("fileProviderInMemoryFeature — shape", () => {
@@ -33,3 +34,57 @@ describe("listKeys / clearStorage — per-tenant store helpers", () => {
     expect(() => clearStorage("never-touched")).not.toThrow();
   });
 });
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind.
+function isFileProviderPlugin(o: unknown): o is FileProviderPlugin {
+  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
+}
+
+function inmemoryPlugin(): FileProviderPlugin {
+  const options = fileProviderInMemoryFeature.extensionUsages.find(
+    (u) => u.extensionName === "fileProvider" && u.entityName === "inmemory",
+  )?.options;
+  if (!isFileProviderPlugin(options)) {
+    throw new Error("file-provider-inmemory: inmemory plugin not registered with a build()");
+  }
+  return options;
+}
+
+const bytes = (s: string) => new TextEncoder().encode(s);
+
+describe("file-provider-inmemory — build() + per-tenant store", () => {
+  test("build liefert Provider; Write erscheint in listKeys(tenant)", async () => {
+    const provider = await inmemoryPlugin().build({}, "tenant-build-1");
+    await provider.write("doc.txt", bytes("x"));
+    expect(listKeys("tenant-build-1")).toContain("doc.txt");
+    clearStorage("tenant-build-1");
+  });
+
+  test("selber Tenant: zwei builds liefern identitätsstabilen Storage (State bleibt)", async () => {
+    const a = await inmemoryPlugin().build({}, "tenant-stable");
+    await a.write("first.txt", bytes("1"));
+    const b = await inmemoryPlugin().build({}, "tenant-stable");
+    expect(await b.exists("first.txt")).toBe(true);
+    clearStorage("tenant-stable");
+  });
+
+  test("Tenant-Isolation: Write in A erscheint nicht in B", async () => {
+    const a = await inmemoryPlugin().build({}, "tenant-iso-a");
+    const b = await inmemoryPlugin().build({}, "tenant-iso-b");
+    await a.write("only-in-a.txt", bytes("a"));
+    expect(listKeys("tenant-iso-a")).toContain("only-in-a.txt");
+    expect(listKeys("tenant-iso-b")).not.toContain("only-in-a.txt");
+    expect(await b.exists("only-in-a.txt")).toBe(false);
+    clearStorage("tenant-iso-a");
+    clearStorage("tenant-iso-b");
+  });
+
+  test("clearStorage leert den Tenant-Store", async () => {
+    const p = await inmemoryPlugin().build({}, "tenant-clear");
+    await p.write("gone.txt", bytes("x"));
+    expect(listKeys("tenant-clear")).toHaveLength(1);
+    clearStorage("tenant-clear");
+    expect(listKeys("tenant-clear")).toEqual([]);
+  });
+});

package/src/file-provider-s3/__tests__/feature.test.ts

@@ -1,6 +1,7 @@
 // feature.ts contract tests for file-provider-s3.
 
 import { describe, expect, test } from "bun:test";
+import type { FileProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
 import { fileProviderS3Feature, S3_SECRET_ACCESS_KEY } from "../feature";
 
 describe("fileProviderS3Feature — shape", () => {
@@ -52,3 +53,29 @@ describe("fileProviderS3Feature — plugin-registration", () => {
     );
   });
 });
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate.
+function isFileProviderPlugin(o: unknown): o is FileProviderPlugin {
+  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
+}
+
+function s3Plugin(): FileProviderPlugin {
+  const options = fileProviderS3Feature.extensionUsages.find(
+    (u) => u.extensionName === "fileProvider" && u.entityName === "s3",
+  )?.options;
+  if (!isFileProviderPlugin(options)) {
+    throw new Error("file-provider-s3: s3 plugin not registered with a build()");
+  }
+  return options;
+}
+
+describe("fileProviderS3Feature — build() guard", () => {
+  test("build ohne ctx.config wirft (config-feature nicht gemountet)", async () => {
+    // Die tieferen Value-/Secret-Pfade (bucket/region/accessKeyId leer,
+    // secret fehlt, Happy-Path) hängen an der echten Config-/Secrets-
+    // Pipeline → S3-Integration-Test (setupTestStack + MinIO), nicht hier.
+    // Die requireNonEmpty-Werteprüfung selbst ist über
+    // foundation-shared/config-helpers abgedeckt.
+    await expect(s3Plugin().build({}, "tenant-x")).rejects.toThrow("ctx.config is missing");
+  });
+});

package/src/files-provider-s3/__tests__/s3-provider.integration.test.ts

@@ -111,17 +111,45 @@ describe("s3-provider (Minio)", () => {
     await expect(provider.read(key)).rejects.toThrow();
   });
 
-  test("writeStream round-trip via multipart writer preserves bytes", async () => {
-    // Pinst die idiomatic Bun-S3-writer-Form (write + end, kein manual
-    // flush). Chunks summieren absichtlich auf > 5 MiB (partSize) UND auf
-    // einen krummen Rest, damit der multipart-finalizer auch dann greift,
-    // wenn die Source-Chunks nicht auf die Part-Boundary aufgehen.
+  test("writeStream round-trip via multipart writer preserves byte-exact ordering", async () => {
+    // Regression guard for the multipart-flush bug: the source chunks are
+    // deliberately NON-ALIGNED to the 5 MiB part boundary ([3,3,2] MiB → the
+    // internal part split at 5 MiB lands mid-chunk #2). The old
+    // `buffered >= STREAM_PART_SIZE` flush would emit a non-final part of an
+    // odd size at that boundary; the Bun-writer (partSize) path produces the
+    // correct part topology. Either way we verify END-TO-END byte integrity,
+    // not just total size + first/last byte.
+    //
+    // Each chunk carries a chunk-distinct content pattern (incl. a per-chunk
+    // marker in byte[0]). A re-order, dropped, or duplicated part therefore
+    // changes the readback SHA256 — a same-pattern-per-part test would not
+    // catch that. We assert both the SHA256 over the whole stream AND the
+    // per-chunk-offset marker bytes.
+    //
+    // NOTE: MinIO does NOT enforce the AWS `MinPartSize` (5 MiB non-final
+    // part) rule, so this test cannot reproduce the genuine S3 `EntityTooSmall`
+    // rejection — that needs a manual smoke against AWS/R2. What it DOES guard
+    // is byte-ordering/integrity of the multipart round-trip, which is
+    // provider-agnostic.
     const key = uniqueKey("stream-multipart.bin");
     const partSize = 5 * 1024 * 1024;
-    const chunk = new Uint8Array(1024 * 1024);
-    for (let i = 0; i < chunk.length; i++) chunk[i] = i % 251;
-    const chunks: Uint8Array[] = [];
-    for (let i = 0; i < 7; i++) chunks.push(chunk);
+    const MiB = 1024 * 1024;
+    const chunkSizes = [3 * MiB, 3 * MiB, 2 * MiB]; // 8 MiB total, non-aligned to 5 MiB
+
+    function makeChunk(index: number, size: number): Uint8Array {
+      const c = new Uint8Array(size);
+      // byte[0] = chunk marker; remaining bytes mix index + position so each
+      // chunk's body is distinct (reorder/duplicate changes the hash).
+      c[0] = index;
+      for (let i = 1; i < size; i++) c[i] = (index * 31 + i) % 251;
+      return c;
+    }
+    const chunks = chunkSizes.map((size, i) => makeChunk(i, size));
+
+    // Expected hash over the concatenated source.
+    const sourceHasher = new Bun.CryptoHasher("sha256");
+    for (const c of chunks) sourceHasher.update(c);
+    const expectedHash = sourceHasher.digest("hex");
 
     if (!provider.writeStream) throw new Error("s3 provider should implement writeStream");
     await provider.writeStream(
@@ -132,10 +160,24 @@ describe("s3-provider (Minio)", () => {
     );
 
     const readBack = await provider.read(key);
-    expect(readBack.byteLength).toBe(chunks.length * chunk.length);
+    const totalSize = chunkSizes.reduce((a, b) => a + b, 0);
+    expect(readBack.byteLength).toBe(totalSize);
     expect(readBack.byteLength).toBeGreaterThan(partSize);
-    expect(readBack[0]).toBe(0);
-    expect(readBack[readBack.byteLength - 1]).toBe(chunk[chunk.length - 1]);
+
+    // Byte-exact integrity over the full stream — catches any mid-stream
+    // corruption / reorder / off-by-part the size+endpoints check would miss.
+    const readHasher = new Bun.CryptoHasher("sha256");
+    readHasher.update(readBack);
+    expect(readHasher.digest("hex")).toBe(expectedHash);
+
+    // Explicit per-chunk marker check at the expected source offsets — proves
+    // the parts landed in order (not just that the bytes are collectively
+    // present).
+    let offset = 0;
+    for (let i = 0; i < chunks.length; i++) {
+      expect(readBack[offset]).toBe(i);
+      offset += chunkSizes[i] ?? 0;
+    }
   });
 });
 

package/src/foundation-shared/__tests__/config-helpers.test.ts

@@ -0,0 +1,72 @@
+// config-helpers Unit-Tests (Phase 1, test-luecken-integration).
+//
+// Pinnt das Verhalten der von ai-/mail-/file-foundation geteilten
+// Narrowing-Helfer — inkl. der non-obvious Grenzfälle: requireDefined
+// narrowt NUR `undefined` (nicht falsy), und requireNonEmpty hat zwei
+// getrennte Fehlerpfade (undefined vs leer), die über die Error-Message
+// unterschieden werden.
+
+import { describe, expect, test } from "bun:test";
+import { requireDefined, requireNonEmpty } from "../config-helpers";
+
+describe("requireDefined", () => {
+  test("undefined → wirft mit featureName + label + Misconfig-Hinweis", () => {
+    expect(() => requireDefined(undefined, "ai-foundation", "apiKey")).toThrow(
+      "ai-foundation: 'apiKey' config key resolved to undefined — registry misconfigured (no value + no default)",
+    );
+  });
+
+  test("defined Wert → unverändert zurück", () => {
+    expect(requireDefined("sk-123", "ai-foundation", "apiKey")).toBe("sk-123");
+  });
+
+  test("falsy-aber-defined Werte passieren (Check ist === undefined, nicht falsy)", () => {
+    // Würde hier ein falsy-Check stehen, bräche ein numerischer Key mit Wert 0
+    // oder ein leerer-String-Default. requireNonEmpty ist der strengere Helfer.
+    expect(requireDefined(0, "f", "n")).toBe(0);
+    expect(requireDefined("", "f", "n")).toBe("");
+    expect(requireDefined(false, "f", "n")).toBe(false);
+    expect(requireDefined(null, "f", "n")).toBeNull();
+  });
+
+  test("Objekt-Wert → identische Referenz zurück (generischer Typ erhalten)", () => {
+    const cfg = { host: "smtp.example.com", port: 587 };
+    expect(requireDefined(cfg, "mail-foundation", "smtp")).toBe(cfg);
+  });
+});
+
+describe("requireNonEmpty", () => {
+  test("undefined → wirft die requireDefined-Message (delegiert, NICHT empty-Pfad)", () => {
+    expect(() => requireNonEmpty(undefined, "mail-foundation", "host")).toThrow(
+      "config key resolved to undefined",
+    );
+  });
+
+  test("leerer String → wirft empty-Message mit Default-uiHint", () => {
+    expect(() => requireNonEmpty("", "file-foundation", "bucket")).toThrow(
+      "file-foundation: 'bucket' is empty — tenant must configure it before use. Set via tenant-admin UI or seed-handler.",
+    );
+  });
+
+  test("leerer String mit custom uiHint → Hint landet in der Message", () => {
+    expect(() =>
+      requireNonEmpty("", "ai-foundation", "model", "Choose a model in Settings → AI."),
+    ).toThrow("is empty — tenant must configure it before use. Choose a model in Settings → AI.");
+  });
+
+  test("non-empty Wert → unverändert zurück", () => {
+    expect(requireNonEmpty("smtp.example.com", "mail-foundation", "host")).toBe("smtp.example.com");
+  });
+
+  test("reiner Whitespace → wirft empty-Message (getrimmt, gilt als leer)", () => {
+    expect(() => requireNonEmpty("   ", "mail-foundation", "host")).toThrow(
+      "mail-foundation: 'host' is empty — tenant must configure it before use.",
+    );
+  });
+
+  test("umgebender Whitespace wird vom Rückgabewert getrimmt", () => {
+    expect(requireNonEmpty("  smtp.example.com  ", "mail-foundation", "host")).toBe(
+      "smtp.example.com",
+    );
+  });
+});

package/src/foundation-shared/config-helpers.ts

@@ -50,6 +50,10 @@ export function requireDefined<T>(value: T | undefined, featureName: string, lab
  * Typical use: SMTP host, S3 bucket, model id — values without which the
  * downstream SDK would 400 with a cryptic message. The clearer "tenant
  * must configure X via tenant-admin UI" lands at the call-site instead.
+ *
+ * Whitespace is trimmed: a whitespace-only value counts as empty, and the
+ * returned string has surrounding whitespace removed — so a stray " host "
+ * never reaches the SDK as-is.
  */
 export function requireNonEmpty(
   value: string | undefined,
@@ -57,11 +61,11 @@ export function requireNonEmpty(
   label: string,
   uiHint = "Set via tenant-admin UI or seed-handler.",
 ): string {
-  const defined = requireDefined(value, featureName, label);
-  if (defined.length === 0) {
+  const trimmed = requireDefined(value, featureName, label).trim();
+  if (trimmed.length === 0) {
     throw new Error(
       `${featureName}: '${label}' is empty — tenant must configure it before use. ${uiHint}`,
     );
   }
-  return defined;
+  return trimmed;
 }

package/src/tier-engine/__tests__/tier-engine.integration.test.ts

@@ -223,6 +223,61 @@ describe("scenario 6: access control", () => {
     expectErrorIncludes(error, "access_denied");
   });
 
+  test("TenantAdmin (ohne SystemAdmin) cannot create a tier-assignment — Self-Upgrade-Schutz", async () => {
+    // Tier-Wechsel ist Plattform-/Billing-Hoheit: ein Tenant-Admin darf
+    // seinen eigenen Tier NICHT setzen (sonst Gratis-Self-Upgrade).
+    const tenantAdmin = createTestUser({
+      id: 310,
+      tenantId: testTenantId(310),
+      roles: ["TenantAdmin"],
+    });
+
+    const error = await stack.http.writeErr(
+      TierEngineHandlers.create,
+      { tier: "pro" },
+      tenantAdmin,
+    );
+
+    expectErrorIncludes(error, "access_denied");
+  });
+
+  test("TenantAdmin cannot update a tier-assignment", async () => {
+    const sysadmin = createTestUser({
+      id: 311,
+      tenantId: testTenantId(311),
+      roles: ["SystemAdmin"],
+    });
+    const created = await stack.http.writeOk(TierEngineHandlers.create, { tier: "free" }, sysadmin);
+    const id = (created!["data"] as Record<string, unknown>)["id"] as string;
+
+    // Selber Tenant, aber reiner TenantAdmin → darf den Tier nicht ändern.
+    const tenantAdmin = createTestUser({
+      id: 312,
+      tenantId: testTenantId(311),
+      roles: ["TenantAdmin"],
+    });
+
+    const error = await stack.http.writeErr(
+      TierEngineHandlers.update,
+      { id, version: 1, changes: { tier: "agency" } },
+      tenantAdmin,
+    );
+
+    expectErrorIncludes(error, "access_denied");
+  });
+
+  test("SystemAdmin (ohne TenantAdmin) CAN create a tier-assignment", async () => {
+    const sysadmin = createTestUser({
+      id: 313,
+      tenantId: testTenantId(313),
+      roles: ["SystemAdmin"],
+    });
+
+    const result = await stack.http.writeOk(TierEngineHandlers.create, { tier: "team" }, sysadmin);
+
+    expect((result!["data"] as Record<string, unknown>)["tier"]).toBe("team");
+  });
+
   test("query handlers carry the admin-only access rule (config-level check)", () => {
     // Read-access is enforced by the same role-rule set on the query handler.
     // We assert the rule is registered correctly — covers regression when

package/src/tier-engine/feature.ts

@@ -81,6 +81,12 @@ const tierAssignmentExecutor = createEventStoreExecutor(tierAssignmentTable, tie
 });
 
 const adminAccess = { access: { roles: ["TenantAdmin", "SystemAdmin"] } } as const;
+// Tier-Wechsel ist Plattform-/Billing-Hoheit — ein Tenant-Admin darf den
+// eigenen Tier NIE setzen (sonst Gratis-Self-Upgrade). Daher sind die
+// Writes SystemAdmin-only; Reads (list, get-active-tier) bleiben
+// TenantAdmin-sichtbar. Auto-default-Hook + Billing schreiben als System,
+// hängen also nicht an diesem Handler-Access.
+const writeAccess = { access: { roles: ["SystemAdmin"] } } as const;
 
 /**
  * Options for createTierEngineFeature. Both fields optional — wenn beide
@@ -167,8 +173,8 @@ export function createTierEngineFeature<
     r.entity("tier-assignment", tierAssignmentEntity);
 
     // Standard-CRUD via Helper.
-    r.writeHandler(defineEntityCreateHandler("tier-assignment", tierAssignmentEntity, adminAccess));
-    r.writeHandler(defineEntityUpdateHandler("tier-assignment", tierAssignmentEntity, adminAccess));
+    r.writeHandler(defineEntityCreateHandler("tier-assignment", tierAssignmentEntity, writeAccess));
+    r.writeHandler(defineEntityUpdateHandler("tier-assignment", tierAssignmentEntity, writeAccess));
 
     // Reads.
     r.queryHandler(defineEntityListHandler("tier-assignment", tierAssignmentEntity, adminAccess));