@cosmicdrift/kumiko-bundled-features 0.319.0 → 0.321.0

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

@@ -3,13 +3,34 @@
 // Plugin-registration shape is also pinned (drift-pin: name "smtp",
 // build-fn presence).
 
-import { describe, expect, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import type { lookup } from "node:dns/promises";
 import type { ConfigAccessor } from "@cosmicdrift/kumiko-framework/engine";
+import { UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
+import { HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR } from "../../foundation-shared";
 import { isMailTransportPlugin, type MailTransportPlugin } from "../../mail-foundation";
 import { describeMailTransportContract } from "../../mail-foundation/__tests__/mail-transport-contract";
-import { mailTransportSmtpFeature, SMTP_PASSWORD } from "../feature";
+import { mailTransportSmtpFeature, SMTP_PASSWORD, setSmtpMailHostLookup } from "../feature";
+
+// The contract fixture's host never actually connects (nodemailer's pool
+// connects lazily on send, never on construction) — "localhost" only needs
+// to pass the host-egress guard, so it goes through the operator escape
+// hatch instead of a real DNS lookup for a placeholder hostname.
+const originalAllowedPrivateHostsEnv = process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+
+beforeAll(() => {
+  process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "localhost";
+});
+
+afterAll(() => {
+  if (originalAllowedPrivateHostsEnv === undefined) {
+    delete process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+  } else {
+    process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = originalAllowedPrivateHostsEnv;
+  }
+});
 
 function registeredPlugin(): MailTransportPlugin {
   const usage = mailTransportSmtpFeature.extensionUsages.find(
@@ -28,7 +49,7 @@ function fakeConfig(
 ): ConfigAccessor {
   const keys = mailTransportSmtpFeature.exports.configKeys;
   const values = new Map<string, string | number | boolean>([
-    [keys.host.name, overrides.host ?? "smtp.contract-test.invalid"],
+    [keys.host.name, overrides.host ?? "localhost"],
     [keys.port.name, overrides.port ?? 587],
     [keys.secure.name, overrides.secure ?? false],
     [keys.from.name, overrides.from ?? "noreply@contract-test.invalid"],
@@ -71,6 +92,105 @@ describe("mailTransportSmtpFeature — build error path", () => {
   });
 });
 
+describe("mailTransportSmtpFeature — mail-host guard", () => {
+  afterEach(() => {
+    setSmtpMailHostLookup(undefined);
+    delete process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+  });
+
+  test("a private IP-literal host is rejected as unconfigured, naming 'host'", async () => {
+    const ctx = { config: fakeConfig({ host: "10.0.0.5" }), secrets: fakeSecrets(), _userId: "x" };
+    try {
+      await registeredPlugin().build(ctx, "contract-test-tenant");
+      expect.unreachable("expected build to throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(UnconfiguredError);
+      expect((e as UnconfiguredError).details).toMatchObject({
+        feature: "mail-transport-smtp",
+        key: "host",
+      });
+      expect((e as Error).message).not.toContain("10.0.0.5");
+    }
+  });
+
+  test("a blocked host and a DNS resolution failure produce the exact same tenant-visible message", async () => {
+    const blockedCtx = {
+      config: fakeConfig({ host: "10.0.0.5" }),
+      secrets: fakeSecrets(),
+      _userId: "x",
+    };
+    let blockedMessage: string | undefined;
+    try {
+      await registeredPlugin().build(blockedCtx, "contract-test-tenant");
+      expect.unreachable("expected build to throw");
+    } catch (e) {
+      blockedMessage = (e as Error).message;
+    }
+
+    const failingLookup = (async () => {
+      throw new Error("ENOTFOUND");
+    }) as unknown as typeof lookup;
+    setSmtpMailHostLookup(failingLookup);
+    const unresolvableCtx = {
+      config: fakeConfig({ host: "nowhere.test" }),
+      secrets: fakeSecrets(),
+      _userId: "x",
+    };
+    let unresolvableMessage: string | undefined;
+    try {
+      await registeredPlugin().build(unresolvableCtx, "contract-test-tenant");
+      expect.unreachable("expected build to throw");
+    } catch (e) {
+      unresolvableMessage = (e as Error).message;
+    }
+
+    expect(blockedMessage).toBe(unresolvableMessage);
+    expect(blockedMessage).not.toContain("10.0.0.5");
+    expect(unresolvableMessage).not.toContain("nowhere.test");
+  });
+
+  test("a hostname resolving to a private address is rejected as unconfigured", async () => {
+    const fakeLookup = (async () => [
+      { address: "127.0.0.1", family: 4 },
+    ]) as unknown as typeof lookup;
+    setSmtpMailHostLookup(fakeLookup);
+    const ctx = {
+      config: fakeConfig({ host: "internal-relay.test" }),
+      secrets: fakeSecrets(),
+      _userId: "x",
+    };
+    await expect(registeredPlugin().build(ctx, "contract-test-tenant")).rejects.toBeInstanceOf(
+      UnconfiguredError,
+    );
+  });
+
+  test("a DNS resolution failure is not reclassified as unconfigured (transient, not a tenant config problem)", async () => {
+    const failingLookup = (async () => {
+      throw new Error("ENOTFOUND");
+    }) as unknown as typeof lookup;
+    setSmtpMailHostLookup(failingLookup);
+    const ctx = {
+      config: fakeConfig({ host: "nowhere.test" }),
+      secrets: fakeSecrets(),
+      _userId: "x",
+    };
+    await expect(registeredPlugin().build(ctx, "contract-test-tenant")).rejects.toBeInstanceOf(
+      HostResolutionError,
+    );
+  });
+
+  test("an operator-allowlisted private host builds successfully, bypassing resolution", async () => {
+    process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "relay.internal";
+    const ctx = {
+      config: fakeConfig({ host: "relay.internal" }),
+      secrets: fakeSecrets(),
+      _userId: "x",
+    };
+    const transport = await registeredPlugin().build(ctx, "contract-test-tenant");
+    expect(typeof transport.send).toBe("function");
+  });
+});
+
 describe("mailTransportSmtpFeature — shape", () => {
   test("has the expected name", () => {
     expect(mailTransportSmtpFeature.name).toBe("mail-transport-smtp");

package/src/mail-transport-smtp/changes.json

@@ -1 +1,14 @@
-[]
+[
+  {
+    "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."
+  }
+]

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

@@ -25,14 +25,21 @@
 //   - `config` — für die Tenant-Config-Keys
 //   - `secrets` — für das verschlüsselte SMTP-Password
 
+import type { lookup } from "node:dns/promises";
 import {
   createSmtpTransport,
   type EmailTransport,
 } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import {
+  BlockedHostError,
+  HostResolutionError,
+  MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  type MailConnectTarget,
+  readAllowedPrivateMailHostsFromEnv,
   requireDefined,
   requireNonEmpty,
   requireSecretSet,
+  resolveMailConnectTarget,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   MAIL_TRANSPORT_EXTENSION,
@@ -41,9 +48,41 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import * as z from "zod";
 
 const FEATURE_NAME = "mail-transport-smtp";
 
+const log = createFallbackLogger(FEATURE_NAME);
+
+// Operator escape hatch for an internal relay or a dev/test SMTP server
+// (mailpit, MailHog): KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, an operator env
+// var never a tenant-config value, so a tenant can never grant themselves
+// the private-host bypass. Declared here (not duplicated in
+// inbound-provider-imap's envSchema) since both features read the same
+// var and composeEnvSchema rejects two features declaring the same key —
+// see foundation-shared/mail-host-policy.ts for the shared reader + the
+// guard this feeds.
+export const mailTransportSmtpEnvSchema = z.object({
+  [MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
+    .string()
+    .optional()
+    .describe(
+      "Comma-separated operator allowlist of private/internal hosts (e.g. a local mailpit/greenmail dev server) that bypass the public-address check for SMTP and IMAP host config. Shared with inbound-provider-imap — never a tenant-config value.",
+    ),
+});
+
+// Test-only DNS seam — production never calls this, resolveMailConnectTarget
+// defaults to the real resolver. Lets tests pin deterministic, network-free
+// host resolutions instead of depending on real DNS for a placeholder host.
+// Reset it in afterEach/afterAll — this is module-global state.
+let mailHostLookup: typeof lookup | undefined;
+
+export function setSmtpMailHostLookup(fn: typeof lookup | undefined): void {
+  mailHostLookup = fn;
+}
+
 // =============================================================================
 // Feature-definition
 // =============================================================================
@@ -60,6 +99,7 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
   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", {
@@ -134,6 +174,18 @@ export const SMTP_PASSWORD = mailTransportSmtpFeature.exports.password;
 // Internal: build the EmailTransport from tenant config + secret
 // =============================================================================
 
+// Tenant-visible for both a blocked host and a DNS failure — must not
+// reveal which one occurred, or the host itself. Built once so a
+// HostResolutionError raised for the other branch can reuse the exact same
+// `.message` string byte-for-byte instead of just a similar hint.
+function mailHostUnreachableError(): UnconfiguredError {
+  return new UnconfiguredError({
+    feature: FEATURE_NAME,
+    key: "host",
+    hint: "host is not reachable or not allowed",
+  });
+}
+
 async function buildSmtpTransport(
   ctx: MailTransportContext,
   tenantId: string,
@@ -177,12 +229,35 @@ async function buildSmtpTransport(
 
   const password = await readPassword(ctx, tenantId);
 
+  let target: MailConnectTarget;
+  try {
+    target = await resolveMailConnectTarget(host, {
+      allowedPrivateMailHosts: readAllowedPrivateMailHostsFromEnv(),
+      lookupFn: mailHostLookup,
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    // Both branches throw the exact same tenant-visible message text — the
+    // blocked-vs-unresolvable distinction and the host itself stay
+    // server-log-only. Class stays distinct: UnconfiguredError (422, a
+    // config problem, no retry) for a blocked host vs HostResolutionError
+    // (transient, retried) for a DNS failure — see mailHostUnreachableError().
+    const unreachable = mailHostUnreachableError();
+    if (err instanceof BlockedHostError) {
+      log.warn("rejected blocked host", { host, reason });
+      throw unreachable;
+    }
+    log.warn("host resolution failed", { host, reason });
+    throw new HostResolutionError(unreachable.message);
+  }
+
   return createSmtpTransport({
-    host,
+    host: target.host,
     port,
     secure,
     from,
     auth: { user: authUser, pass: password },
+    ...(target.servername && { servername: target.servername }),
   });
 }
 

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

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

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -9,6 +9,7 @@ import {
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createInMemoryFileProvider } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
   type TestStack,
@@ -124,6 +125,10 @@ beforeAll(async () => {
       // ≤2 requests per (distinct) token, so this ceiling never trips them.
       patRateLimiter: createInMemoryLoginRateLimiter(3, 60_000),
     },
+    // Only exercised by the route-guard describe block below (POST/GET
+    // /api/files) — proves the guard blocks a PAT there even though the
+    // route is actually mounted and reachable for a JWT/cookie caller.
+    files: { storageProvider: createInMemoryFileProvider() },
   });
   h = makeSessionHelpers(stack, TENANT);
 
@@ -550,3 +555,57 @@ describe("PAT list projection (fw#2548 Teil B)", () => {
     expect(expired.rows[0]?.status).toBe("expired");
   });
 });
+
+describe("PAT route guard: dispatcher routes only (#security)", () => {
+  test("PAT → GET /api/sse → 403, even with a granted scope", async () => {
+    const actor = await actorFor("route-guard-sse@example.com");
+    const token = await mintToken(actor);
+    const res = await stack.http.raw("GET", "/api/sse", undefined, {
+      Authorization: `Bearer ${token}`,
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("access_denied");
+  });
+
+  test("PAT → POST /api/files → 403 (route is mounted — a JWT gets past the guard to the 400 validation)", async () => {
+    const actor = await actorFor("route-guard-files-post@example.com");
+    const token = await mintToken(actor);
+    const patRes = await h.authedPost("/api/files", token);
+    expect(patRes.status).toBe(403);
+
+    const jwt = await loginToken("route-guard-files-post@example.com");
+    const jwtRes = await h.authedPost("/api/files", jwt);
+    expect(jwtRes.status).toBe(400);
+  });
+
+  test("PAT → GET /api/files/:id → 403 (a JWT gets past the guard to the 404 not_found)", async () => {
+    const actor = await actorFor("route-guard-files-get@example.com");
+    const token = await mintToken(actor);
+    const patRes = await stack.http.raw("GET", "/api/files/does-not-exist", undefined, {
+      Authorization: `Bearer ${token}`,
+    });
+    expect(patRes.status).toBe(403);
+
+    const jwt = await loginToken("route-guard-files-get@example.com");
+    const jwtRes = await stack.http.raw("GET", "/api/files/does-not-exist", undefined, {
+      Authorization: `Bearer ${jwt}`,
+    });
+    expect(jwtRes.status).toBe(404);
+  });
+
+  test("PAT → GET /api/auth/tenants → 403 (a JWT reaches the real 200)", async () => {
+    const actor = await actorFor("route-guard-tenants@example.com");
+    const token = await mintToken(actor);
+    const patRes = await stack.http.raw("GET", "/api/auth/tenants", undefined, {
+      Authorization: `Bearer ${token}`,
+    });
+    expect(patRes.status).toBe(403);
+
+    const jwt = await loginToken("route-guard-tenants@example.com");
+    const jwtRes = await stack.http.raw("GET", "/api/auth/tenants", undefined, {
+      Authorization: `Bearer ${jwt}`,
+    });
+    expect(jwtRes.status).toBe(200);
+  });
+});

package/src/sessions/__tests__/sessions.integration.test.ts

@@ -100,6 +100,11 @@ beforeEach(async () => {
     userSessionTable,
     eventsTable,
   ]);
+  // login.write.ts is `per: "ip+handler"` rate-limited (20/60s). h.login()
+  // goes through stack.http.raw with no socket address, so every test in
+  // this file shares one "unknown" IP bucket — flush it per test so the
+  // file's cumulative login() calls can't push a later test over the cap.
+  await stack.redis.flushNamespace();
 });
 
 describe("sessions feature — login → check → revoke → rejected", () => {

package/src/shared/password-hashing.test.ts

@@ -1,15 +1,15 @@
 import { describe, expect, test } from "bun:test";
 import { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
 
-const medianMs = async (fn: () => Promise<unknown>, runs = 5): Promise<number> => {
-  const samples: number[] = [];
-  for (let i = 0; i < runs; i++) {
-    const start = performance.now();
-    await fn();
-    samples.push(performance.now() - start);
-  }
-  samples.sort((a, b) => a - b);
-  return samples[Math.floor(samples.length / 2)] ?? 0;
+const timeMs = async (fn: () => Promise<unknown>): Promise<number> => {
+  const start = performance.now();
+  await fn();
+  return performance.now() - start;
+};
+
+const median = (samples: readonly number[]): number => {
+  const sorted = [...samples].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? 0;
 };
 
 // #774: the login no-user path must cost the same argon2 latency as a real
@@ -24,12 +24,20 @@ describe("verifyDummyPassword (anti-enumeration timing)", () => {
     // warm the lazily-cached dummy hash so we time the verify, not the one-off hash
     await verifyDummyPassword("warmup");
 
-    const realMs = await medianMs(() => verifyPassword(realHash, "wrong-password"));
-    const dummyMs = await medianMs(() => verifyDummyPassword("wrong-password"));
+    // Interleaved so both paths see the same machine load: two back-to-back
+    // median blocks drift apart on a busy CI runner and skew the ratio.
+    const realSamples: number[] = [];
+    const dummySamples: number[] = [];
+    for (let i = 0; i < 7; i++) {
+      realSamples.push(await timeMs(() => verifyPassword(realHash, "wrong-password")));
+      dummySamples.push(await timeMs(() => verifyDummyPassword("wrong-password")));
+    }
+    const realMs = median(realSamples);
+    const dummyMs = median(dummySamples);
 
     // A skipped miss-path (the bug) is sub-millisecond; a real argon2 verify
-    // is ~20ms. A half-of-real floor is a wide, non-flaky bound that still
-    // fails hard if the dummy verify is ever removed.
+    // is ~20ms. A half-of-real floor still fails hard if the dummy verify is
+    // ever removed.
     expect(dummyMs).toBeGreaterThan(realMs * 0.5);
   });
 });

package/src/step-dispatcher/__tests__/feature.boot.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { createSecretsFeature } from "../../secrets";
 import { createStepDispatcherFeature } from "../feature";
 
 describe("step-dispatcher (fw#2068)", () => {
@@ -7,7 +8,13 @@ describe("step-dispatcher (fw#2068)", () => {
     expect(createStepDispatcherFeature().systemScope).toBeFalsy();
   });
 
-  test("boot-validates standalone", () => {
-    expect(() => validateBoot([createStepDispatcherFeature()])).not.toThrow();
+  test("boot-validates alongside the secrets feature it requires", () => {
+    expect(() =>
+      validateBoot([createStepDispatcherFeature(), createSecretsFeature()]),
+    ).not.toThrow();
+  });
+
+  test("boot-validation rejects step-dispatcher without secrets mounted", () => {
+    expect(() => validateBoot([createStepDispatcherFeature()])).toThrow(/secrets/);
   });
 });