@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/chat-channels.md

@@ -0,0 +1,254 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/chat-channels. Do not edit. -->
+
+# chat-channels
+
+Chat channels. Delivery notifications to Slack, minus the browser tab.
+
+## README
+
+# Sample: Chat Channels
+
+Shows how a feature posts to a tenant's Slack channel without ever handling the webhook URL.
+
+## What you learn here
+
+**Route-only targets:** Chat targets belong to the tenant, not to a user. A handler addresses one with `ctx.notify(type, { route: { slack: "ops" } })`; `"ops"` is a connection name. The chat channels declare no `resolve`, so a normal `to: userId` notification skips them without a log row.
+
+**Secrets for the URL:** The tenant stores the webhook URL as a secret under `channel-slack:webhooks.<connection name>` (namespace declared by the channel, written through `secrets:write:set`). The `delivery.send` job reads it with an audit entry (`channel-slack:send`), posts the message and records only the connection name and an outcome code (`http_500`, `timeout`, `redirect_blocked`, `host_not_allowed`, `missing_credentials`, `invalid_address`).
+
+**App-level hardening:** Each channel only talks to its provider's hosts, over https, without following redirects. `allowedHosts`, `requireHttps` and `timeoutMs` are options of `createChannelSlackFeature(opts)`. Tenants cannot change them; the test uses them to point at a local stub.
+
+**Production boot:** `runProdApp`, `runDevApp` and `runWorkerApp` wire `ctx.notify` and the tenant secrets for you, so no app wiring is needed. Queued channels run through the `delivery.render`/`delivery.send` jobs on the worker lane (all-in-one by default); a "send test message" handler can pass `immediate: true` to `ctx.notify` to deliver inline and read `sent`/`failed` from the returned `deliveries`.
+
+The same shape works for `channel-discord`, `channel-teams` (connection name + webhook secret) and `channel-telegram` (one `botToken` secret, the address is the chat id).
+
+## Run
+
+```bash
+bun test --config=bunfig.integration.toml --timeout=15000 samples/recipes/chat-channels
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Proves the chat-channel path end to end: handler -> ctx.notify(route) ->
+// delivery.send job (real BullMQ worker) -> tenant secret -> HTTP POST to a local
+// stub standing in for Slack. Nothing real is contacted; the stub URL is only
+// reachable because the app mounts the channel with an allowlist override.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { createChannelSlackFeature } from "@cosmicdrift/kumiko-bundled-features/channel-slack";
+import {
+  configValuesTable,
+  createConfigFeature,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createDeliveryFeature,
+  createDeliveryTestContext,
+  deliveryAttemptsTable,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import {
+  createSecretsContext,
+  createSecretsFeature,
+  tenantSecretsTable,
+} from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  createTenantFeature,
+  TenantQueries,
+  tenantEntity,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import { OPS_ANNOUNCEMENT_TYPE, opsFeature } from "../feature";
+
+const admin = createTestUser({ roles: ["Admin", "TenantAdmin"] });
+const viewer = createTestUser({ roles: ["Viewer"] });
+
+let stack: TestStack;
+let jobRunner: JobRunner;
+let stub: ReturnType<typeof Bun.serve>;
+const received: unknown[] = [];
+
+beforeAll(async () => {
+  const redisUrl = process.env["REDIS_URL"];
+  if (!redisUrl) throw new Error("REDIS_URL required for the async delivery recipe test");
+
+  stub = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      received.push(await req.json());
+      return new Response("ok");
+    },
+  });
+
+  const masterKeyProvider = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createSecretsFeature(),
+      createDeliveryFeature(),
+      createChannelSlackFeature({ allowedHosts: ["127.0.0.1"], requireHttps: false }),
+      opsFeature,
+    ],
+    masterKeyProvider,
+    extraContext: (deps) => {
+      const secrets = createSecretsContext({
+        db: deps.db,
+        masterKeyProvider,
+        registry: deps.registry,
+      });
+      jobRunner = createJobRunner({
+        registry: deps.registry,
+        context: { db: deps.db, secrets },
+        redisUrl,
+        consumerLane: "worker",
+        queueNamePrefix: `kumiko-chat-recipe-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      });
+      return {
+        secrets,
+        ...createDeliveryTestContext(deps, {
+          tenantUserIdsQuery: TenantQueries.resolveUserIds,
+          jobRunner,
+        }),
+      };
+    },
+  });
+  await unsafePushTables(stack.db, {
+    configValuesTable,
+    tenantMembershipsTable,
+    tenant_secrets: tenantSecretsTable,
+  });
+  await unsafeCreateEntityTable(stack.db, tenantEntity, "tenant");
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  stub.stop(true);
+  await stack.cleanup();
+});
+
+describe("chat-channels recipe", () => {
+  test("announce -> Slack webhook receives the escaped text; log shows the connection name", async () => {
+    // The tenant admin stores the webhook URL under the connection name.
+    await stack.http.writeOk(
+      "secrets:write:set",
+      {
+        key: "channel-slack:webhooks.ops",
+        value: `http://127.0.0.1:${stub.port}/services/T000/B000/XXXX`,
+      },
+      admin,
+    );
+
+    await stack.http.writeOk(
+      "ops:write:announce",
+      { connection: "ops", title: "Deploy done", body: "release <v2> & friends" },
+      admin,
+    );
+
+    await waitFor(
+      async () => {
+        const rows = await selectMany(db(), deliveryAttemptsTable, {
+          notificationType: OPS_ANNOUNCEMENT_TYPE,
+          channel: "slack",
+        });
+        expect(rows.some((r) => r["status"] === "sent")).toBe(true);
+      },
+      { delays: Array(40).fill(250) },
+    );
+
+    expect(received).toEqual([{ text: "Deploy done\nrelease &lt;v2&gt; &amp; friends" }]);
+    const rows = await selectMany(db(), deliveryAttemptsTable, {
+      notificationType: OPS_ANNOUNCEMENT_TYPE,
+    });
+    expect(rows.map((r) => r["recipientAddress"])).toEqual(["ops"]);
+    expect(JSON.stringify(rows)).not.toContain("XXXX");
+  }, 20000);
+
+  test("announce rejects a caller without the Admin role", async () => {
+    const attemptsBefore = await selectMany(db(), deliveryAttemptsTable, {
+      notificationType: OPS_ANNOUNCEMENT_TYPE,
+    });
+    const error = await stack.http.writeErr(
+      "ops:write:announce",
+      { connection: "ops", title: "Not allowed" },
+      viewer,
+    );
+    expect(error.code).toBe("access_denied");
+    const attemptsAfter = await selectMany(db(), deliveryAttemptsTable, {
+      notificationType: OPS_ANNOUNCEMENT_TYPE,
+    });
+    expect(attemptsAfter).toHaveLength(attemptsBefore.length);
+  });
+});
+
+function db() {
+  return stack.db;
+}
+```
+
+### src/feature.ts
+
+```ts
+// Chat Channels Sample
+//
+// A handler tells the tenant's ops chat about something. Chat targets belong to
+// the tenant, not to a user, so the feature addresses one by connection name via
+// `route` — it never sees the webhook URL. The tenant stores that URL as a secret
+// under `channel-slack:webhooks.<connection name>`.
+
+import {
+  defineFeature,
+  defineWriteHandler,
+  type NotifyFn,
+  qn,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+
+export const OPS_ANNOUNCEMENT_TYPE = qn("ops", "notify", "announcement");
+
+export const opsFeature = defineFeature("ops", (r) => {
+  r.requires("delivery");
+
+  r.writeHandler(
+    defineWriteHandler({
+      name: "announce",
+      schema: z.object({
+        connection: z.string(),
+        title: z.string().min(1),
+        body: z.string().optional(),
+      }),
+      access: { roles: ["Admin"] },
+      handler: async (event, ctx) => {
+        const notify = ctx.notify as NotifyFn;
+        await notify(OPS_ANNOUNCEMENT_TYPE, {
+          route: { slack: event.payload.connection },
+          data: { title: event.payload.title, body: event.payload.body },
+        });
+        return { isSuccess: true, data: { announced: true } };
+      },
+    }),
+  );
+});
+```

package/agents/examples/compliance-profiles-demo.md

@@ -0,0 +1,307 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/compliance-profiles-demo. Do not edit. -->
+
+# compliance-profiles-demo
+
+Two-tenant demo: EU + Swiss compliance profiles deliver different authority contacts, languages, and grace periods through the same App-code.
+
+## README
+
+# compliance-profiles-demo
+
+Same app code, three tenants, three regulatory profiles — no `if (region)`
+branches in your domain handlers.
+
+## What it shows
+
+How a multi-tenant platform uses `compliance-profiles` to deliver different
+regulatory behaviour per tenant:
+
+| Tenant | Profile | Supervisory authority | Languages | Tenant-destroy grace |
+|---|---|---|---|---|
+| **A** (DACH) | `eu-dsgvo` | BlnBDI Berlin | de / en | 30 days |
+| **B** (Switzerland) | `swiss-dsg` | EDÖB Bern | de / fr / it / en | 30 days |
+| **C** (DACH-HR) | `de-hr-dsgvo-hgb` | State DPA | de | 60 days (HR override) |
+
+Plus tenant B with an override (`gracePeriod: { days: 90 }`) extending
+user-rights grace without losing other profile fields — deep-merge on the
+base profile; atomic paths replace, the rest inherits from `swiss-dsg` (which
+itself extends `eu-dsgvo`).
+
+## Feature composition
+
+The sample imports one feature:
+
+```ts illustration
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+
+export const features = [createComplianceProfilesFeature()];
+```
+
+The feature exposes `compliance.forTenant` — other features (`user-data-rights`,
+`data-retention`, tenant lifecycle) resolve the effective profile via this API
+instead of hard-coding region rules.
+
+## Flow
+
+1. Operator assigns a profile to each tenant (`eu-dsgvo`, `swiss-dsg`, …).
+2. Tenant B adds a partial override (longer grace) — merged atomically.
+3. `compliance.forTenant(tenantId)` returns resolved fields (languages,
+   supervisory authority, grace periods, retention presets).
+4. Downstream features read the resolver — forget grace, retention policy, and
+   audit obligations follow the profile without app-level branching.
+
+## 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
+# From kumiko-framework repo root:
+bun test samples/recipes/compliance-profiles-demo/src/__tests__/feature.integration.test.ts
+```
+
+Five full-stack tests via `setupTestStack` + real HTTP — profile assignment,
+override merge, and cross-tenant isolation.
+
+## Local dev
+
+This recipe has no standalone server bootstrap — tests are self-contained. To
+try interactively, mount `complianceProfilesDemoFeatures` in your own
+`runDevApp` config.
+
+## Related samples
+
+- [user-data-rights](/en/samples/recipes-user-data-rights/) — forget grace from
+  `compliance.forTenant` drives deletion timing.
+- [apps-user-data-rights-demo](/en/samples/apps-user-data-rights-demo/) — full
+  GDPR app with `eu-dsgvo` profile wired.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Two-tenant compliance-profiles demo (S1.6).
+//
+// Beweist die Cross-Tenant-Isolation des compliance-profiles-Features:
+// gleiche App, zwei Tenants, zwei Profile, zwei effektive Verhalten.
+//
+// Tenant A (DACH) → eu-dsgvo:
+//   - Aufsicht: BlnBDI Berlin
+//   - Sprachen: de, en
+//   - Grace-Period: 30d
+//
+// Tenant B (Schweiz) → swiss-dsg (extends eu-dsgvo):
+//   - Aufsicht: EDÖB Bern
+//   - Sprachen: de, fr, it, en
+//   - Grace-Period: 30d (geerbt)
+//
+// Tenant C (DACH-HR) → de-hr-dsgvo-hgb (extends eu-dsgvo, HR-Override):
+//   - Aufsicht: Landes-Datenschutzbehörde
+//   - Sprachen: de
+//   - Tenant-Destroy-Grace: 60d (HR-Override)
+//   - Audit-Retention: 10y (HGB-Override)
+//   - Plus worksCouncilApprovalRequired
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { tenantComplianceProfileEntity } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { complianceProfilesDemoFeatures } from "../feature";
+
+const SET_PROFILE = "compliance-profiles:write:set-profile";
+const FOR_TENANT = "compliance-profiles:query:for-tenant";
+
+let stack: TestStack;
+
+const tenantADachAdmin = createTestUser({
+  id: 1,
+  tenantId: testTenantId(1),
+  roles: ["TenantAdmin"],
+});
+const tenantBSwissAdmin = createTestUser({
+  id: 2,
+  tenantId: testTenantId(2),
+  roles: ["TenantAdmin"],
+});
+const tenantCHrAdmin = createTestUser({
+  id: 3,
+  tenantId: testTenantId(3),
+  roles: ["TenantAdmin"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: complianceProfilesDemoFeatures });
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await createEventsTable(stack.db);
+
+  // Onboarding-Setup: jeder Tenant-Admin waehlt sein Profile.
+  await stack.http.writeOk(SET_PROFILE, { profileKey: "eu-dsgvo" }, tenantADachAdmin);
+  await stack.http.writeOk(SET_PROFILE, { profileKey: "swiss-dsg" }, tenantBSwissAdmin);
+  await stack.http.writeOk(SET_PROFILE, { profileKey: "de-hr-dsgvo-hgb" }, tenantCHrAdmin);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("compliance-profiles-demo :: cross-tenant isolation", () => {
+  test("Tenant A (DACH) → eu-dsgvo: BlnBDI + DE/EN-Sprachen", async () => {
+    const result = await stack.http.queryOk<{
+      profile: {
+        key: string;
+        breach: { authorityContact: string };
+        notifications: { languages: string[] };
+        userRights: { gracePeriod: { days: number } };
+        tenantDestroyGracePeriod: { days: number };
+      };
+    }>(FOR_TENANT, {}, tenantADachAdmin);
+
+    expect(result.profile.key).toBe("eu-dsgvo");
+    expect(result.profile.breach.authorityContact).toBe("BlnBDI Berlin");
+    expect(result.profile.notifications.languages).toEqual(["de", "en"]);
+    expect(result.profile.userRights.gracePeriod).toEqual({ days: 30 });
+    expect(result.profile.tenantDestroyGracePeriod).toEqual({ days: 30 });
+  });
+
+  test("Tenant B (Schweiz) → swiss-dsg: EDÖB + DE/FR/IT/EN-Sprachen", async () => {
+    const result = await stack.http.queryOk<{
+      profile: {
+        key: string;
+        breach: { authorityContact: string };
+        notifications: { languages: string[] };
+        userRights: { gracePeriod: { days: number } };
+      };
+    }>(FOR_TENANT, {}, tenantBSwissAdmin);
+
+    expect(result.profile.key).toBe("swiss-dsg");
+    expect(result.profile.breach.authorityContact).toBe("EDÖB Bern");
+    expect(result.profile.notifications.languages).toEqual(["de", "fr", "it", "en"]);
+    // Geerbt aus eu-dsgvo via extends:
+    expect(result.profile.userRights.gracePeriod).toEqual({ days: 30 });
+  });
+
+  test("Tenant C (DACH-HR) → de-hr-dsgvo-hgb: HR-Override greift", async () => {
+    const result = await stack.http.queryOk<{
+      profile: {
+        key: string;
+        breach: { authorityContact: string; worksCouncilNotificationRequired?: boolean };
+        notifications: { languages: string[] };
+        tenantDestroyGracePeriod: { days: number };
+        auditLog: { retention: { years?: number } };
+        subProcessor: { worksCouncilApprovalRequired?: boolean };
+      };
+    }>(FOR_TENANT, {}, tenantCHrAdmin);
+
+    expect(result.profile.key).toBe("de-hr-dsgvo-hgb");
+    expect(result.profile.breach.authorityContact).toBe("Landes-Datenschutzbehörde");
+    expect(result.profile.breach.worksCouncilNotificationRequired).toBe(true);
+    expect(result.profile.notifications.languages).toEqual(["de"]);
+    expect(result.profile.tenantDestroyGracePeriod).toEqual({ days: 60 });
+    expect(result.profile.auditLog.retention).toEqual({ years: 10 });
+    expect(result.profile.subProcessor.worksCouncilApprovalRequired).toBe(true);
+  });
+
+  test("Profile-Wechsel auf demselben Tenant zeigt sofort neues Verhalten", async () => {
+    // Eigener Tenant D damit der Test reihenfolge-unabhaengig laeuft
+    // (Tenant A bleibt auf eu-dsgvo fuer die anderen Tests).
+    const tenantDAdmin = createTestUser({
+      id: 4,
+      tenantId: testTenantId(4),
+      roles: ["TenantAdmin"],
+    });
+    await stack.http.writeOk(SET_PROFILE, { profileKey: "eu-dsgvo" }, tenantDAdmin);
+
+    // Wechsel von eu-dsgvo auf swiss-dsg
+    await stack.http.writeOk(SET_PROFILE, { profileKey: "swiss-dsg" }, tenantDAdmin);
+    const after = await stack.http.queryOk<{
+      profile: { key: string; breach: { authorityContact: string } };
+    }>(FOR_TENANT, {}, tenantDAdmin);
+    expect(after.profile.key).toBe("swiss-dsg");
+    expect(after.profile.breach.authorityContact).toBe("EDÖB Bern");
+
+    // Zurueck auf eu-dsgvo
+    await stack.http.writeOk(SET_PROFILE, { profileKey: "eu-dsgvo" }, tenantDAdmin);
+    const back = await stack.http.queryOk<{
+      profile: { key: string; breach: { authorityContact: string } };
+    }>(FOR_TENANT, {}, tenantDAdmin);
+    expect(back.profile.key).toBe("eu-dsgvo");
+    expect(back.profile.breach.authorityContact).toBe("BlnBDI Berlin");
+  });
+
+  test("Tenant-Override merged auf base-profile, andere Felder bleiben", async () => {
+    // Eigener Tenant E damit der Override-State Tenant B nicht
+    // ueberschreibt (reihenfolge-unabhaengig).
+    const tenantEAdmin = createTestUser({
+      id: 5,
+      tenantId: testTenantId(5),
+      roles: ["TenantAdmin"],
+    });
+    await stack.http.writeOk(
+      SET_PROFILE,
+      {
+        profileKey: "swiss-dsg",
+        override: JSON.stringify({
+          userRights: { gracePeriod: { days: 90 } },
+        }),
+      },
+      tenantEAdmin,
+    );
+
+    const result = await stack.http.queryOk<{
+      profile: {
+        userRights: {
+          gracePeriod: { days: number };
+          portabilityFormat: string[];
+          restrictionAllowed: boolean;
+        };
+        notifications: { languages: string[] };
+      };
+    }>(FOR_TENANT, {}, tenantEAdmin);
+
+    expect(result.profile.userRights.gracePeriod).toEqual({ days: 90 });
+    // Andere userRights aus swiss-dsg bleiben
+    expect(result.profile.userRights.portabilityFormat).toEqual(["json"]);
+    expect(result.profile.userRights.restrictionAllowed).toBe(true);
+    // Sprachen aus swiss-dsg unverändert
+    expect(result.profile.notifications.languages).toEqual(["de", "fr", "it", "en"]);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Compliance-Profiles Demo
+//
+// Same App-Code, two different tenants, two different DSGVO-Profile —
+// das ist die Sales-Story von Compliance-Profiles. Tenant-Admin waehlt
+// einmal beim Onboarding, danach laufen alle User-Rights-Grace-Periods,
+// Notification-Sprachen, Breach-Disclosure-Pflichten und Audit-Log-
+// Retentions automatisch profil-spezifisch.
+//
+// Demo-Szenario:
+//   Tenant A (DACH-Customer)        → eu-dsgvo
+//     - 30d Grace-Period fuer Forget
+//     - DE/EN-Notifications
+//     - Aufsicht: BlnBDI Berlin
+//
+//   Tenant B (Swiss-Customer)       → swiss-dsg
+//     - 30d Grace-Period (geerbt aus eu-dsgvo via extends)
+//     - DE/FR/IT/EN-Notifications
+//     - Aufsicht: EDÖB Bern
+//
+// Beide Tenants laufen auf derselben App-Instance. Das compliance-
+// profiles-Feature haelt den Profile-State pro Tenant; jedes consumer-
+// Feature ruft `compliance.forTenant` (Sprint 2+) und sieht das
+// effektive Profile fuer den aktuellen Tenant.
+
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+
+export const complianceProfilesDemoFeatures = [createComplianceProfilesFeature()];
+```