@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/search.md

@@ -0,0 +1,233 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/search. Do not edit. -->
+
+# search
+
+Tenant-scoped Meilisearch. Because ILIKE is not search.
+
+## README
+
+# Search
+
+Tenant-scoped full-text search (Meilisearch / in-memory adapter).
+
+## What it shows
+
+- `searchable` / `searchWeight` on fields
+- Handler reads via `ctx.searchAdapter`
+
+## 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/search
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Search Sample — Integration Test
+// Proves: searchable fields indexed via system hook, search returns matches
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { productEntity, productFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [productFeature] });
+  await unsafeCreateEntityTable(stack.db, productEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  // Advance the dispatcher cursor past previous-test events so each test
+  // starts with a clean horizon — same pattern as realtime-sse sample.
+  await stack.eventDispatcher?.runOnce();
+  stack.events.reset();
+});
+
+describe("search indexing", () => {
+  test("created product is findable via search", async () => {
+    await stack.http.writeOk(
+      "shop:write:product:create",
+      {
+        name: "Wireless Mouse",
+        brand: "Logitech",
+        sku: "WM-001",
+        category: "peripherals",
+      },
+      admin,
+    );
+
+    // Since D.4 search indexing runs as an async EventConsumer — drain the
+    // dispatcher before asserting.
+    await stack.eventDispatcher?.runOnce();
+
+    // Search via SearchAdapter directly
+    const results = await stack.search.search("00000000-0000-4000-8000-000000000001", "wireless", {
+      filterType: "product",
+    });
+    expect(results.some((r) => r.entityType === "product")).toBe(true);
+  });
+
+  test("search via list handler returns matching rows", async () => {
+    await stack.http.writeOk(
+      "shop:write:product:create",
+      {
+        name: "Mechanical Keyboard",
+        brand: "Cherry",
+        sku: "MK-002",
+      },
+      admin,
+    );
+    await stack.eventDispatcher?.runOnce();
+
+    const list = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "shop:query:product:list",
+      { search: "mechanical" },
+      admin,
+    );
+
+    expect(list.rows.some((r) => r["name"] === "Mechanical Keyboard")).toBe(true);
+  });
+
+  test("search by brand field", async () => {
+    await stack.http.writeOk(
+      "shop:write:product:create",
+      {
+        name: "Budget Mouse",
+        brand: "UniqueTestBrand",
+        sku: "BM-003",
+      },
+      admin,
+    );
+    await stack.eventDispatcher?.runOnce();
+
+    const results = await stack.search.search(
+      "00000000-0000-4000-8000-000000000001",
+      "UniqueTestBrand",
+      { filterType: "product" },
+    );
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  test("non-searchable field not indexed", async () => {
+    await stack.http.writeOk(
+      "shop:write:product:create",
+      {
+        name: "Hidden SKU Product",
+        sku: "SECRET-SKU-999",
+        category: "test",
+      },
+      admin,
+    );
+    await stack.eventDispatcher?.runOnce();
+
+    // SKU is not searchable, should not find via SKU search
+    const results = await stack.search.search(
+      "00000000-0000-4000-8000-000000000001",
+      "SECRET-SKU-999",
+      { filterType: "product" },
+    );
+    expect(results).toHaveLength(0);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Search Sample
+// Shows: searchable fields, searchWeight, search via InMemory SearchAdapter.
+// Each handler builds its executor inline so `ctx.searchAdapter` is read fresh
+// per call — tests swap the adapter between runs.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const productEntity = createEntity({
+  table: "read_sample_products",
+  fields: {
+    name: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+    }),
+    brand: createTextField({ personal: false, reason: "is_business_data", searchable: true }),
+    sku: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    category: createTextField({ personal: false, reason: "is_business_data" }),
+  },
+  searchWeight: 10,
+});
+
+const productTable = buildEntityTable("product", productEntity);
+
+export const productFeature = defineFeature("shop", (r) => {
+  r.entity("product", productEntity);
+
+  r.writeHandler(
+    "product:create",
+    z.object({
+      name: z.string().min(1),
+      brand: z.string().optional(),
+      sku: z.string().min(1),
+      category: z.string().optional(),
+    }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(productTable, productEntity, {
+        searchAdapter: ctx.searchAdapter,
+        entityName: "product",
+      });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.queryHandler(
+    "product:list",
+    z.object({
+      search: z.string().optional(),
+      limit: z.number().optional(),
+    }),
+    async (query, ctx) => {
+      const crud = createEventStoreExecutor(productTable, productEntity, {
+        searchAdapter: ctx.searchAdapter,
+        entityName: "product",
+      });
+      return crud.list(query.payload, query.user, ctx.db);
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in user may search and list products in this recipe; creating " +
+            "a product still requires the Admin role above",
+        },
+      },
+    },
+  );
+});
+```

package/agents/examples/secrets-demo.md

@@ -0,0 +1,417 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/secrets-demo. Do not edit. -->
+
+# secrets-demo
+
+Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
+
+## README
+
+# Secrets Demo
+
+Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
+
+## What it shows
+
+- `r.secret` + `ctx.secrets.get` (audited reads)
+- Charge-style handler that never returns the plaintext key
+
+## 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/secrets-demo
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Secrets Demo — End-to-End Proof
+//
+// What we're proving (all via real HTTP + BullMQ dispatch — no direct
+// function calls into framework internals):
+//   1. A TenantAdmin sets a secret over HTTP → DB holds only an envelope.
+//   2. list handler returns a redacted preview, never plaintext.
+//   3. Feature code (ctx.secrets.get) decrypts through the audited wrapper.
+//      Every read writes a tenantSecretRead event to the events-table.
+//   4. The response-guard catches accidental Secret<> leaks: a handler
+//      that tries to return the branded value triggers a 500 at the
+//      dispatcher boundary (not a silent exfiltration).
+//   5. KEK rotation works end-to-end via the core rotate job, triggered
+//      through BullMQ — app code writes zero rotation logic.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { createJobsFeature } from "@cosmicdrift/kumiko-bundled-features/jobs";
+import {
+  createSecretsContext,
+  createSecretsFeature,
+  type StoredEnvelope,
+  TENANT_SECRET_READ_EVENT,
+  tenantSecretsTable,
+} from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineFeature, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import { createEnvMasterKeyProvider, createSecret } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createMutableMasterKeyProvider,
+  type MutableMasterKeyProvider,
+  waitFor,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { z } from "zod";
+import { createBillingFeature, STRIPE_API_KEY } from "../feature";
+
+// Stable KEK bytes across provider rebuilds — mimics ops flipping env vars
+// across a redeploy without rotating the actual key material.
+const KEK_V1 = randomBytes(32);
+const KEK_V2 = randomBytes(32);
+
+function keyringEnv(current: number, withV2 = false): Record<string, string> {
+  const env: Record<string, string> = {
+    KUMIKO_SECRETS_MASTER_KEY_V1: KEK_V1.toString("base64"),
+    KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: String(current),
+  };
+  if (withV2) env["KUMIKO_SECRETS_MASTER_KEY_V2"] = KEK_V2.toString("base64");
+  return env;
+}
+
+// Buggy handler for the response-guard test. Deliberately returns a Secret<>
+// branded value in its data payload. The R6 compile-time guard now makes that a
+// type error, so `as unknown as string` deliberately erodes the type — the
+// `any`-hole R6 cannot see — to prove the RUNTIME guard is the backstop that
+// still intercepts the leak before the response leaves the wire.
+const leakyFeature = defineFeature("leaky", (r) => {
+  r.writeHandler(
+    defineWriteHandler({
+      name: "leak",
+      schema: z.object({}),
+      access: { roles: ["TenantAdmin"] },
+      handler: async () => ({
+        isSuccess: true,
+        data: { apiKey: createSecret("would-have-been-leaked") as unknown as string },
+      }),
+    }),
+  );
+});
+
+const tenantAdmin = createTestUser({
+  id: "00000000-0000-4000-8000-000000000010",
+  tenantId: "00000000-0000-4000-8000-000000000001",
+  roles: ["TenantAdmin"],
+});
+
+let stack: TestStack;
+let jobRunner: JobRunner;
+let providerRef: MutableMasterKeyProvider;
+
+beforeAll(async () => {
+  const initialProvider = createEnvMasterKeyProvider({ env: keyringEnv(1) });
+  providerRef = createMutableMasterKeyProvider(initialProvider);
+
+  stack = await setupTestStack({
+    features: [createJobsFeature(), createSecretsFeature(), createBillingFeature(), leakyFeature],
+    // Typed masterKeyProvider option: lands in AppContext as a typed field,
+    // no Record<string, unknown>-via-extraContext. The rotation job reads
+    // it from ctx.masterKeyProvider directly.
+    masterKeyProvider: providerRef,
+    extraContext: ({ db, registry }) => ({
+      // SecretsContext sees the mutable ref — any replace() flips what
+      // set/get/rotate use on the NEXT call.
+      secrets: createSecretsContext({ db, masterKeyProvider: providerRef, registry }),
+    }),
+  });
+
+  await unsafePushTables(stack.db, {
+    tenant_secrets: tenantSecretsTable,
+  });
+  await createEventsTable(stack.db);
+
+  // BullMQ-backed job runner. Triggering rotate via dispatch() routes
+  // through the queue + worker just like production — not a direct call
+  // into the handler function.
+  const redisUrl = `redis://${stack.redis.redis.options.host}:${stack.redis.redis.options.port}/${stack.redis.redis.options.db}`;
+  jobRunner = createJobRunner({
+    registry: stack.registry,
+    context: {
+      db: stack.db,
+      registry: stack.registry,
+      masterKeyProvider: providerRef,
+    },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-secrets-demo-${Date.now()}`,
+  });
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await stack.cleanup();
+});
+
+describe("1. at-rest representation", () => {
+  test("set stores envelope only — plaintext nowhere in the row", async () => {
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: STRIPE_API_KEY.name, value: "sk_test_SuperSecretLivePlatz12345" },
+      tenantAdmin,
+    );
+
+    const [row] = await selectMany(stack.db, tenantSecretsTable, {
+      tenantId: tenantAdmin.tenantId,
+      key: STRIPE_API_KEY.name,
+    });
+    if (!row) throw new Error("row missing");
+
+    const env = row.envelope as StoredEnvelope;
+    expect(env.ciphertext).toBeTruthy();
+    expect(env.kekVersion).toBe(1);
+    expect(row.kekVersion).toBe(1);
+    expect(JSON.stringify(row)).not.toContain("sk_test_SuperSecretLivePlatz12345");
+  });
+});
+
+describe("2. list shows preview only", () => {
+  test("redactedPreview uses billing's domain-aware redact function", async () => {
+    const list = await stack.http.queryOk<
+      Array<{ key: string; redactedPreview: string | null; kekVersion: number }>
+    >("secrets:query:list", {}, tenantAdmin);
+
+    const stripe = list.find((r) => r.key === STRIPE_API_KEY.name);
+    expect(stripe).toBeDefined();
+    expect(stripe?.redactedPreview).toMatch(/^sk_test\.\.\..+$/);
+    expect(stripe?.redactedPreview).not.toContain("SuperSecretLive");
+  });
+});
+
+describe("3. feature code decrypts via audited path", () => {
+  test("billing:charge reads plaintext; audit row is appended", async () => {
+    // Post-ES: read-audit rides on the events-table as tenantSecretRead
+    // domain-events (one per get() call, fresh aggregate-id each). Filter
+    // by tenantId so parallel tests don't skew the count.
+    const before = await selectMany(stack.db, eventsTable, {
+      tenantId: tenantAdmin.tenantId,
+      type: TENANT_SECRET_READ_EVENT,
+    });
+
+    const result = await stack.http.writeOk<{
+      chargeId: string;
+      amount: number;
+      keyFingerprint: string;
+    }>("billing:write:charge", { amount: 4999, customerRef: "cust_42" }, tenantAdmin);
+
+    expect(result.keyFingerprint).toBe("sk_te...2345");
+    expect(result.chargeId).toContain("cust_42");
+    expect(JSON.stringify(result)).not.toContain("sk_test_SuperSecretLivePlatz12345");
+
+    const after = await selectMany(stack.db, eventsTable, {
+      tenantId: tenantAdmin.tenantId,
+      type: TENANT_SECRET_READ_EVENT,
+    });
+    expect(after.length).toBe(before.length + 1);
+
+    const newest = after[after.length - 1];
+    if (!newest) throw new Error("read-audit event missing");
+    const payload = newest.payload as {
+      key: string;
+      userId: string;
+      handlerName: string;
+    };
+    expect(payload.key).toBe(STRIPE_API_KEY.name);
+    expect(payload.userId).toBe(tenantAdmin.id);
+    expect(payload.handlerName).toBe("billing:write:charge");
+  });
+});
+
+describe("4. response guard via the real dispatcher", () => {
+  test("a handler that returns Secret<> is rejected at the dispatcher boundary", async () => {
+    // Full HTTP path: the leakyFeature's handler returns Secret<> in its
+    // data. The dispatcher's post-handler guard catches it and converts
+    // to a 500 with a "leaked" message — the client never sees the secret.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/write",
+      { type: "leaky:write:leak", payload: {} },
+      { Authorization: `Bearer ${await stack.jwt.sign(tenantAdmin)}` },
+    );
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error?: { message?: string } };
+    expect(body.error?.message).toMatch(/leaked/);
+    // Response must not echo the branded value — ever.
+    expect(JSON.stringify(body)).not.toContain("would-have-been-leaked");
+  });
+});
+
+describe("5. KEK rotation via the core job + real BullMQ dispatch", () => {
+  test("rotate job triggered over BullMQ migrates the V1 row onto V2", async () => {
+    // Sanity: row is still on V1 before we flip the ring.
+    const beforeRow = await fetchOne<{ kekVersion: number }>(stack.db, tenantSecretsTable, {
+      key: STRIPE_API_KEY.name,
+    });
+    expect(beforeRow?.kekVersion).toBe(1);
+
+    // Ops flipped CURRENT to V2 (and keyring has V1+V2). In production
+    // this is an env swap + redeploy; here we replace the inner provider
+    // of the mutable ref so every downstream caller — SecretsContext AND
+    // the rotate job — sees the new current.
+    providerRef.replace(createEnvMasterKeyProvider({ env: keyringEnv(2, /* withV2 */ true) }));
+
+    // Trigger the rotate job through the SAME path production uses:
+    // jobRunner.dispatch → BullMQ queue → worker → registered handler.
+    // Nothing calls rotateJob directly; the r.job wire has to be intact
+    // for this to produce the expected DB change.
+    await jobRunner.dispatch("secrets:job:rotate", { batchSize: 10 });
+
+    // Wait for the BullMQ worker to finish. waitFor retries with escalating
+    // delays (250ms → 1s → 3s) and throws the assertion error from the
+    // final attempt — so a real rotation failure surfaces as a clear
+    // "expected 2, got 1" instead of a "polling timed out" noise message.
+    await waitFor(async () => {
+      const row = await fetchOne<{ kekVersion: number }>(stack.db, tenantSecretsTable, {
+        key: STRIPE_API_KEY.name,
+      });
+      expect(row?.kekVersion).toBe(2);
+    });
+
+    // Ciphertext byte-identical — only the DEK wrapper changed. Proves
+    // rewrapDek's promise (cheap rotation on large tables).
+    const [full] = await selectMany(stack.db, tenantSecretsTable, { key: STRIPE_API_KEY.name });
+    if (!full) throw new Error("row missing");
+    expect((full.envelope as StoredEnvelope).kekVersion).toBe(2);
+  });
+
+  test("subsequent ctx.secrets.get after rotation still returns the original plaintext", async () => {
+    // Goes through the whole real stack: HTTP → dispatcher → billing
+    // handler → ctx.secrets.get → cached DEK-unwrap with V2 → decrypt.
+    // If rotation broke anything, fingerprint would differ or the call
+    // would throw.
+    const result = await stack.http.writeOk<{ keyFingerprint: string }>(
+      "billing:write:charge",
+      { amount: 100, customerRef: "post_rotation_check" },
+      tenantAdmin,
+    );
+    expect(result.keyFingerprint).toBe("sk_te...2345");
+  });
+
+  test("re-dispatching the job is a no-op once all rows are on current", async () => {
+    await jobRunner.dispatch("secrets:job:rotate", { batchSize: 10 });
+    // Row state already at V2 from the previous test; waitFor only gates
+    // on the assertion succeeding, so if the job worker stayed idle (no
+    // work to do) this returns on the first check.
+    await waitFor(async () => {
+      const row = await fetchOne<{ kekVersion: number }>(stack.db, tenantSecretsTable, {
+        key: STRIPE_API_KEY.name,
+      });
+      expect(row?.kekVersion).toBe(2);
+    });
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// A miniature "billing" feature that reads a Stripe API key from ctx.secrets
+// and simulates a charge. The point is to show how feature code uses the
+// plaintext secret without ever exposing it to clients — the charge endpoint
+// returns { chargeId } but never the apiKey.
+
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  defineFeature,
+  defineWriteHandler,
+  type FeatureDefinition,
+  type SecretKeyHandle,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+// Typed handle exported by the feature's setup. Bound to what r.secret
+// returns below — downstream code imports STRIPE_API_KEY.name for the
+// qualified string, but never has to retype "billing:secret:stripe-api-key".
+// Renaming the r.secret call updates every call-site through the import graph.
+export let STRIPE_API_KEY: SecretKeyHandle;
+
+const chargeWrite = defineWriteHandler({
+  name: "charge",
+  schema: z.object({
+    amount: z.number().positive(),
+    customerRef: z.string().min(1),
+  }),
+  access: { roles: ["TenantAdmin", "User"] },
+  handler: async (event, ctx) => {
+    const secrets = requireSecretsContext(ctx, "billing:write:charge");
+    // requireSecretsContext returned a wrapper that auto-fills the audit
+    // context (userId + "billing:write:charge") on every .get — the read
+    // lands in tenant_secret_reads without the handler having to remember.
+    const branded = await secrets.get(event.user.tenantId, STRIPE_API_KEY);
+    if (!branded) {
+      return failUnprocessable("stripe_key_missing", {
+        hint: `TenantAdmin must first set ${STRIPE_API_KEY} via /api/write/secrets:write:set`,
+      });
+    }
+    // reveal() is the explicit un-brand. Everything that comes out stays
+    // plaintext string — we're now responsible for not letting it escape
+    // into the response. Fingerprint is the deliberate, audited leak.
+    const apiKey = branded.reveal();
+
+    // Fake the external call — in real code this would be
+    //   stripe = new Stripe(apiKey)
+    //   await stripe.paymentIntents.create({...})
+    // The key is consumed in-memory only; the response to the client never
+    // mentions it.
+    const chargeId = `ch_${Date.now()}_${event.payload.customerRef}`;
+    const keyFingerprint = `${apiKey.slice(0, 5)}...${apiKey.slice(-4)}`;
+
+    return {
+      isSuccess: true,
+      data: {
+        chargeId,
+        amount: event.payload.amount,
+        // Include a harmless fingerprint so the test can assert the charge
+        // used the correct key without revealing the full plaintext.
+        keyFingerprint,
+      },
+    };
+  },
+});
+
+export function createBillingFeature(): FeatureDefinition {
+  return defineFeature("billing", (r) => {
+    // Typed declaration of the secret this feature needs. Admin UIs can
+    // list known secrets (label + hint) so tenant-admin doesn't have to
+    // guess the key name; rotation / audit work by qualified name. The
+    // handle's .name is the QN the registrar built for us.
+    STRIPE_API_KEY = r.secret("stripe.apiKey", {
+      label: { de: "Stripe API-Schlüssel", en: "Stripe API Key" },
+      hint: {
+        de: "Aus dem Stripe-Dashboard unter Developers → API Keys.",
+        en: "From the Stripe dashboard under Developers → API Keys.",
+      },
+      // Domain-aware redaction: Stripe keys have a documented prefix+last4
+      // shape, so show that instead of the generic first-3 policy.
+      redact: (plaintext) => {
+        if (plaintext.length < 10) return "•".repeat(plaintext.length);
+        return `${plaintext.slice(0, 7)}...${plaintext.slice(-4)}`;
+      },
+      scope: "tenant",
+    });
+    r.writeHandler(chargeWrite);
+  });
+}
+```