@cosmicdrift/kumiko-bundled-features 0.319.0 → 0.320.0

package/src/inbound-provider-imap/changes.json

@@ -1 +1,14 @@
-[]
+[
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "The tenant-configured IMAP host must resolve to a public address",
+    "migration": "An operator relying on an internal IMAP server or a local dev/test server\n(greenmail on localhost or a private IP) now gets an InboundAuthError\n(account marked auth_error) unless that host is explicitly allowed. Set\nthe same operator env var mail-transport-smtp reads (comma-separated, no\nboot-time code call needed) before starting the process:\n  KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS=greenmail.internal\nThis is an operator env var, not a tenant config value — a tenant cannot\nadd their own host to this list. A DNS resolution failure for a\ngenuinely unreachable host now surfaces as InboundTransientError (job\nretry) instead of reaching imapflow at all."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "IMAP connect failures no longer distinguish a blocked host from a DNS failure in the thrown message",
+    "detail": "`createImapClient` throws the same generic message\n(\"IMAP host is not reachable or not allowed\") for both a blocked host\n(`InboundAuthError`) and a DNS resolution failure (`InboundTransientError`).\nThe configured host and the underlying error are now logged via the\nfeature's own logger instead of being embedded in the thrown message.\nError class (and therefore retry behavior) is unchanged."
+  }
+]

package/src/inbound-provider-imap/feature.ts

@@ -44,6 +44,7 @@ import {
   coerceDate,
   createImapClient,
   IMAP_MAILBOX,
+  imapMailHostGuard,
   mapImapError,
   parseImapCursor,
   toRawInboundMessage,
@@ -52,6 +53,8 @@ import {
 const FEATURE_NAME = "inbound-provider-imap";
 export const IMAP_PROVIDER_KEY = "imap";
 
+export { setImapMailHostLookup } from "./imap-client";
+
 // =============================================================================
 // Credential-Read — per-Account-Slot, Worker-tauglich (slim ctx).
 // =============================================================================
@@ -88,7 +91,7 @@ async function fetchMessages(
   opts: { readonly backfillWindowDays: number; readonly maxMessages: number },
 ): Promise<InboundFetchResult> {
   const doc = await readCredentialDocument(ctx, account);
-  const client = createImapClient(doc);
+  const client = await createImapClient(doc, imapMailHostGuard());
   let lock: Awaited<ReturnType<typeof client.getMailboxLock>> | undefined;
   try {
     await client.connect();
@@ -164,7 +167,7 @@ async function watchMailbox(
   },
 ): Promise<() => Promise<void>> {
   const doc = await readCredentialDocument(ctx, account);
-  const client: ImapFlow = createImapClient(doc);
+  const client: ImapFlow = await createImapClient(doc, imapMailHostGuard());
   let stopped = false;
 
   try {
@@ -252,7 +255,7 @@ async function watchMailbox(
 export const imapInboundMailPlugin: InboundMailProviderPlugin = {
   verify: async (ctx, account) => {
     const doc = await readCredentialDocument(ctx, account);
-    const client = createImapClient(doc);
+    const client = await createImapClient(doc, imapMailHostGuard());
     try {
       await client.connect();
     } catch (err) {

package/src/inbound-provider-imap/imap-client.ts

@@ -2,6 +2,12 @@
 // Referenz-Impl: /Users/marc/code/doc-o-mat (HEINZ) — aber inkrementeller
 // UIDVALIDITY:lastUid-Cursor statt '1:*'-Vollscan.
 
+import {
+  BlockedHostError,
+  type MailHostGuardOptions,
+  readAllowedPrivateMailHostsFromEnv,
+  resolveMailConnectTarget,
+} from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   InboundAuthError,
   InboundCursorInvalidError,
@@ -9,6 +15,7 @@ import {
   type RawInboundMessage,
   type SyncCursorPayload,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { legacyDateToInstant } from "@cosmicdrift/kumiko-framework/time";
 import { ImapFlow } from "imapflow";
 import { type AddressObject, type ParsedMail, simpleParser } from "mailparser";
@@ -18,15 +25,66 @@ import type { ImapCredentialDocument } from "./credential-document";
 export const IMAP_MAILBOX = "INBOX";
 const SNIPPET_MAX = 300;
 
+const log = createFallbackLogger("inbound-provider-imap");
+
+// Tenant-visible for both branches below — must not reveal whether the host
+// was blocked (private/reserved range) or merely failed to resolve, and
+// must never include the host or the underlying error text. Server-side
+// detail goes to `log` only.
+const IMAP_HOST_UNREACHABLE_MESSAGE = "IMAP host is not reachable or not allowed";
+
 // =============================================================================
 // Client-Factory + Fehler-Mapping
 // =============================================================================
 
-export function createImapClient(doc: ImapCredentialDocument): ImapFlow {
+// Operator escape hatch for an internal relay or a dev/test IMAP server
+// (greenmail): KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, the same operator env
+// var mail-transport-smtp declares (see its envSchema — composeEnvSchema
+// rejects two features declaring the same key, so this feature reads it
+// without redeclaring it), never a tenant-config value, so a tenant can
+// never grant themselves the private-host bypass.
+//
+// mailHostLookup is a test-only DNS seam — production leaves it undefined,
+// so resolveMailConnectTarget uses the real resolver. Module-global state:
+// reset it in afterEach/afterAll.
+let mailHostLookup: MailHostGuardOptions["lookupFn"];
+
+export function setImapMailHostLookup(fn: MailHostGuardOptions["lookupFn"]): void {
+  mailHostLookup = fn;
+}
+
+export function imapMailHostGuard(): MailHostGuardOptions {
+  return {
+    allowedPrivateMailHosts: readAllowedPrivateMailHostsFromEnv(),
+    lookupFn: mailHostLookup,
+  };
+}
+
+// Resolves+pins doc.host before ever touching imapflow — a blocked host
+// (private/reserved range) must never reach a connect attempt. Rejection is
+// InboundAuthError (no retry, a config problem) vs InboundTransientError for
+// a DNS failure (matches mapImapError's ENOTFOUND handling below).
+export async function createImapClient(
+  doc: ImapCredentialDocument,
+  hostGuard: MailHostGuardOptions = {},
+): Promise<ImapFlow> {
+  let target: Awaited<ReturnType<typeof resolveMailConnectTarget>>;
+  try {
+    target = await resolveMailConnectTarget(doc.host, hostGuard);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    if (err instanceof BlockedHostError) {
+      log.warn("rejected blocked host", { host: doc.host, reason });
+      throw new InboundAuthError(IMAP_HOST_UNREACHABLE_MESSAGE);
+    }
+    log.warn("host resolution failed", { host: doc.host, reason });
+    throw new InboundTransientError(IMAP_HOST_UNREACHABLE_MESSAGE);
+  }
   return new ImapFlow({
-    host: doc.host,
+    host: target.host,
     port: doc.port,
     secure: doc.secure,
+    ...(target.servername && { servername: target.servername }),
     auth: doc.password
       ? { user: doc.user, pass: doc.password }
       : { user: doc.user, accessToken: doc.accessToken as string },

package/src/inbound-provider-imap/index.ts

@@ -6,7 +6,7 @@ export {
   type ParseCredentialResult,
   parseImapCredentialDocument,
 } from "./credential-document";
-export { IMAP_PROVIDER_KEY, inboundProviderImapFeature } from "./feature";
+export { IMAP_PROVIDER_KEY, inboundProviderImapFeature, setImapMailHostLookup } from "./feature";
 export {
   assertUidValidity,
   buildProviderMessageId,

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

@@ -599,6 +599,86 @@ describe("ledger integration — createSchedule with a caller-chosen id (idempot
   });
 });
 
+describe("ledger integration — account code uniqueness", () => {
+  test("a second account with the same code in the same tenant is rejected", async () => {
+    await stack.http.writeOk(
+      LedgerHandlers.createAccount,
+      { name: "Bank", type: "asset", code: "1000" },
+      admin,
+    );
+
+    const err = await stack.http.writeErr(
+      LedgerHandlers.createAccount,
+      { name: "Bank 2", type: "asset", code: "1000" },
+      admin,
+    );
+    expect(err.code).toBe("unique_violation");
+
+    // The rejected create must not leave an event behind that a later rebuild
+    // would replay into a duplicate.
+    const accounts = await stack.http.queryOk<{ rows: { code?: string }[] }>(
+      LedgerQueries.accountList,
+      {},
+      admin,
+    );
+    expect(accounts.rows.filter((row) => row.code === "1000")).toHaveLength(1);
+    const [eventCount] = await asRawClient(stack.db).unsafe<{ count: number }>(
+      "SELECT count(*)::int AS count FROM kumiko_events WHERE tenant_id = $1",
+      [admin.tenantId],
+    );
+    expect(eventCount?.count).toBe(1);
+  });
+
+  test("two accounts without a code in the same tenant both succeed", async () => {
+    await stack.http.writeOk(LedgerHandlers.createAccount, { name: "Bank", type: "asset" }, admin);
+    const second = await stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.createAccount,
+      { name: "Bank 2", type: "asset" },
+      admin,
+    );
+    expect(second.id).toBeDefined();
+  });
+
+  test("the same code in two different tenants both succeed", async () => {
+    const a = await stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.createAccount,
+      { name: "Bank", type: "asset", code: "1000" },
+      admin,
+    );
+    const b = await stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.createAccount,
+      { name: "Bank", type: "asset", code: "1000" },
+      otherTenant,
+    );
+    expect(a.id).not.toBe(b.id);
+  });
+
+  test("updating an account's code to an existing code in the same tenant is rejected", async () => {
+    await stack.http.writeOk(
+      LedgerHandlers.createAccount,
+      { name: "Bank", type: "asset", code: "1000" },
+      admin,
+    );
+    const other = await stack.http.writeOk<{ id: string }>(
+      LedgerHandlers.createAccount,
+      { name: "Rent", type: "income", code: "2000" },
+      admin,
+    );
+    const otherDetail = await stack.http.queryOk<{ version: number }>(
+      LedgerQueries.accountDetail,
+      { id: other.id },
+      admin,
+    );
+
+    const err = await stack.http.writeErr(
+      LedgerHandlers.updateAccount,
+      { id: other.id, version: otherDetail.version, changes: { code: "1000" } },
+      admin,
+    );
+    expect(err.code).toBe("unique_violation");
+  });
+});
+
 describe("ledger integration — subject dimension (filterable business-object reference)", () => {
   test("a booking with subjectType/subjectId round-trips and is findable via an eq filter", async () => {
     const bank = await createAccount("Bank", "asset");

package/src/ledger/changes.json

@@ -1 +1,9 @@
-[]
+[
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "Account code is unique per tenant (partial unique index read_ledger_accounts_tenant_id_code_uidx)",
+    "detail": "`accountEntity` declares `read_ledger_accounts_tenant_id_code_uidx`, a unique index on `(tenant_id, code)` that only covers accounts with a code. Two parallel find-then-create calls for the same code (two tabs, two devices) could each create an account and leave a tenant with duplicate codes. The second write now fails with `unique_violation` (HTTP 409). This applies to `createAccount` and to an `updateAccount` that changes the code. Accounts without a code are unaffected, and the same code in different tenants stays allowed.",
+    "migration": "Before you apply the migration, check for existing duplicates:\n\n  SELECT tenant_id, code, count(*) FROM read_ledger_accounts\n  WHERE code IS NOT NULL GROUP BY tenant_id, code HAVING count(*) > 1;\n\n`kumiko schema generate` treats a new unique index on a managed projection as destructive. It emits DROP TABLE + CREATE TABLE plus a `.rebuild.json`, which means a full event replay of `read_ledger_accounts`. A rebuild creates the table's indexes before it replays. So if a tenant's event history ever contained two accounts with the same code at the same time, the replay hits the unique index and fails, even after one of them was renamed. For an app with existing ledger data, hand-edit the generated migration before committing it. Replace the DROP/CREATE with an in-place\n\n  CREATE UNIQUE INDEX IF NOT EXISTS \"read_ledger_accounts_tenant_id_code_uidx\"\n    ON \"read_ledger_accounts\" (\"tenant_id\", \"code\") WHERE \"code\" IS NOT NULL;\n\nand delete the `.rebuild.json`. The migrations snapshot stays as generated. If the duplicate check found rows, resolve them first through real writes, for example an `updateAccount` that gives the extra account another code. Never edit the table directly. For such a tenant, a later full rebuild of `read_ledger_accounts` still replays the historical duplicate and fails. An app that already created this index by hand under the same name (money-horse migration 0024) gets a no-op from the in-place statement.\n\nCode that does find-then-create by code should expect `unique_violation` on create and re-read the account that won the race."
+  }
+]

package/src/ledger/entity.ts

@@ -1,3 +1,4 @@
+import { sql } from "@cosmicdrift/kumiko-framework/db";
 import {
   createDateField,
   createEmbeddedListField,
@@ -26,11 +27,23 @@ export const accountEntity = createEntity({
       reason: "is_business_data",
     }),
     type: createSelectField({ options: ACCOUNT_TYPES, required: true }),
-    // Optional account number (Kontonummer / SKR code) — free text in v1.
+    // Optional account number (Kontonummer / SKR code); unique per tenant when set.
     code: createTextField({ maxLength: 32, personal: false, reason: "technical_reference" }),
     // Parent account id, or absent for a root account. No FK (event-sourced).
     parentId: createTextField({ maxLength: 64, personal: false, reason: "technical_reference" }),
   },
+  // Find-then-create by code (solon, money-horse) races across tabs/devices;
+  // only the DB closes that gap. Partial because code is optional. The name is
+  // the one money-horse's hand-written migration 0024 already uses, so both
+  // declare the same Postgres object instead of two indexes.
+  indexes: [
+    {
+      columns: ["tenantId", "code"],
+      unique: true,
+      where: sql`"code" IS NOT NULL`,
+      name: "read_ledger_accounts_tenant_id_code_uidx",
+    },
+  ],
 });
 
 // transaction — a journal entry. The balanced posting lines live embedded as

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

@@ -10,6 +10,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
+import type { lookup } from "node:dns/promises";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
@@ -32,8 +33,13 @@ import { ConfigHandlers } from "../../config/constants";
 import { createConfigAccessorFactory } from "../../config/feature";
 import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
+import { MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR } from "../../foundation-shared";
 import { clearInbox, getInbox, mailTransportInMemoryFeature } from "../../mail-transport-inmemory";
-import { mailTransportSmtpFeature, SMTP_PASSWORD } from "../../mail-transport-smtp";
+import {
+  mailTransportSmtpFeature,
+  SMTP_PASSWORD,
+  setSmtpMailHostLookup,
+} from "../../mail-transport-smtp";
 import { createSecretsContext, createSecretsFeature, tenantSecretsTable } from "../../secrets";
 import { createTenantFeature } from "../../tenant/feature";
 import { tenantEntity } from "../../tenant/schema/tenant";
@@ -86,6 +92,25 @@ let providerRef: MutableMasterKeyProvider;
 
 const testEncryptionKey = randomBytes(32).toString("base64");
 
+// Tenant-supplied SMTP hosts here are placeholder `.test`/`localhost`
+// names that never touch a real server (createSmtpTransport allocates a
+// nodemailer pool lazily, connecting only on send) — pin DNS to a fixed
+// public address so the host-egress guard resolves deterministically
+// instead of depending on real DNS for a name that's never meant to work.
+// "internal-relay.test" is the one exception, mapped to a private address
+// on purpose for scenario 5's resolves-privately rejection case.
+beforeAll(() => {
+  const fakeLookup = (async (hostname: string) => {
+    if (hostname === "internal-relay.test") return [{ address: "127.0.0.1", family: 4 }];
+    return [{ address: "93.184.216.34", family: 4 }];
+  }) as unknown as typeof lookup;
+  setSmtpMailHostLookup(fakeLookup);
+});
+
+afterAll(() => {
+  setSmtpMailHostLookup(undefined);
+});
+
 beforeAll(async () => {
   const encryption = createTestEnvelopeCipher(testEncryptionKey);
   resolver = createConfigResolver({ cipher: encryption });
@@ -283,3 +308,63 @@ describe("scenario 4: in-memory transport dispatch", () => {
     expect(getInbox(admin.tenantId)).toEqual([message]);
   });
 });
+
+// --- Scenario 5: tenant-supplied SMTP host must resolve to a public address ---
+
+describe("scenario 5: mail-host guard", () => {
+  async function configureSmtp(admin: ReturnType<typeof adminFor>, host: string) {
+    await selectSmtpProvider(admin);
+    await setConfig(admin, "mail-transport-smtp:config:host", host);
+    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);
+  }
+
+  test("a private IP-literal host is rejected as unconfigured, naming 'host'", async () => {
+    const admin = adminFor(407);
+    await configureSmtp(admin, "10.0.0.5");
+
+    const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.details).toMatchObject({ feature: "mail-transport-smtp", key: "host" });
+  });
+
+  test("a hostname that resolves to a private address is rejected as unconfigured", async () => {
+    const admin = adminFor(408);
+    await configureSmtp(admin, "internal-relay.test");
+
+    const error = await stack.http.writeErr(TEST_HANDLER_QN, {}, admin);
+    expect(error.httpStatus).toBe(422);
+    expect(error.code).toBe("unconfigured");
+    expect(error.details).toMatchObject({ feature: "mail-transport-smtp", key: "host" });
+  });
+
+  test("a public tenant-supplied host builds successfully", async () => {
+    const admin = adminFor(409);
+    await configureSmtp(admin, "smtp.public-relay.test");
+
+    const result = (await stack.http.writeOk(TEST_HANDLER_QN, {}, admin)) as Record<
+      string,
+      unknown
+    >;
+    expect(result["hasSend"]).toBe(true);
+  });
+
+  test("an operator-allowlisted private relay bypasses the guard", async () => {
+    process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "ops-relay.internal";
+    try {
+      const admin = adminFor(410);
+      await configureSmtp(admin, "ops-relay.internal");
+
+      const result = (await stack.http.writeOk(TEST_HANDLER_QN, {}, admin)) as Record<
+        string,
+        unknown
+      >;
+      expect(result["hasSend"]).toBe(true);
+    } finally {
+      delete process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+    }
+  });
+});

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."
+  }
+]