@cosmicdrift/kumiko-framework 0.2.1 → 0.2.3

package/src/engine/__tests__/boot-validator-s0-integration.test.ts

@@ -0,0 +1,160 @@
+// Integration-Test: alle Sprint-0-Surfaces in einem Mini-Feature-Set.
+//
+// Beweist dass die einzelnen S0-Komponenten (PII-Annotations, retention,
+// extension-names, exposesApi/usesApi, ROLES) zusammen funktionieren —
+// keine still-konkurrierenden Validierungen, keine Race-Conditions
+// zwischen Sub-Validatoren.
+//
+// Mini-Feature-Set:
+//   compliance-profiles  exposesApi("compliance.forTenant")
+//   user-data-rights     usesApi + extendsRegistrar(EXT_USER_DATA)
+//   tenant               useExtension(EXT_USER_DATA, "user", ...)
+//                        + entity mit pii / userOwned / tenantOwned-Fields
+//                        + retention.blockDelete + anonymize-Funktion
+//                        + handler-access mit ROLES.TenantAdmin
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { z } from "zod";
+import { ROLES } from "../../auth";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import {
+  createEntity,
+  createLongTextField,
+  createTextField,
+  createTimestampField,
+  EXT_USER_DATA,
+} from "../index";
+
+describe("S0 Integration — full surface stack", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("alle S0-Surfaces zusammen passen Boot-Validation", () => {
+    const complianceProfiles = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+      r.queryHandler({
+        name: "compliance:query:for-tenant",
+        schema: z.object({}),
+        handler: async () => ({ profile: "eu-dsgvo" }) as never,
+        access: { openToAll: true },
+      });
+    });
+
+    const userDataRights = defineFeature("user-data-rights", (r) => {
+      r.requires("compliance-profiles");
+      r.usesApi("compliance.forTenant");
+      r.extendsRegistrar(EXT_USER_DATA, {
+        hooks: {},
+      });
+    });
+
+    const tenantFeature = defineFeature("tenant-app", (r) => {
+      r.requires("user-data-rights", "compliance-profiles");
+
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true }),
+            displayName: createTextField({ pii: true }),
+            lastLoginAt: createTimestampField({ pii: true }),
+          },
+          retention: {
+            keepFor: "10y",
+            strategy: "blockDelete",
+            reference: "createdAt",
+          },
+        }),
+      );
+
+      r.entity(
+        "comment",
+        createEntity({
+          fields: {
+            body: createLongTextField({
+              userOwned: { ownerField: "authorId" },
+              anonymize: () => "[ANONYMIZED]",
+            }),
+            authorId: { type: "reference", entity: "user" },
+          },
+        }),
+      );
+
+      r.queryHandler({
+        name: "user:list",
+        schema: z.object({}),
+        handler: async () => ({ rows: [], nextCursor: null }) as never,
+        access: { openToAll: true },
+      });
+
+      r.useExtension(EXT_USER_DATA, "user", {});
+      r.useExtension(EXT_USER_DATA, "comment", {});
+
+      r.writeHandler({
+        name: "user:rename",
+        schema: z.object({ id: z.string(), displayName: z.string() }),
+        handler: async () => undefined as never,
+        access: { roles: [ROLES.TenantAdmin] },
+      });
+    });
+
+    expect(() => validateBoot([complianceProfiles, userDataRights, tenantFeature])).not.toThrow();
+  });
+
+  test("missing requires() on usesApi-target throws even when other surfaces are clean", () => {
+    const complianceProfiles = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+
+    const userDataRights = defineFeature("user-data-rights", (r) => {
+      // VERGESSEN: r.requires("compliance-profiles")
+      r.usesApi("compliance.forTenant");
+    });
+
+    expect(() => validateBoot([complianceProfiles, userDataRights])).toThrow(
+      /not in requires\/optionalRequires\. Add r\.requires\("compliance-profiles"\)/,
+    );
+  });
+
+  test("retention.reference pointing to non-existent field throws even with valid PII annotations", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true }),
+          },
+          retention: {
+            keepFor: "30d",
+            strategy: "hardDelete",
+            reference: "notARealField",
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /retention\.reference "notARealField" does not exist/,
+    );
+  });
+
+  test("ROLES.TenantAdmin works as handler-access role string (no Admin/TenantAdmin drift)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ fields: { ts: createTimestampField() } }));
+      r.writeHandler({
+        name: "thing:create",
+        schema: z.object({}),
+        handler: async () => undefined as never,
+        access: { roles: [ROLES.TenantAdmin] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

package/src/engine/boot-validator.ts

@@ -8,10 +8,76 @@ import type {
   NavDefinition,
   WorkspaceDefinition,
 } from "./types";
+import type { PiiAnnotations } from "./types/fields";
 import { normalizeEditField, normalizeListColumn } from "./types/screen";
 
 const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
 
+// Field-Namen die typischerweise PII enthalten. Ohne `pii: true` /
+// `userOwned` / `tenantOwned` / `allowPlaintext`-Marker → Boot-Warning.
+// Lower-case compare für case-insensitive Match (displayName vs displayname).
+//
+// Bewusst NICHT in der Liste:
+//   - `name` allein — zu viele Geschäfts-Kontexte (product.name,
+//     tenant.name, role.name) sind kein PII. Personen-Namen werden
+//     ueber displayName / firstName / lastName / fullName erfasst.
+//
+// Quelle: docs/plans/datenschutz/crypto-shredding.md Boot-Validation-Sektion.
+const PII_DIRECT_NAME_HINTS: ReadonlySet<string> = new Set([
+  "email",
+  "phone",
+  "phonenumber",
+  "mobile",
+  "address",
+  "street",
+  "postalcode",
+  "zipcode",
+  "zip",
+  "city",
+  "displayname",
+  "firstname",
+  "lastname",
+  "fullname",
+  "birthday",
+  "birthdate",
+  "dateofbirth",
+  "dob",
+  "ssn",
+  "taxid",
+  "vatid",
+  "passport",
+  "iban",
+  "bic",
+]);
+
+// Field-Namen die typischerweise User-Generated-Content enthalten —
+// User-Forget muss diese mit Author-Subject-Key encrypten.
+const PII_USER_OWNED_NAME_HINTS: ReadonlySet<string> = new Set([
+  "body",
+  "text",
+  "content",
+  "message",
+  "comment",
+  "description",
+  "note",
+  "notes",
+]);
+
+// Framework-managed Timestamp-Spalten — dürfen als retention.reference
+// genutzt werden auch wenn nicht in entity.fields deklariert.
+const FRAMEWORK_TIMESTAMP_FIELDS: ReadonlySet<string> = new Set([
+  "createdAt",
+  "updatedAt",
+  "lastSeenAt",
+  "deletedAt",
+]);
+
+// Erlaubtes Format fuer retention.keepFor — Zahlen + Suffix (h/d/w/m/y).
+// Echtes Parsen kommt mit dem Cleanup-Job in Sprint 2; Boot-Validator
+// macht nur den Sanity-Check damit Tippfehler ("30days") frueh sichtbar
+// werden statt erst beim ersten Cleanup-Run.
+const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
+
 /**
  * Validates all feature configurations at boot time.
  * Throws on the first error found — fail fast.
@@ -71,6 +137,24 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   const allWorkspaceQns = collectWorkspaceQns(features);
   const allWriteHandlerQns = collectWriteHandlerQns(features);
 
+  // Cross-feature API exposure-map — jedes Feature deklariert Marker via
+  // r.exposesApi(name). Per-feature validateApiExposureMatching walkt
+  // usedApis-Set und checkt dass jeder Eintrag hier einen Match findet.
+  // Verhindert dass typo-getroffene oder gedroppte QN-Aufrufe zu
+  // Runtime-Crash statt Boot-Fail werden.
+  const allExposedApis = new Map<string, string>(); // apiName → providerFeature
+  for (const f of features) {
+    for (const apiName of f.exposedApis) {
+      const existing = allExposedApis.get(apiName);
+      if (existing && existing !== f.name) {
+        throw new Error(
+          `Cross-feature API "${apiName}" exposed by both "${existing}" and "${f.name}" — API names must be globally unique.`,
+        );
+      }
+      allExposedApis.set(apiName, f.name);
+    }
+  }
+
   let hasEncryptedFields = false;
   let hasFileFields = false;
 
@@ -78,6 +162,8 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
     validateCircularDeps(feature.name, featureMap);
     if (validateEncryptedFields(feature)) hasEncryptedFields = true;
     if (validateFileFields(feature)) hasFileFields = true;
+    validatePiiAndRetention(feature);
+    validateApiExposureMatching(feature, allExposedApis, featureMap);
     validateEmbeddedFields(feature);
     validateMultiSelectFields(feature);
     validateReferenceFields(feature, featureMap);
@@ -498,6 +584,196 @@ function validateFileFields(feature: FeatureDefinition): boolean {
   return false;
 }
 
+// --- PII / Subject-Key Annotations + Retention validation ---
+//
+// Drei Klassen von Checks:
+//
+// 1. Mutual exclusion: pro Field nur EINE der drei Subject-Annotations
+//    (pii / userOwned / tenantOwned). Mehr ist semantisch widersprüchlich
+//    weil pro Field genau ein Subject-Key gehört.
+//
+// 2. Reference-Integrity: userOwned.ownerField muss auf ein existierendes
+//    reference-Field zeigen (das auf user-Entity zeigen sollte). Erkennt
+//    Tippfehler und Drop-Refactorings beim Boot statt beim ersten
+//    Encrypt-Aufruf.
+//
+// 3. Heuristik-Warnings: Field-Namen die typischerweise PII enthalten
+//    (email, name, phone, body, etc.) ohne Annotation → Boot-Warning.
+//    Mit `allowPlaintext: "<reason>"` unterdrückbar (geht in Audit).
+//
+// 4. Retention-Integrity: retention.reference (wenn gesetzt) muss auf
+//    ein bestehendes Field zeigen (oder Framework-Timestamp). retention.
+//    strategy="blockDelete" ohne anonymize-Felder ist sinnlos — User-
+//    Forget kann nichts machen, Warning.
+//
+// Encrypt/Decrypt-Mechanik landet in Sprint 3 (crypto-shredding); diese
+// Validation greift schon ab Sprint 0 damit Schema-Drift früh auffällt.
+function validatePiiAndRetention(feature: FeatureDefinition): void {
+  for (const [entityName, entity] of Object.entries(feature.entities)) {
+    const fieldsByName = entity.fields;
+
+    for (const [fieldName, field] of Object.entries(fieldsByName)) {
+      // PiiAnnotations-Properties sind type-level optional. Auf Field-
+      // Defs die nicht via "& PiiAnnotations" erweitert sind (Boolean,
+      // Money, Reference, Embedded, Tz, LocatedTimestamp, File*, Image*)
+      // liefert property-access undefined zur Runtime. Die TS-Compile-
+      // Time-Validation hat dort schon abgelehnt → Cast ist safe.
+      const annot = field as PiiAnnotations;
+
+      const hasPii = Boolean(annot.pii);
+      const hasUserOwned = Boolean(annot.userOwned);
+      const hasTenantOwned = Boolean(annot.tenantOwned);
+      const annotCount = (hasPii ? 1 : 0) + (hasUserOwned ? 1 : 0) + (hasTenantOwned ? 1 : 0);
+
+      if (annotCount > 1) {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has multiple subject-key annotations (pii / userOwned / tenantOwned). Pick one — each field belongs to exactly one subject.`,
+        );
+      }
+
+      if (annot.userOwned) {
+        const ownerName = annot.userOwned.ownerField;
+        if (!ownerName || typeof ownerName !== "string") {
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has userOwned without ownerField name`,
+          );
+        }
+        const ownerField = fieldsByName[ownerName];
+        if (!ownerField) {
+          const known = Object.keys(fieldsByName).sort().join(", ");
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references userOwned.ownerField "${ownerName}" but no such field exists. Known fields: ${known}`,
+          );
+        }
+        if (ownerField.type !== "reference") {
+          throw new Error(
+            `[Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" must be a reference field, got type "${ownerField.type}"`,
+          );
+        }
+        // Soft-Warning wenn das reference-target nicht offensichtlich user
+        // ist — custom subject-entities (HR-Mitarbeiter, Patient) sind
+        // erlaubt, müssen aber bewusste Wahl sein.
+        const refTarget = ownerField.entity;
+        const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
+        if (targetEntity !== "user") {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`,
+          );
+        }
+      }
+
+      // PII-Heuristik: nur wenn keine Annotation gesetzt UND kein
+      // allowPlaintext-Marker. Ergibt false positives auf Geschäftsdaten
+      // mit personenartigem Namen (z.B. company.legalName) — Author
+      // unterdrückt mit { allowPlaintext: "is-business-data" }.
+      const noAnnotation = annotCount === 0 && !annot.allowPlaintext;
+      if (noAnnotation) {
+        const lower = fieldName.toLowerCase();
+        if (PII_DIRECT_NAME_HINTS.has(lower)) {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no { pii: true } annotation. If this is PII, mark it. If business data, set { allowPlaintext: "is-business-data" } to silence.`,
+          );
+        } else if (PII_USER_OWNED_NAME_HINTS.has(lower)) {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no { userOwned } annotation. If this contains user-generated content, mark it { userOwned: { ownerField: "<authorIdField>" }}. If business data, set { allowPlaintext: "..." } to silence.`,
+          );
+        }
+      }
+    }
+
+    // --- Entity-level retention ---
+    const retention = entity.retention;
+    if (retention) {
+      if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
+        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+        console.warn(
+          `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.keepFor="${retention.keepFor}" hat ungueltiges Format. Erwartet: <Zahl><h|d|w|m|y> (z.B. "30d", "10y", "6m"). Cleanup-Job (Sprint 2) wird das nicht parsen koennen.`,
+        );
+      }
+
+      if (retention.reference !== undefined) {
+        const refName = retention.reference;
+        if (!fieldsByName[refName] && !FRAMEWORK_TIMESTAMP_FIELDS.has(refName)) {
+          const known = Object.keys(fieldsByName).sort().join(", ");
+          const framework = [...FRAMEWORK_TIMESTAMP_FIELDS].sort().join(", ");
+          throw new Error(
+            `[Feature ${feature.name}] Entity "${entityName}" retention.reference "${refName}" does not exist. Known fields: ${known} — framework-managed timestamps also accepted: ${framework}`,
+          );
+        }
+      }
+
+      if (retention.strategy === "blockDelete") {
+        const hasAnonymize = Object.values(fieldsByName).some((f) => {
+          const a = f as PiiAnnotations;
+          return Boolean(a.anonymize);
+        });
+        if (!hasAnonymize) {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`,
+          );
+        }
+      }
+    }
+  }
+}
+
+// --- Cross-feature API exposure / usage matching ---
+//
+// `r.exposesApi(name, impl)` registers a callable; `r.usesApi(name)`
+// declares a caller. Boot-Validator prüft drei Invarianten:
+//   1. Jeder usesApi(name) findet einen exposesApi(name) in irgendeinem
+//      Feature.
+//   2. Das exposing-Feature ist in requires/optionalRequires des callers
+//      gelisted (sonst klappt die Cross-Feature-Aufruf-Reihenfolge nicht).
+//   3. Self-exposure ist erlaubt (Feature ruft eigene API), wird aber
+//      mit Warning markiert weil es typisch ein Refactor-Restbestand ist.
+//
+// Globale Eindeutigkeit der apiNames (kein Dublicate über Features)
+// wird in validateBoot() vor dem Per-Feature-Walk geprüft.
+function validateApiExposureMatching(
+  feature: FeatureDefinition,
+  allExposedApis: ReadonlyMap<string, string>,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  for (const apiName of feature.usedApis) {
+    const providerFeature = allExposedApis.get(apiName);
+    if (!providerFeature) {
+      const known = [...allExposedApis.keys()].sort().join(", ") || "(none)";
+      throw new Error(
+        `[Feature ${feature.name}] r.usesApi("${apiName}") but no feature exposes that API. Known exposed APIs: ${known}`,
+      );
+    }
+
+    if (providerFeature === feature.name) {
+      // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+      console.warn(
+        `[kumiko:boot] [Feature ${feature.name}] r.usesApi("${apiName}") on its own r.exposesApi — typically a refactor leftover. Call the impl directly instead.`,
+      );
+      continue;
+    }
+
+    const allDeps = [...feature.requires, ...feature.optionalRequires];
+    if (!allDeps.includes(providerFeature)) {
+      throw new Error(
+        `[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires("${providerFeature}").`,
+      );
+    }
+
+    // Sanity: provider feature actually exists in this app's feature set.
+    // Should always be true if allExposedApis was built from `features`,
+    // aber defensiv für unklare Constructor-Pfade.
+    if (!featureMap.has(providerFeature)) {
+      throw new Error(
+        `[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map`,
+      );
+    }
+  }
+}
+
 // --- Extension usage validation ---
 
 function validateExtensionUsages(

package/src/engine/define-feature.ts

@@ -112,6 +112,8 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const notifications: Record<string, NotificationDefinition> = {};
   const registrarExtensions: Record<string, RegistrarExtensionDef> = {};
   const extensionUsages: RegistrarExtensionRegistration[] = [];
+  const exposedApis: Set<string> = new Set();
+  const usedApis: Set<string> = new Set();
   const referenceData: ReferenceDataDef[] = [];
   const handlerEntityMappings: Record<string, string> = {};
   const metrics: Record<string, FeatureMetricDef> = {};
@@ -464,6 +466,41 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       extensionUsages.push({ extensionName, entityName: resolveName(entityRef), options });
     },
 
+    /**
+     * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
+     * unter dem genannten Namen bereit. Die eigentliche Implementation
+     * wird separat als Query- oder Write-Handler unter dem QN-Pattern
+     * registriert; r.exposesApi ist reine Boot-Check-Surface.
+     *
+     * Beispiel:
+     *   defineFeature("compliance-profiles", (r) => {
+     *     r.exposesApi("compliance.forTenant");
+     *     r.queryHandler({ name: "compliance:query:for-tenant", ... });
+     *   });
+     *   defineFeature("user-data-rights", (r) => {
+     *     r.requires("compliance-profiles");
+     *     r.usesApi("compliance.forTenant");
+     *     // ruft im Handler: ctx.callQuery("compliance:query:for-tenant", ...)
+     *   });
+     */
+    exposesApi(apiName: string): void {
+      if (exposedApis.has(apiName)) {
+        throw new Error(
+          `[Feature ${name}] r.exposesApi("${apiName}") called twice — API names must be unique within a feature.`,
+        );
+      }
+      exposedApis.add(apiName);
+    },
+
+    /**
+     * Declares that this feature calls a cross-feature API. Boot-Validator
+     * checkt dass irgendein anderes Feature `r.exposesApi(name)` macht und
+     * dass dieses Feature `r.requires` darauf hat.
+     */
+    usesApi(apiName: string): void {
+      usedApis.add(apiName);
+    },
+
     metric(shortName: string, options: MetricOptions): void {
       if (metrics[shortName]) {
         throw new Error(
@@ -720,6 +757,8 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     notifications,
     registrarExtensions,
     extensionUsages,
+    exposedApis,
+    usedApis,
     referenceData,
     events,
     eventMigrations,

package/src/engine/extension-names.ts

@@ -0,0 +1,105 @@
+// Standardisierte Extension-Namen fuer Datenschutz-Hook-Achsen.
+//
+// Features registrieren Extensions via:
+//   r.extendsRegistrar(EXT_USER_DATA, { hooks: { ... } });
+//
+// Andere Features haengen sich ein via:
+//   r.useExtension(EXT_USER_DATA, "myEntity", { ...hookImpls });
+//
+// Hintergrund: Magic-Strings driften zwischen Bundled-Features (Beispiel:
+// text-content nutzt "Admin" als Rolle, tenant-handler nutzt "TenantAdmin").
+// Constants sind die einzige Quelle der Wahrheit; String-Literale werden
+// in den Sprint-Touchpoints schrittweise ersetzt. Boot-Validator
+// (validateExtensionUsages) checkt dass jedes useExtension einen
+// passenden extendsRegistrar findet — Tippfehler in Constants →
+// Compile-Time-Fail.
+//
+// Hook-Signaturen + Boot-Validation pro Extension-Achse kommen mit dem
+// jeweiligen registrierenden Sprint:
+//   userData / tenantData         → Sprint 2 (user-data-rights, retention)
+//   storageProvider                → Sprint 4 (storage-encryption)
+//   searchAdapter / external /     → Sprint 5 (tenant-lifecycle)
+//   infraResource
+
+/**
+ * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `export(userId, ctx) => Promise<UserDataExport>`
+ *   - `delete(userId, strategy: "delete" | "anonymize", ctx) => Promise<void>`
+ *
+ * Registriert von: `user-data-rights` (Sprint 2).
+ * Genutzt von: jedes Feature mit User-Referenzen (tasks, comments, files, ...).
+ */
+export const EXT_USER_DATA = "userData" as const;
+
+/**
+ * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `destroy(tenantId, ctx) => Promise<void>`
+ *
+ * Registriert von: `tenant-lifecycle` (Sprint 5).
+ * Genutzt von: jedes Feature mit tenantId-Field.
+ */
+export const EXT_TENANT_DATA = "tenantData" as const;
+
+/**
+ * `storageProvider` — File-Storage-Plugin-Hooks (Crypto-Shredding fuer Files).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `destroyTenant(tenantId, ctx) => Promise<void>`
+ *   - `destroySubject(subject, ctx) => Promise<{ deleted: number }>`
+ *
+ * Registriert von: `storage-encryption` (Sprint 4).
+ * Genutzt von: pluggable Provider (Local, MinIO, S3, R2).
+ */
+export const EXT_STORAGE_PROVIDER = "storageProvider" as const;
+
+/**
+ * `searchAdapter` — Search-Adapter-Forget-Hooks (Meilisearch-Index-Cleanup
+ * bei User-Forget oder Tenant-Destroy).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `destroyTenant(tenantId, ctx) => Promise<void>`
+ *   - `eraseSubject(subject, ctx) => Promise<void>`
+ *
+ * Registriert von: `tenant-lifecycle` (Sprint 5).
+ * Genutzt von: Meilisearch- und andere Search-Adapter-Implementierungen.
+ */
+export const EXT_SEARCH_ADAPTER = "searchAdapter" as const;
+
+/**
+ * `externalResource` — External-Service-Tenant-Cleanup
+ * (Webhook-Subscriptions, Brevo-Empfaenger-Listen, Stripe-Customer-Account).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `destroyTenant(tenantId, ctx) => Promise<void>`
+ *
+ * Registriert von: `tenant-lifecycle` (Sprint 5).
+ */
+export const EXT_EXTERNAL_RESOURCE = "externalResource" as const;
+
+/**
+ * `infraResource` — Pulumi-managed Resources pro Tenant
+ * (Custom-Domain, Cert-Manager-Issuer, dedicated Pod/Volume).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `destroyTenant(tenantId, ctx) => Promise<void>`
+ *
+ * Registriert von: `tenant-lifecycle` (Sprint 5).
+ */
+export const EXT_INFRA_RESOURCE = "infraResource" as const;
+
+/**
+ * Union aller standardisierten Extension-Namen der Datenschutz-Surface.
+ * Nicht alle Extensions im System sind in dieser Liste — andere
+ * Features koennen weiterhin eigene Extension-Namen registrieren.
+ */
+export type KumikoExtensionName =
+  | typeof EXT_USER_DATA
+  | typeof EXT_TENANT_DATA
+  | typeof EXT_STORAGE_PROVIDER
+  | typeof EXT_SEARCH_ADAPTER
+  | typeof EXT_EXTERNAL_RESOURCE
+  | typeof EXT_INFRA_RESOURCE;