@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/public-share-token.md

@@ -0,0 +1,351 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/public-share-token. Do not edit. -->
+
+# public-share-token
+
+Generic share-token entity: mint hash-stored token, anonymous read-by-token with IP rate-limit.
+
+## README
+
+# Public share token
+
+Minimal pattern for **tokenized anonymous read surfaces**: authenticated users
+mint a link; visitors resolve it without login.
+
+Domain-agnostic — no credit/folder logic. A full consumer adds snapshots,
+layout templates and tier gates on top.
+
+## What it shows
+
+- **`createEntity` + event-sourced CRUD** — `tokenHash` unique, plain token show-once
+- **`defineWriteHandler` / `defineQueryHandler`** — create, revoke, read-by-token
+- **Anonymous query** — `roles: ["anonymous", …]` + `rateLimit: { per: "ip+handler" }`
+- **404 ohne Leak** — invalid / expired / revoked → same `NotFoundError` shape
+- **`anonymousAccess`** on test stack (see integration test)
+
+Client wiring: [`recipes/apex-surface-auth`](../apex-surface-auth/) or a gate
+before `createKumikoApp` (a small gate component that renders the public view when
+the URL carries a share token).
+
+## Handlers
+
+| QN | Access |
+|---|---|
+| `public-share:write:share-link:create` | authenticated (`openToAll`) |
+| `public-share:write:share-link:revoke` | owner |
+| `public-share:query:share-by-token` | anonymous + authenticated |
+
+## Run tests
+
+From repo root (needs `TEST_DATABASE_URL` + `REDIS_URL`):
+
+```bash
+cd kumiko-framework/samples/recipes/public-share-token
+bun test src/__tests__/feature.integration.test.ts
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { publicShareTokenFeature, shareLinkEntity } from "../feature";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+
+let stack: TestStack;
+
+const owner = createTestUser({ id: 1, tenantId: TENANT_ID, roles: ["TenantAdmin"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [publicShareTokenFeature],
+    anonymousAccess: { defaultTenantId: TENANT_ID },
+  });
+  await unsafeCreateEntityTable(stack.db, shareLinkEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack?.cleanup();
+});
+
+describe("public-share-token recipe", () => {
+  test("create → anonymous share-by-token returns payload", async () => {
+    const created = await stack.http.writeOk<{
+      id: string;
+      plainToken: string;
+    }>(
+      "public-share:write:share-link:create",
+      { label: "Demo", payload: { note: "hello" }, expiresInDays: 7 },
+      owner,
+    );
+
+    expect(created.plainToken.startsWith("sh_")).toBe(true);
+
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "public-share:query:share-by-token",
+      payload: { token: created.plainToken },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { label: string; payload: { note: string } } };
+    expect(body.data.label).toBe("Demo");
+    expect(body.data.payload.note).toBe("hello");
+  });
+
+  test("revoke → share-by-token 404", async () => {
+    const created = await stack.http.writeOk<{ id: string; plainToken: string }>(
+      "public-share:write:share-link:create",
+      { label: "Revoke me", expiresInDays: 7 },
+      owner,
+    );
+
+    await stack.http.writeOk("public-share:write:share-link:revoke", { id: created.id }, owner);
+
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "public-share:query:share-by-token",
+      payload: { token: created.plainToken },
+    });
+    expect(res.status).toBe(404);
+  });
+
+  test("random token → 404", async () => {
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "public-share:query:share-by-token",
+      payload: { token: "sh_not-a-real-token" },
+    });
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("public-share-token recipe: expiry", () => {
+  test("expired token → share-by-token 404", async () => {
+    const created = await stack.http.writeOk<{ id: string; plainToken: string }>(
+      "public-share:write:share-link:create",
+      { label: "Expires soon", expiresInDays: 1 },
+      owner,
+    );
+
+    await stack.db.unsafe(
+      "UPDATE read_public_share_links SET expires_at = now() - interval '1 day' WHERE id = $1",
+      [created.id],
+    );
+
+    const res = await stack.http.raw("POST", "/api/query", {
+      type: "public-share:query:share-by-token",
+      payload: { token: created.plainToken },
+    });
+    expect(res.status).toBe(404);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Public share token — generic recipe (no domain payload).
+//
+// Pattern: authenticated create → plain token show-once → anonymous
+// read-by-token with SHA-256 lookup. Revoke sets revokedAt via executor.
+//
+// A full consumer adds domain snapshots, layouts and tier gates on top.
+
+import { generateToken } from "@cosmicdrift/kumiko-framework/api";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEntity,
+  createEntityExecutor,
+  createJsonbField,
+  createTextField,
+  createTimestampField,
+  defineFeature,
+  defineQueryHandler,
+  defineWriteHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+
+const TOKEN_PREFIX = "sh_";
+
+const SHARE_BY_TOKEN_REASON =
+  "resolves the share link by token hash for callers whose dispatch tenant is not the link owner's";
+
+export const shareLinkEntity = createEntity({
+  table: "read_public_share_links",
+  idType: "uuid",
+  fields: {
+    tokenHash: createTextField({
+      personal: false,
+      reason: "is_token_hash",
+      required: true,
+      maxLength: 64,
+    }),
+    label: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 200,
+    }),
+    payload: createJsonbField(),
+    expiresAt: createTimestampField({ required: true }),
+    revokedAt: createTimestampField({}),
+  },
+  indexes: [
+    {
+      unique: true,
+      columns: ["tokenHash"],
+      name: "read_public_share_links_hash_unique",
+    },
+  ],
+});
+
+const { executor, table } = createEntityExecutor("share-link", shareLinkEntity);
+
+async function hashToken(plain: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(plain));
+  let hex = "";
+  for (const byte of new Uint8Array(digest)) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+async function mintToken(): Promise<{ plain: string; hash: string }> {
+  const plain = `${TOKEN_PREFIX}${generateToken()}`;
+  return { plain, hash: await hashToken(plain) };
+}
+
+const createSchema = z.object({
+  label: z.string().min(1).max(200),
+  payload: z.record(z.string(), z.unknown()).optional(),
+  expiresInDays: z.number().int().min(1).max(90).default(30),
+});
+
+export const shareLinkCreateWrite = defineWriteHandler({
+  name: "share-link:create",
+  schema: createSchema,
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may create a share link for their own tenant; the link " +
+        "itself is only reachable via its unguessable token",
+    },
+  },
+  rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
+  handler: async (event, ctx) => {
+    const { plain, hash } = await mintToken();
+    const now = getTemporal().Now.instant();
+    const expiresAt = now.add({ hours: 24 * event.payload.expiresInDays });
+
+    const result = await executor.create(
+      {
+        tokenHash: hash,
+        label: event.payload.label,
+        payload: event.payload.payload ?? {},
+        expiresAt,
+        revokedAt: null,
+        tenantId: event.user.tenantId,
+      },
+      event.user,
+      ctx.db,
+    );
+    if (!result.isSuccess) return result;
+
+    const id = String((result.data as { id: unknown }).id);
+    return {
+      isSuccess: true as const,
+      data: { id, plainToken: plain, expiresAt: expiresAt.toString() },
+    };
+  },
+});
+
+export const shareLinkRevokeWrite = defineWriteHandler({
+  name: "share-link:revoke",
+  schema: z.object({ id: z.uuid() }),
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may attempt to revoke a share link, but only the link's " +
+        "own creator succeeds; the handler checks ownerId against the caller and " +
+        "returns not-found otherwise",
+    },
+  },
+  handler: async (event, ctx) => {
+    const rows = await ctx.db.selectMany(
+      table,
+      { id: event.payload.id, tenantId: event.user.tenantId },
+      { limit: 1 },
+    );
+    const row = rows[0];
+    const ownerId = String(row?.["insertedById"] ?? row?.["inserted_by_id"] ?? "");
+    if (!row || ownerId !== event.user.id) {
+      throw new NotFoundError("share-link");
+    }
+
+    return executor.update(
+      {
+        id: event.payload.id,
+        version: Number(row["version"]),
+        changes: { revokedAt: getTemporal().Now.instant() },
+      },
+      event.user,
+      ctx.db,
+    );
+  },
+});
+
+interface ShareLinkRow {
+  readonly id: string;
+  readonly label: string;
+  readonly payload: unknown;
+  readonly expiresAt: Temporal.Instant;
+  readonly revokedAt: Temporal.Instant | null;
+}
+
+export const shareByTokenQuery = defineQueryHandler({
+  name: "share-by-token",
+  schema: z.object({ token: z.string().min(1) }),
+  access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: SHARE_BY_TOKEN_REASON,
+  },
+  handler: async (query, ctx) => {
+    const hash = await hashToken(query.payload.token);
+    const row = await fetchOne<ShareLinkRow>(ctx.db.unsafeRaw(), table, {
+      tokenHash: hash,
+    });
+
+    if (!row) {
+      throw new NotFoundError("share-link");
+    }
+
+    const now = getTemporal().Now.instant();
+    if (row.revokedAt != null || row.expiresAt.epochMilliseconds <= now.epochMilliseconds) {
+      throw new NotFoundError("share-link");
+    }
+
+    return {
+      label: row.label,
+      payload: row.payload,
+    };
+  },
+});
+
+export const publicShareTokenFeature = defineFeature("public-share", (r) => {
+  r.entity("share-link", shareLinkEntity);
+  r.writeHandler(shareLinkCreateWrite);
+  r.writeHandler(shareLinkRevokeWrite);
+  r.queryHandler(shareByTokenQuery);
+});
+```

package/agents/examples/rate-limiting.md

@@ -0,0 +1,211 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/rate-limiting. Do not edit. -->
+
+# rate-limiting
+
+End-to-end rate limiting: L1 global-IP + L2 auth-endpoints + L3 handler opt-in.
+
+## README
+
+# Rate Limiting
+
+End-to-end rate limiting: L1 global-IP + L2 auth + L3 handler opt-in.
+
+## What it shows
+
+- Handler `rateLimit: { per, limit, windowSeconds }`
+- How L1/L2 from `buildServer` stack with L3
+
+## Per-payload limits
+
+A public write handler that mails an address typed by the caller is also limited per
+address, so rotating IPs does not help against mail flooding. Declare it next to `rateLimit`:
+
+```ts illustration
+r.writeHandler({
+  // ...
+  access: { roles: ["anonymous"] },
+  rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
+  additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
+});
+```
+
+`additionalRateLimits` only complements `rateLimit`: an anonymous handler still needs a real,
+ip-keyed `rateLimit` (boot fails otherwise), and `payloadField` must be a top-level string field
+of the handler's Zod object schema. The value is trimmed, lowercased and HMAC-hashed into the
+bucket key, so Redis never holds the address in plaintext. The check runs after schema
+validation and before the handler, identically for matching and non-matching values, and is
+skipped for system callers. Exceeding it answers 429 `rate_limited`.
+
+## 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/rate-limiting
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Rate-Limiting Showcase — End-to-end proof that all three layers stack.
+//
+// The boot config below is the same shape a real app would use:
+//   buildServer({ ..., rateLimit: { global: ..., auth: ... } })
+// L3 comes from the feature itself (handler-declared `rateLimit:`).
+//
+// One TestStack hosts all three layers. Each test uses a distinct
+// bucket dimension (per-user vs per-IP vs per-IP+path) so the layers
+// don't shadow each other; beforeEach flushes Redis so counters start
+// clean. Limits are picked so the 4th/3rd/21st call is the first 429
+// in each layer's test.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { createRateLimitShowcaseFeature } from "../feature";
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createRateLimitShowcaseFeature()],
+    // The L1/L2 tests below simulate distinct client IPs via
+    // X-Forwarded-For. Without a trusted proxy hop configured, the
+    // client-ip resolver now ignores X-Forwarded-For by design (it can't
+    // tell a real proxy from a spoofing client) and every call falls into
+    // the shared "unknown" bucket — trust one hop so the showcase actually
+    // demonstrates per-IP buckets, the way a real app behind one proxy would.
+    trustedProxyHops: 1,
+    rateLimit: {
+      // L1: 20/min per IP. High enough that L3 tests (which loop 4×
+      // with their own IP) don't accidentally trip L1 first.
+      global: { limit: 20, windowSeconds: 60 },
+      // L2: 2/min per (IP + path). Default `path: "/api/auth/*"` —
+      // tight limit because login brute-force is the canonical use case.
+      auth: { path: "/api/auth/*", limit: 2, windowSeconds: 60 },
+    },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.redis.flushNamespace();
+});
+
+describe("L3 — handler opt-in (per-user budget on expensive-search)", () => {
+  test("4th call from same user returns 429 with user-bucket", async () => {
+    for (let i = 0; i < 3; i++) {
+      const ok = await stack.http.queryOk<{ q: string; hits: number }>(
+        "rl-showcase:query:expensive-search",
+        { q: "kumiko" },
+        admin,
+      );
+      expect(ok.q).toBe("kumiko");
+    }
+
+    // queryOk would throw on non-2xx; query() returns the raw response so
+    // the wire-shape of the 429 body is observable.
+    const blocked = await stack.http.query(
+      "rl-showcase:query:expensive-search",
+      { q: "kumiko" },
+      admin,
+    );
+    expect(blocked.status).toBe(429);
+    const body = (await blocked.json()) as {
+      error: { code: string; details?: { bucket?: string } };
+    };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details?.bucket).toBe("user");
+  });
+});
+
+describe("L1 — global IP middleware (covers every /api/* request)", () => {
+  test("21st request from same IP returns 429 with l1:ip bucket", async () => {
+    // L1 sits ahead of auth + every /api/* route. Target an authless,
+    // routeless path: pre-21st calls pass through L1 and surface a 401
+    // from jwtGuard (no token attached). The response code itself
+    // doesn't matter — what matters is that the bucket counter advances.
+    const ipHeader = { "x-forwarded-for": "10.99.0.1" };
+    for (let i = 0; i < 20; i++) {
+      const res = await stack.app.request("/api/_probe", { headers: ipHeader });
+      expect(res.headers.get("X-RateLimit-Remaining")).toBe(String(19 - i));
+    }
+    const blocked = await stack.app.request("/api/_probe", { headers: ipHeader });
+    expect(blocked.status).toBe(429);
+    expect(blocked.headers.get("Retry-After")).toBeTruthy();
+    const body = (await blocked.json()) as {
+      error: { code: string; details: { bucket: string } };
+    };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details.bucket).toBe("l1");
+  });
+});
+
+describe("L2 — auth-endpoints middleware (tighter cap on /api/auth/*)", () => {
+  test("3rd POST to /api/auth/login from same IP returns 429 with l2:ip:path bucket", async () => {
+    const ipHeader = { "x-forwarded-for": "10.99.0.2" };
+
+    // L2 fires before the route resolves. Without an authConfig wired
+    // these POSTs would 404, but L2 still counts them — that's the
+    // whole point: gate before the request body even gets parsed.
+    for (let i = 0; i < 2; i++) {
+      const res = await stack.app.request("/api/auth/login", {
+        method: "POST",
+        headers: ipHeader,
+      });
+      expect(res.headers.get("X-RateLimit-Remaining")).toBe(String(1 - i));
+    }
+    const blocked = await stack.app.request("/api/auth/login", {
+      method: "POST",
+      headers: ipHeader,
+    });
+    expect(blocked.status).toBe(429);
+    const body = (await blocked.json()) as {
+      error: { code: string; details: { bucket: string } };
+    };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details.bucket).toBe("l2");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Rate-Limiting Showcase — minimal feature
+//
+// Declares one query handler with an L3 rateLimit option so the
+// dispatcher gates calls before the handler body runs. The integration
+// test pairs this with L1+L2 middleware wired via buildServer's
+// `rateLimit` option to prove all three layers stack.
+
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export function createRateLimitShowcaseFeature(): FeatureDefinition {
+  return defineFeature("rl-showcase", (r) => {
+    // Per-user budget. Real apps tune `limit` to actual handler cost — a
+    // search call against a sharded index might warrant 5/min, a full
+    // export 1/min. The bucket is `user:<userId>` (see rate-limit/bucket.ts).
+    r.queryHandler(
+      "expensive-search",
+      z.object({ q: z.string().min(1) }),
+      async ({ payload }) => ({ q: payload.q, hits: 0 }),
+      {
+        access: { roles: ["Admin", "User"] },
+        rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
+      },
+    );
+  });
+}
+```