@cosmicdrift/kumiko-bundled-features 0.1.0

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

@@ -0,0 +1,182 @@
+// 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,
+  type EmailTransport,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import {
+  requireDefined,
+  requireNonEmpty,
+} from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import type { MailTransportPlugin } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  access,
+  createTenantConfig,
+  defineFeature,
+  type HandlerContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const FEATURE_NAME = "mail-transport-smtp";
+
+// =============================================================================
+// Feature-definition
+// =============================================================================
+
+export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.requires("config");
+  r.requires("secrets");
+  r.requires("mail-foundation");
+
+  // Provider-secret. Sensitive: redact-helper for admin-UI display.
+  const password = r.secret("smtp.password", {
+    label: { de: "SMTP-Passwort", en: "SMTP password" },
+    hint: {
+      de: "Login-Passwort am SMTP-Server. Bei Brevo/Postmark/SES heißt es 'API key' bzw. 'SMTP credentials'.",
+      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",
+  });
+
+  const configKeys = r.config({
+    keys: {
+      host: createTenantConfig("text", {
+        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", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      authUser: createTenantConfig("text", {
+        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: HandlerContext, tenantId: string) => buildSmtpTransport(ctx, tenantId),
+  };
+  r.useExtension("mailTransport", "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
+// =============================================================================
+
+async function buildSmtpTransport(ctx: HandlerContext, 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;
+  const secure = requireDefined(
+    await ctxConfig(mailTransportSmtpFeature.exports.configKeys.secure),
+    FEATURE_NAME,
+    "secure",
+  ) as boolean;
+  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);
+
+  return createSmtpTransport({
+    host,
+    port,
+    secure,
+    from,
+    auth: { user: authUser, pass: password },
+  });
+}
+
+async function readPassword(ctx: HandlerContext, tenantId: string): Promise<string> {
+  const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+  const branded = await secrets.get(tenantId, SMTP_PASSWORD);
+  if (!branded) {
+    throw new Error(
+      `${FEATURE_NAME}: ${SMTP_PASSWORD.name} not set for tenant ${tenantId} — Tenant-Admin must set it via /api/write/secrets:write:set`,
+    );
+  }
+  return branded.reveal();
+}

package/src/mail-transport-smtp/index.ts

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

package/src/rate-limiting/__tests__/rate-limiting.integration.ts

@@ -0,0 +1,84 @@
+// Integration test for the rate-limiting feature: proves the status
+// query handler is registered, accessible to admins, and reports the
+// real bucket state from the framework's RateLimitResolver.
+//
+// L3 dispatcher hook + resolver wiring are tested in framework-side
+// suites; here we only verify the feature's own surface area.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createRateLimitingFeature } from "../feature";
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+// Helper handler with a tight rate limit so we can drain the bucket
+// fast enough for the status query to observe a non-trivial state.
+const probeFeature = defineFeature("rl-probe", (r) => {
+  r.queryHandler("ping", z.object({}), async () => ({ ok: true }), {
+    access: { roles: ["Admin"] },
+    rateLimit: { per: "user", limit: 5, windowSeconds: 60 },
+  });
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createRateLimitingFeature(), probeFeature],
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.redis.flushNamespace();
+});
+
+describe("rate-limiting feature — status query", () => {
+  test("reports a fresh bucket as fully available before any traffic", async () => {
+    const status = await stack.http.queryOk<{
+      bucket: string;
+      limit: number;
+      remaining: number;
+      windowSeconds: number;
+    }>(
+      "rate-limiting:query:status",
+      { bucket: `user:${admin.id}`, limit: 5, windowSeconds: 60 },
+      admin,
+    );
+    expect(status.bucket).toBe(`user:${admin.id}`);
+    expect(status.limit).toBe(5);
+    expect(status.remaining).toBe(5);
+    expect(status.windowSeconds).toBe(60);
+  });
+
+  test("reports the deducted remaining tokens after real handler traffic", async () => {
+    // Drain the bucket via the probe handler — same per/limit/window
+    // as the status query peeks below, so the buckets line up.
+    for (let i = 0; i < 3; i++) {
+      await stack.http.queryOk("rl-probe:query:ping", {}, admin);
+    }
+
+    const status = await stack.http.queryOk<{ remaining: number }>(
+      "rate-limiting:query:status",
+      { bucket: `user:${admin.id}`, limit: 5, windowSeconds: 60 },
+      admin,
+    );
+    // 3 deductions of cost-1 → 2 tokens left.
+    expect(status.remaining).toBe(2);
+  });
+
+  test("status access requires Admin/SystemAdmin", async () => {
+    const guest = TestUsers.user;
+    const res = await stack.http.query(
+      "rate-limiting:query:status",
+      { bucket: "user:0", limit: 1, windowSeconds: 60 },
+      guest,
+    );
+    // Access-denied surfaces as 403 in the dispatcher's outer wrapper.
+    expect(res.status).toBe(403);
+  });
+});

package/src/rate-limiting/constants.ts

@@ -0,0 +1,9 @@
+export const RATE_LIMITING_FEATURE = "rateLimiting" as const;
+
+export const RateLimitQueries = {
+  status: "rate-limiting:query:status",
+} as const;
+
+export const RateLimitErrors = {
+  resolverUnavailable: "rate_limit_resolver_unavailable",
+} as const;

package/src/rate-limiting/feature.ts

@@ -0,0 +1,16 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { rateLimitStatus } from "./handlers/status.query";
+
+// Opt-in feature. Loading it does NOT install rate-limit middleware —
+// the framework auto-wires the L3 dispatcher hook and the resolver
+// when (a) at least one handler declared a rateLimit option, OR (b) the
+// caller passed `context.rateLimit` explicitly (e.g. for L1/L2 setup).
+//
+// Loading this feature only adds the ops-side status query. Apps that
+// only use L3 (handler-opt-in) and don't need ops introspection can
+// skip this feature entirely — the resolver still runs.
+export function createRateLimitingFeature() {
+  return defineFeature("rateLimiting", (r) => {
+    r.queryHandler(rateLimitStatus);
+  });
+}

package/src/rate-limiting/handlers/status.query.ts

@@ -0,0 +1,52 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { RateLimitErrors } from "../constants";
+
+// Ops-side bucket inspection. Pass the bucket key (e.g. "user:42",
+// "user+handler:42:orders:write:order:create") plus the limit/window the bucket
+// was configured with, and get back the current state. Backed by
+// resolver.peek() — purely read-only, no token deduction and no
+// refill-timestamp update, so dashboards can poll without nudging the
+// bucket state ahead of the next real request.
+//
+// Use cases: ops-CLI ("kumiko rl status user:42"), support agent debugging
+// "why is this user blocked", dashboard tile.
+//
+// Bucket key format is owned by the framework (see rate-limit/bucket.ts);
+// callers pass the constructed key directly. We don't synthesize from
+// (per, user, handler) here — peeking is a low-level op, the lookup
+// surface stays small.
+export const rateLimitStatus = defineQueryHandler({
+  // Short name — the registry qualifies this to `rate-limiting:query:status`
+  // when the feature is registered. Passing the qualified form here would
+  // double-prefix it and the handler wouldn't be reachable.
+  name: "status",
+  schema: z.object({
+    bucket: z.string().min(1),
+    limit: z.number().int().positive(),
+    windowSeconds: z.number().int().positive(),
+  }),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    if (!ctx.rateLimit) {
+      throw new UnprocessableError(RateLimitErrors.resolverUnavailable, {
+        i18nKey: "rateLimiting.errors.resolverUnavailable",
+      });
+    }
+    const decision = await ctx.rateLimit.peek(query.payload.bucket, {
+      limit: query.payload.limit,
+      windowSeconds: query.payload.windowSeconds,
+    });
+    return {
+      bucket: query.payload.bucket,
+      limit: decision.limit,
+      remaining: decision.remaining,
+      windowSeconds: decision.windowSeconds,
+      // resetAt is meaningful only if the bucket is currently exhausted;
+      // we still return it so dashboards can show "next refill" uniformly.
+      resetAt: decision.resetAt.toString(),
+      retryAfterSeconds: decision.retryAfterSeconds,
+    };
+  },
+});

package/src/rate-limiting/index.ts

@@ -0,0 +1,2 @@
+export { RATE_LIMITING_FEATURE, RateLimitErrors, RateLimitQueries } from "./constants";
+export { createRateLimitingFeature } from "./feature";

package/src/renderer-simple/__tests__/simple-renderer.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "vitest";
+import { simpleRenderer } from "../simple-renderer";
+
+describe("simple renderer", () => {
+  test("renders header", async () => {
+    const html = await simpleRenderer.render({
+      template: "test",
+      variables: { header: "Willkommen" },
+    });
+    expect(html).toContain("<h1");
+    expect(html).toContain("Willkommen");
+    expect(html).toContain("<!DOCTYPE html>");
+  });
+
+  test("renders text section", async () => {
+    const html = await simpleRenderer.render({
+      template: "test",
+      variables: {
+        sections: [{ text: "Dies ist ein Absatz." }],
+      },
+    });
+    expect(html).toContain("<p");
+    expect(html).toContain("Dies ist ein Absatz.");
+  });
+
+  test("renders button section with link", async () => {
+    const html = await simpleRenderer.render({
+      template: "test",
+      variables: {
+        sections: [{ button: { label: "Klick mich", url: "https://example.com/action" } }],
+      },
+    });
+    expect(html).toContain('href="https://example.com/action"');
+    expect(html).toContain("Klick mich");
+    expect(html).toContain("<a ");
+  });
+
+  test("renders footer", async () => {
+    const html = await simpleRenderer.render({
+      template: "test",
+      variables: { footer: "Kumiko Framework" },
+    });
+    expect(html).toContain("Kumiko Framework");
+    expect(html).toContain("border-top");
+  });
+
+  test("renders full email with all parts", async () => {
+    const html = await simpleRenderer.render({
+      template: "order-assigned",
+      variables: {
+        header: "Neuer Auftrag",
+        sections: [
+          { text: "Auftrag #42 wurde dir zugewiesen." },
+          { button: { label: "Auftrag oeffnen", url: "/orders/42" } },
+        ],
+        footer: "Automatische Benachrichtigung",
+      },
+    });
+
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).toContain("Neuer Auftrag");
+    expect(html).toContain("Auftrag #42 wurde dir zugewiesen.");
+    expect(html).toContain('href="/orders/42"');
+    expect(html).toContain("Auftrag oeffnen");
+    expect(html).toContain("Automatische Benachrichtigung");
+    expect(html).toContain("</html>");
+  });
+
+  test("escapes HTML in all fields", async () => {
+    const html = await simpleRenderer.render({
+      template: "test",
+      variables: {
+        header: '<script>alert("xss")</script>',
+        sections: [
+          { text: "Text with <b>tags</b>" },
+          { button: { label: "Click <here>", url: 'https://evil.com/"><script>' } },
+        ],
+        footer: "Footer & more",
+      },
+    });
+
+    expect(html).not.toContain("<script>");
+    expect(html).not.toContain("<b>");
+    expect(html).toContain("&lt;script&gt;");
+    expect(html).toContain("&lt;b&gt;");
+    expect(html).toContain("Footer &amp; more");
+  });
+
+  test("renders empty template without errors", async () => {
+    const html = await simpleRenderer.render({
+      template: "empty",
+      variables: {},
+    });
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).toContain("</html>");
+  });
+});

package/src/renderer-simple/feature.ts

@@ -0,0 +1,12 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { simpleRenderer } from "./simple-renderer";
+
+export function createRendererSimpleFeature(): FeatureDefinition {
+  return defineFeature("rendererSimple", (r) => {
+    r.requires("delivery");
+
+    r.useExtension("notificationRenderer", "simple", {
+      render: simpleRenderer.render,
+    });
+  });
+}

package/src/renderer-simple/index.ts

@@ -0,0 +1,2 @@
+export { createRendererSimpleFeature } from "./feature";
+export { simpleRenderer } from "./simple-renderer";

package/src/renderer-simple/simple-renderer.ts

@@ -0,0 +1,72 @@
+import type { NotificationRenderer } from "../delivery";
+
+type Section =
+  | { readonly text: string }
+  | { readonly button: { readonly label: string; readonly url: string } };
+
+type EmailTemplateData = {
+  // Preferred: structured email data
+  readonly header?: string;
+  readonly sections?: readonly Section[];
+  readonly footer?: string;
+  // Fallback: plain title + body (used when no structured template is defined)
+  readonly title?: string;
+  readonly body?: string;
+};
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function renderSection(section: Section): string {
+  if ("text" in section) {
+    return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
+  }
+  if ("button" in section) {
+    return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:#2563eb;color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
+  }
+  return "";
+}
+
+// Simple Renderer: turns structured email template data into HTML with inline CSS.
+// No external dependencies, no template engine — just string concatenation.
+export const simpleRenderer: NotificationRenderer = {
+  name: "simple",
+
+  async render(input) {
+    const data = input.variables as EmailTemplateData;
+
+    // Fallback: if no structured fields, use title + body as header + single text section
+    const header = data.header ?? data.title;
+    const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
+
+    const parts: string[] = [];
+    parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
+    parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
+
+    if (header) {
+      parts.push(
+        `<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`,
+      );
+    }
+
+    if (sections) {
+      for (const section of sections) {
+        parts.push(renderSection(section));
+      }
+    }
+
+    if (data.footer) {
+      parts.push(
+        `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`,
+      );
+    }
+
+    parts.push("</div></body></html>");
+    return parts.join("");
+  },
+};