@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/src/db/eagerload.ts

@@ -1,260 +0,0 @@
-// Tier 2.7e Server-Side Eagerload für Reference-Felder.
-//
-// Nach `executor.list`/`detail` scannen wir die zurückgelieferten
-// rows nach reference-Field-Values, sammeln pro Reference die UUIDs
-// (deduped), führen einen einzigen WHERE id IN (...)-Lookup pro
-// Referenced-Entity aus, und hängen die resolved Rows als
-// `_refs.<fieldName>` (single) bzw. `_refs.<fieldName>: Row[]`
-// (multiple) an die Original-Rows.
-//
-// Tenant-Scope: TenantDb hat den Tenant-Filter eingebaut (mode:
-// "tenant"); der Lookup erbt das transparent. Cross-Feature-Refs
-// landen automatisch im selben Tenant — falls ein referenced Item
-// dem User nicht gehört, kommt es aus dem Lookup nicht zurück
-// (TenantDb filtert), und der Renderer fällt auf UUID zurück.
-//
-// Limit: kein expliziter limit auf den Lookup-SELECT — wir
-// fragen genau die UUIDs ab die in den main-Rows vorkommen, also
-// O(n) pro Page (bei pageSize:50 mit 2 ref-Spalten = max 100 IDs).
-// Render-Side limit:200-Workaround entfällt damit komplett.
-//
-// Diese Datei lebt im framework/db damit sie an einer Stelle
-// zwischen executor und entity-handlers gemounted ist; sie nutzt
-// keine framework-engine-Internals und kann auch von custom
-// query-handlern manuell aufgerufen werden.
-
-import { requestContext } from "../api/request-context";
-import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto";
-import { selectMany } from "../db/query";
-import { parseRefTargetEntityName } from "../engine/parse-ref-target";
-import type { EntityDefinition, FieldDefinition, ReferenceFieldDef } from "../engine/types";
-import {
-  collectEncryptedFieldNames,
-  decryptEntityFieldValues,
-  resolveEntityFieldEncryption,
-} from "./entity-field-encryption";
-import { buildEntityTable } from "./table-builder";
-import type { TenantDb } from "./tenant-db";
-
-// Minimaler Registry-Lookup-Contract: pro entity-name → EntityDefinition.
-// Wir importieren NICHT den ganzen Registry-Type weil das einen
-// circular import zwischen db/ und engine/ erzeugen würde — der
-// Caller (entity-handlers.ts) hat ctx.registry und reicht hier eine
-// Closure rein.
-export type EagerLoadEntityResolver = (entityName: string) => EntityDefinition | undefined;
-
-// Tier 2.7e Audit-Fix #6: zentral typed Row-Shape mit _refs. Der
-// `_refs`-Property ist Server-Eagerload-Output: pro reference-Field
-// die resolved Row (single) oder ein Array resolved Rows (multiple).
-// Eine reference-Spalte mit value=null hat _refs[fieldName]=undefined.
-//
-// Renderer/Cell-Code liest `row._refs?.[fieldName]` statt inline-Cast;
-// Server-Code stempelt `_refs` über enrichWithReferences. Type ist
-// strukturell — auch Apps die ihre eigenen Refs setzen (Custom-
-// Handler) sollten das hier wiederverwenden.
-export type EagerloadedRow<T extends Record<string, unknown> = Record<string, unknown>> = T & {
-  readonly _refs?: Readonly<
-    Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>> | undefined>
-  >;
-};
-
-type ReferenceFieldEntry = {
-  readonly fieldName: string;
-  readonly refEntityName: string;
-  readonly multiple: boolean;
-};
-
-function isReferenceField(field: FieldDefinition): field is ReferenceFieldDef {
-  return field.type === "reference";
-}
-
-export function collectReferenceFields(entity: EntityDefinition): readonly ReferenceFieldEntry[] {
-  const out: ReferenceFieldEntry[] = [];
-  for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-    if (!isReferenceField(fieldDef)) continue;
-    out.push({
-      fieldName,
-      refEntityName: parseRefTargetEntityName(fieldDef.entity),
-      multiple: fieldDef.multiple === true,
-    });
-  }
-  return out;
-}
-
-// Referenced rows are read via a raw selectMany, not the referenced entity's
-// own executor context (enrichWithReferences only gets an
-// EagerLoadEntityResolver — routing through buildExecutorContext per ref
-// would need table/searchAdapter/entityCache wiring for no reason). Mirrors
-// event-store-executor-context's decryptForRead ordering: PII is the outer
-// layer, peel it before the envelope-encrypted fields, or the envelope
-// cipher chokes on a still-PII-wrapped string.
-//
-// Ownership guard (fw#1671): the ref lookup below is tenant-scoped only, not
-// ownership-scoped — this function has no SessionUser to evaluate
-// refEntity.access.read against. If the ref entity declares row-level
-// ownership at all, decrypting here would hand a same-tenant User A the
-// plaintext PII of a User B row they merely reference (e.g. a freely-settable
-// reference UUID), even though refEntity.access.read says "own" — the caller
-// never gets to run that ownership check. Fail closed: strip PII/encrypted
-// fields entirely instead of decrypting (or leaking ciphertext) when that
-// guarantee can't be evaluated here.
-function hasOwnershipScopedRead(refEntity: EntityDefinition): boolean {
-  const readMap = refEntity.access?.read;
-  if (readMap === undefined) return false;
-  // "all" means that role sees every row unrestricted — a map where every
-  // rule is "all" carries no ownership restriction at all, so stripping
-  // here would just silently drop PII/encrypted fields #1667 wants
-  // decrypted, for no security benefit.
-  return Object.values(readMap).some((rule) => rule !== "all");
-}
-
-async function decryptReferencedRow(
-  row: Record<string, unknown>,
-  refEntity: EntityDefinition,
-  piiFields: readonly string[],
-  encryptedFields: ReadonlySet<string>,
-  kms: ReturnType<typeof configuredPiiSubjectKms>,
-): Promise<Record<string, unknown>> {
-  if (hasOwnershipScopedRead(refEntity)) {
-    if (piiFields.length === 0 && encryptedFields.size === 0) return row;
-    const out = { ...row };
-    for (const field of piiFields) delete out[field];
-    for (const field of encryptedFields) delete out[field];
-    return out;
-  }
-
-  let out = row;
-  if (piiFields.length > 0 && kms) {
-    out = await decryptPiiFieldValues(out, piiFields, kms, {
-      requestId: requestContext.get()?.requestId ?? "eagerload",
-    });
-  }
-  if (encryptedFields.size > 0) {
-    out = await decryptEntityFieldValues(out, encryptedFields, resolveEntityFieldEncryption());
-  }
-  return out;
-}
-
-// Per-row, not Promise.all: a single legacy/backfilled row without a valid
-// envelope (decryptEntityFieldValues throws hard on malformed ciphertext)
-// must not 500 the whole list request — the main rows the caller asked for
-// are unrelated to this one broken reference. Drop just that row from the
-// map; the renderer falls back to the raw UUID.
-//
-// piiFields/encryptedFields/kms are constant per refEntity (fw#1671) — the
-// caller computes them once and passes them in instead of recomputing per row.
-async function buildRefLookupMap(
-  rawRefRows: ReadonlyArray<Record<string, unknown>>,
-  refEntity: EntityDefinition,
-  refEntityName: string,
-  piiFields: readonly string[],
-  encryptedFields: ReadonlySet<string>,
-  kms: ReturnType<typeof configuredPiiSubjectKms>,
-): Promise<Map<string, Record<string, unknown>>> {
-  const map = new Map<string, Record<string, unknown>>();
-  for (const r of rawRefRows) {
-    let decrypted: Record<string, unknown>;
-    try {
-      decrypted = await decryptReferencedRow(r, refEntity, piiFields, encryptedFields, kms);
-    } catch (e) {
-      console.warn(
-        `[eagerload] failed to decrypt referenced row entity=${refEntityName} id=${String(r["id"])}: ${e instanceof Error ? e.message : String(e)}`,
-      );
-      continue;
-    }
-    const id = decrypted["id"];
-    if (typeof id === "string") map.set(id, decrypted);
-  }
-  return map;
-}
-
-/** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
- *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
-export async function enrichWithReferences(
-  rows: ReadonlyArray<Record<string, unknown>>,
-  entity: EntityDefinition,
-  resolveEntity: EagerLoadEntityResolver,
-  db: TenantDb,
-): Promise<Array<Record<string, unknown>>> {
-  const refFields = collectReferenceFields(entity);
-  if (refFields.length === 0 || rows.length === 0) {
-    return rows.map((r) => ({ ...r }));
-  }
-
-  // Pro reference-Field: deduped Set der IDs sammeln, dann ein
-  // einziger SELECT WHERE id IN (...). Maps werden parallel gebaut
-  // damit die Lookups nicht serialisieren (Promise.all).
-  const lookupMaps = await Promise.all(
-    refFields.map(async (rf) => {
-      const ids = new Set<string>();
-      for (const row of rows) {
-        const v = row[rf.fieldName];
-        if (rf.multiple) {
-          if (Array.isArray(v)) {
-            for (const item of v) {
-              if (typeof item === "string" && item.length > 0) ids.add(item);
-            }
-          }
-        } else if (typeof v === "string" && v.length > 0) {
-          ids.add(v);
-        }
-      }
-      if (ids.size === 0) return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
-      const refEntity = resolveEntity(rf.refEntityName);
-      if (refEntity === undefined) {
-        // Author-Fehler oder Race-Condition (entity gerade umbenannt
-        // ohne registry-Reload). Boot-Validator hat das normalerweise
-        // gepinnt; Runtime-Defense: leere Map → Renderer fällt auf
-        // UUID zurück, kein Crash.
-        return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
-      }
-      const refTable = buildEntityTable(rf.refEntityName, refEntity);
-      const idArray = [...ids];
-      const rawRefRows = (await selectMany(db, refTable, { id: idArray })) as Array<
-        Record<string, unknown>
-      >;
-      const piiFields = collectPiiSubjectFields(refEntity);
-      const encryptedFields = collectEncryptedFieldNames(refEntity);
-      const kms = configuredPiiSubjectKms();
-      const map = await buildRefLookupMap(
-        rawRefRows,
-        refEntity,
-        rf.refEntityName,
-        piiFields,
-        encryptedFields,
-        kms,
-      );
-      return { fieldName: rf.fieldName, multiple: rf.multiple, map };
-    }),
-  );
-
-  return rows.map((row) => {
-    const refs: Record<string, unknown> = {};
-    for (const lookup of lookupMaps) {
-      const v = row[lookup.fieldName];
-      if (lookup.multiple) {
-        const ids = Array.isArray(v) ? v : [];
-        const resolved = ids
-          .map((id) => (typeof id === "string" ? lookup.map.get(id) : undefined))
-          .filter((r) => r !== undefined);
-        refs[lookup.fieldName] = resolved;
-      } else if (typeof v === "string" && v.length > 0) {
-        refs[lookup.fieldName] = lookup.map.get(v);
-      } else {
-        refs[lookup.fieldName] = undefined;
-      }
-    }
-    return { ...row, _refs: refs };
-  });
-}
-
-/** Single-Row-Variante für detail-Calls. */
-export async function enrichRowWithReferences(
-  row: Record<string, unknown>,
-  entity: EntityDefinition,
-  resolveEntity: EagerLoadEntityResolver,
-  db: TenantDb,
-): Promise<Record<string, unknown>> {
-  const enriched = await enrichWithReferences([row], entity, resolveEntity, db);
-  return enriched[0] ?? { ...row, _refs: {} };
-}

package/src/db/entity-field-encryption.ts

@@ -1,158 +0,0 @@
-// Entity-field encryption (`encrypted: true` on text/longText fields),
-// backed by the same envelope cipher as encrypted config values: JSON
-// StoredEnvelope in the TEXT column, kekVersion per value, legacy
-// single-key ciphertexts (pre-envelope ENCRYPTION_KEY era) readable via
-// the cipher's legacy fallback until re-encrypted.
-
-import { collectPiiSubjectFields } from "../crypto";
-import type { EntityDefinition, TenantId } from "../engine/types";
-import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider";
-import type { EnvelopeCipher } from "../secrets/envelope-cipher";
-import type { KeyScope } from "../secrets/types";
-
-export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string> {
-  const names = new Set<string>();
-  for (const [name, field] of Object.entries(entity.fields)) {
-    if ((field.type === "text" || field.type === "longText") && field.encrypted === true) {
-      names.add(name);
-    }
-  }
-  return names;
-}
-
-// A field whose stored value is ciphertext, either always (encrypted) or
-// depending on runtime KMS wiring (PII) — either way it has no plaintext
-// column to compare against directly.
-export function isSensitiveLabelField(entity: EntityDefinition, field: string): boolean {
-  return (
-    collectEncryptedFieldNames(entity).has(field) || collectPiiSubjectFields(entity).includes(field)
-  );
-}
-
-// `searchable: true` on a text field means it is indexed plaintext
-// somewhere findable by term — a plain text field's own column, or (for a
-// personal-data field) the derived search index mirroring it.
-export function hasSearchablePlaintext(entity: EntityDefinition, field: string): boolean {
-  const def = entity.fields[field];
-  return def?.type === "text" && def.searchable === true;
-}
-
-// BYOK hook: thread the row's tenant to the cipher when the row carries one
-// (system-scope rows may not).
-function scopeOf(row: Record<string, unknown>): KeyScope | undefined {
-  const tenantId = row["tenantId"];
-  return typeof tenantId === "string" ? { tenantId: tenantId as TenantId } : undefined; // @cast-boundary db-row
-}
-
-async function encryptFieldValue(
-  fieldName: string,
-  value: unknown,
-  cipher: EnvelopeCipher,
-  scope: KeyScope | undefined,
-): Promise<string> {
-  if (value === null || value === undefined) {
-    throw new Error(`encrypted field "${fieldName}" cannot be null or undefined`);
-  }
-  if (typeof value !== "string") {
-    throw new Error(`encrypted field "${fieldName}" must be a string, got ${typeof value}`);
-  }
-  return cipher.encrypt(value, scope);
-}
-
-export async function encryptEntityFieldValues(
-  row: Record<string, unknown>,
-  encryptedFields: ReadonlySet<string>,
-  cipher: EnvelopeCipher,
-  opts?: { onlyKeys?: Iterable<string> },
-): Promise<Record<string, unknown>> {
-  if (encryptedFields.size === 0) return row;
-  const only = opts?.onlyKeys ? new Set(opts.onlyKeys) : null;
-  const out = { ...row };
-  const scope = scopeOf(row);
-  for (const name of encryptedFields) {
-    if (only && !only.has(name)) continue;
-    if (!(name in out)) continue;
-    const value = out[name];
-    if (value === null || value === undefined) continue;
-    out[name] = await encryptFieldValue(name, value, cipher, scope);
-  }
-  return out;
-}
-
-export async function decryptEntityFieldValues(
-  row: Record<string, unknown>,
-  encryptedFields: ReadonlySet<string>,
-  cipher: EnvelopeCipher,
-): Promise<Record<string, unknown>> {
-  if (encryptedFields.size === 0) return row;
-  const out = { ...row };
-  const scope = scopeOf(row);
-  for (const name of encryptedFields) {
-    const value = out[name];
-    if (value === null || value === undefined) continue;
-    if (typeof value !== "string") continue;
-    out[name] = await cipher.decrypt(value, scope);
-  }
-  return out;
-}
-
-// Boot-injected app-wide cipher. run{Prod,Dev}App (and test setups that
-// exercise encrypted fields) call configureEntityFieldEncryption once with
-// the same cipher instance the config feature uses; executors resolve it
-// lazily so entities without encrypted fields never touch it.
-let injectedCipher: EnvelopeCipher | undefined;
-
-export function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void {
-  injectedCipher = cipher;
-}
-
-export function resolveEntityFieldEncryption(): EnvelopeCipher {
-  if (!injectedCipher) {
-    throw new Error(
-      "entity-field encryption is not configured — encrypted entity fields need a master key " +
-        "(KUMIKO_SECRETS_MASTER_KEY_V<n>); run{Prod,Dev}App wire the cipher automatically, " +
-        "custom boots call configureEntityFieldEncryption(cipher).",
-    );
-  }
-  return injectedCipher;
-}
-
-// Non-throwing probe for callers that degrade gracefully (DSGVO export
-// replaces encrypted fields with an explicit marker instead of failing
-// the whole export when no cipher is wired).
-export function configuredEntityFieldEncryption(): EnvelopeCipher | undefined {
-  return injectedCipher;
-}
-
-/** @internal test-only */
-export function resetEntityFieldEncryptionCacheForTests(): void {
-  injectedCipher = undefined;
-}
-
-// Boot-time availability probe for validateBoot: either a cipher was
-// injected, or the env keyring must be constructible — eager construction
-// surfaces missing AND malformed keys (wrong length, bad base64) at boot
-// instead of on the first encrypted read in prod. validateBoot runs before
-// configureEntityFieldEncryption, so the env probe is the common path.
-export function validateEntityFieldEncryptionAvailable(
-  env: Readonly<Record<string, string | undefined>> = process.env,
-): void {
-  // skip: an injected cipher (test seam / custom KMS) satisfies availability
-  if (injectedCipher) return;
-  try {
-    createEnvMasterKeyProvider({
-      env: {
-        ...env,
-        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION:
-          env["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
-      },
-    });
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `encrypted entity fields in use but no usable master key (${reason}) — set ` +
-        "KUMIKO_SECRETS_MASTER_KEY_V1 (32 bytes, base64) or inject a cipher via " +
-        "configureEntityFieldEncryption().",
-    );
-  }
-}

package/src/db/entity-table-from-registry.ts

@@ -1,31 +0,0 @@
-// The table an entity actually lives in, as the booted registry sees it.
-//
-// `buildEntityTable` derives a table from the entity definition alone, which is
-// right until something changed the projection after registration — an
-// extendEntityProjection, a featureName prefix, a table override. The registry
-// carries the result of all of that, so a caller that needs to read or write
-// the same rows the pipeline writes has to ask the registry first and may only
-// fall back to deriving.
-//
-// Callers are the ones holding a registry and an entity definition but no
-// executor: seeds, jobs and consumers that talk to a feature's read model
-// directly.
-
-import type { Registry } from "../engine";
-import type { SchemaTable } from "./dialect";
-import { buildEntityTable } from "./table-builder";
-
-export function entityTableFromRegistry(
-  registry: Registry,
-  entityName: string,
-  entity: Parameters<typeof buildEntityTable>[1],
-): SchemaTable {
-  for (const projection of registry.getAllProjections().values()) {
-    if (!projection.isImplicit) continue;
-    if (projection.source !== entityName) continue;
-    // @cast-boundary registry-projection — ProjectionDefinition.table is the
-    // untyped table object every projection registrar accepts.
-    return projection.table as SchemaTable;
-  }
-  return buildEntityTable(entityName, entity);
-}

package/src/db/entity-table-meta-types.ts

@@ -1,2 +0,0 @@
-// Legacy path — re-exported for callers still importing this module directly.
-export type * from "@cosmicdrift/kumiko-types/entity-table-meta-types";