@cosmicdrift/kumiko-bundled-features 0.257.0 → 0.258.0

package/src/folders/__tests__/folders-read-gate.integration.test.ts

@@ -0,0 +1,179 @@
+// The read twin of folders-parent-visibility.integration.test.ts (fw#2766).
+// set-folder/clear-folder were gated against the host row's own read path, but
+// `folder-assignment:list` returned every membership row of the tenant — and
+// unlike tags/notes, folders had no `ownership` option at all, so there was no
+// opt-in lever either. The gate below is default-on.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { FoldersHandlers, FoldersQueries } from "../constants";
+import { folderAssignmentEntity, folderEntity } from "../entity";
+import { createFoldersFeature } from "../feature";
+
+const PROJECT_TABLE = "folders_rg_test_projects";
+
+const teamScopedRead: NonNullable<EntityDefinition["access"]> = {
+  read: {
+    TenantMember: {
+      kind: "where",
+      where: (user, ctx) => ({
+        sqlText: `${ctx.tableName}.team_id = $${ctx.paramStart}`,
+        params: [user.claims?.["team"] ?? null],
+      }),
+    },
+  },
+};
+
+const projectEntity = createEntity({
+  table: PROJECT_TABLE,
+  fields: {
+    teamId: createTextField({
+      required: true,
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+    }),
+  },
+  access: teamScopedRead,
+});
+
+const hostFixturesFeature = defineFeature("folders-rg-test-fixtures", (r) => {
+  r.entity("project", projectEntity);
+});
+
+type TestUser = ReturnType<typeof createTestUser>;
+
+const userA: TestUser = createTestUser({
+  id: 90,
+  roles: ["TenantMember"],
+  claims: { team: "team-a" },
+});
+const userB: TestUser = createTestUser({
+  id: 91,
+  roles: ["TenantMember"],
+  claims: { team: "team-b" },
+});
+
+const PROJECT_A = "e0000000-0000-4000-8000-00000000000a";
+const PROJECT_B = "e0000000-0000-4000-8000-00000000000b";
+const ORPHAN_HOST_ID = "e0000000-0000-4000-8000-0000000000ff";
+
+type AssignmentRow = { id: string; folderId: string; entityType: string; entityId: string };
+type Page = { rows: readonly AssignmentRow[]; nextCursor: string | null; total?: number };
+
+let stack: TestStack;
+let folderId: string;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createFoldersFeature({ access: { openToAll: true } }), hostFixturesFeature],
+  });
+  await unsafeCreateEntityTable(stack.db, folderEntity);
+  await unsafeCreateEntityTable(stack.db, folderAssignmentEntity);
+  await unsafeCreateEntityTable(stack.db, projectEntity);
+  await createEventsTable(stack.db);
+
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id) VALUES ($1, $3, 'team-a'), ($2, $3, 'team-b')`,
+    [PROJECT_A, PROJECT_B, userA.tenantId],
+  );
+
+  const folder = await stack.http.writeOk<{ id: string }>(
+    FoldersHandlers.createFolder,
+    { name: "Shared" },
+    userA,
+  );
+  folderId = folder.id;
+
+  await stack.http.writeOk(
+    FoldersHandlers.setFolder,
+    { folderId, entityType: "project", entityId: PROJECT_A },
+    userA,
+  );
+  await stack.http.writeOk(
+    FoldersHandlers.setFolder,
+    { folderId, entityType: "project", entityId: PROJECT_B },
+    userB,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function listAssignments(payload: Record<string, unknown>, user: TestUser): Promise<Page> {
+  return stack.http.queryOk<Page>(FoldersQueries.assignmentList, payload, user);
+}
+
+describe("folders read-gate", () => {
+  test("the owning team sees which folder its own project sits in", async () => {
+    const page = await listAssignments(
+      { filter: { field: "entityId", op: "eq", value: PROJECT_A } },
+      userA,
+    );
+    expect(page.rows).toHaveLength(1);
+    expect(page.rows[0]?.entityId).toBe(PROJECT_A);
+  });
+
+  test("a foreign team sees nothing there — folders never had an ownership opt-in", async () => {
+    const page = await listAssignments(
+      { filter: { field: "entityId", op: "eq", value: PROJECT_A }, totalCount: true },
+      userB,
+    );
+    expect(page.rows).toHaveLength(0);
+    expect(page.total).toBe(0);
+  });
+
+  test("listing a folder's contents shows only hosts the caller can read", async () => {
+    const forA = await listAssignments(
+      { filter: { field: "folderId", op: "eq", value: folderId }, totalCount: true },
+      userA,
+    );
+    expect(forA.rows.map((r) => r.entityId)).toEqual([PROJECT_A]);
+    expect(forA.total).toBe(1);
+
+    const forB = await listAssignments(
+      { filter: { field: "folderId", op: "eq", value: folderId }, totalCount: true },
+      userB,
+    );
+    expect(forB.rows.map((r) => r.entityId)).toEqual([PROJECT_B]);
+    expect(forB.total).toBe(1);
+  });
+
+  test("an assignment whose entityType names no registered entity is invisible to everyone", async () => {
+    const orphanId = "e0000000-0000-4000-8000-0000000000f1";
+    await asRawClient(stack.db).unsafe(
+      `INSERT INTO read_folder_assignments (id, tenant_id, folder_id, entity_type, entity_id, is_deleted)
+       VALUES ($1, $2, $3, 'not-a-registered-entity', $4, FALSE)`,
+      [orphanId, userA.tenantId, folderId, ORPHAN_HOST_ID],
+    );
+
+    for (const user of [userA, userB]) {
+      const page = await listAssignments(
+        { filter: { field: "entityId", op: "eq", value: ORPHAN_HOST_ID }, totalCount: true },
+        user,
+      );
+      expect(page.rows).toHaveLength(0);
+      expect(page.total).toBe(0);
+    }
+
+    const raw = await asRawClient(stack.db).unsafe<{ n: number }>(
+      "SELECT count(*)::int AS n FROM read_folder_assignments WHERE id = $1",
+      [orphanId],
+    );
+    expect(raw[0]?.n).toBe(1);
+  });
+});

package/src/folders/entity.ts

@@ -1,4 +1,8 @@
-import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createTextField,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 // folder — per-tenant hierarchical catalog. Event-sourced (create/update/delete
 // via the standard executor); the framework projects `read_folders` from its own
@@ -39,30 +43,45 @@ export const folderEntity = createEntity({
 // Cross-entity views compose in the read-layer (no JOIN):
 //   - folder of an entity  → list assignments filter { field: "entityId", op: "eq" }
 //   - entities in a folder  → list assignments filter { field: "folderId", op: "eq" }
-export const folderAssignmentEntity = createEntity({
-  table: "read_folder_assignments",
-  description:
-    "The membership row recording which folder one host entity, addressed by entityType and entityId, is filed in. At most one row exists per entity, so filing it elsewhere changes this row's folderId rather than adding a second.",
-  softDelete: true,
-  fields: {
-    folderId: createTextField({
-      required: true,
-      maxLength: 64,
-      personal: false,
-      reason: "technical_reference",
-    }),
-    entityType: createTextField({
-      required: true,
-      maxLength: 64,
-      personal: false,
-      reason: "technical_reference",
-    }),
-    // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
-    entityId: createTextField({
-      required: true,
-      maxLength: 128,
-      personal: false,
-      reason: "technical_reference",
-    }),
-  },
-});
+export function createFolderAssignmentEntity(
+  access?: EntityDefinition["access"],
+  parents?: readonly string[],
+) {
+  return createEntity({
+    table: "read_folder_assignments",
+    description:
+      "The membership row recording which folder one host entity, addressed by entityType and entityId, is filed in. At most one row exists per entity, so filing it elsewhere changes this row's folderId rather than adding a second.",
+    softDelete: true,
+    access,
+    // Declared unconditionally: the host-visibility gate is the default for
+    // both paths, and `parents` only narrows which hosts are admissible.
+    parentRef: {
+      entityTypeField: "entityType",
+      entityIdField: "entityId",
+      ...(parents !== undefined && { allowedTypes: parents }),
+    },
+    fields: {
+      folderId: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      entityType: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+      entityId: createTextField({
+        required: true,
+        maxLength: 128,
+        personal: false,
+        reason: "technical_reference",
+      }),
+    },
+  });
+}
+
+export const folderAssignmentEntity = createFolderAssignmentEntity();

package/src/folders/feature.ts

@@ -22,10 +22,12 @@ import {
   defineEntityListHandler,
   defineEntityUpdateHandler,
   defineFeature,
+  type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { hasWhereRule } from "../shared";
 import { DEFAULT_FOLDER_ACCESS, FOLDERS_FEATURE_NAME } from "./constants";
-import { folderAssignmentEntity, folderEntity } from "./entity";
+import { createFolderAssignmentEntity, folderEntity } from "./entity";
 import { createClearFolderHandler } from "./handlers/clear-folder.write";
 import { createDeleteFolderHandler } from "./handlers/delete-folder.write";
 import { createSetFolderHandler } from "./handlers/set-folder.write";
@@ -41,6 +43,8 @@ function registerFolders(
   r: FeatureRegistrar<typeof FOLDERS_FEATURE_NAME>,
   access: AccessRule,
   toggleable: FoldersToggleable | undefined,
+  ownership: EntityDefinition["access"] | undefined,
+  parents: readonly string[] | undefined,
 ): void {
   r.describe(
     "Generic, host-agnostic hierarchical folders for any entity. Owns two event-sourced entities — the per-tenant `folder` tree (`read_folders`, self-referential via parentId) and SINGLE-membership `folder-assignment` rows keyed by (entityType, entityId) (`read_folder_assignments`) — so filing an entity adds NO column to the host and needs no relational pivot or JOIN. The folder catalog uses the generic entity handlers (create, update [= rename, optimistic-locked], delete, list, detail); set-folder puts/moves an entity into a folder (one folder per entity) and clear-folder unfiles it (both idempotent). Read which folder an entity is in, or which entities a folder holds, by listing `folder-assignment` filtered on `entityId` or `folderId`. Every path uses one access rule — adopt the host's model with createFoldersFeature({ access: { openToAll: true } }) or pin roles. Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
@@ -53,6 +57,7 @@ function registerFolders(
 
   if (toggleable !== undefined) r.toggleable(toggleable);
 
+  const folderAssignmentEntity = createFolderAssignmentEntity(ownership, parents);
   r.entity("folder", folderEntity);
   r.entity("folder-assignment", folderAssignmentEntity);
 
@@ -103,7 +108,7 @@ function registerFolders(
 }
 
 export const foldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) =>
-  registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined),
+  registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined, undefined, undefined),
 );
 
 export type FoldersFeatureOptions = {
@@ -119,6 +124,28 @@ export type FoldersFeatureOptions = {
    *  `default` applies when no toggle/tier override exists — use { default: false }
    *  for fail-closed tier-gating. Omit to keep folders always-on (default). */
   readonly toggleable?: FoldersToggleable;
+  /** Row-level ownership on the folder-assignment rows themselves — orthogonal
+   *  to `access`, which only gates whether a caller may dispatch set/clear/list
+   *  at all. Not needed to keep a caller from reading assignments on host
+   *  entities they can't see: that gate is default-on since fw#2766 and derives
+   *  from the entity's `parentRef`. Use `ownership.read` for an ADDITIONAL row
+   *  rule on the assignment row itself; it is AND-ed with the host-visibility
+   *  gate. Applies only to `folder-assignment`; the `folder` 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. 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"];
+  /** Allowlist narrowing which registered entities may be filed into a folder.
+   *  Not what turns host-checking on — set/clear and the assignment list always
+   *  verify that entityType names a registered entity whose row the caller can
+   *  see. Setting it narrows further, and shrinks the read gate's SQL, which
+   *  otherwise considers every registered entity as a candidate host. */
+  readonly parents?: readonly string[];
 };
 
 function resolveAccess(opts: FoldersFeatureOptions): AccessRule {
@@ -130,9 +157,36 @@ function resolveAccess(opts: FoldersFeatureOptions): AccessRule {
 // Options wrapper. Without options returns the module-level singleton (no
 // rebuild). access/roles/toggleable build a fresh feature-definition.
 export function createFoldersFeature(opts: FoldersFeatureOptions = {}): typeof foldersFeature {
-  if (opts.access === undefined && opts.roles === undefined && opts.toggleable === undefined) {
+  if (
+    opts.access === undefined &&
+    opts.roles === undefined &&
+    opts.toggleable === undefined &&
+    opts.ownership === undefined &&
+    opts.parents === undefined
+  ) {
     return foldersFeature;
   }
+  if (hasWhereRule(opts.ownership?.write)) {
+    throw new Error(
+      "createFoldersFeature({ 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, so such a rule can only ever deny — boot validation " +
+        "rejects it too (fw#2626). Use a `from()` rule for ownership.write, or " +
+        "leave it unset.",
+    );
+  }
+  if (opts.parents !== undefined && opts.parents.length === 0) {
+    throw new Error(
+      "createFoldersFeature({ parents }): parents must not be an empty array — " +
+        "an empty allowlist rejects every set-folder call and hides every " +
+        "assignment row. Omit `parents` to keep every registered entity " +
+        "admissible as a host instead.",
+    );
+  }
   const access = resolveAccess(opts);
-  return defineFeature(FOLDERS_FEATURE_NAME, (r) => registerFolders(r, access, opts.toggleable));
+  return defineFeature(FOLDERS_FEATURE_NAME, (r) =>
+    registerFolders(r, access, opts.toggleable, opts.ownership, opts.parents),
+  );
 }

package/src/folders/handlers/clear-folder.write.ts

@@ -1,6 +1,6 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { parentRowIsVisible } from "../../shared";
+import { joinRowParentIsVisible } from "../../shared";
 import { folderAssignmentAggregateId } from "../aggregate-id";
 import { DEFAULT_FOLDER_ACCESS } from "../constants";
 import { folderAssignmentExecutor } from "../executor";
@@ -31,10 +31,10 @@ export function createClearFolderHandler(
       // an invisible parent apart from a missing assignment or an unknown folder —
       // every path answers with the same NotFoundError.
       if (
-        !(await parentRowIsVisible(
+        !(await joinRowParentIsVisible(
           ctx.registry,
-          payload.entityType,
-          payload.entityId,
+          "folder-assignment",
+          payload,
           event.user,
           ctx.db,
         ))

package/src/folders/handlers/set-folder.write.ts

@@ -1,6 +1,6 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { parentRowIsVisible } from "../../shared";
+import { joinRowParentIsVisible } from "../../shared";
 import { folderAssignmentAggregateId } from "../aggregate-id";
 import { DEFAULT_FOLDER_ACCESS } from "../constants";
 import { folderAssignmentExecutor, folderExecutor } from "../executor";
@@ -47,10 +47,10 @@ export function createSetFolderHandler(
       // an invisible parent apart from a missing assignment or an unknown folder —
       // every path answers with the same NotFoundError.
       if (
-        !(await parentRowIsVisible(
+        !(await joinRowParentIsVisible(
           ctx.registry,
-          payload.entityType,
-          payload.entityId,
+          "folder-assignment",
+          payload,
           event.user,
           ctx.db,
         ))

package/src/notes-history/__tests__/add-note-author-name-kms.integration.test.ts

@@ -34,7 +34,7 @@ import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testin
 import { userEntity, userTable } from "../../user/schema/user";
 import { seedUser } from "../../user/seeding";
 import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
-import { noteEntryEntity } from "../entity";
+import { noteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 const notesHistoryFeature = createNotesHistoryFeature();
@@ -66,6 +66,7 @@ function memberUser(userId: string): SessionUser {
 beforeAll(async () => {
   stack = await setupTestStack({ features: [notesHistoryFeature, contactFixtureFeature] });
   await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(stack.db, noteMentionEntity);
   await unsafeCreateEntityTable(stack.db, userEntity);
   await unsafeCreateEntityTable(stack.db, contactEntity);
   await asRawClient(stack.db).unsafe(

package/src/notes-history/__tests__/notes-history-ownership.integration.test.ts

@@ -35,7 +35,7 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
-import { createNoteEntryEntity, noteEntryEntity } from "../entity";
+import { createNoteEntryEntity, noteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 // Minimal fixture standing in for a real host projection: which team a host
@@ -123,6 +123,7 @@ beforeAll(async () => {
     features: [createNotesHistoryFeature({ ownership: teamOwnership }), projectFixtureFeature],
   });
   await unsafeCreateEntityTable(scopedStack.db, createNoteEntryEntity(teamOwnership));
+  await unsafeCreateEntityTable(scopedStack.db, noteMentionEntity);
   await unsafeCreateEntityTable(scopedStack.db, projectEntity);
   await createEventsTable(scopedStack.db);
   await asRawClient(scopedStack.db).unsafe(
@@ -138,6 +139,7 @@ beforeAll(async () => {
     features: [createNotesHistoryFeature(), projectFixtureFeature],
   });
   await unsafeCreateEntityTable(defaultStack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(defaultStack.db, noteMentionEntity);
   await unsafeCreateEntityTable(defaultStack.db, projectEntity);
   await createEventsTable(defaultStack.db);
   await insertProjects(defaultStack, userA.tenantId, [PROJ_1]);
@@ -286,6 +288,7 @@ describe("unqualified where-rule fails closed, not open (fw#2639)", () => {
       ],
     });
     await unsafeCreateEntityTable(unqualifiedStack.db, createNoteEntryEntity(unqualifiedOwnership));
+    await unsafeCreateEntityTable(unqualifiedStack.db, noteMentionEntity);
     await unsafeCreateEntityTable(unqualifiedStack.db, projectEntity);
     await createEventsTable(unqualifiedStack.db);
     await asRawClient(unqualifiedStack.db).unsafe(

package/src/notes-history/__tests__/notes-history-parent-visibility.integration.test.ts

@@ -25,7 +25,7 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { NotesHistoryHandlers } from "../constants";
-import { createNoteEntryEntity } from "../entity";
+import { createNoteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 const PROJECT_TABLE = "notes_pv_test_projects";
@@ -118,6 +118,7 @@ beforeAll(async () => {
   });
   await unsafeCreateEntityTable(guardedStack.db, guardedProjectEntity);
   await unsafeCreateEntityTable(guardedStack.db, createNoteEntryEntity());
+  await unsafeCreateEntityTable(guardedStack.db, noteMentionEntity);
   await createEventsTable(guardedStack.db);
   await asRawClient(guardedStack.db).unsafe(
     `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id, name) VALUES
@@ -134,6 +135,7 @@ beforeAll(async () => {
   });
   await unsafeCreateEntityTable(openStack.db, guardedProjectEntity);
   await unsafeCreateEntityTable(openStack.db, createNoteEntryEntity());
+  await unsafeCreateEntityTable(openStack.db, noteMentionEntity);
   await createEventsTable(openStack.db);
   await asRawClient(openStack.db).unsafe(
     `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id, name) VALUES ($1, $2, 'team-a', 'Project Open')`,

package/src/notes-history/__tests__/notes-history.integration.test.ts

@@ -28,7 +28,7 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
-import { noteEntryEntity } from "../entity";
+import { noteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 const notesHistoryFeature = createNotesHistoryFeature();
@@ -73,6 +73,7 @@ const CONTACT_SHARED = "30000000-0000-4000-8000-000000000007";
 beforeAll(async () => {
   stack = await setupTestStack({ features: [notesHistoryFeature, contactFixtureFeature] });
   await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(stack.db, noteMentionEntity);
   await unsafeCreateEntityTable(stack.db, contactEntity);
   await createEventsTable(stack.db);