@cosmicdrift/kumiko-framework 0.80.0 → 0.81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.80.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.81.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/boot-validator-gdpr-storage.test.ts

@@ -0,0 +1,74 @@
+// V1 — GDPR storage-persistence boot guard. Catches the prod failure class:
+// user-data-rights mounted but exports land in an ephemeral / missing store,
+// and s3-env selected as the GDPR store without its env vars set.
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { validateGdprStoragePersistence } from "../boot-validator/gdpr-storage";
+import { defineFeature } from "../define-feature";
+
+const udr = () => defineFeature("user-data-rights", () => {});
+const fileProvider = (name: string) =>
+  defineFeature(`file-provider-${name}`, (r) => {
+    r.useExtension("fileProvider", name);
+  });
+
+const S3_ENV = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"] as const;
+
+describe("validateGdprStoragePersistence (V1)", () => {
+  let warnSpy: ReturnType<typeof spyOn>;
+  let savedEnv: Array<readonly [string, string | undefined]>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    savedEnv = S3_ENV.map((k) => [k, process.env[k]] as const);
+    for (const k of S3_ENV) delete process.env[k];
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  });
+
+  test("no user-data-rights → never warns", () => {
+    validateGdprStoragePersistence([fileProvider("inmemory")]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("user-data-rights + only inmemory → ephemeral-store warn", () => {
+    validateGdprStoragePersistence([udr(), fileProvider("inmemory")]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0]?.[0])).toContain("LOST on restart");
+  });
+
+  test("user-data-rights + no file provider at all → ephemeral-store warn", () => {
+    validateGdprStoragePersistence([udr()]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test("user-data-rights + s3 provider → no warn", () => {
+    validateGdprStoragePersistence([udr(), fileProvider("s3")]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("user-data-rights + s3-env, env missing → s3-env env warn naming the vars", () => {
+    validateGdprStoragePersistence([udr(), fileProvider("s3-env")]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    expect(msg).toContain("S3_BUCKET");
+    expect(msg).toContain("s3-env");
+  });
+
+  test("user-data-rights + s3-env, env set → no warn", () => {
+    for (const k of S3_ENV) process.env[k] = "x";
+    validateGdprStoragePersistence([udr(), fileProvider("s3-env")]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("user-data-rights + s3 AND s3-env (use-all-bundled shape) → no warn even with env unset", () => {
+    validateGdprStoragePersistence([udr(), fileProvider("s3"), fileProvider("s3-env")]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/src/engine/boot-validator/gdpr-storage.ts

@@ -0,0 +1,59 @@
+import type { FeatureDefinition } from "../types";
+
+// Providers whose bytes do not survive a process restart. Only "inmemory"
+// today; extend if another ephemeral bundled provider lands.
+const EPHEMERAL_PROVIDERS: ReadonlySet<string> = new Set(["inmemory"]);
+
+// Env vars file-provider-s3-env reads (see files-provider-s3/env-helper).
+// Missing any → createS3ProviderFromEnv throws on the first file op.
+const S3_ENV_REQUIRED = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"] as const;
+
+// Cross-feature GDPR storage guard (V1). Catches the failure class we shipped
+// to prod: user-data-rights mounted but exports land in an ephemeral / missing
+// store (lost on restart → the download 500s), and — once s3-env is the GDPR
+// store — its env vars unset (the provider throws lazily on the first export
+// inside the cron instead of failing loud at boot).
+//
+// Registry-only signal: validateBoot can't see the app's effective `provider`
+// config-override, so it reasons from the registered fileProvider plugins. A
+// false negative is possible (mount a persistent provider, then override the
+// config back to inmemory) — accepted; the common shape (no persistent store)
+// is caught, and this is a WARN, not a hard gate.
+export function validateGdprStoragePersistence(features: readonly FeatureDefinition[]): void {
+  const featureNames = new Set(features.map((f) => f.name));
+  if (!featureNames.has("user-data-rights")) {
+    // skip: this guard only applies to apps that mount user-data-rights
+    return;
+  }
+
+  const registeredProviders = new Set<string>();
+  for (const f of features) {
+    for (const usage of f.extensionUsages) {
+      if (usage.extensionName === "fileProvider") registeredProviders.add(usage.entityName);
+    }
+  }
+
+  const persistent = [...registeredProviders].filter((p) => !EPHEMERAL_PROVIDERS.has(p));
+
+  if (persistent.length === 0) {
+    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+    console.warn(
+      "[kumiko:boot] user-data-rights is mounted but no persistent file provider is — GDPR exports use an ephemeral/in-memory store and are LOST on restart (the download then 500s). Mount file-provider-s3 or file-provider-s3-env and select it via the file-foundation provider config.",
+    );
+    // skip: ephemeral store already warned; the s3-env env-var check below is moot
+    return;
+  }
+
+  // s3-env is the sole persistent store → it's the effective GDPR store. Its
+  // credentials come from env; a missing var only surfaces at the first file op
+  // (inside the export cron). Surface it at boot instead.
+  if (persistent.length === 1 && persistent[0] === "s3-env") {
+    const missing = S3_ENV_REQUIRED.filter((v) => !process.env[v]);
+    if (missing.length > 0) {
+      // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+      console.warn(
+        `[kumiko:boot] file-provider-s3-env is the GDPR file store but these env vars are unset: ${missing.join(", ")}. The provider throws on the first export (inside the cron), not here — set them so GDPR storage works.`,
+      );
+    }
+  }
+}

package/src/engine/boot-validator/index.ts

@@ -25,6 +25,7 @@ import {
   validateReferenceFields,
   validateTransitions,
 } from "./entity-handler";
+import { validateGdprStoragePersistence } from "./gdpr-storage";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
 import {
@@ -160,6 +161,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateNavCycles(allNavQns);
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateExtensionPreSaveWiring(features);
+  validateGdprStoragePersistence(features);
 
   if (hasEncryptedFields && !process.env["ENCRYPTION_KEY"]) {
     throw new Error("ENCRYPTION_KEY environment variable is required (encrypted fields in use)");

package/src/engine/extensions/user-data.ts

@@ -43,10 +43,33 @@ export type UserDataDeleteStrategy = "delete" | "anonymize";
  * raw-DB-Operationen machen funktionieren auf beiden Shapes via
  * Drizzle's polymorphem select/insert/update/delete-Chain.
  */
+/**
+ * Minimal storage surface a file-aware forget hook needs to erase binaries.
+ * Structural on purpose — the engine stays free of a dependency on the files
+ * package; `FileStorageProvider` is assignable here. The forget/export
+ * orchestrator resolves the concrete provider per tenant from the mounted
+ * file-foundation and injects it via `UserDataHookCtx.buildStorageProvider`.
+ */
+export interface UserDataStorageProvider {
+  delete(storageKey: string): Promise<void>;
+}
+
 export interface UserDataHookCtx {
   readonly db: DbRunner;
   readonly tenantId: TenantId;
   readonly userId: UserId;
+  /**
+   * Per-tenant storage-provider resolver, injected by the forget orchestrator
+   * from the mounted file-foundation — so a hook deletes binaries from the
+   * SAME store the upload/export path uses (delete-target == upload-target by
+   * construction). Undefined when no file provider is resolvable; file-aware
+   * hooks then skip binary cleanup (row-only delete) and warn. Resolution
+   * failures (provider not configured) should be caught by the hook so a
+   * misconfigured store never permanently blocks the user's erasure.
+   */
+  readonly buildStorageProvider?: (
+    tenantId: TenantId,
+  ) => Promise<UserDataStorageProvider | undefined>;
 }
 
 /**

package/src/engine/index.ts

@@ -86,6 +86,7 @@ export type {
   UserDataExportSnippet,
   UserDataExtensionHooks,
   UserDataHookCtx,
+  UserDataStorageProvider,
 } from "./extensions/user-data";
 export {
   createBigIntField,