@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/legal-pages/web/client-plugin.ts

@@ -0,0 +1,81 @@
+// @runtime client
+// Client-Feature-Factory für legal-pages Visual-Tree. Liefert statische
+// Tree-Knoten für die DACH-Compliance-Blöcke (imprint, privacy in de/en).
+// Jeder Knoten linkt auf text-content's edit-Action — reines Cross-Feature-
+// Linking, kein eigener State oder Fetch nötig.
+//
+// **Static statt fetch**: legal-pages weiß out-of-the-box welche Blocks
+// existieren (LEGAL_REQUIRED_BLOCKS + LEGAL_OPTIONAL_BLOCKS aus constants).
+// Anders als text-content's Provider (der alle Slugs des Tenants holt)
+// ist diese Liste bekannt zur Build-Zeit — kein /api/query-Round-trip nötig.
+//
+// **Content-State unbekannt**: V.1.2 setzt keine state-Markierung; alle
+// Knoten erscheinen "filled" (default). V.1.3+ könnte via by-slug-Query
+// ermitteln ob ein Block tatsächlich body hat und „stub" markieren wenn
+// leer (Provider-Author-Hinweis dass Block existiert aber befüllt werden
+// muss). Aktuell ist legal-pages's Boot-Check der primäre Wächter für
+// fehlende Pflicht-Blocks.
+
+import type { TreeChildrenSubscribe, TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { LEGAL_OPTIONAL_BLOCKS, LEGAL_REQUIRED_BLOCKS } from "../constants.js";
+
+const treeProvider: TreeChildrenSubscribe = () => (emit) => {
+  // V.1.5d Slug-first Verschachtelung (Variante C):
+  //   📁 Legal
+  //     📁 imprint
+  //       de
+  //       en
+  //     📁 privacy
+  //       de
+  //       en
+  //
+  // Slug ist der Übersetzungs-Anker — User pflegt DE+EN-Versionen
+  // desselben Inhalts zusammen statt nach Sprache zu gruppieren.
+  // Sub-Items sind reine Sprach-Leaves; Label = Sprache, target zeigt
+  // auf template-resolver:edit mit slug+locale.
+
+  // Group all blocks by slug, collect set of langs per slug.
+  const bySlug = new Map<string, string[]>();
+  for (const b of [...LEGAL_REQUIRED_BLOCKS, ...LEGAL_OPTIONAL_BLOCKS]) {
+    const langs = bySlug.get(b.slug) ?? [];
+    if (!langs.includes(b.lang)) langs.push(b.lang);
+    bySlug.set(b.slug, langs);
+  }
+
+  const slugFolders: TreeNode[] = [];
+  for (const slug of [...bySlug.keys()].sort()) {
+    const langs = bySlug.get(slug);
+    if (langs === undefined) continue;
+    const langLeaves: TreeNode[] = langs.sort().map((lang) => ({
+      label: lang,
+      target: {
+        featureId: "template-resolver",
+        action: "edit",
+        args: { slug, locale: lang },
+      },
+    }));
+    slugFolders.push({
+      label: slug,
+      icon: "folder",
+      state: "filled",
+      children: langLeaves,
+    });
+  }
+
+  // Der App-seitige r.nav-Knoten IST der "Legal"-Container → der Provider
+  // emittiert die slug-Folder direkt darunter.
+  emit(slugFolders);
+  return () => {};
+};
+
+// `navId` = QN des r.nav({ provider: true })-Knotens den die App registriert.
+// Statisch (kein Fetch, keine Entities) → kein SSE-Refresh nötig. Ohne navId:
+// kein Sidebar-Knoten (server-only-Consumer leaken nichts).
+export function legalPagesClient(opts?: { readonly navId?: string }): ClientFeatureDefinition {
+  const navId = opts?.navId;
+  return {
+    name: "legal-pages",
+    ...(navId !== undefined && { navProviders: { [navId]: treeProvider } }),
+  };
+}

package/packages/bundled-features/src/legal-pages/web/index.ts

@@ -0,0 +1,4 @@
+// @runtime client
+// Public exports für die Browser-Seite des legal-pages Features.
+
+export { legalPagesClient } from "./client-plugin.js";

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

@@ -0,0 +1 @@
+[]

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

@@ -0,0 +1,233 @@
+// 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 {
+  type EmailTransport,
+  withPiiCiphertextGuard,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import {
+  access,
+  type ConfigAccessor,
+  createTenantConfig,
+  defineFeature,
+  type Registry,
+} 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" as const;
+
+// =============================================================================
+// Plugin-Interface — what a Provider-Plugin must implement
+// =============================================================================
+
+/**
+ * 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>;
+};
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind. Mirrors file-foundation's isFileProviderPlugin.
+export function isMailTransportPlugin(o: unknown): o is MailTransportPlugin {
+  return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
+}
+
+// r.useExtension options-shape, co-located since the framework never imports upward.
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [MAIL_TRANSPORT_EXTENSION]: MailTransportPlugin;
+  }
+}
+
+// =============================================================================
+// 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: MailTransportContext,
+  tenantId: string,
+  handlerName = "mail-foundation:transport-factory",
+): Promise<EmailTransport> {
+  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",
+  ) as string; // @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/packages/bundled-features/src/mail-foundation/index.ts

@@ -0,0 +1,17 @@
+// 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,
+  type MailTransportContext,
+  type MailTransportPlugin,
+  mailFoundationFeature,
+} from "./feature.js";

package/packages/bundled-features/src/mail-transport-inmemory/changes.json

@@ -0,0 +1 @@
+[]

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

@@ -0,0 +1,97 @@
+// 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 type {
+  EmailMessage,
+  EmailTransport,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { createInMemoryTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import {
+  MAIL_TRANSPORT_EXTENSION,
+  type MailTransportContext,
+  type MailTransportPlugin,
+} 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<string, ReturnType<typeof createInMemoryTransport>>();
+
+function getOrCreateTransportForTenant(tenantId: string) {
+  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: string): readonly EmailMessage[] {
+  return transportsByTenant.get(tenantId)?.sent ?? [];
+}
+
+/**
+ * Demo/Test-Helper: clear einen Tenant-Buffer (z.B. zwischen Test-
+ * Szenarien).
+ */
+export function clearInbox(tenantId: string): void {
+  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: MailTransportPlugin = {
+    build: async (_ctx: MailTransportContext, tenantId: string): Promise<EmailTransport> => {
+      // 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/packages/bundled-features/src/mail-transport-inmemory/index.ts

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

package/packages/bundled-features/src/mail-transport-smtp/changes.json

@@ -0,0 +1,20 @@
+[
+  {
+    "version": "0.326.1",
+    "type": "fix",
+    "title": "Mail stack on patched nodemailer 10, imapflow and mailparser",
+    "detail": "Bumps nodemailer to ^10.0.13 (GHSA-v53p-9fqp-m79j, high), mailparser to ^3.9.32 and imapflow to ^1.7.8 so no dependency pins a vulnerable nodemailer 9.x any more. nodemailer 10 ships its own types, so @types/nodemailer is dropped; it requires Node.js >= 20. No API change for kumiko apps."
+  },
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "The tenant-configured SMTP host must resolve to a public address",
+    "migration": "An operator relying on an internal SMTP relay or a local dev/test server\n(mailpit, MailHog on localhost or a private IP) now gets a build-time\n422 (code \"unconfigured\", naming the \"host\" config-key) unless that host\nis explicitly allowed. Set the operator env var (comma-separated, read\nat connect time — no boot-time code call needed) before starting the\nprocess:\n  KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS=mailpit.internal\nThis is an operator env var, not a tenant config value — a tenant cannot\nadd their own host to this list. Shared with inbound-provider-imap: one\nenv var covers both SMTP and IMAP allowlisting. A DNS resolution failure\nfor a genuinely unreachable host now surfaces distinctly (not as\n\"unconfigured\") instead of only failing later at first-send time."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "SMTP connect failures no longer distinguish a blocked host from a DNS failure in the thrown message",
+    "detail": "`buildSmtpTransport` throws an `UnconfiguredError` for a blocked host and\na `HostResolutionError` for a DNS failure — both classes unchanged for\nretry semantics — but the `.message` text is now byte-identical between\nthe two (\"... host is not reachable or not allowed\"). The configured\nhost and the underlying error are now logged via the feature's own\nlogger instead of being embedded in the thrown message."
+  }
+]