@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

package/src/db/__tests__/tenant-db-global.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+import type { EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
 import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import { createEntity, createTextField } from "../../engine";
 import { AccessDeniedError } from "../../errors";
@@ -69,6 +70,19 @@ const explicitGlobalLiteralTable = buildEntityTable("globalGuardExplicitGlobal",
 
 const own = testTenantId(1);
 
+function recordingReporter(): {
+  readonly report: EscapeHatchReporter;
+  readonly calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }>;
+} {
+  const calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }> = [];
+  return {
+    report: (kind, reason, target) => {
+      calls.push({ kind, reason, target });
+    },
+    calls,
+  };
+}
+
 // Type-only assertions — never invoked, checked by `tsc --build` only.
 function typeAssertions(tdb: TenantDb): void {
   // @ts-expect-error db.global() on a "tenant"-tenancy table (default tenancy) is a type error.
@@ -157,6 +171,41 @@ describe("TenantDb.global()", () => {
     expect(captured).toHaveLength(1);
   });
 
+  test("write with an escapeHatch reports global-write once with the grant's reason", async () => {
+    const db: DbRunner = {
+      unsafe: async () => [{ id: "x" }],
+      begin: async () => {
+        throw new Error("begin not used in this test");
+      },
+    } as DbRunner;
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(db, own, "tenant", undefined, undefined, undefined, {
+      globalWrites: { reason: "cross-tenant backfill job" },
+      report,
+    });
+    await tdb.global(globalUnmanagedTable).insertOne({ name: "x" });
+    expect(calls).toEqual([
+      { kind: "global-write", reason: "cross-tenant backfill job", target: undefined },
+    ]);
+  });
+
+  test("denied global write (no grant) reports nothing", async () => {
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        report,
+      },
+    );
+    await expect(tdb.global(globalUnmanagedTable).insertOne({ name: "x" })).rejects.toThrow();
+    expect(calls).toEqual([]);
+  });
+
   test("write with an explicit non-SYSTEM tenantId rejects even with a valid escapeHatch", async () => {
     const tdb = createTenantDb(
       unreachableRunner(),
@@ -214,6 +263,41 @@ describe("TenantDb.unsafeRaw()", () => {
     });
     expect(tdb.unsafeRaw("some reason")).toBe(rawDb);
   });
+
+  test("with a valid grant reports unsafe-raw once with the reason", () => {
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        unsafeRaw: { reason: "granted" },
+        report,
+      },
+    );
+    tdb.unsafeRaw("cleanup read");
+    expect(calls).toEqual([{ kind: "unsafe-raw", reason: "cleanup read", target: undefined }]);
+  });
+
+  test("without a grant reports nothing", () => {
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        report,
+      },
+    );
+    expect(() => tdb.unsafeRaw("some reason")).toThrow(AccessDeniedError);
+    expect(calls).toEqual([]);
+  });
 });
 
 describe("withUnsafeRawGrant", () => {
@@ -257,4 +341,12 @@ describe("UncheckedSystemDb.unsafeRaw", () => {
     const sysDb = createUncheckedSystemDb(tdb);
     expect(sysDb.unsafeRaw("cleanup job")).toBe(rawDb);
   });
+
+  test("reports unsafe-raw once with the reason", () => {
+    const tdb = createTenantDb(unreachableRunner(), own);
+    const { report, calls } = recordingReporter();
+    const sysDb = createUncheckedSystemDb(tdb, undefined, report);
+    sysDb.unsafeRaw("cleanup job");
+    expect(calls).toEqual([{ kind: "unsafe-raw", reason: "cleanup job", target: undefined }]);
+  });
 });

package/src/db/__tests__/tenant-db-no-raw.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { InternalError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import { createTenantDb, createUncheckedSystemDb, withUnsafeRawGrant } from "../tenant-db";
+import { tenantDbRunner } from "../tenant-db-runner";
+
+// TenantDb.raw is gone from the type; framework-internal callers resolve
+// the bound DbRunner through tenant-db-runner.ts's WeakMap instead.
+
+const tenantId = testTenantId(1);
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => [],
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("TenantDb has no .raw", () => {
+  test("compile-time: .raw is not a property of TenantDb", () => {
+    const tdb = createTenantDb(fakeRunner(), tenantId);
+    // @ts-expect-error TenantDb no longer exposes `raw`.
+    expect(tdb.raw).toBeUndefined();
+  });
+});
+
+describe("tenantDbRunner", () => {
+  test("returns the runner bound at createTenantDb() (identity)", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId);
+    expect(tenantDbRunner(tdb)).toBe(runner);
+  });
+
+  test("withUnsafeRawGrant rebinds also resolve to the original runner", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId);
+    const regranted = withUnsafeRawGrant(tdb, { reason: "test grant" });
+    expect(regranted).not.toBe(tdb);
+    expect(tenantDbRunner(regranted)).toBe(runner);
+  });
+
+  test("throws InternalError for a hand-built object not built by createTenantDb", () => {
+    const handBuilt = { tenantId, mode: "tenant" } as unknown as TenantDb;
+    expect(() => tenantDbRunner(handBuilt)).toThrow(InternalError);
+  });
+
+  test("throws InternalError for a throwing guard Proxy, without the proxy's get trap firing", () => {
+    let getTrapFired = false;
+    const guardProxy = new Proxy(
+      {},
+      {
+        get() {
+          getTrapFired = true;
+          throw new Error("systemScope guard: property access denied");
+        },
+      },
+    ) as unknown as TenantDb;
+
+    expect(() => tenantDbRunner(guardProxy)).toThrow(InternalError);
+    expect(getTrapFired).toBe(false);
+  });
+});
+
+describe("createUncheckedSystemDb(...).unsafeRaw", () => {
+  test("resolves to the runner bound at createTenantDb()", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    expect(systemDb.unsafeRaw("test reason")).toBe(runner);
+  });
+});

package/src/db/__tests__/tenant-db.integration.test.ts

@@ -110,7 +110,9 @@ describe("scoped mode (default)", () => {
 
       await tdb.insertOne(table, { name: "ColSelect" });
 
-      const rows = await asRawClient(tdb).unsafe<Record<string, unknown>>(
+      // This probes a custom column projection, not tenant-scoping, so it goes
+      // straight at the underlying runner tdb was built from.
+      const rows = await asRawClient(testDb.db).unsafe<Record<string, unknown>>(
         `SELECT id, name FROM "tenant_db_items" WHERE name = $1 LIMIT 10`,
         ["ColSelect"],
       );

package/src/db/__tests__/unchecked-system-db.test.ts

@@ -1,9 +1,23 @@
 import { describe, expect, test } from "bun:test";
+import type { EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
 import { SYSTEM_TENANT_ID } from "../../engine";
 import { testTenantId } from "../../stack";
 import type { DbRunner } from "../connection";
 import { createTenantDb, createUncheckedSystemDb, SYSTEM_SCOPE_CHECK_BRAND } from "../tenant-db";
 
+function recordingReporter(): {
+  readonly report: EscapeHatchReporter;
+  readonly calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }>;
+} {
+  const calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }> = [];
+  return {
+    report: (kind, reason, target) => {
+      calls.push({ kind, reason, target });
+    },
+    calls,
+  };
+}
+
 // createUncheckedSystemDb wraps a "system"-mode TenantDb (r.systemScope())
 // so a handler must explicitly clear a self-check before using it — none of
 // these checks execute a query, so a runner that always throws is enough to
@@ -44,6 +58,16 @@ describe("createUncheckedSystemDb", () => {
 
       expect(() => unchecked.assertTenantMatch(foreign)).toThrow(/tenant self-check failed/);
     });
+
+    test("does not report — it is a tenant-safe check", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+
+      unchecked.assertTenantMatch(own);
+      expect(() => unchecked.assertTenantMatch(foreign)).toThrow();
+      expect(calls).toEqual([]);
+    });
   });
 
   describe("assertRowsTenant", () => {
@@ -88,6 +112,16 @@ describe("createUncheckedSystemDb", () => {
 
       expect(unchecked.assertRowsTenant(rows, "tenantId")).toBe(rows);
     });
+
+    test("does not report — it is a tenant-safe check", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+      const rows = [{ tenantId: own, name: "a" }];
+
+      unchecked.assertRowsTenant(rows, "tenantId");
+      expect(calls).toEqual([]);
+    });
   });
 
   describe("acknowledgeCrossTenant", () => {
@@ -113,6 +147,30 @@ describe("createUncheckedSystemDb", () => {
 
       expect(() => unchecked.acknowledgeCrossTenant("   ")).toThrow(/non-empty reason/);
     });
+
+    test("reports acknowledge-cross-tenant once with the reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+
+      unchecked.acknowledgeCrossTenant("user feature is cross-tenant by design");
+      expect(calls).toEqual([
+        {
+          kind: "acknowledge-cross-tenant",
+          reason: "user feature is cross-tenant by design",
+          target: undefined,
+        },
+      ]);
+    });
+
+    test("an empty reason throws and does not report", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+
+      expect(() => unchecked.acknowledgeCrossTenant("")).toThrow();
+      expect(calls).toEqual([]);
+    });
   });
 
   describe("outsideTransaction", () => {
@@ -178,6 +236,24 @@ describe("createUncheckedSystemDb", () => {
           /no outside-transaction database source is configured/,
         );
       });
+
+      test("reports acknowledge-cross-tenant once with the reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const { report, calls } = recordingReporter();
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb, report);
+
+        unchecked.outsideTransaction.acknowledgeCrossTenant(
+          "durability write is cross-tenant by design",
+        );
+        expect(calls).toEqual([
+          {
+            kind: "acknowledge-cross-tenant",
+            reason: "durability write is cross-tenant by design",
+            target: undefined,
+          },
+        ]);
+      });
     });
   });
 });

package/src/db/apply-entity-event.ts

@@ -89,7 +89,7 @@ export async function applyEntityEvent(
   switch (verb) {
     case "created": {
       // tenantId-Resolution explizit, nicht via Spread-Reihenfolge:
-      // Live-Pfad nutzt tx=db.raw (kein TenantDb-Wrapper-Auto-Inject),
+      // Live-Pfad nutzt tx=tenantDbRunner(db) (kein TenantDb-Wrapper-Auto-Inject),
       // beim Replay erst recht keiner. Default = event.tenantId; payload
       // gewinnt NUR wenn gültig string mit length > 0 (seedTenantMembership-
       // Pfad: Operator schreibt im Ziel-Tenant, Event im Operator-Tenant).

package/src/db/assert-exists-in.ts

@@ -5,7 +5,7 @@ import type { DbConnection } from "./connection";
 import type { TenantDb } from "./tenant-db";
 
 function isTenantDb(db: DbConnection | TenantDb): db is TenantDb {
-  return typeof (db as TenantDb).fetchOne === "function" && "raw" in db;
+  return "tenantId" in db && "fetchOne" in db && typeof db.fetchOne === "function";
 }
 
 /**

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

@@ -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";
 import type { EntityDefinition, TenantId } from "../engine/types";
 import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher";
@@ -19,6 +20,23 @@ export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySe
   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 {

package/src/db/event-store-executor-context.ts

@@ -38,6 +38,7 @@ import type { EventStoreExecutorOptions } from "./event-store-executor";
 import { constraintOf, isUniqueViolation } from "./pg-error";
 import { toSnakeCase } from "./table-builder";
 import type { TenantDb } from "./tenant-db";
+import { tenantDbRunner } from "./tenant-db-runner";
 
 // Shared context-building for the event-store-executor CRUD verbs (create/
 // update/delete/forget/restore/list/detail — see event-store-executor-write.ts
@@ -50,11 +51,11 @@ export type Table = TableColumns<any>;
 
 // Screen-Filter (Tier 2.7c) — Op-Mapping als Where-Operator. Boot-
 // Validator pinst field-Existenz + filterable + op-vs-Type-Compat.
-// `op` ist auf {eq,ne,lt,gt,in} normalisiert; "in" mit empty-array ist
-// explizit no-match.
+// `op` ist auf {eq,ne,lt,gt,lte,gte,in} normalisiert; "in" mit
+// empty-array ist explizit no-match.
 export function buildFilterWhere(
   field: string,
-  op: "eq" | "ne" | "lt" | "gt" | "in",
+  op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in",
   value: unknown,
 ): WhereObject | null {
   switch (op) {
@@ -66,6 +67,10 @@ export function buildFilterWhere(
       return { [field]: { lt: value } };
     case "gt":
       return { [field]: { gt: value } };
+    case "lte":
+      return { [field]: { lte: value } };
+    case "gte":
+      return { [field]: { gte: value } };
     case "in":
       if (Array.isArray(value) && value.length > 0) {
         return { [field]: value };
@@ -358,7 +363,7 @@ export function buildExecutorContext(
     id: EntityId,
     tenantId: TenantId,
   ): Promise<void> {
-    if (await isStreamArchived(db.raw, tenantId, String(id))) {
+    if (await isStreamArchived(tenantDbRunner(db), tenantId, String(id))) {
       throw new ArchivedStreamError(tenantId, String(id));
     }
   }
@@ -401,7 +406,9 @@ export function buildExecutorContext(
     whereParts.push(shifted.sqlText);
     for (const p of shifted.params) params.push(p);
     const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
-    return [...(await executeRawQueryRead<Record<string, unknown>>(db.raw, sqlText, params))];
+    return [
+      ...(await executeRawQueryRead<Record<string, unknown>>(tenantDbRunner(db), sqlText, params)),
+    ];
   }
 
   return {