@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/anonymous-access.md

@@ -0,0 +1,300 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/anonymous-access. Do not edit. -->
+
+# anonymous-access
+
+Public endpoints (anonymous role) for shop / CMS-style apps. Tenant resolution via header, cookie, or default.
+
+## README
+
+# Anonymous Access
+
+Public endpoints without a logged-in user.
+
+## What it shows
+
+- `access: "anonymous"` on handlers that must stay public
+- Rate limits that still bind anonymous callers (`per: "ip+handler"`)
+
+## 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/anonymous-access
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Single-tenant shop wiring: defaultTenantId is the simplest setup. No
+// resolver, no header, no cookie — anonymous requests just work. Suitable
+// for WordPress-clones, SaaS landing pages, and standalone shops.
+//
+// For multi-tenant deployments, swap defaultTenantId for a tenantResolver
+// that parses the host (acme.shop.com → tenantId) plus a tenantExists
+// callback that confirms the tenant is real (against DB or cache).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { ANONYMOUS_USER_ID, type TenantId } 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 {
+  anonymousAccessFeature,
+  guestOrderEntity,
+  guestOrderTable,
+  productEntity,
+  productTable,
+} from "../feature";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [anonymousAccessFeature],
+    // The single-tenant shortcut: every anonymous request lands on this
+    // tenant. No header, cookie, or resolver needed.
+    anonymousAccess: { defaultTenantId: TENANT_ID },
+  });
+  await unsafeCreateEntityTable(stack.db, productEntity);
+  await unsafeCreateEntityTable(stack.db, guestOrderEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack?.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${productTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${guestOrderTable.tableName}"`);
+});
+
+describe("public read: anonymous + authenticated share the listing", () => {
+  test("anonymous caller sees products without any auth headers", async () => {
+    await stack.http.writeOk(
+      "shop:write:product:create",
+      { name: "Espresso Beans", priceCents: "1500" },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "shop:query:product:list",
+      payload: {},
+    });
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: Array<{ name: string }> };
+    expect(body.data).toHaveLength(1);
+    expect(body.data[0]?.name).toBe("Espresso Beans");
+  });
+
+  test("authenticated user reaches the same handler via JWT", async () => {
+    await stack.http.writeOk(
+      "shop:write:product:create",
+      { name: "Espresso Beans", priceCents: "1500" },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.query("shop:query:product:list", {}, TestUsers.user);
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("guest checkout: anonymous write lands with placedBy=anonymous", () => {
+  test("anonymous order is stored and tagged with the anonymous user-id", async () => {
+    await stack.http.writeOk(
+      "shop:write:product:create",
+      { name: "Espresso Beans", priceCents: "1500" },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "shop:write:guest-order:place",
+      payload: {
+        productId: "00000000-0000-4000-8000-000000000099",
+        email: "guest@example.com",
+      },
+    });
+
+    expect(res.status).toBe(200);
+
+    const orders = await selectMany(stack.db, guestOrderTable);
+    expect(orders).toHaveLength(1);
+    expect(orders[0]?.placedBy).toBe(ANONYMOUS_USER_ID);
+    expect(orders[0]?.email).toBe("guest@example.com");
+  });
+});
+
+describe("regression guards", () => {
+  test("openToAll handler rejects anonymous (was the silent-public bug)", async () => {
+    // Enabling anonymousAccess must NOT turn every existing openToAll endpoint
+    // public. hasAccess rejects anonymous on openToAll, and the dispatcher
+    // answers 401: the caller has to sign in, not ask for another role.
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "shop:query:product:authenticated-only",
+      payload: {},
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("admin-only handler rejects anonymous", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "shop:write:product:create",
+      payload: { name: "Tea Set", priceCents: "1000" },
+    });
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Anonymous-Access Sample
+//
+// Most Kumiko apps put every endpoint behind a JWT — fine for CRMs, ERPs,
+// and back-office tools where every caller is a known user. Shops, CMSs,
+// marketing-microsites have a different shape: 50%+ of traffic is anonymous
+// (visitors, scrapers, search engines) and the public surface is a feature,
+// not a hack.
+//
+// This recipe wires that public surface in two ways:
+//
+//  1. `roles: ["anonymous"]` on a handler → unauthenticated callers reach it.
+//     The framework synthesises a SessionUser with id="anonymous" + that
+//     single role. `access.anonymous` is the typed shorthand for the role.
+//
+//  2. Combined with authenticated roles → the same handler serves both
+//     audiences, with the handler-body branching on `event.user.id` if
+//     personalisation is needed.
+//
+// `openToAll` is intentionally NOT public — it still means "any
+// authenticated user", and the framework rejects anonymous callers there.
+// Without that guard, enabling anonymousAccess on the server would silently
+// expose every existing openToAll handler. The `product:authenticated-only`
+// query below proves this.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const productEntity = createEntity({
+  table: "shop_products",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    priceCents: createTextField({ personal: false, reason: "is_business_data", default: "0" }),
+  },
+});
+
+export const guestOrderEntity = createEntity({
+  table: "shop_guest_orders",
+  fields: {
+    productId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    email: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    placedBy: createTextField({ personal: "ref", default: "" }),
+  },
+});
+
+export const productTable = buildEntityTable("product", productEntity);
+export const guestOrderTable = buildEntityTable("guest-order", guestOrderEntity);
+
+export const anonymousAccessFeature = defineFeature("shop", (r) => {
+  r.entity("product", productEntity);
+  r.entity("guest-order", guestOrderEntity);
+
+  // Public listing: anonymous + authenticated customers see it. Combining
+  // the roles in one handler is preferred over duplicating the read path —
+  // the handler body can branch on `event.user.id === "anonymous"` if it
+  // needs to personalise (e.g. show a sign-in CTA, hide a wishlist button).
+  r.queryHandler(
+    "product:list",
+    z.object({}),
+    async (_event, ctx) => ctx.db.selectMany(productTable),
+    {
+      access: { roles: [...access.anonymous, "User", "Admin"] },
+      rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    },
+  );
+
+  // Authenticated-only listing — same data, different access rule. The
+  // openToAll declaration here is the regression-guard: even with
+  // anonymousAccess enabled on the server, this endpoint stays gated to
+  // logged-in users.
+  r.queryHandler(
+    "product:authenticated-only",
+    z.object({}),
+    async (_event, ctx) => ctx.db.selectMany(productTable),
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in (non-anonymous) user may list products here; this handler is " +
+            "the regression-guard proving anonymousAccess never silently exposes an authenticated-only endpoint",
+        },
+      },
+    },
+  );
+
+  // Anonymous + authenticated guest checkout. Stores the synthesised user-id
+  // ("anonymous") in `placedBy` so audit-trail / support queries can tell
+  // an authenticated order from a walk-in. Rate-limited per IP because every
+  // anonymous caller shares user.id="anonymous" — a per-user rate-limit
+  // would be a single global tap any caller could drain (the boot-validator
+  // refuses the misconfiguration).
+  const guestOrderExecutor = createEventStoreExecutor(guestOrderTable, guestOrderEntity, {
+    entityName: "guest-order",
+  });
+  r.writeHandler(
+    "guest-order:place",
+    z.object({
+      productId: z.uuid(),
+      email: z.string().email(),
+    }),
+    async (event, ctx) =>
+      guestOrderExecutor.create({ ...event.payload, placedBy: event.user.id }, event.user, ctx.db),
+    {
+      // `email` is recordOwned PII (personal: { of: "id" }) written by an
+      // anonymous root handler — the runtime personal-data gate
+      // (write-origin.ts) requires this explicit opt-in, the same way the
+      // boot validator would reject an openToAll declaration missing it.
+      access: { roles: [...access.anonymous, "User"], personalData: "public-intake" },
+      rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
+    },
+  );
+
+  // Admin-only product CRUD — proves role-gated handlers still reject
+  // anonymous callers. Same shape as any other handler in the framework:
+  // anonymous is just a regular role, not a special case.
+  r.writeHandler(
+    "product:create",
+    z.object({ name: z.string().min(1), priceCents: z.string() }),
+    async (event, ctx) => {
+      const exec = createEventStoreExecutor(productTable, productEntity, {
+        entityName: "product",
+      });
+      return exec.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+```