@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -0,0 +1,454 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import {
+  computeBlindIndex,
+  configuredBlindIndexKey,
+  configuredPiiSubjectKms,
+  type SubjectId,
+  subjectIdSchema,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  type DbRunner,
+  nullBlindIndexesForSubject,
+  recordEventsOwnedExclusivelyByTenant,
+  recordRowExistsInTenant,
+  recordRowOwningTenantId,
+  subjectRowExistsInTenant,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineWriteHandler,
+  type EntityDefinition,
+  type FeatureDefinition,
+  type HandlerContext,
+  type SessionUser,
+  type TenantId,
+  type WriteEvent,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  InternalError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { assertIrreversibleOperationAllowed } from "@cosmicdrift/kumiko-framework/pipeline";
+import { purgeSearchDocumentsForSubject } from "@cosmicdrift/kumiko-framework/search";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { resolveRetentionPolicyForTenant } from "../../data-retention/index.js";
+import { revokeAllPatTokensForUser } from "../../personal-access-tokens/index.js";
+import { USER_STATUS } from "../../user/index.js";
+import {
+  denyIfTargetOutsideAdminTenant,
+  isSystemAdminActor,
+  updateUserLifecycle,
+} from "../../user-data-rights/index.js";
+import {
+  CRYPTO_SHREDDING_AGGREGATE_TYPE,
+  RECORD_ENTITY_NOT_REGISTERED,
+  SUBJECT_FORGET_DENIED_EVENT_NAME,
+  SUBJECT_FORGOTTEN_EVENT_NAME,
+  TARGET_RECORD_NOT_ADMIN_TENANT,
+  TARGET_RECORD_RETENTION_BLOCK_DELETE,
+  TARGET_TENANT_NOT_ADMIN_TENANT,
+} from "../constants.js";
+
+export { subjectIdSchema };
+
+export const forgetSubjectSchema = z.object({
+  subject: subjectIdSchema,
+  reason: z.string().min(10),
+});
+
+export const subjectForgottenSchema = z.object({
+  subjectKey: z.string().min(1),
+  reason: z.string().min(10),
+  forgottenBy: z.string().min(1),
+});
+
+export const subjectForgetDeniedSchema = z.object({
+  subjectKeyDigest: z.string().min(1).optional(),
+  subjectKind: z.enum(["user", "tenant", "record"]),
+  reason: z.string().min(10),
+  forgottenBy: z.string().min(1),
+  actorTenantId: z.string().min(1),
+  denial: z.string().min(1),
+});
+
+type SubjectIdInput = z.infer<typeof subjectIdSchema>;
+
+// Exhaustive switch so a 4th subject kind fails to compile instead of
+// silently aggregating under the wrong id.
+function subjectAggregateId(raw: SubjectIdInput): string {
+  switch (raw.kind) {
+    case "user":
+      return raw.userId;
+    case "tenant":
+      return raw.tenantId;
+    case "record":
+      return raw.id;
+    default: {
+      const exhaustiveCheck: never = raw;
+      throw new Error(`Unhandled subject kind: ${JSON.stringify(exhaustiveCheck)}`);
+    }
+  }
+}
+
+// The record subject names its own entity — resolve it against the registry
+// instead of trusting the payload straight into resolveTableName/SQL (#2786).
+function findRegisteredEntity(
+  features: ReadonlyMap<string, FeatureDefinition>,
+  entityName: string,
+): EntityDefinition | undefined {
+  for (const feature of features.values()) {
+    const entity = feature.entities?.[entityName];
+    if (entity) return entity;
+  }
+  return undefined;
+}
+
+// Tenant-scope guard (mh#349): DataProtectionOfficer is a tenant-scoped role,
+// but the handler otherwise erases ANY subject cross-tenant on a raw
+// (un-scoped) client — a Tenant-A DPO who learns a Tenant-B subject id
+// (export, support ticket, log line) could destroy it. SystemAdmin
+// (platform-wide) always bypasses.
+async function resolveTenantScopeDenial(
+  db: DbRunner,
+  features: ReadonlyMap<string, FeatureDefinition>,
+  user: SessionUser,
+  raw: SubjectIdInput,
+): Promise<WriteFailure | undefined> {
+  if (isSystemAdminActor(user)) return undefined;
+
+  if (raw.kind === "tenant") {
+    if (raw.tenantId === user.tenantId) return undefined;
+    return writeFailure(
+      new AccessDeniedError({ details: { reason: TARGET_TENANT_NOT_ADMIN_TENANT } }),
+    );
+  }
+
+  if (raw.kind === "record") {
+    // Same fail-open rule as the user branch below — without the tenant
+    // feature there is no tenant concept to enforce.
+    if (!features.has("tenant")) return undefined;
+    const entity = findRegisteredEntity(features, raw.entity);
+    const rowInTenant =
+      entity !== undefined &&
+      (await recordRowExistsInTenant(db, features, raw.entity, raw.id, user.tenantId));
+    if (rowInTenant) return undefined;
+    // A deleted row or a custom aggregate without an entity has no projection
+    // row to check; its event stream still proves which tenant owns it.
+    if (await recordEventsOwnedExclusivelyByTenant(db, raw.entity, raw.id, user.tenantId)) {
+      return undefined;
+    }
+    return writeFailure(
+      new AccessDeniedError({
+        details: {
+          reason: entity ? TARGET_RECORD_NOT_ADMIN_TENANT : RECORD_ENTITY_NOT_REGISTERED,
+        },
+      }),
+    );
+  }
+
+  // Without the tenant feature there's no membership table to check against —
+  // no scoping concept exists to enforce (single/no-tenant apps only;
+  // ponytail: fail-open here, not a gap in multi-tenant apps).
+  if (!features.has("tenant")) return undefined;
+
+  const memberDenied = await denyIfTargetOutsideAdminTenant(db, user, raw.userId);
+  if (!memberDenied) return undefined;
+
+  // Not a real user in the actor's tenant — raw.userId may still be a
+  // self-owned PII subject (share-token recipient, email subscriber, ...)
+  // whose own row carries a real tenant_id.
+  const ownedInTenant = await subjectRowExistsInTenant(db, features, raw.userId, user.tenantId);
+  return ownedInTenant ? undefined : memberDenied;
+}
+
+// fw#2789/#2805: blockDelete (legally mandated physical retention, e.g.
+// ledger/invoice text) means this command must refuse, not silently
+// anonymize or proceed. Refused when the host entity itself declares
+// blockDelete OR the owning tenant's effective data-retention policy
+// (preset/override layering) does, so a tenant preset cannot be bypassed here.
+// The entity declaration is checked first and independent of the tenant
+// feature/gate and of data-retention being mounted: a retention obligation
+// holds in single-tenant apps too.
+async function resolveRetentionDenial(
+  ctx: HandlerContext,
+  raw: SubjectIdInput,
+  // Lazy: unsafeRaw writes an audit entry per call, so only request it once a read is needed.
+  getRunner: () => DbRunner,
+): Promise<WriteFailure | undefined> {
+  if (raw.kind !== "record") return undefined;
+  const features = ctx.registry.features;
+  const deny = () =>
+    writeFailure(
+      new AccessDeniedError({ details: { reason: TARGET_RECORD_RETENTION_BLOCK_DELETE } }),
+    );
+  const entity = findRegisteredEntity(features, raw.entity);
+  if (entity?.retention?.strategy === "blockDelete") return deny();
+  if (!features.has("data-retention")) return undefined;
+
+  // The row's own tenant, not the actor's: a SystemAdmin acts across tenants.
+  const runner = getRunner();
+  const owningTenantId = await recordRowOwningTenantId(runner, features, raw.entity, raw.id);
+  if (owningTenantId === undefined) return undefined;
+  const effective = await resolveRetentionPolicyForTenant({
+    db: runner,
+    registry: ctx.registry,
+    tenantId: owningTenantId as TenantId,
+    entityName: raw.entity,
+  });
+  return effective.policy?.strategy === "blockDelete" ? deny() : undefined;
+}
+
+// AccessDeniedError.code is the generic "access_denied" for every branch;
+// the specific branch lives in details.reason.
+function denialReasonOf(failure: WriteFailure): string {
+  const details = failure.error.details;
+  if (typeof details === "object" && details !== null && "reason" in details) {
+    const { reason } = details;
+    if (typeof reason === "string") return reason;
+  }
+  return failure.error.code;
+}
+
+// Denied cross-tenant probes must still leave an audit trail (fw#2348).
+// Appended outside the handler tx (fw#2592): the caller's
+// `return tenantScopeDenial` rolls that tx back.
+async function appendDenialAuditEvent(
+  ctx: HandlerContext,
+  event: WriteEvent<z.infer<typeof forgetSubjectSchema>>,
+  subjectKey: string,
+  subjectKind: SubjectIdInput["kind"],
+  denialCode: string,
+  denialAuditRunner: DbRunner | undefined,
+): Promise<WriteFailure | null> {
+  if (!denialAuditRunner) {
+    return writeFailure(
+      new InternalError({
+        message:
+          "[crypto-shredding] forget-subject denial audit event cannot be appended without " +
+          "ctx.dbOutsideTransaction — dispatch wiring is missing the outside-tx db source.",
+      }),
+    );
+  }
+  const eventDef = ctx.registry.getEvent(SUBJECT_FORGET_DENIED_EVENT_NAME);
+  if (!eventDef) {
+    return writeFailure(
+      new InternalError({
+        message: `[crypto-shredding] event "${SUBJECT_FORGET_DENIED_EVENT_NAME}" is not registered.`,
+      }),
+    );
+  }
+  const blindIndexKey = configuredBlindIndexKey();
+  const payload = subjectForgetDeniedSchema.parse({
+    // The denial lands in the REQUESTING actor's own tenant-scoped stream —
+    // it must never materialise the foreign subject's identifiers there. A
+    // plaintext subjectKey/aggregateId would survive as a permanent record
+    // for the prober and would still be present when the owning tenant
+    // later runs its own (legitimate) forget-subject for that subject. The
+    // digest is keyed (a bare hash of a guessable id could be recomputed from
+    // a candidate id) and lets an operator correlate repeated probes of the
+    // same subject; without a blind-index key no digest is stored at all.
+    ...(blindIndexKey !== undefined && {
+      subjectKeyDigest: computeBlindIndex(blindIndexKey, subjectKey),
+    }),
+    subjectKind,
+    reason: event.payload.reason,
+    forgottenBy: event.user.id,
+    actorTenantId: event.user.tenantId,
+    denial: denialCode,
+  });
+  const reqCtx = requestContext.get();
+  // This event is the only proof the denial happened. Skipping
+  // runProjectionsForEvent here is fine — nothing projects
+  // crypto-shredding:event:forget-denied.
+  await append(denialAuditRunner, {
+    aggregateId: generateId(),
+    aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
+    // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw
+    // bypasses TenantDb's scoping, so this is the only guard against a cross-tenant denial event (fw#2452).
+    tenantId: event.user.tenantId,
+    expectedVersion: 0,
+    type: SUBJECT_FORGET_DENIED_EVENT_NAME,
+    eventVersion: eventDef.version,
+    payload,
+    metadata: {
+      userId: event.user.id,
+      ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
+      ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
+      ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
+    },
+  });
+  return null;
+}
+
+// Manual crypto-shred for a DPO / platform operator: erases the subject's
+// DEK immediately (all its PII ciphertext becomes unreadable, reads render
+// "[[erased]]") and appends the audit event. Forget is final — the adapter
+// keeps a tombstone, so the subject can never get a new key.
+//
+// The automated Art.-17 path (user-data-rights forget-cleanup) calls
+// kms.eraseKey directly inside its per-user sub-tx; this command is the
+// standalone trigger for cases outside that pipeline (authority requests,
+// tenant-destroy in Sprint 5, operator recovery).
+export const forgetSubjectWrite = defineWriteHandler({
+  name: "forget-subject",
+  schema: forgetSubjectSchema,
+  access: { roles: [ROLES.DataProtectionOfficer, ROLES.SystemAdmin] },
+  description:
+    "Irreversibly crypto-shreds one user, tenant or record subject by erasing its encryption key, nulling its blind indexes, purging its search documents and closing the user's login, for supervisory-authority requests and operator recovery outside the automated Art. 17 cleanup pipeline.",
+  // Erasing the subject key is irreversible: there is no undo, so an agent must
+  // not be able to reach it at all.
+  agent: { expose: false, risk: "high" },
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason:
+      "denial audit append names the prober's own tenant stream on the outside-transaction db; " +
+      "the tenant-scope and retention checks run against the subject's tenant, not necessarily the caller's; " +
+      "the blind-index sweep and search purge address the subject across tenants; the user " +
+      "lifecycle update and PAT revoke run on the SYSTEM user stream.",
+  },
+  handler: async (event, ctx) => {
+    assertIrreversibleOperationAllowed("forget-subject key erase");
+    const kms = configuredPiiSubjectKms();
+    if (!kms) {
+      return writeFailure(
+        new InternalError({
+          message:
+            "[crypto-shredding] forget-subject called but no KMS adapter is configured — " +
+            "pass runProdApp({ kms }) / configurePiiSubjectKms(adapter) at boot.",
+        }),
+      );
+    }
+
+    const raw = event.payload.subject;
+    const subject: SubjectId =
+      raw.kind === "user"
+        ? { kind: "user", userId: raw.userId }
+        : raw.kind === "tenant"
+          ? { kind: "tenant", tenantId: raw.tenantId }
+          : { kind: "record", entity: raw.entity, id: raw.id };
+    const subjectKey = subjectIdToKey(subject);
+
+    const tenantScopeDenial = await resolveTenantScopeDenial(
+      ctx.db.unsafeRaw(
+        "tenant-scope check runs against the subject's tenant, not necessarily the caller's",
+      ),
+      ctx.registry.features,
+      event.user,
+      raw,
+    );
+    if (tenantScopeDenial) {
+      const auditFailure = await appendDenialAuditEvent(
+        ctx,
+        event,
+        subjectKey,
+        raw.kind,
+        denialReasonOf(tenantScopeDenial),
+        ctx.dbOutsideTransaction?.unsafeRaw(
+          "denial audit append: names the prober's own tenant stream on the outside-transaction db",
+        ),
+      );
+      return auditFailure ?? tenantScopeDenial;
+    }
+
+    // Runs after the tenant gate but before any key is touched: a retention
+    // check ahead of the tenant gate would leak a foreign entity's retention
+    // posture to a cross-tenant prober.
+    const retentionDenial = await resolveRetentionDenial(ctx, raw, () =>
+      ctx.db.unsafeRaw("retention check reads the record row's owning tenant, not the caller's"),
+    );
+    if (retentionDenial) {
+      const auditFailure = await appendDenialAuditEvent(
+        ctx,
+        event,
+        subjectKey,
+        raw.kind,
+        TARGET_RECORD_RETENTION_BLOCK_DELETE,
+        ctx.dbOutsideTransaction?.unsafeRaw(
+          "denial audit append: names the prober's own tenant stream on the outside-transaction db",
+        ),
+      );
+      return auditFailure ?? retentionDenial;
+    }
+
+    // Erase BEFORE the audit append: if the append throws, the key is gone
+    // but no event exists — a retry is a no-op erase plus the event. The
+    // reverse order could leave an audit trail claiming a shred that never
+    // happened.
+    await kms.eraseKey(subject, {
+      requestId: requestContext.get()?.requestId ?? "crypto-shredding:forget-subject",
+      userId: event.user.id,
+      eraseReason: event.payload.reason,
+    });
+
+    // Blind-index sweep (#818): nulls bidx columns now so the deterministic
+    // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
+    const crossTenantSubjectRunner = ctx.db.unsafeRaw(
+      "blind-index sweep and search purge address the subject across tenants",
+    );
+    await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
+
+    // Derived search index still holds plaintext (#1610) — purge next to the
+    // blind-index sweep. No adapter → no-op (apps without search).
+    if (ctx.searchAdapter) {
+      await purgeSearchDocumentsForSubject(
+        crossTenantSubjectRunner,
+        ctx.registry.features,
+        ctx.searchAdapter,
+        subjectKey,
+        subject,
+      );
+    }
+
+    // User subject: close the login door. DEK-erase makes the passwordHash
+    // ciphertext unreadable, but status + PATs are standalone credentials —
+    // the PAT resolver only checks revokedAt/expiresAt, NOT user.status
+    // (resolver.ts). Without this block a forgotten user with a live PAT stays
+    // callable. Mirror of the automated Art.-17 path (userDeleteHook:
+    // status=Deleted; apiTokenDeleteHook: revoke):
+    //   - user.updated as lifecycle event (updateUserLifecycle), so a
+    //     read_users rebuild doesn't wipe the flip (#494)
+    //   - sessions don't need active revocation — session-callbacks
+    //     re-validate user.status on every request (isPrincipalBlocked
+    //     blocks Deleted).
+    // Both idempotent (status set / revokedAt IS NULL filter), retry after
+    // crash recovery is safe. User-feature guard: without the user feature
+    // read_users doesn't exist (crypto-only stack). Tenant subjects have no
+    // credentials.
+    // Graceful fail: email-subscribers and other non-user entities may use
+    // user-style subject keys without having an actual user row — the key
+    // erase above is the important part for GDPR compliance; the lifecycle
+    // update is best-effort for real users.
+    if (raw.kind === "user" && ctx.registry.features.has("user")) {
+      try {
+        const userLifecycleRunner = ctx.db.unsafeRaw(
+          "user lifecycle update and PAT revoke run on the SYSTEM user stream",
+        );
+        await updateUserLifecycle(userLifecycleRunner, raw.userId, { status: USER_STATUS.Deleted });
+        if (ctx.registry.features.has("personal-access-tokens")) {
+          await revokeAllPatTokensForUser(userLifecycleRunner, raw.userId);
+        }
+      } catch {
+        // User row may not exist (e.g. email subscribers with user-style
+        // subject keys). Key erase + blind-index sweep above already ran.
+      }
+    }
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: subjectAggregateId(raw),
+      aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
+      type: SUBJECT_FORGOTTEN_EVENT_NAME,
+      payload: {
+        subjectKey,
+        reason: event.payload.reason,
+        forgottenBy: event.user.id,
+      },
+    });
+
+    return { isSuccess: true as const, data: { subjectKey } };
+  },
+});

package/packages/bundled-features/src/crypto-shredding/index.ts

@@ -0,0 +1,13 @@
+export {
+  CRYPTO_SHREDDING_AGGREGATE_TYPE,
+  CRYPTO_SHREDDING_FEATURE_NAME,
+  SUBJECT_FORGET_DENIED_EVENT_NAME,
+  SUBJECT_FORGOTTEN_EVENT_NAME,
+} from "./constants.js";
+export { createCryptoShreddingFeature } from "./feature.js";
+export {
+  forgetSubjectSchema,
+  subjectForgetDeniedSchema,
+  subjectForgottenSchema,
+  subjectIdSchema,
+} from "./handlers/forget-subject.write.js";

package/packages/bundled-features/src/custom-fields/aggregate-id.ts

@@ -0,0 +1,34 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID-namespace für custom-field-definition aggregate-id-Ableitung.
+// Generiert einmalig (2026-05-22), in Stein gemeißelt: ein Wechsel würde
+// jeden existing fieldDefinition-Stream re-keyen → kaputter event-replay,
+// kaputte definition-history. Drift-Pin in __tests__/drift.test.ts.
+const FIELD_DEFINITION_NAMESPACE = "f1d3b2c7-4e5a-4b9c-8d1f-2a3b4c5d6e7f";
+
+/**
+ * Deterministic aggregate-id für ein fieldDefinition-Aggregate aus dem
+ * Tripel (tenantId, entityName, fieldKey). Pro (Tenant|System, Entity,
+ * FieldKey) existiert genau ein Aggregate.
+ *
+ * **Scope-Semantik:**
+ *   - System-Scope: `tenantId = SYSTEM_TENANT_ID` → die fieldDefinition
+ *     gilt für alle Tenants (vendor-defined).
+ *   - Tenant-Scope: `tenantId = <tenant-uuid>` → pro Tenant eigene
+ *     fieldDefinition.
+ *
+ * **Conflict-Rule** (durchgesetzt im write-handler, NICHT via DB-constraint):
+ *   Pro (entityName, fieldKey) darf nur EINE Definition existieren — entweder
+ *   system oder tenant, nicht beide. Wenn system `customer.internalNumber`
+ *   definiert, kann Tenant kein eigenes `customer.internalNumber` mehr
+ *   definieren (422 `fieldKey_conflict`). Verhindert Resolution-Ambiguität
+ *   beim Read.
+ */
+// @wrapper-known uuid-domain
+export function fieldDefinitionAggregateId(
+  tenantId: string,
+  entityName: string,
+  fieldKey: string,
+): string {
+  return uuidv5(`${tenantId}|${entityName}|${fieldKey}`, FIELD_DEFINITION_NAMESPACE);
+}

package/packages/bundled-features/src/custom-fields/changes.json

@@ -0,0 +1,15 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "field-definition list keeps TenantAdmin when fieldDefinitionWriteRoles is set",
+    "detail": "custom-fields: the field-definition list roles always include the default `TenantAdmin`, also when `fieldDefinitionWriteRoles` is set. `TenantAdmin` keeps saving values by default, so the form section must keep loading for it; `fieldDefinitionWriteRoles: []` no longer locks out the list.",
+    "migration": "No action needed. Set fieldDefinitionListRoles explicitly to narrow the list roles."
+  },
+  {
+    "version": "0.146.0",
+    "type": "improvement",
+    "title": "custom-fields: PII-Support entfernt (#972) — custom fields sind für zusätzliche Business-…",
+    "detail": "custom-fields: PII-Support entfernt (#972) — custom fields sind für zusätzliche Business-Infos, nicht für personenbezogene Daten. BREAKING: `serializedField.sensitive` wird beim Anlegen/Update rejected, gespeicherte Definitionen mit dem Key werfen beim Parsen (zero-legacy, Feld neu anlegen). Der Self-Projection-Sonderweg und der user-data-rights-Forget-Strip entfallen; jeder `customField.set` trägt seinen Wert im Event — custom fields sind damit vollständig rebuild-safe. PII gehört in Schema-Entity-Felder mit pii/userOwned/tenantOwned-Annotation."
+  }
+]

package/packages/bundled-features/src/custom-fields/constants.ts

@@ -0,0 +1,79 @@
+// @runtime client
+// custom-fields bundle constants — feature-name + event-names.
+//
+// Spec: kumiko-platform/docs/plans/features/custom-fields.md
+// Sprint plan: kumiko-platform/docs/plans/custom-fields-sprint.md
+
+export const CUSTOM_FIELDS_FEATURE_NAME = "custom-fields";
+
+// Qualified handler names (QN format: scope:type:name). Mirror text-
+// content's Handler/Queries object pattern — Clients (z.B. die
+// CustomFieldsFormSection web-component) referenzieren über das Object
+// statt magic-strings.
+export const CustomFieldsHandlers = {
+  defineTenantField: "custom-fields:write:define-tenant-field",
+  defineSystemField: "custom-fields:write:define-system-field",
+  deleteTenantField: "custom-fields:write:delete-tenant-field",
+  deleteSystemField: "custom-fields:write:delete-system-field",
+  setCustomField: "custom-fields:write:set-custom-field",
+  clearCustomField: "custom-fields:write:clear-custom-field",
+} as const;
+
+export const CustomFieldsQueries = {
+  fieldDefinitionList: "custom-fields:query:field-definition:list",
+} as const;
+
+// Name the web component registers under in ExtensionSectionsProvider.
+export const CUSTOM_FIELDS_FORM_EXTENSION_NAME = "CustomFieldsFormSection";
+
+// Entity-CRUD auto-events for the `field-definition` entity. registry.ts emits
+// these as `${entityName}.created`/`.updated` (dot form) — they do NOT run
+// through r.defineEvent/toKebab, so the dot MUST stay.
+export const FIELD_DEFINITION_AGGREGATE_TYPE = "field-definition";
+export const FIELD_DEFINITION_CREATED_EVENT = "field-definition.created";
+export const FIELD_DEFINITION_UPDATED_EVENT = "field-definition.updated";
+// Qualified at registration via r.defineEvent — final name is
+// `custom-fields:event:field-definition-deleted`. Short-name MUST be kebab
+// (no dots): qualifyEntityName runs toKebab which collapses dots to dashes.
+export const FIELD_DEFINITION_DELETED_EVENT = "field-definition-deleted";
+
+// Custom-field-VALUE events. Live auf host-aggregate stream (ES-Option-B).
+// Short-names werden via r.defineEvent qualified zu `custom-fields:event:
+// custom-field-set` etc. (qualifyEntityName runs toKebab which collapses dots
+// to dashes — so the short-name MUST already be in dash form, otherwise
+// handler-built strings won't match the registry key).
+export const CUSTOM_FIELD_SET_EVENT = "custom-field-set";
+export const CUSTOM_FIELD_CLEARED_EVENT = "custom-field-cleared";
+
+// Extension-name für r.useExtension("customFields", "<entity>") — registriert
+// dass eine host-entity Custom-Fields haben darf.
+export const CUSTOM_FIELDS_EXTENSION = "customFields";
+
+// Default-RBAC der Value-Write- und List-Pfade. Apps mit eigenem Rollen-
+// Vokabular (publicstatus: "Admin"/"Editor" statt "TenantAdmin"/
+// "TenantMember") überschreiben via createCustomFieldsFeature({
+// valueWriteRoles, fieldDefinitionListRoles }) — sonst sind die hart
+// verdrahteten Bundle-QNs, die die CustomFieldsFormSection dispatcht,
+// für jeden App-User access_denied.
+export const DEFAULT_VALUE_WRITE_ROLES = ["TenantAdmin", "TenantMember"] as const;
+export const DEFAULT_FIELD_DEFINITION_LIST_ROLES = ["TenantAdmin"] as const;
+// Default-RBAC of the definition-CRUD triad (define-/update-/delete-tenant-field,
+// #2296). Apps with their own role vocabulary override via
+// createCustomFieldsFeature({ fieldDefinitionWriteRoles }) — otherwise those three
+// hard-wired handler QNs are access_denied for every app-user without a
+// "TenantAdmin" role (same Role-Naming-Drift as DEFAULT_VALUE_WRITE_ROLES above).
+export const DEFAULT_FIELD_DEFINITION_WRITE_ROLES = ["TenantAdmin"] as const;
+
+// Field-type union — identisch zu Stammfeld-Field-Type-System (Spec Z.59-73:
+// `Identisch zu Entity-Feld-Typen`). Builder-Reuse-Promise: was `r.field.X()`
+// kann, kann eine Custom-Field-Definition auch.
+export const SUPPORTED_FIELD_TYPES = [
+  "text",
+  "number",
+  "boolean",
+  "date",
+  "enum",
+  "money",
+  "embedded",
+] as const;
+export type SupportedFieldType = (typeof SUPPORTED_FIELD_TYPES)[number];

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

@@ -0,0 +1,17 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+export async function selectSerializedFieldDefinition(
+  runner: DbRunner,
+  tenantId: string,
+  entityName: string,
+  fieldKey: string,
+): Promise<unknown | null> {
+  const rows = await unsafeReadRetrying(
+    runner,
+    "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]; // @cast-boundary db-row
+  return first ? (first["serialized_field"] ?? null) : null;
+}