@cosmicdrift/kumiko-framework 0.116.1 → 0.119.0

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/handlers.ts

@@ -267,6 +267,10 @@ type SharedContextFields = {
   // job which deliberately operates outside the per-call audit trail (it
   // processes rows system-wide, not a per-user read).
   readonly masterKeyProvider?: import("../../secrets").MasterKeyProvider;
+  // Subject-key adapter for crypto-shredding (GDPR Art. 17). Present when
+  // the app wired a KmsAdapter at boot; the PII envelope engine and the
+  // forget pipeline reach for it. Absent = crypto-shredding not enabled.
+  readonly kms?: import("../../crypto").KmsAdapter;
   // Observability: optional at the outer boundary, always populated by the
   // time a handler receives its ctx (Noop fallback when no provider is
   // configured, so handler code can call ctx.tracer/ctx.metrics without

package/src/engine/types/index.ts

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