Access Control
Default-deny access rules and FK indices via relations.
What it shows
Section titled “What it shows”- Handler
accessroles as the default-deny gate - Relation-declared FK indices for join-friendly schemas
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/access-controlbun 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):
// Access Control + FK-Indices Sample//// Demonstrates the framework's security + performance defaults://// 1. Default-deny: every handler must declare an access rule. Boot fails// loudly when one is missing. Two shapes:// { roles: ["Admin", ...] } — role allowlist// { openToAll: { reason: "..." } } — any authenticated user, with a required reason//// 2. Foreign-key relations declared via r.relation() become indexed columns// automatically — no manual CREATE INDEX. Inspect the Drizzle table// config in tests to verify.
import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";import { createEntity, createTextField, defineEntityCreateHandler, defineEntityListHandler, defineFeature, defineRoles,} from "@cosmicdrift/kumiko-framework/engine";import { z } from "zod";
// Typed role registry — `defineRoles` returns an object keyed by role name// so access rules can reference `AccessControlRoles.Admin` instead of the// magic string "Admin". Typos become compile errors, renames refactor.export const AccessControlRoles = defineRoles(["Admin"] as const);
export const projectEntity = createEntity({ name: "project", table: "read_ac_projects", fields: { name: createTextField({ personal: false, reason: "is_business_data", required: true }), ownerId: createTextField({ personal: "ref", required: true }), },});
export const taskEntity = createEntity({ name: "task", table: "read_ac_tasks", fields: { title: createTextField({ personal: false, reason: "is_business_data", required: true }), assigneeId: createTextField({ personal: "ref" }), projectId: createTextField({ personal: false, reason: "is_system_identifier", required: true }), },});
// The "owner" relation points at a hypothetical external `user` entity — in// a real app this would be @cosmicdrift/kumiko-bundled-features/user. For the sample we// keep it internal: projectRelations only holds FK metadata (no cross-entity// resolution) so the sample stays self-contained.export const projectRelations = {} as const;
export const taskRelations = { project: { type: "belongsTo", target: "project", foreignKey: "projectId" },} as const;
// Relations flow into buildEntityTable — every belongsTo FK gets its own// index on this table.export const projectTable = buildEntityTable(projectEntity, { relations: projectRelations,});export const taskTable = buildEntityTable(taskEntity, { relations: taskRelations,});
export const accessControlFeature = defineFeature("access-control", (r) => { r.entity(projectEntity); r.entity(taskEntity); r.relation({ entity: "task", name: "project", ...taskRelations.project });
// Admin-only: standard create — no business logic, helper handles schema + // executor + handler-body. r.writeHandler( defineEntityCreateHandler("project", projectEntity, { access: { roles: [AccessControlRoles.Admin] }, }), );
// Custom create: assigneeId defaults to the caller when omitted, so we // hand-write this handler instead of using the helper. The framework helpers // are deliberately scope-limited — opt out the moment you need defaults. const taskExecutor = createEventStoreExecutor(taskTable, taskEntity, { entityName: "task" }); r.writeHandler({ name: "task:create", schema: z.object({ title: z.string().min(1), projectId: z.uuid(), assigneeId: z.uuid().optional(), }), handler: async (event, ctx) => taskExecutor.create( { ...event.payload, assigneeId: event.payload.assigneeId ?? event.user.id, }, event.user, ctx.db, ), access: { openToAll: { reason: "any signed-in tenant user may create a task; assigneeId defaults to the caller when omitted", }, }, });
// Update requires version — optimistic locking is the default and this // narrowed schema (only title + assigneeId mutable) is stricter than the // helper's generic update schema, so we keep it hand-written. r.writeHandler({ name: "task:update", schema: z.object({ id: z.uuid(), version: z.number(), changes: z.object({ title: z.string().min(1).optional(), assigneeId: z.uuid().optional(), }), }), handler: async (event, ctx) => taskExecutor.update(event.payload, event.user, ctx.db), access: { openToAll: { reason: "any signed-in tenant user may update a task; optimistic locking (version) " + "guards against concurrent overwrites, not caller identity", }, }, });
// Self-service list — no custom logic. r.queryHandler( defineEntityListHandler("task", taskEntity, { access: { openToAll: { reason: "any signed-in tenant user may list tasks; there is no per-user filter in this recipe", }, }, }), );});📄 On GitHub: samples/recipes/access-control/src/feature.ts