@cosmicdrift/kumiko-framework 0.115.0 → 0.116.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.115.0",
+  "version": "0.116.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.115.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.116.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -3,14 +3,18 @@
 // and s3-env selected as the GDPR store without its env vars set.
 // V2 — export-without-erase guard. Catches features that register an export
 // hook but no delete hook (Art.17 violation).
+// V3 — PII-entity-without-hook guard. Catches entities with pii/userOwned
+// fields that no feature registers an EXT_USER_DATA hook for.
 
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import {
   validateGdprHookCompleteness,
+  validateGdprPiiHookCoverage,
   validateGdprStoragePersistence,
 } from "../boot-validator/gdpr-storage";
 import { defineFeature } from "../define-feature";
 import { EXT_USER_DATA } from "../extension-names";
+import { createEntity, createLongTextField, createTextField } from "../factories";
 
 const udr = () => defineFeature("user-data-rights", () => {});
 const fileProvider = (name: string) =>
@@ -141,3 +145,85 @@ describe("validateGdprHookCompleteness (V2)", () => {
     expect(String(warnSpy.mock.calls[0]?.[0])).toContain("entityB");
   });
 });
+
+describe("validateGdprPiiHookCoverage (V3)", () => {
+  let warnSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  const exportFn = async () => null;
+  const deleteFn = async () => {};
+
+  const piiFeature = () =>
+    defineFeature("crm", (r) => {
+      r.entity(
+        "contact",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true }),
+            note: createLongTextField({ userOwned: { ownerField: "authorId" } }),
+            authorId: { type: "reference", entity: "user" },
+          },
+        }),
+      );
+    });
+
+  test("user-data-rights not mounted → no warn", () => {
+    validateGdprPiiHookCoverage([piiFeature()]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("pii entity without any EXT_USER_DATA hook → warn naming entity and fields", () => {
+    validateGdprPiiHookCoverage([udr(), piiFeature()]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    expect(msg).toContain('"contact"');
+    expect(msg).toContain("email");
+    expect(msg).toContain("note");
+    expect(msg).toContain("Art.17");
+  });
+
+  test("pii entity with hook registered by another feature → no warn", () => {
+    const hooks = defineFeature("crm-user-data", (r) => {
+      r.useExtension(EXT_USER_DATA, "contact", { export: exportFn, delete: deleteFn });
+    });
+    validateGdprPiiHookCoverage([udr(), piiFeature(), hooks]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("entity without subject annotations → no warn", () => {
+    const plain = defineFeature("catalog", (r) => {
+      r.entity(
+        "product",
+        createEntity({
+          fields: { sku: createTextField({ allowPlaintext: "is-business-data" }) },
+        }),
+      );
+    });
+    validateGdprPiiHookCoverage([udr(), plain]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("userOwned field alone counts as user-subject data → warn", () => {
+    const f = defineFeature("notes", (r) => {
+      r.entity(
+        "note",
+        createEntity({
+          fields: {
+            body: createLongTextField({ userOwned: { ownerField: "authorId" } }),
+            authorId: { type: "reference", entity: "user" },
+          },
+        }),
+      );
+    });
+    validateGdprPiiHookCoverage([udr(), f]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0]?.[0])).toContain('"note"');
+  });
+});

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

@@ -1,5 +1,6 @@
 import { EXT_USER_DATA } from "../extension-names";
 import type { FeatureDefinition } from "../types";
+import type { PiiAnnotations } from "../types/fields";
 
 // Providers whose bytes do not survive a process restart. Only "inmemory"
 // today; extend if another ephemeral bundled provider lands.
@@ -78,3 +79,41 @@ export function validateGdprHookCompleteness(features: readonly FeatureDefinitio
     }
   }
 }
+
+// V3: PII-entity-without-hook guard. V2 checks registered hooks for
+// completeness; V3 catches the entity nobody registered at all — fields
+// annotated as user-subject data (pii / userOwned) yet invisible to the
+// Art.15/20 export and Art.17 forget pipeline. Matching is by entity name
+// across all features (usage.entityName is unqualified); a same-named entity
+// in another feature can mask a gap — accepted for a WARN-level heuristic.
+export function validateGdprPiiHookCoverage(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 hookedEntities = new Set<string>();
+  for (const f of features) {
+    for (const usage of f.extensionUsages) {
+      if (usage.extensionName === EXT_USER_DATA) hookedEntities.add(usage.entityName);
+    }
+  }
+
+  for (const feature of features) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      if (hookedEntities.has(entityName)) continue;
+      const subjectFields = Object.entries(entity.fields)
+        .filter(([, field]) => {
+          const annot = field as PiiAnnotations; // @cast-boundary schema-walk
+          return Boolean(annot.pii) || Boolean(annot.userOwned);
+        })
+        .map(([name]) => name);
+      if (subjectFields.length === 0) continue;
+      // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+      console.warn(
+        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has user-subject fields (${subjectFields.join(", ")}) but no feature registers an EXT_USER_DATA hook for it — the data never appears in Art.15/20 exports and is never erased on forget (Art.17 gap). Register r.useExtension(EXT_USER_DATA, "${entityName}", { export, delete }) in the owning feature or a defaults feature.`,
+      );
+    }
+  }
+}

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

@@ -27,7 +27,11 @@ import {
   validateReferenceFields,
   validateTransitions,
 } from "./entity-handler";
-import { validateGdprHookCompleteness, validateGdprStoragePersistence } from "./gdpr-storage";
+import {
+  validateGdprHookCompleteness,
+  validateGdprPiiHookCoverage,
+  validateGdprStoragePersistence,
+} from "./gdpr-storage";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
@@ -179,6 +183,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateGdprHookCompleteness(features);
+  validateGdprPiiHookCoverage(features);
 
   if (hasEncryptedFields) {
     // Availability check, not env-presence: eagerly building the keyring