@cosmicdrift/kumiko-samples 0.373.0 → 0.377.0

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

@@ -1,5 +1,3 @@
-import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineFeature,
   defineQueryHandler,
@@ -16,40 +14,30 @@ import {
   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";
+  HOST_HEADER_MAX_LENGTH,
+  HOST_ROUTING_FEATURE,
+  TENANT_KEY_MAX_LENGTH,
+} from "./constants.ts";
+import { classifyHost, normalizeHostname } from "./host.ts";
 import type { HostRoutingOptions } from "./options.ts";
+import {
+  isTenantServing,
+  servingTenantIdByKey,
+  servingTenantIdByResolver,
+} from "./tenant-lookup.ts";
 import { validateHostRoutingOptions } from "./validate-options.ts";
 
-type TenantRow = {
-  readonly id: TenantId;
-  readonly isEnabled: boolean;
-  readonly status: TenantLifecycleStatus;
+type RequestReader = {
+  readonly req: {
+    readonly header: (name: string) => string | undefined;
+    readonly url: string;
+    readonly path: string;
+    readonly raw?: Request;
+  };
 };
 
-// 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 {
+function isRequestReader(c: unknown): c is RequestReader {
   return (
     typeof c === "object" &&
     c !== null &&
@@ -57,10 +45,66 @@ function isHostHeaderReader(c: unknown): c is HostHeaderReader {
     typeof c.req === "object" &&
     c.req !== null &&
     "header" in c.req &&
-    typeof c.req.header === "function"
+    typeof c.req.header === "function" &&
+    "url" in c.req &&
+    typeof c.req.url === "string" &&
+    "path" in c.req &&
+    typeof c.req.path === "string"
   );
 }
 
+// Hono routes on the decoded path and ignores a trailing slash, so the
+// allowlist must compare the same shape: "/api/%71uery" and "/api/query/"
+// reach the query handler too.
+function routedPathOf(c: RequestReader): string {
+  return c.req.path.length > 1 ? c.req.path.replace(/\/+$/, "") : c.req.path;
+}
+
+// "example.com" and "www.example.com" are one site: a host without its own
+// entry falls back to the other variant's entry instead of keeping the anchor.
+function allowlistFor(
+  options: HostRoutingOptions,
+  hostname: string,
+): readonly string[] | undefined {
+  const allowlists = options.apexAnonymousQueryAllowlist;
+  if (allowlists === undefined) return undefined;
+  const counterpart = hostname.startsWith("www.") ? hostname.slice(4) : `www.${hostname}`;
+  for (const key of [hostname, counterpart]) {
+    if (Object.hasOwn(allowlists, key)) return allowlists[key];
+  }
+  return undefined;
+}
+
+// Both carry { type, payload } and run read handlers; /api/batch is commands only.
+const TYPED_READ_PATHS: ReadonlySet<string> = new Set(["/api/query", "/api/stream"]);
+const queryTypeBodySchema = z.object({ type: z.string() });
+
+// Reads the query type from a clone, so the body stays intact for the handler.
+async function peekQueryType(c: RequestReader): Promise<string | null> {
+  if (c.req.raw === undefined) return null;
+  try {
+    const parsed = queryTypeBodySchema.safeParse(await c.req.raw.clone().json());
+    return parsed.success ? parsed.data.type : null;
+  } catch {
+    return null;
+  }
+}
+
+// Apex anchor tenant for anonymous calls. A host with an allowlist only gets
+// the anchor for the listed query types on read paths; other paths keep it.
+async function apexAnchorFor(
+  options: HostRoutingOptions,
+  c: RequestReader,
+  hostname: string,
+): Promise<TenantId | null> {
+  const anchor = options.apexAnonymousTenantId ?? null;
+  if (anchor === null) return null;
+  const allowlist = allowlistFor(options, hostname);
+  if (allowlist === undefined || !TYPED_READ_PATHS.has(routedPathOf(c))) return anchor;
+  const type = await peekQueryType(c);
+  return type !== null && allowlist.includes(type) ? anchor : null;
+}
+
 // 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({
@@ -85,32 +129,68 @@ const tenantKeyExistsQuery = defineQueryHandler({
   },
 });
 
+function hostTenantExistsQueryFor(options: HostRoutingOptions) {
+  return defineQueryHandler({
+    name: "host-tenant-exists",
+    schema: z.object({ host: z.string().min(1).max(HOST_HEADER_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 host check backing the unknown-host 404 of the host-routing hostDispatch in tenantBy resolver mode. Returns only { exists }.",
+    handler: async (query, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message: "host-routing:query:host-tenant-exists requires ctx.systemDb (r.systemScope())",
+        });
+      }
+      const hostname = normalizeHostname(query.payload.host);
+      if (hostname === null) return { exists: false };
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "host existence check for the host-routing 404 — publicly observable via the 404 itself",
+      );
+      return { exists: (await servingTenantIdByResolver(options, db, hostname)) !== null };
+    },
+  });
+}
+
 function tenantResolverFor(options: HostRoutingOptions): TenantResolverProvider | undefined {
-  const apexTenantId = options.apexAnonymousTenantId ?? null;
-  if (options.tenantBy === "host") {
+  if (options.tenantBy !== "path") {
     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);
+          if (!isRequestReader(c)) return null;
+          const hostHeader = c.req.header("Host") ?? "";
+          const host = classifyHost(hostHeader, options);
           // Fixed and unknown hosts have no anonymous tenant: an authoritative
           // null answers tenant_required, whatever X-Tenant says.
-          return host.kind === "apex" ? apexTenantId : null;
+          switch (host.kind) {
+            case "subdomain":
+              return servingTenantIdByKey(db, host.key);
+            case "resolved":
+              return servingTenantIdByResolver(options, db, host.hostname);
+            case "apex":
+              return apexAnchorFor(options, c, normalizeHostname(hostHeader) ?? "");
+            case "fixed":
+            case "unknown":
+              return null;
+          }
         },
     };
   }
-  if (apexTenantId === null) return undefined;
+  if (options.apexAnonymousTenantId === undefined) 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
+      if (!isRequestReader(c)) return null;
+      const hostHeader = c.req.header("Host") ?? "";
+      return classifyHost(hostHeader, options).kind === "apex"
+        ? apexAnchorFor(options, c, normalizeHostname(hostHeader) ?? "")
         : null;
     },
   };
@@ -128,6 +208,7 @@ export function createHostRoutingFeature(options: HostRoutingOptions): FeatureDe
     r.requires({ features: ["auth-foundation", "tenant"] });
     r.systemScope();
     r.queryHandler(tenantKeyExistsQuery);
+    if (typeof options.tenantBy === "function") r.queryHandler(hostTenantExistsQueryFor(options));
 
     const resolver = tenantResolverFor(options);
     if (resolver !== undefined) {

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

@@ -19,6 +19,8 @@ export type HostClass =
   | { readonly kind: "fixed"; readonly surface: HostRoutingSurface }
   | { readonly kind: "apex" }
   | { readonly kind: "subdomain"; readonly key: string }
+  // tenantBy resolver mode: any host that is neither fixed nor apex.
+  | { readonly kind: "resolved"; readonly hostname: string }
   | { readonly kind: "unknown" };
 
 export function classifyHost(host: string, options: HostRoutingOptions): HostClass {
@@ -31,8 +33,9 @@ export function classifyHost(host: string, options: HostRoutingOptions): HostCla
       ? options.hosts[hostname]
       : undefined;
   if (fixed !== undefined) return { kind: "fixed", surface: fixed };
+  if (isApexHostname(hostname, options.baseDomain)) return { kind: "apex" };
   const baseDomain = options.baseDomain.toLowerCase();
-  if (hostname === baseDomain || hostname === `www.${baseDomain}`) return { kind: "apex" };
+  if (typeof options.tenantBy === "function") return { kind: "resolved", hostname };
   const suffix = `.${baseDomain}`;
   if (!hostname.endsWith(suffix)) return { kind: "unknown" };
   const label = hostname.slice(0, -suffix.length);
@@ -40,3 +43,27 @@ export function classifyHost(host: string, options: HostRoutingOptions): HostCla
   if (!isTenantKeyCandidate(label)) return { kind: "unknown" };
   return { kind: "subdomain", key: label };
 }
+
+export 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) };
+}
+
+// undefined: path is outside the prefix; null: bare prefix without a key.
+export 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;
+}
+
+// Apex hostnames are the only ones that may carry a path-named tenant or an
+// anonymous anchor tenant.
+export function isApexHostname(hostname: string, baseDomain: string): boolean {
+  const base = baseDomain.toLowerCase();
+  return hostname === base || hostname === `www.${base}`;
+}

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

@@ -16,6 +16,9 @@ export type {
   HostRoutingApexSurface,
   HostRoutingLocales,
   HostRoutingOptions,
+  HostRoutingRedirect,
   HostRoutingSurface,
   HostRoutingTenantMode,
+  HostTenantResolver,
 } from "./options.ts";
+export { createHostTenantIdResolver } from "./tenant-lookup.ts";

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

@@ -1,3 +1,4 @@
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 // What a host (or a tenant) gets served on the HTML fallback.
@@ -20,11 +21,43 @@ export type HostRoutingLocales = {
   readonly prefixed: readonly string[];
 };
 
+// Maps a normalized hostname (lowercase, no port) that is neither the apex nor
+// a fixed host to the tenant it belongs to, e.g. a subdomain or custom domain
+// stored in an app table. Null means "no tenant here": the dispatch answers
+// 404 and the API answers tenant_required, never a default tenant. The
+// result still has to be an enabled, active tenant. Runs on every request
+// that reaches such a host, so keep it to one indexed lookup.
+export type HostTenantResolver = (
+  host: string,
+  db: DbConnection | TenantDb,
+) => Promise<TenantId | null> | TenantId | null;
+
 export type HostRoutingTenantMode =
   // <key>.<baseDomain> names the tenant.
-  | { readonly tenantBy: "host" }
+  | {
+      readonly tenantBy: "host";
+      // Also serve the tenant surface on the apex under <tenantPathPrefix>/<key>/...
+      readonly tenantPathPrefix?: string;
+    }
   // <baseDomain><tenantPathPrefix>/<key>/... names the tenant.
-  | { readonly tenantBy: "path"; readonly tenantPathPrefix: string };
+  | { readonly tenantBy: "path"; readonly tenantPathPrefix: string }
+  // The app resolves every other host itself (custom domains, profile subdomains).
+  | {
+      readonly tenantBy: HostTenantResolver;
+      readonly tenantPathPrefix?: string;
+    };
+
+// Fixed, app-configured redirect. `to` is a same-origin path or an https URL;
+// nothing from the request ever picks the target, only the matched remainder
+// of the path is appended.
+export type HostRoutingRedirect = {
+  // Path (exact or as a segment prefix, e.g. "/old" matches "/old" and "/old/x").
+  readonly from: string;
+  readonly to: string;
+  // Limits the rule to one lowercase hostname without port. Omit for every host.
+  readonly host?: string;
+  readonly status?: 301 | 302;
+};
 
 export type HostRoutingOptions = HostRoutingTenantMode & {
   // Apex host without port, e.g. "example.com". "www.<baseDomain>" counts as apex.
@@ -40,4 +73,14 @@ export type HostRoutingOptions = HostRoutingTenantMode & {
   // 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;
+  // Per apex hostname ("example.com" or "www.example.com"): the only
+  // /api/query and /api/stream types that get the apexAnonymousTenantId anchor. Other anonymous
+  // queries on that host get no tenant (tenant_required). "example.com" and
+  // "www.example.com" share one entry: a host without its own uses the other's.
+  // Other paths (e.g. /api/batch) keep the anchor for everything.
+  // Not allowed with tenantBy "path" (boot error): there the client's X-Tenant
+  // wins over the resolver, so the allowlist would be ineffective.
+  readonly apexAnonymousQueryAllowlist?: Readonly<Record<string, readonly string[]>>;
+  // Checked first, before any host classification.
+  readonly redirects?: readonly HostRoutingRedirect[];
 };

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

@@ -0,0 +1,33 @@
+import { normalizeHostname } from "./host.ts";
+import type { HostRoutingRedirect } from "./options.ts";
+
+// Same-origin targets collapse leading slashes and backslashes so an appended
+// "//evil.example" remainder can never turn into a protocol-relative URL.
+export function sameOriginPath(path: string): string {
+  return `/${path.replace(/^[/\\]+/, "")}`;
+}
+
+function remainderAfter(from: string, path: string): string | null {
+  if (path === from) return "";
+  const prefix = from.endsWith("/") ? from : `${from}/`;
+  return path.startsWith(prefix) ? path.slice(prefix.length - 1) : null;
+}
+
+export function matchRedirect(
+  redirects: readonly HostRoutingRedirect[],
+  host: string,
+  path: string,
+  search: string,
+): { readonly to: string; readonly status: 301 | 302 } | undefined {
+  const hostname = normalizeHostname(host);
+  for (const rule of redirects) {
+    if (rule.host !== undefined && rule.host !== hostname) continue;
+    const remainder = remainderAfter(rule.from, path);
+    if (remainder === null) continue;
+    const target = rule.to.startsWith("https://")
+      ? `${rule.to.replace(/\/$/, "")}${remainder}`
+      : sameOriginPath(`${rule.to.replace(/\/$/, "")}${remainder}`);
+    return { to: `${target}${search}`, status: rule.status ?? 301 };
+  }
+  return undefined;
+}

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

@@ -0,0 +1,65 @@
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  isTenantServingPublicContent,
+  type TenantLifecycleStatus,
+  tenantTable,
+} from "../tenant/index.ts";
+import { classifyHost } from "./host.ts";
+import type { HostRoutingOptions } from "./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.
+export 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;
+}
+
+export async function isTenantServing(db: DbConnection | TenantDb, id: TenantId): Promise<boolean> {
+  const row = await fetchOne<TenantRow>(db, tenantTable, { id });
+  return row !== undefined && isTenantServingPublicContent(row);
+}
+
+export async function servingTenantIdByResolver(
+  options: HostRoutingOptions,
+  db: DbConnection | TenantDb,
+  hostname: string,
+): Promise<TenantId | null> {
+  if (typeof options.tenantBy !== "function") return null;
+  const resolved = await options.tenantBy(hostname, db);
+  return resolved !== null && (await isTenantServing(db, resolved)) ? resolved : null;
+}
+
+// The tenant a Host header belongs to, without any request: subdomain key,
+// resolver result or the apex anchor. Fixed and unknown hosts have none.
+// Meant for features that serve per-tenant content by host, e.g. the
+// `resolveApexTenant` option of managed-pages.
+export function createHostTenantIdResolver(
+  options: HostRoutingOptions,
+  db: DbConnection | TenantDb,
+): (host: string) => Promise<TenantId | null> {
+  return async (host) => {
+    const classified = classifyHost(host, options);
+    switch (classified.kind) {
+      case "subdomain":
+        return options.tenantBy === "host" ? servingTenantIdByKey(db, classified.key) : null;
+      case "resolved":
+        return servingTenantIdByResolver(options, db, classified.hostname);
+      case "apex":
+        return options.apexAnonymousTenantId ?? null;
+      case "fixed":
+      case "unknown":
+        return null;
+    }
+  };
+}

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

@@ -1,9 +1,51 @@
+import { isApexHostname } from "./host.ts";
 import type { HostRoutingOptions } from "./options.ts";
 
 const DOMAIN_PATTERN = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
 const PATH_PREFIX_PATTERN = /^\/[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
 const LOCALE_PATTERN = /^[a-z]{2}(?:-[a-z]{2})?$/;
 
+const REDIRECT_PATH_PATTERN = /^\/[A-Za-z0-9._~/-]*$/;
+// A redirect target is either a same-origin path or an https URL; neither may
+// carry a query or fragment, because the request's query string is appended.
+const REDIRECT_TARGET_PATTERN =
+  /^(?:\/(?!\/)[A-Za-z0-9._~/-]*|https:\/\/[a-z0-9.-]+(?::[0-9]{1,5})?(?:\/[A-Za-z0-9._~/-]*)?)$/;
+
+function validateRedirects(options: HostRoutingOptions): void {
+  for (const rule of options.redirects ?? []) {
+    if (!REDIRECT_PATH_PATTERN.test(rule.from)) {
+      throw new Error(`host-routing: redirect from must be a path like "/old", got "${rule.from}"`);
+    }
+    if (!REDIRECT_TARGET_PATTERN.test(rule.to)) {
+      throw new Error(
+        `host-routing: redirect to must be a same-origin path or an https URL without query, got "${rule.to}"`,
+      );
+    }
+    if (rule.host !== undefined && !DOMAIN_PATTERN.test(rule.host)) {
+      throw new Error(
+        `host-routing: redirect host must be a lowercase hostname, got "${rule.host}"`,
+      );
+    }
+  }
+}
+
+function validateAnonymousQueryAllowlist(options: HostRoutingOptions): void {
+  if (options.apexAnonymousQueryAllowlist !== undefined && options.tenantBy === "path") {
+    // Path mode resolves as fallback-only: a client-sent X-Tenant or cookie wins
+    // before the resolver runs, so the allowlist could never hold.
+    throw new Error(
+      'host-routing: apexAnonymousQueryAllowlist cannot be used with tenantBy "path", because the client names its tenant there and bypasses the allowlist',
+    );
+  }
+  for (const host of Object.keys(options.apexAnonymousQueryAllowlist ?? {})) {
+    if (!isApexHostname(host, options.baseDomain)) {
+      throw new Error(
+        `host-routing: apexAnonymousQueryAllowlist key must be the apex or www.<apex> hostname, got "${host}"`,
+      );
+    }
+  }
+}
+
 // Checked once when the app composes its features, so a config typo fails
 // the boot instead of routing every request to a 404.
 export function validateHostRoutingOptions(options: HostRoutingOptions): void {
@@ -17,11 +59,16 @@ export function validateHostRoutingOptions(options: HostRoutingOptions): void {
       throw new Error(`host-routing: hosts key must be a lowercase hostname, got "${host}"`);
     }
   }
-  if (options.tenantBy === "path" && !PATH_PREFIX_PATTERN.test(options.tenantPathPrefix)) {
+  if (
+    options.tenantPathPrefix !== undefined &&
+    !PATH_PREFIX_PATTERN.test(options.tenantPathPrefix)
+  ) {
     throw new Error(
       `host-routing: tenantPathPrefix must look like "/app" (leading slash, no trailing slash), got "${options.tenantPathPrefix}"`,
     );
   }
+  validateRedirects(options);
+  validateAnonymousQueryAllowlist(options);
   const { locales } = options;
   if (locales !== undefined) {
     for (const locale of [locales.default, ...locales.prefixed]) {

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "Declarative mailbox list and rename screens",
+    "detail": "The feature registers the projectionList mail-accounts (name, address, provider, status, connected; row actions rename and disconnect) and the actionForm mail-account-edit, both restricted to SystemAdmin and TenantAdmin like the handlers. The list shows several mailboxes per tenant, never a credential. Screens are dormant, so the app places the list in its own nav. MAIL_ACCOUNT_LIST_SCREEN_ID and MAIL_ACCOUNT_EDIT_SCREEN_ID are exported.",
+    "migration": "Place mail-accounts in the app nav with r.nav; no other change."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/inbound-mail-foundation/feature.ts

@@ -79,6 +79,7 @@ import { ingestMessageHandler } from "./handlers/ingest-message.write.ts";
 import { listAccountsQuery } from "./handlers/list-accounts.query.ts";
 import { listMessagesQuery } from "./handlers/list-messages.query.ts";
 import { updateAccountHandler } from "./handlers/update-account.write.ts";
+import { INBOUND_MAIL_FOUNDATION_I18N } from "./i18n.ts";
 import {
   applyInboundMessageReceived,
   applyMailAccountConnected,
@@ -90,6 +91,7 @@ import {
   mailThreadsProjectionTable,
 } from "./projection.ts";
 import { runInboundMailRetention } from "./retention-sweep.ts";
+import { mailAccountEditScreen, mailAccountListScreen } from "./screens.ts";
 import {
   INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON,
   inboundMessageTenantDestroyHook,
@@ -195,6 +197,12 @@ export function createInboundMailFoundationFeature() {
       r.queryHandler(listAccountsQuery);
       r.queryHandler(listMessagesQuery);
 
+      // Declarative mailbox admin: list (rename, disconnect) and rename form.
+      // The app places `mailAccountListScreen` via r.nav in its settings area.
+      r.screen(mailAccountListScreen);
+      r.screen(mailAccountEditScreen);
+      r.translations({ keys: INBOUND_MAIL_FOUNDATION_I18N });
+
       // Entity-genaue GDPR-Destroy-Hooks — der gdpr-storage-Boot-Validator
       // prueft die EXT_TENANT_DATA-Registrierung pro tenant-subject-Entity.
       r.useExtension(EXT_TENANT_DATA, "mail-account", {

package/packages/bundled-features/src/inbound-mail-foundation/i18n.ts

@@ -0,0 +1,42 @@
+import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
+import { fieldLabelKey } from "@cosmicdrift/kumiko-renderer/headless";
+import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.ts";
+import {
+  MAIL_ACCOUNT_EDIT_SCREEN_ID,
+  MAIL_ACCOUNT_LIST_SCREEN_ID,
+  MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX,
+} from "./screens.ts";
+
+const formFieldKey = (field: string): string =>
+  fieldLabelKey(INBOUND_MAIL_FOUNDATION_FEATURE, ACTION_FORM_ENTITY, field);
+
+export const INBOUND_MAIL_FOUNDATION_I18N: Readonly<Record<string, { readonly en: string }>> = {
+  [`screen:${MAIL_ACCOUNT_LIST_SCREEN_ID}.title`]: { en: "Mailboxes" },
+  [`screen:${MAIL_ACCOUNT_EDIT_SCREEN_ID}.title`]: { en: "Edit mailbox" },
+  "inboundMail.accounts.col.name": { en: "Name" },
+  "inboundMail.accounts.col.address": { en: "Address" },
+  "inboundMail.accounts.col.provider": { en: "Provider" },
+  "inboundMail.accounts.col.status": { en: "Status" },
+  "inboundMail.accounts.col.connected": { en: "Connected" },
+  [`${MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX}${InboundMailAccountStatuses.active}`]: {
+    en: "Active",
+  },
+  [`${MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX}${InboundMailAccountStatuses.authError}`]: {
+    en: "Sign-in failed",
+  },
+  [`${MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX}${InboundMailAccountStatuses.degraded}`]: {
+    en: "Interrupted",
+  },
+  [`${MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX}${InboundMailAccountStatuses.disconnected}`]: {
+    en: "Disconnected",
+  },
+  "inboundMail.accounts.edit": { en: "Rename" },
+  "inboundMail.accounts.edit.submit": { en: "Save" },
+  "inboundMail.accounts.disconnect": { en: "Disconnect" },
+  "inboundMail.accounts.disconnect.confirm": {
+    en: "Disconnect this mailbox? No new mail is fetched; stored mail is kept.",
+  },
+  [formFieldKey("accountId")]: { en: "Mailbox" },
+  [formFieldKey("displayName")]: { en: "Name" },
+  [formFieldKey("reason")]: { en: "Reason" },
+};

package/packages/bundled-features/src/inbound-mail-foundation/index.ts

@@ -77,6 +77,10 @@ export {
   resolveInboundProviderForAccount,
   resolveInboundProviderForKey,
 } from "./provider-factory.ts";
+export {
+  MAIL_ACCOUNT_EDIT_SCREEN_ID,
+  MAIL_ACCOUNT_LIST_SCREEN_ID,
+} from "./screens.ts";
 export {
   InboundAuthError,
   InboundCursorInvalidError,