@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.2.3

package/src/data-retention/handlers/policy-for.query.ts

@@ -0,0 +1,57 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { parseRetentionOverrideOrNull } from "../_internal/parse-override";
+import { type EffectiveRetentionPolicy, resolveRetentionPolicy } from "../resolver";
+import { tenantRetentionOverrideTable } from "../schema/tenant-retention-override";
+
+// retention:query:policy-for — Cross-Feature-API fuer den Forget-Flow.
+//
+// user-data-rights-Sprint-2.U5 ruft das pro Entity um zu wissen ob ein
+// Forget mit "delete" oder "anonymize" oder "blockDelete-bis-Frist"
+// laufen soll. Plus Cleanup-Job-Sprint-2.D2b fuer das gleiche.
+//
+// Tenant-Preset-Storage existiert noch nicht (kommt mit S2.D2b ueber
+// einen tenant-config-key). Bis dahin tenantPreset=null — der Resolver
+// liefert dann nur die Entity-Default-Layer + Override.
+//
+// access: openToAll — andere Features im selben Tenant duerfen das
+// abrufen. Keine PII im Result, nur Policy-Metadata.
+export const policyForQuery = defineQueryHandler({
+  name: "policy-for",
+  schema: z.object({
+    entityName: z.string().min(1).max(100),
+  }),
+  access: { openToAll: true },
+  handler: async (query, ctx): Promise<EffectiveRetentionPolicy> => {
+    const entityName = query.payload.entityName;
+
+    // Layer 3: Tenant-Override aus DB laden (UNIQUE(tenantId, entityName))
+    const overrideRow = (await fetchOne(
+      ctx.db,
+      tenantRetentionOverrideTable,
+      eq(tenantRetentionOverrideTable["tenantId"], query.user.tenantId),
+      eq(tenantRetentionOverrideTable["entityName"], entityName),
+    )) as { config: string | null } | null;
+
+    const tenantOverride = parseRetentionOverrideOrNull(
+      overrideRow?.config ?? null,
+      query.user.tenantId,
+      "data-retention:policy-for",
+    );
+
+    // Layer 1: Entity-Default aus Registry
+    const entityDef = ctx.registry?.getEntity(entityName) ?? null;
+
+    // Layer 2: Tenant-Preset — Storage kommt mit S2.D2b. Bis dahin null.
+    const tenantPreset = null;
+
+    return resolveRetentionPolicy({
+      entityName,
+      entityDef,
+      tenantPreset,
+      tenantOverride,
+    });
+  },
+});

package/src/data-retention/index.ts

@@ -0,0 +1,18 @@
+export type {
+  EffectiveRetentionPolicy,
+  ResolveForTenantArgs,
+  ResolveRetentionPolicyArgs,
+  RetentionOverride,
+  RetentionPreset,
+  RetentionPresetKey,
+} from "./feature";
+export {
+  createDataRetentionFeature,
+  RETENTION_PRESETS,
+  resolveRetentionPolicy,
+  resolveRetentionPolicyForTenant,
+  retentionOverrideSchema,
+  SELECTABLE_RETENTION_PRESETS,
+  tenantRetentionOverrideEntity,
+  tenantRetentionOverrideTable,
+} from "./feature";

package/src/data-retention/keep-for.ts

@@ -0,0 +1,75 @@
+// keepFor-Format-Parser: "30d" / "10y" / "6m" / "1w" / "24h" → Cutoff-Instant.
+//
+// Nicht millisekunden-praezise — DSGVO-Aufbewahrungspflichten haben
+// Tag-/Monat-Granularitaet. "6m" = 6×30d, "10y" = 10×365d. Cleanup-Job
+// laeuft taeglich, ein paar Tage Differenz beim Cutoff sind akzeptabel.
+//
+// Boot-Validator (S0.2) hat das Format schon gegen /^\d+[hdwmy]$/
+// gecheckt — hier defensiv nochmal validiert fuer Migration-Edge-Cases.
+//
+// Temporal kommt via globalThis (Polyfill in framework-Boot installiert).
+// `getTemporal()` aus framework/time gibt typed Zugriff.
+
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+
+const KEEP_FOR_PATTERN = /^(\d+)([hdwmy])$/;
+
+const UNIT_TO_DAYS: Readonly<Record<string, number>> = {
+  d: 1,
+  w: 7,
+  m: 30,
+  y: 365,
+};
+
+export class InvalidKeepForError extends Error {
+  constructor(spec: string) {
+    super(
+      `Invalid keepFor format "${spec}" — expected /^\\d+[hdwmy]$/ (e.g. "30d", "10y", "6m", "1w", "24h")`,
+    );
+  }
+}
+
+// Re-export von Temporal.Instant als Type-Alias damit Caller den Type
+// nicht selbst aus globalThis ziehen muessen.
+export type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+/**
+ * Berechnet den Cutoff-Instant — Rows mit reference < cutoff sind
+ * abgelaufen und werden vom Cleanup-Job geraeumt.
+ *
+ * @param spec keepFor-String wie "30d", "10y", "6m", "1w", "24h"
+ * @param now Aktueller Zeitpunkt (advisor-Pattern: injection-Parameter
+ *            fuer Time-Travel-Tests, kein global Temporal.Now)
+ */
+export function computeCutoff(spec: string, now: Instant): Instant {
+  const match = KEEP_FOR_PATTERN.exec(spec);
+  if (!match) {
+    throw new InvalidKeepForError(spec);
+  }
+  const amount = Number.parseInt(match[1] ?? "0", 10);
+  const unit = match[2] ?? "";
+
+  if (unit === "h") {
+    return now.subtract({ hours: amount });
+  }
+
+  const daysFactor = UNIT_TO_DAYS[unit];
+  if (daysFactor === undefined) {
+    throw new InvalidKeepForError(spec);
+  }
+  return now.subtract({ hours: amount * daysFactor * 24 });
+}
+
+/**
+ * Ist referenceTimestamp aelter als der keepFor-Cutoff bei now?
+ * Cleanup-Job nutzt das pro Row.
+ */
+export function isPastCutoff(args: {
+  readonly referenceTimestamp: Instant;
+  readonly keepFor: string;
+  readonly now: Instant;
+}): boolean {
+  const T = getTemporal();
+  const cutoff = computeCutoff(args.keepFor, args.now);
+  return T.Instant.compare(args.referenceTimestamp, cutoff) < 0;
+}

package/src/data-retention/override-schema.ts

@@ -0,0 +1,37 @@
+// Zod-Schema fuer RetentionOverride mit .strict() — Sprint 2.D2.5 (M2+M3).
+//
+// Symmetrisch zu compliance-profiles override-schema.ts (S1.9 Z3).
+// Sub-Sprint-Pattern (advisor-pinned): bei jedem User-konfigurierbarem
+// JSON-Override → strict-Zod + enum-validated.
+//
+// Schuetzt vor:
+//   - Top-Level-Tippfehler ("keepfor" statt "keepFor") — strict()-Reject
+//   - Strategy-Enum-Drift ("delete" statt "hardDelete") — z.enum-Reject
+//   - keepFor-Format-Drift ("30days" statt "30d") — regex-Reject
+//
+// Tenant-Override darf alle drei Properties weglassen (Resolver
+// fallback auf Preset/Entity-Default), aber WAS gesetzt ist muss
+// gueltig sein.
+
+import { z } from "zod";
+
+const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
+
+const retentionStrategySchema = z.enum(["hardDelete", "softDelete", "anonymize", "blockDelete"]);
+
+/**
+ * RetentionOverride-Zod-Schema mit .strict() — fuer (a) set-override-
+ * Handler-Validation (S2.D3) und (b) DB-Loader im Cleanup-Job (S2.D2b)
+ * der invalides JSON aus der config-Spalte loggt + skipt statt mit
+ * undefined behavior weiterzumachen.
+ */
+export const retentionOverrideSchema = z
+  .object({
+    keepFor: z
+      .string()
+      .regex(KEEP_FOR_PATTERN, "keepFor must match /^\\d+[hdwmy]$/ (e.g. '30d', '10y', '6m')")
+      .optional(),
+    strategy: retentionStrategySchema.optional(),
+    reference: z.string().min(1).optional(),
+  })
+  .strict();

package/src/data-retention/presets.ts

@@ -0,0 +1,72 @@
+// Retention-Presets — vorgefertigte Bündel von per-Entity-Aufbewahrungs-
+// Konfigurationen pro Compliance-Regime. Tenant-Admin wählt EINES (analog
+// zu compliance-profiles); Entity-Default + Tenant-Override liegen als
+// Schichten 1+3 darüber (siehe resolver.ts).
+//
+// Plan-Roadmap docs/plans/datenschutz/core-data-retention.md hat 8 Presets
+// vorgeschlagen. Sprint-2-MVP: 3 Production-Presets + 1 dev-Default,
+// rest folgt on-demand wenn Customer fragt.
+//
+// Presets sind pure Daten — keine Logik. Erweitern = Constant erweitern,
+// kein Code-Eingriff.
+
+import type { RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
+
+/**
+ * Pro Entity-Name gemappte Retention-Policy. Entity-Namen sind der
+ * String aus r.entity("name", ...) — kebab-case oder lowercase.
+ * Cleanup-Job iteriert alle bekannten Entities; was nicht im Preset
+ * steht, fällt auf Entity-Default (Layer 1) zurück.
+ */
+export type RetentionPreset = Readonly<Record<string, RetentionDef>>;
+
+export type RetentionPresetKey = "default" | "dsgvo-basic" | "dsgvo-hgb" | "swiss-dsg";
+
+/**
+ * MVP-Set für Sprint 2. Erweiterungen (hipaa, ccpa, aggressive-gdpr,
+ * pipeda-default, ca-quebec-l25) kommen on-demand.
+ */
+export const RETENTION_PRESETS: Readonly<Record<RetentionPresetKey, RetentionPreset>> = {
+  // Default — keine Auto-Aktion. Nur sinnvoll für Dev/Staging.
+  // Production-Tenant der "default" stehen lässt → Cleanup-Job
+  // schreibt Audit-Eintrag "skipped: no preset selected".
+  default: {},
+
+  // DSGVO Basic — Datenminimierung ohne Buchhaltungspflichten.
+  "dsgvo-basic": {
+    auditLog: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
+    session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
+    httpLog: { keepFor: "90d", strategy: "hardDelete", reference: "createdAt" },
+  },
+
+  // DSGVO + HGB — deutsche Aufbewahrungspflichten überlagert. Order
+  // wird anonymisiert (PII raus, Geschäftsdaten bleiben), Invoice +
+  // Booking sind blockDelete bis 10 Jahre, dann Anonymize.
+  "dsgvo-hgb": {
+    auditLog: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
+    session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
+    httpLog: { keepFor: "90d", strategy: "hardDelete", reference: "createdAt" },
+    invoice: { keepFor: "10y", strategy: "blockDelete", reference: "createdAt" },
+    booking: { keepFor: "10y", strategy: "blockDelete", reference: "createdAt" },
+    contract: { keepFor: "6y", strategy: "blockDelete", reference: "createdAt" },
+    order: { keepFor: "6y", strategy: "anonymize", reference: "completedAt" },
+  },
+
+  // Schweizer DSG — ähnlich DSGVO mit OR Art. 958f Aufbewahrung.
+  "swiss-dsg": {
+    auditLog: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
+    session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
+    invoice: { keepFor: "10y", strategy: "blockDelete", reference: "createdAt" },
+  },
+};
+
+/**
+ * Auswählbare Presets für den Onboarding-Banner. "default" ist Migration-
+ * Edge-Case und wird nicht angezeigt — Production-Tenants wählen ein
+ * echtes Preset.
+ */
+export const SELECTABLE_RETENTION_PRESETS: readonly RetentionPresetKey[] = [
+  "dsgvo-basic",
+  "dsgvo-hgb",
+  "swiss-dsg",
+];

package/src/data-retention/resolve-for-tenant.ts

@@ -0,0 +1,50 @@
+// Direkter Resolver-Helper fuer Bulk-Iteration (S2.U5b Cleanup-Runner).
+//
+// `policy-for` Query (handlers/policy-for.query.ts) ist die Cross-Feature-
+// API fuer einzelne Lookups. Der Cleanup-Runner iteriert N Entities × M
+// Tenants — Handler-Roundtrip pro Lookup waere zu teuer + braucht einen
+// HandlerContext. Beide Pfade nutzen denselben `parseRetentionOverrideOrNull`
+// + `resolveRetentionPolicy`, also kein Drift-Risiko.
+
+import { type DbRunner, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { parseRetentionOverrideOrNull } from "./_internal/parse-override";
+import { type EffectiveRetentionPolicy, resolveRetentionPolicy } from "./resolver";
+import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override";
+
+export interface ResolveForTenantArgs {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+  readonly entityName: string;
+}
+
+export async function resolveRetentionPolicyForTenant(
+  args: ResolveForTenantArgs,
+): Promise<EffectiveRetentionPolicy> {
+  const overrideRow = (await fetchOne(
+    args.db,
+    tenantRetentionOverrideTable,
+    eq(tenantRetentionOverrideTable["tenantId"], args.tenantId),
+    eq(tenantRetentionOverrideTable["entityName"], args.entityName),
+  )) as { config: string | null } | null;
+
+  const tenantOverride = parseRetentionOverrideOrNull(
+    overrideRow?.config ?? null,
+    args.tenantId,
+    "data-retention:resolve-for-tenant",
+  );
+
+  const entityDef = args.registry.getEntity(args.entityName) ?? null;
+
+  // Layer 2 (Tenant-Preset) kommt mit S2.D2b. Bis dahin null.
+  const tenantPreset = null;
+
+  return resolveRetentionPolicy({
+    entityName: args.entityName,
+    entityDef,
+    tenantPreset,
+    tenantOverride,
+  });
+}

package/src/data-retention/resolver.ts

@@ -0,0 +1,107 @@
+// 3-Schicht-Retention-Resolver.
+//
+// Layer 1: Entity-Default       — Feature-Author setzt r.entity({retention})
+// Layer 2: Tenant-Preset        — Tenant-Admin wählt Bundle (RETENTION_PRESETS)
+// Layer 3: Tenant-Override      — per (tenantId, entityName) JSON-Override
+//
+// Resolver-Reihenfolge:
+//   effective = override(tenantId, entityName)
+//             ?? preset[tenant.retentionPreset][entityName]
+//             ?? entity.retention   (Code-Default aus EntityDefinition)
+//             ?? null               (keine Auto-Aktion)
+//
+// Cleanup-Job in S2.D2 ruft das pro (tenantId, entityName) und
+// entscheidet was zu tun ist (hardDelete / softDelete / anonymize /
+// blockDelete-mit-Frist-Check).
+//
+// Cross-Feature-API r.exposesApi("retention.policyFor") (S2.D3)
+// macht das aus user-data-rights heraus konsumierbar — Forget-Flow
+// fragt blockDelete-Felder ab + anonymisiert sie statt zu löschen.
+
+import type { EntityDefinition, RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
+import { RETENTION_PRESETS, type RetentionPresetKey } from "./presets";
+
+/**
+ * Roh-Override aus der DB-Tabelle (config-Spalte als JSON-String).
+ * Nicht das gleiche wie RetentionDef weil hier alles optional ist —
+ * Override darf einzelne Properties überschreiben.
+ */
+export interface RetentionOverride {
+  readonly keepFor?: string;
+  readonly strategy?: RetentionDef["strategy"];
+  readonly reference?: string;
+}
+
+/**
+ * Effektive Policy nach Resolver-Lauf. Source dokumentiert WELCHE
+ * Schicht den Wert geliefert hat — Audit-Trail für DPO.
+ *
+ * `override-incomplete` bedeutet: Tenant-Override ist gesetzt, aber
+ * füllt keepFor weder selbst noch via Preset-/Entity-Fallback.
+ * Cleanup-Job logt eine Warning + skippt — anstatt mit Default-"0d"
+ * sofort alles zu löschen.
+ */
+export interface EffectiveRetentionPolicy {
+  readonly entityName: string;
+  readonly policy: RetentionDef | null;
+  readonly source: "override" | "preset" | "entity-default" | "none" | "override-incomplete";
+}
+
+export interface ResolveRetentionPolicyArgs {
+  readonly entityName: string;
+  readonly entityDef: EntityDefinition | null;
+  readonly tenantPreset: RetentionPresetKey | null;
+  readonly tenantOverride: RetentionOverride | null;
+}
+
+/**
+ * Auswertung der drei Schichten. Pure Function — kein DB-Access, alle
+ * Inputs werden vom Caller besorgt (Cleanup-Job aggregiert pro Tenant
+ * vorher).
+ */
+export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): EffectiveRetentionPolicy {
+  const { entityName, entityDef, tenantPreset, tenantOverride } = args;
+
+  // Layer 3: Override wins, aber Override darf Felder weglassen — dann
+  // fallen die einzelnen Properties auf Layer 2/1 zurück.
+  if (tenantOverride !== null) {
+    const baseFromPreset =
+      tenantPreset !== null ? (RETENTION_PRESETS[tenantPreset]?.[entityName] ?? null) : null;
+    const baseFromEntity = entityDef?.retention ?? null;
+    const base = baseFromPreset ?? baseFromEntity;
+
+    const keepFor = tenantOverride.keepFor ?? base?.keepFor;
+    const strategy = tenantOverride.strategy ?? base?.strategy;
+
+    // keepFor + strategy sind Pflicht für jede aktive Policy. Wenn
+    // weder Override noch Base sie liefert, ist das Override semantisch
+    // unvollständig — Cleanup-Job soll WARNEN statt mit Default-"0d"
+    // sofort alles löschen. Source-Marker dokumentiert das.
+    if (keepFor === undefined || strategy === undefined) {
+      return { entityName, policy: null, source: "override-incomplete" };
+    }
+
+    const merged: RetentionDef = {
+      keepFor,
+      strategy,
+      reference: tenantOverride.reference ?? base?.reference,
+    };
+    return { entityName, policy: merged, source: "override" };
+  }
+
+  // Layer 2: Preset
+  if (tenantPreset !== null) {
+    const fromPreset = RETENTION_PRESETS[tenantPreset]?.[entityName];
+    if (fromPreset) {
+      return { entityName, policy: fromPreset, source: "preset" };
+    }
+  }
+
+  // Layer 1: Entity-Default
+  if (entityDef?.retention) {
+    return { entityName, policy: entityDef.retention, source: "entity-default" };
+  }
+
+  // Nichts da — Cleanup-Job überspringt diese Entity für diesen Tenant.
+  return { entityName, policy: null, source: "none" };
+}

package/src/data-retention/schema/tenant-retention-override.ts

@@ -0,0 +1,47 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createLongTextField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// tenantRetentionOverride — Layer 3 im 3-Schicht-Resolver.
+//
+// Per (tenantId, entityName) eine optionale Override-Config die das
+// Preset (Layer 2) für genau diese eine Entity überschreibt. Use-Cases:
+//   - Anwaltskanzlei in DE: caseFile 6y blockDelete (nicht im Preset)
+//   - Pilot-Tenant der länger speichert für Test
+//   - Branchenspezifische verkürzte Fristen
+//
+// reason ist Pflicht — Audit für DPO + Aufsichtsbehörde nachvollziehbar.
+//
+// config ist JSON-String mit `{ keepFor, strategy, reference? }`. Zod-
+// Schema validiert beim set-override-Call (S2.D2 ggf. erweitert).
+//
+// Tenant-1-zu-N: pro Tenant beliebig viele Entity-Overrides. UNIQUE-
+// Index auf (tenantId, entityName) damit pro Entity max ein Override.
+export const tenantRetentionOverrideEntity = createEntity({
+  table: "read_tenant_retention_overrides",
+  fields: {
+    entityName: createTextField({
+      required: true,
+      maxLength: 100,
+      allowPlaintext: "is-business-data",
+    }),
+    config: createLongTextField({
+      required: true,
+      allowPlaintext: "is-business-data",
+    }),
+    reason: createTextField({
+      required: true,
+      maxLength: 500,
+      allowPlaintext: "is-business-data",
+    }),
+  },
+  indexes: [{ unique: true, columns: ["tenantId", "entityName"] }],
+});
+
+export const tenantRetentionOverrideTable = buildDrizzleTable(
+  "tenantRetentionOverride",
+  tenantRetentionOverrideEntity,
+);

package/src/file-foundation/feature.ts

@@ -24,9 +24,10 @@
 import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   access,
+  type ConfigAccessor,
   createTenantConfig,
   defineFeature,
-  type HandlerContext,
+  type Registry,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
 
@@ -36,13 +37,52 @@ const FEATURE_NAME = "file-foundation";
 // Plugin-Interface — what a Provider-Plugin must implement
 // =============================================================================
 
+/**
+ * Schmaler Surface-Type fuer Provider-Plugins. HandlerContext ist zu
+ * fett (haelt tx, actor, signal etc.) — Provider sollen sich auf die
+ * read-Felder beschraenken die fuer Tenant-Config + Secret-Lookup
+ * gebraucht werden.
+ *
+ * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job) gibt
+ * es keinen request-bezogenen `tx`/`actor`/`signal`. Wenn ein Provider
+ * `ctx.tx` lesen wuerde, wuerde der ganze Worker-Pfad zur Runtime
+ * brechen — und das wuerde NUR mit S3 und nur in production auffallen.
+ * Die schmale Surface zwingt Provider zur expliziten Erweiterung
+ * (extra-arg) statt silent ctx-feld-ausnutzen.
+ *
+ * **Felder:**
+ *   config  — fuer tenant-config-reads (bucket/region/endpoint/...)
+ *   registry — fuer extension-Lookup in der Factory (nicht Plugin-intern)
+ *   secrets — fuer tenant-secret-reads (s3.secretAccessKey)
+ *   _userId — Audit-Identity fuer secret-reads. Im Handler-Pfad setzt
+ *             der dispatcher das auf die Caller-User-ID; im Worker-Pfad
+ *             muss der r.job-Wrap das explizit auf eine System-Identity
+ *             setzen (z.B. "system:user-data-rights:run-export-jobs").
+ */
+export type FileProviderContext = {
+  readonly config?: ConfigAccessor;
+  readonly registry?: Registry;
+  readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
+  readonly _userId?: string | undefined;
+};
+
 /**
  * File-Storage-Plugin contract. Each provider-feature (file-provider-s3,
  * file-provider-azure-blob, ...) registers an implementation via
  * `r.useExtension("fileProvider", "<name>", { build })`.
+ *
+ * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein FileProviderContext,
+ * nicht ein voller HandlerContext. Felder ausserhalb der schmalen
+ * Surface (z.B. `ctx.tx`, `ctx.actor`, `ctx.signal`, `ctx.notify`) sind
+ * im Worker-Pfad (r.job-getriggerte Provider-Builds) NICHT vorhanden.
+ * Cast `ctx as unknown as HandlerContext` macht den Compiler happy aber
+ * fliegt zur Runtime im Worker — und der Crash kommt erst in production
+ * mit dem ersten S3-Tenant. Wenn ein Plugin Felder braucht die nicht in
+ * FileProviderContext sind: lieber FileProviderContext explizit erweitern
+ * (sichtbarer breaking change) als ctx-cast.
  */
 export type FileProviderPlugin = {
-  readonly build: (ctx: HandlerContext, tenantId: string) => Promise<FileStorageProvider>;
+  readonly build: (ctx: FileProviderContext, tenantId: string) => Promise<FileStorageProvider>;
 };
 
 // =============================================================================
@@ -77,7 +117,7 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
 // =============================================================================
 
 export async function createFileProviderForTenant(
-  ctx: HandlerContext,
+  ctx: FileProviderContext,
   tenantId: string,
   handlerName = "file-foundation:provider-factory",
 ): Promise<FileStorageProvider> {

package/src/file-foundation/index.ts

@@ -2,6 +2,7 @@
 
 export {
   createFileProviderForTenant,
+  type FileProviderContext,
   type FileProviderPlugin,
   fileFoundationFeature,
 } from "./feature";

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

@@ -17,8 +17,11 @@
 // **NICHT für Production.** Buffer ist Process-Memory, geht beim
 // Restart verloren + wächst monoton mit jedem write.
 
-import type { FileProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
-import { defineFeature, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createInMemoryFileProvider,
   type FileStorageProvider,
@@ -63,7 +66,7 @@ export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
   r.requires("file-foundation");
 
   const plugin: FileProviderPlugin = {
-    build: async (_ctx: HandlerContext, tenantId: string): Promise<FileStorageProvider> => {
+    build: async (_ctx: FileProviderContext, tenantId: string): Promise<FileStorageProvider> => {
       // Returnt den per-tenant Storage. Identitätsstabil zwischen calls
       // damit accumulated state erhalten bleibt.
       return getOrCreateProviderForTenant(tenantId);

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

@@ -18,19 +18,17 @@
 //
 // **Boot-Dependencies:** config + secrets + file-foundation.
 
-import type { FileProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import type {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
 import { createS3Provider } from "@cosmicdrift/kumiko-bundled-features/files-provider-s3";
 import {
   requireDefined,
   requireNonEmpty,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import {
-  access,
-  createTenantConfig,
-  defineFeature,
-  type HandlerContext,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
 
 const FEATURE_NAME = "file-provider-s3";
@@ -89,7 +87,7 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
   // Plugin-Registration. entityName "s3" ist was tenants in
   // file-foundation's `provider` config-key setzen.
   const plugin: FileProviderPlugin = {
-    build: async (ctx: HandlerContext, tenantId: string) => buildS3Provider(ctx, tenantId),
+    build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId),
   };
   r.useExtension("fileProvider", "s3", plugin);
 
@@ -104,7 +102,7 @@ export const S3_SECRET_ACCESS_KEY = fileProviderS3Feature.exports.secretAccessKe
 // =============================================================================
 
 async function buildS3Provider(
-  ctx: HandlerContext,
+  ctx: FileProviderContext,
   tenantId: string,
 ): Promise<FileStorageProvider> {
   const ctxConfig = ctx.config;
@@ -157,7 +155,7 @@ async function buildS3Provider(
   });
 }
 
-async function readSecretAccessKey(ctx: HandlerContext, tenantId: string): Promise<string> {
+async function readSecretAccessKey(ctx: FileProviderContext, tenantId: string): Promise<string> {
   const secrets = requireSecretsContext(ctx, FEATURE_NAME);
   const branded = await secrets.get(tenantId, S3_SECRET_ACCESS_KEY);
   if (!branded) {