@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/examples/access-control.md

@@ -0,0 +1,355 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/access-control. Do not edit. -->
+
+# access-control
+
+Default-deny access rules, openToAll vs. role-based handlers, and auto-indices for foreign keys.
+
+## README
+
+# Access Control
+
+Default-deny access rules and FK indices via relations.
+
+## What it shows
+
+- Handler `access` roles as the default-deny gate
+- Relation-declared FK indices for join-friendly schemas
+
+## 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/access-control
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import {
+  accessControlFeature,
+  projectEntity,
+  projectTable,
+  taskEntity,
+  taskTable,
+} from "../feature";
+
+let stack: TestStack;
+const admin = TestUsers.admin; // { id: 1, tenantId: 1, roles: ["Admin"] }
+const user = TestUsers.user; // { id: 2, tenantId: 1, roles: ["User"] }
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [accessControlFeature] });
+  await unsafeCreateEntityTable(stack.db, projectEntity);
+  await unsafeCreateEntityTable(stack.db, taskEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack?.cleanup();
+});
+
+describe("default-deny: refuses handlers without access", () => {
+  test("throws at registration when a handler lacks an access rule", () => {
+    // `access` is required since fw#2855 — the registrar throws before validateBoot ever runs.
+    expect(() =>
+      defineFeature("broken-feature", (r) => {
+        // @ts-expect-error — No { access: ... }: registration must reject this.
+        r.writeHandler("forgotAccess", z.object({ name: z.string() }), async () => ({
+          isSuccess: true as const,
+          data: {},
+        }));
+      }),
+    ).toThrow(/requires schema \+ handler \+ options\.access/);
+  });
+});
+
+describe("role-based vs openToAll", () => {
+  test("Admin-only handler rejects a User caller with access_denied", async () => {
+    const raw = await stack.http.write(
+      "access-control:write:project:create",
+      { name: "Rejected", ownerId: "11111111-0000-4000-8000-000000000001" },
+      user,
+    );
+    const body = (await raw.json()) as { isSuccess: boolean; error?: { code: string } };
+    expect(body.isSuccess).toBe(false);
+    expect(body.error?.code).toBe("access_denied");
+  });
+
+  test("Admin-only handler accepts an Admin caller", async () => {
+    await stack.http.writeOk(
+      "access-control:write:project:create",
+      { name: "Alpha", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+  });
+
+  test("openToAll handler accepts any authenticated user", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "Shared", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+    await stack.http.writeOk(
+      "access-control:write:task:create",
+      { title: "User's task", projectId: proj.data.id },
+      user,
+    );
+  });
+});
+
+describe("auto-indices from relations", () => {
+  test("task table has an index on project_id because of the belongsTo relation", () => {
+    const names = taskTable.indexes.map((i) => i.name);
+
+    expect(names).toContain("read_ac_tasks_tenant_id_idx");
+    expect(names).toContain("read_ac_tasks_project_id_idx");
+  });
+
+  test("project table has only the tenant_id index (no belongsTo relations)", () => {
+    expect(projectTable.indexes.map((i) => i.name)).toEqual(["read_ac_projects_tenant_id_idx"]);
+  });
+});
+
+describe("optimistic locking: version required in update schema", () => {
+  test("update without version fails schema validation before reaching the crud executor", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "VersionedProject", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+    const created = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:task:create",
+      { title: "Needs version", projectId: proj.data.id },
+      user,
+    );
+
+    const raw = await stack.http.write(
+      "access-control:write:task:update",
+      // Missing `version` — schema rejects before any DB call.
+      { id: created.data.id, changes: { title: "Updated" } },
+      user,
+    );
+    const body = (await raw.json()) as { isSuccess: boolean; error?: { code: string } };
+    expect(body.isSuccess).toBe(false);
+    expect(body.error?.code).toBe("validation_error");
+  });
+
+  test("update with correct version succeeds", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "VersionedOk", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+    const created = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:task:create",
+      { title: "Task v1", projectId: proj.data.id },
+      user,
+    );
+
+    await stack.http.writeOk(
+      "access-control:write:task:update",
+      { id: created.data.id, version: 1, changes: { title: "Task v2" } },
+      user,
+    );
+  });
+});
+
+// Ensures this sample is wired through the full stack — if any of its
+// handlers regress to missing access or broken schemas, boot or this list
+// query will fail loudly.
+describe("end-to-end", () => {
+  test("list returns seeded tasks across users", async () => {
+    const proj = await stack.http.writeOk<{ data: { id: string } }>(
+      "access-control:write:project:create",
+      { name: "ListTarget", ownerId: "11111111-0000-4000-8000-000000000001" },
+      admin,
+    );
+
+    await stack.http.writeOk(
+      "access-control:write:task:create",
+      { title: "t1", projectId: proj.data.id },
+      user,
+    );
+    await stack.http.writeOk(
+      "access-control:write:task:create",
+      { title: "t2", projectId: proj.data.id },
+      admin,
+    );
+
+    const list = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "access-control:query:task:list",
+      {},
+      user,
+    );
+    expect(list.rows.length).toBeGreaterThanOrEqual(2);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// 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({
+  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({
+  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("project", projectEntity, {
+  relations: projectRelations,
+});
+export const taskTable = buildEntityTable("task", taskEntity, {
+  relations: taskRelations,
+});
+
+export const accessControlFeature = defineFeature("access-control", (r) => {
+  r.entity("project", projectEntity);
+  r.entity("task", taskEntity);
+  r.relation("task", "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(
+    "task:create",
+    z.object({
+      title: z.string().min(1),
+      projectId: z.uuid(),
+      assigneeId: z.uuid().optional(),
+    }),
+    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(
+    "task:update",
+    z.object({
+      id: z.uuid(),
+      version: z.number(),
+      changes: z.object({
+        title: z.string().min(1).optional(),
+        assigneeId: z.uuid().optional(),
+      }),
+    }),
+    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",
+        },
+      },
+    }),
+  );
+});
+```