@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -0,0 +1,125 @@
+// Nav validation + collectKnownRoles (role synthesis for ownership
+// validation in index.ts — thematically adjacent to ownership.ts, kept
+// here since this is a structural move, not a semantic reorg).
+
+import { qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+
+export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
+  const set = new Set<string>();
+  for (const f of features) {
+    for (const handlerName of Object.keys(f.writeHandlers)) {
+      set.add(qualifyEntityName(f.name, "write", handlerName));
+    }
+  }
+  return set;
+}
+
+export function collectNavQns(
+  features: readonly FeatureDefinition[],
+): Map<string, NavDefinition & { readonly featureName: string }> {
+  const map = new Map<string, NavDefinition & { readonly featureName: string }>();
+  for (const f of features) {
+    for (const [navId, navDef] of Object.entries(f.navs)) {
+      const qualified = qualifyEntityName(f.name, "nav", navId);
+      map.set(qualified, { ...navDef, featureName: f.name });
+    }
+  }
+  return map;
+}
+
+// Per-feature ref validation: screen + parent refs point at real QNs. Cycle
+// detection runs once globally afterwards (it's cheaper to do a single DFS
+// over the merged graph than restart it per feature).
+export function validateNavs(
+  feature: FeatureDefinition,
+  allScreenQns: ReadonlySet<string>,
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
+): void {
+  for (const [navId, navDef] of Object.entries(feature.navs)) {
+    if (navDef.screen !== undefined && !allScreenQns.has(navDef.screen)) {
+      throw new Error(
+        `[Feature ${feature.name}] Nav entry "${navId}" references screen "${navDef.screen}" ` +
+          `which is not registered. Expected a qualified name of the form ` +
+          `"<feature>:screen:<id>" pointing at an r.screen() declaration.`,
+      );
+    }
+    if (navDef.parent !== undefined && !allNavQns.has(navDef.parent)) {
+      throw new Error(
+        `[Feature ${feature.name}] Nav entry "${navId}" references parent "${navDef.parent}" ` +
+          `which is not a registered nav entry. Expected a qualified name of the form ` +
+          `"<feature>:nav:<id>".`,
+      );
+    }
+    if (navDef.workspaces !== undefined) {
+      for (const wsQn of navDef.workspaces) {
+        if (!allWorkspaceQns.has(wsQn)) {
+          throw new Error(
+            `[Feature ${feature.name}] Nav entry "${navId}" self-assigns to workspace "${wsQn}" ` +
+              `which is not registered. Expected a qualified name of the form ` +
+              `"<feature>:workspace:<id>" pointing at an r.workspace() declaration.`,
+          );
+        }
+      }
+    }
+  }
+}
+
+// Walks parent-refs across ALL nav entries (cross-feature). A cycle here
+// would crash client-side tree assembly — easier to fail loud at boot than
+// to debug a React "Maximum update depth exceeded" stack trace.
+export function validateNavCycles(
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+): void {
+  const visited = new Set<string>();
+  const stack = new Set<string>();
+
+  function visit(qualified: string, path: string[]): void {
+    if (stack.has(qualified)) {
+      throw new Error(
+        `[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}`,
+      );
+    }
+    // skip: already visited — cycle-detection only needs to traverse each
+    // node once, and the `stack` check above catches any actual cycles
+    // reached via a different path.
+    if (visited.has(qualified)) return;
+    visited.add(qualified);
+    stack.add(qualified);
+    const navDef = allNavQns.get(qualified);
+    if (navDef?.parent) {
+      visit(navDef.parent, [...path, qualified]);
+    }
+    stack.delete(qualified);
+  }
+
+  for (const qualified of allNavQns.keys()) {
+    visit(qualified, []);
+  }
+}
+
+// Roles we recognise at boot time. The framework has no explicit
+// role-registry (r.defineRoles is a type helper only), so we synthesise
+// one from every handler-access rule plus the "all"/"system" built-ins.
+export function collectKnownRoles(features: readonly FeatureDefinition[]): Set<string> {
+  const roles = new Set<string>(["all", "system"]);
+  for (const f of features) {
+    for (const def of Object.values(f.writeHandlers)) {
+      if (def.access && "roles" in def.access) {
+        for (const r of def.access.roles) roles.add(r);
+      }
+    }
+    for (const def of Object.values(f.queryHandlers)) {
+      if (def.access && "roles" in def.access) {
+        for (const r of def.access.roles) roles.add(r);
+      }
+    }
+    for (const def of Object.values(f.streamHandlers)) {
+      if (def.access && "roles" in def.access) {
+        for (const r of def.access.roles) roles.add(r);
+      }
+    }
+  }
+  return roles;
+}

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

@@ -1,5 +1,5 @@
 import type { FeatureDefinition } from "../types";
-import type { PiiAnnotations } from "../types/fields";
+import type { FieldAccess, PiiAnnotations } from "../types/fields";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS } from "./entity-handler";
 
 // Framework-managed Timestamp-Spalten — dürfen als retention.reference
@@ -64,6 +64,84 @@ 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.`,
+          );
+        }
+      }
+
+      // piiEncrypted (kumiko-platform#231/#456): a declarative alias over
+      // the subject-KMS — text only (storage stays the plaintext column
+      // with subject ciphertext, no separate envelope path).
+      const piiEncryptedFlag = field as { readonly piiEncrypted?: boolean }; // @cast-boundary schema-walk
+      if (piiEncryptedFlag.piiEncrypted === true && field.type !== "text") {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } but has type "${field.type}" — piiEncrypted only applies to text fields.`,
+        );
+      }
+      // piiEncrypted wiring (kumiko-platform#457): resolveSubjectForField/
+      // collectPiiSubjectFields only ever look at pii/userOwned/tenantOwned
+      // — piiEncrypted alone doesn't pick a subject. Without one of the
+      // three, the field would silently stay plaintext (no encrypt-on-
+      // write happens). Fail at boot like lookupable does, not at first read.
+      if (piiEncryptedFlag.piiEncrypted === true && annotCount === 0) {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } without a subject annotation (pii / userOwned / tenantOwned) — piiEncrypted alone doesn't encrypt anything, it only adds the access/masking layer on top of the subject-key encryption.`,
+        );
+      }
+      // piiEncrypted access model (kumiko-platform#460): field-level
+      // access.read already exists + is enforced (filterReadFields), but
+      // its default without an access config is "visible to everyone" —
+      // the wrong default for a field whose entire point is "only the
+      // legitimate owner may see the plaintext". Force an explicit choice
+      // instead of silently decrypting for every row-reader.
+      const accessFlag = field as { readonly access?: FieldAccess }; // @cast-boundary schema-walk
+      if (piiEncryptedFlag.piiEncrypted === true && !accessFlag.access?.read) {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } without { access: { read: [...] } } — without it the decrypted value is visible to anyone who can read the row. Set the roles allowed to see the plaintext.`,
+        );
+      }
+
+      // sensitive-Felder liegen seit #967 als Tabellen-Ciphertext im Event-
+      // Log — ohne ciphertext-at-rest würde der Append Klartext in die
+      // immutable History schreiben.
+      const sensitiveFlags = field as {
+        readonly sensitive?: boolean;
+        readonly encrypted?: boolean;
+      }; // @cast-boundary schema-walk
+      if (
+        sensitiveFlags.sensitive === true &&
+        annotCount === 0 &&
+        sensitiveFlags.encrypted !== true
+      ) {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (pii / userOwned / tenantOwned) or { encrypted: true }.`,
+        );
+      }
+
+      // 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 || piiEncryptedFlag.piiEncrypted === true) {
+        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 or { piiEncrypted: true } 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 +156,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.`,
+            );
+          }
         }
       }