@cosmicdrift/kumiko-framework 0.290.0 → 0.292.0

package/src/crypto/__tests__/event-pii.test.ts

@@ -30,6 +30,12 @@ const attemptSchema = z.object({
   status: z.string(),
 });
 
+const requiredOwnerSchema = z.object({
+  recipientId: z.string(),
+  recipientAddress: z.string().nullable(),
+  status: z.string(),
+});
+
 const EVENT_TYPE = "mailer:event:attempt";
 
 const ENVELOPE: EventSubjectEnvelope = {
@@ -54,18 +60,28 @@ describe("normalizeEventPiiSubject", () => {
     expect(normalizeEventPiiSubject({ personal: { of: "recipientId" } })).toEqual({
       kind: "user",
       ownerField: "recipientId",
+      whenAbsent: undefined,
     });
     expect(normalizeEventPiiSubject({ subjectField: "recipientId" })).toEqual({
       kind: "user",
       ownerField: "recipientId",
+      whenAbsent: undefined,
     });
   });
+
+  test("whenAbsent rides along on the canonical form", () => {
+    expect(
+      normalizeEventPiiSubject({ personal: { of: "recipientId", whenAbsent: "tenant" } }),
+    ).toEqual({ kind: "user", ownerField: "recipientId", whenAbsent: "tenant" });
+  });
 });
 
 describe("defineEvent piiFields validation", () => {
   test("valid piiFields land on the EventDef and in the registry catalog", () => {
+    // The deprecated subjectField form cannot express whenAbsent, so it only
+    // registers against a schema whose owner field is always populated.
     const feature = defineFeature("mailer", (r) => {
-      r.defineEvent("attempt", attemptSchema, {
+      r.defineEvent("attempt", requiredOwnerSchema, {
         piiFields: { recipientAddress: { subjectField: "recipientId" } },
       });
     });
@@ -108,12 +124,12 @@ describe("defineEvent piiFields validation", () => {
   test("valid canonical personal.of piiFields land on the EventDef and in the registry catalog", () => {
     const feature = defineFeature("mailer", (r) => {
       r.defineEvent("attempt", attemptSchema, {
-        piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+        piiFields: { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
       });
     });
     createRegistry([feature]);
     expect(configuredEventPiiCatalog().get(EVENT_TYPE)).toEqual({
-      recipientAddress: { personal: { of: "recipientId" } },
+      recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },
     });
   });
 
@@ -206,6 +222,41 @@ describe("defineEvent piiFields validation", () => {
       }),
     ).toThrow(/piiFields references "nope"/);
   });
+
+  test("a nullable owner field without a whenAbsent stance fails registration", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+        });
+      }),
+    ).toThrow(/allows to be null\/undefined/);
+  });
+
+  test("a nullable owner field with a declared whenAbsent registers", () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema, {
+        piiFields: { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
+      });
+    });
+    expect(feature.events["attempt"]?.piiFields).toEqual({
+      recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },
+    });
+  });
+
+  test("a non-nullable owner field needs no whenAbsent", () => {
+    const required = z.object({
+      recipientId: z.string(),
+      recipientAddress: z.string(),
+    });
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", required, {
+          piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+        });
+      }),
+    ).not.toThrow();
+  });
 });
 
 describe("encryptEventPayloadPii", () => {
@@ -255,17 +306,67 @@ describe("encryptEventPayloadPii", () => {
     expect(String(canonical["recipientAddress"])).toContain("user:u-1");
   });
 
-  test("null subject field → value stays plaintext (no user key to shred)", async () => {
+  const systemPayload = {
+    recipientId: null,
+    recipientAddress: "ops@example.com",
+    status: "sent",
+  };
+
+  test("null subject field without a whenAbsent stance fails the append closed", async () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());
-    const systemPayload = {
-      recipientId: null,
-      recipientAddress: "ops@example.com",
-      status: "sent",
-    };
+    expect(encryptEventPayloadPii(EVENT_TYPE, systemPayload, ENVELOPE)).rejects.toThrow(
+      /carries no id and the event declares no whenAbsent fallback/,
+    );
+  });
+
+  test('null subject field with whenAbsent: "tenant" encrypts under the envelope tenant key', async () => {
+    configureEventPiiCatalog(
+      new Map([
+        [
+          EVENT_TYPE,
+          { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
+        ],
+      ]),
+    );
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+
+    const out = await encryptEventPayloadPii(EVENT_TYPE, systemPayload, ENVELOPE);
+    expect(isPiiCiphertext(out["recipientAddress"])).toBe(true);
+    expect(String(out["recipientAddress"])).toContain(`tenant:${ENVELOPE.tenantId}`);
+
+    const back = await decryptPiiFieldValues(out, ["recipientAddress"], kms, { requestId: "test" });
+    expect(back["recipientAddress"]).toBe("ops@example.com");
+  });
+
+  test('null subject field with whenAbsent: "plaintext" is an acknowledged passthrough', async () => {
+    configureEventPiiCatalog(
+      new Map([
+        [
+          EVENT_TYPE,
+          { recipientAddress: { personal: { of: "recipientId", whenAbsent: "plaintext" } } },
+        ],
+      ]),
+    );
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
     expect(await encryptEventPayloadPii(EVENT_TYPE, systemPayload, ENVELOPE)).toBe(systemPayload);
   });
 
+  test('whenAbsent: "tenant" still prefers the user key when the owner field is populated', async () => {
+    configureEventPiiCatalog(
+      new Map([
+        [
+          EVENT_TYPE,
+          { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
+        ],
+      ]),
+    );
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const out = await encryptEventPayloadPii(EVENT_TYPE, payload, ENVELOPE);
+    expect(String(out["recipientAddress"])).toContain("user:u-1");
+  });
+
   test("null pii value passes through", async () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());

package/src/crypto/__tests__/subject-resolver.test.ts

@@ -154,16 +154,37 @@ describe("resolveEventSubject (fw#2801)", () => {
     expect(subject).toEqual({ kind: "user", userId: UUID_A });
   });
 
-  test("personal: { of } with a missing owner value → null, no throw (system-triggered event)", () => {
+  test("personal: { of } with a missing owner value and no whenAbsent → throws (fw#2776)", () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: { of: "authorId" } },
+        { authorId: null },
+        { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+      ),
+    ).toThrow(/carries no id and the event declares no whenAbsent fallback/);
+  });
+
+  test('personal: { of, whenAbsent: "plaintext" } with a missing owner → null (fw#2776)', () => {
     const subject = resolveEventSubject(
       "note",
-      { personal: { of: "authorId" } },
+      { personal: { of: "authorId", whenAbsent: "plaintext" } },
       { authorId: null },
       { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
     );
     expect(subject).toBeNull();
   });
 
+  test('personal: { of, whenAbsent: "tenant" } with a missing owner → envelope tenant (fw#2776)', () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: { of: "authorId", whenAbsent: "tenant" } },
+      { authorId: null },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "tenant", tenantId: EVENT_TENANT });
+  });
+
   test('personal: "tenant" → subject from the envelope tenantId', () => {
     const subject = resolveEventSubject(
       "note",

package/src/crypto/subject-resolver.ts

@@ -135,11 +135,19 @@ export interface EventSubjectEnvelope {
   readonly aggregateId: string;
 }
 
+function resolveEnvelopeTenant(fieldName: string, envelope: EventSubjectEnvelope): SubjectId {
+  if (nonEmptyString(envelope.tenantId) === null) {
+    throw new SubjectResolutionError(fieldName, "event envelope tenantId is empty");
+  }
+  return { kind: "tenant", tenantId: envelope.tenantId };
+}
+
 // Same resolver for the live-append path (encryptEventPayloadPii) and the
 // backfill catalog path (backfillEventPiiEncryption) — the reason the two
-// can never encrypt the same field under different subjects. "user" returns
-// null on a missing owner (no key to shred for system-triggered events);
-// "tenant"/"self" throw instead, since their envelope facts are structural.
+// can never encrypt the same field under different subjects. A "user"
+// subject whose owner field is empty falls back to the declared whenAbsent
+// stance and throws when none is declared (fw#2776); "tenant"/"self" throw
+// on an empty envelope, since their facts are structural.
 export function resolveEventSubject(
   fieldName: string,
   spec: EventPiiSubject,
@@ -150,14 +158,23 @@ export function resolveEventSubject(
 
   if (normalized.kind === "user") {
     const userId = nonEmptyString(payload[normalized.ownerField]);
-    return userId === null ? null : { kind: "user", userId };
+    if (userId !== null) return { kind: "user", userId };
+    if (normalized.whenAbsent === "tenant") return resolveEnvelopeTenant(fieldName, envelope);
+    if (normalized.whenAbsent === "plaintext") {
+      // skip: author declared whenAbsent: "plaintext" — value ships unencrypted by decision
+      return null;
+    }
+    throw new SubjectResolutionError(
+      fieldName,
+      `owner field "${normalized.ownerField}" carries no id and the event declares no whenAbsent fallback — ` +
+        `refusing to append plaintext PII. Declare { personal: { of: "${normalized.ownerField}", ` +
+        `whenAbsent: "tenant" } } to encrypt under the envelope tenant key, or whenAbsent: "plaintext" ` +
+        "to acknowledge that this value cannot be crypto-shredded (fw#2776).",
+    );
   }
 
   if (normalized.kind === "tenant") {
-    if (nonEmptyString(envelope.tenantId) === null) {
-      throw new SubjectResolutionError(fieldName, "event envelope tenantId is empty");
-    }
-    return { kind: "tenant", tenantId: envelope.tenantId };
+    return resolveEnvelopeTenant(fieldName, envelope);
   }
 
   if (normalized.kind === "self") {

package/src/db/queries/shadow-swap.ts

@@ -18,6 +18,7 @@
 // expressed in meta (hand-added in a migration) is not reconstructed, and a
 // partial index whose WHERE the renderer can't express is rejected up-front.
 
+import { configuredBlindIndexKey } from "../../crypto";
 import type { DbConnection, DbTx } from "../connection";
 import type { EntityTableMeta } from "../entity-table-meta";
 import { type AnyDb, asEntityTableMeta, asRawClient } from "../query";
@@ -247,6 +248,40 @@ export async function assertNoUnreachableLiveRows(
   );
 }
 
+// The bidx column is schema-driven, not key-driven: it exists NULL in a
+// plaintext install and in the fw#1610 case (KMS configured, no index key),
+// both of which are correct as-is. Only a POPULATED column with no key
+// configured in THIS process means the rebuild is about to overwrite proof
+// of a real index with NULL — that's the one provable data-loss case.
+export async function assertNoBlindIndexLoss(
+  tx: AnyDb,
+  tableName: string,
+  meta: EntityTableMeta,
+  projectionName: string,
+): Promise<void> {
+  // skip: a key is configured — the replay recomputes every bidx column with it
+  if (configuredBlindIndexKey() !== undefined) return;
+  const bidxCols = meta.columns.filter((c) => c.name.endsWith("_bidx"));
+  // skip: no blind-index column on this table — nothing the rebuild could lose
+  if (bidxCols.length === 0) return;
+  const t = quoteTableIdent(tableName);
+  const raw = asRawClient(tx);
+  const where = bidxCols.map((c) => `${quoteTableIdent(c.name)} IS NOT NULL`).join(" OR ");
+  const rows = await raw.unsafe<{ total: string }>(
+    `SELECT count(*)::text AS total FROM public.${t} WHERE ${where}`,
+  );
+  const count = Number(rows[0]?.total ?? "0");
+  // skip: every bidx column is already NULL — nothing for the rebuild to lose
+  if (count === 0) return;
+  throw new Error(
+    `projection-rebuild "${projectionName}": "${tableName}" has ${count} row(s) with a populated ` +
+      `blind-index column, but KUMIKO_BLIND_INDEX_KEY is not configured in this process. The rebuild ` +
+      `would recompute those columns to NULL, and equality lookups on that field (login, password ` +
+      `reset) would stop matching afterward. Configure the blind-index key before this apply/rebuild ` +
+      `runs. See fw#3091. Rebuild aborted; live table untouched.`,
+  );
+}
+
 // Columns ignored by countColumnDrift — the one PROVABLY legitimate class of
 // live-vs-shadow divergence. A blind-index column (`<field>_bidx`) is
 // recomputed to NULL on GDPR key-shredding; the NULL is the intended end

package/src/engine/__tests__/boot-validator-pii-retention.test.ts

@@ -603,6 +603,128 @@ describe("validateBoot — PII annotations", () => {
     );
     expect(matchingWarn).toBeDefined();
   });
+
+  // --- #2918: deprecation warning for text fields without any stance ---
+
+  const NO_STANCE = "declares no personal stance";
+
+  test("text field without a personal stance warns, naming feature, entity and field", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: { ...unannotatedText },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeDefined();
+    const message = String((matchingWarn as unknown[])[0]);
+    expect(message).toContain("[Feature test]");
+    expect(message).toContain('Field "externalRef" on entity "invoice"');
+    expect(message).toContain('{ reason: "..." }');
+  });
+
+  test("longText field without a personal stance warns", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            remarks: { ...unannotatedLongText },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeDefined();
+  });
+
+  test("personal: false with a reason silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: createTextField({
+              personal: false,
+              reason: "is_business_data",
+            }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("personal: self silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: createTextField({
+              personal: "self",
+              find: "none",
+            }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("personal: ref silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            ownerRef: createTextField({ personal: "ref" }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("number field without a personal stance does not warn", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            total: { type: "number", required: false },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
 });
 
 describe("validateBoot — retention", () => {

package/src/engine/__tests__/boot-validator-projection-list.test.ts

@@ -443,6 +443,99 @@ describe("validateBoot — projectionList screens", () => {
       expect(() => validateBoot([feature])).not.toThrow();
     });
 
+    // fw#3104: a dateRange facet sends its two bounds as the top-level params
+    // it names, so `filters` is the wrong thing to require — the declared
+    // param names are.
+    test("a dateRange facet on a query that can't narrow by time is rejected at boot", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ from: z.iso.datetime().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["dueAt"],
+          facets: [
+            {
+              field: "dueAt",
+              type: "dateRange",
+              label: "Due",
+              params: { from: "from", to: "to" },
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/no "to" parameter/);
+    });
+
+    test('a dateRange facet does NOT require a "filters" parameter', () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({
+            since: z.iso.datetime().optional(),
+            until: z.iso.datetime().optional(),
+          }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["dueAt"],
+          facets: [
+            {
+              field: "dueAt",
+              type: "dateRange",
+              label: "Due",
+              params: { from: "since", to: "until" },
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
+    test("a dateRange facet naming a reserved list-payload key is rejected", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ limit: z.number().optional(), to: z.iso.datetime().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["dueAt"],
+          facets: [
+            {
+              field: "dueAt",
+              type: "dateRange",
+              label: "Due",
+              params: { from: "limit", to: "to" },
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/reserved list-payload key/);
+    });
+
     test("a reference facet targeting an unknown entity is rejected", () => {
       const feature = defineFeature("ledger", (r) => {
         r.queryHandler(