@cosmicdrift/kumiko-framework 0.369.0 → 0.370.0

package/agents/examples/prod-boot-options.md

@@ -0,0 +1,180 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/prod-boot-options. Do not edit. -->
+
+# prod-boot-options
+
+runProdApp boot options: mail, kmsMode, fileStorage, demoMode and signal handling declared as options instead of hand-wired in bin/main.ts.
+
+## README
+
+# 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
+```
+
+## Source files
+
+### src/__tests__/boot-options.test.ts
+
+```ts
+// KUMIKO_DRY_RUN_ENV=boot validates the whole wiring and exits before any
+// DB/Redis connection, so the recipe's options 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 { 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",
+  SMTP_HOST: "smtp.recipe.example",
+  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"),
+  S3_BUCKET: "recipe",
+  S3_REGION: "eu-central",
+  S3_ACCESS_KEY: "access",
+  S3_SECRET_KEY: "secret",
+};
+
+function withoutKey(key: string): Record<string, string> {
+  const { [key]: _dropped, ...rest } = PRODUCTION_BOOT_ENV;
+  return rest;
+}
+
+async function bootValidate(envSource: Record<string, string>): Promise<void> {
+  const features = appFeatures();
+  const handle = await runProdApp({
+    features,
+    envSchema: composeEnvSchema({ features: [] }),
+    autoListen: false,
+    migrations: false,
+    envSource,
+    ...bootOptions(envSource),
+  });
+  await handle.stop();
+}
+
+describe("prod boot options 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("a complete production env passes boot validation", async () => {
+    await bootValidate({ ...PRODUCTION_BOOT_ENV });
+    const lines = logSpy.mock.calls.map((call: unknown[]) => String(call[0]));
+    expect(lines.some((line: string) => line.includes("boot validation OK"))).toBe(true);
+  });
+
+  test("an incomplete S3 env aborts the production boot", async () => {
+    await expect(bootValidate(withoutKey("S3_BUCKET"))).rejects.toThrow(/S3_BUCKET/);
+  });
+
+  test("the dry run reports a missing SMTP host from the mail option's env block", async () => {
+    await bootValidate(withoutKey("SMTP_HOST"));
+    const lines = logSpy.mock.calls.map((call: unknown[]) => String(call[0]));
+    const inventory = lines.find((line: string) => line.startsWith("Env check")) ?? "";
+    expect(inventory).toMatch(/SMTP_HOST\s+runProdApp\.mail\s+required\s+.*missing/i);
+    expect(lines.some((line: string) => line.includes("boot validation OK"))).toBe(false);
+  });
+
+  test("a missing KMS trio aborts the boot under kmsMode required", async () => {
+    const envSource = withoutKey("PLATFORM_KEK");
+    delete envSource["SUBJECT_KEYS_DATABASE_URL"];
+    delete envSource["KUMIKO_BLIND_INDEX_KEY"];
+    await expect(bootValidate(envSource)).rejects.toThrow(/kmsMode "required"/);
+  });
+});
+```
+
+### src/app.ts
+
+```ts
+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/agents/examples/relations.md

@@ -41,6 +41,7 @@ import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createCascadeDeleteHook } from "@cosmicdrift/kumiko-framework/pipeline";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
+import { createTestStoredEvent } from "@cosmicdrift/kumiko-testing/helpers";
 import {
   setupTestStack,
   type TestStack,
@@ -101,6 +102,7 @@ describe("restrict: team cannot be deleted with members", () => {
           id: team.id,
           data: { tenantId: "00000000-0000-4000-8000-000000000001" },
           entityName: "team",
+          event: createTestStoredEvent(),
         },
         { db: stack.db },
       ),
@@ -123,6 +125,7 @@ describe("restrict: team cannot be deleted with members", () => {
           id: team.id,
           data: { tenantId: "00000000-0000-4000-8000-000000000001" },
           entityName: "team",
+          event: createTestStoredEvent(),
         },
         { db: stack.db },
       ),
@@ -172,6 +175,7 @@ describe("cascade: deleting member removes tasks", () => {
         id: member.id,
         data: { tenantId: "00000000-0000-4000-8000-000000000001" },
         entityName: "member",
+        event: createTestStoredEvent(),
       },
       { db: stack.db },
     );

package/agents/examples/secrets-demo.md

@@ -53,6 +53,8 @@ import { createJobsFeature } from "@cosmicdrift/kumiko-bundled-features/jobs";
 import {
   createSecretsContext,
   createSecretsFeature,
+  SecretsHandlers,
+  SecretsQueries,
   type StoredEnvelope,
   TENANT_SECRET_READ_EVENT,
   tenantSecretsTable,
@@ -167,7 +169,7 @@ afterAll(async () => {
 describe("1. at-rest representation", () => {
   test("set stores envelope only — plaintext nowhere in the row", async () => {
     await stack.http.writeOk(
-      "secrets:write:set",
+      SecretsHandlers.set,
       { key: STRIPE_API_KEY.name, value: "sk_test_SuperSecretLivePlatz12345" },
       tenantAdmin,
     );
@@ -190,7 +192,7 @@ describe("2. list shows preview only", () => {
   test("redactedPreview uses billing's domain-aware redact function", async () => {
     const list = await stack.http.queryOk<
       Array<{ key: string; redactedPreview: string | null; kekVersion: number }>
-    >("secrets:query:list", {}, tenantAdmin);
+    >(SecretsQueries.list, {}, tenantAdmin);
 
     const stripe = list.find((r) => r.key === STRIPE_API_KEY.name);
     expect(stripe).toBeDefined();

package/agents/examples/security-baseline.md

@@ -2,13 +2,13 @@
 
 # security-baseline
 
-securityBaselineFeatures() preset: sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing.
+composeSecurityStack(): 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
+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
@@ -17,16 +17,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.
 
@@ -45,22 +48,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
@@ -69,14 +72,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
 ];
@@ -166,15 +169,15 @@ describe("security-baseline sample", () => {
 
 ```ts
 // 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[] = [
@@ -182,6 +185,6 @@ export const APP_FEATURES: FeatureDefinition[] = [
   createUserFeature(),
   createTenantFeature(),
   createAuthFoundationFeature(),
-  ...securityBaselineFeatures(),
+  ...composeSecurityStack(),
 ];
 ```

package/agents/examples.md

@@ -10,6 +10,7 @@
 | `apex-landing` | Apex landing page composed from other features — hero copy from template-resolver, prices and caps from tier-engine — rendered to one static HTML string. | `examples/apex-landing.md` |
 | `apex-surface-auth` | Apex-Surface: öffentliche Account-Flows (Login/Register/PW/Löschen) via createPublicSurface + AuthShell, inkl. anonymem email-verifiziertem Deletion-Flow. | `examples/apex-surface-auth.md` |
 | `api-worker-split` | Split deploy topology: API process (runSingleInstance:false, enqueue-only) + worker process (consumes worker-lane jobs, applies multiStreamProjections, writes results back through the worker dispatcher). | `examples/api-worker-split.md` |
+| `app-config` | kumiko.config.ts with defineAppConfig: the one feature list, client entries and ports the tooling reads. | `examples/app-config.md` |
 | `auth-claims` | r.authClaims() — features contribute identity facts into the JWT at login time with auto-prefixed keys. | `examples/auth-claims.md` |
 | `auth-foundation-providers` | Register custom tenantResolver / tenantExistence via auth-foundation extension points (no anonymousAccess callbacks). | `examples/auth-foundation-providers.md` |
 | `auth-mfa` | createAuthMfaFeature — TOTP/2FA enrollment, login challenge, and recovery codes wired into auth-email-password. | `examples/auth-mfa.md` |
@@ -17,6 +18,7 @@
 | `boot-check` | A feature declares its own mount-invariant via r.bootCheck. | `examples/boot-check.md` |
 | `chat-channels` | Chat channels. Delivery notifications to Slack, minus the browser tab. | `examples/chat-channels.md` |
 | `compliance-profiles-demo` | Two-tenant demo: EU + Swiss compliance profiles deliver different authority contacts, languages, and grace periods through the same App-code. | `examples/compliance-profiles-demo.md` |
+| `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. | `examples/compose-stacks.md` |
 | `cross-feature-events` | Feature appends a typed domain event via ctx.appendEvent; a r.multiStreamProjection reacts asynchronously. | `examples/cross-feature-events.md` |
 | `crypto-shredding-hr` | Crypto-shredding: PII fields encrypted per subject key; forgetting the subject erases the key and every field it protected. | `examples/crypto-shredding-hr.md` |
 | `currencies-global` | Shared money fields across tenants. Commas still matter. | `examples/currencies-global.md` |
@@ -30,12 +32,14 @@
 | `embedded` | Embedded fields on entities. Structured JSON without the JSON part. | `examples/embedded.md` |
 | `embedded-entity-form` | RenderEdit hosted in a Drawer, no screen or route — externally-sourced prefill, controlled mode, and a custom write handler instead of the built-in CRUD create. | `examples/embedded-entity-form.md` |
 | `encrypted-tenant-config` | Per-tenant secrets via config-key encryption — Stripe-API-key pattern. | `examples/encrypted-tenant-config.md` |
+| `env-composition` | Typed app env from the env blocks bundled features register, plus app-level blocks in extend. | `examples/env-composition.md` |
 | `error-contract` | Typed errors on the wire. With snake_case reasons, because we care. | `examples/error-contract.md` |
 | `event-sourcing` | Production-pattern ES sample: r.defineEvent (versioned + migrations) + ctx.appendEvent + r.projection + r.multiStreamProjection + ctx.loadAggregate (asOf) + ctx.archiveStream + ctx.queryProjection. | `examples/event-sourcing.md` |
 | `feature-toggles` | Runtime feature-toggle flip — two toggleable features, one registers a cross-feature hook on the other; disabling either has the documented effect without reboot. | `examples/feature-toggles.md` |
 | `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
 | `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
 | `golden-path` | The smallest complete feature: entity, write handler, event, projection, screen and an integration test. | `examples/golden-path.md` |
+| `host-routing` | createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server. | `examples/host-routing.md` |
 | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
 | `idempotency` | Same request, same result. Dedupes on request ID. | `examples/idempotency.md` |
 | `inbound-mail-triage` | Inbound-mail consumer pattern: inbound-mail-foundation + in-memory provider, a worker-lane triage job attached to the ingest handler, verified end-to-end through createAllInOneEntrypoint. | `examples/inbound-mail-triage.md` |
@@ -50,6 +54,7 @@
 | `ownership` | Entity- and Field-level Row-Ownership: from() helper, Straddle-safe multi-role checks, Field-level Read/Write filtering. | `examples/ownership.md` |
 | `pdf-audit-export` | Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and uploads the bytes before the transaction (uploadFileBytesBeforeTransaction) and stores them as a FileRef (createFileRefFromUploadedBytes). | `examples/pdf-audit-export.md` |
 | `pipeline-basics` | M.1 Tier-1 step-vocabulary showcase: every step in one inventory-management feature (aggregate.{create,update,appendEvent}, read.{findOne,findMany}, branch, forEach, compute, return, unsafeProjection{Upsert,Delete}). | `examples/pipeline-basics.md` |
+| `prod-boot-options` | runProdApp boot options: mail, kmsMode, fileStorage, demoMode and signal handling declared as options instead of hand-wired in bin/main.ts. | `examples/prod-boot-options.md` |
 | `public-share-token` | Generic share-token entity: mint hash-stored token, anonymous read-by-token with IP rate-limit. | `examples/public-share-token.md` |
 | `rate-limiting` | End-to-end rate limiting: L1 global-IP + L2 auth-endpoints + L3 handler opt-in. | `examples/rate-limiting.md` |
 | `realtime-sse` | Server-sent events demo. Goodbye F5. | `examples/realtime-sse.md` |
@@ -59,7 +64,7 @@
 | `screens-nav` | r.screen() + r.nav() — entityList/entityEdit/custom screens, cross-feature nav parents, FieldCondition<TData>, boot-validator behaviour. | `examples/screens-nav.md` |
 | `search` | Tenant-scoped Meilisearch. Because ILIKE is not search. | `examples/search.md` |
 | `secrets-demo` | Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation. | `examples/secrets-demo.md` |
-| `security-baseline` | securityBaselineFeatures() preset: sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing. | `examples/security-baseline.md` |
+| `security-baseline` | composeSecurityStack(): sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing. | `examples/security-baseline.md` |
 | `seed-migration` | ES-Operations seed-migrations — file-based diff-and-apply für Aggregate-Updates die idempotent-Seeder nicht erfassen. | `examples/seed-migration.md` |
 | `session-revocation` | createSessionCallbacks + sessionChecker — server-side session revocation via JWT jti. | `examples/session-revocation.md` |
 | `state-machine` | Enforced entity state transitions. No more illegal state changes. | `examples/state-machine.md` |

package/agents/features.md

@@ -2,6 +2,12 @@
 
 # Bundled features
 
+## account-security
+
+Self-service account dashboard: MFA enrollment, recovery codes and the user's own sessions, composed from the auth-mfa and sessions screens.
+
+Requires: `sessions`, `auth-mfa`
+
 ## admin-shell
 
 Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.
@@ -363,6 +369,12 @@ Requires: `user-data-rights`
 
 Optional requires: `form-draft`
 
+## host-routing
+
+Host- and path-based tenant routing: an authoritative tenant resolver from the subdomain (tenantBy host), a tenant existence check against enabled, active tenants, and the tenant-key query behind createHostDispatch, which picks the HTML file, CSP, locale redirect or 404 per host for runProdApp's hostDispatch.
+
+Requires: `auth-foundation`, `tenant`
+
 ## inbound-mail-foundation
 
 Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.
@@ -538,7 +550,7 @@ Requires: `template-resolver`
 
 ## renderer-mail-html
 
-A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource="logo"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
+A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource="logo"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. `readMailChrome` hands the same brand row and footer, resolved for one locale, to pages a recipient opens from a mail, such as the unsubscribe page. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
 
 Requires: `renderer-foundation`, `template-resolver`
 
@@ -558,7 +570,7 @@ Requires: `renderer-foundation`
 
 ## secrets
 
-Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins). Server-side code writes a tenant secret with `dispatchSystemWrite({ handlerQn: "secrets:write:set", payload, tenantId })`: set and delete also admit the in-process system identity, so such writes pass the same declared-key and value checks.
+Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins). Server-side code writes a tenant secret with `dispatchSystemWrite({ handlerQn: SecretsHandlers.set, payload, tenantId })`: set and delete also admit the in-process system identity, so such writes pass the same declared-key and value checks.
 
 Category: infrastructure
 

package/dist/api/anonymous-cookie.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from "hono";
-import type { TenantId } from "../engine/types/index.js";
+import type { TenantId } from "../engine/types/index.ts";
 export type SetTenantCookieOptions = {
     readonly maxAgeSeconds?: number;
     readonly sameSite?: "Lax" | "Strict";

package/dist/api/anonymous-live-entities.d.ts

@@ -1,2 +1,2 @@
-import type { Registry } from "../engine/types/index.js";
+import type { Registry } from "../engine/types/index.ts";
 export declare function collectAnonymousLiveEntities(registry: Registry): ReadonlySet<string>;

package/dist/api/auth-middleware.d.ts

@@ -1,6 +1,6 @@
 import type { Context, Next } from "hono";
-import type { SessionUser, TenantId } from "../engine/types/index.js";
-import type { JwtHelper } from "./jwt.js";
+import type { SessionUser, TenantId } from "../engine/types/index.ts";
+import type { JwtHelper } from "./jwt.ts";
 export declare const CSRF_HEADER_NAME = "X-CSRF-Token";
 export declare const PAT_TOKEN_PREFIX = "kpat_";
 export type AuthTransport = "cookie" | "bearer";

package/dist/api/auth-routes.d.ts

@@ -1,11 +1,11 @@
 import { Hono } from "hono";
 import type { Redis } from "ioredis";
-import { type SessionUser } from "../engine/types/index.js";
-import type { Dispatcher } from "../pipeline/dispatcher.js";
-import { type AuthSessionChecker, type AuthSessionStatus, type TokenVerifier } from "./auth-middleware.js";
-import { type ClientIpResolver } from "./client-ip.js";
-import type { JwtHelper } from "./jwt.js";
-import type { PostAuthLandingResolver } from "./post-auth-landing.js";
+import { type SessionUser } from "../engine/types/index.ts";
+import type { Dispatcher } from "../pipeline/dispatcher.ts";
+import { type AuthSessionChecker, type AuthSessionStatus, type TokenVerifier } from "./auth-middleware.ts";
+import { type ClientIpResolver } from "./client-ip.ts";
+import type { JwtHelper } from "./jwt.ts";
+import type { PostAuthLandingResolver } from "./post-auth-landing.ts";
 export type LoginRateLimiter = {
     check(key: string): Promise<boolean>;
     reset(key: string): Promise<void>;
@@ -41,7 +41,7 @@ export type AuthRoutesConfig = {
     sessionChecker?: SessionChecker;
     tokenVerifier?: TokenVerifier;
     patRateLimiter?: LoginRateLimiter;
-    resolveTenantLifecycleStatus?: import("./auth-middleware.js").TenantLifecycleStatusResolver;
+    resolveTenantLifecycleStatus?: import("./auth-middleware.ts").TenantLifecycleStatusResolver;
     passwordReset?: PasswordResetConfig;
     emailVerification?: EmailVerificationConfig;
     accountUnlock?: AccountUnlockConfig;

package/dist/api/extra-route.d.ts

@@ -1,6 +1,6 @@
 import type { Context, Hono } from "hono";
-import type { HttpRouteMethod, Registry, SessionUser, TenantId, WriteResult } from "../engine/types/index.js";
-import type { SecretsContext } from "../secrets/index.js";
+import type { HttpRouteMethod, Registry, SessionUser, TenantId, WriteResult } from "../engine/types/index.ts";
+import type { SecretsContext } from "../secrets/index.ts";
 export declare const ExtraRouteEntries: {
     readonly anonymous: "anonymous";
     readonly user: "user";

package/dist/api/index.d.ts

@@ -1,37 +1,37 @@
-export type { SetTenantCookieOptions } from "./anonymous-cookie.js";
-export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.js";
-export { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
-export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.js";
-export type { AnonymousAccessConfig, AnonymousAccessResolved, AuthMiddlewareOptions, AuthSessionChecker, AuthSessionCheckResult, AuthSessionStatus, TenantExists, TenantLifecycleStatusResolver, TenantResolver, TokenVerifier, } from "./auth-middleware.js";
-export { authMiddleware, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.js";
-export type { AuthRoutesConfig, LoginRateLimiter, SessionChecker, SessionCreator, SessionMassRevoker, SessionMetadata, SessionRevoker, } from "./auth-routes.js";
-export { createAuthRoutes, createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.js";
-export type { ClientIpHeaderSource, ClientIpResolver } from "./client-ip.js";
-export { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, extractSocketAddress, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, UNKNOWN_CLIENT_IP, } from "./client-ip.js";
-export type { AnonymousExtraRoute, AnonymousExtraRouteDeps, ExtraRouteDefinition, ExtraRouteEntry, ExtraRouteRejectionOptions, ExtraRouteRejectionStatus, RoleDispatchArgs, SignatureExtraRoute, SignatureExtraRouteDeps, SignatureExtraRouteVerifyDeps, SignatureExtraRouteVerifyRequest, SystemDispatchArgs, UserExtraRoute, UserExtraRouteDeps, } from "./extra-route.js";
-export { ExtraRouteEntries, ExtraRouteRejection, signatureRoute } from "./extra-route.js";
-export type { CachedResponseInit, CachePolicy } from "./http-cache.js";
-export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, parseIfNoneMatch, } from "./http-cache.js";
-export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt.js";
-export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt.js";
-export { publicOriginOf } from "./origin-middleware.js";
-export { patAllows, qnMatches } from "./pat-scope.js";
-export type { PostAuthLandingArgs, PostAuthLandingFlow, PostAuthLandingResolver, } from "./post-auth-landing.js";
-export { isSafeLandingPath } from "./post-auth-landing.js";
-export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker.js";
-export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
-export { type RequestContextData, readonlyRequestContext as requestContext, } from "./request-context.js";
-export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
-export type { MetricsRouteOptions } from "./route-registrars.js";
-export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
-export { createApiRoutes } from "./routes.js";
-export type { KumikoServer, ServerOptions } from "./server.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
-export type { ResolvedSessionCookies, SessionCookieBase, SessionCookieNames, } from "./session-cookies.js";
-export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
-export type { SseBroker, SseClient, SseEvent } from "./sse-broker.js";
-export { createSseBroker } from "./sse-broker.js";
-export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS, type SseRouteOptions } from "./sse-route.js";
-export { generateToken } from "./tokens.js";
-export type { KumikoServeEnv, KumikoServerWebSocket, KumikoWebSocketData, WebSocketUpgradeServer, } from "./websocket-route.js";
-export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";
+export type { SetTenantCookieOptions } from "./anonymous-cookie.ts";
+export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.ts";
+export { collectAnonymousLiveEntities } from "./anonymous-live-entities.ts";
+export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.ts";
+export type { AnonymousAccessConfig, AnonymousAccessResolved, AuthMiddlewareOptions, AuthSessionChecker, AuthSessionCheckResult, AuthSessionStatus, TenantExists, TenantLifecycleStatusResolver, TenantResolver, TokenVerifier, } from "./auth-middleware.ts";
+export { authMiddleware, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.ts";
+export type { AuthRoutesConfig, LoginRateLimiter, SessionChecker, SessionCreator, SessionMassRevoker, SessionMetadata, SessionRevoker, } from "./auth-routes.ts";
+export { createAuthRoutes, createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.ts";
+export type { ClientIpHeaderSource, ClientIpResolver } from "./client-ip.ts";
+export { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, extractSocketAddress, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, UNKNOWN_CLIENT_IP, } from "./client-ip.ts";
+export type { AnonymousExtraRoute, AnonymousExtraRouteDeps, ExtraRouteDefinition, ExtraRouteEntry, ExtraRouteRejectionOptions, ExtraRouteRejectionStatus, RoleDispatchArgs, SignatureExtraRoute, SignatureExtraRouteDeps, SignatureExtraRouteVerifyDeps, SignatureExtraRouteVerifyRequest, SystemDispatchArgs, UserExtraRoute, UserExtraRouteDeps, } from "./extra-route.ts";
+export { ExtraRouteEntries, ExtraRouteRejection, signatureRoute } from "./extra-route.ts";
+export type { CachedResponseInit, CachePolicy } from "./http-cache.ts";
+export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, parseIfNoneMatch, } from "./http-cache.ts";
+export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt.ts";
+export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt.ts";
+export { publicOriginOf } from "./origin-middleware.ts";
+export { patAllows, qnMatches } from "./pat-scope.ts";
+export type { PostAuthLandingArgs, PostAuthLandingFlow, PostAuthLandingResolver, } from "./post-auth-landing.ts";
+export { isSafeLandingPath } from "./post-auth-landing.ts";
+export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker.ts";
+export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.ts";
+export { type RequestContextData, readonlyRequestContext as requestContext, } from "./request-context.ts";
+export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.ts";
+export type { MetricsRouteOptions } from "./route-registrars.ts";
+export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.ts";
+export { createApiRoutes } from "./routes.ts";
+export type { KumikoServer, ServerOptions } from "./server.ts";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.ts";
+export type { ResolvedSessionCookies, SessionCookieBase, SessionCookieNames, } from "./session-cookies.ts";
+export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.ts";
+export type { SseBroker, SseClient, SseEvent } from "./sse-broker.ts";
+export { createSseBroker } from "./sse-broker.ts";
+export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS, type SseRouteOptions } from "./sse-route.ts";
+export { generateToken } from "./tokens.ts";
+export type { KumikoServeEnv, KumikoServerWebSocket, KumikoWebSocketData, WebSocketUpgradeServer, } from "./websocket-route.ts";
+export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.ts";

package/dist/api/jwt.d.ts

@@ -1,4 +1,4 @@
-import type { SessionUser, TenantId } from "../engine/types/index.js";
+import type { SessionUser, TenantId } from "../engine/types/index.ts";
 export type JwtPayload = {
     sub: string;
     tenantId: TenantId;

package/dist/api/observability-middleware.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Next } from "hono";
-import { type Meter, type SensitiveFilterConfig, type Tracer } from "../observability/index.js";
+import { type Meter, type SensitiveFilterConfig, type Tracer } from "../observability/index.ts";
 export type ObservabilityMiddlewareOptions = {
     readonly tracer: Tracer;
     readonly meter: Meter;

package/dist/api/readiness.d.ts

@@ -1,5 +1,5 @@
 import type { Redis } from "ioredis";
-import type { DbConnection } from "../db/connection.js";
+import type { DbConnection } from "../db/connection.ts";
 export type ReadinessCheck = {
     readonly name: string;
     readonly run: () => Promise<void>;

package/dist/api/redis-sse-broker.d.ts

@@ -1,5 +1,5 @@
-import { type RedisClientOptions } from "../redis/client.js";
-import { type SseBroker } from "./sse-broker.js";
+import { type RedisClientOptions } from "../redis/client.ts";
+import { type SseBroker } from "./sse-broker.ts";
 export type RedisSseBrokerOptions = {
     readonly redisUrl: string;
     readonly clientOptions?: RedisClientOptions;