@cosmicdrift/kumiko-bundled-features 0.2.1 → 0.2.3

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) {

package/src/files/README.md

@@ -0,0 +1,50 @@
+# files
+
+Schema-Sicht der framework-internen `file_refs`-Tabelle als bundled-feature.
+Sprint-1.5 Refactor (Pre-Sprint-2).
+
+## Was es macht
+
+Deklariert `r.entity("fileRef", ...)` für die DB-Tabelle die das
+Framework via `createFileRoutes` (multipart-Upload + binary-Download)
+bewirtschaftet. Das öffnet die Tür für Cross-Feature-Hooks:
+
+- **Sprint 2** (`user-data-rights-defaults`) registriert `r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })` — Forget-Flow + Daten-Export fassen die Files automatisch an. ✅ done
+- **Sprint 5** (`tenant-lifecycle`) wird `r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })` registrieren — Tenant-Destroy löscht alle FileRefs.
+
+## Was es NICHT macht
+
+- **Keine Upload-/Download-Routes** — die bleiben in
+  `framework/src/api/server.ts` via `options.files`-Bootstrap.
+  Multipart-Form-Body und Binary-Streaming passen nicht ins Write/Query-
+  Handler-Pattern; ein Refactor zu `r.httpRoute` wäre orthogonal zu
+  diesem Sprint.
+- **Kein eigener Drizzle-Table-Build** — die `file_refs`-Tabelle
+  existiert schon in `framework/src/files/file-ref-table.ts`. Diese
+  Entity ist nur die Schema-Sicht für Cross-Feature-Hooks; Drizzle-
+  Queries laufen weiter über `fileRefsTable` aus
+  `@cosmicdrift/kumiko-framework/files`.
+
+## PII-Annotations (Sprint 0.1+0.7)
+
+```ts
+fileName    → pii: true                  (Originalname enthält oft Personen-Bezug)
+storageKey  → allowPlaintext: "is-business-data"  (interner UUID-Key)
+mimeType    → allowPlaintext: "is-business-data"
+size        → allowPlaintext: "is-business-data"
+entityType  → allowPlaintext: "is-business-data"
+entityId    → allowPlaintext: "is-business-data"
+fieldName   → allowPlaintext: "is-business-data"
+insertedAt  → kein PII-Marker (Audit-Timestamp, Framework-managed)
+insertedById → allowPlaintext: "is-business-data"  (User-Reference, kein Eigen-PII)
+```
+
+`fileName: pii: true` heißt: Sprint 3 Crypto-Shredding wird den Wert
+mit dem Author-Subject-Key encrypten (für File-INHALTE: separates
+Subject-Resolver-Pattern via `subjectField` — siehe storage-encryption.md
+Sprint 4).
+
+## Tests
+
+`__tests__/files.integration.ts` — 5 Tests die beweisen dass die Feature-
+Definition clean lädt + die PII-Markers + Tabellenname stimmen.

package/src/files/__tests__/files.integration.ts

@@ -0,0 +1,157 @@
+// files-feature integration tests (S1.5 + S1.7).
+//
+// Tests sortiert nach Verhaltens-Tiefe:
+//   1. Feature-Definition Smoke (Boot-Validation passes)
+//   2. Cross-Feature-Behavior: fileRef-Entity ist als Hook-Anker für
+//      Sprint-2-userData-Extension nutzbar
+//   3. DDL-Konsistenz: Framework-pgTable + Feature-Entity zeigen auf
+//      dieselbe Postgres-Struktur (Drift-Guard)
+//   4. Event-QN-Match: r.defineEvent + framework's fileUploadedEvent
+//      resolven zum selben QN
+
+import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { FILE_UPLOADED_EVENT_TYPE, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { getTableColumns } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createFilesFeature, fileRefEntity } from "../feature";
+
+let stack: TestStack;
+
+const feature = createFilesFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("files :: feature-definition smoke", () => {
+  test("Boot ist clean (PII-Annotations + Event-Schema valide)", async () => {
+    // setupTestStack hat das feature im beforeAll geladen — wenn Boot-
+    // Validation fehlschlägt, würde dieser Block nie laufen.
+    expect(stack).toBeDefined();
+  });
+
+  test("Tabellen-Name matched die Framework-pgTable (file_refs)", () => {
+    expect(fileRefEntity.table).toBe("file_refs");
+  });
+
+  test("fileName ist als pii: true markiert", () => {
+    const fileName = fileRefEntity.fields["fileName"] as { pii?: boolean };
+    expect(fileName.pii).toBe(true);
+  });
+});
+
+describe("files :: cross-feature behavior (F1, S1.7)", () => {
+  test("Sprint-2-Pattern: ein Consumer-Feature kann r.useExtension(EXT_USER_DATA, fileRef, ...) registrieren", async () => {
+    // Stub-Feature simuliert die Sprint-2-Semantik: extendsRegistrar
+    // (kommt aus user-data-rights) + useExtension auf fileRef.
+    const userDataProvider = defineFeature("test-user-data-provider", (r) => {
+      r.extendsRegistrar(EXT_USER_DATA, {
+        // Spec-stub — Sprint 2 wird die echten Hook-Signaturen liefern.
+      });
+    });
+
+    const consumer = defineFeature("test-files-consumer", (r) => {
+      r.requires("files", "test-user-data-provider");
+      r.useExtension(EXT_USER_DATA, "fileRef", {
+        // Stub-Hooks: in Sprint 2 werden diese die echte Forget-/Export-
+        // Logik tragen. Hier reicht: useExtension findet die fileRef-
+        // Entity in der Registry → kein Boot-Error.
+        export: async () => [],
+        delete: async () => undefined,
+      });
+    });
+
+    // Eigener Test-Stack damit dieser Sub-Test isoliert vom outer
+    // beforeAll-Stack laeuft.
+    const crossStack = await setupTestStack({
+      features: [feature, userDataProvider, consumer],
+    });
+    expect(crossStack).toBeDefined();
+    await crossStack.cleanup();
+  });
+
+  test("useExtension auf nicht-existierendes Entity wirft beim Boot", async () => {
+    const userDataProvider = defineFeature("test-user-data-provider-2", (r) => {
+      r.extendsRegistrar(EXT_USER_DATA, {});
+    });
+
+    const consumer = defineFeature("test-broken-consumer", (r) => {
+      r.requires("test-user-data-provider-2");
+      // GHOSTLY: useExtension auf "ghostEntity" gibt es nirgends.
+      r.useExtension(EXT_USER_DATA, "ghostEntity", {});
+    });
+
+    // Boot soll laufen — es ist NICHT der Job des Boot-Validators zu
+    // pruefen ob die referenced Entity existiert (Extensions sind
+    // generisch, "ghostEntity" könnte ein App-Entity in einem anderen
+    // Feature sein). Test dokumentiert das aktuelle Verhalten als
+    // Regression-Guard. Sprint 2 schaerft ggf. mit
+    // validateUserDataExtensionTargets.
+    const ghostStack = await setupTestStack({
+      features: [userDataProvider, consumer],
+    });
+    expect(ghostStack).toBeDefined();
+    await ghostStack.cleanup();
+  });
+});
+
+describe("files :: DDL-Konsistenz (M3, S1.7)", () => {
+  // Drizzle's getTableColumns liefert die typed column-map ohne den
+  // Symbol-Properties-Junk. Sauberer als Object.keys(table) das auch
+  // interne Drizzle-Symbols mitnimmt.
+  function pgColumnNames(): Set<string> {
+    return new Set(Object.keys(getTableColumns(fileRefsTable)));
+  }
+
+  test("Feature-Entity-Felder matchen die Framework-pgTable column-set", () => {
+    // Framework's fileRefsTable ist die Quelle der Wahrheit fuer die
+    // DB-Struktur. Feature-Entity ist Schema-Sicht. Beide muessen
+    // konsistent sein — sonst landet Sprint-2's userData-Hook in
+    // Drift-Hell beim Forget-Flow.
+    //
+    // Vergleich: alle Feature-Felder muessen als Spalten in der pgTable
+    // existieren (umgekehrt darf pgTable framework-managed Spalten haben
+    // wie tenantId/createdAt/updatedAt/deletedAt — die deklariert das
+    // Framework automatisch beim buildDrizzleTable-Mapping).
+    const pgColumns = pgColumnNames();
+    const featureFields = Object.keys(fileRefEntity.fields);
+
+    for (const field of featureFields) {
+      expect(
+        pgColumns.has(field),
+        `Feature-Field "${field}" fehlt in framework pgTable file_refs — Schema-Drift!`,
+      ).toBe(true);
+    }
+  });
+
+  test("Framework-pgTable hat die kritischen file_ref-Spalten (storageKey, fileName, mimeType, size)", () => {
+    const pgColumns = pgColumnNames();
+    expect(pgColumns.has("storageKey")).toBe(true);
+    expect(pgColumns.has("fileName")).toBe(true);
+    expect(pgColumns.has("mimeType")).toBe(true);
+    expect(pgColumns.has("size")).toBe(true);
+  });
+});
+
+describe("files :: event-QN-match (M4, S1.7)", () => {
+  test("framework's fileUploadedEvent.name === 'files:event:uploaded'", () => {
+    // Wenn das Framework den Event-Namen aendert, fliegt dieser Test
+    // sofort an — und der QN aus r.defineEvent("uploaded") im feature
+    // wuerde nicht mehr matchen. Drift-Guard.
+    expect(FILE_UPLOADED_EVENT_TYPE).toBe("files:event:uploaded");
+  });
+
+  test("Feature-Name 'files' + Event-Short 'uploaded' = QN 'files:event:uploaded'", () => {
+    // r.defineEvent("uploaded") in defineFeature("files", ...) resolved
+    // zu QN "files:event:uploaded" via Framework-Convention. Match
+    // garantiert dass framework's appendEvent + EventDef-Schema-
+    // Validation auf demselben QN landen.
+    const expected = `${feature.name}:event:uploaded`;
+    expect(expected).toBe(FILE_UPLOADED_EVENT_TYPE);
+  });
+});

package/src/files/feature.ts

@@ -0,0 +1,34 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { fileUploadedPayloadSchema } from "@cosmicdrift/kumiko-framework/files";
+import { fileRefEntity } from "./schema/file-ref";
+
+export { fileRefEntity } from "./schema/file-ref";
+
+// files — Schema-Sicht der framework-internen file_refs-Tabelle als
+// bundled-feature, damit Cross-Feature-Hooks (userData, tenantData) sich
+// an die "fileRef"-Entity hängen können.
+//
+// Sprint 1.5 (this commit):
+//   - r.entity("fileRef", fileRefEntity) — Schema-Surface
+//   - r.defineEvent("uploaded", schema)  — Event-Marker
+//
+// Sprint 2 (kommt):
+//   - r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })
+//
+// Sprint 5 (kommt):
+//   - r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })
+//
+// Routes bleiben framework-internal (multipart-Upload + binary-Streaming
+// passen nicht in das Handler-Pattern; siehe schema/file-ref.ts für
+// Architektur-Note).
+//
+// Sprint-1.5-Plan-Roadmap-Wille: "fileRefsTable bleibt in framework
+// (kein Daten-Move), aber r.entity('fileRef') deklariert sie für das
+// Feature." — diese Datei IST die Umsetzung.
+export function createFilesFeature(): FeatureDefinition {
+  return defineFeature("files", (r) => {
+    r.entity("fileRef", fileRefEntity);
+
+    r.defineEvent("uploaded", fileUploadedPayloadSchema);
+  });
+}

package/src/files/index.ts

@@ -0,0 +1 @@
+export { createFilesFeature, fileRefEntity } from "./feature";

package/src/files/schema/file-ref.ts

@@ -0,0 +1,58 @@
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// fileRef — Schema-Sicht der File-Metadata-Tabelle aus dem Framework.
+//
+// Architektur-Entscheidung (Sprint 1.5):
+//
+// Die DB-Tabelle `file_refs` lebt weiterhin in
+// `framework/src/files/file-ref-table.ts` als drizzle pgTable, weil
+// die Hono-Upload-/Download-Routes (`createFileRoutes` in
+// `framework/src/api/server.ts`) sie direkt nutzen. Multipart-Upload
+// und Binary-Streaming passen nicht in das Write/Query-Handler-Pattern
+// — Routes bleiben framework-internal.
+//
+// Was hier passiert: dieselbe DB-Tabelle wird zusätzlich als
+// `r.entity("fileRef")` in einem bundled-feature deklariert. Das
+// ermoeglicht:
+//   1. r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })
+//      in Sprint 2 — Forget-Flow + Daten-Export erkennen die Entity.
+//   2. r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })
+//      in Sprint 5 — Tenant-Lifecycle löscht alle FileRefs.
+//   3. Boot-Validation für PII-Annotations greift (fileName, originalName).
+//
+// Kein buildDrizzleTable hier — die Mapping-Tabelle existiert schon im
+// Framework. Drizzle-Reads in den Sprint-2+-Hooks gehen direkt über
+// `fileRefsTable` aus `@cosmicdrift/kumiko-framework/files`.
+//
+// PII-Annotations (Sprint 0.1+0.7+1.7):
+//   - fileName  → pii: true (Originalname enthält oft Personen-Bezug:
+//                "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf")
+//
+//   Andere Felder brauchen KEINE Annotation:
+//   - storageKey, mimeType, size, entityType, entityId, fieldName,
+//     insertedById → keine PII-typischen Field-Namen, PII-Heuristik
+//     greift nicht (siehe boot-validator.ts PII_DIRECT_NAME_HINTS).
+//     Ein allowPlaintext-Marker wäre Über-Annotation ohne Effekt.
+//   - insertedAt → Audit-Timestamp, framework-managed.
+//
+// Tabellenname matched die Framework-pgTable damit r.entity-Reads über
+// dieselbe Postgres-Tabelle laufen.
+export const fileRefEntity = createEntity({
+  table: "file_refs",
+  fields: {
+    storageKey: createTextField({ required: true }),
+    fileName: createTextField({ required: true, pii: true }),
+    mimeType: createTextField({ required: true }),
+    size: createNumberField({ required: true }),
+    entityType: createTextField(),
+    entityId: createTextField(),
+    fieldName: createTextField(),
+    insertedAt: createTimestampField({ sortable: true, filterable: true }),
+    insertedById: createTextField(),
+  },
+});

package/src/files-provider-s3/s3-provider.ts

@@ -1,3 +1,4 @@
+import { Readable } from "node:stream";
 import {
   DeleteObjectCommand,
   GetObjectCommand,
@@ -5,9 +6,45 @@ import {
   PutObjectCommand,
   S3Client,
 } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
 import { getSignedUrl as presign } from "@aws-sdk/s3-request-presigner";
 import type { FileStorageProvider, SignedUrlOptions } from "@cosmicdrift/kumiko-framework/files";
 
+// =============================================================================
+// Operator-Pflicht-Setup (Multipart-Upload-Cleanup)
+// =============================================================================
+//
+// `writeStream` nutzt @aws-sdk/lib-storage's Upload-class fuer echtes
+// multipart-streaming. S3 created dabei eine Multipart-Upload-Session mit
+// einer Upload-ID; bei normaler Completion wird sie via Complete-
+// MultipartUpload geschlossen.
+//
+// **Edge-Case bei Worker-Abort:** wenn der Export-Worker mid-write gecancelt
+// wird (Pod-Restart, K8s-OOM-Kill, Process-Signal), bleibt die Multipart-
+// Upload-Session in S3 OFFEN. S3 behaelt die bereits hochgeladenen Parts
+// und berechnet Storage-Kosten dafuer — bis sie manuell oder via Lifecycle-
+// Rule abgebrochen werden.
+//
+// **Pflicht-Operator-Setup auf jedem Bucket:**
+//
+//   {
+//     "Rules": [{
+//       "ID": "AbortIncompleteMultipartUploads",
+//       "Status": "Enabled",
+//       "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 },
+//       "Filter": {}
+//     }]
+//   }
+//
+// AWS-CLI: `aws s3api put-bucket-lifecycle-configuration --bucket <name>
+// --lifecycle-configuration file://lifecycle.json`. Hetzner Object Storage
+// + R2 + Minio supporten dieselbe Syntax.
+//
+// **Code-side abort()** fuer graceful Worker-Shutdown ist follow-up. Das
+// braucht Worker-Cancel-Semantik (AbortSignal-Propagation durch r.job),
+// die im framework noch nicht existiert. Bis dahin ist die Lifecycle-
+// Rule die einzige Garantie gegen Storage-Leakage.
+
 // Minimal config surface — everything the SDK needs, nothing framework-
 // specific. Apps wire this into `buildServer({ files: { storageProvider } })`
 // the same way they'd pass createLocalProvider in dev.
@@ -62,6 +99,33 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
       );
     },
 
+    async writeStream(key, source, options): Promise<void> {
+      // Echtes multipart-streaming via @aws-sdk/lib-storage.Upload —
+      // der Source-AsyncIterable wird chunk-weise zu S3 hochgeladen,
+      // niemals alles im Memory aggregiert. lib-storage handled
+      // automatisch chunking (5MB-Parts default), parallel-uploads
+      // (4 concurrent default), und retry bei Part-Failures.
+      //
+      // Memory-Footprint: ~5MB pro in-flight-part × 4 concurrent =
+      // ~20MB Heap-Bound, unabhaengig von der Total-Bundle-Size. Macht
+      // 1GB+ Bundles moeglich ohne OOM.
+      //
+      // Readable.from(source) adapiert AsyncIterable → node:Readable —
+      // lib-storage's Body-Type akzeptiert Web-ReadableStream + node-
+      // Readable, nicht direkt AsyncIterable. Adapter ist zero-copy.
+      const body = Readable.from(source);
+      const upload = new Upload({
+        client,
+        params: {
+          Bucket: config.bucket,
+          Key: key,
+          Body: body,
+          ...(options?.mimeType !== undefined && { ContentType: options.mimeType }),
+        },
+      });
+      await upload.done();
+    },
+
     async read(key): Promise<Uint8Array> {
       const response = await client.send(new GetObjectCommand({ Bucket: config.bucket, Key: key }));
       if (!response.Body) {
@@ -73,6 +137,31 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
       return response.Body.transformToByteArray();
     },
 
+    readStream(key): AsyncIterable<Uint8Array> {
+      // S3 GetObject.Body ist ein StreamingBlobPayloadOutputTypes — auf
+      // node ist das ein Readable-Stream der bereits AsyncIterable<Buffer>
+      // ist. Wir wrappen lazy: erst beim ersten chunk-pull wird der
+      // GetObject-Request abgesetzt. Wenn der Key nicht existiert, faellt
+      // der Error genau dort (nicht beim readStream-Aufruf) — gleiches
+      // Lazy-Verhalten wie inmemory + local.
+      return {
+        async *[Symbol.asyncIterator]() {
+          const response = await client.send(
+            new GetObjectCommand({ Bucket: config.bucket, Key: key }),
+          );
+          if (!response.Body) {
+            throw new Error(`s3_read_empty_body: ${key}`);
+          }
+          // SdkStream is AsyncIterable<Buffer> on node. Buffer extends
+          // Uint8Array; cast sichert die Surface ohne neue runtime-deps.
+          const body = response.Body as AsyncIterable<Uint8Array>;
+          for await (const chunk of body) {
+            yield chunk;
+          }
+        },
+      };
+    },
+
     async delete(key): Promise<void> {
       await client.send(new DeleteObjectCommand({ Bucket: config.bucket, Key: key }));
     },

package/src/secrets/__tests__/require-secrets-context.test.ts

@@ -0,0 +1,81 @@
+// requireSecretsContext-Surface-Tests (S2.U3 Atom 3b.fix2).
+//
+// Pinst dass `requireSecretsContext` mit dem schmalen FileProviderContext-
+// Surface funktioniert — nicht nur mit voller HandlerContext.
+// Regression-Pin fuer den latenten Worker-Pfad-Bug:
+//   - Vor 3b.fix wurde `ctx as unknown as HandlerContext` durchgereicht
+//   - Im Worker-Pfad ist `ctx._userId` undefined (dispatcher setzt es nur
+//     im request-Pfad), also throw `_userId missing`
+//   - Fix: Worker-Wrap setzt explizit `_userId: SYSTEM_USER_ID`
+//
+// Der Test inszeniert beide Surfaces (HandlerContext-shape via type-assert
+// + FileProviderContext-shape direkt) und prueft dass beide den happy-path
+// + den fehlt-_userId-throw durchlaufen.
+
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { describe, expect, test, vi } from "vitest";
+import { requireSecretsContext } from "../feature";
+
+function makeRawSecretsContext(): SecretsContext {
+  return {
+    get: vi.fn(),
+    set: vi.fn(),
+    delete: vi.fn(),
+  };
+}
+
+describe("requireSecretsContext :: FileProviderContext surface", () => {
+  test("succeeds with secrets + _userId present (Worker-Pfad mit SYSTEM_USER_ID)", () => {
+    const fileProviderCtx = {
+      secrets: makeRawSecretsContext(),
+      _userId: SYSTEM_USER_ID,
+    };
+    expect(() => requireSecretsContext(fileProviderCtx, "test-handler")).not.toThrow();
+  });
+
+  test("throws when _userId is missing (latenter Worker-Bug pre-3b.fix)", () => {
+    // Pinst die Falle die der 3b.fix abfaengt: wenn ein Provider-Plugin
+    // `requireSecretsContext` ruft und der ctx kein _userId hat (z.B. weil
+    // ein r.job-Wrap das vergessen hat zu setzen), faellt es FRUEH mit
+    // einer klaren Fehlermeldung um — nicht silent broken.
+    const fileProviderCtx = {
+      secrets: makeRawSecretsContext(),
+      // _userId absichtlich undefined
+    };
+    expect(() => requireSecretsContext(fileProviderCtx, "test-handler")).toThrow(/_userId missing/);
+  });
+
+  test("throws when secrets is missing (boot-Misconfig)", () => {
+    const fileProviderCtx = {
+      _userId: SYSTEM_USER_ID,
+      // secrets absichtlich undefined
+    };
+    expect(() => requireSecretsContext(fileProviderCtx, "test-handler")).toThrow(
+      /ctx\.secrets missing/,
+    );
+  });
+
+  test("audit-userId reaches secrets.get when call is delegated", async () => {
+    // Pinst den Audit-Pfad: wenn ein Plugin secrets.get(...) aufruft, kommt
+    // _userId als audit.userId ohne Override durch. Das ist der Grund warum
+    // SYSTEM_USER_ID nicht durch einen ad-hoc-magic-string ersetzt werden
+    // darf — sonst wird der Audit-Trail inkonsistent.
+    const raw = makeRawSecretsContext();
+    const ctx = {
+      secrets: raw,
+      _userId: SYSTEM_USER_ID,
+    };
+    const wrapped = requireSecretsContext(ctx, "user-data-rights:run-export-jobs");
+    await wrapped.get(
+      "tenant-x" as Parameters<SecretsContext["get"]>[0],
+      "any-key" as unknown as Parameters<SecretsContext["get"]>[1],
+    );
+    // Erste-Aufruf-args: [tenantId, key, audit-Object]
+    const audit = vi.mocked(raw.get).mock.calls[0]?.[2];
+    expect(audit).toEqual({
+      userId: SYSTEM_USER_ID,
+      handlerName: "user-data-rights:run-export-jobs",
+    });
+  });
+});

package/src/secrets/feature.ts

@@ -1,8 +1,4 @@
-import {
-  defineFeature,
-  type FeatureDefinition,
-  type HandlerContext,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { deleteWrite } from "./handlers/delete.write";
@@ -24,7 +20,15 @@ export { type StoredEnvelope, type StoredMetadata, tenantSecretsTable } from "./
 // wraps that raw context so every `.get(...)` call auto-includes the
 // current user + handler as audit metadata — feature code can't forget
 // to log the read (silent bypass of audit was the v1 gap).
-export function requireSecretsContext(ctx: HandlerContext, handlerName: string): SecretsContext {
+//
+// Surface bewusst minimal: HandlerContext-Pfade (Set/Delete-Handler) +
+// FileProviderContext-Pfade (S3-Plugin im Worker) liefern dieselben
+// zwei Felder, also reicht die schmale ctx-shape — kein voller
+// HandlerContext-Import noetig.
+export function requireSecretsContext(
+  ctx: { readonly secrets?: SecretsContext; readonly _userId?: string | undefined },
+  handlerName: string,
+): SecretsContext {
   if (!ctx.secrets) {
     throw new InternalError({
       message:

package/src/sessions/constants.ts

@@ -5,6 +5,10 @@ export const SESSIONS_FEATURE = "sessions" as const;
 export const SessionHandlers = {
   revoke: "sessions:write:user-session:revoke",
   revokeAllOthers: "sessions:write:user-session:revoke-all-others",
+  /** Privileged: System-Caller (cross-feature) revokes ALL live sessions
+   *  fuer einen User. Genutzt von user-data-rights:restrict-account
+   *  (DSGVO Art. 18 Account-Freeze). */
+  revokeAllForUser: "sessions:write:user-session:revoke-all-for-user",
 } as const;
 
 export const SessionQueries = {

package/src/sessions/feature.ts

@@ -3,6 +3,7 @@ import { cleanupJob } from "./handlers/cleanup.job";
 import { listQuery } from "./handlers/list.query";
 import { mineQuery } from "./handlers/mine.query";
 import { revokeWrite } from "./handlers/revoke.write";
+import { revokeAllForUserWrite } from "./handlers/revoke-all-for-user.write";
 import { revokeAllOthersWrite } from "./handlers/revoke-all-others.write";
 import { userSessionEntity } from "./schema/user-session";
 import type { SessionMassRevoker } from "./session-callbacks";
@@ -42,7 +43,9 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     const handlers = {
       revoke: r.writeHandler(revokeWrite),
       revokeAllOthers: r.writeHandler(revokeAllOthersWrite),
+      revokeAllForUser: r.writeHandler(revokeAllForUserWrite),
     };
+    r.exposesApi("sessions.revokeAllForUser");
 
     const queries = {
       mine: r.queryHandler(mineQuery),

package/src/sessions/handlers/revoke-all-for-user.write.ts

@@ -0,0 +1,42 @@
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { and, eq, isNull } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { userSessionTable } from "../schema/user-session";
+
+// Mass-revoke ALL live sessions for a target user — privileged-only.
+// Used by user-data-rights:restrict-account zur Account-Freeze
+// (DSGVO Art. 18) sowie potenziell anderen ops-flows ("ban user",
+// "compromised account"). Im Gegensatz zu revoke-all-others wird
+// die ggf. aufrufende Session ebenfalls revoked — Caller ist System
+// (cron/operator/cross-feature), nicht der Endnutzer selbst.
+//
+// Tenant-scope: das userSession-Schema persistiert tenantId pro Row
+// (User kann mehrere Sessions in mehreren Tenants haben). Wir
+// revoken cross-tenant, weil "Account-Restriction" eine globale
+// User-Aussage ist (Forget-Pfad ist auch global, sieht User-Entity-
+// special-Doc). UPDATE filtert nur auf userId.
+export const revokeAllForUserWrite = defineWriteHandler({
+  name: "user-session:revoke-all-for-user",
+  schema: z.object({
+    userId: z.string().min(1),
+  }),
+  access: { roles: access.privileged },
+  handler: async (event, ctx) => {
+    const updated = await ctx.db.raw
+      .update(userSessionTable)
+      .set({ revokedAt: Temporal.Now.instant() })
+      .where(
+        and(
+          eq(userSessionTable["userId"], event.payload.userId),
+          isNull(userSessionTable["revokedAt"]),
+        ),
+      )
+      .returning();
+
+    return {
+      isSuccess: true as const,
+      data: { count: updated.length, userId: event.payload.userId },
+    };
+  },
+});