@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/encrypted-tenant-config.md

@@ -0,0 +1,405 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/encrypted-tenant-config. Do not edit. -->
+
+# encrypted-tenant-config
+
+Per-tenant secrets via config-key encryption — Stripe-API-key pattern.
+
+## README
+
+# Recipe: Encrypted per-tenant config
+
+**What this shows:** how a SaaS customer stores their own API key
+(Stripe, Slack webhook, SMTP password …) in their settings, without
+the platform operator being able to read the plaintext from the DB.
+
+## Pattern
+
+```ts illustration
+import { access, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine";
+
+createTenantConfig("text", {
+  encrypted: true,        // ← ciphertext in the DB
+  write: access.admin,    // ← the tenant admin writes their own
+  read: access.admin,     // ← nobody else sees it
+  mask: { title: "billing.stripe-api-key", order: 1 },  // ← derives the edit screen + nav
+});
+```
+
+The config resolver decrypts on the `ctx.config(handle)` call using
+the `EncryptionProvider` from `extraContext.configEncryption`. Anyone
+without the master key (= the `KUMIKO_SECRETS_MASTER_KEY_V<n>` env) only sees
+base64 AES ciphertext in the DB.
+
+The `mask` entry is all the UI needs: `buildConfigFeatureSchema` derives
+the `configEdit` screen (pre-filled from `config:query:values`, where the
+key comes back as `••••••`) **and** its Settings-Hub nav entry from the
+registered key — no hand-written `r.screen`/`r.nav`. `mask.title` is the
+i18n key of the field label, `mask.order` its position.
+
+## Use cases
+
+- **Per-tenant API keys** — Customer A uses THEIR Stripe account,
+  Customer B uses THEIRS. The platform operator never makes Stripe
+  calls on behalf of customers.
+- **Webhook secrets** — per-tenant Slack/Discord incoming webhook URL.
+- **SMTP credentials** — per-tenant mail server (see
+  `samples/showcases/publicstatus` Phase 2).
+
+## Vs. `r.secret` / `samples/recipes/secrets-demo`
+
+| Pattern | Scope | Use case |
+|---|---|---|
+| **`r.secret`** (envelope encryption, KEK rotation) | App-global | Platform-owned secrets (e.g. the master Stripe key that bills ALL customers). |
+| **`encrypted: true` config key** (this recipe) | Per-tenant | Customer-owned secrets. Customer sets, rotates, and never sees another customer's. Same envelope encryption + KEK keyring under the hood. |
+
+Combinable: the platform uses `r.secret` for its internal secrets,
+and in parallel customers have their tenant-owned `encrypted: true`
+config keys.
+
+## Boot wiring
+
+None. `runProdApp` / `runDevApp` wire the envelope cipher automatically as
+soon as a master key is present in the environment:
+
+```bash illustration
+KUMIKO_SECRETS_MASTER_KEY_V1=$(openssl rand -base64 32)
+```
+
+That single key drives `encrypted: true` config keys, `r.secret`, and
+encrypted entity fields — one keyring, one rotation story. Only tests or
+custom boots pass their own cipher:
+
+```ts illustration
+import { createConfigResolver } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+
+const cipher = createTestEnvelopeCipher();
+const configResolver = createConfigResolver({ cipher });
+// extraContext: { configResolver, configEncryption: cipher, ... }
+```
+
+## Flow
+
+1. Tenant admin sets `stripe-api-key` via `config:write:set` (scope tenant).
+2. DB row holds a JSON envelope (AES-GCM ciphertext + wrapped DEK + `kekVersion`) — backups and `SELECT` leak nothing.
+3. `config:query:values` returns `••••••` for the encrypted key in the UI.
+4. Domain handler calls `ctx.config(handle)` → decrypted value in-process.
+5. Tenant B cannot charge with Tenant A's key — per-tenant config row isolation.
+
+## Security guarantees
+
+1. **DB plaintext-free:** `SELECT value FROM config_values WHERE key = 'stripe-api-key'` returns ONLY ciphertext. Backup files, DB dumps, postgres eavesdropping → no plaintext leak.
+2. **UI mask:** `config:query:values` returns `"••••••"` for encrypted keys. Even the admin allowed to SET the value doesn't see it back. (If you need the value, go through `ctx.config(handle)` in the backend, not through the UI.)
+3. **Tenant isolation:** every tenant has its own entry — `(key, tenantId)` is unique in the config feature. Customer A NEVER sees Customer B's API key.
+
+## 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:
+
+- DB stores ciphertext, not plaintext
+- UI query masks encrypted values
+- Charge handler reads decrypted key and succeeds only when set
+- Tenant A's key does not leak to Tenant B
+- `mask` derives the `configEdit` screen without hand-written `r.screen`
+
+## Key rotation
+
+Config values carry their `kekVersion`, so rotation is operational, not
+cryptographic surgery:
+
+1. Add `KUMIKO_SECRETS_MASTER_KEY_V2` to the environment (old key stays).
+2. Set `KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION=2` — new writes use V2,
+   old rows still decrypt via the keyring.
+3. Trigger the manual `config:reencrypt` job — it re-encrypts every
+   encrypted config row onto the current version (and migrates any
+   pre-envelope legacy rows). Idempotent, chunked, circuit-breaker on
+   repeated failures.
+4. Only after the job reports `failed: 0` remove V1 from the environment.
+
+The same job doubles as the migration path away from the deprecated
+single-key `CONFIG_ENCRYPTION_KEY` format: keep the old env var as the
+decrypt fallback until the job has run once, then delete it.
+
+## What's not in this recipe
+
+- **Audit trail:** secrets-demo tracks every secret read as an event. Not here — config keys are meant as "settings" (read frequent, audit overkill).
+- **Backup encryption:** the `KUMIKO_SECRETS_MASTER_KEY_V<n>` keyring must be backed up alongside every backup, otherwise the DB is worthless after restore. Operator's job.
+
+## Related samples
+
+- [managed-config](/en/samples/recipes-managed-config/) — `backing: "secrets"`
+  for platform-owned keys + tenant cascade for SMTP defaults.
+- [apps-cap-billing-demo](/en/samples/apps-cap-billing-demo/) — billing
+  handlers that read per-tenant Stripe keys.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// End-to-End: Tenant-Admin setzt Stripe-API-Key → DB hat ciphertext →
+// charge-handler liest entschlüsselt → caller sieht charge-id, NIE den
+// Key. Plus: zwei Tenants haben getrennte Keys.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import {
+  configValuesTable,
+  createConfigAccessorFactory,
+  createConfigFeature,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { billingFeature, stripeApiKeyHandle } from "../feature";
+
+const TENANT_A = testTenantId(1);
+const TENANT_B = testTenantId(2);
+const acmeAdmin = { ...TestUsers.admin, tenantId: TENANT_A };
+const globexAdmin = { ...TestUsers.admin, tenantId: TENANT_B, id: "globex-admin" };
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  const resolver = createConfigResolver({ cipher: encryption });
+
+  stack = await setupTestStack({
+    features: [createConfigFeature(), billingFeature],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+afterAll(async () => stack?.cleanup());
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${configValuesTable.tableName}"`);
+});
+
+describe("encrypted tenant-config: per-tenant Stripe-API-key", () => {
+  test("DB hält ciphertext, NICHT plaintext", async () => {
+    const plaintextKey = "sk_live_super_secret_stripe_key_12345";
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: stripeApiKeyHandle.name, value: plaintextKey, scope: "tenant" },
+      acmeAdmin,
+    );
+
+    const rows = await selectMany(stack.db, configValuesTable, { key: stripeApiKeyHandle.name });
+    expect(rows.length).toBe(1);
+    const stored = rows[0]?.["value"];
+    expect(typeof stored).toBe("string");
+    expect(stored).not.toContain("sk_live");
+    expect(stored).not.toContain("12345");
+    expect(stored).not.toContain("super_secret");
+  });
+
+  test("config:query:values maskt encrypted-key mit ••••••", async () => {
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: stripeApiKeyHandle.name, value: "sk_live_xyz", scope: "tenant" },
+      acmeAdmin,
+    );
+    const cfg = await stack.http.queryOk<Record<string, { value: unknown; scope: string }>>(
+      "config:query:values",
+      {},
+      acmeAdmin,
+    );
+    expect(cfg[stripeApiKeyHandle.name]?.value).toBe("••••••");
+  });
+
+  test("charge-handler liest den entschlüsselten Key + nutzt ihn", async () => {
+    // Charge ohne gesetzten Key → schlägt mit klarer Error fehl
+    const noKey = await stack.http.write(
+      "billing:write:charge",
+      { amount: 1000, customerRef: "cust_42" },
+      acmeAdmin,
+    );
+    expect(noKey.status).toBeGreaterThanOrEqual(400);
+
+    // Key setzen → charge geht durch (mock-impl returnt charge-id)
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: stripeApiKeyHandle.name, value: "sk_live_acme", scope: "tenant" },
+      acmeAdmin,
+    );
+    const ok = await stack.http.writeOk<{ chargeId: string }>(
+      "billing:write:charge",
+      { amount: 1000, customerRef: "cust_42" },
+      acmeAdmin,
+    );
+    expect(ok.chargeId).toContain("cust_42");
+  });
+
+  test("Tenant-Isolation: Tenant-A's Key leakt NICHT zu Tenant-B", async () => {
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: stripeApiKeyHandle.name, value: "sk_live_acme_only", scope: "tenant" },
+      acmeAdmin,
+    );
+
+    // Tenant-B macht charge OHNE eigenen Key → fehlschlägt (sieht
+    // den acme-Key NICHT). Beweis: per-tenant config-row, nicht globale
+    // Variable.
+    const res = await stack.http.write(
+      "billing:write:charge",
+      { amount: 500, customerRef: "globex_cust" },
+      globexAdmin,
+    );
+    expect(res.status).toBeGreaterThanOrEqual(400);
+  });
+});
+```
+
+### src/__tests__/feature.test.ts
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { buildConfigFeatureSchema, createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { billingFeature, stripeApiKeyHandle } from "../feature";
+
+// The recipe's headline claim: the `mask` entry alone (no hand-written
+// r.screen/r.nav) makes buildConfigFeatureSchema derive the configEdit screen
+// for the key. If that derivation broke for this key name (e.g. after a
+// framework refactor), the recipe would silently stop showing the field — pin
+// it. Pure schema derivation, no DB/HTTP — moved out of feature.integration.test.ts (482/2).
+describe("encrypted tenant-config: mask derives the configEdit screen", () => {
+  test("buildConfigFeatureSchema produces billing-tenant with the qualified stripe key", () => {
+    const schema = buildConfigFeatureSchema(
+      createRegistry([createConfigFeature(), billingFeature]),
+    );
+    const screen = schema.screens.find((s) => s.id === "billing-tenant");
+    expect(screen).toBeDefined();
+    expect(screen?.type).toBe("configEdit");
+    if (screen?.type === "configEdit") {
+      expect(screen.configKeys).toEqual({ "stripe-api-key": stripeApiKeyHandle.name });
+      // mask.title flows through to the per-field label override.
+      expect(screen.fieldLabels).toEqual({ "stripe-api-key": "billing.stripe-api-key" });
+    }
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Encrypted per-tenant config — Stripe-API-key pattern.
+//
+// Minimal-Showcase: ein dummy "billing"-feature mit einem per-tenant
+// Stripe-API-Key. Der `mask`-Eintrag lässt den configEdit-Screen +
+// Settings-Hub-Nav automatisch entstehen (kein handgeschriebenes
+// r.screen/r.nav mehr). charge-handler liest den Key über ctx.config
+// (entschlüsselt automatisch).
+//
+// Production: nicht aufrufen — der echte Stripe-Call ist hier ein Mock.
+// Pattern in produktiven Apps: Strip-API-Key in tenantBillingConfig.key,
+// charge-handler lädt key + ruft tatsächlich Stripe.
+
+import {
+  access,
+  type ConfigKeyHandle,
+  createTenantConfig,
+  defineFeature,
+  defineWriteHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+const FEATURE = "billing";
+
+// Config-Key-Definition: encrypted=true → ciphertext in der DB. write/
+// read: access.admin damit nur Tenant-Admin den Key setzt + reads sind
+// nur backend-side via ctx.config (frontend sieht "••••••"). `mask` →
+// buildConfigFeatureSchema derivt Screen + Settings-Hub-Nav.
+const stripeApiKeyDef = createTenantConfig("text", {
+  encrypted: true,
+  write: access.admin,
+  read: access.admin,
+  // mask-derived screens carry no field constraints (maxLength, pattern) —
+  // set those separately in a configEdit schema if you need them enforced.
+  mask: { title: "billing.stripe-api-key", order: 1 },
+});
+
+const stripeApiKeyHandle: ConfigKeyHandle<"text"> = {
+  name: `${FEATURE}:config:stripe-api-key`,
+  type: "text",
+};
+
+// Charge-Handler — nutzt den entschlüsselten API-Key. Caller sieht NUR
+// die charge-id zurück, der Key bleibt server-side.
+const chargeHandler = defineWriteHandler({
+  name: "charge",
+  schema: z.object({
+    amount: z.number().positive(),
+    customerRef: z.string().min(1),
+  }),
+  access: { roles: ["Admin"] },
+  async handler(event, ctx) {
+    if (!ctx.config) {
+      return writeFailure(
+        new UnprocessableError("config_unavailable", {
+          i18nKey: "billing.errors.configUnavailable",
+        }),
+      );
+    }
+    const apiKey = await ctx.config(stripeApiKeyHandle);
+    if (!apiKey || apiKey.length === 0) {
+      return writeFailure(
+        new UnprocessableError("stripe_key_missing", {
+          i18nKey: "billing.errors.stripeKeyMissing",
+        }),
+      );
+    }
+
+    // Mock: real impl würde fetch("https://api.stripe.com/v1/charges",
+    // { headers: { Authorization: `Bearer ${apiKey}` }, ... }) ausführen.
+    // Wichtig: apiKey verlässt den server NICHT — kein log, kein
+    // response-field, kein error-detail.
+    const chargeId = `ch_${Date.now()}_${event.payload.customerRef}`;
+
+    return {
+      isSuccess: true as const,
+      data: { chargeId },
+    };
+  },
+});
+
+export const billingFeature = defineFeature(FEATURE, (r) => {
+  r.requires("config");
+  r.config("stripe-api-key", stripeApiKeyDef);
+  r.writeHandler(chargeHandler);
+  // Kein r.screen/r.nav: der `mask`-Eintrag auf dem Key lässt
+  // buildConfigFeatureSchema den configEdit-Screen (••••••-maskiert,
+  // config:write:set verschlüsselt vor dem write) + den Settings-Hub-Nav
+  // automatisch ableiten.
+
+  r.translations({
+    keys: {
+      "billing.settings": { de: "Abrechnung", en: "Billing" },
+      "billing.stripe-api-key": { de: "Stripe-API-Schlüssel", en: "Stripe API Key" },
+    },
+  });
+});
+
+// Re-exports damit tests die handles ohne re-typing nutzen können.
+export { stripeApiKeyHandle };
+```