@cosmicdrift/kumiko-bundled-features 0.40.1 → 0.41.0

package/package.json

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

package/src/custom-fields/__tests__/feature.test.ts

@@ -123,3 +123,47 @@ describe("fieldDefinitionAggregateId determinism", () => {
     expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
   });
 });
+
+// Role-Naming-Drift (Wave J): die CustomFieldsFormSection dispatcht die
+// Bundle-QNs hart — Apps mit eigenem Rollen-Vokabular (publicstatus:
+// "Admin"/"Editor") müssen die Access-Rollen der Value-Writes + des
+// fieldDefinition-List-Queries überschreiben können, sonst ist jeder
+// Save/Load für App-User access_denied.
+describe("createCustomFieldsFeature access-options", () => {
+  function writeAccess(
+    feature: ReturnType<typeof createCustomFieldsFeature>,
+    nameMatch: string,
+  ): readonly string[] {
+    const entry = Object.entries(feature.writeHandlers).find(([qn]) => qn.includes(nameMatch));
+    if (!entry) throw new Error(`handler ${nameMatch} not registered`);
+    const access = entry[1].access;
+    if (!access || !("roles" in access)) throw new Error(`handler ${nameMatch} has no roles`);
+    return access.roles;
+  }
+
+  test("ohne Optionen: Singleton mit Default-Rollen", () => {
+    const feature = createCustomFieldsFeature();
+    expect(feature).toBe(createCustomFieldsFeature());
+    expect(writeAccess(feature, "set-custom-field")).toEqual(["TenantAdmin", "TenantMember"]);
+    expect(writeAccess(feature, "clear-custom-field")).toEqual(["TenantAdmin", "TenantMember"]);
+  });
+
+  test("valueWriteRoles überschreibt set- UND clear-custom-field", () => {
+    const feature = createCustomFieldsFeature({ valueWriteRoles: ["Admin", "Editor"] });
+    expect(writeAccess(feature, "set-custom-field")).toEqual(["Admin", "Editor"]);
+    expect(writeAccess(feature, "clear-custom-field")).toEqual(["Admin", "Editor"]);
+    // Definition-CRUD bleibt unberührt — dafür existieren App-Wrapper.
+    expect(writeAccess(feature, "define-tenant-field")).toEqual(["TenantAdmin"]);
+  });
+
+  test("fieldDefinitionListRoles überschreibt den List-Query (FormSection-Lade-Pfad)", () => {
+    const feature = createCustomFieldsFeature({ fieldDefinitionListRoles: ["Admin", "Editor"] });
+    const entry = Object.entries(feature.queryHandlers).find(([qn]) =>
+      qn.includes("field-definition:list"),
+    );
+    if (!entry) throw new Error("field-definition:list not registered");
+    const access = entry[1].access;
+    if (!access || !("roles" in access)) throw new Error("list-query has no roles");
+    expect(access.roles).toEqual(["Admin", "Editor"]);
+  });
+});

package/src/custom-fields/constants.ts

@@ -50,6 +50,15 @@ export const CUSTOM_FIELD_CLEARED_EVENT = "custom-field-cleared";
 // 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;
+
 // 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.

package/src/custom-fields/feature.ts

@@ -50,11 +50,15 @@ import {
   CUSTOM_FIELD_SET_EVENT,
   CUSTOM_FIELDS_EXTENSION,
   CUSTOM_FIELDS_FEATURE_NAME,
+  DEFAULT_FIELD_DEFINITION_LIST_ROLES,
   FIELD_DEFINITION_DELETED_EVENT,
 } from "./constants";
 import { fieldDefinitionEntity } from "./entity";
 import { customFieldClearedSchema, customFieldSetSchema } from "./events";
-import { clearCustomFieldHandler } from "./handlers/clear-custom-field.write";
+import {
+  clearCustomFieldHandler,
+  createClearCustomFieldHandler,
+} from "./handlers/clear-custom-field.write";
 import { defineSystemFieldHandler } from "./handlers/define-system-field.write";
 import {
   createDefineTenantFieldHandler,
@@ -62,11 +66,12 @@ import {
 } from "./handlers/define-tenant-field.write";
 import { deleteSystemFieldHandler } from "./handlers/delete-system-field.write";
 import { deleteTenantFieldHandler } from "./handlers/delete-tenant-field.write";
-import { setCustomFieldHandler } from "./handlers/set-custom-field.write";
+import {
+  createSetCustomFieldHandler,
+  setCustomFieldHandler,
+} from "./handlers/set-custom-field.write";
 import { updateTenantFieldHandler } from "./handlers/update-tenant-field.write";
 
-const tenantAdminAccess = { access: { roles: ["TenantAdmin"] } } as const;
-
 const fieldDefinitionDeletedSchema = z.object({
   entityName: z.string(),
   fieldKey: z.string(),
@@ -78,13 +83,21 @@ const fieldDefinitionDeletedSchema = z.object({
   tenantId: z.string().optional(),
 });
 
-// Shared registration body for both the singleton and the quota-variant.
-// Only the define-tenant-field handler differs (quota baked in or not); every
-// other entity/event/handler is registered identically here so a new
-// event/handler can never silently miss the quota variant.
+// Handler-/Access-Varianten die zwischen Singleton und Options-Variante
+// differieren können. Alles andere registriert registerCustomFields für
+// beide identisch, damit ein neues Event/Handler nie still die
+// Options-Variante verfehlt.
+type RegisterVariant = {
+  readonly defineTenantHandler: WriteHandlerDef;
+  readonly setHandler: WriteHandlerDef;
+  readonly clearHandler: WriteHandlerDef;
+  readonly fieldDefinitionListRoles: readonly string[];
+};
+
+// Shared registration body for both the singleton and the options-variant.
 function registerCustomFields(
   r: FeatureRegistrar<typeof CUSTOM_FIELDS_FEATURE_NAME>,
-  defineTenantHandler: WriteHandlerDef,
+  variant: RegisterVariant,
 ) {
   r.describe(
     "Tenant- and system-scoped custom field definitions with generic value storage on any host entity. Registers the `field-definition` entity (event-sourced CRUD via `define-tenant-field`, `define-system-field`, `update-tenant-field`, `delete-tenant-field`, `delete-system-field`) and two value write-handlers (`set-custom-field`, `clear-custom-field`) that emit `custom-fields:event:custom-field-set` / `custom-fields:event:custom-field-cleared` events on the host aggregate's stream. To attach custom fields to your own entity, call `wireCustomFieldsFor(r, entityName, entityTable)` in the host feature — this wires the JSONB projection, `postQuery` flattening hook, and search-payload extension. The host entity must declare a `customFieldsField()` JSONB column.",
@@ -113,19 +126,23 @@ function registerCustomFields(
   r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
 
   // Definition-CRUD handlers (B1; update kam mit Bug-Bash D2 2026-06-08).
-  r.writeHandler(defineTenantHandler);
+  r.writeHandler(variant.defineTenantHandler);
   r.writeHandler(defineSystemFieldHandler);
   r.writeHandler(updateTenantFieldHandler);
   r.writeHandler(deleteTenantFieldHandler);
   r.writeHandler(deleteSystemFieldHandler);
 
   // Value-write handlers (B2). Emittieren events auf host-aggregate-stream.
-  r.writeHandler(setCustomFieldHandler);
-  r.writeHandler(clearCustomFieldHandler);
+  r.writeHandler(variant.setHandler);
+  r.writeHandler(variant.clearHandler);
 
-  // List-Query — tenant-scoped (B1-limit).
+  // List-Query — tenant-scoped (B1-limit). Die CustomFieldsFormSection
+  // dispatcht diesen QN hart — Apps mit eigenem Rollen-Vokabular
+  // überschreiben die Rollen via fieldDefinitionListRoles.
   r.queryHandler(
-    defineEntityListHandler("field-definition", fieldDefinitionEntity, tenantAdminAccess),
+    defineEntityListHandler("field-definition", fieldDefinitionEntity, {
+      access: { roles: variant.fieldDefinitionListRoles },
+    }),
   );
 
   return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
@@ -137,29 +154,54 @@ function registerCustomFields(
 // (feature.ts -> handlers/*.write.ts -> feature.ts) löst sich auf weil
 // kein top-level-access stattfindet.
 export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
-  registerCustomFields(r, defineTenantFieldHandler),
+  registerCustomFields(r, {
+    defineTenantHandler: defineTenantFieldHandler,
+    setHandler: setCustomFieldHandler,
+    clearHandler: clearCustomFieldHandler,
+    fieldDefinitionListRoles: DEFAULT_FIELD_DEFINITION_LIST_ROLES,
+  }),
 );
 
+export type CustomFieldsFeatureOptions = {
+  /** T1.5e: Quota für define-tenant-field. */
+  readonly fieldDefinitionLimitPerTenant?: number;
+  /** Rollen für set-/clear-custom-field — die Save-Pfade der
+   *  CustomFieldsFormSection. Default ["TenantAdmin","TenantMember"];
+   *  Apps mit eigenem Rollen-Vokabular (z.B. ["Admin","Editor"]) MÜSSEN
+   *  das setzen, sonst ist der Value-Save für jeden App-User
+   *  access_denied (Role-Naming-Drift). */
+  readonly valueWriteRoles?: readonly string[];
+  /** Rollen für custom-fields:query:field-definition:list — der
+   *  Lade-Pfad der CustomFieldsFormSection. Default ["TenantAdmin"]. */
+  readonly fieldDefinitionListRoles?: readonly string[];
+};
+
 // Backwards-compat-wrapper. Bestehende Caller (z.B. integration-tests,
 // host-apps) nutzen weiterhin `createCustomFieldsFeature()`. Returnt den
 // module-level-Singleton — kein neuer build pro Aufruf, was für consumer
-// nicht erkennbar ist (read-only inspection).
-//
-// **T1.5e options**: when `fieldDefinitionLimitPerTenant` is set, the
-// returned feature carries a fresh `define-tenant-field` handler with the
-// quota baked in. Callers that don't pass options get the singleton — no
-// change in behavior.
+// nicht erkennbar ist (read-only inspection). Jede gesetzte Option baut
+// eine frische Feature-Definition mit den Varianten-Handlern.
 export function createCustomFieldsFeature(
-  opts: { readonly fieldDefinitionLimitPerTenant?: number } = {},
+  opts: CustomFieldsFeatureOptions = {},
 ): typeof customFieldsFeature {
-  if (opts.fieldDefinitionLimitPerTenant === undefined) {
+  const hasOptions =
+    opts.fieldDefinitionLimitPerTenant !== undefined ||
+    opts.valueWriteRoles !== undefined ||
+    opts.fieldDefinitionListRoles !== undefined;
+  if (!hasOptions) {
     return customFieldsFeature;
   }
   const limit = opts.fieldDefinitionLimitPerTenant;
   return defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
-    registerCustomFields(
-      r,
-      createDefineTenantFieldHandler({ fieldDefinitionLimitPerTenant: limit }),
-    ),
+    registerCustomFields(r, {
+      defineTenantHandler:
+        limit !== undefined
+          ? createDefineTenantFieldHandler({ fieldDefinitionLimitPerTenant: limit })
+          : defineTenantFieldHandler,
+      setHandler: createSetCustomFieldHandler(opts.valueWriteRoles),
+      clearHandler: createClearCustomFieldHandler(opts.valueWriteRoles),
+      fieldDefinitionListRoles:
+        opts.fieldDefinitionListRoles ?? DEFAULT_FIELD_DEFINITION_LIST_ROLES,
+    }),
   );
 }

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

@@ -1,6 +1,7 @@
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
+import { DEFAULT_VALUE_WRITE_ROLES } from "../constants";
 import { customFieldsFeature } from "../feature";
 import { checkFieldAccessForWrite } from "../lib/field-access";
 
@@ -25,7 +26,7 @@ export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSche
 export const clearCustomFieldHandler: WriteHandlerDef = {
   name: "clear-custom-field",
   schema: clearCustomFieldPayloadSchema,
-  access: { roles: ["TenantAdmin", "TenantMember"] },
+  access: { roles: DEFAULT_VALUE_WRITE_ROLES },
   handler: async (event, ctx) => {
     const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
 
@@ -62,3 +63,11 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
     };
   },
 };
+
+/** Pendant zu createSetCustomFieldHandler — gleiche Rollen für set + clear,
+ *  ein Wert ohne Clear-Recht wäre nur halb beherrschbar. */
+export function createClearCustomFieldHandler(
+  roles: readonly string[] = DEFAULT_VALUE_WRITE_ROLES,
+): WriteHandlerDef {
+  return { ...clearCustomFieldHandler, access: { roles } };
+}

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

@@ -1,6 +1,7 @@
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
+import { DEFAULT_VALUE_WRITE_ROLES } from "../constants";
 import { customFieldsFeature } from "../feature";
 import { fieldWriteAccessDeniedRoles, loadFieldDefinition } from "../lib/field-access";
 import { buildCustomFieldValueSchema } from "../lib/value-schema";
@@ -48,7 +49,7 @@ export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 export const setCustomFieldHandler: WriteHandlerDef = {
   name: "set-custom-field",
   schema: setCustomFieldPayloadSchema,
-  access: { roles: ["TenantAdmin", "TenantMember"] },
+  access: { roles: DEFAULT_VALUE_WRITE_ROLES },
   handler: async (event, ctx) => {
     const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload
 
@@ -102,3 +103,12 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     };
   },
 };
+
+/** Value-Write mit App-Rollen statt der Bundle-Defaults — Apps mit eigenem
+ *  Rollen-Vokabular (z.B. "Admin"/"Editor") reichen ihre Rollen über
+ *  createCustomFieldsFeature({ valueWriteRoles }) hierher durch. */
+export function createSetCustomFieldHandler(
+  roles: readonly string[] = DEFAULT_VALUE_WRITE_ROLES,
+): WriteHandlerDef {
+  return { ...setCustomFieldHandler, access: { roles } };
+}

package/src/custom-fields/index.ts

@@ -14,7 +14,11 @@ export {
   customFieldClearedSchema,
   customFieldSetSchema,
 } from "./events";
-export { createCustomFieldsFeature, customFieldsFeature } from "./feature";
+export {
+  type CustomFieldsFeatureOptions,
+  createCustomFieldsFeature,
+  customFieldsFeature,
+} from "./feature";
 export {
   type ClearCustomFieldPayload,
   clearCustomFieldPayloadSchema,