@cosmicdrift/kumiko-samples 0.369.0 → 0.371.0

package/samples/recipes/managed-config/README.md

@@ -69,6 +69,7 @@ const masterKeyProvider = createEnvMasterKeyProvider({ env: process.env });
 const resolver = createConfigResolver();
 
 await runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   extraContext: ({ db, registry }) => ({
     configResolver: resolver,
     _configAccessorFactory: createConfigAccessorFactory(registry, resolver),

package/samples/recipes/managed-pages/README.md

@@ -53,6 +53,7 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
 
 await runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   features: [
     createManagedPagesFeature({
       // Host → tenantId. Single-tenant returns a constant; multi-tenant maps

package/samples/recipes/prod-boot-options/README.md

@@ -0,0 +1,48 @@
+# Prod boot options
+
+Declare mail, KMS, file storage, demo mode, seeds and signal handling as
+`runProdApp` options instead of wiring them by hand in `bin/main.ts`. Each
+option mounts the matching bundled feature, reads its env block and fails
+the boot with a clear message when the env is incomplete.
+
+## What it shows
+
+- **`mail`**: `{ transport: "smtp-env" }` mounts `channel-email` with an
+  SMTP transport from `SMTP_*` and makes the auth mail flows use it.
+  `"inmemory"` is for dev and tests and is rejected in production.
+- **`kmsMode`**: `"required"` builds the KMS adapter and blind-index key from
+  `PLATFORM_KEK`, `SUBJECT_KEYS_DATABASE_URL` and `KUMIKO_BLIND_INDEX_KEY` and
+  aborts without them. `"optional"` uses them when present.
+  `{ plaintextReason }` stores PII in plaintext on purpose.
+- **`fileStorage`**: `{ provider: "auto" }` mounts the S3 provider when
+  `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY` and `S3_SECRET_KEY` are complete. In
+  production a partial S3 env aborts the boot; in dev it falls back to
+  in-memory storage.
+- **`demoMode`**: `GET /demo-mode` publishes the notice, and `readOnly: true`
+  answers every write except query and login with `403 demo_read_only`.
+- **`signals`**: SIGTERM and SIGINT run `stop()` with a drain timeout, then
+  exit 0, or exit 1 on timeout or error. `signals: false` leaves the process
+  signals to the host.
+- **`seeds`**: `{ demoTenant, demoAdminFromEnv, sysadminFromEnv, run }`
+  replaces hand-written tenant and admin seeds; needs the auth features (not
+  mounted here).
+- **`billing`**: `{ stripe: { priceToTier }, defaultTier }` mounts the Stripe
+  bridge and the tier-sync webhook route; needs `billing-foundation` and
+  `tier-engine`.
+
+## Flow
+
+1. `src/app.ts` lists the features and the boot options.
+2. `bin/server.ts` passes both to `runProdApp`.
+3. The test boots with `KUMIKO_DRY_RUN_ENV=boot`, which runs the full
+   validation and exits before any DB or Redis connection: a complete
+   production env passes, a partial S3 or missing KMS env aborts the boot,
+   and a missing `SMTP_HOST` shows up in the env inventory under
+   `runProdApp.mail`, because the options add their env blocks to the app's
+   `envSchema`.
+
+## Run
+
+```bash
+bun test samples/recipes/prod-boot-options
+```

package/samples/recipes/prod-boot-options/bin/server.ts

@@ -0,0 +1,11 @@
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { appFeatures, bootOptions } from "../src/app";
+
+const features = appFeatures();
+
+await runProdApp({
+  features,
+  envSchema: composeEnvSchema({ features }),
+  ...bootOptions(process.env),
+});

package/samples/recipes/prod-boot-options/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-prod-boot-options",
+  "description": "runProdApp boot options: mail, kmsMode, fileStorage, demoMode and signal handling declared as options instead of hand-wired in bin/main.ts.",
+  "private": true,
+  "scripts": {
+    "start": "bun bin/server.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-server-runtime": "workspace:*"
+  }
+}

package/samples/recipes/prod-boot-options/src/app.ts

@@ -0,0 +1,32 @@
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { createFileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import type { RunProdAppOptions } from "@cosmicdrift/kumiko-server-runtime";
+
+export function appFeatures(): RunProdAppOptions["features"] {
+  return [
+    createConfigFeature(),
+    createTenantFeature(),
+    createDeliveryFeature(),
+    createFileFoundationFeature(),
+  ];
+}
+
+type BootOptions = Pick<
+  RunProdAppOptions,
+  "mail" | "kmsMode" | "fileStorage" | "demoMode" | "signals"
+>;
+
+export function bootOptions(envSource: Record<string, string | undefined>): BootOptions {
+  return {
+    mail: { transport: "smtp-env", from: "Recipe <noreply@recipe.example>" },
+    kmsMode: "required",
+    fileStorage: { provider: "auto" },
+    demoMode: {
+      readOnly: envSource["DEMO_READ_ONLY"] === "true",
+      notice: { text: { en: "This demo is read-only.", de: "Diese Demo ist schreibgeschützt." } },
+    },
+    signals: { drainTimeoutMs: 20_000 },
+  };
+}

package/samples/recipes/security-baseline/README.md

@@ -1,6 +1,6 @@
 # Security baseline
 
-Mount `securityBaselineFeatures()` instead of hand-picking the four features
+Mount `composeSecurityStack()` 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
@@ -9,16 +9,19 @@ 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.
+- **`composeSecurityStack()`** (`@cosmicdrift/kumiko-dev-server/compose-stacks`) —
+  returns the four features in one call, fresh instances per call. It replaces
+  the deprecated `securityBaselineFeatures()` preset. `runProdApp` refuses to
+  boot it without a KMS decision (`kmsMode`) or with `rateLimit: false`; see
+  [`compose-stacks`](../compose-stacks/).
 - **`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()`
+  from the stack explicitly. Not required for combining with
+  `composeGdprStack({ selfService })`: both mount `createSessionsFeature()`
   with no-arg options, and the framework's `dedupeFeatures()` collapses the
   two identical instances at boot instead of throwing.
 
@@ -37,22 +40,22 @@ audit             → tenant-scoped audit trail
 
 ## When to reach for it
 
-Any app that also mounts `dsgvoSelfServiceFeatures()` — that preset already
+Any app that also mounts `composeGdprStack({ selfService })`, which 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";
+import { composeGdprStack, composeSecurityStack } from "@cosmicdrift/kumiko-dev-server/compose-stacks";
 
 export const APP_FEATURES = [
   // ...config, user, tenant, auth-foundation...
-  ...dsgvoSelfServiceFeatures(),
-  ...securityBaselineFeatures(),
+  ...composeGdprStack({ selfService: {} }),
+  ...composeSecurityStack(),
 ];
 ```
 
-For an app that does not mount `dsgvoSelfServiceFeatures()`, use
-`securityBaselineFeatures()` with its default options, as this recipe does.
+For an app without the self-service stack, use `composeSecurityStack()` 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
@@ -61,14 +64,14 @@ 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
+stack'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(),
+  ...composeSecurityStack(),
   // throws: Duplicate feature: "sessions" mounted twice with different
   // options — mount it once or pass identical options
 ];

package/samples/recipes/security-baseline/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@cosmicdrift/kumiko-sample-security-baseline",
-  "description": "securityBaselineFeatures() preset: sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing.",
+  "description": "composeSecurityStack(): sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing.",
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-dev-server": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
   }
 }

package/samples/recipes/security-baseline/src/feature.ts

@@ -1,13 +1,13 @@
 // Security-Baseline Sample
-// Shows: mounting securityBaselineFeatures() (sessions, crypto-shredding,
+// Shows: mounting composeSecurityStack() (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 { createAuthFoundationFeature } 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 { composeSecurityStack } from "@cosmicdrift/kumiko-dev-server/compose-stacks";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 
 export const APP_FEATURES: FeatureDefinition[] = [
@@ -15,5 +15,5 @@ export const APP_FEATURES: FeatureDefinition[] = [
   createUserFeature(),
   createTenantFeature(),
   createAuthFoundationFeature(),
-  ...securityBaselineFeatures(),
+  ...composeSecurityStack(),
 ];

package/packages/bundled-features/src/file-provider-s3-env/changes.json

@@ -1 +0,0 @@
-[]

package/packages/bundled-features/src/file-provider-s3-env/index.ts

@@ -1,8 +0,0 @@
-import { createFileProviderS3Feature } from "../file-provider-s3/index.js";
-
-/**
- * @deprecated Use createFileProviderS3Feature({ fromEnv: true }) from
- * `@cosmicdrift/kumiko-bundled-features/file-provider-s3`. Run `bun kumiko-upgrade --apply`.
- * Removed in the first release after 2026-10-29.
- */
-export const fileProviderS3EnvFeature = createFileProviderS3Feature({ fromEnv: true });

package/packages/bundled-features/src/files-provider-s3/changes.json

@@ -1 +0,0 @@
-[]

package/packages/bundled-features/src/files-provider-s3/index.ts

@@ -1,11 +0,0 @@
-/**
- * @deprecated Moved to `@cosmicdrift/kumiko-bundled-features/file-provider-s3/lib`. Run `bun kumiko-upgrade --apply`
- * to rewrite imports. Removed in the first release after 2026-10-29.
- */
-export {
-  createS3Provider,
-  createS3ProviderFromEnv,
-  parseS3EnvConfig,
-  resolveForcePathStyle,
-  type S3ProviderConfig,
-} from "../file-provider-s3/lib/index.js";