@cosmicdrift/kumiko-framework 0.288.0 → 0.289.0

package/src/crypto/kms-wiring.ts

@@ -8,6 +8,7 @@
 // is wrong), `resolveKmsWiring` is the boot entry point that also constructs
 // the adapter.
 
+import { type KekSourceOptions, resolvePlatformKeks } from "./kek-source";
 import { createPgKmsAdapter, type PgKmsAdapter, type PgKmsAdapterOptions } from "./pg-kms-adapter";
 
 // The index signature is what lets callers pass `process.env` directly. Without
@@ -186,3 +187,22 @@ export function requireKmsWiring(
   }
   return wiring;
 }
+
+/** Same as `resolveKmsWiring`, but resolves `PLATFORM_KEK`/`PLATFORM_KEK_PREVIOUS`
+ *  from a Key Manager ciphertext first when no plaintext is set — see
+ *  `resolvePlatformKeks`. The validation stays in the sync function; this only
+ *  adds the KEK-fetching step in front of it. */
+export async function resolveKmsWiringAsync(
+  env: KmsWiringEnv,
+  options: KmsWiringOptions & KekSourceOptions = {},
+): Promise<KmsWiring> {
+  return resolveKmsWiring(await resolvePlatformKeks(env, options), options);
+}
+
+/** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
+export async function requireKmsWiringAsync(
+  env: KmsWiringEnv,
+  options: KmsWiringOptions & KekSourceOptions = {},
+): Promise<ActiveKmsWiring> {
+  return requireKmsWiring(await resolvePlatformKeks(env, options), options);
+}

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -385,6 +385,197 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 });
 
+// =============================================================================
+// expect precondition (kumiko-framework#3024) — declarative "genau einmal"
+// guard on update(). The version_conflict describe above proves the pre-
+// existing stream-version race protection; these prove `expect:` closes the
+// gap that leaves open: a caller (like updateUserLifecycle) that opts out of
+// the optimistic lock entirely, so a "late" writer whose own version read is
+// fresh never trips version_conflict at all.
+// =============================================================================
+
+const expectEntity = createEntity({
+  table: "read_es_write_expect",
+  fields: {
+    email: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    status: createTextField({ personal: false, reason: "test_fixture" }),
+    note: createTextField({ personal: false, reason: "test_fixture" }),
+  },
+});
+const expectTable = buildEntityTable("esWriteExpect", expectEntity);
+
+describe("event-store-executor write-verbs — expect precondition (#3024)", () => {
+  const crud = createEventStoreExecutor(expectTable, expectEntity, {
+    entityName: "esWriteExpect",
+  });
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTable(testDb.db, expectEntity, "esWriteExpect");
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_write_expect RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("expect matching the fresh row → applies", async () => {
+    const created = await crud.create({ email: "match@test.de", status: "Active" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.update(
+      { id: created.data.id, changes: { status: "Requested" } },
+      admin,
+      tdb,
+      { skipOptimisticLock: true, expect: { status: "Active" } },
+    );
+    expect(result.isSuccess).toBe(true);
+  });
+
+  test("expect not matching the fresh row → precondition_failed, row unchanged", async () => {
+    const created = await crud.create({ email: "stale@test.de", status: "Requested" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.update(
+      { id: created.data.id, changes: { status: "Deleted" } },
+      admin,
+      tdb,
+      { skipOptimisticLock: true, expect: { status: "Active" } },
+    );
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect(result.error.code).toBe("precondition_failed");
+
+    const row = await asRawClient(testDb.db).unsafe(
+      `SELECT status FROM read_es_write_expect WHERE id = $1`,
+      [created.data.id],
+    );
+    expect((row as unknown as { status: string }[])[0]?.status).toBe("Requested");
+  });
+
+  test("multiple expect fields, one mismatches → precondition_failed", async () => {
+    const created = await crud.create(
+      { email: "multi@test.de", status: "Active", note: "kept" },
+      admin,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const result = await crud.update(
+      { id: created.data.id, changes: { status: "Requested" } },
+      admin,
+      tdb,
+      { skipOptimisticLock: true, expect: { status: "Active", note: "different" } },
+    );
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess) return;
+    expect(result.error.code).toBe("precondition_failed");
+  });
+
+  test("expect: null matches a null field, rejects a non-null one", async () => {
+    const withNullNote = await crud.create({ email: "null-note@test.de" }, admin, tdb);
+    if (!withNullNote.isSuccess) throw new Error("setup failed");
+    const matched = await crud.update(
+      { id: withNullNote.data.id, changes: { note: "now set" } },
+      admin,
+      tdb,
+      { skipOptimisticLock: true, expect: { note: null } },
+    );
+    expect(matched.isSuccess).toBe(true);
+
+    const withNote = await crud.create(
+      { email: "present-note@test.de", note: "present" },
+      admin,
+      tdb,
+    );
+    if (!withNote.isSuccess) throw new Error("setup failed");
+    const rejected = await crud.update(
+      { id: withNote.data.id, changes: { note: "overwritten" } },
+      admin,
+      tdb,
+      { skipOptimisticLock: true, expect: { note: null } },
+    );
+    expect(rejected.isSuccess).toBe(false);
+  });
+
+  // The scenario version_conflict alone can't catch: both callers skip the
+  // optimistic lock (updateUserLifecycle's shape), so the second caller's own
+  // stream-version read is fresh and never collides — only the fresh expect
+  // re-read at write time sees that the first caller already moved the row on.
+  test("late writer: expect catches a precondition an earlier write already violated, with no version race", async () => {
+    const created = await crud.create({ email: "late@test.de", status: "Active" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+    const id = created.data.id;
+
+    const first = await crud.update({ id, changes: { status: "Requested" } }, admin, tdb, {
+      skipOptimisticLock: true,
+      expect: { status: "Active" },
+    });
+    expect(first.isSuccess).toBe(true);
+
+    const second = await crud.update({ id, changes: { status: "Requested" } }, admin, tdb, {
+      skipOptimisticLock: true,
+      expect: { status: "Active" },
+    });
+    expect(second.isSuccess).toBe(false);
+    if (second.isSuccess) return;
+    expect(second.error.code).toBe("precondition_failed");
+  });
+
+  // Wrapped in its own transaction per racer, like "two concurrent first-time
+  // creates ... inside a transaction" above — this is how the dispatcher
+  // always calls update() in production (the whole handler runs in one
+  // transaction), and it matters here: without it, a single writer's own
+  // event-append and projection-update commit as two SEPARATE, independently
+  // visible statements against the bare pool, so a second reader can
+  // observe "event committed, projection not yet" — a torn state that
+  // doesn't exist once both writes commit together as one transaction. The
+  // HTTP-level equivalent (anonymous-deletion.integration.test.ts, real
+  // dispatcher, real transaction) already covers the true production
+  // guarantee; this test pins the same guarantee at the executor level with
+  // an explicit transaction to match.
+  test("two concurrent updates with the same expect, both skipOptimisticLock → exactly one applies", async () => {
+    const created = await crud.create(
+      { email: "race-expect@test.de", status: "Active" },
+      admin,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("setup failed");
+    const id = created.data.id;
+    const options = { skipOptimisticLock: true, expect: { status: "Active" } } as const;
+
+    const [a, b] = await Promise.all([
+      transaction(testDb.db, (tx) =>
+        crud.update(
+          { id, changes: { status: "Requested" } },
+          admin,
+          createTenantDb(tx, admin.tenantId),
+          options,
+        ),
+      ),
+      transaction(testDb.db, (tx) =>
+        crud.update(
+          { id, changes: { status: "Requested" } },
+          admin,
+          createTenantDb(tx, admin.tenantId),
+          options,
+        ),
+      ),
+    ]);
+
+    const results = [a, b];
+    expect(results.filter((r) => r.isSuccess)).toHaveLength(1);
+    const loser = results.find((r) => !r.isSuccess);
+    if (!loser || loser.isSuccess) throw new Error("expected exactly one loser");
+    expect(["precondition_failed", "version_conflict"]).toContain(loser.error.code);
+
+    const healthCheck = (await asRawClient(testDb.db).unsafe(`SELECT 1 AS ok`)) as Array<{
+      ok: number;
+    }>;
+    expect(healthCheck[0]?.ok).toBe(1);
+  });
+});
+
 // =============================================================================
 // Explicit-id create: cross-tenant isolation, no resurrection of a deleted row
 // =============================================================================

package/src/db/__tests__/tenant-db-declared-unsafe-raw.test.ts

@@ -1,10 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import type { EscapeHatchKind } from "@cosmicdrift/kumiko-types/handlers";
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
-import { AccessDeniedError, InternalError } from "../../errors";
+import { AccessDeniedError, FrameworkReasons, InternalError } from "../../errors";
 import { testTenantId } from "../../stack";
 import type { DbRunner } from "../connection";
 import {
+  acknowledgeConventionCrossTenant,
   createTenantDb,
   createUncheckedSystemDb,
   unsafeRawForDeclaredStep,
@@ -102,3 +103,61 @@ describe("unsafeRawForDeclaredStep", () => {
     expect(unsafeRawForDeclaredStep(regranted, REASON)).toBe(runner);
   });
 });
+
+describe("memberReadOnly grant", () => {
+  function memberReadOnlyDb(report?: (kind: EscapeHatchKind, reason: string) => void): TenantDb {
+    return createTenantDb(fakeRunner(), tenantId, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "handler declared unsafeRaw" },
+      memberReadOnly: true,
+      ...(report && { report }),
+    });
+  }
+
+  function deniedReason(run: () => unknown): unknown {
+    try {
+      run();
+    } catch (e) {
+      if (!(e instanceof AccessDeniedError)) return e;
+      const details: unknown = e.details;
+      return typeof details === "object" && details !== null && "reason" in details
+        ? details.reason
+        : details;
+    }
+    return "no throw";
+  }
+
+  test("denies unsafeRaw even with a declared escapeHatch, without reporting", () => {
+    const reports: Array<{ kind: EscapeHatchKind; reason: string }> = [];
+    const tdb = memberReadOnlyDb((kind, reason) => {
+      reports.push({ kind, reason });
+    });
+
+    expect(deniedReason(() => tdb.unsafeRaw(REASON))).toBe(
+      FrameworkReasons.memberResolutionReadOnly,
+    );
+    expect(reports).toEqual([]);
+  });
+
+  test("denies the declared-step path and survives a withUnsafeRawGrant rebind", () => {
+    const tdb = memberReadOnlyDb();
+    const regranted = withUnsafeRawGrant(tdb, { reason: "hook re-grant" });
+
+    expect(deniedReason(() => unsafeRawForDeclaredStep(tdb, REASON))).toBe(
+      FrameworkReasons.memberResolutionReadOnly,
+    );
+    expect(deniedReason(() => regranted.unsafeRaw(REASON))).toBe(
+      FrameworkReasons.memberResolutionReadOnly,
+    );
+    expect(deniedReason(() => unsafeRawForDeclaredStep(regranted, REASON))).toBe(
+      FrameworkReasons.memberResolutionReadOnly,
+    );
+  });
+
+  test("survives the acknowledgeConventionCrossTenant rebind", () => {
+    const crossTenant = acknowledgeConventionCrossTenant(memberReadOnlyDb(), "test: cross-tenant");
+
+    expect(deniedReason(() => crossTenant.unsafeRaw(REASON))).toBe(
+      FrameworkReasons.memberResolutionReadOnly,
+    );
+  });
+});

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

@@ -175,6 +175,12 @@ export type ExecutorContext = {
       | { kind: "empty" }
       | { kind: "sql"; sqlText: string; params: readonly unknown[] },
   ) => Promise<Record<string, unknown>[]>;
+  readonly loadExpectSnapshot: (
+    db: TenantDb,
+    id: EntityId,
+    streamTenantId: TenantId,
+    expectKeys: readonly string[],
+  ) => Promise<{ readonly row: Record<string, unknown> | null; readonly streamVersion: number }>;
   readonly encryptForStorage: (
     row: Record<string, unknown>,
     user: SessionUser,
@@ -411,6 +417,78 @@ export function buildExecutorContext(
     ];
   }
 
+  // Combined, atomic read for the `expect:` precondition (#3024): the
+  // projection row's expect-checked fields AND the events table's current
+  // MAX(version) for this aggregate, in ONE SQL statement.
+  //
+  // Two separate reads (loadById then getStreamVersion, in either order)
+  // leave a real gap: applyEntityEvent writes the projection in a SEPARATE
+  // statement AFTER its event commits, so a second reader can see a version
+  // that already reflects a concurrent writer's event while its OWN read of
+  // the expect fields still reflects the pre-write projection row — verified
+  // empirically: ~40% of genuinely concurrent update() calls slipped a stale
+  // precondition through with two round-trips, regardless of read order. One
+  // query removes the gap: Postgres executes it against a single consistent
+  // snapshot.
+  //
+  // This also sidesteps a correctness bug the row's own `version` column
+  // can't be trusted for: applyEntityEvent only keeps row.version in
+  // lock-step with the OTHER projection columns for rows this executor
+  // itself wrote. A row seeded directly (raw INSERT — test fixtures, or
+  // legacy pre-#762 data) can carry a default version (e.g. 1) with ZERO
+  // matching events. Deriving expectedVersion from such a row.version makes
+  // the append below target a non-existent predecessor and fail outright.
+  // The events table's MAX(version) (0 for such a row) is the only value
+  // append() can safely use as expectedVersion — exactly what
+  // getStreamVersion() already returns for every other (non-`expect`)
+  // caller; this reads it in the same statement as the expect columns
+  // instead of a second round-trip.
+  //
+  // Reads raw column values — no decryptForRead pass — so `expect:` only
+  // supports plain (non-pii, non-encrypted) columns: business-state fields
+  // like status flags or foreign-key ids, not PII.
+  async function loadExpectSnapshot(
+    db: TenantDb,
+    id: EntityId,
+    streamTenantId: TenantId,
+    expectKeys: readonly string[],
+  ): Promise<{ readonly row: Record<string, unknown> | null; readonly streamVersion: number }> {
+    const quote = (name: string): string => `"${name.replace(/"/g, '""')}"`;
+    const columnOf = (field: string): string =>
+      quote((table[field] as { name?: string } | undefined)?.name ?? toSnakeCase(field));
+    const tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
+
+    const selectCols = expectKeys.map((key) => `${columnOf(key)} AS ${quote(key)}`);
+    const whereParts: string[] = [`${columnOf("id")} = $1`];
+    const params: unknown[] = [id];
+    if (table["tenantId"] !== undefined && db.mode === "tenant") {
+      params.push(db.tenantId, SYSTEM_TENANT_ID);
+      whereParts.push(`${columnOf("tenantId")} IN ($${params.length - 1}, $${params.length})`);
+    }
+    params.push(String(id), streamTenantId);
+    const streamAggregateIdx = params.length - 1;
+    const streamTenantIdx = params.length;
+
+    const sqlText =
+      `SELECT ${selectCols.join(", ")}, ` +
+      `(SELECT MAX("version") FROM "kumiko_events" WHERE "aggregate_id" = $${streamAggregateIdx} ` +
+      `AND "tenant_id" = $${streamTenantIdx}) AS "__streamVersion" ` +
+      `FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
+
+    const rows = await executeRawQueryRead<Record<string, unknown>>(
+      tenantDbRunner(db),
+      sqlText,
+      params,
+    );
+    const row = rows[0];
+    if (!row) return { row: null, streamVersion: 0 };
+    const { __streamVersion, ...fields } = row;
+    return {
+      row: fields,
+      streamVersion: typeof __streamVersion === "number" ? __streamVersion : 0,
+    };
+  }
+
   return {
     table,
     entity,
@@ -423,6 +501,7 @@ export function buildExecutorContext(
     loadById,
     assertStreamWritable,
     loadWithOwnership,
+    loadExpectSnapshot,
     encryptForStorage,
     decryptForRead,
     applyDefaults,

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

@@ -8,6 +8,7 @@ import {
   IdempotentReplayError,
   InternalError,
   NotFoundError,
+  PreconditionFailedError,
   UnprocessableError,
   writeFailure,
 } from "../errors";
@@ -114,6 +115,7 @@ export function createWriteVerbs(
     stripSensitive,
     loadById,
     assertStreamWritable,
+    loadExpectSnapshot,
   } = ctx;
 
   return {
@@ -399,11 +401,46 @@ export function createWriteVerbs(
       // aggregate); a stale row.version here would make the next CRUD write
       // trip `events_aggregate_version_uq` (tenant_id, aggregate_id, version)
       // with version_conflict.
-      const currentVersion = await getStreamVersion(
-        runner,
-        String(payload.id),
-        streamTenantFor(user),
-      );
+      //
+      // `expect:` (#3024) reads this same authoritative version, but through
+      // loadExpectSnapshot's single combined query instead of a second,
+      // separate getStreamVersion() round-trip: two reads (in either order)
+      // leave a real gap — applyEntityEvent writes the projection in a
+      // SEPARATE statement after its event commits, so a second reader's
+      // version-read can land in that gap and see a fresh, non-conflicting
+      // version paired with a still-stale projection row (verified
+      // empirically: ~40% of genuinely concurrent runs slipped through with
+      // two round-trips). One query removes the gap. It also avoids trusting
+      // the row's own `version` column for the expectedVersion: that column
+      // is only in lock-step with the rest of the row for rows THIS executor
+      // wrote — a raw-seeded row (test fixture, or legacy pre-#762 data) can
+      // carry a default version with zero matching events, which would make
+      // the append below target a non-existent predecessor and fail outright.
+      let currentVersion: number;
+      if (updateOptions?.expect) {
+        const expectKeys = Object.keys(updateOptions.expect);
+        const snapshot = await loadExpectSnapshot(
+          db,
+          payload.id,
+          streamTenantFor(user),
+          expectKeys,
+        );
+        if (!snapshot.row) {
+          return writeFailure(new PreconditionFailedError({ entityId: payload.id, field: "id" }));
+        }
+        const mismatch = Object.entries(updateOptions.expect).find(
+          ([key, expected]) => snapshot.row?.[key] !== expected,
+        );
+        if (mismatch) {
+          return writeFailure(
+            new PreconditionFailedError({ entityId: payload.id, field: mismatch[0] }),
+          );
+        }
+        currentVersion = snapshot.streamVersion;
+      } else {
+        currentVersion = await getStreamVersion(runner, String(payload.id), streamTenantFor(user));
+      }
+
       if (!updateOptions?.skipOptimisticLock) {
         if (payload.version === undefined) {
           return writeFailure(

package/src/db/index.ts

@@ -148,6 +148,7 @@ export {
   buildEntityTable,
   declareGlobalTenancy,
   type EntityTable,
+  physicalColumnName,
   toSnakeCase,
   toTableName,
 } from "./table-builder";

package/src/db/tenant-db.ts

@@ -25,7 +25,7 @@ import {
   type WhereObject,
 } from "../db/query";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
-import { AccessDeniedError, InternalError } from "../errors";
+import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import { fallbackEscapeHatchReporter } from "../observability/escape-hatch-report";
 import type { DbRunner } from "./connection";
@@ -202,6 +202,9 @@ export type TenantDbGrants = {
   readonly globalWrites?: EscapeHatchDeclaration;
   readonly unsafeRaw?: EscapeHatchDeclaration;
   readonly report?: EscapeHatchReporter;
+  // Set for a resolved member principal (ctx.queryAsMember): no raw DbRunner leaves
+  // this TenantDb, so no handler can COMMIT/RELEASE SAVEPOINT out of the READ ONLY scope.
+  readonly memberReadOnly?: boolean;
 };
 
 const unsafeRawRebinders = new WeakMap<
@@ -419,6 +422,10 @@ export function createTenantDb(
     if (reason.trim().length === 0) {
       throw new Error("unsafeRaw requires a non-empty reason");
     }
+    // Ahead of the grant check: a declared escapeHatch must not buy a raw runner here either.
+    if (grants?.memberReadOnly) {
+      throw memberResolutionReadOnlyDenied();
+    }
     if (!hasGrant(grants?.unsafeRaw)) {
       throw new AccessDeniedError({
         message:

package/src/engine/__tests__/boot-validator-i18n-keys.test.ts

@@ -95,3 +95,59 @@ describe("validateBoot — i18n surface keys", () => {
     expect(() => validateBoot([feature])).not.toThrow();
   });
 });
+
+// fw#2986: requiredKeysFromScreen read only section.fields, so a field declared
+// through section.groups — and every groups[].title — slipped past this guard.
+describe("validateBoot — i18n surface keys from section.groups (fw#2986)", () => {
+  function groupsFeature(keys: Record<string, { de: string; en: string }>) {
+    return defineFeature("demo", (r) => {
+      r.entity(
+        "item",
+        createEntity({
+          table: "Items",
+          fields: {
+            name: createTextField({ sortable: true, personal: false, reason: "test_fixture" }),
+          },
+        }),
+      );
+      r.screen({
+        id: "item-edit",
+        type: "entityEdit",
+        entity: "item",
+        layout: {
+          sections: [
+            {
+              fields: [],
+              groups: [{ title: "demo:group.basics", fields: ["name"] }],
+            },
+          ],
+        },
+      });
+      r.translations({ keys });
+    });
+  }
+
+  const complete = {
+    "screen:item-edit.title": { de: "Bearbeiten", en: "Edit" },
+    "demo:group.basics": { de: "Basis", en: "Basics" },
+    "demo:entity:item:field:name": { de: "Name", en: "Name" },
+  };
+
+  test("passes when the group title and the group's field label are translated", () => {
+    expect(() => validateBoot([groupsFeature(complete)])).not.toThrow();
+  });
+
+  test("throws for a missing label of a field declared only in groups", () => {
+    const { "demo:entity:item:field:name": _dropped, ...withoutFieldLabel } = complete;
+    expect(() => validateBoot([groupsFeature(withoutFieldLabel)])).toThrow(
+      /required translation key missing: "demo:entity:item:field:name"/,
+    );
+  });
+
+  test("throws for a missing groups[].title translation", () => {
+    const { "demo:group.basics": _dropped, ...withoutGroupTitle } = complete;
+    expect(() => validateBoot([groupsFeature(withoutGroupTitle)])).toThrow(
+      /required translation key missing: "demo:group\.basics"/,
+    );
+  });
+});