@cosmicdrift/kumiko-framework 0.369.0 → 0.370.0

package/AGENTS.md

@@ -135,6 +135,7 @@ The scaffold (`bun create kumiko-app <name>`) produces this layout. Keep it.
 
 | Path | Content |
 | --- | --- |
+| `kumiko.config.ts` | `defineAppConfig({ features, prodFeatures?, client, ports })`: the one list the tooling reads |
 | `src/run-config.ts` | `APP_FEATURES`, the mounted feature list |
 | `src/features/<name>/feature.ts` | `defineFeature(...)` with entities, handlers, screens, navs |
 | `src/features/<name>/index.ts` | Public exports of the feature |
@@ -143,7 +144,17 @@ The scaffold (`bun create kumiko-app <name>`) produces this layout. Keep it.
 | `src/__tests__/*.test.ts` | Unit tests, no services |
 | `src/__tests__/*.integration.test.ts` | Integration tests against Postgres and Redis |
 | `e2e/*.spec.ts` | Playwright tests against a booted app |
-| `kumiko/schema.ts`, `kumiko/migrations/` | Database schema and generated migrations |
+| `kumiko/schema.ts`, `kumiko/migrations/` | Generated schema shim over `kumiko.config.ts`, and the migrations |
+| `bin/server.ts`, `bin/main.ts`, `bin/env-schema.ts` | Dev server, production boot, env contract |
+| `e2e/_helpers/`, `src/__tests__/_setup.ts` | Shared e2e helpers and the shared integration stack setup |
+
+Files whose first line reads `kumiko-managed` (deploy/, `.github/workflows/`,
+`.husky/pre-push`, the bunfigs, `kumiko/schema.ts`) belong to the framework.
+`bun run check` reports drift against the installed version and
+`bunx kumiko sync-managed --write` restores them. Keep a deliberate change with
+`# kumiko-managed: local <reason>` on line 2. `biome.json` and `tsconfig.json`
+extend `@cosmicdrift/kumiko-framework/biome` and `.../tsconfig.app.json`; put
+app overrides next to `extends`. Full list: `docs/reference/app-skeleton.md`.
 
 The scaffolded `src/features/tasks/feature.ts` and
 `src/__tests__/tasks.integration.test.ts` are the smallest complete pair of
@@ -155,6 +166,8 @@ feature and test. Start from them.
 | --- | --- |
 | Run the app with demo data | `bun dev` |
 | Boot validation without serving | `bun run boot` |
+| Boot, guards, managed files and script standard | `bun run check` |
+| Restore framework-owned files | `bunx kumiko sync-managed --write` |
 | Types | `bun run typecheck` |
 | Lint | `bun run lint` |
 | Unit tests | `bun run test` |

package/agents/examples/apex-surface-auth.md

@@ -81,6 +81,7 @@ anonymous **email-verified** deletion flow from `user-data-rights`:
 
 ```ts illustration
 runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   features: composeApexAccountApp({
     deletionTokenSecret: process.env.DELETION_TOKEN_SECRET!,
     deletionVerifyUrl: "https://app.example.com/delete-account/confirm",
@@ -299,7 +300,7 @@ describe("apex-surface-auth recipe", () => {
 // SERVER-WIRING: die App aktiviert `anonymousAccess` (defaultTenantId = der
 // Apex-Host-Tenant), damit /api/write die anonymen Deletion-Handler erreicht:
 //
-//   runProdApp({ features: composeApexAccountApp({...}),
+//   runProdApp({ features: composeApexAccountApp({...}), envSchema,
 //                anonymousAccess: { defaultTenantId: APEX_TENANT_ID } })
 
 import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";

package/agents/examples/app-config.md

@@ -0,0 +1,98 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/app-config. Do not edit. -->
+
+# app-config
+
+kumiko.config.ts with defineAppConfig: the one feature list, client entries and ports the tooling reads.
+
+## README
+
+# App config
+
+`kumiko.config.ts` is the one place an app names its features, client entries
+and ports. `kumiko/schema.ts`, `kumiko agent lint`, `kumiko check` and
+`kumiko ports` all read it.
+
+## What it shows
+
+- **`defineAppConfig`** from `@cosmicdrift/kumiko-framework/config` validates the
+  config when the file loads: ports in range and unique within the app, client
+  entries relative and inside the app.
+- **`prodFeatures`** are mounted only in production (provider features such as
+  S3 or SMTP). `allAppFeatures(config)` returns `features` plus `prodFeatures`;
+  that is the list migrations and agent lint check.
+- **`ports`** with `dev`, `e2e` and optional `infra` (`postgres`, `redis`,
+  `meilisearch`, `s3`). Keep them number literals: `kumiko ports` reads them
+  statically across all apps of a workspace and reports collisions.
+
+## Files
+
+```
+kumiko.config.ts                  defineAppConfig with features, prodFeatures, client, ports
+src/feature.ts                    two placeholder features
+src/__tests__/app-config.test.ts  feature list, port list, validation errors
+```
+
+See [`docs/reference/app-skeleton.md`](../../../docs/reference/app-skeleton.md)
+for the files around it.
+
+## Source files
+
+### src/__tests__/app-config.test.ts
+
+```ts
+import { describe, expect, test } from "bun:test";
+import {
+  allAppFeatures,
+  defineAppConfig,
+  findAppPortProblems,
+  listAppPorts,
+} from "@cosmicdrift/kumiko-framework/config";
+import appConfig from "../../kumiko.config";
+import { notesFeature } from "../feature";
+
+describe("kumiko.config.ts", () => {
+  test("schema, agent lint and boot see features plus prodFeatures", () => {
+    expect(allAppFeatures(appConfig).map((feature) => feature.name)).toEqual([
+      "notes",
+      "audit-export",
+    ]);
+  });
+
+  test("ports list every claim, infrastructure included", () => {
+    expect(listAppPorts(appConfig.ports)).toEqual([
+      { role: "dev", port: 4510 },
+      { role: "e2e", port: 4511 },
+      { role: "postgres", port: 15510 },
+    ]);
+  });
+
+  test("defineAppConfig rejects a port claimed twice inside the app", () => {
+    const ports = { dev: 4510, e2e: 4510 };
+    expect(findAppPortProblems(ports)).not.toEqual([]);
+    expect(() =>
+      defineAppConfig({ features: [notesFeature], client: { entries: ["src/client.tsx"] }, ports }),
+    ).toThrow();
+  });
+
+  test("client entries must stay inside the app", () => {
+    expect(() =>
+      defineAppConfig({
+        features: [notesFeature],
+        client: { entries: ["../other-app/src/client.tsx"] },
+        ports: { dev: 4510, e2e: 4511 },
+      }),
+    ).toThrow();
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const notesFeature = defineFeature("notes", () => {});
+
+// Stands in for a provider feature that only production mounts (S3, SMTP).
+export const auditExportFeature = defineFeature("audit-export", () => {});
+```

package/agents/examples/auth-mfa.md

@@ -61,6 +61,19 @@ const server = buildServer({
 
 Apps built via `runDevApp`/`runProdApp` (the dev-server bootstrap used by `create-kumiko-app`) get all of this automatically — just add `createAuthMfaFeature(...)` to `APP_FEATURES`. `composeFeatures` threads the status-checker and the bootstrap wires the session-revoke bind and the verify route for you. This sample shows the raw contract those helpers implement.
 
+## Self-service screen
+
+`createAccountSecurityFeature({ nav?, access? })` adds one screen,
+`account-security:screen:account-security`, that embeds the MFA enable,
+regenerate and disable screens plus the own-sessions list. It owns no handlers
+and needs no `composeAuthStack`: mount it next to `auth-mfa` and `sessions`.
+Without `nav` the screen stays dormant (reachable by its route, no sidebar
+entry); `access` defaults to every signed-in user.
+
+```ts illustration
+features: [..., createSessionsFeature(), mfaFeature, createAccountSecurityFeature({ nav: { order: 90 } })]
+```
+
 ## Design rules
 
 1. **Enrollment is stateless until confirmed.** `enable-start` returns a signed setup token (QR + secret + 8 recovery codes) — nothing is persisted until `enable-confirm` proves the user scanned it with a valid TOTP code.
@@ -74,9 +87,61 @@ Apps built via `runDevApp`/`runProdApp` (the dev-server bootstrap used by `creat
 
 - **Baseline:** a user without MFA enrolled still gets a JWT straight from `/auth/login`.
 - **End-to-end:** enroll via `enable-start`/`enable-confirm`, log in (gets a challenge, no JWT), complete via `/auth/mfa/verify` (gets a JWT) — copies the `buildServer({ auth: ... })` block from the sample comment verbatim.
+- **Account security:** the composed screen boot-validates next to `auth-mfa` and `sessions` and shows a sidebar entry once `nav` is set.
 
 ## Source files
 
+### src/__tests__/account-security.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-testing/helpers";
+import {
+  ACCOUNT_SECURITY_SCREEN_QN,
+  createAccountSecurityFeature,
+  createAuthMfaFeature,
+} from "../feature";
+
+const mfaFeature = createAuthMfaFeature({
+  setupTokenSecret: "sample-setup-token-secret-not-for-prod",
+  challengeTokenSecret: "sample-mfa-challenge-secret-at-least-32-bytes",
+  issuer: "Kumiko Sample",
+});
+
+describe("account-security next to auth-mfa", () => {
+  // user-mfa has encrypted fields, so boot validation needs a cipher.
+  beforeAll(() => configureEntityFieldEncryption(createTestEnvelopeCipher()));
+  afterAll(() => configureEntityFieldEncryption(undefined));
+
+  test("boot-validates without composeAuthStack and adds a sidebar entry with nav", () => {
+    const accountSecurity = createAccountSecurityFeature({ nav: { order: 90 } });
+    expect(() =>
+      validateBoot([
+        createConfigFeature(),
+        createUserFeature(),
+        createTenantFeature(),
+        createAuthFoundationFeature(),
+        createPersonalAccessTokensFeature({ scopes: {} }),
+        createSessionsFeature(),
+        mfaFeature,
+        accountSecurity,
+      ]),
+    ).not.toThrow();
+    expect(Object.values(accountSecurity.navs).map((nav) => nav.screen)).toEqual([
+      ACCOUNT_SECURITY_SCREEN_QN,
+    ]);
+  });
+});
+```
+
 ### src/__tests__/feature.integration.test.ts
 
 ```ts
@@ -306,6 +371,13 @@ describe("auth-mfa sample wiring", () => {
 //     complete exactly one login challenge, then it's burned.
 //  4. Every MFA state change signs out every OTHER live session (stolen-
 //     session defense) — but never the session that made the change.
+
+// One self-service screen for MFA and own sessions. Dormant until `nav` is
+// set, so apps that mount it only for deep links get no sidebar entry.
+export {
+  ACCOUNT_SECURITY_SCREEN_QN,
+  createAccountSecurityFeature,
+} from "@cosmicdrift/kumiko-bundled-features/account-security";
 export {
   AuthMfaHandlers,
   base32Decode,

package/agents/examples/compose-stacks.md

@@ -0,0 +1,188 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/compose-stacks. Do not edit. -->
+
+# compose-stacks
+
+compose*Stack helpers for auth, security, GDPR and SaaS billing, and the runProdApp check that names a stack whose boot option is missing.
+
+## README
+
+# Compose stacks
+
+Mount the auth, security, GDPR and SaaS features through the `compose*Stack`
+helpers from `@cosmicdrift/kumiko-dev-server/compose-stacks` instead of
+listing each feature and its require order by hand. A stack that depends on a
+`runProdApp` option marks that on its features (`bootRequires`), and
+`runProdApp` refuses to boot when the option is missing, naming the stack and
+the option.
+
+## What it shows
+
+- **`composeAuthStack({ mfa, sessions })`**: `auth-foundation`, `sessions`,
+  and with `mfa` also `auth-mfa` plus `account-security`. The password login
+  itself still comes from the `auth` option or `composeFeatures`.
+- **`composeSecurityStack({ includeSessions })`**: `sessions`,
+  `crypto-shredding`, `rate-limiting` and `audit`. Needs a KMS decision
+  (`kmsMode`) and fails with `rateLimit: false`. Replaces
+  `securityBaselineFeatures()`.
+- **`composeGdprStack({ tenantLifecycle, selfService })`**: `data-retention`
+  and `compliance-profiles`, optionally `tenant-lifecycle`. `selfService` adds
+  `sessions`, `user-data-rights` and `user-profile` (needs `mail`) and
+  replaces `dsgvoSelfServiceFeatures()`.
+- **`composeSaasStack({ billing, tiers, caps, waitlist })`**:
+  `billing-foundation` and `tier-engine`, plus `cap-counter`/`cap-overview`
+  and `waitlist` when configured. `billing: "stripe"` leaves
+  `subscription-stripe` to the `billing` boot option, which also mounts the
+  tier-sync webhook route; `billing: "mollie"` mounts `subscription-mollie`
+  itself.
+
+## Boot requirements
+
+| Stack | Boot option | Also satisfied by |
+| --- | --- | --- |
+| `composeMailStack` | `mail` | a mounted `channel-email` |
+| `composeFileStack` without providers | `fileStorage` | a mounted file provider |
+| `composeGdprStack` | `kmsMode` | `kms` or `allowPlaintextPii` |
+| `composeGdprStack({ selfService })`, `composeUserDataRightsStack` | `mail` | a mounted `channel-email` |
+| `composeSecurityStack` | `kmsMode`, `rateLimit` not `false` | `kms` or `allowPlaintextPii` |
+| `composeSaasStack({ billing: "stripe" })` | `billing` | a mounted subscription provider |
+
+A missing option fails the boot with:
+
+```
+[runProdApp] stacks in `features` need boot options that are not set:
+  - composeSaasStack needs the boot option `billing`: set billing: { stripe: { priceToTier }, defaultTier }
+```
+
+## Flow
+
+1. `src/app.ts` lists the stacks and the boot options they need.
+2. The test boots with `KUMIKO_DRY_RUN_ENV=boot`, which runs the whole
+   validation and stops before any DB or Redis connection: with the options
+   the boot passes, without `billing` or `kmsMode` it fails and names the
+   stacks.
+
+## Tests
+
+```bash
+bun test samples/recipes/compose-stacks
+```
+
+## Source files
+
+### src/__tests__/app.test.ts
+
+```ts
+// KUMIKO_DRY_RUN_ENV=boot runs the full wiring check and stops before any
+// DB/Redis connection, so the stack requirements are checked without infra.
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { type RunProdAppOptions, runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { appFeatures, bootOptions } from "../app";
+
+const PRODUCTION_BOOT_ENV: Readonly<Record<string, string>> = {
+  DATABASE_URL: "postgres://recipe:recipe@127.0.0.1:1/recipe",
+  REDIS_URL: "redis://127.0.0.1:1",
+  JWT_SECRET: "r".repeat(32),
+  KUMIKO_DRY_RUN_ENV: "boot",
+  NODE_ENV: "production",
+  PLATFORM_KEK: randomBytes(32).toString("base64"),
+  SUBJECT_KEYS_DATABASE_URL: "postgres://kms:kms@127.0.0.1:1/subject_keys",
+  KUMIKO_BLIND_INDEX_KEY: randomBytes(32).toString("base64"),
+};
+
+async function bootValidate(options: Pick<RunProdAppOptions, "kmsMode" | "billing">) {
+  const handle = await runProdApp({
+    features: appFeatures(),
+    envSchema: composeEnvSchema({ features: [] }),
+    autoListen: false,
+    migrations: false,
+    envSource: { ...PRODUCTION_BOOT_ENV },
+    ...options,
+  });
+  await handle.stop();
+}
+
+describe("compose stacks recipe", () => {
+  let logSpy: ReturnType<typeof spyOn>;
+  let warnSpy: ReturnType<typeof spyOn>;
+  beforeEach(() => {
+    logSpy = spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    logSpy.mockRestore();
+    warnSpy.mockRestore();
+  });
+
+  test("the stacks with their boot options pass boot validation", async () => {
+    await bootValidate(bootOptions());
+    const lines = logSpy.mock.calls.map((call: unknown[]) => String(call[0]));
+    expect(lines.some((line: string) => line.includes("boot validation OK"))).toBe(true);
+  });
+
+  test("a missing billing option names composeSaasStack and the option", async () => {
+    const { billing: _billing, ...withoutBilling } = bootOptions();
+    await expect(bootValidate(withoutBilling)).rejects.toThrow(
+      "composeSaasStack needs the boot option `billing`",
+    );
+  });
+
+  test("a missing KMS decision names every stack that needs it", async () => {
+    const { kmsMode: _kmsMode, ...withoutKms } = bootOptions();
+    const failure = bootValidate(withoutKms);
+    await expect(failure).rejects.toThrow("composeSecurityStack needs the boot option `kmsMode`");
+    await expect(failure).rejects.toThrow("composeGdprStack needs the boot option `kmsMode`");
+  });
+});
+```
+
+### src/app.ts
+
+```ts
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import {
+  composeAuthStack,
+  composeGdprStack,
+  composeSaasStack,
+  composeSecurityStack,
+} from "@cosmicdrift/kumiko-dev-server/compose-stacks";
+import type { RunProdAppOptions } from "@cosmicdrift/kumiko-server-runtime";
+
+export const PRO_PRICE_ID = "price_pro_monthly";
+
+export function appFeatures(): RunProdAppOptions["features"] {
+  return [
+    createConfigFeature(),
+    createSecretsFeature(),
+    createUserFeature(),
+    createTenantFeature(),
+    ...composeAuthStack(),
+    ...composeSecurityStack(),
+    ...composeGdprStack({ tenantLifecycle: true }),
+    ...composeSaasStack({
+      billing: "stripe",
+      tiers: {
+        defaultTier: "free",
+        tierMap: {
+          free: { features: [], caps: { seats: 1 } },
+          pro: { features: [], caps: { seats: 25 } },
+        },
+      },
+    }),
+  ];
+}
+
+type StackBootOptions = Pick<RunProdAppOptions, "kmsMode" | "billing">;
+
+export function bootOptions(): StackBootOptions {
+  return {
+    kmsMode: "required",
+    billing: { stripe: { priceToTier: { [PRO_PRICE_ID]: "pro" } }, defaultTier: "free" },
+  };
+}
+```