@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/mail-foundation/__tests__/feature.test.ts

@@ -0,0 +1,46 @@
+// feature.ts contract tests — pin the public surface of the
+// Plugin-API-shaped mail-foundation. Provider-specific configs/secrets
+// are tested in their own provider-feature (mail-transport-smtp/__tests__).
+//
+// **Pattern-Vorbild:** mirrors delivery-feature shape — the foundation
+// declares an extension-point + a single selector config-key, nothing
+// provider-concrete.
+
+import { describe, expect, test } from "vitest";
+import { mailFoundationFeature } from "../feature";
+
+describe("mailFoundationFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(mailFoundationFeature.name).toBe("mail-foundation");
+  });
+
+  test("declares config as a hard requirement (provider-selector lives there)", () => {
+    expect(mailFoundationFeature.requires).toContain("config");
+  });
+
+  test("does NOT require secrets — provider-plugins own their own secrets", () => {
+    // The foundation knows nothing about SMTP-passwords; only the SMTP
+    // plugin-feature requires secrets. This separation lets a Brevo-
+    // API-only deployment skip the secrets-feature if Brevo's provider
+    // uses tenant-config text-keys instead.
+    expect(mailFoundationFeature.requires).not.toContain("secrets");
+  });
+});
+
+describe("mailFoundationFeature.exports — typed handles", () => {
+  test("exposes only the provider-selector config-key", () => {
+    const keys = mailFoundationFeature.exports.configKeys;
+    expect(keys.provider).toBeDefined();
+    // No host/port/from/authUser — those live in the provider-plugin.
+    expect((keys as Record<string, unknown>)["host"]).toBeUndefined();
+    expect((keys as Record<string, unknown>)["port"]).toBeUndefined();
+  });
+});
+
+describe("mailFoundationFeature — registers extension-point", () => {
+  test("declares the 'mailTransport' extension-point that providers register against", () => {
+    // r.extendsRegistrar("mailTransport", ...) lands in
+    // feature.registrarExtensions keyed by extension-name.
+    expect(mailFoundationFeature.registrarExtensions["mailTransport"]).toBeDefined();
+  });
+});

package/src/mail-foundation/__tests__/mail-foundation.integration.ts

@@ -0,0 +1,247 @@
+// Full-stack integration test for mail-foundation. Drives the
+// transport-factory through the dispatcher so the real config-resolver +
+// secrets-context + tenant-scoped reads are exercised — the same path
+// production handlers will hit when sending mail.
+//
+// **Test-Handler-Pattern:** we register a tiny one-off feature with a
+// write-handler that calls createTransportForTenant + reports back what
+// it saw. That's the cheapest way to get a real `HandlerContext` in a
+// test without re-implementing the dispatcher.
+
+import { randomBytes } from "node:crypto";
+import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  createEntityTable,
+  createTestUser,
+  pushTables,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createMutableMasterKeyProvider,
+  type MutableMasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createConfigFeature } from "../../config";
+import { ConfigHandlers } from "../../config/constants";
+import { createConfigAccessorFactory } from "../../config/feature";
+import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { mailTransportSmtpFeature, SMTP_PASSWORD } from "../../mail-transport-smtp";
+import { createSecretsContext, createSecretsFeature, tenantSecretsTable } from "../../secrets";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createTransportForTenant, mailFoundationFeature } from "../feature";
+
+// --- Test-Handler that exercises the factory end-to-end ---
+
+const TEST_HANDLER_QN = "mail-test:write:build-transport";
+const testProbeFeature = defineFeature("mail-test", (r) => {
+  r.requires("config");
+  r.requires("secrets");
+  r.writeHandler(
+    defineWriteHandler({
+      name: "build-transport",
+      schema: z.object({}),
+      access: { roles: ["TenantAdmin", "SystemAdmin"] },
+      handler: async (event, ctx) => {
+        const transport = await createTransportForTenant(ctx, event.user.tenantId, TEST_HANDLER_QN);
+        return {
+          isSuccess: true,
+          data: { hasSend: typeof transport.send === "function" },
+        };
+      },
+    }),
+  );
+});
+
+// --- Setup ---
+
+let stack: TestStack;
+let db: DbConnection;
+let resolver: ConfigResolver;
+let providerRef: MutableMasterKeyProvider;
+
+const testEncryptionKey = randomBytes(32).toString("base64");
+
+beforeAll(async () => {
+  const encryption = createEncryptionProvider(testEncryptionKey);
+  resolver = createConfigResolver({ encryption });
+
+  // Master-key for the secrets-feature. Production env shape:
+  //   KUMIKO_SECRETS_MASTER_KEY_V1=<base64 32 bytes>
+  //   KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION=1
+  const initialKp = createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  });
+  providerRef = createMutableMasterKeyProvider(initialKp);
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createSecretsFeature(),
+      mailFoundationFeature,
+      mailTransportSmtpFeature,
+      testProbeFeature,
+    ],
+    masterKeyProvider: providerRef,
+    extraContext: ({ db, registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      // _configAccessorFactory wires `ctx.config(handle)` for every
+      // dispatched handler. Without it createTransportForTenant fails
+      // with "ctx.config is missing".
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      secrets: createSecretsContext({ db, masterKeyProvider: providerRef }),
+    }),
+  });
+  db = stack.db;
+
+  await createEntityTable(db, tenantEntity);
+  await pushTables(db, { configValuesTable, tenant_secrets: tenantSecretsTable });
+  await createEventsTable(db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+}
+
+async function setConfig(admin: ReturnType<typeof adminFor>, key: string, value: unknown) {
+  await stack.http.writeOk(ConfigHandlers.set, { key, value }, admin);
+}
+
+/** Set the mail-foundation provider-selector to "smtp". Plugin-API
+ *  needs this — without it the foundation-factory doesn't know which
+ *  registered transport to use. */
+async function selectSmtpProvider(admin: ReturnType<typeof adminFor>) {
+  await setConfig(admin, "mail-foundation:config:provider", "smtp");
+}
+
+// --- Scenario 1: full happy-path roundtrip ---
+
+describe("scenario 1: happy path", () => {
+  test("admin sets config + secret → factory builds working transport", async () => {
+    const admin = adminFor(401);
+
+    // Plugin-API: select "smtp" — foundation looks it up in the registry.
+    await selectSmtpProvider(admin);
+
+    // Tenant configures their SMTP — Mailhog-style local test server.
+    await setConfig(admin, "mail-transport-smtp:config:host", "localhost");
+    await setConfig(admin, "mail-transport-smtp:config:port", 1025);
+    await setConfig(admin, "mail-transport-smtp:config:from", "noreply@test.local");
+    await setConfig(admin, "mail-transport-smtp:config:auth-user", "admin@test.local");
+
+    // Sensitive: SMTP password via the secrets-write handler.
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: SMTP_PASSWORD.name, value: "test-password-123" },
+      admin,
+    );
+
+    // Drive the factory through a dispatcher-real test-handler.
+    // writeOk returns the handler's TData (custom-shaped). For the
+    // crud-pattern (tenant/user features) TData is a SaveContext
+    // (`{ data, isNew, ... }`); our test-handler returns plain
+    // `{ hasSend }` so writeOk's response is just `{ hasSend }`.
+    const result = (await stack.http.writeOk(TEST_HANDLER_QN, {}, admin)) as Record<
+      string,
+      unknown
+    >;
+    expect(result["hasSend"]).toBe(true);
+  });
+});
+
+// --- Scenario 2: missing host config is rejected with a clear error ---
+
+describe("scenario 2: validation errors", () => {
+  test("missing host → factory throws with hint instead of a cryptic SMTP error", async () => {
+    const admin = adminFor(402);
+
+    await selectSmtpProvider(admin);
+    // Set everything EXCEPT host. The plugin should fail with a
+    // message naming the missing key before touching nodemailer.
+    await setConfig(admin, "mail-transport-smtp:config:port", 587);
+    await setConfig(admin, "mail-transport-smtp:config:from", "noreply@test.local");
+    await setConfig(admin, "mail-transport-smtp:config:auth-user", "admin@test.local");
+    await stack.http.writeOk("secrets:write:set", { key: SMTP_PASSWORD.name, value: "pw" }, admin);
+
+    // writeOk would throw an assertion-error; use writeRaw + check status.
+    const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
+    expect(JSON.stringify(error)).toMatch(/'host' is empty/);
+  });
+
+  test("missing password secret → factory throws naming the secret", async () => {
+    const admin = adminFor(403);
+
+    await selectSmtpProvider(admin);
+    await setConfig(admin, "mail-transport-smtp:config:host", "localhost");
+    await setConfig(admin, "mail-transport-smtp:config:port", 587);
+    await setConfig(admin, "mail-transport-smtp:config:from", "noreply@test.local");
+    await setConfig(admin, "mail-transport-smtp:config:auth-user", "admin@test.local");
+    // Skip the secret. requireSecretsContext.get returns undefined,
+    // factory throws referencing SMTP_PASSWORD.name.
+
+    const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
+    expect(JSON.stringify(error)).toMatch(/smtp-password/);
+  });
+});
+
+// --- Scenario 3: tenant isolation (config + secret stay per-tenant) ---
+
+describe("scenario 3: tenant isolation", () => {
+  test("tenant A's SMTP config doesn't bleed into tenant B's transport", async () => {
+    const adminA = adminFor(404);
+    const adminB = adminFor(405);
+
+    await selectSmtpProvider(adminA);
+    await selectSmtpProvider(adminB);
+
+    // Tenant A configures their SMTP.
+    await setConfig(adminA, "mail-transport-smtp:config:host", "smtp.tenant-a.test");
+    await setConfig(adminA, "mail-transport-smtp:config:port", 587);
+    await setConfig(adminA, "mail-transport-smtp:config:from", "a@tenant-a.test");
+    await setConfig(adminA, "mail-transport-smtp:config:auth-user", "a-user");
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: SMTP_PASSWORD.name, value: "pw-a" },
+      adminA,
+    );
+
+    // Tenant B has their OWN SMTP — different host on purpose.
+    await setConfig(adminB, "mail-transport-smtp:config:host", "smtp.tenant-b.test");
+    await setConfig(adminB, "mail-transport-smtp:config:port", 465);
+    await setConfig(adminB, "mail-transport-smtp:config:from", "b@tenant-b.test");
+    await setConfig(adminB, "mail-transport-smtp:config:auth-user", "b-user");
+    await stack.http.writeOk(
+      "secrets:write:set",
+      { key: SMTP_PASSWORD.name, value: "pw-b" },
+      adminB,
+    );
+
+    // Both factories should succeed — that's the per-tenant promise.
+    // The actual host-validation is on the SMTP transport build (object
+    // allocation), not a network call.
+    const a = (await stack.http.writeOk(TEST_HANDLER_QN, {}, adminA)) as Record<string, unknown>;
+    const b = (await stack.http.writeOk(TEST_HANDLER_QN, {}, adminB)) as Record<string, unknown>;
+    expect(a["hasSend"]).toBe(true);
+    expect(b["hasSend"]).toBe(true);
+  });
+});

package/src/mail-foundation/feature.ts

@@ -0,0 +1,160 @@
+// 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 } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import {
+  access,
+  createTenantConfig,
+  defineFeature,
+  type HandlerContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const FEATURE_NAME = "mail-foundation";
+
+// =============================================================================
+// Plugin-Interface — what a Provider-Plugin must implement
+// =============================================================================
+
+/**
+ * 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.
+ */
+export type MailTransportPlugin = {
+  readonly build: (ctx: HandlerContext, tenantId: string) => Promise<EmailTransport>;
+};
+
+// =============================================================================
+// Feature-definition
+// =============================================================================
+
+export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
+  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("mailTransport", {
+    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.
+    },
+  });
+
+  const configKeys = r.config({
+    keys: {
+      // 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.
+      provider: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+      }),
+    },
+  });
+
+  return {
+    /** Config-key-handle for the provider-selector. */
+    configKeys,
+  };
+});
+
+// =============================================================================
+// 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: HandlerContext,
+  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.configKeys.provider),
+    FEATURE_NAME,
+    "provider",
+  ) as string;
+  if (provider.length === 0) {
+    const usages = ctx.registry.getExtensionUsages("mailTransport");
+    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("mailTransport");
+  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.`,
+    );
+  }
+
+  // @cast-boundary engine-payload — extension-usage carries unknown options
+  const plugin = usage.options as MailTransportPlugin;
+  return plugin.build(ctx, tenantId);
+}

package/src/mail-foundation/index.ts

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

package/src/mail-transport-inmemory/__tests__/feature.test.ts

@@ -0,0 +1,37 @@
+// feature.ts contract tests for mail-transport-inmemory.
+
+import { describe, expect, test } from "vitest";
+import { clearInbox, getInbox, mailTransportInMemoryFeature } from "../feature";
+
+describe("mailTransportInMemoryFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(mailTransportInMemoryFeature.name).toBe("mail-transport-inmemory");
+  });
+
+  test("requires only mail-foundation (no config, no secrets — nothing to configure)", () => {
+    expect(mailTransportInMemoryFeature.requires).toContain("mail-foundation");
+    expect(mailTransportInMemoryFeature.requires).not.toContain("config");
+    expect(mailTransportInMemoryFeature.requires).not.toContain("secrets");
+  });
+});
+
+describe("mailTransportInMemoryFeature — plugin-registration", () => {
+  test("registers itself under entityName 'inmemory' for mail-foundation's extension", () => {
+    const usages = mailTransportInMemoryFeature.extensionUsages;
+    expect(
+      usages.some((u) => u.extensionName === "mailTransport" && u.entityName === "inmemory"),
+    ).toBe(true);
+  });
+});
+
+describe("getInbox / clearInbox — per-tenant buffer helpers", () => {
+  test("getInbox liefert empty-array für unbekannten Tenant", () => {
+    expect(getInbox("never-touched-tenant")).toEqual([]);
+  });
+
+  test("clearInbox auf nicht-existierenden Tenant ist no-op (kein throw)", () => {
+    // Defensive — wenn ein Demo-Test clearInbox vor dem ersten send aufruft,
+    // soll das nicht crashen.
+    expect(() => clearInbox("not-yet-existing")).not.toThrow();
+  });
+});

package/src/mail-transport-inmemory/feature.ts

@@ -0,0 +1,90 @@
+// 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 type { MailTransportPlugin } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import { defineFeature, type HandlerContext } 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) => {
+  // 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: HandlerContext, tenantId: string): Promise<EmailTransport> => {
+      // Returnt den per-tenant Buffer. Identitätsstabil zwischen calls
+      // damit die Demo-Inbox accumulated bleibt.
+      return getOrCreateTransportForTenant(tenantId);
+    },
+  };
+  r.useExtension("mailTransport", "inmemory", plugin);
+});

package/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";

package/src/mail-transport-smtp/__tests__/feature.test.ts

@@ -0,0 +1,61 @@
+// feature.ts contract tests for mail-transport-smtp — pins the
+// SMTP-specific config-keys + secret-handle that the plugin owns.
+// Plugin-registration shape is also pinned (drift-pin: name "smtp",
+// build-fn presence).
+
+import { describe, expect, test } from "vitest";
+import { mailTransportSmtpFeature, SMTP_PASSWORD } from "../feature";
+
+describe("mailTransportSmtpFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(mailTransportSmtpFeature.name).toBe("mail-transport-smtp");
+  });
+
+  test("requires config + secrets + mail-foundation as hard dependencies", () => {
+    expect(mailTransportSmtpFeature.requires).toContain("config");
+    expect(mailTransportSmtpFeature.requires).toContain("secrets");
+    expect(mailTransportSmtpFeature.requires).toContain("mail-foundation");
+  });
+});
+
+describe("mailTransportSmtpFeature.exports — typed handles", () => {
+  test("exports.configKeys covers the SMTP-config knobs", () => {
+    const keys = mailTransportSmtpFeature.exports.configKeys;
+    expect(keys.host).toBeDefined();
+    expect(keys.port).toBeDefined();
+    expect(keys.secure).toBeDefined();
+    expect(keys.from).toBeDefined();
+    expect(keys.authUser).toBeDefined();
+  });
+
+  test("exports.password is the SMTP_PASSWORD secret-handle (drift-pin)", () => {
+    expect(mailTransportSmtpFeature.exports.password).toBe(SMTP_PASSWORD);
+    expect(SMTP_PASSWORD.name).toBe("mail-transport-smtp:secret:smtp-password");
+  });
+});
+
+describe("SMTP_PASSWORD — generic redaction", () => {
+  const secretDef = mailTransportSmtpFeature.secretKeys["smtp.password"];
+
+  test("redact preserves first 3 + last 2 chars for verifiability on long keys", () => {
+    expect(secretDef?.redact).toBeDefined();
+    expect(secretDef?.redact?.("brevoXKEY01abc")).toMatch(/^bre\.\.\.bc$/);
+  });
+
+  test("redact masks short keys completely (no leak on under-8-char input)", () => {
+    expect(secretDef?.redact?.("shortpw")).toBe("•".repeat(7));
+  });
+});
+
+describe("mailTransportSmtpFeature — plugin-registration", () => {
+  test("registers itself under entityName 'smtp' for mail-foundation's extension", () => {
+    // r.useExtension("mailTransport", "smtp", ...) lands in the feature's
+    // feature.extensionUsages. Drift-pin: tenant sets `mail-foundation:
+    // config:provider = "smtp"` and the foundation-factory looks up by
+    // exactly this name.
+    const usages = mailTransportSmtpFeature.extensionUsages;
+    expect(usages.some((u) => u.extensionName === "mailTransport" && u.entityName === "smtp")).toBe(
+      true,
+    );
+  });
+});