@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/examples/ownership.md

@@ -0,0 +1,404 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/ownership. Do not edit. -->
+
+# ownership
+
+Entity- and Field-level Row-Ownership: from() helper, Straddle-safe multi-role checks, Field-level Read/Write filtering.
+
+## README
+
+# Ownership
+
+Row-level ownership for read and write.
+
+## What it shows
+
+- Entity- and field-level ownership rules
+- Straddle-safe checks across tenants/users
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/ownership
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Ownership Sample — Integration Test
+//
+// Drives the whole Read/Write × Entity/Field matrix against the contract
+// feature. Each test maps directly to a cell in the design-doc matrix.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { contractEntity, contractsFeature, teamsFeature } from "../feature";
+
+let stack: TestStack;
+
+function usersForTenant(tenant: TenantId) {
+  return {
+    admin: { ...TestUsers.admin, tenantId: tenant },
+    teamMemberEng: createTestUser({
+      id: "11111111-0000-4000-8000-000000000001",
+      tenantId: tenant,
+      roles: ["TeamMember"],
+      claims: { "teams:teamId": "eng" },
+    }),
+    teamMemberOps: createTestUser({
+      id: "11111111-0000-4000-8000-000000000002",
+      tenantId: tenant,
+      roles: ["TeamMember"],
+      claims: { "teams:teamId": "ops" },
+    }),
+    driverAlice: createTestUser({
+      id: "22222222-0000-4000-8000-000000000001",
+      tenantId: tenant,
+      roles: ["Driver"],
+    }),
+  };
+}
+
+// Each test runs in its own tenant, so contract rows from other tests never show up.
+let nextTenant = 1;
+let { admin, teamMemberEng, teamMemberOps, driverAlice } = usersForTenant(testTenantId(nextTenant));
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [teamsFeature, contractsFeature] });
+  await unsafeCreateEntityTable(stack.db, contractEntity, "contract");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+let engRowId: string;
+let engRowVersion: number;
+let opsRowId: string;
+
+beforeEach(async () => {
+  nextTenant += 1;
+  ({ admin, teamMemberEng, teamMemberOps, driverAlice } = usersForTenant(testTenantId(nextTenant)));
+  const eng = await stack.http.writeOk<{ id: string; data: { version: number } }>(
+    "contracts:write:contract:create",
+    {
+      teamId: "eng",
+      assigneeId: driverAlice.id,
+      propA: "public-eng",
+      propB: "admin-eng",
+      propC: "team-eng",
+    },
+    admin,
+  );
+  engRowId = eng.id;
+  engRowVersion = eng.data.version;
+  const ops = await stack.http.writeOk<{ id: string }>(
+    "contracts:write:contract:create",
+    {
+      teamId: "ops",
+      propA: "public-ops",
+      propB: "admin-ops",
+      propC: "team-ops",
+    },
+    admin,
+  );
+  opsRowId = ops.id;
+});
+
+// --- Entity-level READ ---
+
+describe("entity-level read: list / detail filtering", () => {
+  test("Admin lists both rows", async () => {
+    const res = await stack.http.queryOk<{ rows: Array<{ teamId: string }> }>(
+      "contracts:query:contract:list",
+      {},
+      admin,
+    );
+    expect(res.rows).toHaveLength(2);
+  });
+
+  test("TeamMember eng lists only eng's row", async () => {
+    const res = await stack.http.queryOk<{ rows: Array<{ teamId: string }> }>(
+      "contracts:query:contract:list",
+      {},
+      teamMemberEng,
+    );
+    expect(res.rows).toHaveLength(1);
+    expect(res.rows[0]?.teamId).toBe("eng");
+  });
+
+  test("Driver alice lists only rows assigned to her", async () => {
+    const res = await stack.http.queryOk<{ rows: Array<{ assigneeId: string }> }>(
+      "contracts:query:contract:list",
+      {},
+      driverAlice,
+    );
+    expect(res.rows).toHaveLength(1);
+    expect(res.rows[0]?.assigneeId).toBe(driverAlice.id);
+  });
+
+  test("TeamMember eng getting ops row via detail → null (indistinguishable from not-found)", async () => {
+    const res = await stack.http.queryOk(
+      "contracts:query:contract:detail",
+      {
+        id: opsRowId,
+      },
+      teamMemberEng,
+    );
+    expect(res).toBeNull();
+  });
+});
+
+// --- Field-level READ ---
+
+describe("field-level read: response JSON strips unreadable fields", () => {
+  test("TeamMember eng sees propA + propC; propB missing", async () => {
+    const res = await stack.http.queryOk<Record<string, unknown>>(
+      "contracts:query:contract:detail",
+      { id: engRowId },
+      teamMemberEng,
+    );
+    expect(res["propA"]).toBe("public-eng");
+    expect(res["propC"]).toBe("team-eng");
+    expect(res).not.toHaveProperty("propB");
+  });
+
+  test("TeamMember ops reading eng's row — blocked at entity level (detail=null)", async () => {
+    const res = await stack.http.queryOk(
+      "contracts:query:contract:detail",
+      {
+        id: engRowId,
+      },
+      teamMemberOps,
+    );
+    expect(res).toBeNull();
+  });
+});
+
+// --- Entity-level WRITE ---
+
+describe("entity-level write: create/update/delete blocked on foreign rows", () => {
+  test("TeamMember eng CANNOT create an ops-team contract", async () => {
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:create",
+      { teamId: "ops", propA: "rogue" },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "ownership_denied");
+  });
+
+  test("TeamMember eng CANNOT update the ops row (not visible → not modifiable)", async () => {
+    // The row exists but entity-level ownership rejects the update.
+    // version is guessed — doesn't matter, the ownership check fires first.
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:update",
+      { id: opsRowId, version: 1, changes: { propA: "hack" } },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "ownership_denied");
+  });
+
+  test("TeamMember eng CANNOT move their row to another team (teamId rewrite blocked)", async () => {
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:update",
+      {
+        id: engRowId,
+        version: engRowVersion,
+        changes: { teamId: "ops" },
+      },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "ownership_denied");
+  });
+});
+
+// --- Field-level WRITE ---
+
+describe("field-level write: individual fields rejected fail-loud", () => {
+  test("TeamMember eng updating propB (Admin-only) → access_denied (role gate)", async () => {
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:update",
+      {
+        id: engRowId,
+        version: engRowVersion,
+        changes: { propB: "sneak" },
+      },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+
+  test("TeamMember eng updating propA succeeds on their own row", async () => {
+    const res = await stack.http.writeOk<{ data: { propA: string } }>(
+      "contracts:write:contract:update",
+      {
+        id: engRowId,
+        version: engRowVersion,
+        changes: { propA: "my-edit" },
+      },
+      teamMemberEng,
+    );
+    expect(res.data.propA).toBe("my-edit");
+  });
+});
+
+// --- Admin short-circuit ---
+
+describe("admin-all short-circuit skips every ownership predicate", () => {
+  test("Admin reads both rows with all fields intact", async () => {
+    const eng = await stack.http.queryOk<Record<string, unknown>>(
+      "contracts:query:contract:detail",
+      { id: engRowId },
+      admin,
+    );
+    expect(eng["propA"]).toBe("public-eng");
+    expect(eng["propB"]).toBe("admin-eng");
+    expect(eng["propC"]).toBe("team-eng");
+  });
+
+  test("Admin updates, deletes, restores on any team", async () => {
+    const updated = await stack.http.writeOk<{ data: { propB: string; version: number } }>(
+      "contracts:write:contract:update",
+      {
+        id: opsRowId,
+        version: 1,
+        changes: { propB: "admin-edit-across-teams" },
+      },
+      admin,
+    );
+    expect(updated.data.propB).toBe("admin-edit-across-teams");
+    const deleted = await stack.http.writeOk<{ id: string }>(
+      "contracts:write:contract:delete",
+      { id: opsRowId },
+      admin,
+    );
+    expect(deleted.id).toBe(opsRowId);
+    const restored = await stack.http.writeOk<{ id: string }>(
+      "contracts:write:contract:restore",
+      { id: opsRowId },
+      admin,
+    );
+    expect(restored.id).toBe(opsRowId);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Ownership Sample
+//
+// Concrete contract-entity showing the full ownership matrix:
+//
+//   Dimension      Entity-level           Field-level
+//   ---------      ------------           -----------
+//   Read           list/detail filter     propX stripped from response JSON
+//   Write          create/update/delete   individual fields rejected loud
+//   Rule shape     { Role: OwnershipRule } (same on both dimensions)
+//   Rule kinds     "all" / from(ref, col?) / { where: (user, table) => SQL }
+//
+// The entity below is the "contract" example from the H.2 design
+// discussion: propA is public, propB is Admin-only, propC requires a
+// matching team claim. Integration tests prove each row/column path.
+//
+// Why fail-loud on write (not silent drop): Silent-drop makes bugs
+// invisible at the reporting layer. "Save doesn't work" with no error
+// becomes weeks of blame between frontend / API / infrastructure. A loud
+// `field_ownership_denied` with the field name + role + userId in the
+// details payload is a single log-line to a root cause.
+
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  from,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// The "teams" feature declares the teamId claim. Any other feature can
+// reference it via the QN string "teams:teamId" in ownership rules — no
+// cross-feature import needed. The boot-validator rejects a reference to a
+// claim no feature declared.
+export const teamsFeature = defineFeature("teams", (r) => {
+  r.claimKey("teamId", { type: "string" });
+});
+
+// Contract entity demonstrating the full access matrix.
+export const contractEntity = createEntity({
+  table: "read_ownership_contracts",
+  softDelete: true,
+  fields: {
+    // teamId is the ownership-scoping column. It's referenced by claim-rules
+    // via the default column (rule's shortName = "teamId" matches).
+    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    // Optional — when set, only that user (via user:id rule) can access.
+    assigneeId: createTextField({ personal: "ref" }),
+
+    // propA: public field. No access declared — every caller reads AND writes.
+    propA: createTextField({ personal: false, reason: "is_business_data" }),
+
+    // propB: Admin-only. Non-admins don't see it in responses; attempts
+    // to write it return access_denied (role gate in dispatcher).
+    propB: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      access: {
+        read: { Admin: "all" },
+        write: { Admin: "all" },
+      },
+    }),
+
+    // propC: Admin + Matching-Team. Non-admins with the wrong team see no
+    // propC in responses; writes to propC on a foreign team's row return
+    // field_ownership_denied (executor ownership check).
+    propC: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      access: {
+        read: { Admin: "all", TeamMember: from("claim:teams:teamId") },
+        write: { Admin: "all", TeamMember: from("claim:teams:teamId") },
+      },
+    }),
+  },
+
+  // Entity-level access: controls list/detail/update/delete/restore of the
+  // whole row. Admin sees everything; TeamMember scoped to their team;
+  // assigned Driver sees rows assigned to them.
+  access: {
+    read: {
+      Admin: "all",
+      TeamMember: from("claim:teams:teamId"),
+      Driver: from("user:id", "assigneeId"),
+    },
+    write: {
+      Admin: "all",
+      TeamMember: from("claim:teams:teamId"),
+      Driver: from("user:id", "assigneeId"),
+    },
+  },
+});
+
+export const contractsFeature = defineFeature("contracts", (r) => {
+  const contractAccess = { access: { roles: ["Admin", "TeamMember", "Driver"] } } as const;
+  r.crud("contract", contractEntity, {
+    write: contractAccess,
+    read: contractAccess,
+  });
+});
+```