@cosmicdrift/kumiko-framework 0.209.1 → 0.210.0

package/src/engine/types/index.ts

@@ -106,16 +106,22 @@ export type {
   FieldsMap,
   FileFieldDef,
   FilesFieldDef,
+  Findability,
   ImageFieldDef,
   ImagesFieldDef,
   JsonbFieldDef,
   LocatedTimestampFieldDef,
   LongTextFieldDef,
+  LongTextFindability,
   MoneyFieldDef,
   MultiSelectFieldDef,
   NumberFieldDef,
-  PiiAnnotations,
+  PersonalAnnotations,
+  PersonalAnnotationsLongText,
+  PersonalAnnotationsNoFind,
+  PersonalSubject,
   ReferenceFieldDef,
+  ResolvedPiiFlags,
   RetentionDef,
   SelectFieldDef,
   TextFieldDef,

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -37,7 +37,7 @@ const BIDX_KEY = Buffer.alloc(32, 5).toString("base64");
 
 const contactEntity = createEntity({
   fields: {
-    email: createTextField({ required: true, pii: true, lookupable: true }),
+    email: createTextField({ required: true, personal: "self", find: "exact" }),
     displayName: createTextField(),
   },
 });
@@ -55,6 +55,20 @@ const mailerFeature = defineFeature("mailer", (r) => {
   );
 });
 
+// personal: { of } (not "self") — the named owner field can legitimately be
+// absent from an old event's payload, unlike contact.email (self-subject via row id).
+const noteEntity = createEntity({
+  fields: {
+    authorId: createTextField(),
+    body: createTextField({ personal: { of: "authorId" }, find: "none" }),
+  },
+});
+const noteTable = buildEntityTable("note", noteEntity);
+
+const notesFeature = defineFeature("notes", (r) => {
+  r.entity("note", noteEntity);
+});
+
 let testDb: TestDb;
 let registry: Registry;
 let kms: InMemoryKmsAdapter;
@@ -79,9 +93,10 @@ async function appendPlain(
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  registry = createRegistry([crmFeature, mailerFeature]);
+  registry = createRegistry([crmFeature, mailerFeature, notesFeature]);
   await createEventsTable(testDb.db);
   await unsafeCreateEntityTable(testDb.db, contactEntity, "contact");
+  await unsafeCreateEntityTable(testDb.db, noteEntity, "note");
 });
 
 afterAll(async () => {
@@ -92,6 +107,7 @@ beforeEach(async () => {
   const raw = asRawClient(testDb.db);
   await raw.unsafe(`TRUNCATE "kumiko_events" RESTART IDENTITY`);
   await raw.unsafe(`TRUNCATE "${contactTable.tableName}"`);
+  await raw.unsafe(`TRUNCATE "${noteTable.tableName}"`);
   // Plaintext era: NO KMS while the legacy events are appended.
   resetPiiSubjectKmsForTests();
   resetBlindIndexKeyForTests();
@@ -280,6 +296,167 @@ describe("backfillEventPiiEncryption", () => {
   });
 });
 
+describe("backfillEventPiiEncryption: owner-resolution chain (fw#2266)", () => {
+  async function insertNoteProjectionRow(id: string, authorId: string): Promise<void> {
+    await asRawClient(testDb.db).unsafe(
+      `INSERT INTO "${noteTable.tableName}" (id, tenant_id, author_id, body) VALUES ($1, $2, $3, $4)`,
+      [id, TENANT, authorId, "projection-row-body"],
+    );
+  }
+
+  test("payload missing owner + projection row has it: resolveOwnerFromProjection encrypts, no failures", async () => {
+    const author = generateId();
+    const noteId = generateId();
+    await insertNoteProjectionRow(noteId, author);
+    // Legacy event predating the authorId column — payload never carried it.
+    await appendPlain(noteId, "note", "note.created", { id: noteId, body: "old plaintext note" });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry, {
+      resolveOwnerFromProjection: true,
+    });
+
+    expect(result.failures).toEqual([]);
+    expect(result.encryptedFields).toBe(1);
+    expect(result.ownerFromProjection).toBe(1);
+
+    const created = (await loadAggregate(testDb.db, noteId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(isPiiCiphertext(created["body"])).toBe(true);
+    expect(String(created["body"])).toContain(`user:${author}`);
+  });
+
+  test("same event without the flags: stays in failures (default behavior unchanged)", async () => {
+    const author = generateId();
+    const noteId = generateId();
+    await insertNoteProjectionRow(noteId, author);
+    await appendPlain(noteId, "note", "note.created", { id: noteId, body: "old plaintext note" });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.encryptedFields).toBe(0);
+    expect(result.failures).toHaveLength(1);
+    expect(result.failures[0]?.reason).toContain("resolveOwnerFromProjection");
+    expect(result.failures[0]?.reason).toContain("eraseUnresolvableSubjects");
+
+    const created = (await loadAggregate(testDb.db, noteId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(created["body"]).toBe("old plaintext note");
+  });
+
+  test("owner missing from payload AND projection: eraseUnresolvableSubjects sentinels the field", async () => {
+    const noteId = generateId();
+    // No projection row for this aggregate — hard-deleted, or never rebuilt.
+    await appendPlain(noteId, "note", "note.created", { id: noteId, body: "orphaned note" });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry, {
+      resolveOwnerFromProjection: true,
+      eraseUnresolvableSubjects: true,
+    });
+
+    expect(result.failures).toEqual([]);
+    expect(result.erasedFields).toBe(1);
+    expect(result.erasedUnresolvable).toBe(1);
+
+    const created = (await loadAggregate(testDb.db, noteId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(created["body"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("already-ciphertext field with unresolvable owner is left untouched (no data loss)", async () => {
+    // Produce genuine ciphertext under a real, resolvable subject first.
+    const author = generateId();
+    const seedId = generateId();
+    await appendPlain(seedId, "note", "note.created", {
+      id: seedId,
+      authorId: author,
+      body: "seed",
+    });
+
+    armKms();
+    await backfillEventPiiEncryption(testDb.db, registry);
+    const seeded = (await loadAggregate(testDb.db, seedId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    const ciphertext = seeded["body"];
+    expect(isPiiCiphertext(ciphertext)).toBe(true);
+
+    // New event: body already holds that ciphertext, owner unresolvable
+    // (no authorId in payload, no projection row for THIS aggregate).
+    const noteId = generateId();
+    await appendPlain(noteId, "note", "note.created", { id: noteId, body: ciphertext });
+
+    const result = await backfillEventPiiEncryption(testDb.db, registry, {
+      resolveOwnerFromProjection: true,
+      eraseUnresolvableSubjects: true,
+    });
+
+    expect(result.failures).toEqual([]);
+    expect(result.erasedUnresolvable).toBe(0);
+    expect(result.encryptedFields).toBe(0);
+    expect(result.erasedFields).toBe(0);
+
+    const created = (await loadAggregate(testDb.db, noteId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(created["body"]).toBe(ciphertext);
+  });
+
+  test("payload owner differs from projection owner: payload wins, ownerFromProjection stays 0", async () => {
+    const payloadAuthor = generateId();
+    const projectionAuthor = generateId();
+    const noteId = generateId();
+    await insertNoteProjectionRow(noteId, projectionAuthor);
+    // Ownership changed since this event was written — payload is the
+    // historical truth, the projection only today's state. Stage 2 must
+    // fill gaps, never override a value stage 1 already resolved.
+    await appendPlain(noteId, "note", "note.created", {
+      id: noteId,
+      authorId: payloadAuthor,
+      body: "old plaintext note",
+    });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry, {
+      resolveOwnerFromProjection: true,
+    });
+
+    expect(result.failures).toEqual([]);
+    expect(result.encryptedFields).toBe(1);
+    expect(result.ownerFromProjection).toBe(0);
+
+    const created = (await loadAggregate(testDb.db, noteId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(isPiiCiphertext(created["body"])).toBe(true);
+    expect(String(created["body"])).toContain(`user:${payloadAuthor}`);
+  });
+
+  test("pii field absent from the section with an unresolvable owner: skipped, no failure (no flags)", async () => {
+    const noteId = generateId();
+    // No "body" key at all, no authorId, no projection row — the value
+    // guard skips owner resolution entirely before it could ever fail.
+    await appendPlain(noteId, "note", "note.created", { id: noteId });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.failures).toEqual([]);
+    expect(result.updatedEvents).toBe(0);
+  });
+});
+
 describe("backfillEventPiiEncryption: raw jsonb column type (fw#2253)", () => {
   // The UPDATE used to wrap outcome.payload in JSON.stringify before handing
   // it to the ::jsonb cast — Bun.SQL already serializes objects, so the

package/src/files/file-ref-entity.ts

@@ -14,7 +14,7 @@ import { createBigIntField, createEntity, createTextField } from "../engine";
 // ohne `.default(now()).notNull()` macht inserted_at still nullable.
 //
 // PII-Annotations:
-//   - fileName → pii: true (Originalname enthält oft Personen-Bezug:
+//   - fileName → personal: "self" (Originalname enthält oft Personen-Bezug:
 //     "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf"). Andere Felder
 //     (storageKey, mimeType, size, entityType, entityId, fieldName) treffen
 //     die PII-Heuristik nicht.
@@ -23,7 +23,7 @@ export const fileRefEntity = createEntity({
   softDelete: true,
   fields: {
     storageKey: createTextField({ required: true }),
-    fileName: createTextField({ required: true, pii: true }),
+    fileName: createTextField({ required: true, personal: "self", find: "none" }),
     mimeType: createTextField({ required: true }),
     size: createBigIntField({ required: true }),
     entityType: createTextField(),

package/src/search/__tests__/reindex-entity.integration.test.ts

@@ -46,7 +46,7 @@ const widgetFeature = defineFeature("reindex-test", (r) => {
 const contactEntity = createEntity({
   table: "read_reindex_contacts",
   fields: {
-    label: createTextField({ required: true, maxLength: 100, pii: true, searchable: true }),
+    label: createTextField({ required: true, maxLength: 100, personal: "self", find: "fuzzy" }),
   },
 });
 const contactTable = buildEntityTable("contact", contactEntity);

package/src/search/__tests__/search-pii-derived-index.integration.test.ts

@@ -18,8 +18,8 @@ import { purgeSearchDocumentsForSubject } from "../purge-subject";
 const contactEntity = createEntity({
   table: "read_search_pii_contacts",
   fields: {
-    // pii: true → subject = entity id (self). searchable via derived index.
-    label: createTextField({ required: true, maxLength: 100, pii: true, searchable: true }),
+    // personal: "self" → subject = entity id. find: "fuzzy" → searchable via derived index.
+    label: createTextField({ required: true, maxLength: 100, personal: "self", find: "fuzzy" }),
     note: createTextField({ required: true, maxLength: 100, searchable: true }),
   },
 });

package/src/testing/shared-entities.ts

@@ -31,15 +31,18 @@ export const sharedUserEntity = createEntity({
       required: true,
       format: "email",
       searchable: true,
-      allowPlaintext: "test-fixture",
+      personal: false,
+      reason: "test_fixture",
     }),
     firstName: createTextField({
       searchable: true,
-      allowPlaintext: "test-fixture",
+      personal: false,
+      reason: "test_fixture",
     }),
     lastName: createTextField({
       searchable: true,
-      allowPlaintext: "test-fixture",
+      personal: false,
+      reason: "test_fixture",
     }),
     isEnabled: createBooleanField({ default: true }),
   },