@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/mail-transport-smtp/feature.ts

@@ -0,0 +1,268 @@
+// kumiko-feature-version: 1
+//
+// mail-transport-smtp — concrete SMTP-implementation for the
+// mail-foundation plugin-API.
+//
+// **Was diese Feature liefert:**
+//   1. Provider-spezifische Tenant-Config (host/port/secure/from/authUser)
+//      und Secret (smtp.password). Self-contained — mail-foundation kennt
+//      diese Schlüssel nicht; wenn ein App-Owner zwischen SMTP und Brevo-
+//      API wechseln will, hat er pro-Plugin eigenständige Config-Sets.
+//   2. **Plugin-Registration** via `r.useExtension("mailTransport",
+//      "smtp", { build })`. Beim Boot kennt mail-foundation's
+//      Factory-Lookup damit den name "smtp" ↔ build-Funktion.
+//   3. `build(ctx, tenantId)` liest die config-keys + secret und ruft
+//      `createSmtpTransport()` aus channel-email auf. Das ist der
+//      EINZIGE Cross-Feature-Import dieses Plugins — bewusst lokal
+//      gehalten, mail-foundation bleibt provider-frei.
+//
+// **Pattern-Vorbild:** mirrors `channel-email` registering itself for
+// `delivery`. Diese Feature ist analog: registriert sich für
+// mail-foundation's "mailTransport"-Extension-Point.
+//
+// **Boot-Dependencies:**
+//   - `mail-foundation` — extension-point owner
+//   - `config` — für die Tenant-Config-Keys
+//   - `secrets` — für das verschlüsselte SMTP-Password
+
+import type { lookup } from "node:dns/promises";
+import {
+  createSmtpTransport,
+  type EmailTransport,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import {
+  BlockedHostError,
+  HostResolutionError,
+  MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  type MailConnectTarget,
+  readAllowedPrivateMailHostsFromEnv,
+  requireDefined,
+  requireNonEmpty,
+  requireSecretSet,
+  resolveMailConnectTarget,
+} from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import {
+  MAIL_TRANSPORT_EXTENSION,
+  type MailTransportContext,
+  type MailTransportPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import * as z from "zod";
+
+const FEATURE_NAME = "mail-transport-smtp";
+
+const log = createFallbackLogger(FEATURE_NAME);
+
+// Operator escape hatch for an internal relay or a dev/test SMTP server
+// (mailpit, MailHog): KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, an operator env
+// var never a tenant-config value, so a tenant can never grant themselves
+// the private-host bypass. Declared here (not duplicated in
+// inbound-provider-imap's envSchema) since both features read the same
+// var and composeEnvSchema rejects two features declaring the same key —
+// see foundation-shared/mail-host-policy.ts for the shared reader + the
+// guard this feeds.
+export const mailTransportSmtpEnvSchema = z.object({
+  [MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
+    .string()
+    .optional()
+    .describe(
+      "Comma-separated operator allowlist of private/internal hosts (e.g. a local mailpit/greenmail dev server) that bypass the public-address check for SMTP and IMAP host config. Shared with inbound-provider-imap — never a tenant-config value.",
+    ),
+});
+
+// Test-only DNS seam — production never calls this, resolveMailConnectTarget
+// defaults to the real resolver. Lets tests pin deterministic, network-free
+// host resolutions instead of depending on real DNS for a placeholder host.
+// Reset it in afterEach/afterAll — this is module-global state.
+let mailHostLookup: typeof lookup | undefined;
+
+export function setSmtpMailHostLookup(fn: typeof lookup | undefined): void {
+  mailHostLookup = fn;
+}
+
+// =============================================================================
+// Feature-definition
+// =============================================================================
+
+export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers itself as the `"smtp"` provider for `mail-foundation` and owns the per-tenant config keys (`host`, `port`, `secure`, `from`, `authUser`) and the encrypted `smtp.password` secret. Tenants set `mail-foundation`\'s `provider` config key to `"smtp"` to activate it; set the SMTP credentials via the admin UI or a seed handler before sending the first mail.',
+  );
+  r.uiHints({
+    displayLabel: "Mail Transport · SMTP",
+    category: "notifications",
+    recommended: false,
+  });
+  r.requires("config");
+  r.requires("secrets");
+  r.requires("mail-foundation");
+  r.envSchema(mailTransportSmtpEnvSchema);
+
+  // Provider-secret. Sensitive: redact-helper for admin-UI display.
+  const password = r.secret("smtp.password", {
+    label: { en: "SMTP password" },
+    hint: {
+      en: "Login password at the SMTP server. Brevo/Postmark/SES call it 'API key' or 'SMTP credentials'.",
+    },
+    redact: (plaintext) => {
+      if (plaintext.length < 8) return "•".repeat(plaintext.length);
+      return `${plaintext.slice(0, 3)}...${plaintext.slice(-2)}`;
+    },
+    scope: "tenant",
+    // required: true ↔ the missing-secret throw in readPassword — keep in sync.
+    required: true,
+  });
+
+  // required: true ↔ the requireNonEmpty calls in buildSmtpTransport — keep in sync.
+  const configKeys = r.config({
+    keys: {
+      host: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      port: createTenantConfig("number", {
+        default: 587,
+        bounds: { min: 1, max: 65535 },
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      secure: createTenantConfig("boolean", {
+        default: false,
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      from: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      authUser: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+    },
+  });
+
+  // Plugin: register against mail-foundation's "mailTransport" extension.
+  // `entityName` "smtp" is what tenants set in mail-foundation's
+  // `provider` config-key to pick this transport.
+  const plugin: MailTransportPlugin = {
+    build: async (ctx: MailTransportContext, tenantId: string) => buildSmtpTransport(ctx, tenantId), // @wrapper-known semantic-alias
+  };
+  r.useExtension(MAIL_TRANSPORT_EXTENSION, "smtp", plugin);
+
+  return {
+    /** Config-key-handles — typed reads via `ctx.config(...)` in
+     *  consumer handlers. */
+    configKeys,
+    /** Secret-handle for the SMTP password. */
+    password,
+  };
+});
+
+/** Typed handle for the SMTP password — exported so seeds + tests can
+ *  set it via `secrets:write:set` with the full qualified-name. */
+export const SMTP_PASSWORD = mailTransportSmtpFeature.exports.password;
+
+// =============================================================================
+// Internal: build the EmailTransport from tenant config + secret
+// =============================================================================
+
+// Tenant-visible for both a blocked host and a DNS failure — must not
+// reveal which one occurred, or the host itself. Built once so a
+// HostResolutionError raised for the other branch can reuse the exact same
+// `.message` string byte-for-byte instead of just a similar hint.
+function mailHostUnreachableError(): UnconfiguredError {
+  return new UnconfiguredError({
+    feature: FEATURE_NAME,
+    key: "host",
+    hint: "host is not reachable or not allowed",
+  });
+}
+
+async function buildSmtpTransport(
+  ctx: MailTransportContext,
+  tenantId: string,
+): Promise<EmailTransport> {
+  const ctxConfig = ctx.config;
+  if (!ctxConfig) {
+    throw new Error(
+      `${FEATURE_NAME}: ctx.config is missing — feature requires the config-feature mounted in the registry`,
+    );
+  }
+
+  const SMTP_HINT = "Set via tenant-admin UI or seed-handler before sending mail.";
+  const host = requireNonEmpty(
+    await ctxConfig(mailTransportSmtpFeature.exports.configKeys.host),
+    FEATURE_NAME,
+    "host",
+    SMTP_HINT,
+  );
+  const port = requireDefined(
+    await ctxConfig(mailTransportSmtpFeature.exports.configKeys.port),
+    FEATURE_NAME,
+    "port",
+  ) as number; // @cast-boundary engine-payload
+  const secure = requireDefined(
+    await ctxConfig(mailTransportSmtpFeature.exports.configKeys.secure),
+    FEATURE_NAME,
+    "secure",
+  ) as boolean; // @cast-boundary engine-payload
+  const from = requireNonEmpty(
+    await ctxConfig(mailTransportSmtpFeature.exports.configKeys.from),
+    FEATURE_NAME,
+    "from",
+    SMTP_HINT,
+  );
+  const authUser = requireNonEmpty(
+    await ctxConfig(mailTransportSmtpFeature.exports.configKeys.authUser),
+    FEATURE_NAME,
+    "authUser",
+    SMTP_HINT,
+  );
+
+  const password = await readPassword(ctx, tenantId);
+
+  let target: MailConnectTarget;
+  try {
+    target = await resolveMailConnectTarget(host, {
+      allowedPrivateMailHosts: readAllowedPrivateMailHostsFromEnv(),
+      lookupFn: mailHostLookup,
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    // Both branches throw the exact same tenant-visible message text — the
+    // blocked-vs-unresolvable distinction and the host itself stay
+    // server-log-only. Class stays distinct: UnconfiguredError (422, a
+    // config problem, no retry) for a blocked host vs HostResolutionError
+    // (transient, retried) for a DNS failure — see mailHostUnreachableError().
+    const unreachable = mailHostUnreachableError();
+    if (err instanceof BlockedHostError) {
+      log.warn("rejected blocked host", { host, reason });
+      throw unreachable;
+    }
+    log.warn("host resolution failed", { host, reason });
+    throw new HostResolutionError(unreachable.message);
+  }
+
+  return createSmtpTransport({
+    host: target.host,
+    port,
+    secure,
+    from,
+    auth: { user: authUser, pass: password },
+    ...(target.servername && { servername: target.servername }),
+  });
+}
+
+async function readPassword(ctx: MailTransportContext, tenantId: string): Promise<string> {
+  const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+  const branded = await secrets.get(tenantId, SMTP_PASSWORD);
+  return requireSecretSet(branded, FEATURE_NAME, SMTP_PASSWORD.name).reveal();
+}

package/packages/bundled-features/src/mail-transport-smtp/index.ts

@@ -0,0 +1,8 @@
+// Public API of the mail-transport-smtp bundled-feature.
+
+export {
+  mailTransportSmtpEnvSchema,
+  mailTransportSmtpFeature,
+  SMTP_PASSWORD,
+  setSmtpMailHostLookup,
+} from "./feature.js";

package/packages/bundled-features/src/managed-pages/branding.ts

@@ -0,0 +1,173 @@
+import {
+  access,
+  type ConfigAccessor,
+  type ConfigKeyDefinition,
+  createTenantConfig,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type BrandingTokens, EMPTY_BRANDING } from "../page-render/index.js";
+
+// Per-tenant branding, lifted from the publicstatus-local branding-config
+// pattern into the framework so every app + studio-tenant gets tenant-editable
+// branding. Stored as `config` keys (scope: tenant), edited via the
+// configEdit screen (screens/branding-screen.ts), read at render time via the
+// branding query.
+//
+// Write-validated: accent-color must be a CSS hex, logo/site URLs must be
+// https. The configEdit screen dispatches `config:write:set` per key, which
+// runs the keyDef.pattern gate (set.write.ts → validatePattern). `read: all`
+// (scope default) so the anonymous public-render path can read them.
+//
+// `write: access.withSystem(access.admin)` — tenant admins self-service via
+// configEdit AND the system actor (ctx.systemWriteAs) may provision/migrate
+// these keys. The scope default (`access.admin`, admin-only) has no system
+// path, so a continuity migration could not set them (issue #396). Adding
+// SYSTEM_ROLE keeps the keys human-writable (checkWriteAccess collapses to
+// system-only only when system is the SOLE writer), so self-service survives.
+//
+// CONTINUITY (Phase 5 — Prod trap): these keys land under
+// `managed-pages:config:branding-*`, NOT the live `publicstatus:config:
+// branding-*`. The publicstatus consumer (Phase 5) MUST migrate the existing
+// read_config_values rows to the new QNs per tenant BEFORE switching the read
+// path, or every tenant resets to defaults on deploy. The migration is
+// deliberately NOT built here — the source QNs belong to the consumer app.
+
+// Anchored, allow-empty (empty = "unset, use default"; cleared via the form).
+// Linear → ReDoS-safe on untrusted tenant input. The URL char-class mirrors
+// the render-side validator (page-render/branding.ts) so a value that saves
+// also renders. text keys carry an explicit length cap too — `validateType`
+// only checks the JS type, and the configEdit `maxLength` is client-side, so a
+// direct config:write:set would otherwise be unbounded (the page body is
+// likewise capped in Phase 2).
+const HEX_PATTERN = {
+  regex: "^$|^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
+} as const;
+const HTTPS_PATTERN = { regex: "^$|^https://[^\\s\"'<>]{1,2000}$" } as const;
+const TITLE_PATTERN = { regex: "^[\\s\\S]{0,200}$" } as const;
+const DESCRIPTION_PATTERN = { regex: "^[\\s\\S]{0,500}$" } as const;
+// Custom CSS is too complex for a regex allowlist — the write-time pattern only
+// caps length (ReDoS-safe, allow-empty); the real allowlist sanitization runs at
+// render (page-render/css-sanitize.ts). Keep this cap in sync with MAX_CSS_LENGTH
+// there.
+const CUSTOM_CSS_PATTERN = { regex: "^[\\s\\S]{0,8000}$" } as const;
+
+export const LAYOUT_PRESETS = ["minimal", "centered", "wide"] as const;
+
+// Companion toggle feature name. managed-pages reads ctx.hasFeature() against it
+// in the branding query to per-tenant-gate custom-CSS emission. Declared as a
+// `r.toggleable({default:false})` feature in css-gate.ts.
+export const MANAGED_PAGES_CSS_FEATURE = "managed-pages-css";
+
+// Short keys → qualified names via define-feature's `qn(feature, "config",
+// toKebab(key))`: e.g. `brandingSiteUrl` → `managed-pages:config:branding-
+// site-url`. BRANDING_QN below is the single source those QN strings are read
+// from (configEdit screen + render read); the integration test pins write-
+// target == read-source end-to-end.
+// Admin self-service + system provisioning (see write-access note above, #396).
+const BRANDING_WRITE = access.withSystem(access.admin);
+
+export const BRANDING_KEYS = {
+  brandingTitle: createTenantConfig("text", {
+    default: "",
+    pattern: TITLE_PATTERN,
+    write: BRANDING_WRITE,
+  }),
+  brandingDescription: createTenantConfig("text", {
+    default: "",
+    pattern: DESCRIPTION_PATTERN,
+    write: BRANDING_WRITE,
+  }),
+  brandingSiteUrl: createTenantConfig("text", {
+    default: "",
+    pattern: HTTPS_PATTERN,
+    write: BRANDING_WRITE,
+  }),
+  brandingAccentColor: createTenantConfig("text", {
+    default: "",
+    pattern: HEX_PATTERN,
+    write: BRANDING_WRITE,
+  }),
+  brandingLogoUrl: createTenantConfig("text", {
+    default: "",
+    pattern: HTTPS_PATTERN,
+    write: BRANDING_WRITE,
+  }),
+  brandingLayoutPreset: createTenantConfig("select", {
+    default: "centered",
+    options: LAYOUT_PRESETS,
+    write: BRANDING_WRITE,
+  }),
+} satisfies Record<string, ConfigKeyDefinition>;
+
+// Registered ONLY when the app passes allowCustomCss:true — kept out of
+// BRANDING_KEYS so the CSS editor field + key don't exist when the capability is
+// off (fail-closed at the app level). The render-time sanitizer is the real
+// safety boundary; this is the opt-in switch + a per-tenant toggle gate.
+export const CUSTOM_CSS_KEY = {
+  brandingCustomCss: createTenantConfig("text", { default: "", pattern: CUSTOM_CSS_PATTERN }),
+} satisfies Record<string, ConfigKeyDefinition>;
+
+export const BRANDING_QN = {
+  title: "managed-pages:config:branding-title",
+  description: "managed-pages:config:branding-description",
+  siteUrl: "managed-pages:config:branding-site-url",
+  accentColor: "managed-pages:config:branding-accent-color",
+  logoUrl: "managed-pages:config:branding-logo-url",
+  layoutPreset: "managed-pages:config:branding-layout-preset",
+  customCss: "managed-pages:config:branding-custom-css",
+} as const;
+
+export const BRANDING_QUERY_QN = "managed-pages:query:branding";
+
+async function readText(config: ConfigAccessor, qualifiedKey: string): Promise<string> {
+  const value = await config(qualifiedKey);
+  return typeof value === "string" ? value : "";
+}
+
+// Resolve the tenant's branding cascade into render tokens. `config` is
+// optional because ctx.config is only wired when the app composes the config
+// feature — a missing accessor degrades to defaults (same posture as
+// publicstatus' branding read), not a crash.
+export async function readBranding(config: ConfigAccessor | undefined): Promise<BrandingTokens> {
+  if (!config) return EMPTY_BRANDING;
+  const [title, description, siteUrl, accentColor, logoUrl, layoutPreset] = await Promise.all([
+    readText(config, BRANDING_QN.title),
+    readText(config, BRANDING_QN.description),
+    readText(config, BRANDING_QN.siteUrl),
+    readText(config, BRANDING_QN.accentColor),
+    readText(config, BRANDING_QN.logoUrl),
+    readText(config, BRANDING_QN.layoutPreset),
+  ]);
+  // customCss stays "" here — it is gated (allowCustomCss + per-tenant toggle)
+  // and read separately by the branding query via readCustomCss.
+  return { title, description, siteUrl, accentColor, logoUrl, layoutPreset, customCss: "" };
+}
+
+// Read the raw, untrusted custom CSS for the request's tenant. The caller (the
+// branding query) only invokes this once the gate has passed; the value is
+// sanitized at render (page-render), never trusted here.
+export async function readCustomCss(config: ConfigAccessor): Promise<string> {
+  return readText(config, BRANDING_QN.customCss);
+}
+
+function stringField(source: Record<string, unknown>, key: string): string {
+  const value = source[key];
+  return typeof value === "string" ? value : "";
+}
+
+// Coerce the branding query's wire response (`{ data: <BrandingTokens> }`)
+// into BrandingTokens at the IO boundary, without an `as` cast — any missing/
+// non-string field falls back to "" so a malformed/empty response renders the
+// unbranded default rather than throwing.
+export function coerceBranding(value: unknown): BrandingTokens {
+  if (typeof value !== "object" || value === null) return EMPTY_BRANDING;
+  const source = Object.fromEntries(Object.entries(value));
+  return {
+    title: stringField(source, "title"),
+    description: stringField(source, "description"),
+    siteUrl: stringField(source, "siteUrl"),
+    accentColor: stringField(source, "accentColor"),
+    logoUrl: stringField(source, "logoUrl"),
+    layoutPreset: stringField(source, "layoutPreset"),
+    customCss: stringField(source, "customCss"),
+  };
+}

package/packages/bundled-features/src/managed-pages/changes.json

@@ -0,0 +1,25 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Anonymous queries rate-limit per IP and handler instead of sharing one bucket"
+  },
+  {
+    "version": "0.147.3",
+    "type": "fix",
+    "title": "`managed-pages`' `GET {basePath}/:slug` render route and `seo`'s `sitemap.xml`/`llms.txt`…",
+    "detail": "`managed-pages`' `GET {basePath}/:slug` render route and `seo`'s `sitemap.xml`/`llms.txt` routes now use the `systemQuery` in-process dispatch (introduced for `legal-pages` in the `resolverTrust` fix) instead of an internal `app.fetch` self-request with a forged `X-Tenant` header. That self-fetch carried no `Host` header (Host is only implied by the request URL, never stored in `Headers`), so a host-based `anonymousAccess.tenantResolver` reading only the header resolved `null` for the inner request. Under `resolverTrust: \"authoritative\"` there is no client-tenant fallback for a `null` resolution, so the route failed with `tenant_required` (503 \"page unavailable\" / empty sitemap entries) even for a legitimate, correctly-routed visitor. `systemQuery` forces the already host-resolved tenant in-process — no header round-trip, nothing that can go missing. Consumers running `managed-pages` or `seo` with `resolverTrust: \"authoritative\"` should upgrade — the render/discovery routes were not reliably servable under that mode before this fix. - @cosmicdrift/kumiko-framework@0.147.3 - @cosmicdrift/kumiko-dispatcher-live@0.147.3 - @cosmicdrift/kumiko-headless@0.147.3 - @cosmicdrift/kumiko-renderer@0.147.3 - @cosmicdrift/kumiko-renderer-web@0.147.3"
+  },
+  {
+    "version": "0.123.1",
+    "type": "fix",
+    "title": "managed-pages: add a `./managed-pages/web` client export (`managedPagesClient()`) so apps…",
+    "detail": "managed-pages: add a `./managed-pages/web` client export (`managedPagesClient()`) so apps can register the feature's admin-screen translations into the browser i18n store. Previously the server-side `r.translations` bundle never reached the client, so configEdit/entityEdit labels (branding, page CMS) rendered as raw i18n keys in the admin UI. The client bundle is pivoted from the same `MANAGED_PAGES_I18N` source (no key duplication). renderer-web: extract a shared `FormScreenShell` primitive — the canonical centered `max-w-3xl` form/settings column that `DefaultForm` (configEdit/entityEdit) already used. Exporting it lets custom settings screens share the exact same width + centering instead of each author re-inventing the wrapper. `user-data-rights`' privacy-center screen adopts it. - @cosmicdrift/kumiko-renderer-web@0.123.1 - @cosmicdrift/kumiko-framework@0.123.1 - @cosmicdrift/kumiko-dispatcher-live@0.123.1 - @cosmicdrift/kumiko-headless@0.123.1 - @cosmicdrift/kumiko-renderer@0.123.1"
+  },
+  {
+    "version": "0.122.5",
+    "type": "fix",
+    "title": "managed-pages: ship de/en translations for its admin screens (branding settings + page CM…",
+    "detail": "managed-pages: ship de/en translations for its admin screens (branding settings + page CMS) via `r.translations`, so field labels, section headers and screen titles no longer render as raw i18n keys. Any app mounting `managed-pages` now boots with a complete, translated admin surface. Also adds `tag` and `key` to the nav-icon allowlist (`NAV_ICONS`) so nav entries using those keys render a Lucide icon instead of the grey dot fallback. - @cosmicdrift/kumiko-renderer-web@0.122.5 - @cosmicdrift/kumiko-framework@0.122.5 - @cosmicdrift/kumiko-dispatcher-live@0.122.5 - @cosmicdrift/kumiko-headless@0.122.5 - @cosmicdrift/kumiko-renderer@0.122.5"
+  }
+]

package/packages/bundled-features/src/managed-pages/css-gate.ts

@@ -0,0 +1,24 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { MANAGED_PAGES_CSS_FEATURE } from "./branding.js";
+
+// Per-tenant toggle gate for the managed-pages custom-CSS capability. Declares
+// no handlers/entities — composing it simply registers `managed-pages-css` as a
+// `toggleable` feature (default OFF), which an operator/tier can enable per
+// tenant via feature-toggles. managed-pages' branding query reads
+// `ctx.hasFeature("managed-pages-css")` and only emits raw tenant CSS when this
+// toggle is on AND the app passed `allowCustomCss: true`.
+//
+// Without a feature-toggles/tier-engine runtime wired, ctx.hasFeature returns
+// true (apps without tier-cuts treat all features on), so `allowCustomCss`
+// alone governs. To per-tenant tier-gate CSS-inject, compose this feature AND
+// wire feature-toggles; the render-time sanitizer is the safety boundary either
+// way. Compose alongside managed-pages (it `requires` it).
+export function createManagedPagesCssFeature(): FeatureDefinition {
+  return defineFeature(MANAGED_PAGES_CSS_FEATURE, (r) => {
+    r.describe(
+      'Per-tenant toggle gate for the managed-pages custom-CSS (raw tenant CSS-inject) capability. Handler-less: composing it makes `managed-pages-css` a toggleable feature defaulting OFF, so an operator/tier can grant raw CSS-inject per tenant. managed-pages reads `ctx.hasFeature("managed-pages-css")` in its branding query and emits tenant CSS only when this toggle is on AND the app passed `allowCustomCss: true`. The tenant CSS is allowlist-sanitized + scoped at render regardless; this gate is the commercial/operator control, not the safety boundary.',
+    );
+    r.requires("managed-pages");
+    r.toggleable({ default: false });
+  });
+}