@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/crypto-shredding/handlers/forget-subject.write.js

@@ -0,0 +1,292 @@
+import { createHash } from "node:crypto";
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { configuredPiiSubjectKms, subjectIdSchema, subjectIdToKey, } from "@cosmicdrift/kumiko-framework/crypto";
+import { nullBlindIndexesForSubject, recordRowExistsInTenant, subjectRowExistsInTenant, } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError, InternalError, 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 { 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),
+    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),
+});
+// Exhaustive switch so a 4th subject kind fails to compile instead of
+// silently aggregating under the wrong id.
+function subjectAggregateId(raw) {
+    switch (raw.kind) {
+        case "user":
+            return raw.userId;
+        case "tenant":
+            return raw.tenantId;
+        case "record":
+            return raw.id;
+        default: {
+            const exhaustiveCheck = 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, entityName) {
+    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, features, user, raw) {
+    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);
+        if (!entity) {
+            return writeFailure(new AccessDeniedError({ details: { reason: RECORD_ENTITY_NOT_REGISTERED } }));
+        }
+        const ownedInTenant = await recordRowExistsInTenant(db, features, raw.entity, raw.id, user.tenantId);
+        return ownedInTenant
+            ? undefined
+            : writeFailure(new AccessDeniedError({ details: { reason: TARGET_RECORD_NOT_ADMIN_TENANT } }));
+    }
+    // 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: the host entity's OWN retention declaration gets the last word on
+// a targeted row-shred — blockDelete (legally mandated physical retention,
+// e.g. ledger/invoice text) means this command must refuse, not silently
+// anonymize or proceed. Deliberately independent of the tenant feature/gate
+// above: a retention obligation holds in single-tenant apps too, and running
+// unconditionally (not nested under `features.has("tenant")`) keeps that
+// true. Only the entity's declared `retention.strategy` is consulted here —
+// NOT the data-retention feature's tenant-preset/override layering
+// (resolveRetentionPolicy) — so a tenant cannot override its own way past a
+// blockDelete declared on the entity.
+function resolveRetentionDenial(features, raw) {
+    if (raw.kind !== "record")
+        return undefined;
+    const entity = findRegisteredEntity(features, raw.entity);
+    if (entity?.retention?.strategy !== "blockDelete")
+        return undefined;
+    return writeFailure(new AccessDeniedError({ details: { reason: TARGET_RECORD_RETENTION_BLOCK_DELETE } }));
+}
+// 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, event, subjectKey, subjectKind, denialCode, denialAuditRunner) {
+    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 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 still lets an operator correlate repeated probes of the same
+        // subject without exposing it (fw#2452).
+        subjectKeyDigest: createHash("sha256").update(subjectKey, "utf8").digest("base64url"),
+        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: {
+        reason: "denial audit append names the prober's own tenant stream on the outside-transaction db; " +
+            "the tenant-scope check runs 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 = 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, tenantScopeDenial.error.code, 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 (VORHER only means "before the shred"): a
+        // retention check ahead of the tenant gate would leak a foreign
+        // entity's retention posture to a cross-tenant prober.
+        const retentionDenial = resolveRetentionDenial(ctx.registry.features, raw);
+        if (retentionDenial) {
+            // Own reason constant, not tenantScopeDenial's `.error.code` pattern:
+            // AccessDeniedError.code is the generic "access_denied" for every
+            // branch, so re-deriving it here would make a blockDelete refusal
+            // indistinguishable from a cross-tenant one in the audit trail.
+            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, data: { subjectKey } };
+    },
+});

package/dist/crypto-shredding/index.d.ts

@@ -0,0 +1,3 @@
+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/dist/crypto-shredding/index.js

@@ -0,0 +1,3 @@
+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/dist/custom-fields/aggregate-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export declare function fieldDefinitionAggregateId(tenantId: string, entityName: string, fieldKey: string): string;

package/dist/custom-fields/aggregate-id.js

@@ -0,0 +1,28 @@
+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, entityName, fieldKey) {
+    return uuidv5(`${tenantId}|${entityName}|${fieldKey}`, FIELD_DEFINITION_NAMESPACE);
+}

package/dist/custom-fields/constants.d.ts

@@ -0,0 +1,25 @@
+export declare const CUSTOM_FIELDS_FEATURE_NAME = "custom-fields";
+export declare const CustomFieldsHandlers: {
+    readonly defineTenantField: "custom-fields:write:define-tenant-field";
+    readonly defineSystemField: "custom-fields:write:define-system-field";
+    readonly deleteTenantField: "custom-fields:write:delete-tenant-field";
+    readonly deleteSystemField: "custom-fields:write:delete-system-field";
+    readonly setCustomField: "custom-fields:write:set-custom-field";
+    readonly clearCustomField: "custom-fields:write:clear-custom-field";
+};
+export declare const CustomFieldsQueries: {
+    readonly fieldDefinitionList: "custom-fields:query:field-definition:list";
+};
+export declare const CUSTOM_FIELDS_FORM_EXTENSION_NAME = "CustomFieldsFormSection";
+export declare const FIELD_DEFINITION_AGGREGATE_TYPE = "field-definition";
+export declare const FIELD_DEFINITION_CREATED_EVENT = "field-definition.created";
+export declare const FIELD_DEFINITION_UPDATED_EVENT = "field-definition.updated";
+export declare const FIELD_DEFINITION_DELETED_EVENT = "field-definition-deleted";
+export declare const CUSTOM_FIELD_SET_EVENT = "custom-field-set";
+export declare const CUSTOM_FIELD_CLEARED_EVENT = "custom-field-cleared";
+export declare const CUSTOM_FIELDS_EXTENSION = "customFields";
+export declare const DEFAULT_VALUE_WRITE_ROLES: readonly ["TenantAdmin", "TenantMember"];
+export declare const DEFAULT_FIELD_DEFINITION_LIST_ROLES: readonly ["TenantAdmin"];
+export declare const DEFAULT_FIELD_DEFINITION_WRITE_ROLES: readonly ["TenantAdmin"];
+export declare const SUPPORTED_FIELD_TYPES: readonly ["text", "number", "boolean", "date", "enum", "money", "embedded"];
+export type SupportedFieldType = (typeof SUPPORTED_FIELD_TYPES)[number];

package/dist/custom-fields/constants.js

@@ -0,0 +1,72 @@
+// @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",
+};
+export const CustomFieldsQueries = {
+    fieldDefinitionList: "custom-fields:query:field-definition:list",
+};
+// Name the web component registers under in ExtensionSectionsProvider —
+// apps reference it in the screen schema via:
+// { kind: "extension", title, contributesToFormSubmit: true,
+//   component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } } }
+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"];
+export const DEFAULT_FIELD_DEFINITION_LIST_ROLES = ["TenantAdmin"];
+// 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"];
+// 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",
+];

package/dist/custom-fields/db/queries/field-access.d.ts

@@ -0,0 +1,2 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+export declare function selectSerializedFieldDefinition(runner: DbRunner, tenantId: string, entityName: string, fieldKey: string): Promise<unknown | null>;

package/dist/custom-fields/db/queries/field-access.js

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

package/dist/custom-fields/db/queries/projection.d.ts

@@ -0,0 +1,6 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+export declare function setCustomFieldValue(db: DbRunner, tableName: string, fieldKey: string, value: unknown, aggregateId: string, tenantId: TenantId): Promise<void>;
+export declare function clearCustomFieldKey(db: DbRunner, tableName: string, fieldKey: string, aggregateId: string, tenantId: TenantId): Promise<void>;
+export declare function removeCustomFieldKeyForTenant(db: DbRunner, tableName: string, fieldKey: string, tenantId: TenantId): Promise<void>;
+export declare function removeCustomFieldKeyFromAllTenants(db: DbRunner, tableName: string, fieldKey: string): Promise<void>;

package/dist/custom-fields/db/queries/projection.js

@@ -0,0 +1,45 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+function quoteTable(tableName) {
+    return `"${tableName.replace(/"/g, '""')}"`;
+}
+function bindJsonbParam(value) {
+    // Scalar JSON primitives can't bind directly to ::jsonb — Postgres rejects a
+    // bound boolean/number with "cannot cast type boolean/integer to jsonb" (and
+    // Bun.SQL infers boolean[] candidates). Route them through ::text::jsonb with
+    // a JSON-encoded literal. Objects/arrays/strings already bind as ::jsonb.
+    if (typeof value === "boolean" || typeof value === "number") {
+        return { sql: "$1::text::jsonb", bound: JSON.stringify(value) };
+    }
+    // JSON.stringify throws on bigint; its decimal string is a valid JSON number literal.
+    if (typeof value === "bigint") {
+        return { sql: "$1::text::jsonb", bound: value.toString() };
+    }
+    return { sql: "$1::jsonb", bound: value };
+}
+// Security invariant: aggregateId is a global row UUID, so without the tenant_id
+// filter tenant A could mutate tenant B's row by its UUID (cf. removeCustomFieldKeyForTenant).
+export async function setCustomFieldValue(db, tableName, fieldKey, value, aggregateId, tenantId) {
+    const tbl = quoteTable(tableName);
+    const escapedKey = fieldKey.replace(/'/g, "''");
+    const jsonb = bindJsonbParam(value);
+    await asRawClient(db).unsafe(`UPDATE ${tbl} SET custom_fields = jsonb_set(custom_fields, '{${escapedKey}}', ${jsonb.sql}, true) WHERE id = $2 AND tenant_id = $3`, [jsonb.bound, aggregateId, tenantId]);
+}
+export async function clearCustomFieldKey(db, tableName, fieldKey, aggregateId, tenantId) {
+    const tbl = quoteTable(tableName);
+    await asRawClient(db).unsafe(`UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE id = $2 AND tenant_id = $3`, [fieldKey, aggregateId, tenantId]);
+}
+// Tenant-scoped orphan-cleanup: removes the jsonb key only from the deleting
+// tenant's rows. This is the default path for tenant-field deletions — without
+// the tenant_id filter, deleting tenant A's field strips the same kebab key
+// from every tenant's rows (cross-tenant data loss).
+export async function removeCustomFieldKeyForTenant(db, tableName, fieldKey, tenantId) {
+    const tbl = quoteTable(tableName);
+    await asRawClient(db).unsafe(`UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE tenant_id = $2`, [fieldKey, tenantId]);
+}
+// Cross-tenant cleanup: strips the key from EVERY tenant's rows. Only valid for
+// system-scope field-definition deletions (the field applied to all tenants).
+// Never call this for a tenant-scoped deletion — use removeCustomFieldKeyForTenant.
+export async function removeCustomFieldKeyFromAllTenants(db, tableName, fieldKey) {
+    const tbl = quoteTable(tableName);
+    await asRawClient(db).unsafe(`UPDATE ${tbl} SET custom_fields = custom_fields - $1`, [fieldKey]);
+}

package/dist/custom-fields/db/queries/quota.d.ts

@@ -0,0 +1,2 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+export declare function countTenantFieldDefinitions(runner: DbRunner, tenantId: string): Promise<number>;

package/dist/custom-fields/db/queries/quota.js

@@ -0,0 +1,12 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+export async function countTenantFieldDefinitions(runner, tenantId) {
+    // Active definitions only — delete soft-deletes (the deterministic stream is
+    // kept so a re-define can restore it), so isDeleted rows must not consume quota.
+    const rowsResult = await unsafeReadRetrying(runner, "SELECT COUNT(*)::int AS n FROM read_custom_field_definitions WHERE tenant_id = $1 AND is_deleted = FALSE", [tenantId]);
+    const rows = rowsResult; // @cast-boundary db-row
+    const first = rows[0];
+    if (!first)
+        return 0;
+    const n = first["n"];
+    return typeof n === "number" ? n : Number.parseInt(String(n ?? 0), 10);
+}

package/dist/custom-fields/db/queries/retention.d.ts

@@ -0,0 +1,3 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+export declare function selectHostRowsWithCustomFields(db: DbRunner, tableName: string, tenantId: string): Promise<readonly unknown[]>;
+export declare function applyRetentionRemovals(db: DbRunner, tableName: string, deleteKeys: readonly string[], anonymizeKeys: readonly string[], rowId: string): Promise<void>;

package/dist/custom-fields/db/queries/retention.js

@@ -0,0 +1,23 @@
+import { asRawClient, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+export async function selectHostRowsWithCustomFields(db, tableName, tenantId) {
+    const quoted = `"${tableName.replace(/"/g, '""')}"`;
+    const rowsResult = await unsafeReadRetrying(db, `SELECT id, modified_at, custom_fields FROM ${quoted} WHERE tenant_id = $1 AND custom_fields IS NOT NULL`, [tenantId]);
+    return Array.isArray(rowsResult) ? rowsResult : [];
+}
+export async function applyRetentionRemovals(db, tableName, deleteKeys, anonymizeKeys, rowId) {
+    const quoted = `"${tableName.replace(/"/g, '""')}"`;
+    // Atomic per-row jsonb edit instead of read-modify-write of the whole
+    // object: delete-keys are dropped (`- $1::text[]`), anonymize-keys are set
+    // to JSON null via a merge patch. Operating on the live row value preserves
+    // a concurrent set-custom-field on any *other* key — no lost update.
+    await asRawClient(db).unsafe(`UPDATE ${quoted} SET custom_fields = CASE
+       WHEN jsonb_typeof(custom_fields) = 'object' THEN
+         (custom_fields - $1::text[])
+         || COALESCE(
+              (SELECT jsonb_object_agg(k, 'null'::jsonb) FROM unnest($2::text[]) AS k),
+              '{}'::jsonb
+            )
+       ELSE custom_fields
+     END
+     WHERE id = $3`, [deleteKeys, anonymizeKeys, rowId]);
+}

package/dist/custom-fields/db/queries/user-data-rights.d.ts

@@ -0,0 +1,6 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+export declare function selectCustomFieldsHostRows(db: DbRunner, tableName: string, userIdColumn: string, userId: string, tenantId: string): Promise<readonly unknown[]>;
+export declare function selectFieldDefinitionsForEntity(db: DbRunner, entityName: string, tenantId: string): Promise<readonly {
+    field_key: string;
+    serialized_field: unknown;
+}[]>;

package/dist/custom-fields/db/queries/user-data-rights.js

@@ -0,0 +1,16 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+function quoteTable(tableName) {
+    return `"${tableName.replace(/"/g, '""')}"`;
+}
+function quoteColumn(columnName) {
+    return `"${columnName.replace(/"/g, '""')}"`;
+}
+export async function selectCustomFieldsHostRows(db, tableName, userIdColumn, userId, tenantId) {
+    const tbl = quoteTable(tableName);
+    const userCol = quoteColumn(userIdColumn);
+    const rowsResult = await unsafeReadRetrying(db, `SELECT id, custom_fields FROM ${tbl} WHERE ${userCol} = $1 AND tenant_id = $2`, [userId, tenantId]);
+    return Array.isArray(rowsResult) ? rowsResult : [];
+}
+export async function selectFieldDefinitionsForEntity(db, entityName, tenantId) {
+    return unsafeReadRetrying(db, "SELECT field_key, serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND tenant_id = $2", [entityName, tenantId]);
+}