@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/db/eagerload.js

@@ -0,0 +1,191 @@
+// 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.js";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
+import { selectMany } from "../db/query.js";
+import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
+import { collectEncryptedFieldNames, decryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
+import { buildEntityTable } from "./table-builder.js";
+function isReferenceField(field) {
+    return field.type === "reference";
+}
+export function collectReferenceFields(entity) {
+    const out = [];
+    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) {
+    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, refEntity, piiFields, encryptedFields, kms) {
+    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, refEntity, refEntityName, piiFields, encryptedFields, kms) {
+    const map = new Map();
+    for (const r of rawRefRows) {
+        let decrypted;
+        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, entity, resolveEntity, db) {
+    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();
+        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 }));
+        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 = {};
+        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, entity, resolveEntity, db) {
+    const enriched = await enrichWithReferences([row], entity, resolveEntity, db);
+    return enriched[0] ?? { ...row, _refs: {} };
+}

package/dist/db/entity-field-encryption.d.ts

@@ -0,0 +1,15 @@
+import type { EntityDefinition } from "../engine/types/index.js";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher.js";
+export declare function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string>;
+export declare function isSensitiveLabelField(entity: EntityDefinition, field: string): boolean;
+export declare function hasSearchablePlaintext(entity: EntityDefinition, field: string): boolean;
+export declare function encryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher, opts?: {
+    onlyKeys?: Iterable<string>;
+}): Promise<Record<string, unknown>>;
+export declare function decryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher): Promise<Record<string, unknown>>;
+export declare function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void;
+export declare function resolveEntityFieldEncryption(): EnvelopeCipher;
+export declare function configuredEntityFieldEncryption(): EnvelopeCipher | undefined;
+/** @internal test-only */
+export declare function resetEntityFieldEncryptionCacheForTests(): void;
+export declare function validateEntityFieldEncryptionAvailable(env?: Readonly<Record<string, string | undefined>>): void;

package/dist/db/entity-field-encryption.js

@@ -0,0 +1,127 @@
+// 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/index.js";
+import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider.js";
+export function collectEncryptedFieldNames(entity) {
+    const names = new Set();
+    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, field) {
+    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, field) {
+    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) {
+    const tenantId = row["tenantId"];
+    return typeof tenantId === "string" ? { tenantId: tenantId } : undefined; // @cast-boundary db-row
+}
+async function encryptFieldValue(fieldName, value, cipher, scope) {
+    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, encryptedFields, cipher, opts) {
+    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, encryptedFields, cipher) {
+    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;
+export function configureEntityFieldEncryption(cipher) {
+    injectedCipher = cipher;
+}
+export function resolveEntityFieldEncryption() {
+    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() {
+    return injectedCipher;
+}
+/** @internal test-only */
+export function resetEntityFieldEncryptionCacheForTests() {
+    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 = process.env) {
+    // 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/dist/db/entity-table-from-registry.d.ts

@@ -0,0 +1,4 @@
+import type { Registry } from "../engine/index.js";
+import type { SchemaTable } from "./dialect.js";
+import { buildEntityTable } from "./table-builder.js";
+export declare function entityTableFromRegistry(registry: Registry, entityName: string, entity: Parameters<typeof buildEntityTable>[1]): SchemaTable;

package/dist/db/entity-table-from-registry.js

@@ -0,0 +1,25 @@
+// 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 { buildEntityTable } from "./table-builder.js";
+export function entityTableFromRegistry(registry, entityName, entity) {
+    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;
+    }
+    return buildEntityTable(entityName, entity);
+}

package/dist/db/entity-table-meta-types.d.ts

@@ -0,0 +1 @@
+export type * from "@cosmicdrift/kumiko-types/entity-table-meta-types";

package/dist/db/entity-table-meta-types.js

@@ -0,0 +1 @@
+export {};

package/dist/db/entity-table-meta.d.ts

@@ -0,0 +1,30 @@
+import type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
+import type { EntityDefinition } from "../engine/types/index.js";
+import type { BuildEntityTableMetaOptions, EntityTableMeta, UnmanagedTableInput } from "./entity-table-meta-types.js";
+export type { BuildEntityTableMetaOptions, ColumnMeta, CompositePrimaryKeyMeta, EntityTableMeta, IndexMeta, PgType, UnmanagedTableInput, } from "./entity-table-meta-types.js";
+export declare function resolveTableName(entityName: string, entity: EntityDefinition, featureName: string | undefined): string;
+/**
+ * Derive EntityTableMeta from an EntityDefinition (base columns + field DDL).
+ * Defaults to `source: "managed"` (rebuildable projection). For direct-write
+ * stores pass `{ source: "unmanaged" }` and use a non-`read_` table name
+ * (convention: `store_*`) — or build columns by hand with `defineUnmanagedTable`.
+ *
+ * Named `derive*` (not `build*Meta`) so it is not mistaken for the unmanaged
+ * escape hatch (#1208).
+ */
+export declare function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options?: BuildEntityTableMetaOptions): EntityTableMeta;
+/** @deprecated Use {@link deriveEntityTableMeta} — the old name read as an unmanaged escape hatch (#1208). */
+export declare const buildEntityTableMeta: typeof deriveEntityTableMeta;
+export declare function assertBackingTableSuperset(entityName: string, fieldMeta: EntityTableMeta, tableMeta: EntityTableMeta): void;
+/**
+ * Hand-built EntityTableMeta for direct-write stores (no entity base columns).
+ * Prefer a `store_*` table name; `read_` is reserved for managed projections (#1220).
+ *
+ * Escape hatch, not a shortcut: no audit trail, no automatic tenant_id index,
+ * no softDelete — the app author owns tenant-scoping and retention for this
+ * table. Justify WHY in the call site; reviewers should scrutinize every new
+ * unmanaged table.
+ */
+export declare function defineUnmanagedTable<const T extends EntityTenancy = "tenant">(input: UnmanagedTableInput & {
+    readonly tenancy?: T;
+}): EntityTableMeta & TenancyBrand<T>;