@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/security-baseline.md

@@ -0,0 +1,187 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/security-baseline. Do not edit. -->
+
+# security-baseline
+
+securityBaselineFeatures() preset: sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing.
+
+## README
+
+# Security baseline
+
+Mount `securityBaselineFeatures()` instead of hand-picking the four features
+every prod app needs for basic account/security hygiene: `sessions`
+(revocable JWTs), `crypto-shredding` (operator-triggered subject-key erase),
+`rate-limiting` (ops-side bucket-status query, dispatcher wiring is
+automatic), and `audit` (tenant-scoped audit trail). Forgetting one of them
+used to be silent; now the boot validator warns at `NODE_ENV=production`.
+
+## What it shows
+
+- **`securityBaselineFeatures()`** (`@cosmicdrift/kumiko-bundled-features/presets`) —
+  returns the four features in one call, fresh instances per call.
+- **`warnOnMissingSecurityBaseline`** — wired into `validateBoot` (fw#2857).
+  At `NODE_ENV=production`, boot compares mounted feature names against
+  `SECURITY_BASELINE_FEATURE_NAMES` and logs a `console.warn` naming whatever
+  is missing. It never throws — the baseline is a strong recommendation, not
+  a hard requirement — and it is silent outside production.
+- **`includeSessions: false`** — an optional opt-out for dropping `sessions`
+  from the preset explicitly. Not required for combining with
+  `dsgvoSelfServiceFeatures()` any more: both mount `createSessionsFeature()`
+  with no-arg options, and the framework's `dedupeFeatures()` collapses the
+  two identical instances at boot instead of throwing.
+
+## Feature composition
+
+```
+config            → tenant's r.requires("config") dependency
+user              → cross-tenant identity (sessions' r.requires target)
+tenant            → memberships (audit's r.requires target)
+auth-foundation   → tokenVerifier extension point (sessions' r.requires target)
+sessions          → revocable JWTs
+crypto-shredding  → operator-triggered subject-key erase
+rate-limiting     → ops-side rate-limit status query
+audit             → tenant-scoped audit trail
+```
+
+## When to reach for it
+
+Any app that also mounts `dsgvoSelfServiceFeatures()` — that preset already
+mounts `sessions` as part of its own require-chain. Combine both directly;
+`dedupeFeatures()` collapses the two identical `sessions` instances at boot:
+
+```ts illustration
+import { dsgvoSelfServiceFeatures, securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/presets";
+
+export const APP_FEATURES = [
+  // ...config, user, tenant, auth-foundation...
+  ...dsgvoSelfServiceFeatures(),
+  ...securityBaselineFeatures(),
+];
+```
+
+For an app that does not mount `dsgvoSelfServiceFeatures()`, use
+`securityBaselineFeatures()` with its default options, as this recipe does.
+
+Dedupe keeps the first mounted instance. Late-bound state such as
+`bindAutoRevokeOnPasswordChange` must be bound on the instance returned by
+`composeFeatures`/`createApp`, not on a locally held handle to the dropped one:
+the dropped instance's hooks never run and password changes silently stop
+revoking sessions.
+
+A `createSessionsFeature({ ... })` mounted with different options than the
+preset's own no-arg instance still produces a clear boot error — dedupe only
+collapses provably interchangeable instances, never silently picks one:
+
+```ts illustration
+export const APP_FEATURES = [
+  // ...
+  createSessionsFeature({ expiresInMs: 1000 }),
+  ...securityBaselineFeatures(),
+  // throws: Duplicate feature: "sessions" mounted twice with different
+  // options — mount it once or pass identical options
+];
+```
+
+## Tests
+
+```bash
+bun test samples/recipes/security-baseline/src/__tests__/feature.test.ts
+```
+
+Three cases: `APP_FEATURES` boots clean; at `NODE_ENV=production` it produces
+no security-baseline warning; dropping `crypto-shredding`/`rate-limiting`/
+`audit` (`sessions` stays mounted — `auth-foundation`'s own bootCheck requires
+a sessionStore) at `NODE_ENV=production` produces exactly one warning and
+still does not throw.
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+// Security-Baseline Sample — Test
+// Proves: APP_FEATURES boots clean, and the NODE_ENV=production boot warning
+// fires only when the baseline features are missing, never for APP_FEATURES.
+
+import { describe, expect, spyOn, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { APP_FEATURES } from "../feature";
+
+function securityBaselineWarnings(calls: readonly unknown[][]): unknown[][] {
+  return calls.filter(
+    (call) => typeof call[0] === "string" && call[0].includes("security baseline"),
+  );
+}
+
+describe("security-baseline sample", () => {
+  test("APP_FEATURES boots without throwing", () => {
+    expect(() => validateBoot(APP_FEATURES)).not.toThrow();
+  });
+
+  test("NODE_ENV=production + APP_FEATURES → no security-baseline warning", () => {
+    const originalNodeEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      validateBoot(APP_FEATURES);
+      expect(securityBaselineWarnings(warnSpy.mock.calls)).toHaveLength(0);
+    } finally {
+      warnSpy.mockRestore();
+      if (originalNodeEnv === undefined) {
+        delete process.env["NODE_ENV"];
+      } else {
+        process.env["NODE_ENV"] = originalNodeEnv;
+      }
+    }
+  });
+
+  test("NODE_ENV=production + baseline features missing → warns but does not throw", () => {
+    const originalNodeEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    // Keep "sessions" mounted — auth-foundation's own bootCheck requires a
+    // tokenVerifier or sessionStore, and dropping it would fail boot for an
+    // unrelated reason before warnOnMissingSecurityBaseline ever runs.
+    const withoutBaseline = APP_FEATURES.filter(
+      (f) => !["crypto-shredding", "rate-limiting", "audit"].includes(f.name),
+    );
+
+    try {
+      expect(() => validateBoot(withoutBaseline)).not.toThrow();
+      expect(securityBaselineWarnings(warnSpy.mock.calls)).toHaveLength(1);
+    } finally {
+      warnSpy.mockRestore();
+      if (originalNodeEnv === undefined) {
+        delete process.env["NODE_ENV"];
+      } else {
+        process.env["NODE_ENV"] = originalNodeEnv;
+      }
+    }
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Security-Baseline Sample
+// Shows: mounting securityBaselineFeatures() (sessions, crypto-shredding,
+// rate-limiting, audit) and how it silences the NODE_ENV=production boot
+// warning that fires when one of those four is missing.
+
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/presets";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+export const APP_FEATURES: FeatureDefinition[] = [
+  createConfigFeature(),
+  createUserFeature(),
+  createTenantFeature(),
+  authFoundationFeature,
+  ...securityBaselineFeatures(),
+];
+```

package/agents/examples/seed-migration.md

@@ -0,0 +1,99 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/seed-migration. Do not edit. -->
+
+# seed-migration
+
+ES-Operations seed-migrations — file-based diff-and-apply für Aggregate-Updates die idempotent-Seeder nicht erfassen.
+
+## README
+
+# Seed-Migration
+
+File-based migrations for Event-Sourcing operations — like `kumiko schema apply`, but for aggregate-state-changes after the initial seed.
+
+## What it shows
+
+- **`seedsDir`-Option** in `runProdApp({ seedsDir: "./seeds" })` — beim Boot werden pending Files in chronologischer Reihenfolge angewendet und in `kumiko_es_operations` markiert.
+- **`SeedMigration`-Interface** — default-Export einer seed-File mit `description` + `run(ctx)`. ctx liefert `systemWriteAs` (System-User bypassed Access-Check) + Read-Helpers (`findUserByEmail`, `findMembershipsOfUser`, `findTenants`, `findTemplateResources`).
+- **Idempotency** — Marker landet nach Erfolg in der Tracking-Tabelle, zweiter Boot skipped applied Seeds.
+- **Tx-Atomicity** — Jede Migration läuft in eigener Transaction; Failure rollt zurück + bricht Boot ab (kein Partial-Apply).
+- **Chronologische File-IDs** — Filename `<date>-<slug>.ts` (z.B. `2026-05-20-fix-admin-roles.ts`) ist die ID.
+
+### Phase 1.5 hinzugefügt
+
+- **`tenantIdOverride`** in `ctx.systemWriteAs(qn, payload, tenantId)` — Pflicht wenn das Aggregate in einem Tenant-Stream lebt (sonst `version_conflict`).
+- **Dry-Run-Validator** — Runner parsed seed-files vor Run + checked alle handler-QNs gegen registry. camelCase-typos & andere QN-Drift werden BEFORE the write erkannt.
+- **`scripts/smoke.ts`** — copy-paste-Template für lokalen Pre-Push-Smoke. Bun-runnable, validiert Module-Load + QN-Resolution + Access offline. **Pflicht-Pattern vor Push.**
+- **Docker-COPY-Pflicht** dokumentiert in `framework/src/es-ops/README.md`.
+
+## Lokaler Smoke vor Push (Pflicht)
+
+```bash
+# Im App-Root:
+bun samples/recipes/seed-migration/scripts/smoke.ts --seeds-dir ./seeds
+```
+
+Erwarteter Output:
+```
+seed: 2026-05-20-fix-admin-roles.ts
+  ✓ loads: "ergänze TenantAdmin-Rolle"
+  ✓ "tenant:write:update-member-roles" registered + accessible
+
+✓ all 1 seed-file(s) pass smoke.
+```
+
+Bei typo / drift fail-t mit klarer message + exit-code 1 — CI nutzt es als prä-build-step. App-Author muss in `smoke.ts` den `features`-Array gegen die eigene App-Feature-Set tauschen (siehe TODO im File).
+
+### Archive template rows
+
+`findTemplateResources({ slug?, kind?, status?, locale?, tenantId? })` replaces a raw `SELECT … FROM read_template_resources`. It defaults to the system tenant and returns `[]` when template-resolver is not mounted:
+
+```ts
+for (const t of await ctx.findTemplateResources({ kind: "mail", status: "active" })) {
+  await ctx.systemWriteAs("template-resolver:write:archive", { id: t.id }, SYSTEM_TENANT_ID, [
+    "SystemAdmin",
+  ]);
+}
+```
+
+## When to reach for it
+
+Du hast einen idempotent-Seeder der bei initialer Erstellung „Insert wenn nicht existiert" macht (z.B. `auth.admin.memberships`), und dann ändern sich die Soll-Daten — neue Rolle, anderer Tier, korrigierte Bezeichnung. Idempotent-Seeder skippen die existing Rows → DB driftet vom Code-Stand ab.
+
+Seed-Migrations sind der saubere Fix: ein File schreibt das gewünschte Update einmalig in den Event-Store, Projection läuft automatisch.
+
+## Don't reach for it when
+
+- **Initial Seeding** (erste Daten beim leeren Stack). Dafür gibt es `r.config({seeds})` + `options.seeds`-Array — idempotent-by-design durch deterministische Aggregate-IDs.
+- **Schema-Migrations**. Dafür gibt es `kumiko schema generate`. Seed-migrations sind
+  Data-Layer, nicht Schema-Layer.
+- **Read-only Operationen / Reports**. Dafür gibt es App-spezifische Routes / Queries.
+
+## How it works
+
+1. Bei `runProdApp`-Boot scannt das Framework `seedsDir` nach `*.ts`-Files.
+2. SELECT `id` FROM `kumiko_es_operations` WHERE `operation_type='seed-migration'` → applied-Set.
+3. Pending = files-on-disk **minus** applied-set, sortiert chronologisch.
+4. Pro pending: Tx auf, `migration.run(ctx)` (kann beliebige Handler via `systemWriteAs` rufen), Marker einfügen, Tx commit.
+5. Failure → Tx rollback, kein Marker, Boot bricht ab. Operator fixt + Retry.
+
+## CLI
+
+```bash
+# Scaffold neue Migration mit Datum-Prefix
+bunx kumiko ops seed:new fix-admin-roles
+# → seeds/2026-05-20-fix-admin-roles.ts
+
+# Was applied, was pending
+bunx kumiko ops seed:status
+
+# (Phase 1.5) Direct apply ohne Boot
+bunx kumiko ops seed:apply [--dry-run]
+```
+
+## Skippable im Notfall
+
+Wenn eine kaputte Migration den Boot blockiert: setze `skippable: true` im seed-File und beim nächsten Boot `KUMIKO_SKIP_ES_OPS_<sanitized-id>=1` env-var. Marker wird nicht geschrieben → beim nächsten Boot ohne Flag würde der Seed wieder laufen. NICHT als Standard-Workflow — Recovery-only.
+
+## See also
+
+- **Driver-Use-Case:** `seeds/2026-02-01-fix-admin-roles.ts` in this recipe

package/agents/examples/session-revocation.md

@@ -0,0 +1,259 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/session-revocation. Do not edit. -->
+
+# session-revocation
+
+createSessionCallbacks + sessionChecker — server-side session revocation via JWT jti.
+
+## README
+
+# Sample: Session Revocation
+
+**I want JWTs to be revocable server-side — logout, password change, or admin force-logout should invalidate outstanding tokens before they expire.**
+
+## What this sample shows
+
+The production wiring shape: an app builds `createSessionCallbacks()` against a live DB handle, then hands the creator, revoker, and checker to `buildServer({ auth: ... })`. From there the framework handles the rest — login persists a `sid`, the middleware checks it on every request, logout flips the DB row, and a forged JWT without a matching session is rejected.
+
+## The wiring in 3 sentences
+
+1. `createSessionCallbacks({ db })` returns `sessionCreator`, `sessionRevoker`, and `sessionChecker` backed by `store_user_sessions`.
+2. `buildServer({ auth: { sessionCreator, sessionRevoker, sessionChecker, ... } })` links the JWT `jti` claim to that table on every request.
+3. After logout (or mass-revoke on password change), the same JWT returns 401 even though the signature is still valid.
+
+## What to copy into your app
+
+```ts illustration
+const db = createDbConnection(config.databaseUrl);
+const callbacks = createSessionCallbacks({ db });
+
+const server = buildServer({
+  registry: buildRegistry([
+    createSessionsFeature({
+      autoRevokeOnPasswordChange: callbacks.sessionMassRevoker,
+    }),
+    // ... other features
+  ]),
+  context: { db, /* ... */ },
+  jwtSecret: process.env.JWT_SECRET,
+  auth: {
+    membershipQuery: "tenant:query:memberships",
+    loginHandler: "auth-email-password:write:login",
+    sessionCreator: callbacks.sessionCreator,
+    sessionRevoker: callbacks.sessionRevoker,
+    sessionChecker: callbacks.sessionChecker,
+  },
+});
+```
+
+## Design rules
+
+1. **Sessions are a feature, not built-in.** Without `createSessionsFeature()` and wired callbacks, the app issues plain stateless JWTs — valid until expiry, no revocation path.
+2. **Storage is pluggable.** This sample uses the default DB-backed impl; swap in Redis or Memcached by implementing the same `SessionCreator` / `SessionRevoker` / `SessionChecker` signatures.
+3. **`jti` is the link.** When a checker is wired, the middleware never trusts the JWT alone — it confirms the session row is still live.
+
+## Tests
+
+- **End-to-end:** login → authenticated query → logout → same token rejected with 401
+- **Wiring contract:** copies the `buildServer({ auth: ... })` block from the sample comment verbatim
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Session Revocation Sample — Integration Test
+//
+// Drives the wiring from the sample's comment snippet end-to-end against
+// real HTTP + DB + Redis. If a reader copies the buildServer({...}) block
+// verbatim, the resulting app behaves like this test asserts.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  AuthHandlers,
+  createAuthEmailPasswordFeature,
+  hashPassword,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import {
+  configValuesTable,
+  createConfigFeature,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  type SessionCallbacks,
+  userSessionEntity,
+  userSessionTable,
+} from "@cosmicdrift/kumiko-bundled-features/sessions";
+import {
+  sessionCallbacksFromLateBound,
+  withMintedSession,
+} from "@cosmicdrift/kumiko-bundled-features/sessions/testing";
+import {
+  createTenantFeature,
+  tenantEntity,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { seedTenantMembership } from "@cosmicdrift/kumiko-bundled-features/tenant/seeding";
+import {
+  createUserFeature,
+  UserHandlers,
+  userEntity,
+  userTable,
+} from "@cosmicdrift/kumiko-bundled-features/user";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createLateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
+import * as jose from "jose";
+import { createSessionCallbacks, createSessionsFeature } from "../feature";
+
+const TENANT: TenantId = testTenantId(1);
+
+let stack: TestStack;
+const callbacks = createLateBoundHolder<SessionCallbacks>("session-callbacks");
+
+beforeAll(async () => {
+  const bound = sessionCallbacksFromLateBound(callbacks);
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthEmailPasswordFeature(),
+      authFoundationFeature,
+      createSessionsFeature(),
+    ],
+    authConfig: {
+      ...bound.asAuthConfig(),
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+    },
+  });
+  callbacks.set(createSessionCallbacks({ db: stack.db }));
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, userSessionEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userSessionTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+});
+
+describe("session-revocation sample wiring", () => {
+  test("end-to-end: login, use, logout, reject", async () => {
+    const hash = await hashPassword("super-long-password");
+    const actor = await withMintedSession(
+      (user, meta) => callbacks.get().sessionCreator(user, meta),
+      TestUsers.systemAdmin,
+    );
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      { email: "demo@example.com", passwordHash: hash, displayName: "Demo" },
+      actor,
+    );
+    await seedTenantMembership(stack.db, {
+      userId: created.id,
+      tenantId: TENANT,
+      roles: ["User"],
+    });
+
+    const loginRes = await stack.http.raw("POST", "/api/auth/login", {
+      email: "demo@example.com",
+      password: "super-long-password",
+    });
+    expect(loginRes.status).toBe(200);
+    const { token } = (await loginRes.json()) as { token: string };
+    expect(jose.decodeJwt(token).jti).toBeTypeOf("string");
+
+    const beforeLogout = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "user:query:user:me", payload: {} },
+      { Authorization: `Bearer ${token}` },
+    );
+    expect(beforeLogout.status).toBe(200);
+
+    const logout = await stack.http.raw("POST", "/api/auth/logout", undefined, {
+      Authorization: `Bearer ${token}`,
+    });
+    expect(logout.status).toBe(200);
+
+    const afterLogout = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "user:query:user:me", payload: {} },
+      { Authorization: `Bearer ${token}` },
+    );
+    expect(afterLogout.status).toBe(401);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Session Revocation Sample
+//
+// Shows the production-wiring shape: an app builds `createSessionCallbacks()`
+// against a live DB handle, then hands the creator/revoker/checker to
+// `buildServer({ auth: ... })`. From there the framework handles the rest —
+// login persists a sid, the middleware checks it on every request, logout
+// flips the DB row, a forged JWT without a matching session is rejected.
+//
+// What to copy into your own app:
+//
+//   const db = createDbConnection(config.databaseUrl);
+//   const callbacks = createSessionCallbacks({ db });
+//   const server = buildServer({
+//     registry: buildRegistry([
+//       // Pass the mass-revoker into the sessions feature to wire
+//       // "password-change signs you out everywhere" — the feature registers
+//       // a cross-feature entity-hook on the user entity that runs it.
+//       createSessionsFeature({
+//         autoRevokeOnPasswordChange: callbacks.sessionMassRevoker,
+//       }),
+//       // ... other features
+//     ]),
+//     context: { db, ... },
+//     jwtSecret: config.jwtSecret,
+//     auth: {
+//       membershipQuery: "tenant:query:memberships",
+//       loginHandler: "auth-email-password:write:login",
+//       sessionCreator: callbacks.sessionCreator,
+//       sessionRevoker: callbacks.sessionRevoker,
+//       sessionChecker: callbacks.sessionChecker,
+//     },
+//   });
+//
+// Design rules the sample demonstrates:
+//
+//  1. Sessions are a feature, not built-in. An app that doesn't register
+//     `createSessionsFeature()` (or doesn't wire callbacks) issues plain
+//     stateless JWTs — valid until expiry, no revocation path.
+//  2. Session storage is abstracted behind the three callback signatures.
+//     This sample uses the default DB-backed impl; you could swap in a
+//     Redis- or Memcached-backed version by wiring your own callbacks that
+//     match `SessionCreator`/`SessionRevoker`/`SessionChecker`.
+//  3. The `jti` claim on the JWT is the link between stateless token and
+//     stateful server. The middleware never trusts the JWT alone when a
+//     checker is wired — it confirms the sid is still live.
+
+export {
+  createSessionCallbacks,
+  createSessionsFeature,
+} from "@cosmicdrift/kumiko-bundled-features/sessions";
+```