@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

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

@@ -0,0 +1,198 @@
+import type { OwnershipMap, OwnershipRule } from "../ownership";
+import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
+
+// --- Ownership rule validation (H.2) ---
+//
+// Walks every entity.access and every field.access map, resolves each
+// FromRule against the cross-feature claim registry, and confirms the
+// referenced column exists on the entity. Catches typos, renames, and
+// cross-feature-claim-removal scenarios at boot instead of at request time.
+
+export function validateOwnershipRules(
+  feature: FeatureDefinition,
+  allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition>,
+  knownRoles: ReadonlySet<string>,
+): void {
+  for (const [entityName, entity] of Object.entries(feature.entities)) {
+    const columnNames = new Set<string>(Object.keys(entity.fields));
+    // Framework-managed columns that rules are allowed to reference too.
+    // These are the base columns buildDrizzleTable adds unconditionally.
+    const frameworkColumns = ["id", "tenantId", "version", "insertedAt", "modifiedAt"];
+    for (const col of frameworkColumns) columnNames.add(col);
+
+    // Entity-level access
+    if (entity.access?.read) {
+      checkOwnershipMap({
+        map: entity.access.read,
+        columnNames,
+        allClaimKeys,
+        knownRoles,
+        scope: `entity "${entityName}".access.read`,
+        featureName: feature.name,
+      });
+    }
+    if (entity.access?.write) {
+      checkOwnershipMap({
+        map: entity.access.write,
+        columnNames,
+        allClaimKeys,
+        knownRoles,
+        scope: `entity "${entityName}".access.write`,
+        featureName: feature.name,
+      });
+    }
+
+    // Field-level access — OwnershipMap form goes through checkOwnershipMap,
+    // legacy string[] through checkLegacyRoleList. Both enforce role-name
+    // existence against knownRoles so typos fail loud.
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+      checkFieldAccess({
+        access: field.access?.read,
+        columnNames,
+        allClaimKeys,
+        knownRoles,
+        scope: `${entityName}.${fieldName}.access.read`,
+        featureName: feature.name,
+      });
+      checkFieldAccess({
+        access: field.access?.write,
+        columnNames,
+        allClaimKeys,
+        knownRoles,
+        scope: `${entityName}.${fieldName}.access.write`,
+        featureName: feature.name,
+      });
+    }
+  }
+}
+
+export function checkFieldAccess(args: {
+  readonly access: OwnershipMap | readonly string[] | undefined;
+  readonly columnNames: ReadonlySet<string>;
+  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition>;
+  readonly knownRoles: ReadonlySet<string>;
+  readonly scope: string;
+  readonly featureName: string;
+}): void {
+  // skip: no access rules on this field, nothing to validate
+  if (!args.access) return;
+  if (Array.isArray(args.access)) {
+    // Legacy string[] form — every entry is a role name. Ref/column
+    // validation is n/a here (no claim refs in this shape), but the
+    // role-existence check applies.
+    checkLegacyRoleList(
+      args.access as readonly string[], // @cast-boundary schema-walk
+      args.knownRoles,
+      args.scope,
+      args.featureName,
+    );
+    // skip: legacy form validated, OwnershipMap check below doesn't apply
+    return;
+  }
+  checkOwnershipMap({
+    map: args.access as OwnershipMap, // @cast-boundary schema-walk
+    columnNames: args.columnNames,
+    allClaimKeys: args.allClaimKeys,
+    knownRoles: args.knownRoles,
+    scope: args.scope,
+    featureName: args.featureName,
+  });
+}
+
+export function checkLegacyRoleList(
+  roles: readonly string[],
+  knownRoles: ReadonlySet<string>,
+  scope: string,
+  featureName: string,
+): void {
+  // skip: no handler-declared roles in this app, role-validation disabled
+  if (!shouldValidateRoles(knownRoles)) return;
+  for (const roleName of roles) {
+    if (!knownRoles.has(roleName)) {
+      throw new Error(buildUnknownRoleMessage(roleName, knownRoles, scope, featureName));
+    }
+  }
+}
+
+// Only validate role-existence when at least one handler in the system has
+// declared a non-builtin role. Apps that run entirely on openToAll +
+// system-role handlers don't benefit from role-typo detection and would
+// otherwise get false-positive errors on every OwnershipMap — their
+// knownRoles corpus is empty beyond "all"/"system", so any app-defined
+// role would flag as unknown.
+export function shouldValidateRoles(knownRoles: ReadonlySet<string>): boolean {
+  for (const r of knownRoles) {
+    if (r !== "all" && r !== "system") return true;
+  }
+  return false;
+}
+
+export function checkOwnershipMap(args: {
+  readonly map: OwnershipMap;
+  readonly columnNames: ReadonlySet<string>;
+  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition>;
+  readonly knownRoles: ReadonlySet<string>;
+  readonly scope: string;
+  readonly featureName: string;
+}): void {
+  for (const [roleName, rawRule] of Object.entries(args.map)) {
+    // Role-existence check — typos like `{"Admi": "all"}` where no handler
+    // or other map mentions "Admi" would otherwise silently grant nothing.
+    // Skip when no app-defined roles exist anywhere (handler-less or
+    // system-only apps — shouldValidateRoles returns false there).
+    if (shouldValidateRoles(args.knownRoles) && !args.knownRoles.has(roleName)) {
+      throw new Error(
+        buildUnknownRoleMessage(roleName, args.knownRoles, args.scope, args.featureName),
+      );
+    }
+
+    // @cast-boundary schema-walk — extracted from feature-config inspection
+    const rule = rawRule as OwnershipRule;
+    if (rule === "all") continue;
+    if (rule.kind === "where") continue; // escape hatch — feature author owns the SQL
+
+    // FromRule — validate ref + column.
+    if (rule.refKind === "claim") {
+      // refPath is the qualified claim name ("feature:shortName").
+      const claim = args.allClaimKeys.get(rule.refPath);
+      if (!claim) {
+        const known = [...args.allClaimKeys.keys()].sort().join(", ") || "(none)";
+        throw new Error(
+          `[Kumiko Ownership] ${args.scope} references unknown claim "${rule.refPath}" ` +
+            `(role: "${roleName}", feature: "${args.featureName}"). ` +
+            `Declare it via r.claimKey("...", { type: "..." }) in the owning feature. ` +
+            `Known claims: ${known}`,
+        );
+      }
+      // String-compatible columns accept string and string[] claims equally
+      // (array → inArray). For other claim types we rely on the author
+      // knowing the row-column shape; we can't introspect PG types without
+      // the schema built. This is a best-effort ref-existence check.
+    }
+
+    if (!args.columnNames.has(rule.column)) {
+      const known = [...args.columnNames].sort().join(", ");
+      throw new Error(
+        `[Kumiko Ownership] ${args.scope} references column "${rule.column}" ` +
+          `which does not exist on the entity (role: "${roleName}", feature: ` +
+          `"${args.featureName}"). Available columns: ${known}`,
+      );
+    }
+  }
+}
+
+export function buildUnknownRoleMessage(
+  roleName: string,
+  knownRoles: ReadonlySet<string>,
+  scope: string,
+  featureName: string,
+): string {
+  const known = [...knownRoles].sort().join(", ");
+  return (
+    `[Kumiko Ownership] ${scope} references unknown role "${roleName}" ` +
+    `(feature: "${featureName}"). Roles are collected from handler access ` +
+    `rules across all features plus the "all" and "system" built-ins; if ` +
+    `"${roleName}" is real, make sure at least one handler declares ` +
+    `access.roles: ["${roleName}"]. Known roles: ${known}`
+  );
+}

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

@@ -0,0 +1,155 @@
+import type { FeatureDefinition } from "../types";
+import type { 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
+// genutzt werden auch wenn nicht in entity.fields deklariert.
+const FRAMEWORK_TIMESTAMP_FIELDS: ReadonlySet<string> = new Set([
+  "createdAt",
+  "updatedAt",
+  "lastSeenAt",
+  "deletedAt",
+]);
+
+// Erlaubtes Format fuer retention.keepFor — Zahlen + Suffix (h/d/w/m/y).
+// Echtes Parsen kommt mit dem Cleanup-Job in Sprint 2; Boot-Validator
+// macht nur den Sanity-Check damit Tippfehler ("30days") frueh sichtbar
+// werden statt erst beim ersten Cleanup-Run.
+const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
+
+// --- PII / Subject-Key Annotations + Retention validation ---
+//
+// Drei Klassen von Checks:
+//
+// 1. Mutual exclusion: pro Field nur EINE der drei Subject-Annotations
+//    (pii / userOwned / tenantOwned). Mehr ist semantisch widersprüchlich
+//    weil pro Field genau ein Subject-Key gehört.
+//
+// 2. Reference-Integrity: userOwned.ownerField muss auf ein existierendes
+//    reference-Field zeigen (das auf user-Entity zeigen sollte). Erkennt
+//    Tippfehler und Drop-Refactorings beim Boot statt beim ersten
+//    Encrypt-Aufruf.
+//
+// 3. Heuristik-Warnings: Field-Namen die typischerweise PII enthalten
+//    (email, name, phone, body, etc.) ohne Annotation → Boot-Warning.
+//    Mit `allowPlaintext: "<reason>"` unterdrückbar (geht in Audit).
+//
+// 4. Retention-Integrity: retention.reference (wenn gesetzt) muss auf
+//    ein bestehendes Field zeigen (oder Framework-Timestamp). retention.
+//    strategy="blockDelete" ohne anonymize-Felder ist sinnlos — User-
+//    Forget kann nichts machen, Warning.
+//
+// Encrypt/Decrypt-Mechanik landet in Sprint 3 (crypto-shredding); diese
+// Validation greift schon ab Sprint 0 damit Schema-Drift früh auffällt.
+export function validatePiiAndRetention(feature: FeatureDefinition): void {
+  for (const [entityName, entity] of Object.entries(feature.entities)) {
+    const fieldsByName = entity.fields;
+
+    for (const [fieldName, field] of Object.entries(fieldsByName)) {
+      // PiiAnnotations-Properties sind type-level optional. Auf Field-
+      // Defs die nicht via "& PiiAnnotations" erweitert sind (Boolean,
+      // Money, Reference, Embedded, Tz, LocatedTimestamp, File*, Image*)
+      // liefert property-access undefined zur Runtime. Die TS-Compile-
+      // Time-Validation hat dort schon abgelehnt → Cast ist safe.
+      const annot = field as PiiAnnotations; // @cast-boundary schema-walk
+
+      const hasPii = Boolean(annot.pii);
+      const hasUserOwned = Boolean(annot.userOwned);
+      const hasTenantOwned = Boolean(annot.tenantOwned);
+      const annotCount = (hasPii ? 1 : 0) + (hasUserOwned ? 1 : 0) + (hasTenantOwned ? 1 : 0);
+
+      if (annotCount > 1) {
+        throw new Error(
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has multiple subject-key annotations (pii / userOwned / tenantOwned). Pick one — each field belongs to exactly one subject.`,
+        );
+      }
+
+      if (annot.userOwned) {
+        const ownerName = annot.userOwned.ownerField;
+        if (!ownerName || typeof ownerName !== "string") {
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has userOwned without ownerField name`,
+          );
+        }
+        const ownerField = fieldsByName[ownerName];
+        if (!ownerField) {
+          const known = Object.keys(fieldsByName).sort().join(", ");
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references userOwned.ownerField "${ownerName}" but no such field exists. Known fields: ${known}`,
+          );
+        }
+        if (ownerField.type !== "reference") {
+          throw new Error(
+            `[Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" must be a reference 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.`,
+          );
+        }
+      }
+
+      // PII-Heuristik: nur wenn keine Annotation gesetzt UND kein
+      // allowPlaintext-Marker. Ergibt false positives auf Geschäftsdaten
+      // mit personenartigem Namen (z.B. company.legalName) — Author
+      // unterdrückt mit { allowPlaintext: "is-business-data" }.
+      const noAnnotation = annotCount === 0 && !annot.allowPlaintext;
+      if (noAnnotation) {
+        const lower = fieldName.toLowerCase();
+        if (PII_DIRECT_NAME_HINTS.has(lower)) {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no { pii: true } annotation. If this is PII, mark it. If business data, set { allowPlaintext: "is-business-data" } to silence.`,
+          );
+        } else if (PII_USER_OWNED_NAME_HINTS.has(lower)) {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no { userOwned } annotation. If this contains user-generated content, mark it { userOwned: { ownerField: "<authorIdField>" }}. If business data, set { allowPlaintext: "..." } to silence.`,
+          );
+        }
+      }
+    }
+
+    // --- Entity-level retention ---
+    const retention = entity.retention;
+    if (retention) {
+      if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
+        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+        console.warn(
+          `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.keepFor="${retention.keepFor}" hat ungueltiges Format. Erwartet: <Zahl><h|d|w|m|y> (z.B. "30d", "10y", "6m"). Cleanup-Job (Sprint 2) wird das nicht parsen koennen.`,
+        );
+      }
+
+      if (retention.reference !== undefined) {
+        const refName = retention.reference;
+        if (!fieldsByName[refName] && !FRAMEWORK_TIMESTAMP_FIELDS.has(refName)) {
+          const known = Object.keys(fieldsByName).sort().join(", ");
+          const framework = [...FRAMEWORK_TIMESTAMP_FIELDS].sort().join(", ");
+          throw new Error(
+            `[Feature ${feature.name}] Entity "${entityName}" retention.reference "${refName}" does not exist. Known fields: ${known} — framework-managed timestamps also accepted: ${framework}`,
+          );
+        }
+      }
+
+      if (retention.strategy === "blockDelete") {
+        const hasAnonymize = Object.values(fieldsByName).some((f) => {
+          const a = f as PiiAnnotations; // @cast-boundary schema-walk
+          return Boolean(a.anonymize);
+        });
+        if (!hasAnonymize) {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`,
+          );
+        }
+      }
+    }
+  }
+}