@cosmicdrift/kumiko-bundled-features 0.319.0 → 0.321.0

package/src/inbound-provider-imap/__tests__/plugin-mocked.test.ts

@@ -2,10 +2,12 @@
 // Greenmail suites skip in CI when the container is down — this file mocks
 // imapflow so the plugin body stays on the coverage badge without Docker.
 
-import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterAll, afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import type { lookup } from "node:dns/promises";
 import { EventEmitter } from "node:events";
 import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
 import { sleep, waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import { MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR } from "../../foundation-shared";
 import {
   type InboundMailContext,
   isInboundAuthError,
@@ -36,10 +38,12 @@ let lastIdleClient: FakeImapFlow | undefined;
 
 class FakeImapFlow extends EventEmitter {
   mailbox: { uidValidity: bigint; uidNext: number } | false = false;
+  readonly opts: Record<string, unknown>;
   private idleReject: ((err: Error) => void) | undefined;
 
-  constructor(_opts: unknown) {
+  constructor(opts: Record<string, unknown>) {
     super();
+    this.opts = opts;
     lastIdleClient = this;
   }
 
@@ -119,7 +123,28 @@ class FakeImapFlow extends EventEmitter {
 const realImapflow = await import("imapflow");
 mock.module("imapflow", () => ({ ImapFlow: FakeImapFlow }));
 
-const { imapInboundMailPlugin } = await import("../feature");
+const { imapInboundMailPlugin, setImapMailHostLookup } = await import("../feature");
+
+/** Host-aware fake resolver — an unmapped hostname behaves like a real ENOTFOUND. */
+function fakeLookupFor(addressesByHost: Readonly<Record<string, string>>): typeof lookup {
+  return (async (hostname: string) => {
+    const address = addressesByHost[hostname];
+    if (!address) throw new Error(`ENOTFOUND ${hostname}`);
+    return [{ address, family: 4 }];
+  }) as unknown as typeof lookup;
+}
+
+// goodDoc's host is a placeholder that must still clear the mail-host guard —
+// resolved to a public address so the pinned-connect path (host+servername)
+// is exercised the same way a real tenant hostname would be.
+beforeEach(() => {
+  setImapMailHostLookup(fakeLookupFor({ "imap.example.com": "203.0.113.5" }));
+});
+
+afterEach(() => {
+  setImapMailHostLookup(undefined);
+  delete process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+});
 
 afterAll(() => {
   mock.module("imapflow", () => realImapflow);
@@ -198,6 +223,10 @@ describe("imapInboundMailPlugin — mocked imapflow", () => {
     await expect(
       imapInboundMailPlugin.verify(ctxWithDoc(goodDoc), account),
     ).resolves.toBeUndefined();
+    // Proves the connect path actually pins to the resolved IP with SNI set
+    // to the original hostname, not just that some connect happened.
+    expect(lastIdleClient?.opts["host"]).toBe("203.0.113.5");
+    expect(lastIdleClient?.opts["servername"]).toBe("imap.example.com");
   });
 
   test("verify: auth failure → InboundAuthError", async () => {
@@ -354,3 +383,59 @@ describe("imapInboundMailPlugin — mocked imapflow", () => {
     await stop().catch(() => {});
   });
 });
+
+function docWithHost(host: string): string {
+  return JSON.stringify({ host, port: 993, secure: true, user: "u@example.com", password: "pw" });
+}
+
+describe("imapInboundMailPlugin — mail-host guard", () => {
+  test("a private IP-literal host is rejected before any connect attempt", async () => {
+    lastIdleClient = undefined;
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc(docWithHost("10.0.0.5")), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+      expect((e as Error).message).toBe("IMAP host is not reachable or not allowed");
+      expect((e as Error).message).not.toContain("10.0.0.5");
+    }
+    expect(lastIdleClient).toBeUndefined();
+  });
+
+  test("a hostname resolving to a private address is rejected before any connect attempt", async () => {
+    setImapMailHostLookup(fakeLookupFor({ "internal.example": "127.0.0.1" }));
+    lastIdleClient = undefined;
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc(docWithHost("internal.example")), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+      expect((e as Error).message).toBe("IMAP host is not reachable or not allowed");
+      expect((e as Error).message).not.toContain("internal.example");
+      expect((e as Error).message).not.toContain("127.0.0.1");
+    }
+    expect(lastIdleClient).toBeUndefined();
+  });
+
+  test("a DNS resolution failure surfaces as InboundTransientError before any connect attempt, with the same tenant-visible message as a blocked host", async () => {
+    setImapMailHostLookup(fakeLookupFor({}));
+    lastIdleClient = undefined;
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc(docWithHost("nowhere.example")), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundTransientError(e)).toBe(true);
+      expect(isInboundAuthError(e)).toBe(false);
+      expect((e as Error).message).toBe("IMAP host is not reachable or not allowed");
+      expect((e as Error).message).not.toContain("nowhere.example");
+    }
+    expect(lastIdleClient).toBeUndefined();
+  });
+
+  test("an operator-allowlisted private host bypasses resolution and keeps its raw host, without SNI", async () => {
+    process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "mailpit.internal";
+    await imapInboundMailPlugin.verify(ctxWithDoc(docWithHost("mailpit.internal")), account);
+    expect(lastIdleClient?.opts["host"]).toBe("mailpit.internal");
+    expect(lastIdleClient?.opts["servername"]).toBeUndefined();
+  });
+});

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];
+    }
+  });
+});