@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/file-foundation/__tests__/file-foundation.integration.ts

@@ -0,0 +1,235 @@
+// Full-stack integration test for file-foundation. Drives the
+// provider-factory through the dispatcher so the real config-resolver
+// + secrets-context + tenant-scoped reads are exercised.
+
+import { randomBytes } from "node:crypto";
+import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createEntityTable,
+  createTestUser,
+  pushTables,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createMutableMasterKeyProvider,
+  type MutableMasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createConfigFeature } from "../../config";
+import { ConfigHandlers } from "../../config/constants";
+import { createConfigAccessorFactory } from "../../config/feature";
+import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { fileProviderS3Feature, S3_SECRET_ACCESS_KEY } from "../../file-provider-s3";
+import { createSecretsContext, createSecretsFeature, tenantSecretsTable } from "../../secrets";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createFileProviderForTenant, fileFoundationFeature } from "../feature";
+
+// --- Test-Handler that exercises the factory end-to-end ---
+
+const TEST_HANDLER_QN = "file-test:write:build-provider";
+const testProbeFeature = defineFeature("file-test", (r) => {
+  r.requires("config");
+  r.requires("secrets");
+  r.writeHandler(
+    defineWriteHandler({
+      name: "build-provider",
+      schema: z.object({}),
+      access: { roles: ["TenantAdmin", "SystemAdmin"] },
+      handler: async (event, ctx) => {
+        const provider = await createFileProviderForTenant(
+          ctx,
+          event.user.tenantId,
+          TEST_HANDLER_QN,
+        );
+        return {
+          isSuccess: true,
+          data: {
+            hasWrite: typeof provider.write === "function",
+            hasRead: typeof provider.read === "function",
+            hasDelete: typeof provider.delete === "function",
+          },
+        };
+      },
+    }),
+  );
+});
+
+// --- Setup ---
+
+let stack: TestStack;
+let db: DbConnection;
+let resolver: ConfigResolver;
+let providerRef: MutableMasterKeyProvider;
+
+const testEncryptionKey = randomBytes(32).toString("base64");
+
+beforeAll(async () => {
+  const encryption = createEncryptionProvider(testEncryptionKey);
+  resolver = createConfigResolver({ encryption });
+
+  const initialKp = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+  providerRef = createMutableMasterKeyProvider(initialKp);
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createSecretsFeature(),
+      fileFoundationFeature,
+      fileProviderS3Feature,
+      testProbeFeature,
+    ],
+    masterKeyProvider: providerRef,
+    extraContext: ({ db, registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      secrets: createSecretsContext({ db, masterKeyProvider: providerRef }),
+    }),
+  });
+  db = stack.db;
+
+  await createEntityTable(db, tenantEntity);
+  await pushTables(db, { configValuesTable, tenant_secrets: tenantSecretsTable });
+  await createEventsTable(db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+}
+
+async function setConfig(admin: ReturnType<typeof adminFor>, key: string, value: unknown) {
+  await stack.http.writeOk(ConfigHandlers.set, { key, value }, admin);
+}
+
+/** Set the file-foundation provider-selector to "s3". */
+async function selectS3Provider(admin: ReturnType<typeof adminFor>) {
+  await setConfig(admin, "file-foundation:config:provider", "s3");
+}
+
+// --- Scenario 1: full happy-path roundtrip (Hetzner Object Storage shape) ---
+
+describe("scenario 1: happy path", () => {
+  test("admin sets config + secret → factory builds working file-storage provider", async () => {
+    const admin = adminFor(501);
+
+    await selectS3Provider(admin);
+    // Hetzner Object Storage typical config — covers MinIO/R2/S3 too via
+    // endpoint + forcePathStyle. AccessKeyId is public-ish, secret goes
+    // into the encrypted secrets store.
+    await setConfig(admin, "file-provider-s3:config:bucket", "test-bucket");
+    await setConfig(admin, "file-provider-s3:config:region", "fsn1");
+    await setConfig(
+      admin,
+      "file-provider-s3:config:endpoint",
+      "https://fsn1.your-objectstorage.com",
+    );
+    await setConfig(admin, "file-provider-s3:config:force-path-style", true);
+    await setConfig(admin, "file-provider-s3:config:access-key-id", "AKIATEST123");
+
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: S3_SECRET_ACCESS_KEY.name, value: "secret-key-not-actually-real" },
+      admin,
+    );
+
+    const result = (await stack.http.writeOk(TEST_HANDLER_QN, {}, admin)) as Record<
+      string,
+      unknown
+    >;
+    expect(result["hasWrite"]).toBe(true);
+    expect(result["hasRead"]).toBe(true);
+    expect(result["hasDelete"]).toBe(true);
+  });
+});
+
+// --- Scenario 2: validation errors ---
+
+describe("scenario 2: validation errors", () => {
+  test("missing bucket → factory throws with hint instead of cryptic SDK error", async () => {
+    const admin = adminFor(502);
+
+    await selectS3Provider(admin);
+    // Set everything except bucket. requireNonEmpty rejects with a clear
+    // message naming `bucket`.
+    await setConfig(admin, "file-provider-s3:config:region", "us-east-1");
+    await setConfig(admin, "file-provider-s3:config:access-key-id", "AKIATEST");
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: S3_SECRET_ACCESS_KEY.name, value: "secret" },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
+    expect(JSON.stringify(error)).toMatch(/'bucket' is empty/);
+  });
+
+  test("missing secret-access-key → factory throws naming the secret", async () => {
+    const admin = adminFor(503);
+
+    await selectS3Provider(admin);
+    await setConfig(admin, "file-provider-s3:config:bucket", "b");
+    await setConfig(admin, "file-provider-s3:config:region", "us-east-1");
+    await setConfig(admin, "file-provider-s3:config:access-key-id", "AKIATEST");
+    // Skip the secret. Factory throws referencing S3_SECRET_ACCESS_KEY.name.
+
+    const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
+    expect(JSON.stringify(error)).toMatch(/s3-secret-access-key/);
+  });
+});
+
+// --- Scenario 3: tenant isolation ---
+
+describe("scenario 3: tenant isolation", () => {
+  test("tenant A's S3 config doesn't bleed into tenant B's provider", async () => {
+    const adminA = adminFor(504);
+    const adminB = adminFor(505);
+
+    await selectS3Provider(adminA);
+    await selectS3Provider(adminB);
+
+    await setConfig(adminA, "file-provider-s3:config:bucket", "tenant-a-bucket");
+    await setConfig(adminA, "file-provider-s3:config:region", "fsn1");
+    await setConfig(adminA, "file-provider-s3:config:access-key-id", "A-KEY");
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: S3_SECRET_ACCESS_KEY.name, value: "secret-a" },
+      adminA,
+    );
+
+    await setConfig(adminB, "file-provider-s3:config:bucket", "tenant-b-bucket");
+    await setConfig(adminB, "file-provider-s3:config:region", "us-east-1");
+    await setConfig(adminB, "file-provider-s3:config:access-key-id", "B-KEY");
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: S3_SECRET_ACCESS_KEY.name, value: "secret-b" },
+      adminB,
+    );
+
+    const a = (await stack.http.writeOk(TEST_HANDLER_QN, {}, adminA)) as Record<string, unknown>;
+    const b = (await stack.http.writeOk(TEST_HANDLER_QN, {}, adminB)) as Record<string, unknown>;
+    expect(a["hasWrite"]).toBe(true);
+    expect(b["hasWrite"]).toBe(true);
+  });
+});

package/src/file-foundation/feature.ts

@@ -0,0 +1,123 @@
+// kumiko-feature-version: 1
+//
+// file-foundation as a Kumiko bundled feature — plugin-API shape.
+//
+// **Pattern-Vorbild:** identisch zu `mail-foundation`. Foundation
+// deklariert extension-point `fileProvider`, Provider-Features (file-
+// provider-s3, später file-provider-azure-blob, file-provider-gcs)
+// registrieren sich namentlich. Tenant wählt zur Runtime via config-
+// key `provider`.
+//
+// **Was diese Foundation NICHT mehr macht:**
+//   - Keine S3-spezifischen Config-Keys mehr (bucket/region/endpoint/
+//     forcePathStyle/accessKeyId) — die leben im Provider-Plugin.
+//   - Kein direkter Import von `createS3Provider`. Foundation kennt
+//     nur das `FileStorageProvider`-Interface (Type-Import, kein
+//     runtime-coupling).
+//
+// **Standalone:** Foundation ist ohne tier-engine nutzbar. Existing
+// `files-provider-s3` (App-wide-Library) bleibt unangetastet.
+//
+// **Boot-Dependencies:** config (für provider-selector). Kein secrets,
+// weil Foundation selbst keine Secrets hält.
+
+import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import {
+  access,
+  createTenantConfig,
+  defineFeature,
+  type HandlerContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+
+const FEATURE_NAME = "file-foundation";
+
+// =============================================================================
+// Plugin-Interface — what a Provider-Plugin must implement
+// =============================================================================
+
+/**
+ * File-Storage-Plugin contract. Each provider-feature (file-provider-s3,
+ * file-provider-azure-blob, ...) registers an implementation via
+ * `r.useExtension("fileProvider", "<name>", { build })`.
+ */
+export type FileProviderPlugin = {
+  readonly build: (ctx: HandlerContext, tenantId: string) => Promise<FileStorageProvider>;
+};
+
+// =============================================================================
+// Feature-definition
+// =============================================================================
+
+export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.requires("config");
+
+  r.extendsRegistrar("fileProvider", {
+    onRegister: () => {
+      // No side-effects at register-time — registry stores the usage,
+      // factory looks it up at request-time.
+    },
+  });
+
+  const configKeys = r.config({
+    keys: {
+      provider: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+      }),
+    },
+  });
+
+  return { configKeys };
+});
+
+// =============================================================================
+// Provider-factory — looks up the registered plugin + delegates
+// =============================================================================
+
+export async function createFileProviderForTenant(
+  ctx: HandlerContext,
+  tenantId: string,
+  handlerName = "file-foundation:provider-factory",
+): Promise<FileStorageProvider> {
+  const ctxConfig = ctx.config;
+  if (!ctxConfig) {
+    throw new Error(
+      `${handlerName}: ctx.config is missing — feature requires the config-feature mounted in the registry`,
+    );
+  }
+  if (!ctx.registry) {
+    throw new Error(
+      `${handlerName}: ctx.registry is missing — required to look up registered file-provider plugins`,
+    );
+  }
+
+  const provider = requireDefined(
+    await ctxConfig(fileFoundationFeature.exports.configKeys.provider),
+    FEATURE_NAME,
+    "provider",
+  ) as string;
+  if (provider.length === 0) {
+    const usages = ctx.registry.getExtensionUsages("fileProvider");
+    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+    throw new Error(
+      `${FEATURE_NAME}: no provider selected — set the 'provider' config-key to one of: ${known}. ` +
+        `Mount a file-provider-* feature first if no plugins are registered.`,
+    );
+  }
+
+  const usages = ctx.registry.getExtensionUsages("fileProvider");
+  const usage = usages.find((u) => u.entityName === provider);
+  if (!usage) {
+    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+    throw new Error(
+      `${FEATURE_NAME}: provider "${provider}" not registered. Known: ${known}. ` +
+        `Mount the matching file-provider-${provider} feature.`,
+    );
+  }
+
+  // @cast-boundary engine-payload — extension-usage carries unknown options
+  const plugin = usage.options as FileProviderPlugin;
+  return plugin.build(ctx, tenantId);
+}

package/src/file-foundation/index.ts

@@ -0,0 +1,7 @@
+// Public API of the file-foundation bundled-feature.
+
+export {
+  createFileProviderForTenant,
+  type FileProviderPlugin,
+  fileFoundationFeature,
+} from "./feature";

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

@@ -0,0 +1,35 @@
+// feature.ts contract tests for file-provider-inmemory.
+
+import { describe, expect, test } from "vitest";
+import { clearStorage, fileProviderInMemoryFeature, listKeys } from "../feature";
+
+describe("fileProviderInMemoryFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(fileProviderInMemoryFeature.name).toBe("file-provider-inmemory");
+  });
+
+  test("requires only file-foundation (no config, no secrets)", () => {
+    expect(fileProviderInMemoryFeature.requires).toContain("file-foundation");
+    expect(fileProviderInMemoryFeature.requires).not.toContain("config");
+    expect(fileProviderInMemoryFeature.requires).not.toContain("secrets");
+  });
+});
+
+describe("fileProviderInMemoryFeature — plugin-registration", () => {
+  test("registers itself under entityName 'inmemory' for file-foundation's extension", () => {
+    const usages = fileProviderInMemoryFeature.extensionUsages;
+    expect(
+      usages.some((u) => u.extensionName === "fileProvider" && u.entityName === "inmemory"),
+    ).toBe(true);
+  });
+});
+
+describe("listKeys / clearStorage — per-tenant store helpers", () => {
+  test("listKeys liefert empty-array für unbekannten Tenant", () => {
+    expect(listKeys("never-touched")).toEqual([]);
+  });
+
+  test("clearStorage auf unbekannten Tenant ist no-op", () => {
+    expect(() => clearStorage("never-touched")).not.toThrow();
+  });
+});

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

@@ -0,0 +1,73 @@
+// kumiko-feature-version: 1
+//
+// file-provider-inmemory — In-Memory-FileProvider für die file-
+// foundation Plugin-API. Speichert Files in einem per-Tenant-Map
+// statt in S3/Hetzner-Object-Storage. Für Demos, Sample-Apps und
+// Tests ohne MinIO-Container.
+//
+// **Was diese Feature liefert:**
+//   1. Plugin-Registration via `r.useExtension("fileProvider",
+//      "inmemory", { build })`.
+//   2. **Pro-Tenant Storage.** Jeder Tenant kriegt einen eigenen
+//      InMemoryFileProvider — Tenant-Isolation by-design, keine
+//      Pfad-Konvention nötig.
+//
+// **Pattern-Vorbild:** mirrors file-provider-s3.
+//
+// **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 {
+  createInMemoryFileProvider,
+  type FileStorageProvider,
+  type InMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+
+const FEATURE_NAME = "file-provider-inmemory";
+
+// =============================================================================
+// Per-tenant in-memory store
+// =============================================================================
+
+const providersByTenant = new Map<string, InMemoryFileProvider>();
+
+function getOrCreateProviderForTenant(tenantId: string): InMemoryFileProvider {
+  let provider = providersByTenant.get(tenantId);
+  if (!provider) {
+    provider = createInMemoryFileProvider();
+    providersByTenant.set(tenantId, provider);
+  }
+  return provider;
+}
+
+/** Demo/Test-Helper: liste die Keys eines Tenant-Storage. */
+export function listKeys(tenantId: string): readonly string[] {
+  return providersByTenant.get(tenantId)?.keys() ?? [];
+}
+
+/** Demo/Test-Helper: leere den Tenant-Storage. */
+export function clearStorage(tenantId: string): void {
+  providersByTenant.get(tenantId)?.clear();
+}
+
+// =============================================================================
+// Feature-definition
+// =============================================================================
+
+export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
+  // Kein r.requires("config") + kein r.requires("secrets") — der
+  // In-Memory-Provider hat keine Config + kein Secret. Nur die
+  // file-foundation muss da sein (Plugin-extension-point).
+  r.requires("file-foundation");
+
+  const plugin: FileProviderPlugin = {
+    build: async (_ctx: HandlerContext, tenantId: string): Promise<FileStorageProvider> => {
+      // Returnt den per-tenant Storage. Identitätsstabil zwischen calls
+      // damit accumulated state erhalten bleibt.
+      return getOrCreateProviderForTenant(tenantId);
+    },
+  };
+  r.useExtension("fileProvider", "inmemory", plugin);
+});

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

@@ -0,0 +1,3 @@
+// Public API of the file-provider-inmemory bundled-feature.
+
+export { clearStorage, fileProviderInMemoryFeature, listKeys } from "./feature";

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

@@ -0,0 +1,54 @@
+// feature.ts contract tests for file-provider-s3.
+
+import { describe, expect, test } from "vitest";
+import { fileProviderS3Feature, S3_SECRET_ACCESS_KEY } from "../feature";
+
+describe("fileProviderS3Feature — shape", () => {
+  test("has the expected name", () => {
+    expect(fileProviderS3Feature.name).toBe("file-provider-s3");
+  });
+
+  test("requires config + secrets + file-foundation", () => {
+    expect(fileProviderS3Feature.requires).toContain("config");
+    expect(fileProviderS3Feature.requires).toContain("secrets");
+    expect(fileProviderS3Feature.requires).toContain("file-foundation");
+  });
+});
+
+describe("fileProviderS3Feature.exports — typed handles", () => {
+  test("exports.configKeys covers the S3-config knobs", () => {
+    const keys = fileProviderS3Feature.exports.configKeys;
+    expect(keys.bucket).toBeDefined();
+    expect(keys.region).toBeDefined();
+    expect(keys.endpoint).toBeDefined();
+    expect(keys.forcePathStyle).toBeDefined();
+    expect(keys.accessKeyId).toBeDefined();
+  });
+
+  test("exports.secretAccessKey is the S3_SECRET_ACCESS_KEY secret-handle (drift-pin)", () => {
+    expect(fileProviderS3Feature.exports.secretAccessKey).toBe(S3_SECRET_ACCESS_KEY);
+    expect(S3_SECRET_ACCESS_KEY.name).toBe("file-provider-s3:secret:s3-secret-access-key");
+  });
+});
+
+describe("S3_SECRET_ACCESS_KEY — generic redaction", () => {
+  const secretDef = fileProviderS3Feature.secretKeys["s3.secretAccessKey"];
+
+  test("redact preserves first 4 + last 4 chars on long keys", () => {
+    expect(secretDef?.redact).toBeDefined();
+    expect(secretDef?.redact?.("AKIA1234567890ABCDEFGHIJ7890klmn")).toMatch(/^AKIA\.\.\.klmn$/);
+  });
+
+  test("redact masks short keys completely", () => {
+    expect(secretDef?.redact?.("short")).toBe("•".repeat(5));
+  });
+});
+
+describe("fileProviderS3Feature — plugin-registration", () => {
+  test("registers itself under entityName 's3' for file-foundation's extension", () => {
+    const usages = fileProviderS3Feature.extensionUsages;
+    expect(usages.some((u) => u.extensionName === "fileProvider" && u.entityName === "s3")).toBe(
+      true,
+    );
+  });
+});