@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/mail-foundation/feature.d.ts

@@ -0,0 +1,71 @@
+import { type EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { type ConfigAccessor, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+export declare const MAIL_TRANSPORT_EXTENSION: "mailTransport";
+/**
+ * Schmaler Surface-Type fuer Transport-Plugins — gespiegelt von
+ * file-foundation's FileProviderContext. HandlerContext ist zu fett
+ * (haelt tx, actor, signal etc.); Plugins beschraenken sich auf die
+ * read-Felder die fuer Tenant-Config + Secret-Lookup noetig sind.
+ *
+ * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job-getriggerte
+ * Transport-Builds, z.B. der user-data-rights forget/export-Cron) gibt es
+ * keinen per-request `config`/`tx`/`actor` — der Wrapper baut den per-Tenant-
+ * ConfigAccessor aus `ctx.configResolver`. Ein Plugin das `ctx.tx` oder
+ * andere request-only-Felder liest, wuerde den Worker-Pfad zur Runtime
+ * brechen — und das fiele NUR mit echtem SMTP und nur in production auf.
+ * Cast `ctx as unknown as HandlerContext` macht den Compiler happy, fliegt
+ * aber zur Runtime im Worker. Plugin das mehr braucht: MailTransportContext
+ * explizit erweitern (sichtbarer breaking change) statt ctx-cast.
+ *
+ * **Felder:**
+ *   config   — tenant-config-reads (host/port/from/... der Plugins)
+ *   registry — extension-Lookup in der Factory (nicht plugin-intern)
+ *   secrets  — tenant-secret-reads (smtp.password)
+ *   _userId  — Audit-Identity fuer secret-reads. Handler-Pfad: dispatcher
+ *              setzt Caller-User-ID; Worker-Pfad: r.job-Wrap setzt eine
+ *              System-Identity.
+ */
+export type MailTransportContext = {
+    readonly config?: ConfigAccessor;
+    readonly registry?: Registry;
+    readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
+    readonly _userId?: string | undefined;
+};
+/**
+ * Mail-Transport-Plugin contract. Each provider-feature (mail-transport-
+ * smtp, mail-transport-brevo-api, ...) registers an implementation via
+ * `r.useExtension("mailTransport", "<name>", { build })`.
+ *
+ * `build(ctx, tenantId)` reads the plugin's own config-keys + secrets
+ * (the plugin owns its provider-specific config schema) and constructs
+ * an EmailTransport. Per-call construction so a tenant editing config
+ * sees the change on the next mail.
+ *
+ * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein MailTransportContext,
+ * nicht ein voller HandlerContext (siehe MailTransportContext-Doc).
+ */
+export type MailTransportPlugin = {
+    readonly build: (ctx: MailTransportContext, tenantId: string) => Promise<EmailTransport>;
+};
+export declare function isMailTransportPlugin(o: unknown): o is MailTransportPlugin;
+declare module "@cosmicdrift/kumiko-framework/engine" {
+    interface KumikoExtensionOptionsMap {
+        [MAIL_TRANSPORT_EXTENSION]: MailTransportPlugin;
+    }
+}
+export declare const mailFoundationFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: {
+        /** Config-key-handle for the provider-selector. */
+        providerConfigKey: import("@cosmicdrift/kumiko-types/config").ConfigKeyHandle<"text">;
+    };
+};
+/**
+ * Resolves the tenant's mail-transport. Reads the `provider` config-key,
+ * looks up the matching plugin in the registry, calls its `build(ctx,
+ * tenantId)`-method.
+ *
+ * **Caller pattern:**
+ *   const transport = await createTransportForTenant(ctx, event.user.tenantId);
+ *   await transport.send({ to, subject, html });
+ */
+export declare function createTransportForTenant(ctx: MailTransportContext, tenantId: string, handlerName?: string): Promise<EmailTransport>;

package/dist/mail-foundation/feature.js

@@ -0,0 +1,128 @@
+// kumiko-feature-version: 1
+//
+// mail-foundation as a Kumiko bundled feature.
+//
+// **Was diese Feature liefert:**
+//   1. **Plugin-API** für Mail-Transport-Provider via `r.extendsRegistrar
+//      ("mailTransport", ...)`. Provider-Features (mail-transport-smtp,
+//      mail-transport-brevo-api, ...) registrieren sich namentlich.
+//   2. **Tenant-Config-key** `provider`: select-Wert der zur Runtime
+//      bestimmt welcher registrierte Plugin verwendet wird.
+//   3. **createTransportForTenant(ctx, tenantId)** Factory die den
+//      gewählten Plugin im Registry sucht und seine `build`-Methode
+//      aufruft.
+//
+// **Was diese Foundation NICHT mehr macht (im Vergleich zur ersten
+// Iteration):**
+//   - Keine SMTP/Brevo/Postmark-spezifischen Config-Keys mehr in
+//     mail-foundation. Provider-spezifische Config (host/port/from/
+//     authUser für SMTP, apiUrl/accountId für Brevo etc.) lebt im
+//     jeweiligen Provider-Plugin-Feature.
+//   - Kein direkter Import von `createSmtpTransport`. Die Foundation
+//     kennt nur das `EmailTransport`-Interface (Type-Import, kein
+//     runtime-coupling), nicht die konkrete Implementation.
+//
+// **Pattern-Vorbild:** identisch zu `delivery` + `channel-email`. Die
+// delivery-feature deklariert `r.extendsRegistrar("deliveryChannel")`,
+// channel-email registriert sich via `r.useExtension("deliveryChannel",
+// "email", {...})`. Selbe Trennung Foundation ↔ Provider.
+//
+// **Standalone:** Foundation ist ohne tier-engine nutzbar. Existing
+// `channel-email` (App-wide-Mail-Sender via delivery) bleibt unangetastet
+// — additive Feature.
+import { withPiiCiphertextGuard, } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { access, createTenantConfig, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
+const FEATURE_NAME = "mail-foundation";
+// Extension-point name for transport-provider plugins (mail-transport-smtp,
+// mail-transport-brevo-api, ...).
+export const MAIL_TRANSPORT_EXTENSION = "mailTransport";
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind. Mirrors file-foundation's isFileProviderPlugin.
+export function isMailTransportPlugin(o) {
+    return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
+}
+// =============================================================================
+// Feature-definition
+// =============================================================================
+export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
+    r.describe("Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending \u2014 use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.");
+    r.uiHints({
+        displayLabel: "Mail Transport Foundation",
+        category: "notifications",
+        recommended: false,
+    });
+    r.requires("config");
+    // Plugin extension-point. Provider-features register here. The
+    // entityName at registration time becomes the value tenants pick in
+    // `provider` config-key (e.g. "smtp", "brevo-api").
+    r.extendsRegistrar(MAIL_TRANSPORT_EXTENSION, {
+        onRegister: () => {
+            // No side-effects at register-time — the registry stores the
+            // usage, factory looks it up at request-time. Same shape as
+            // delivery's extendsRegistrar.
+        },
+    });
+    // Provider-selector. Default empty so the boot-validator throws if a
+    // tenant tries to send mail without first picking + setting up a
+    // provider — better than a silent fallback. The actual list of valid
+    // values lives in the registered plugins, not here — Designer-UI can
+    // render `getExtensionUsages("mailTransport").map(u => u.entityName)`
+    // as the option-list.
+    const providerConfigKey = r.config("provider", createTenantConfig("text", {
+        default: "",
+        // required: ohne gewählten Provider wirft createTransportForTenant —
+        // readiness meldete vorher ready:true und der erste Mail-Send
+        // lieferte den UnconfiguredError (280/1).
+        required: true,
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+    }));
+    // Readiness gating: transport-plugins' required keys/secrets count only
+    // while their plugin is the one this key selects.
+    r.extensionSelector(MAIL_TRANSPORT_EXTENSION, providerConfigKey);
+    return {
+        /** Config-key-handle for the provider-selector. */
+        providerConfigKey,
+    };
+});
+// =============================================================================
+// Transport-factory — looks up the registered plugin + delegates
+// =============================================================================
+/**
+ * Resolves the tenant's mail-transport. Reads the `provider` config-key,
+ * looks up the matching plugin in the registry, calls its `build(ctx,
+ * tenantId)`-method.
+ *
+ * **Caller pattern:**
+ *   const transport = await createTransportForTenant(ctx, event.user.tenantId);
+ *   await transport.send({ to, subject, html });
+ */
+export async function createTransportForTenant(ctx, tenantId, handlerName = "mail-foundation:transport-factory") {
+    const ctxConfig = ctx.config;
+    if (!ctxConfig) {
+        throw new Error(`${handlerName}: ctx.config is missing — feature requires the config-feature mounted in the registry`);
+    }
+    if (!ctx.registry) {
+        throw new Error(`${handlerName}: ctx.registry is missing — required to look up registered mail-transport plugins`);
+    }
+    const provider = requireDefined(await ctxConfig(mailFoundationFeature.exports.providerConfigKey), FEATURE_NAME, "provider"); // @cast-boundary engine-payload
+    if (provider.length === 0) {
+        const usages = ctx.registry.getExtensionUsages(MAIL_TRANSPORT_EXTENSION);
+        const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+        throw new Error(`${FEATURE_NAME}: no provider selected — set the 'provider' config-key to one of: ${known}. ` +
+            `Mount a mail-transport-* feature first if no plugins are registered.`);
+    }
+    const usages = ctx.registry.getExtensionUsages(MAIL_TRANSPORT_EXTENSION);
+    const usage = usages.find((u) => u.entityName === provider);
+    if (!usage) {
+        const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+        throw new Error(`${FEATURE_NAME}: provider "${provider}" not registered. Known: ${known}. ` +
+            `Mount the matching mail-transport-${provider} feature.`);
+    }
+    if (!isMailTransportPlugin(usage.options)) {
+        throw new Error(`${FEATURE_NAME}: provider "${provider}" registered without a build() — ` +
+            `extension options must be a MailTransportPlugin.`);
+    }
+    return withPiiCiphertextGuard(await usage.options.build(ctx, tenantId));
+}

package/dist/mail-foundation/index.d.ts

@@ -0,0 +1 @@
+export { createTransportForTenant, isMailTransportPlugin, MAIL_TRANSPORT_EXTENSION, type MailTransportContext, type MailTransportPlugin, mailFoundationFeature, } from "./feature.js";

package/dist/mail-foundation/index.js

@@ -0,0 +1,9 @@
+// Public API of the mail-foundation bundled-feature.
+//
+// **What downstream apps import:**
+//   - `mailFoundationFeature` — register at app boot
+//   - `createTransportForTenant(ctx, tenantId)` — async factory: looks
+//     up the registered transport-plugin, returns its EmailTransport
+//   - `MailTransportPlugin` — type that provider-features implement
+//     when registering via `r.useExtension("mailTransport", ...)`
+export { createTransportForTenant, isMailTransportPlugin, MAIL_TRANSPORT_EXTENSION, mailFoundationFeature, } from "./feature.js";

package/dist/mail-transport-inmemory/feature.d.ts

@@ -0,0 +1,14 @@
+import type { EmailMessage } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+/**
+ * Demo/Test-Helper: lies die "versendeten" Mails eines Tenants. Im
+ * Sample-App rendert ein query-Handler darauf die Inbox-UI.
+ */
+export declare function getInbox(tenantId: string): readonly EmailMessage[];
+/**
+ * Demo/Test-Helper: clear einen Tenant-Buffer (z.B. zwischen Test-
+ * Szenarien).
+ */
+export declare function clearInbox(tenantId: string): void;
+export declare const mailTransportInMemoryFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};

package/dist/mail-transport-inmemory/feature.js

@@ -0,0 +1,78 @@
+// kumiko-feature-version: 1
+//
+// mail-transport-inmemory — In-Memory-EmailTransport für die mail-
+// foundation Plugin-API. Sammelt Mails in einem per-Tenant-Buffer
+// statt sie über einen echten SMTP-Server zu senden. Designed für
+// Demos, Sample-Apps und Tests die ohne Mailpit/Mailcrab/echten SMTP
+// laufen sollen.
+//
+// **Was diese Feature liefert:**
+//   1. Plugin-Registration via `r.useExtension("mailTransport",
+//      "inmemory", { build })`. Tenants setzen
+//      "mail-foundation:config:provider" auf "inmemory" und kriegen
+//      die buffered-Variante.
+//   2. **Pro-Tenant Inbox.** Jeder Tenant hat einen eigenen
+//      Mail-Buffer (Map<tenantId, EmailMessage[]>). Demo-Apps können
+//      die Inbox via `getInbox(tenantId)` lesen + UI rendern.
+//
+// **Pattern-Vorbild:** mirrors mail-transport-smtp.
+//
+// **NICHT für Production.** Buffer ist im Process-Memory, geht beim
+// Restart verloren. Cap-Counter / Audit-Trail bleiben trotzdem korrekt
+// — die hängen am event-store, nicht am Transport.
+import { createInMemoryTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { MAIL_TRANSPORT_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+const FEATURE_NAME = "mail-transport-inmemory";
+// =============================================================================
+// Per-tenant in-memory buffer
+// =============================================================================
+//
+// Module-level Map weil der Plugin-build-call pro Send einen neuen
+// Transport-Wrapper baut, aber wir wollen dass alle Wrapper für
+// denselben Tenant auf denselben Buffer zeigen. Map<tenantId,
+// InMemoryTransport>.
+const transportsByTenant = new Map();
+function getOrCreateTransportForTenant(tenantId) {
+    let transport = transportsByTenant.get(tenantId);
+    if (!transport) {
+        transport = createInMemoryTransport();
+        transportsByTenant.set(tenantId, transport);
+    }
+    return transport;
+}
+/**
+ * Demo/Test-Helper: lies die "versendeten" Mails eines Tenants. Im
+ * Sample-App rendert ein query-Handler darauf die Inbox-UI.
+ */
+export function getInbox(tenantId) {
+    return transportsByTenant.get(tenantId)?.sent ?? [];
+}
+/**
+ * Demo/Test-Helper: clear einen Tenant-Buffer (z.B. zwischen Test-
+ * Szenarien).
+ */
+export function clearInbox(tenantId) {
+    const t = transportsByTenant.get(tenantId);
+    if (t)
+        t.sent.length = 0;
+}
+// =============================================================================
+// Feature-definition
+// =============================================================================
+export const mailTransportInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
+    r.describe('Registers an in-process `"inmemory"` provider for `mail-foundation` that buffers sent mails per tenant instead of contacting an SMTP server. Use `getInbox(tenantId)` and `clearInbox(tenantId)` in demo apps and tests; not for production (buffer is process-memory, lost on restart).');
+    // Kein r.requires("config") + kein r.requires("secrets") — der
+    // In-Memory-Transport hat keine Config (nichts zu konfigurieren) und
+    // kein Secret. Der einzige hard-require ist mail-foundation, das den
+    // extension-point "mailTransport" definiert.
+    r.requires("mail-foundation");
+    const plugin = {
+        build: async (_ctx, tenantId) => {
+            // Returnt den per-tenant Buffer. Identitätsstabil zwischen calls
+            // damit die Demo-Inbox accumulated bleibt.
+            return getOrCreateTransportForTenant(tenantId);
+        }, // @wrapper-known semantic-alias
+    };
+    r.useExtension(MAIL_TRANSPORT_EXTENSION, "inmemory", plugin);
+});

package/dist/mail-transport-inmemory/index.d.ts

@@ -0,0 +1 @@
+export { clearInbox, getInbox, mailTransportInMemoryFeature } from "./feature.js";

package/dist/mail-transport-inmemory/index.js

@@ -0,0 +1,2 @@
+// Public API of the mail-transport-inmemory bundled-feature.
+export { clearInbox, getInbox, mailTransportInMemoryFeature } from "./feature.js";

package/dist/mail-transport-smtp/feature.d.ts

@@ -0,0 +1,24 @@
+import type { lookup } from "node:dns/promises";
+import * as z from "zod";
+export declare const mailTransportSmtpEnvSchema: z.ZodObject<{
+    KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function setSmtpMailHostLookup(fn: typeof lookup | undefined): void;
+export declare const mailTransportSmtpFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: {
+        /** Config-key-handles — typed reads via `ctx.config(...)` in
+         *  consumer handlers. */
+        configKeys: {
+            readonly host: import("@cosmicdrift/kumiko-types/config").ConfigKeyHandle<"text">;
+            readonly port: import("@cosmicdrift/kumiko-types/config").ConfigKeyHandle<"number">;
+            readonly secure: import("@cosmicdrift/kumiko-types/config").ConfigKeyHandle<"boolean">;
+            readonly from: import("@cosmicdrift/kumiko-types/config").ConfigKeyHandle<"text">;
+            readonly authUser: import("@cosmicdrift/kumiko-types/config").ConfigKeyHandle<"text">;
+        };
+        /** Secret-handle for the SMTP password. */
+        password: import("@cosmicdrift/kumiko-types/feature").SecretKeyHandle;
+    };
+};
+/** Typed handle for the SMTP password — exported so seeds + tests can
+ *  set it via `secrets:write:set` with the full qualified-name. */
+export declare const SMTP_PASSWORD: import("@cosmicdrift/kumiko-types/feature").SecretKeyHandle;

package/dist/mail-transport-smtp/feature.js

@@ -0,0 +1,199 @@
+// 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 { createSmtpTransport, } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, readAllowedPrivateMailHostsFromEnv, requireDefined, requireNonEmpty, requireSecretSet, resolveMailConnectTarget, } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { MAIL_TRANSPORT_EXTENSION, } 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;
+export function setSmtpMailHostLookup(fn) {
+    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 = {
+        build: async (ctx, tenantId) => 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() {
+    return new UnconfiguredError({
+        feature: FEATURE_NAME,
+        key: "host",
+        hint: "host is not reachable or not allowed",
+    });
+}
+async function buildSmtpTransport(ctx, tenantId) {
+    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"); // @cast-boundary engine-payload
+    const secure = requireDefined(await ctxConfig(mailTransportSmtpFeature.exports.configKeys.secure), FEATURE_NAME, "secure"); // @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;
+    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, tenantId) {
+    const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+    const branded = await secrets.get(tenantId, SMTP_PASSWORD);
+    return requireSecretSet(branded, FEATURE_NAME, SMTP_PASSWORD.name).reveal();
+}

package/dist/mail-transport-smtp/index.d.ts

@@ -0,0 +1 @@
+export { mailTransportSmtpEnvSchema, mailTransportSmtpFeature, SMTP_PASSWORD, setSmtpMailHostLookup, } from "./feature.js";

package/dist/mail-transport-smtp/index.js

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

package/dist/managed-pages/branding.d.ts

@@ -0,0 +1,28 @@
+import { type ConfigAccessor, type ConfigKeyDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type BrandingTokens } from "../page-render/index.js";
+export declare const LAYOUT_PRESETS: readonly ["minimal", "centered", "wide"];
+export declare const MANAGED_PAGES_CSS_FEATURE = "managed-pages-css";
+export declare const BRANDING_KEYS: {
+    brandingTitle: ConfigKeyDefinition<"text">;
+    brandingDescription: ConfigKeyDefinition<"text">;
+    brandingSiteUrl: ConfigKeyDefinition<"text">;
+    brandingAccentColor: ConfigKeyDefinition<"text">;
+    brandingLogoUrl: ConfigKeyDefinition<"text">;
+    brandingLayoutPreset: ConfigKeyDefinition<"select">;
+};
+export declare const CUSTOM_CSS_KEY: {
+    brandingCustomCss: ConfigKeyDefinition<"text">;
+};
+export declare const BRANDING_QN: {
+    readonly title: "managed-pages:config:branding-title";
+    readonly description: "managed-pages:config:branding-description";
+    readonly siteUrl: "managed-pages:config:branding-site-url";
+    readonly accentColor: "managed-pages:config:branding-accent-color";
+    readonly logoUrl: "managed-pages:config:branding-logo-url";
+    readonly layoutPreset: "managed-pages:config:branding-layout-preset";
+    readonly customCss: "managed-pages:config:branding-custom-css";
+};
+export declare const BRANDING_QUERY_QN = "managed-pages:query:branding";
+export declare function readBranding(config: ConfigAccessor | undefined): Promise<BrandingTokens>;
+export declare function readCustomCss(config: ConfigAccessor): Promise<string>;
+export declare function coerceBranding(value: unknown): BrandingTokens;