@cosmicdrift/kumiko-samples 0.369.0 → 0.371.0

package/packages/bundled-features/src/form-draft/lookup.ts

@@ -2,8 +2,8 @@ import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { formDraftTable } from "./executor.js";
-import type { FormDraftBlob } from "./schemas.js";
+import { formDraftTable } from "./executor.ts";
+import type { FormDraftBlob } from "./schemas.ts";
 
 export type FormDraftRow = {
   readonly id: string;

package/packages/bundled-features/src/form-draft/release-file-refs.ts

@@ -1,5 +1,5 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import type { FormDraftBlob } from "./schemas.js";
+import type { FormDraftBlob } from "./schemas.ts";
 
 // The draft blob's `values` is free-form by design (issue #1889: form-draft
 // never knows the consuming form's field schema, only { values, stepIndex,

package/packages/bundled-features/src/form-draft/schemas.ts

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { FORM_DRAFT_KEY_MAX_LENGTH, FORM_DRAFT_VALUES_MAX_BYTES } from "./constants.js";
+import { FORM_DRAFT_KEY_MAX_LENGTH, FORM_DRAFT_VALUES_MAX_BYTES } from "./constants.ts";
 
 const draftKeySchema = z.string().trim().min(1).max(FORM_DRAFT_KEY_MAX_LENGTH);
 

package/packages/bundled-features/src/form-draft-user-data/changes.json

@@ -1 +1,10 @@
-[]
+[
+  {
+    "version": "0.370.0",
+    "type": "breaking",
+    "title": "The deprecated formDraftUserDataFeature constant is removed",
+    "detail": "formDraftUserDataFeature was kept next to createFormDraftUserDataFeature() for one release. Mount the feature by calling createFormDraftUserDataFeature().",
+    "migration": "Run bun kumiko-upgrade --apply. It replaces formDraftUserDataFeature with createFormDraftUserDataFeature().",
+    "codemod": "scripts/codemod/feature-factory.ts"
+  }
+]

package/packages/bundled-features/src/form-draft-user-data/hooks.ts

@@ -9,7 +9,7 @@ import {
   type UserDataDeleteHook,
   type UserDataExportHook,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { formDraftExecutor, formDraftTable } from "../form-draft/index.js";
+import { formDraftExecutor, formDraftTable } from "../form-draft/index.ts";
 
 export const formDraftExportHook: UserDataExportHook = async (ctx) => {
   const rows = await ctx.db.selectMany(formDraftTable, {

package/packages/bundled-features/src/form-draft-user-data/index.ts

@@ -6,7 +6,7 @@
 // pull a hard dependency. Mirrors notes-history-user-data.
 
 import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
-import { formDraftDeleteHook, formDraftExportHook } from "./hooks.js";
+import { formDraftDeleteHook, formDraftExportHook } from "./hooks.ts";
 
 export function createFormDraftUserDataFeature() {
   return defineFeature(
@@ -25,6 +25,3 @@ export function createFormDraftUserDataFeature() {
     { dedupeOptions: {} },
   );
 }
-
-/** @deprecated Use createFormDraftUserDataFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
-export const formDraftUserDataFeature = createFormDraftUserDataFeature();

package/packages/bundled-features/src/foundation-shared/build-info-env.ts

@@ -0,0 +1,16 @@
+import * as z from "zod";
+
+/** `BUILD_VERSION`/`BUILD_TIME`, passed from the Dockerfile build args and
+ *  served by the health and version routes ("dev"/"unknown" when unset). */
+export const buildInfoEnvSchema = z.object({
+  BUILD_VERSION: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Release version baked into the image (git tag or sha). Default: dev."),
+  BUILD_TIME: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Image build timestamp (ISO 8601). Default: unknown."),
+});

package/packages/bundled-features/src/foundation-shared/changes.json

@@ -1 +1,8 @@
-[]
+[
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "buildInfoEnvSchema and demoAdminEnvSchema",
+    "detail": "buildInfoEnvSchema declares BUILD_VERSION and BUILD_TIME. demoAdminEnvSchema declares the seed logins DEMO_ADMIN_EMAIL and DEMO_SYSADMIN_EMAIL (required), their passwords (optional, at least 16 characters) and an optional DEMO_TENANT_ID. Apps add both through extend."
+  }
+]

package/packages/bundled-features/src/foundation-shared/demo-admin-env.ts

@@ -0,0 +1,24 @@
+import * as z from "zod";
+
+const SEED_PASSWORD_MIN_LENGTH = 16;
+
+function seedPassword(description: string) {
+  return z
+    .string()
+    .min(SEED_PASSWORD_MIN_LENGTH)
+    .optional()
+    .describe(`${description} Generate with: openssl rand -hex 24`)
+    .meta({ kumiko: { pulumi: { generator: "openssl rand -hex 24", secret: true } } });
+}
+
+/** Logins seeded on first boot: the demo tenant admin and the SystemAdmin.
+ *  The emails are required so a deploy never seeds an account nobody can
+ *  reach; a missing password skips that seed. An app with other rules
+ *  overrides single keys by spreading `.shape` before its own fields. */
+export const demoAdminEnvSchema = z.object({
+  DEMO_ADMIN_EMAIL: z.email().describe("Login of the demo tenant admin seeded on first boot."),
+  DEMO_ADMIN_PASSWORD: seedPassword("Password of the seeded demo tenant admin."),
+  DEMO_SYSADMIN_EMAIL: z.email().describe("Login of the SystemAdmin seeded on first boot."),
+  DEMO_SYSADMIN_PASSWORD: seedPassword("Password of the seeded SystemAdmin."),
+  DEMO_TENANT_ID: z.uuid().optional().describe("Id of the seeded demo tenant. Default: generated."),
+});

package/packages/bundled-features/src/foundation-shared/index.ts

@@ -1,8 +1,10 @@
 // Public API of foundation-shared — utilities consumed by the per-tenant
 // Foundation packages (ai-foundation, mail-foundation, file-foundation).
 
-export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers.js";
-export { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
+export { buildInfoEnvSchema } from "./build-info-env.ts";
+export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers.ts";
+export { demoAdminEnvSchema } from "./demo-admin-env.ts";
+export { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.ts";
 export {
   BlockedHostError,
   HostResolutionError,
@@ -12,4 +14,4 @@ export {
   mailAllowedPrivateHostsEnvSchema,
   readAllowedPrivateMailHostsFromEnv,
   resolveMailConnectTarget,
-} from "./mail-host-policy.js";
+} from "./mail-host-policy.ts";

package/packages/bundled-features/src/foundation-shared/mail-host-policy.ts

@@ -17,7 +17,7 @@ import type { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 import { resolvePublicHostname } from "@cosmicdrift/kumiko-framework/http";
 import * as z from "zod";
-import { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
+import { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.ts";
 
 export const MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS";
 

package/packages/bundled-features/src/host-routing/README.md

@@ -0,0 +1,89 @@
+# host-routing
+
+Tenant routing by host or path for apps with tenant subdomains, a tenant path
+prefix or locale-prefixed marketing pages. Two halves:
+
+- `createHostRoutingFeature(options)`: the server half. In `tenantBy: "host"` it
+  registers an authoritative tenant resolver (`<key>.<baseDomain>` → tenant),
+  so anonymous API calls get their tenant from the Host header only; a
+  disagreeing `X-Tenant` header or cookie answers `400 tenant_mismatch`, and the
+  apex or an unknown host answers `400 tenant_required`. Set
+  `apexAnonymousTenantId` and the apex answers as that tenant instead (host
+  mode: authoritative; path mode: only when the client names no tenant). Path
+  keys may be any 1 to 50 unreserved URL characters, subdomain keys must be
+  one lowercase DNS label. In both modes it
+  registers a tenant existence check: a client-named tenant must exist, be
+  enabled and be active. It also owns the anonymous, rate-limited
+  `host-routing:query:tenant-key-exists` query.
+- `createHostDispatch(options)`: the page half for `runProdApp({ hostDispatch })`.
+  It picks the HTML file and optional CSP per host, answers the locale redirect
+  and returns 404 for unknown tenants and unknown hosts.
+
+The dev server uses the same decision through
+`toDevHostDispatch(dispatch, { entries, staticDir })` from
+`@cosmicdrift/kumiko-dev-server`.
+
+## Setup
+
+```typescript
+import {
+  createHostDispatch,
+  createHostRoutingFeature,
+  type HostRoutingOptions,
+} from "@cosmicdrift/kumiko-bundled-features/host-routing";
+import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+
+const routing: HostRoutingOptions = {
+  tenantBy: "host",
+  baseDomain: "example.com",
+  apex: { file: "index.html", localeFiles: { en: "en/index.html" } },
+  tenant: { file: "app.html", csp: "default-src 'self'; frame-ancestors 'none'" },
+  unknownTenant: { file: "unknown-tenant.html" },
+  hosts: { "admin.example.com": { file: "admin.html" } },
+  locales: { default: "de", prefixed: ["en"] },
+};
+
+runProdApp({
+  features: [...FEATURES, createHostRoutingFeature(routing)],
+  anonymousAccess: () => ({}),
+  hostDispatch: createHostDispatch(routing),
+});
+```
+
+`anonymousAccess` stays an app opt-in: the providers are merged in only when
+the app sets it.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `tenantBy` | `"host"` (`<key>.<baseDomain>`) or `"path"` with `tenantPathPrefix` (`/t/<key>/...` on the apex) |
+| `baseDomain` | Apex hostname, lowercase, no port. `www.<baseDomain>` counts as apex |
+| `apex` | `{ file, csp?, localeFiles? }` for the apex |
+| `tenant` | `{ file, csp? }` for a known tenant and for the bare path prefix |
+| `unknownTenant` | `{ file, csp? }` served with 404; omit for a bare 404 |
+| `hosts` | Further fixed hostnames with their own surface, checked first |
+| `apexAnonymousTenantId` | Tenant for anonymous API calls on the apex (e.g. `SYSTEM_TENANT_ID` for public signup); omit and the apex has none |
+| `locales` | `{ default, prefixed }`: `/<default>/...` answers 301 to the unprefixed path, `/<prefixed>/...` serves `apex.localeFiles[locale]` |
+
+A `csp` replaces runProdApp's default CSP for that surface; without it the
+default applies. Options are validated when the feature or dispatch is built.
+
+## Security
+
+- Only plain DNS names (optional port) are routed. `X-Forwarded-Host` is never
+  read; userinfo, IPv6 literals, lists or nested subdomains fall to a bare 404
+  without a lookup.
+- Redirect targets are same-origin paths; leading slashes and backslashes are
+  collapsed, so `/de//evil.example` never becomes a protocol-relative URL.
+- The key query returns only `{ exists }`, which the 404 page makes public
+  anyway. Over its rate limit the dispatch serves the tenant shell; the API
+  behind it still resolves the tenant itself.
+- In `tenantBy: "path"` no resolver is registered, so the client names its
+  tenant with `X-Tenant`; the existence check still rejects unknown, disabled
+  and destroyed tenants.
+
+## Not covered
+
+Custom domains per tenant, legacy host redirects and app-specific query
+allowlists stay in the app: wrap the dispatch function and fall through to it.

package/packages/bundled-features/src/host-routing/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "createHostRoutingFeature and createHostDispatch route tenants by host or path",
+    "detail": "One HostRoutingOptions object ({ tenantBy: \"host\" } or { tenantBy: \"path\", tenantPathPrefix }, plus baseDomain, apex, tenant, unknownTenant?, hosts?, locales?) drives both halves. createHostRoutingFeature registers an authoritative Host-header tenant resolver in host mode and, in both modes, an existence check that admits only enabled, active tenants. apexAnonymousTenantId gives anonymous apex calls a tenant (e.g. SYSTEM_TENANT_ID); without it the apex answers tenant_required. createHostDispatch is a runProdApp hostDispatch: HTML file and optional CSP per surface (without csp the runProdApp default applies), a 301 from the default-locale prefix to the unprefixed path, and 404 for unknown tenants and hosts. toDevHostDispatch(dispatch, { entries, staticDir }) from @cosmicdrift/kumiko-dev-server plugs the same decision into the dev server. Apps with their own routing feature and hostDispatch move to these; app-specific redirects or custom domains wrap the dispatch function."
+  }
+]

package/packages/bundled-features/src/host-routing/constants.ts

@@ -0,0 +1,24 @@
+export const HOST_ROUTING_FEATURE = "host-routing";
+
+export const HostRoutingQueries = {
+  tenantKeyExists: `${HOST_ROUTING_FEATURE}:query:tenant-key-exists`,
+} as const;
+
+// Matches tenant:write:create's key limit; keeps lookups for absurd keys out
+// of the database.
+export const TENANT_KEY_MAX_LENGTH = 50;
+// A subdomain is one lowercase DNS label, so tenant keys outside this shape
+// are only reachable in path mode.
+export const TENANT_KEY_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$/;
+
+export function isTenantKeyCandidate(value: string): boolean {
+  return value.length <= TENANT_KEY_MAX_LENGTH && TENANT_KEY_PATTERN.test(value);
+}
+
+// Path mode takes any key made of unreserved URL characters, since the tenant
+// feature itself only limits the length.
+const PATH_TENANT_KEY_PATTERN = /^[A-Za-z0-9._~-]+$/;
+
+export function isPathTenantKeyCandidate(value: string): boolean {
+  return value.length <= TENANT_KEY_MAX_LENGTH && PATH_TENANT_KEY_PATTERN.test(value);
+}

package/packages/bundled-features/src/host-routing/dispatch.ts

@@ -0,0 +1,130 @@
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { RateLimitError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import type { PageHeadSystemQuery } from "@cosmicdrift/kumiko-headless/apex";
+import * as z from "zod";
+import { HostRoutingQueries, isPathTenantKeyCandidate, isTenantKeyCandidate } from "./constants.ts";
+import { classifyHost } from "./host.ts";
+import type { HostRoutingOptions, HostRoutingSurface } from "./options.ts";
+import { validateHostRoutingOptions } from "./validate-options.ts";
+
+// Structurally identical to server-runtime's HostDispatchResult. Defined here
+// because server-runtime depends on bundled-features, not the other way round;
+// dev-server pins the compatibility with a type test.
+export type HostRoutingDispatchResult =
+  | { readonly kind: "html"; readonly file: string; readonly csp?: string }
+  | { readonly kind: "redirect"; readonly to: string; readonly status?: 301 | 302 }
+  | { readonly kind: "not-found"; readonly file?: string; readonly csp?: string };
+
+export type HostRoutingRequest = {
+  readonly host: string;
+  readonly path: string;
+  // Query string incl. leading "?", "" if none.
+  readonly search: string;
+};
+
+export type HostRoutingDispatchFn = (
+  req: HostRoutingRequest,
+  deps: { readonly systemQuery: PageHeadSystemQuery },
+) => Promise<HostRoutingDispatchResult>;
+
+const tenantKeyExistsResultSchema = z.object({ exists: z.boolean() });
+
+async function isTenantKeyKnown(systemQuery: PageHeadSystemQuery, key: string): Promise<boolean> {
+  let result: unknown;
+  try {
+    result = await systemQuery(HostRoutingQueries.tenantKeyExists, { key }, SYSTEM_TENANT_ID);
+  } catch (error) {
+    if (error instanceof ValidationError) return false;
+    // Over the rate limit every key looks the same: serve the tenant shell,
+    // which leaks nothing; the API behind it still resolves the tenant itself.
+    if (error instanceof RateLimitError) return true;
+    throw error;
+  }
+  return tenantKeyExistsResultSchema.parse(result).exists;
+}
+
+function serve(
+  surface: HostRoutingSurface,
+  file: string = surface.file,
+): HostRoutingDispatchResult {
+  return surface.csp === undefined
+    ? { kind: "html", file }
+    : { kind: "html", file, csp: surface.csp };
+}
+
+function notFound(surface: HostRoutingSurface | undefined): HostRoutingDispatchResult {
+  if (surface === undefined) return { kind: "not-found" };
+  return surface.csp === undefined
+    ? { kind: "not-found", file: surface.file }
+    : { kind: "not-found", file: surface.file, csp: surface.csp };
+}
+
+// Redirect targets are always same-origin paths. Collapsing leading slashes
+// and backslashes keeps "/de//evil.example" from turning into the
+// protocol-relative "//evil.example".
+function sameOriginPath(path: string): string {
+  return `/${path.replace(/^[/\\]+/, "")}`;
+}
+
+function splitFirstSegment(path: string): { readonly segment: string; readonly rest: string } {
+  const withoutLeading = path.replace(/^\/+/, "");
+  const slash = withoutLeading.indexOf("/");
+  if (slash === -1) return { segment: withoutLeading, rest: "/" };
+  return { segment: withoutLeading.slice(0, slash), rest: withoutLeading.slice(slash) };
+}
+
+function apexPage(options: HostRoutingOptions, req: HostRoutingRequest): HostRoutingDispatchResult {
+  const { apex, locales } = options;
+  if (locales === undefined) return serve(apex);
+  const { segment, rest } = splitFirstSegment(req.path);
+  if (segment === locales.default) {
+    return { kind: "redirect", to: `${sameOriginPath(rest)}${req.search}`, status: 301 };
+  }
+  const locale = locales.prefixed.includes(segment) ? segment : locales.default;
+  return serve(apex, apex.localeFiles?.[locale] ?? apex.file);
+}
+
+async function tenantPage(
+  options: HostRoutingOptions,
+  key: string | null,
+  systemQuery: PageHeadSystemQuery,
+): Promise<HostRoutingDispatchResult> {
+  // No key (bare tenant prefix): the shell handles login and tenant choice.
+  if (key === null) return serve(options.tenant);
+  const isCandidate = options.tenantBy === "path" ? isPathTenantKeyCandidate : isTenantKeyCandidate;
+  if (!isCandidate(key)) return notFound(options.unknownTenant);
+  return (await isTenantKeyKnown(systemQuery, key))
+    ? serve(options.tenant)
+    : notFound(options.unknownTenant);
+}
+
+function tenantKeyFromPath(prefix: string, path: string): string | null | undefined {
+  if (path !== prefix && !path.startsWith(`${prefix}/`)) return undefined;
+  const { segment } = splitFirstSegment(path.slice(prefix.length));
+  return segment === "" ? null : segment;
+}
+
+// The routing decision for runProdApp's `hostDispatch` (and, via
+// toDevHostDispatch, the dev server). Unknown hosts fail closed with 404.
+export function createHostDispatch(options: HostRoutingOptions): HostRoutingDispatchFn {
+  validateHostRoutingOptions(options);
+  return async (req, { systemQuery }) => {
+    const host = classifyHost(req.host, options);
+    switch (host.kind) {
+      case "fixed":
+        return serve(host.surface);
+      case "unknown":
+        return notFound(undefined);
+      case "subdomain":
+        if (options.tenantBy !== "host") return notFound(undefined);
+        return tenantPage(options, host.key, systemQuery);
+      case "apex": {
+        if (options.tenantBy === "path") {
+          const key = tenantKeyFromPath(options.tenantPathPrefix, req.path);
+          if (key !== undefined) return tenantPage(options, key, systemQuery);
+        }
+        return apexPage(options, req);
+      }
+    }
+  };
+}

package/packages/bundled-features/src/host-routing/feature.ts

@@ -0,0 +1,146 @@
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  defineQueryHandler,
+  type FeatureDefinition,
+  isSystemTenant,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import {
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  type TenantExistenceProvider,
+  type TenantResolverProvider,
+} from "../auth-foundation/index.ts";
+import {
+  isTenantServingPublicContent,
+  type TenantLifecycleStatus,
+  tenantTable,
+} from "../tenant/index.ts";
+import { HOST_ROUTING_FEATURE, TENANT_KEY_MAX_LENGTH } from "./constants.ts";
+import { classifyHost } from "./host.ts";
+import type { HostRoutingOptions } from "./options.ts";
+import { validateHostRoutingOptions } from "./validate-options.ts";
+
+type TenantRow = {
+  readonly id: TenantId;
+  readonly isEnabled: boolean;
+  readonly status: TenantLifecycleStatus;
+};
+
+// Disabled tenants and tenants in any destroy phase are not routable, the same
+// rule public files and pages follow.
+async function servingTenantIdByKey(
+  db: DbConnection | TenantDb,
+  key: string,
+): Promise<TenantId | null> {
+  const row = await fetchOne<TenantRow>(db, tenantTable, { key });
+  return row !== undefined && isTenantServingPublicContent(row) ? row.id : null;
+}
+
+async function isTenantServing(db: DbConnection, id: TenantId): Promise<boolean> {
+  const row = await fetchOne<TenantRow>(db, tenantTable, { id });
+  return row !== undefined && isTenantServingPublicContent(row);
+}
+
+type HostHeaderReader = { readonly req: { readonly header: (name: string) => string | undefined } };
+
+// auth-foundation types the Hono context as unknown to stay free of a hono dep.
+function isHostHeaderReader(c: unknown): c is HostHeaderReader {
+  return (
+    typeof c === "object" &&
+    c !== null &&
+    "req" in c &&
+    typeof c.req === "object" &&
+    c.req !== null &&
+    "header" in c.req &&
+    typeof c.req.header === "function"
+  );
+}
+
+// Returns only { exists }: the same fact the tenant 404 page already makes
+// public, never other tenant fields. Rate-limited so it is no cheap oracle.
+const tenantKeyExistsQuery = defineQueryHandler({
+  name: "tenant-key-exists",
+  schema: z.object({ key: z.string().min(1).max(TENANT_KEY_MAX_LENGTH) }),
+  access: { roles: ["anonymous"] },
+  rateLimit: { per: "ip+handler", limit: 120, windowSeconds: 60 },
+  // Page-routing plumbing, not a task an agent performs.
+  agent: { expose: false },
+  description:
+    "Anonymous existence check for a tenant key, backing the unknown-tenant 404 of the host-routing hostDispatch. Returns only { exists }.",
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "host-routing:query:tenant-key-exists requires ctx.systemDb (r.systemScope())",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "tenant-key existence check for the host-routing 404 — publicly observable via the 404 itself",
+    );
+    return { exists: (await servingTenantIdByKey(db, query.payload.key)) !== null };
+  },
+});
+
+function tenantResolverFor(options: HostRoutingOptions): TenantResolverProvider | undefined {
+  const apexTenantId = options.apexAnonymousTenantId ?? null;
+  if (options.tenantBy === "host") {
+    return {
+      trust: "authoritative",
+      build:
+        ({ db }) =>
+        async (c: unknown): Promise<TenantId | null> => {
+          if (!isHostHeaderReader(c)) return null;
+          const host = classifyHost(c.req.header("Host") ?? "", options);
+          if (host.kind === "subdomain") return servingTenantIdByKey(db, host.key);
+          // Fixed and unknown hosts have no anonymous tenant: an authoritative
+          // null answers tenant_required, whatever X-Tenant says.
+          return host.kind === "apex" ? apexTenantId : null;
+        },
+    };
+  }
+  if (apexTenantId === null) return undefined;
+  // Path mode: the client names its tenant; the apex default only fills in
+  // when it does not.
+  return {
+    trust: "fallback-only",
+    build: () => async (c: unknown) => {
+      if (!isHostHeaderReader(c)) return null;
+      return classifyHost(c.req.header("Host") ?? "", options).kind === "apex"
+        ? apexTenantId
+        : null;
+    },
+  };
+}
+
+// Server half of host routing: the tenant for anonymous API requests comes
+// from the Host header only (never from X-Tenant), and a client-named tenant
+// must exist, be enabled and be active. The page half is createHostDispatch.
+export function createHostRoutingFeature(options: HostRoutingOptions): FeatureDefinition {
+  validateHostRoutingOptions(options);
+  return defineFeature(HOST_ROUTING_FEATURE, (r) => {
+    r.describe(
+      "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.",
+    );
+    r.requires({ features: ["auth-foundation", "tenant"] });
+    r.systemScope();
+    r.queryHandler(tenantKeyExistsQuery);
+
+    const resolver = tenantResolverFor(options);
+    if (resolver !== undefined) {
+      // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a registrar method, not a React hook; path mode without an apex tenant must leave the resolver slot free.
+      r.useExtension(EXT_TENANT_RESOLVER, "host", resolver);
+    }
+
+    const existence: TenantExistenceProvider = {
+      build:
+        ({ db }) =>
+        (tenantId: string) =>
+          isSystemTenant(tenantId) ? true : isTenantServing(db, tenantId),
+    };
+    r.useExtension(EXT_TENANT_EXISTENCE, "active-tenant", existence);
+  });
+}

package/packages/bundled-features/src/host-routing/host.ts

@@ -0,0 +1,42 @@
+import { isTenantKeyCandidate } from "./constants.ts";
+import type { HostRoutingOptions, HostRoutingSurface } from "./options.ts";
+
+// Only plain DNS names (plus an optional port) are routable. Anything else,
+// e.g. userinfo ("a@b"), IPv6 literals or stray characters, never matches a
+// configured domain and must not reach URL parsing or a DB lookup.
+const HOST_HEADER_PATTERN = /^[a-z0-9.-]+(?::[0-9]{1,5})?$/;
+
+export function normalizeHostname(host: string): string | null {
+  const lower = host.trim().toLowerCase();
+  if (!HOST_HEADER_PATTERN.test(lower)) return null;
+  const colon = lower.indexOf(":");
+  const hostname = colon === -1 ? lower : lower.slice(0, colon);
+  const withoutTrailingDot = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+  return withoutTrailingDot === "" ? null : withoutTrailingDot;
+}
+
+export type HostClass =
+  | { readonly kind: "fixed"; readonly surface: HostRoutingSurface }
+  | { readonly kind: "apex" }
+  | { readonly kind: "subdomain"; readonly key: string }
+  | { readonly kind: "unknown" };
+
+export function classifyHost(host: string, options: HostRoutingOptions): HostClass {
+  const hostname = normalizeHostname(host);
+  if (hostname === null) return { kind: "unknown" };
+  // Own-property check: the Host header is attacker-controlled, and a plain
+  // "constructor" would otherwise resolve through Object.prototype.
+  const fixed =
+    options.hosts !== undefined && Object.hasOwn(options.hosts, hostname)
+      ? options.hosts[hostname]
+      : undefined;
+  if (fixed !== undefined) return { kind: "fixed", surface: fixed };
+  const baseDomain = options.baseDomain.toLowerCase();
+  if (hostname === baseDomain || hostname === `www.${baseDomain}`) return { kind: "apex" };
+  const suffix = `.${baseDomain}`;
+  if (!hostname.endsWith(suffix)) return { kind: "unknown" };
+  const label = hostname.slice(0, -suffix.length);
+  // Exactly one label: "a.b.<baseDomain>" is not a tenant host.
+  if (!isTenantKeyCandidate(label)) return { kind: "unknown" };
+  return { kind: "subdomain", key: label };
+}

package/packages/bundled-features/src/host-routing/index.ts

@@ -0,0 +1,21 @@
+export {
+  HOST_ROUTING_FEATURE,
+  HostRoutingQueries,
+  isTenantKeyCandidate,
+  TENANT_KEY_MAX_LENGTH,
+} from "./constants.ts";
+export {
+  createHostDispatch,
+  type HostRoutingDispatchFn,
+  type HostRoutingDispatchResult,
+  type HostRoutingRequest,
+} from "./dispatch.ts";
+export { createHostRoutingFeature } from "./feature.ts";
+export { normalizeHostname } from "./host.ts";
+export type {
+  HostRoutingApexSurface,
+  HostRoutingLocales,
+  HostRoutingOptions,
+  HostRoutingSurface,
+  HostRoutingTenantMode,
+} from "./options.ts";

package/packages/bundled-features/src/host-routing/options.ts

@@ -0,0 +1,43 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// What a host (or a tenant) gets served on the HTML fallback.
+export type HostRoutingSurface = {
+  // HTML file relative to the prod staticDir, e.g. "index.html" or "admin.html".
+  readonly file: string;
+  // Replaces the default CSP for this surface. Omit to keep runProdApp's default.
+  readonly csp?: string;
+};
+
+export type HostRoutingApexSurface = HostRoutingSurface & {
+  // Per-locale file for the apex, keyed by locale; falls back to `file`.
+  readonly localeFiles?: Readonly<Record<string, string>>;
+};
+
+export type HostRoutingLocales = {
+  // Served unprefixed; "/<default>/..." answers 301 to the unprefixed path.
+  readonly default: string;
+  // Served under "/<locale>/...".
+  readonly prefixed: readonly string[];
+};
+
+export type HostRoutingTenantMode =
+  // <key>.<baseDomain> names the tenant.
+  | { readonly tenantBy: "host" }
+  // <baseDomain><tenantPathPrefix>/<key>/... names the tenant.
+  | { readonly tenantBy: "path"; readonly tenantPathPrefix: string };
+
+export type HostRoutingOptions = HostRoutingTenantMode & {
+  // Apex host without port, e.g. "example.com". "www.<baseDomain>" counts as apex.
+  readonly baseDomain: string;
+  readonly apex: HostRoutingApexSurface;
+  // Served for a known, enabled tenant (and for the bare tenant path prefix).
+  readonly tenant: HostRoutingSurface;
+  // Served with status 404 for an unknown or disabled tenant. Omit for a bare 404.
+  readonly unknownTenant?: HostRoutingSurface;
+  // Further fixed hosts (full hostname, lowercase, without port), checked first.
+  readonly hosts?: Readonly<Record<string, HostRoutingSurface>>;
+  readonly locales?: HostRoutingLocales;
+  // Tenant for anonymous API calls on the apex (e.g. SYSTEM_TENANT_ID for
+  // public signup forms). Omit and the apex answers tenant_required.
+  readonly apexAnonymousTenantId?: TenantId;
+};