@cosmicdrift/kumiko-bundled-features 0.235.4 → 0.236.0

package/src/notes-history/entity.ts

@@ -2,6 +2,7 @@ import {
   createEntity,
   createLongTextField,
   createTextField,
+  type EntityDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
 
 // note-entry — host-agnostic, append-only note attached to ANY entity via
@@ -14,35 +15,53 @@ import {
 // Strictly append-only by design: no update/delete write-handler is
 // registered (see feature.ts). A correction is a new entry, not an edit —
 // that is the whole point of a note *history* instead of the single
-// overwritable textarea this bundle replaces (solon#13). GDPR erasure of the
-// author still works without a delete path: `body` is `personal: { of:
-// "authorId" }` (crypto-shredding on the author's subject key), not
-// `personal: "self"` on the entity itself.
-export const noteEntryEntity = createEntity({
-  table: "read_note_entries",
-  fields: {
-    entityType: createTextField({ required: true, maxLength: 64 }),
-    // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
-    entityId: createTextField({ required: true, maxLength: 128 }),
-    // Never client-supplied — stamped by the deriveAuthorId preSave hook from
-    // ctx.user.id (see feature.ts), so a note can't be authored as someone
-    // else. subjectRef feeds the GDPR-hook-coverage boot guard (it's a plain
-    // FK into `user`, not content of its own).
-    authorId: createTextField({
-      personal: "ref",
-    }),
-    // Stamped once at write time, never re-resolved later — the history
-    // needs the name as it was then, not whatever the account is called now.
-    authorName: createTextField({
-      maxLength: 200,
-      personal: { of: "authorId" },
-      find: "none",
-    }),
-    body: createLongTextField({
-      required: true,
-      maxLength: 20_000,
-      personal: { of: "authorId" },
-      find: "none",
-    }),
-  },
-});
+// overwritable textarea this bundle replaces (solon#13).
+//
+// `body` is about the HOST entity (entityType/entityId), not the author —
+// the author is never the data subject of a note's content, so it is
+// deliberately NOT `personal: { of: "authorId" }`. That axis would
+// crypto-shred every note's content the moment its author's data-rights key
+// is destroyed (an employee leaving triggers a forget), garbling unrelated
+// business notes about customers/projects/etc. — data loss, not privacy.
+// `body` stays plaintext (`personal: false`), same call as tags' catalog
+// `name` field. GDPR erasure of the AUTHOR still shreds `authorName`
+// (`personal: { of: "authorId" }`, the name as stamped at write time) —
+// `body` and the note itself are unaffected. If a note's body incidentally
+// names or describes a third party, that isn't tracked by field annotation
+// today; no PII hooks exist for note content.
+export function createNoteEntryEntity(access?: EntityDefinition["access"]) {
+  return createEntity({
+    table: "read_note_entries",
+    access,
+    fields: {
+      entityType: createTextField({ required: true, maxLength: 64 }),
+      // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+      entityId: createTextField({ required: true, maxLength: 128 }),
+      // Never client-supplied — stamped by the deriveAuthorId preSave hook from
+      // ctx.user.id (see feature.ts), so a note can't be authored as someone
+      // else. subjectRef feeds the GDPR-hook-coverage boot guard (it's a plain
+      // FK into `user`, not content of its own).
+      authorId: createTextField({
+        personal: "ref",
+      }),
+      // Stamped once at write time, never re-resolved later — the history
+      // needs the name as it was then, not whatever the account is called now.
+      authorName: createTextField({
+        maxLength: 200,
+        personal: { of: "authorId" },
+        find: "none",
+      }),
+      body: createLongTextField({
+        required: true,
+        maxLength: 20_000,
+        // Describes the host entity, not the author — no per-user subject to
+        // crypto-shred against. `personal: false` silences the
+        // user-content-name heuristic (`body` is on PII_USER_OWNED_NAME_HINTS).
+        personal: false,
+        reason: "note_content_not_owned_by_author",
+      }),
+    },
+  });
+}
+
+export const noteEntryEntity = createNoteEntryEntity();

package/src/notes-history/feature.ts

@@ -17,16 +17,19 @@ import {
   type AccessRule,
   defineEntityListHandler,
   defineFeature,
+  type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { hasWhereRule } from "../shared";
 import { DEFAULT_NOTES_HISTORY_ACCESS, NOTES_HISTORY_FEATURE_NAME } from "./constants";
-import { noteEntryEntity } from "./entity";
+import { createNoteEntryEntity } from "./entity";
 import { createAddNoteHandler } from "./handlers/add-note.write";
 import { NOTES_HISTORY_FEATURE_I18N } from "./i18n";
 
 function registerNotesHistory(
   r: FeatureRegistrar<typeof NOTES_HISTORY_FEATURE_NAME>,
   access: AccessRule,
+  ownership: EntityDefinition["access"] | undefined,
 ): void {
   r.describe(
     "Generic, host-agnostic, append-only note history for any entity. Owns one event-sourced entity, `note-entry` (`read_note_entries`), keyed by (entityType, entityId) — so attaching notes adds NO column to the host entity and needs no relational pivot or JOIN. Provides a `create` write-handler (author stamped server-side from the caller, never client-supplied) and a `list` query filterable on entityId. Deliberately append-only: no update or delete handler is registered — a correction is a new entry, not an edit, so who-said-what-when stays reconstructable. Every path uses one access rule — adopt the host's model with createNotesHistoryFeature({ access: { openToAll: true } }) or pin roles with createNotesHistoryFeature({ roles }).",
@@ -37,16 +40,17 @@ function registerNotesHistory(
     recommended: false,
   });
 
-  r.entity("note-entry", noteEntryEntity);
+  const entity = createNoteEntryEntity(ownership);
+  r.entity("note-entry", entity);
 
   r.writeHandler(createAddNoteHandler(access));
-  r.queryHandler(defineEntityListHandler("note-entry", noteEntryEntity, { access }));
+  r.queryHandler(defineEntityListHandler("note-entry", entity, { access }));
 
   r.translations({ keys: NOTES_HISTORY_FEATURE_I18N });
 }
 
 export const notesHistoryFeature = defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
-  registerNotesHistory(r, DEFAULT_NOTES_HISTORY_ACCESS),
+  registerNotesHistory(r, DEFAULT_NOTES_HISTORY_ACCESS, undefined),
 );
 
 export type NotesHistoryFeatureOptions = {
@@ -57,6 +61,22 @@ export type NotesHistoryFeatureOptions = {
   readonly access?: AccessRule;
   /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
   readonly roles?: readonly string[];
+  /** Row-level ownership on the note-entry rows themselves — orthogonal to
+   *  `access`, which only gates whether a caller may dispatch create/list at
+   *  all. Set `ownership.read` to close the read leak: without it — even if
+   *  `ownership.write` is set — `access.read` stays undefined and any
+   *  dispatch-eligible user can read every note in the tenant, including
+   *  notes on entities they can't otherwise see.
+   *
+   *  `ownership.write` is separate and does NOT affect list/read. It's
+   *  consulted by the framework's generic delete/forget/restore paths (not
+   *  by this feature's own add-note handler — see createNotesHistoryFeature's
+   *  boot-guard comment). A `from()` rule there also gates GDPR erasure
+   *  (`forget`): if the rule's role map doesn't cover whatever role the
+   *  erasure/retention pipeline runs as, `forget` denies instead of
+   *  crypto-shredding — a silent Art.17 failure, not a thrown error. Make
+   *  sure any `ownership.write` you set covers that role, or leave it unset. */
+  readonly ownership?: EntityDefinition["access"];
 };
 
 function resolveAccess(opts: NotesHistoryFeatureOptions): AccessRule {
@@ -66,12 +86,24 @@ function resolveAccess(opts: NotesHistoryFeatureOptions): AccessRule {
 }
 
 // Options wrapper. Without options returns the module-level singleton (no
-// rebuild). access/roles build a fresh feature-definition.
+// rebuild). access/roles/ownership build a fresh feature-definition.
 export function createNotesHistoryFeature(
   opts: NotesHistoryFeatureOptions = {},
 ): typeof notesHistoryFeature {
-  if (opts.access === undefined && opts.roles === undefined) return notesHistoryFeature;
+  if (opts.access === undefined && opts.roles === undefined && opts.ownership === undefined) {
+    return notesHistoryFeature;
+  }
+  if (hasWhereRule(opts.ownership?.write)) {
+    throw new Error(
+      "createNotesHistoryFeature({ ownership }): ownership.write must not contain a " +
+        '`{ kind: "where" }` rule — where-rules are evaluated only at the SQL ' +
+        "layer (the read path, via buildOwnershipClause). Write paths that " +
+        "consult access.write (userCanCreateFieldRow/userCanWriteFieldRow) can't " +
+        "evaluate them: create throws at runtime, update/delete/forget/restore " +
+        "silently deny. Use a `from()` rule for ownership.write, or leave it unset.",
+    );
+  }
   return defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
-    registerNotesHistory(r, resolveAccess(opts)),
+    registerNotesHistory(r, resolveAccess(opts), opts.ownership),
   );
 }

package/src/notes-history-user-data/hooks.ts

@@ -27,16 +27,19 @@ export const noteEntryExportHook: UserDataExportHook = async (ctx) => {
   };
 };
 
-// Deliberate no-op: `body` and `authorName` are annotated `personal: { of: "authorId" }`
-// (entity.ts), which relies on crypto-shredding (mounted KMS) for erasure —
-// destroying the author's subject key makes every note-entry event AND
-// projected row unreadable at once, without needing a physical delete
-// (which would also break the bundle's append-only history for OTHER
-// entities' co-authors reading it).
+// Deliberate no-op: only `authorName` is annotated `personal: { of: "authorId" }`
+// (entity.ts) — `body` is deliberately plaintext (`personal: false`), since it
+// describes the HOST entity the note is attached to, not the author. So a
+// forget here crypto-shreds (mounted KMS) just `authorName`: after erasing
+// the author, who wrote a note is no longer visible, but the note's content
+// stays intact and readable — the note is about the host entity, and other
+// readers of that entity's history still need it. No physical delete is
+// needed for either outcome.
 // Same tradeoff as job-run/delivery-attempt (user-data-rights-defaults).
 // Precondition: this ONLY erases anything if the app mounts a KMS adapter —
 // without one, userOwned fields fall back to plaintext storage framework-wide
-// (see pii-field-encryption.ts) and forget is a true no-op for `body`. That
-// gap is a property of the framework's crypto-shredding design, not specific
-// to this hook; apps that need Art.17 coverage without KMS must mount one.
+// (see pii-field-encryption.ts) and forget is a true no-op for `authorName`
+// too. That gap is a property of the framework's crypto-shredding design,
+// not specific to this hook; apps that need Art.17 coverage without KMS must
+// mount one.
 export const noteEntryDeleteHook: UserDataDeleteHook = async () => {};

package/src/shared/has-where-rule.ts

@@ -0,0 +1,14 @@
+import type { OwnershipMap } from "@cosmicdrift/kumiko-framework/engine";
+
+// `where`-rules are read-path only (buildOwnershipClause). On the write path
+// userCanWriteFieldRow silently skips them (fail-closed deny), but
+// userCanCreateFieldRow does NOT skip them — it runs matchesRule(), which
+// throws for `kind: "where"` (no in-memory evaluator for raw SQL). An
+// ownership.write map with a where-rule boots fine (the boot-validator has no
+// where-specific handling either) and only blows up the first time a create
+// hits it. Feature factories that accept an `ownership` option must reject
+// this shape at build time instead of shipping the landmine.
+export function hasWhereRule(map: OwnershipMap | undefined): boolean {
+  if (!map) return false;
+  return Object.values(map).some((rule) => rule !== "all" && rule.kind === "where");
+}

package/src/shared/index.ts

@@ -13,6 +13,7 @@ export { decryptStoredPii } from "./decrypt-stored-pii";
 export { encryptForDirectWrite } from "./encrypt-for-direct-write";
 export { entitiesOf } from "./entities-of";
 export { isWithinGracePeriod } from "./grace-period";
+export { hasWhereRule } from "./has-where-rule";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
 export { mapWithConcurrency } from "./map-with-concurrency";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";

package/src/tags/__tests__/tags-ownership.test.ts

@@ -0,0 +1,23 @@
+// H.2 boot guard — mirrors notes-history-ownership.integration.test.ts's
+// guard test. A where-rule in ownership.write boots fine (the boot-validator
+// has no where-specific handling) and only blows up the first time
+// assign-tag's create() hits it (userCanCreateFieldRow throws on
+// `kind: "where"`, unlike update/delete/forget which silently deny). No DB
+// needed — the guard fires at feature-construction time.
+
+import { describe, expect, test } from "bun:test";
+import { createTagsFeature } from "../feature";
+
+describe("tags — boot guard rejects a where-rule in ownership.write", () => {
+  test("createTagsFeature throws instead of shipping a create()-time landmine", () => {
+    expect(() =>
+      createTagsFeature({
+        ownership: {
+          write: {
+            TenantMember: { kind: "where", where: () => ({ sqlText: "1=1", params: [] }) },
+          },
+        },
+      }),
+    ).toThrow(/ownership\.write must not contain a.*where/);
+  });
+});

package/src/tags/entity.ts

@@ -1,4 +1,8 @@
-import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createTextField,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 // tag — per-tenant tag catalog. Event-sourced entity (create/rename/delete via
 // the standard executor); the framework projects `read_tags` from its own CRUD
@@ -7,11 +11,12 @@ export const tagEntity = createEntity({
   table: "read_tags",
   fields: {
     // Catalog labels ("urgent", "billing"), not user-identifying content —
-    // `personal: false` silences the user-content heuristic (456/5). A
-    // tenant COULD name a tag after a person; if that becomes a real
-    // requirement, this needs a `personal: { of: "<f>" }` annotation +
-    // forget/export hooks in the user-data-rights pipeline (none exist for
-    // tags today).
+    // `personal: false` silences the user-content heuristic (456/5). A tag
+    // has no author to anchor a `personal: { of: "<f>" }` annotation to, and
+    // a tag isn't ABOUT the entity that created it anyway — it's a catalog
+    // entry shared across whatever gets assigned it. If a tenant ever names a
+    // tag after a real person, the fix is renaming or deleting that tag, not
+    // wiring it to a subject key.
     name: createTextField({
       required: true,
       maxLength: 64,
@@ -48,13 +53,18 @@ export const tagEntity = createEntity({
 // Cross-entity views compose in the read-layer (no JOIN):
 //   - tags of an entity   → list assignments filter { field: "entityId", op: "eq" }
 //   - entities with a tag  → list assignments filter { field: "tagId",   op: "eq" }
-export const tagAssignmentEntity = createEntity({
-  table: "read_tag_assignments",
-  softDelete: true,
-  fields: {
-    tagId: createTextField({ required: true, maxLength: 64 }),
-    entityType: createTextField({ required: true, maxLength: 64 }),
-    // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
-    entityId: createTextField({ required: true, maxLength: 128 }),
-  },
-});
+export function createTagAssignmentEntity(access?: EntityDefinition["access"]) {
+  return createEntity({
+    table: "read_tag_assignments",
+    softDelete: true,
+    access,
+    fields: {
+      tagId: createTextField({ required: true, maxLength: 64 }),
+      entityType: createTextField({ required: true, maxLength: 64 }),
+      // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+      entityId: createTextField({ required: true, maxLength: 128 }),
+    },
+  });
+}
+
+export const tagAssignmentEntity = createTagAssignmentEntity();

package/src/tags/feature.ts

@@ -24,10 +24,12 @@ import {
   defineEntityListHandler,
   defineEntityUpdateHandler,
   defineFeature,
+  type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { hasWhereRule } from "../shared";
 import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./constants";
-import { tagAssignmentEntity, tagEntity } from "./entity";
+import { createTagAssignmentEntity, tagEntity } from "./entity";
 import { createAssignTagHandler } from "./handlers/assign-tag.write";
 import { createCreateTagHandler } from "./handlers/create-tag.write";
 import { createDeleteTagHandler } from "./handlers/delete-tag.write";
@@ -48,6 +50,7 @@ function registerTags(
   r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>,
   access: AccessRule,
   toggleable: TagsToggleable | undefined,
+  ownership: EntityDefinition["access"] | undefined,
 ): void {
   r.describe(
     "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
@@ -62,6 +65,7 @@ function registerTags(
   // feature toggleable lets tier-engine/feature-toggles cut it per tenant.
   if (toggleable !== undefined) r.toggleable(toggleable);
 
+  const tagAssignmentEntity = createTagAssignmentEntity(ownership);
   r.entity("tag", tagEntity);
   r.entity("tag-assignment", tagAssignmentEntity);
 
@@ -91,7 +95,7 @@ function registerTags(
 }
 
 export const tagsFeature = defineFeature(TAGS_FEATURE_NAME, (r) =>
-  registerTags(r, DEFAULT_TAG_ACCESS, undefined),
+  registerTags(r, DEFAULT_TAG_ACCESS, undefined, undefined),
 );
 
 export type TagsFeatureOptions = {
@@ -107,6 +111,23 @@ export type TagsFeatureOptions = {
    *  `default` applies when no toggle/tier override exists — use { default: false }
    *  for fail-closed tier-gating. Omit to keep tags always-on (default). */
   readonly toggleable?: TagsToggleable;
+  /** Row-level ownership on the tag-assignment rows themselves — orthogonal to
+   *  `access`, which only gates whether a caller may dispatch assign/remove/list
+   *  at all. Set `ownership.read` to close the read leak: without it — even if
+   *  `ownership.write` is set — `access.read` stays undefined and any
+   *  dispatch-eligible user can read every assignment in the tenant, including
+   *  assignments on entities they can't otherwise see. Applies only to
+   *  `tag-assignment`; the `tag` catalog stays tenant-wide by design.
+   *
+   *  `ownership.write` is separate and does NOT affect list/read. It's
+   *  consulted by the framework's generic delete/forget/restore paths (not by
+   *  this feature's own assign-tag handler — see createTagsFeature's
+   *  boot-guard comment). A `from()` rule there also gates GDPR erasure
+   *  (`forget`): if the rule's role map doesn't cover whatever role the
+   *  erasure/retention pipeline runs as, `forget` denies instead of
+   *  crypto-shredding — a silent Art.17 failure, not a thrown error. Make
+   *  sure any `ownership.write` you set covers that role, or leave it unset. */
+  readonly ownership?: EntityDefinition["access"];
 };
 
 function resolveAccess(opts: TagsFeatureOptions): AccessRule {
@@ -116,11 +137,29 @@ function resolveAccess(opts: TagsFeatureOptions): AccessRule {
 }
 
 // Backwards-compat / options wrapper. Without options returns the module-level
-// singleton (no rebuild). access/roles/toggleable build a fresh feature-definition.
+// singleton (no rebuild). access/roles/toggleable/ownership build a fresh
+// feature-definition.
 export function createTagsFeature(opts: TagsFeatureOptions = {}): typeof tagsFeature {
-  if (opts.access === undefined && opts.roles === undefined && opts.toggleable === undefined) {
+  if (
+    opts.access === undefined &&
+    opts.roles === undefined &&
+    opts.toggleable === undefined &&
+    opts.ownership === undefined
+  ) {
     return tagsFeature;
   }
+  if (hasWhereRule(opts.ownership?.write)) {
+    throw new Error(
+      "createTagsFeature({ ownership }): ownership.write must not contain a " +
+        '`{ kind: "where" }` rule — where-rules are evaluated only at the SQL ' +
+        "layer (the read path, via buildOwnershipClause). Write paths that " +
+        "consult access.write (userCanCreateFieldRow/userCanWriteFieldRow) can't " +
+        "evaluate them: create throws at runtime, update/delete/forget/restore " +
+        "silently deny. Use a `from()` rule for ownership.write, or leave it unset.",
+    );
+  }
   const access = resolveAccess(opts);
-  return defineFeature(TAGS_FEATURE_NAME, (r) => registerTags(r, access, opts.toggleable));
+  return defineFeature(TAGS_FEATURE_NAME, (r) =>
+    registerTags(r, access, opts.toggleable, opts.ownership),
+  );
 }