@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/managed-config.md

@@ -0,0 +1,428 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/managed-config. Do not edit. -->
+
+# managed-config
+
+Managed config: one declaration provisions storage + masking + settings-hub, across backings (secrets vs config) and scopes (system vs tenant).
+
+## README
+
+# Recipe: Managed config
+
+**What this shows:** how one declarative config surface provisions everything a
+key needs — storage, masking, cascade, and a settings-hub entry — across two
+backings and two scopes, without a hand-written screen, nav, or env-wiring map.
+
+Two keys, deliberately different:
+
+| Key | Scope | Backing | Story |
+|---|---|---|---|
+| `payment-api-key` | `system` | `secrets` | Platform-owned secret (one Stripe key bills all tenants). Stored envelope-encrypted in the secrets store, masked in every query, revealed only for the owning feature's `ctx.config` read. |
+| `smtp-host` | `tenant` | config | Platform default that a tenant admin overrides. Cascade resolves `tenant-row → system-row → default`; one tenant's override never leaks to another. |
+
+## Pattern
+
+```ts illustration
+import { access, createSystemConfig, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine";
+
+r.config({
+  keys: {
+    // System-only secret: storage routes to the secrets envelope (KEK rotation
+    // + audit-on-read), never config_values. backing:"secrets" is system-only —
+    // the boot-guard rejects it on tenant/user scope (secrets has no cascade).
+    "payment-api-key": createSystemConfig("text", {
+      backing: "secrets",
+      write: access.systemAdmin,
+      read: access.admin,
+      mask: { title: "integrations.payment-api-key", icon: "credit-card", order: 1 },
+    }),
+    // Tenant override with a platform default sourced from an env var at boot.
+    "smtp-host": createTenantConfig("text", {
+      env: "SMTP_HOST",
+      default: "smtp.platform.example",
+      write: access.roles("SystemAdmin", "Admin"),
+      read: access.admin,
+      mask: { title: "integrations.smtp-host", icon: "mail", order: 2 },
+    }),
+  },
+});
+```
+
+## What each option provisions
+
+- **`backing: "secrets"`** — the value lives in the secrets store (envelope
+  encryption, KEK rotation, audit-on-read) instead of `config_values`. Set/read/
+  reset dispatch through `ctx.secrets`; the query handlers mask the value while
+  the owning feature still reads the revealed plaintext via `ctx.config`. Only
+  valid for `scope: "system"` — secrets are flat per `(tenant, key)` with no
+  cascade, so a tenant override would be incoherent and is rejected at boot.
+- **`env: "SMTP_HOST"`** — at boot (`runProdApp`) the env var seeds the key's
+  default as an app-override, below any `system-row`. The env var *is* the
+  default; no manual `AppConfigOverrides` map, no re-typing in the admin UI.
+- **`mask`** — the key surfaces automatically in the self-populating settings
+  hub: `buildConfigFeatureSchema` derives a `configEdit` screen + a child nav
+  under the audience hub (Platform / Organisation / Personal) from the key's
+  scope and type. No `r.screen`, no `r.nav`. `mask.title` is the i18n label key.
+
+## Boot wiring
+
+```ts illustration
+import {
+  createConfigAccessorFactory,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { createSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+
+const masterKeyProvider = createEnvMasterKeyProvider({ env: process.env });
+const resolver = createConfigResolver();
+
+await runProdApp({
+  extraContext: ({ db, registry }) => ({
+    configResolver: resolver,
+    _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    // Required whenever a key declares backing:"secrets" — without it the set
+    // and read paths fail loud, never silently miss.
+    secrets: createSecretsContext({ db, masterKeyProvider, registry }),
+  }),
+  // ...
+});
+```
+
+Register the `secrets` feature too so its `tenant_secrets` table is migrated;
+the config backing only needs the `ctx.secrets` context shown above.
+
+## Vs. the neighbouring recipes
+
+| Pattern | Storage | Cascade | Use case |
+|---|---|---|---|
+| **`encrypted: true` config key** (`encrypted-tenant-config`) | `config_values`, AES ciphertext | system → tenant | Per-tenant customer secret, no KEK rotation/audit. |
+| **`backing: "secrets"` config key** (this recipe) | secrets envelope, system tenant | none (system-only) | Platform-owned secret needing rotation + audit-on-read, declared as a config key. |
+| **`r.secret`** (`secrets-demo`) | secrets envelope | none | Same storage, but addressed directly — no config key, no settings-hub entry. |
+
+`backing: "secrets"` is the bridge: you get the secrets store's guarantees
+*and* the config feature's declarative surface (masking, settings hub, the same
+`config:write:set` write path).
+
+## Flow
+
+1. SystemAdmin sets `payment-api-key` (`backing: "secrets"`) → value lands in
+   the secrets envelope, masked in every query.
+2. Owning feature reads plaintext via `ctx.config` — audit-on-read from secrets.
+3. SystemAdmin sets platform `smtp-host` default (system scope).
+4. Tenant A overrides `smtp-host` → cascade resolves tenant-row for A only.
+5. Tenant B still sees the system default — no cross-tenant leak.
+
+## 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
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Proves:
+
+- `backing: "secrets"` routes to secrets store, not `config_values`
+- Owning feature reads revealed plaintext; cascade queries stay masked
+- Tenant SMTP override wins locally and never leaks to another tenant
+- Boot rejects `integrationsFeature` without the `secrets` feature mounted
+
+## What's not in this recipe
+
+- **Tenant-scoped secrets** — forbidden by declaration. `backing: "secrets"` +
+  `scope: "tenant"`/`"user"` fails at boot; use `encrypted: true` for a
+  cascading per-tenant secret.
+- **The env→default bridge at runtime** — `env:` is wired by `runProdApp`, not
+  by `setupTestStack`, so the integration test sets the platform default
+  explicitly via a `scope: "system"` write rather than through the env var.
+
+## Related samples
+
+- [encrypted-tenant-config](/en/samples/recipes-encrypted-tenant-config/) —
+  per-tenant customer secrets with `encrypted: true` on config keys.
+- [apps-cap-billing-demo](/en/samples/apps-cap-billing-demo/) — mail transport
+  selected per tenant via config.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// End-to-end over real HTTP: one declarative config surface, two backings.
+//
+//   payment-api-key (backing:"secrets") → set routes into the secrets envelope,
+//   masked in queries, revealed only for the owning feature's ctx.config read.
+//
+//   smtp-host (config, tenant scope) → platform default → system-row → tenant
+//   override; cascade proves a tenant override does not leak across tenants.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import {
+  configValuesTable,
+  createConfigAccessorFactory,
+  createConfigFeature,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createSecretsContext,
+  createSecretsFeature,
+  tenantSecretsTable,
+} from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  type ConfigCascade,
+  createRegistry,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { integrationsFeature, paymentApiKeyHandle, smtpHostHandle } from "../feature";
+
+const TENANT_A = testTenantId(1);
+const TENANT_B = testTenantId(2);
+
+const systemAdmin = TestUsers.systemAdmin;
+const acmeAdmin = { ...TestUsers.admin, tenantId: TENANT_A, id: "acme-admin" };
+const globexAdmin = { ...TestUsers.admin, tenantId: TENANT_B, id: "globex-admin" };
+
+type Cascades = Record<string, ConfigCascade>;
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  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(), createSecretsFeature(), integrationsFeature],
+    extraContext: ({ db, registry }) => {
+      const resolver = createConfigResolver();
+      return {
+        configResolver: resolver,
+        _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+        secrets: createSecretsContext({ db, masterKeyProvider, registry }),
+      };
+    },
+  });
+  await unsafePushTables(stack.db, { configValuesTable, tenantSecretsTable });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("managed config — backing:secrets system key", () => {
+  test("set routes the value into the secrets store, not config_values", async () => {
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: paymentApiKeyHandle.name, value: "sk-live-acme-99", scope: "system" },
+      systemAdmin,
+    );
+
+    const secretRows = await selectMany(stack.db, tenantSecretsTable, {
+      tenantId: SYSTEM_TENANT_ID,
+      key: paymentApiKeyHandle.name,
+    });
+    expect(secretRows).toHaveLength(1);
+    // The plaintext never touches config_values, and the stored secret is an
+    // envelope — no column carries the cleartext.
+    const configRows = await selectMany(stack.db, configValuesTable, {
+      key: paymentApiKeyHandle.name,
+    });
+    expect(configRows).toHaveLength(0);
+    expect(JSON.stringify(secretRows[0])).not.toContain("sk-live-acme-99");
+  });
+
+  test("the owning feature reads the revealed plaintext via ctx.config", async () => {
+    const res = await stack.http.queryOk<{ value: unknown }>(
+      "integrations:query:peek-payment-key",
+      {},
+      systemAdmin,
+    );
+    expect(res.value).toBe("sk-live-acme-99");
+  });
+
+  test("config:query:cascade masks the value and every level", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      "config:query:cascade",
+      { keys: [paymentApiKeyHandle.name] },
+      systemAdmin,
+    );
+    const cascade = res[paymentApiKeyHandle.name];
+    expect(cascade?.value).toBe("••••••");
+    expect(cascade?.source).toBe("system-row");
+    expect(JSON.stringify(cascade)).not.toContain("sk-live-acme-99");
+  });
+});
+
+describe("managed config — tenant cascade override", () => {
+  test("with no rows the tenant sees the platform default", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      "config:query:cascade",
+      { keys: [smtpHostHandle.name] },
+      globexAdmin,
+    );
+    const cascade = res[smtpHostHandle.name];
+    expect(cascade?.value).toBe("smtp.platform.example");
+    expect(cascade?.source).toBe("default");
+  });
+
+  test("a system-row default cascades to every tenant", async () => {
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: smtpHostHandle.name, value: "smtp.system.example", scope: "system" },
+      systemAdmin,
+    );
+    const res = await stack.http.queryOk<Cascades>(
+      "config:query:cascade",
+      { keys: [smtpHostHandle.name] },
+      globexAdmin,
+    );
+    const cascade = res[smtpHostHandle.name];
+    expect(cascade?.value).toBe("smtp.system.example");
+    expect(cascade?.source).toBe("system-row");
+  });
+
+  test("a tenant override wins for its tenant and never leaks to another", async () => {
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: smtpHostHandle.name, value: "smtp.acme.example", scope: "tenant" },
+      acmeAdmin,
+    );
+
+    const acme = (
+      await stack.http.queryOk<Cascades>(
+        "config:query:cascade",
+        { keys: [smtpHostHandle.name] },
+        acmeAdmin,
+      )
+    )[smtpHostHandle.name];
+    expect(acme?.value).toBe("smtp.acme.example");
+    expect(acme?.source).toBe("tenant-row");
+
+    // Tenant B never set an override → still resolves the system-row default.
+    const globex = (
+      await stack.http.queryOk<Cascades>(
+        "config:query:cascade",
+        { keys: [smtpHostHandle.name] },
+        globexAdmin,
+      )
+    )[smtpHostHandle.name];
+    expect(globex?.value).toBe("smtp.system.example");
+    expect(globex?.source).toBe("system-row");
+  });
+});
+
+describe("feature contract — backing:secrets declares the secrets dependency", () => {
+  test("registry build rejects integrationsFeature without the secrets feature", () => {
+    // r.requires("secrets") is what makes this throw: without the dependency a
+    // consumer would only discover the missing tenant_secrets table at runtime.
+    // config is registered so the failure isolates the secrets requirement.
+    expect(() => createRegistry([createConfigFeature(), integrationsFeature])).toThrow(/secrets/);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Managed config — one declaration provisions everything a config key needs.
+//
+// Two keys, two backings, two scopes — same declarative surface:
+//
+//   payment-api-key  scope:"system"  backing:"secrets"   platform-owned secret
+//     → stored envelope-encrypted in the secrets store (system tenant), masked
+//       in every query, revealed only for the owning feature's ctx.config read.
+//
+//   smtp-host        scope:"tenant"  (config, plain)      per-tenant override
+//     → platform default (env/system-row) that a tenant admin can override;
+//       cascade resolves tenant-row → system-row → default.
+//
+// `mask` makes each key surface in the self-populating settings hub without a
+// hand-written r.screen / r.nav. `env` wires the platform default from an
+// environment variable at boot (runProdApp) — no manual AppConfigOverrides map.
+
+import {
+  access,
+  type ConfigKeyHandle,
+  createSystemConfig,
+  createTenantConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+const FEATURE = "integrations";
+
+export const paymentApiKeyHandle: ConfigKeyHandle<"text"> = {
+  name: `${FEATURE}:config:payment-api-key`,
+  type: "text",
+};
+
+export const smtpHostHandle: ConfigKeyHandle<"text"> = {
+  name: `${FEATURE}:config:smtp-host`,
+  type: "text",
+};
+
+export const integrationsFeature = defineFeature(FEATURE, (r) => {
+  r.requires("config");
+  // backing:"secrets" stores payment-api-key in the secrets envelope, which
+  // the secrets feature provisions — declare the dependency so registry-build
+  // enforces it instead of leaving a consumer to discover the missing
+  // tenant_secrets table at runtime.
+  r.requires("secrets");
+
+  r.config({
+    keys: {
+      // System-only secret: backing:"secrets" routes storage to the secrets
+      // envelope (KEK rotation + audit-on-read), never config_values. The
+      // boot-guard rejects backing:"secrets" on any non-system scope.
+      "payment-api-key": createSystemConfig("text", {
+        backing: "secrets",
+        write: access.systemAdmin,
+        read: access.admin,
+        mask: { title: "integrations.payment-api-key", icon: "credit-card", order: 1 },
+      }),
+      // Tenant override with a platform default. env seeds the default from
+      // SMTP_HOST at boot; a tenant admin overrides it per tenant.
+      "smtp-host": createTenantConfig("text", {
+        env: "SMTP_HOST",
+        default: "smtp.platform.example",
+        write: access.roles("SystemAdmin", "Admin"),
+        read: access.admin,
+        mask: { title: "integrations.smtp-host", icon: "mail", order: 2 },
+      }),
+    },
+  });
+
+  // Internal-read probe: the owning feature reads its own secrets-backed key
+  // via ctx.config and receives the revealed plaintext, never the mask.
+  r.queryHandler(
+    "peek-payment-key",
+    z.object({}),
+    async (_query, ctx) => {
+      if (!ctx.config) throw new Error("ctx.config not wired");
+      return { value: await ctx.config(paymentApiKeyHandle) };
+    },
+    { access: { roles: ["SystemAdmin"] } },
+  );
+
+  r.translations({
+    keys: {
+      "integrations.settings": { de: "Integrationen", en: "Integrations" },
+      "integrations.payment-api-key": { de: "Zahlungs-API-Schlüssel", en: "Payment API Key" },
+      "integrations.smtp-host": { de: "SMTP-Server", en: "SMTP Host" },
+    },
+  });
+});
+```