@cosmicdrift/kumiko-framework 0.354.0 → 0.355.0

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

@@ -1,4 +1,5 @@
 import type { EntityDefinition } from "../engine/types/index.js";
+import { type Logger } from "../logging/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;
@@ -6,7 +7,15 @@ export declare function hasSearchablePlaintext(entity: EntityDefinition, field:
 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 logUndecryptableField(info: {
+    entityName: string | undefined;
+    rowId: unknown;
+    field: string;
+    error: unknown;
+}, logger?: Logger): void;
+export declare function decryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher, opts?: {
+    onFieldError?: (field: string, error: unknown) => void;
+}): Promise<Record<string, unknown>>;
 export declare function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void;
 export declare function resolveEntityFieldEncryption(): EnvelopeCipher;
 export declare function configuredEntityFieldEncryption(): EnvelopeCipher | undefined;

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

@@ -4,6 +4,7 @@
 // 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 { createLogger } from "../logging/index.js";
 import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider.js";
 export function collectEncryptedFieldNames(entity) {
     const names = new Set();
@@ -60,7 +61,25 @@ export async function encryptEntityFieldValues(row, encryptedFields, cipher, opt
     }
     return out;
 }
-export async function decryptEntityFieldValues(row, encryptedFields, cipher) {
+let undecryptableFieldLogger;
+function defaultUndecryptableFieldLogger() {
+    undecryptableFieldLogger ??= createLogger();
+    return undecryptableFieldLogger;
+}
+// Logs identifiers and the error class only: ciphertext, key material and the
+// cipher's error message (which may echo envelope content) never reach the log.
+export function logUndecryptableField(info, logger = defaultUndecryptableFieldLogger()) {
+    logger.error("encrypted field could not be decrypted; returned as null", {
+        entity: info.entityName,
+        rowId: info.rowId,
+        field: info.field,
+        errorName: info.error instanceof Error ? info.error.name : typeof info.error,
+    });
+}
+// With `onFieldError` a field that fails to decrypt (wrong key, corrupt
+// envelope) reads as null and is reported instead of throwing, so one bad row
+// cannot fail a whole list. Without it decrypt stays fail-loud (write paths).
+export async function decryptEntityFieldValues(row, encryptedFields, cipher, opts) {
     if (encryptedFields.size === 0)
         return row;
     const out = { ...row };
@@ -71,7 +90,17 @@ export async function decryptEntityFieldValues(row, encryptedFields, cipher) {
             continue;
         if (typeof value !== "string")
             continue;
-        out[name] = await cipher.decrypt(value, scope);
+        if (!opts?.onFieldError) {
+            out[name] = await cipher.decrypt(value, scope);
+            continue;
+        }
+        try {
+            out[name] = await cipher.decrypt(value, scope);
+        }
+        catch (error) {
+            out[name] = null;
+            opts.onFieldError(name, error);
+        }
     }
     return out;
 }

package/dist/db/event-store-executor-context.d.ts

@@ -9,11 +9,15 @@ import type { EventStoreExecutorOptions } from "./event-store-executor.js";
 import type { TenantDb } from "./tenant-db.js";
 export type Table = TableColumns<any>;
 export declare function buildFilterWhere(field: string, op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in", value: unknown): WhereObject | null;
+export declare function ownershipSubject(user: SessionUser, streamTenantId: TenantId | undefined): SessionUser;
 export declare function isForeignTenantOnGlobalEntity(entity: EntityDefinition, tenantIdValue: unknown): boolean;
 export declare function tryMapUniqueViolation(e: unknown, entityName: string): WriteFailure | null;
 export declare function buildEventMetadata(user: SessionUser): EventMetadata;
 export type EntityLifecycleVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
 export declare function entityEventName(entityName: string, verb: EntityLifecycleVerb): string;
+export type DecryptForReadOptions = {
+    readonly degradeUndecryptable?: (field: string) => void;
+};
 export type ExecutorContext = {
     readonly table: Table;
     readonly entity: EntityDefinition;
@@ -21,7 +25,8 @@ export type ExecutorContext = {
     readonly entityCache?: EntityCache;
     readonly searchAdapter?: SearchAdapter;
     readonly softDelete: boolean;
-    readonly streamTenantFor: (user: SessionUser) => TenantId;
+    readonly streamTenantFor: (user: SessionUser, requestedStreamTenantId?: TenantId) => TenantId;
+    readonly streamTenantOverrideFailure: (db: TenantDb, row: Record<string, unknown>, requestedStreamTenantId: TenantId | undefined) => WriteFailure | undefined;
     readonly idFilter: (id: EntityId) => WhereObject;
     readonly loadById: (id: EntityId, db: TenantDb) => Promise<Record<string, unknown> | null>;
     readonly assertStreamWritable: (db: TenantDb, id: EntityId, tenantId: TenantId) => Promise<void>;
@@ -53,8 +58,9 @@ export type ExecutorContext = {
     readonly encryptForStorage: (row: Record<string, unknown>, user: SessionUser, opts?: {
         onlyKeys?: Iterable<string>;
         subjectSource?: Record<string, unknown>;
+        keyTenantId?: TenantId | undefined;
     }) => Promise<Record<string, unknown>>;
-    readonly decryptForRead: (row: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    readonly decryptForRead: (row: Record<string, unknown>, opts?: DecryptForReadOptions) => Promise<Record<string, unknown>>;
     readonly applyDefaults: (payload: Record<string, unknown>) => Record<string, unknown>;
     readonly stripSensitive: (payload: Record<string, unknown> | undefined) => Record<string, unknown>;
 };

package/dist/db/event-store-executor-context.js

@@ -4,11 +4,11 @@ import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { shiftParams } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
-import { InternalError, subjectErasedConflict, UniqueViolationError, writeFailure, } from "../errors/index.js";
+import { AccessDeniedError, InternalError, subjectErasedConflict, UniqueViolationError, writeFailure, } from "../errors/index.js";
 import { ArchivedStreamError, isStreamArchived } from "../event-store/index.js";
 import { assertUnreachable } from "../utils/index.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
-import { collectEncryptedFieldNames, decryptEntityFieldValues, encryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
+import { collectEncryptedFieldNames, decryptEntityFieldValues, encryptEntityFieldValues, logUndecryptableField, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
 import { constraintOf, isUniqueViolation } from "./pg-error.js";
 import { toSnakeCase } from "./table-builder.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
@@ -39,6 +39,13 @@ export function buildFilterWhere(field, op, value) {
             return assertUnreachable(op, "filter op");
     }
 }
+// Tenant-based write-ownership rules (from("user:tenantId", "tenantId")) compare the caller's
+// tenant with the row's. An explicit cross-tenant grant (streamTenantId, checked against the
+// loaded row) is evaluated as the operator acting inside the target tenant. Only this
+// evaluation sees the target tenant: stream actor, metadata and PII keys keep the real identity.
+export function ownershipSubject(user, streamTenantId) {
+    return streamTenantId === undefined ? user : { ...user, tenantId: streamTenantId };
+}
 // Returns the scalar default of a field, or undefined if the field's type
 // doesn't carry a default or no default was declared. Only scalar types
 // (text/number/boolean/select) support creation-time defaults — money/date/
@@ -110,7 +117,24 @@ export function buildExecutorContext(table, entity, options) {
     // user) lives on SYSTEM_TENANT_ID deterministically — every op addresses it
     // there. Everything else stays on the caller's tenant (byte-identical to the
     // old hardcoded user.tenantId). Single source of truth for the stream key.
-    const streamTenantFor = (user) => entity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
+    const streamTenantFor = (user, requestedStreamTenantId) => entity.systemStream ? SYSTEM_TENANT_ID : (requestedStreamTenantId ?? user.tenantId);
+    // Only a system-mode db (r.systemScope() / acknowledged cross-tenant) may address another
+    // tenant's stream, and only the tenant of the row it just loaded.
+    const streamTenantOverrideFailure = (db, row, requestedStreamTenantId) => {
+        if (requestedStreamTenantId === undefined)
+            return undefined;
+        if (db.mode !== "system") {
+            return writeFailure(new AccessDeniedError({
+                message: `${entityName}: streamTenantId requires a system-mode db`,
+            }));
+        }
+        if (row["tenantId"] !== requestedStreamTenantId) {
+            return writeFailure(new AccessDeniedError({
+                message: `${entityName}: streamTenantId does not match the tenant of the addressed row`,
+            }));
+        }
+        return undefined;
+    };
     // idType default (undefined) is now "uuid" — the ES-pivot made UUID the
     // only valid aggregate-id type. Explicit `idType: "serial"` is the only
     // shape that's incompatible with the event-store and still rejected.
@@ -156,10 +180,10 @@ export function buildExecutorContext(table, entity, options) {
     function piiKms() {
         return options.kms ?? configuredPiiSubjectKms();
     }
-    function kmsContextFor(user) {
+    function kmsContextFor(user, keyTenantId) {
         return {
             requestId: requestContext.get()?.requestId ?? "event-store-executor",
-            ...(user && { tenantId: user.tenantId, userId: String(user.id) }),
+            ...(user && { tenantId: keyTenantId ?? user.tenantId, userId: String(user.id) }),
         };
     }
     // Async on purpose: the envelope cipher wraps/unwraps DEKs via the
@@ -176,8 +200,8 @@ export function buildExecutorContext(table, entity, options) {
         const kms = piiKms();
         if (hasPiiFields && kms) {
             try {
-                out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user), {
-                    tenantId: user.tenantId,
+                out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user, opts?.keyTenantId), {
+                    tenantId: opts?.keyTenantId ?? user.tenantId,
                     entityName,
                     ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
                     ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
@@ -198,14 +222,21 @@ export function buildExecutorContext(table, entity, options) {
     // unwrap before envelope decrypt, or the envelope cipher chokes on a
     // still-PII-wrapped string (auth-mfa.totpSecret/recoveryCodes combine both
     // markers; see pii-subject-encryption.integration.test.ts).
-    async function decryptForRead(row) {
+    async function decryptForRead(row, opts) {
         let out = row;
         const kms = piiKms();
         if (hasPiiFields && kms) {
             out = await decryptPiiFieldValues(out, piiSubjectFields, kms, kmsContextFor());
         }
         if (hasEncryptedFields) {
-            out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher());
+            out = await decryptEntityFieldValues(out, encryptedFields, fieldCipher(), opts?.degradeUndecryptable
+                ? {
+                    onFieldError: (field, error) => {
+                        logUndecryptableField({ entityName, rowId: row["id"], field, error });
+                        opts.degradeUndecryptable?.(field);
+                    },
+                }
+                : undefined);
         }
         return out;
     }
@@ -384,6 +415,7 @@ export function buildExecutorContext(table, entity, options) {
         searchAdapter,
         softDelete,
         streamTenantFor,
+        streamTenantOverrideFailure,
         idFilter,
         loadById,
         assertStreamWritable,

package/dist/db/event-store-executor-read.js

@@ -6,7 +6,7 @@ import { coerceRow, extractTableInfo } from "../db/query.js";
 import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { UnprocessableError } from "../errors/index.js";
-import { getStreamVersion } from "../event-store/index.js";
+import { getStreamVersion, getStreamVersions } from "../event-store/index.js";
 import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
@@ -64,6 +64,9 @@ function toCursorSortText(value) {
     }
     return undefined;
 }
+function withStreamVersion(row, streamVersion) {
+    return streamVersion > 0 ? { ...row, version: streamVersion } : row;
+}
 // Keyset boundary for `ORDER BY <sort> <dir>, id ASC` under Postgres' DEFAULT
 // null ordering (ASC → NULLS LAST, DESC → NULLS FIRST). An explicit NULLS clause
 // would change the visible order and cost the sort its index.
@@ -661,11 +664,17 @@ export function createReadVerbs(ctx) {
             // field (ciphertext leaked to the caller).
             const tableInfo = extractTableInfo(table);
             const encryptedRows = rawRows.map((r) => rehydrateCompoundTypes(coerceRow(r, tableInfo), entity));
-            const rows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
-            // list rows carry the READ-ROW version (display-only), never an optimistic-lock
-            // base — edit flows reload via detail(), which reconciles the stream version.
-            // Cache the still-encrypted form: same at-rest guarantee as detail()'s
-            // encryptForStorage round-trip, without paying a re-encrypt.
+            const decryptedRows = await Promise.all(encryptedRows.map((r) => decryptForRead(r, { degradeUndecryptable: () => { } })));
+            // Stream version is authoritative (see detail()): ctx.appendEvent bumps the
+            // stream without touching row.version, so the raw row version would hand
+            // clients a stale optimistic-lock base. Rows without events keep theirs.
+            const streamVersions = decryptedRows.length > 0
+                ? await getStreamVersions(runner, decryptedRows.map((r) => String(r["id"])), streamTenantFor(user))
+                : new Map();
+            const rows = decryptedRows.map((r) => withStreamVersion(r, streamVersions.get(String(r["id"])) ?? 0));
+            // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
+            // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
+            // a cached version that differs from the stream.
             if (entityCache && entityName && rows.length > 0) {
                 await entityCache.mset(user.tenantId, entityName, encryptedRows.map((r) => ({ id: r["id"], data: r })));
             }
@@ -718,7 +727,6 @@ export function createReadVerbs(ctx) {
             // guaranteed version_conflict.
             // A cache hit only counts when its version equals the live stream version:
             // a late entityCache.set() can resurrect an old row after the writer's del().
-            const withVersion = (row, streamVersion) => (streamVersion > 0 ? { ...row, version: streamVersion } : row);
             if (entityCache && entityName) {
                 const cached = await entityCache.get(user.tenantId, entityName, payload.id);
                 if (cached) {
@@ -736,7 +744,7 @@ export function createReadVerbs(ctx) {
                         // Cached rows are stored re-encrypted (see the `set` below) so an
                         // `encrypted` field's plaintext never sits in a second at-rest
                         // store (Redis) the field-encryption feature doesn't cover.
-                        return withVersion(await decryptForRead(cached), streamVersion);
+                        return withStreamVersion(await decryptForRead(cached, { degradeUndecryptable: () => { } }), streamVersion);
                     }
                 }
             }
@@ -747,9 +755,12 @@ export function createReadVerbs(ctx) {
             // Same coerce-before-rehydrate/decrypt ordering as list() above — raw
             // is snake_case (raw SQL); coerceRow maps it to camelCase.
             const rowInfo = extractTableInfo(table);
-            const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity));
-            const result = withVersion(coerced, snapshot.streamVersion);
-            if (entityCache && entityName) {
+            const undecryptableFields = [];
+            const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity), { degradeUndecryptable: (field) => undecryptableFields.push(field) });
+            const result = withStreamVersion(coerced, snapshot.streamVersion);
+            // A degraded row must not be cached: re-encrypting its null would
+            // replay the missing value on later cache hits without any error log.
+            if (entityCache && entityName && undecryptableFields.length === 0) {
                 await entityCache.set(user.tenantId, entityName, payload.id, await encryptForStorage(result, user));
             }
             return result;