Ownership
Row-level ownership for read and write.
What it shows
Section titled “What it shows”- Entity- and field-level ownership rules
- Straddle-safe checks across tenants/users
fromParent(field, entity) lets a child entity inherit ownership instead of copying the scoping column: the contractNote entity grants a TeamMember exactly the notes whose contractId points at a contract that role may read (list, detail) or write (create, update, delete) under the contract’s own access map.
Source
Section titled “Source”Feature entry point: src/feature.ts.
Needs the Postgres from the repo root’s docker-compose.yml (docker compose up -d); TEST_DATABASE_URL defaults to postgresql://kumiko:kumiko@localhost:15432/kumiko_test.
cd samples/recipes/ownershipbun testSource code
Section titled “Source code”The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):
// 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, createReferenceField, createTextField, defineFeature, from, fromParent,} 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({ name: "teamId", type: "string" });});
// Contract entity demonstrating the full access matrix.export const contractEntity = createEntity({ name: "contract", 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"), }, },});
// A note has no teamId of its own: fromParent grants a TeamMember the notes whose contract that// same role may read (and write), so the scoping column is not copied into every child.export const contractNoteEntity = createEntity({ name: "contractNote", table: "read_ownership_contract_notes", fields: { contractId: createReferenceField({ entity: "contract", personal: false, reason: "is_system_identifier", required: true, }), text: createTextField({ personal: false, reason: "is_business_data", required: true }), }, access: { read: { Admin: "all", TeamMember: fromParent("contractId", "contract") }, write: { Admin: "all", TeamMember: fromParent("contractId", "contract") }, },});
export const contractsFeature = defineFeature("contracts", (r) => { const contractAccess = { access: { roles: ["Admin", "TeamMember", "Driver"] } } as const; r.crud(contractEntity, { write: contractAccess, read: contractAccess, }); const noteAccess = { access: { roles: ["Admin", "TeamMember"] } } as const; r.crud(contractNoteEntity, { write: noteAccess, read: noteAccess, });});📄 On GitHub: samples/recipes/ownership/src/feature.ts