@cosmicdrift/kumiko-framework 0.118.0 → 0.119.0

package/src/engine/__tests__/boot-validator-pii-retention.test.ts

@@ -133,19 +133,36 @@ describe("validateBoot — PII annotations", () => {
     );
   });
 
-  test("userOwned.ownerField pointing to non-reference field throws", () => {
+  test("userOwned.ownerField on a text field passes (ES userId-by-convention)", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
         "comment",
         createEntity({
           fields: {
-            body: createLongTextField({ userOwned: { ownerField: "authorName" } }),
-            authorName: createTextField(),
+            body: createLongTextField({ userOwned: { ownerField: "authorId" } }),
+            authorId: createTextField(),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("userOwned.ownerField pointing to a non-id-capable field throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "comment",
+        createEntity({
+          fields: {
+            body: createLongTextField({ userOwned: { ownerField: "isPublic" } }),
+            isPublic: { type: "boolean" },
           },
         }),
       );
     });
-    expect(() => validateBoot([feature])).toThrow(/must be a reference field, got type "text"/);
+    expect(() => validateBoot([feature])).toThrow(
+      /must be a reference or text \(userId\) field, got type "boolean"/,
+    );
   });
 
   test("userOwned.ownerField referencing non-user entity warns", () => {
@@ -568,3 +585,77 @@ describe("validateBoot — retention", () => {
     expect(matchingWarn).toBeUndefined();
   });
 });
+
+describe("validateBoot — lookupable / blind-index (#818)", () => {
+  test("lookupable on subject-annotated text field passes", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true, lookupable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("lookupable without subject annotation throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "doc",
+        createEntity({
+          fields: {
+            slug: createTextField({ lookupable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/lookupable.*without a subject annotation/);
+  });
+
+  test("lookupable on non-text field throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "person",
+        createEntity({
+          fields: {
+            // longText carries PiiAnnotations too — lookupable must still be rejected.
+            bio: createLongTextField({ userOwned: { ownerField: "ownerId" }, lookupable: true }),
+            ownerId: createTextField({ required: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/only apply to text fields/);
+  });
+
+  test("searchable combined with a subject annotation throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            displayName: createTextField({ pii: true, searchable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/searchable.*cannot work/);
+  });
+
+  test("sortable combined with a subject annotation throws", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ pii: true, sortable: true }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/sortable.*cannot work/);
+  });
+});

package/src/engine/__tests__/unmanaged-table.test.ts

@@ -3,7 +3,11 @@
 // drizzle migrate-runner). See define-feature.ts / DX-4.
 
 import { describe, expect, test } from "bun:test";
-import { defineUnmanagedTable, resolveTableName } from "../../db/entity-table-meta";
+import {
+  buildEntityTableMeta,
+  defineUnmanagedTable,
+  resolveTableName,
+} from "../../db/entity-table-meta";
 import { defineFeature } from "../define-feature";
 import { createEntity, createTextField } from "../index";
 import { createRegistry } from "../registry";
@@ -125,3 +129,44 @@ describe("createRegistry — unmanagedTable aggregation", () => {
     );
   });
 });
+
+describe("createRegistry — unmanaged tables with PII-annotated fields (#820)", () => {
+  const piiEntity = createEntity({
+    table: "ut_pii_probe",
+    fields: {
+      userId: createTextField({ required: true }),
+      ip: createTextField({ userOwned: { ownerField: "userId" } }),
+    },
+  });
+  const piiMeta = buildEntityTableMeta("ut-pii-probe", piiEntity);
+
+  test("buildEntityTableMeta records the subject-annotated field names", () => {
+    expect(piiMeta.piiSubjectFields).toEqual(["ip"]);
+  });
+
+  test("rejects a PII-carrying unmanaged table without piiEncryptedOnWrite", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.unmanagedTable(piiMeta, { reason: "direct-write store" });
+    });
+    expect(() => createRegistry([feat])).toThrow(
+      /has PII-annotated fields \(ip\) but direct writes bypass the executor's PII encryption/,
+    );
+  });
+
+  test("accepts it once the feature declares piiEncryptedOnWrite", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.unmanagedTable(piiMeta, {
+        reason: "direct-write store",
+        piiEncryptedOnWrite: true,
+      });
+    });
+    expect(() => createRegistry([feat])).not.toThrow();
+  });
+
+  test("a PII-free unmanaged table needs no declaration", () => {
+    const feat = defineFeature("probe", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "plain store" });
+    });
+    expect(() => createRegistry([feat])).not.toThrow();
+  });
+});

package/src/engine/boot-validator/pii-retention.ts

@@ -64,6 +64,35 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         );
       }
 
+      // lookupable (#818): nur text + nur MIT Subject-Annotation. Ohne
+      // Subject bleibt der Wert eh Klartext — der Blind-Index wäre eine
+      // zweite (deterministische!) Kopie ohne Nutzen.
+      if (annot.lookupable === true) {
+        if (field.type !== "text") {
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { lookupable: true } but has type "${field.type}" — blind-index equality lookups only apply to text fields.`,
+          );
+        }
+        if (annotCount === 0) {
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { lookupable: true } without a subject annotation (pii / userOwned / tenantOwned). Plaintext fields don't need a blind index — add the subject annotation or drop lookupable.`,
+          );
+        }
+      }
+
+      // Substring-Suche/Sortierung auf Ciphertext ist prinzipbedingt
+      // unmöglich — searchable würde Plaintext-Kopien in den Suchindex
+      // schieben, sortable sortiert Base64-Blobs. Equality → lookupable.
+      if (annotCount > 0) {
+        const flags = field as { readonly searchable?: boolean; readonly sortable?: boolean }; // @cast-boundary schema-walk
+        if (flags.searchable === true || flags.sortable === true) {
+          const offending = flags.searchable === true ? "searchable" : "sortable";
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation with { ${offending}: true } — ${offending} on encrypted fields cannot work (ciphertext at rest). For equality lookups use { lookupable: true }; for search/sort the field must stay plaintext (allowPlaintext).`,
+          );
+        }
+      }
+
       if (annot.userOwned) {
         const ownerName = annot.userOwned.ownerField;
         if (!ownerName || typeof ownerName !== "string") {
@@ -78,21 +107,28 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
             `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references userOwned.ownerField "${ownerName}" but no such field exists. Known fields: ${known}`,
           );
         }
-        if (ownerField.type !== "reference") {
+        // Text is accepted alongside reference: the ES-framework carries
+        // user ids as plain text columns throughout the bundled features
+        // (user-session.userId, invitation.invitedBy) — there is no
+        // relational FK to point a reference at. Self-referencing
+        // ownerField (the field's own value IS the owner id) rides on this.
+        if (ownerField.type !== "reference" && ownerField.type !== "text") {
           throw new Error(
-            `[Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" must be a reference field, got type "${ownerField.type}"`,
+            `[Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`,
           );
         }
         // Soft-Warning wenn das reference-target nicht offensichtlich user
         // ist — custom subject-entities (HR-Mitarbeiter, Patient) sind
         // erlaubt, müssen aber bewusste Wahl sein.
-        const refTarget = ownerField.entity;
-        const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
-        if (targetEntity !== "user") {
-          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-          console.warn(
-            `[kumiko:boot] [Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`,
-          );
+        if (ownerField.type === "reference") {
+          const refTarget = ownerField.entity;
+          const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
+          if (targetEntity !== "user") {
+            // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+            console.warn(
+              `[kumiko:boot] [Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`,
+            );
+          }
         }
       }
 

package/src/engine/define-feature.ts

@@ -66,6 +66,7 @@ import type {
   TreeChildrenSubscribe,
   UiHints,
   UnmanagedTableEntry,
+  UnmanagedTableOptions,
   ValidationHookFn,
   WriteHandlerDef,
   WriteHandlerFn,
@@ -867,7 +868,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       };
     },
 
-    unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void {
+    unmanagedTable(meta: EntityTableMeta, options: UnmanagedTableOptions): void {
       // Name comes from the meta itself — apps already give the table a
       // name when calling defineUnmanagedTable, no need to repeat it.
       const tableName = meta.tableName;
@@ -896,6 +897,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
         name: tableName,
         meta,
         reason: options.reason,
+        ...(options.piiEncryptedOnWrite && { piiEncryptedOnWrite: true }),
       };
     },
 

package/src/engine/registry.ts

@@ -678,6 +678,15 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
             `Pick a different tableName — both would emit CREATE TABLE "${umName}".`,
         );
       }
+      const piiFields = umDef.meta.piiSubjectFields ?? [];
+      if (piiFields.length > 0 && !umDef.piiEncryptedOnWrite) {
+        throw new Error(
+          `Unmanaged-table "${umName}" (feature "${feature.name}") has PII-annotated fields ` +
+            `(${piiFields.join(", ")}) but direct writes bypass the executor's PII encryption. ` +
+            `Encrypt those fields before every insert/update (encryptPiiFieldValues) and declare ` +
+            `{ piiEncryptedOnWrite: true }, or drop the subject annotations.`,
+        );
+      }
       physicalTableOwners.set(umName, {
         kind: "unmanaged",
         owner: umName,

package/src/engine/types/feature.ts

@@ -168,6 +168,15 @@ export type UnmanagedTableEntry = {
   readonly name: string;
   readonly meta: EntityTableMeta;
   readonly reason: string;
+  readonly piiEncryptedOnWrite?: true;
+};
+
+/** Options for r.unmanagedTable(). Direct-write stores skip the executor,
+ *  so the executor's PII encryption never runs for them — a feature whose
+ *  meta carries piiSubjectFields must encrypt those fields itself before
+ *  every insert/update and declare that here, or boot fails (#820). */
+export type UnmanagedTableOptions = RawTableOptions & {
+  readonly piiEncryptedOnWrite?: true;
 };
 
 /** Registry-aggregated unmanaged-table — adds the owning feature name. */
@@ -718,7 +727,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // `PgTable` (legacy), unmanagedTable carries the new `EntityTableMeta`
   // shape that `migrate-runner` consumes. After the full drizzle-cut they
   // will likely merge; for now they coexist.
-  unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void;
+  unmanagedTable(meta: EntityTableMeta, options: UnmanagedTableOptions): void;
 
   // Register the tree-actions schema for this feature — a map of
   // action-name → action-definition (with optional typed args). At-most-

package/src/engine/types/fields.ts

@@ -62,6 +62,12 @@ export type PiiAnnotations = {
   readonly tenantOwned?: boolean;
   readonly anonymize?: () => unknown | Promise<unknown>;
   readonly allowPlaintext?: string;
+  /** Equality-Lookups (fetchOne/filter eq) bleiben trotz Verschluesselung
+   *  moeglich: generierte `<snake>_bidx`-Spalte traegt einen HMAC-Blind-
+   *  Index, Query-Compiler matchen `(col = $1 OR col_bidx = $2)`. Nur auf
+   *  text-Feldern MIT Subject-Annotation erlaubt (Boot-Validator).
+   *  Siehe docs/plans/datenschutz/blind-index.md (kumiko-framework#818). */
+  readonly lookupable?: true;
 };
 
 // --- Retention (DSGVO Art. 5(1)(e) + HGB/AO Aufbewahrungspflichten) ---

package/src/engine/types/index.ts

@@ -78,6 +78,7 @@ export type {
   UiHints,
   UnmanagedTableDef,
   UnmanagedTableEntry,
+  UnmanagedTableOptions,
 } from "./feature";
 export type {
   AnyFileFieldDef,