@cosmicdrift/kumiko-bundled-features 0.319.0 → 0.320.0

package/src/auth-email-password/web/auth-client.ts

@@ -33,6 +33,9 @@ export type LoginResponse = {
     readonly tenantId: string;
     readonly roles: readonly string[];
   };
+  // Present only when the server's auth.postAuthLanding resolver returned a
+  // valid path — see auth-routes.ts. Screens prefer this over loggedInHref.
+  readonly landingPath?: string;
 };
 
 // Reason codes the login-handler is known to emit today (login-screen.tsx's
@@ -93,6 +96,14 @@ export type LoginResult =
   | { readonly kind: "mfa-setup-required"; readonly preauthSetupToken: string }
   | { readonly kind: "failure"; readonly error: LoginFailure };
 
+function toLoginResponse(
+  token: string,
+  user: LoginResponse["user"],
+  landingPath: unknown,
+): LoginResponse {
+  return typeof landingPath === "string" ? { token, user, landingPath } : { token, user };
+}
+
 // POST /api/auth/login. Success → token + user; MFA-enrolled user → a
 // challenge token the caller completes via auth-mfa's verify screen;
 // unenrolled user blocked by enforcement policy → mfa-setup-required;
@@ -118,6 +129,7 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
     challengeToken?: string;
     mfaSetupRequired?: boolean;
     preauthSetupToken?: string;
+    landingPath?: string;
     error?:
       | {
           code?: string;
@@ -140,7 +152,7 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
       return { kind: "failure", error: { reason: "mfa_setup_required" } };
     }
     if (body.token !== undefined && body.user !== undefined) {
-      return { kind: "success", data: { token: body.token, user: body.user } };
+      return { kind: "success", data: toLoginResponse(body.token, body.user, body.landingPath) };
     }
   }
   // Der Server schickt error entweder als string ("invalid_body") oder als
@@ -343,6 +355,9 @@ export type SignupConfirmSuccess = {
   // Present only when a bound handover grant existed and its claim
   // succeeded — see signup-confirm.write.ts.
   readonly handover?: { readonly entityType: string; readonly id: string };
+  // Present only when the server's auth.postAuthLanding resolver returned a
+  // valid path — see auth-routes.ts.
+  readonly landingPath?: string;
 };
 
 export async function confirmSignup(

package/src/auth-email-password/web/auth-form-logic.ts

@@ -28,3 +28,13 @@ export function resolveLoggedInHref<Args>(
 ): string {
   return typeof href === "function" ? href(args) : href;
 }
+
+/** The server's `landingPath` (auth.postAuthLanding) wins over the screen's
+ *  loggedInHref prop — that prop is a deprecated per-app fallback. */
+export function resolvePostAuthHref<Args>(
+  landingPath: string | undefined,
+  href: string | ((args: Args) => string),
+  args: Args,
+): string {
+  return landingPath ?? resolveLoggedInHref(href, args);
+}

package/src/auth-email-password/web/invite-accept-screen.tsx

@@ -19,7 +19,7 @@
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useContext, useState } from "react";
 import { csrfHeader } from "./auth-client";
-import { resolveLoggedInHref } from "./auth-form-logic";
+import { resolvePostAuthHref } from "./auth-form-logic";
 import { AuthCard, useUrlToken } from "./auth-form-primitives";
 import { SessionContext, UNAUTHENTICATED } from "./session";
 
@@ -29,7 +29,9 @@ export type InviteAcceptScreenProps = {
   /** Where to redirect on success. Default "/" — multi-tenant apps can pass
    *  `(data) => "/${data.tenantId}/"`. Function-form receives the roles this
    *  flow grants in the target tenant; branch 1 reports the invitation's
-   *  role, which for an existing member is not their full role set there. */
+   *  role, which for an existing member is not their full role set there.
+   *  @deprecated Configure auth.postAuthLanding on the server; its landingPath wins.
+   *  Kept as fallback. */
   readonly loggedInHref?:
     | string
     | ((args: { tenantId: string; roles: readonly string[] }) => string);
@@ -46,6 +48,9 @@ type InviteAcceptResponse = {
   readonly tenantId: string;
   readonly role?: string;
   readonly user?: { readonly roles?: readonly string[] };
+  // Present only when the server's auth.postAuthLanding resolver returned a
+  // valid path — see auth-routes.ts.
+  readonly landingPath?: string;
 };
 
 function grantedRoles(data: InviteAcceptResponse): readonly string[] {
@@ -92,7 +97,7 @@ export function InviteAcceptScreen({
       // @cast-boundary engine-payload — auth route JSON
       const data = (await res.json()) as InviteAcceptResponse;
       window.location.assign(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(data.landingPath, loggedInHref, {
           tenantId: data.tenantId,
           roles: grantedRoles(data),
         }),
@@ -117,7 +122,7 @@ export function InviteAcceptScreen({
       // @cast-boundary engine-payload — auth route JSON
       const data = (await res.json()) as InviteAcceptResponse;
       window.location.assign(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(data.landingPath, loggedInHref, {
           tenantId: data.tenantId,
           roles: grantedRoles(data),
         }),
@@ -142,7 +147,7 @@ export function InviteAcceptScreen({
       // @cast-boundary engine-payload — auth route JSON
       const data = (await res.json()) as InviteAcceptResponse;
       window.location.assign(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(data.landingPath, loggedInHref, {
           tenantId: data.tenantId,
           roles: grantedRoles(data),
         }),

package/src/auth-email-password/web/signup-complete-screen.tsx

@@ -10,15 +10,17 @@
 // server-side token pass `token` as a prop instead.
 //
 // On success: shows a confirmation (account active, signed in) with a
-// button to loggedInHref, instead of navigating away immediately — the
-// server already logged the user in via cookies, but a silent redirect
-// leaves no signal that activation worked. Default pattern is "/" — apps
-// with multi-tenant routing pass `(data) => "/" + data.tenantKey + "/"`.
+// button to the continue target, instead of navigating away immediately —
+// the server already logged the user in via cookies, but a silent redirect
+// leaves no signal that activation worked. Server-side auth.postAuthLanding
+// (landingPath) wins over loggedInHref; loggedInHref is the deprecated
+// per-app fallback. Default pattern is "/" — apps with multi-tenant routing
+// pass `(data) => "/" + data.tenantKey + "/"`.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
 import { confirmSignup, type SignupConfirmSuccess } from "./auth-client";
-import { passwordPairIssue, resolveLoggedInHref } from "./auth-form-logic";
+import { passwordPairIssue, resolvePostAuthHref } from "./auth-form-logic";
 import { AuthCard, useUrlToken } from "./auth-form-primitives";
 
 export type SignupCompleteScreenProps = {
@@ -27,7 +29,9 @@ export type SignupCompleteScreenProps = {
   readonly token?: string;
   /** Where to send the user after activation. Function-form receives the tenantKey, the
    *  roles granted by this flow in that tenant, and the claimed `handover` entity when
-   *  signup claimed a try-first grant. Default "/". */
+   *  signup claimed a try-first grant. Default "/".
+   *  @deprecated Configure auth.postAuthLanding on the server; its landingPath wins.
+   *  Kept as fallback. */
   readonly loggedInHref?:
     | string
     | ((args: {
@@ -73,7 +77,7 @@ export function SignupCompleteScreen({
       // explicit continue button instead of navigating away silently —
       // the user otherwise gets no signal that activation worked.
       setContinueHref(
-        resolveLoggedInHref(loggedInHref, {
+        resolvePostAuthHref(res.data.landingPath, loggedInHref, {
           tenantKey: res.data.tenantKey,
           roles: res.data.user.roles,
           ...(res.data.handover !== undefined && { handover: res.data.handover }),

package/src/auth-mfa/web/mfa-client.ts

@@ -32,6 +32,7 @@ export async function verifyMfaChallenge(
     isSuccess?: boolean;
     token?: string;
     user?: LoginResponse["user"];
+    landingPath?: string;
     error?:
       | {
           code?: string;
@@ -41,7 +42,14 @@ export async function verifyMfaChallenge(
       | string;
   };
   if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
-    return { kind: "success", data: { token: body.token, user: body.user } };
+    return {
+      kind: "success",
+      data: {
+        token: body.token,
+        user: body.user,
+        ...(typeof body.landingPath === "string" && { landingPath: body.landingPath }),
+      },
+    };
   }
   const err = body.error;
   if (typeof err === "string") {
@@ -156,6 +164,7 @@ export async function confirmMfaSetupPreauth(
     isSuccess?: boolean;
     token?: string;
     user?: LoginResponse["user"];
+    landingPath?: string;
     error?:
       | {
           code?: string;
@@ -165,7 +174,14 @@ export async function confirmMfaSetupPreauth(
       | string;
   };
   if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
-    return { kind: "success", data: { token: body.token, user: body.user } };
+    return {
+      kind: "success",
+      data: {
+        token: body.token,
+        user: body.user,
+        ...(typeof body.landingPath === "string" && { landingPath: body.landingPath }),
+      },
+    };
   }
   const err = body.error;
   if (typeof err === "string") {

package/src/channel-email/__tests__/smtp-transport-pinning.test.ts

@@ -0,0 +1,42 @@
+// Proves createSmtpTransport actually forwards a pinned host + SNI
+// servername into nodemailer's createTransport, since EmailTransport's
+// public surface (send() only) doesn't expose that otherwise.
+//
+// Restore hygiene: Bun runs a test-run's files in one process, so a
+// top-level mock.module leaks into every file that runs after this one —
+// the real module is captured before mocking and restored in afterAll.
+
+import { afterAll, describe, expect, mock, test } from "bun:test";
+
+const realNodemailer = await import("nodemailer");
+let capturedOptions: Record<string, unknown> | undefined;
+mock.module("nodemailer", () => ({
+  createTransport: (options: Record<string, unknown>) => {
+    capturedOptions = options;
+    return { sendMail: async () => {} };
+  },
+}));
+
+const { createSmtpTransport } = await import("../smtp-transport");
+
+afterAll(() => {
+  mock.module("nodemailer", () => realNodemailer);
+});
+
+describe("createSmtpTransport — nodemailer wiring", () => {
+  test("pins host to the resolved address and sets servername to the original hostname", () => {
+    createSmtpTransport({
+      host: "203.0.113.5",
+      servername: "smtp.tenant.example",
+      from: "noreply@test.local",
+    });
+    expect(capturedOptions?.["host"]).toBe("203.0.113.5");
+    expect(capturedOptions?.["servername"]).toBe("smtp.tenant.example");
+  });
+
+  test("omits servername when the connect target is already the raw host (IP-literal or allowlisted)", () => {
+    createSmtpTransport({ host: "mailpit.internal", from: "noreply@test.local" });
+    expect(capturedOptions?.["host"]).toBe("mailpit.internal");
+    expect(capturedOptions?.["servername"]).toBeUndefined();
+  });
+});

package/src/channel-email/smtp-transport.ts

@@ -40,6 +40,12 @@ export type SmtpTransportOptions = {
    *  override this applies. Accepts both "noreply@ex.com" and
    *  "Name <noreply@ex.com>". */
   readonly from: string;
+  /** TLS SNI hostname. Only needed when `host` is an IP address pinned by
+   *  the caller for a hostname it already resolved — nodemailer otherwise
+   *  skips SNI for an IP `host` and certificate validation would then check
+   *  the wrong name. Unset for the common case where `host` is already the
+   *  hostname to validate against. */
+  readonly servername?: string;
 };
 
 export function createSmtpTransport(options: SmtpTransportOptions): EmailTransport {
@@ -48,6 +54,7 @@ export function createSmtpTransport(options: SmtpTransportOptions): EmailTranspo
     port: options.port ?? 587,
     secure: options.secure ?? false,
     ...(options.auth && { auth: options.auth }),
+    ...(options.servername && { servername: options.servername }),
     pool: true,
     maxConnections: 5,
   });

package/src/file-derivatives/feature.ts

@@ -102,7 +102,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
 
   return defineFeature(FEATURE_NAME, (r) => {
     r.describe(
-      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
+      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",

package/src/file-derivatives/handlers/public-variant.query.ts

@@ -92,13 +92,11 @@ export const publicVariantQuery = defineQueryHandler({
   schema: publicVariantPayloadSchema,
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
   agent: { expose: false },
-  // ponytail: "ip" trusts the first x-forwarded-for hop (buildRequestContextData
-  // in request-id-middleware.ts) — this is the ONLY throttle on an anonymous,
-  // internet-facing render/storage-cost route, so it assumes the deployment's
-  // ingress overwrites (not appends to) x-forwarded-for. A direct-to-origin
-  // deployment lets a caller rotate the header per request and bypass this.
-  // Upgrade path if that assumption doesn't hold: trusted-proxy-count config
-  // on buildRequestContextData, same fix point as every other /api/* route.
+  // ponytail: "ip" is the ONLY throttle on an anonymous, internet-facing
+  // render/storage-cost route — its accuracy depends on the server's
+  // `trustedProxyHops` matching the real number of reverse proxies in
+  // front of it (see api/client-ip.ts). Left at the default 0 with a proxy
+  // actually in front, every caller collapses into one shared bucket.
   rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
   handler: async (query, ctx) => {
     const row = await fetchOne<FileRefRow>(ctx.db, fileRefsTable, {

package/src/foundation-shared/__tests__/mail-host-policy.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import type { lookup } from "node:dns/promises";
+import {
+  BlockedHostError,
+  HostResolutionError,
+  resolveMailConnectTarget,
+} from "../mail-host-policy";
+
+describe("resolveMailConnectTarget", () => {
+  test("pins a public hostname to its resolved address and sets servername to the original host", async () => {
+    const fakeLookup = (async () => [
+      { address: "203.0.113.5", family: 4 },
+    ]) as unknown as typeof lookup;
+
+    await expect(
+      resolveMailConnectTarget("smtp.tenant.example", { lookupFn: fakeLookup }),
+    ).resolves.toEqual({ host: "203.0.113.5", servername: "smtp.tenant.example" });
+  });
+
+  test("connects a public IP-literal host directly, without a servername", async () => {
+    await expect(resolveMailConnectTarget("93.184.216.34")).resolves.toEqual({
+      host: "93.184.216.34",
+    });
+  });
+
+  test("rejects a private IP-literal host", async () => {
+    await expect(resolveMailConnectTarget("10.0.0.5")).rejects.toThrow(BlockedHostError);
+  });
+
+  test("rejects a hostname that resolves to a private address", async () => {
+    const fakeLookup = (async () => [
+      { address: "127.0.0.1", family: 4 },
+    ]) as unknown as typeof lookup;
+
+    await expect(
+      resolveMailConnectTarget("internal.example", { lookupFn: fakeLookup }),
+    ).rejects.toThrow(BlockedHostError);
+  });
+
+  test("surfaces a DNS failure distinctly from a blocked host", async () => {
+    const failingLookup = (async () => {
+      throw new Error("ENOTFOUND");
+    }) as unknown as typeof lookup;
+
+    await expect(
+      resolveMailConnectTarget("nowhere.example", { lookupFn: failingLookup }),
+    ).rejects.toThrow(HostResolutionError);
+  });
+
+  test("allowlisted private host bypasses resolution entirely, case-insensitively", async () => {
+    const lookupFn = (() => {
+      throw new Error("must not be called for an allowlisted host");
+    }) as unknown as typeof lookup;
+
+    await expect(
+      resolveMailConnectTarget("Mailpit.internal", {
+        allowedPrivateMailHosts: ["mailpit.internal"],
+        lookupFn,
+      }),
+    ).resolves.toEqual({ host: "Mailpit.internal" });
+  });
+
+  test("a host absent from the allowlist still goes through resolution", async () => {
+    await expect(
+      resolveMailConnectTarget("10.0.0.5", { allowedPrivateMailHosts: ["mailpit.internal"] }),
+    ).rejects.toThrow(BlockedHostError);
+  });
+});

package/src/foundation-shared/index.ts

@@ -2,3 +2,12 @@
 // Foundation packages (ai-foundation, mail-foundation, file-foundation).
 
 export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers";
+export {
+  BlockedHostError,
+  HostResolutionError,
+  MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  type MailConnectTarget,
+  type MailHostGuardOptions,
+  readAllowedPrivateMailHostsFromEnv,
+  resolveMailConnectTarget,
+} from "./mail-host-policy";

package/src/foundation-shared/mail-host-policy.ts

@@ -0,0 +1,70 @@
+// Connect-time egress guard for tenant-supplied SMTP/IMAP hosts (shared by
+// mail-transport-smtp and inbound-provider-imap): a tenant-controlled host
+// must resolve to a public address, never an internal one. Resolution
+// happens exactly once and the caller connects to the resolved address
+// directly (see kumiko-http's resolvePublicHostname for why that matters),
+// so this also covers hosts that were valid when a tenant set them and
+// only later re-resolve to a private address.
+//
+// `allowedPrivateMailHosts` is the operator's own escape hatch for an
+// internal relay or a dev/test server (mailpit, greenmail) — deliberately
+// an operator env var (KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, read via
+// readAllowedPrivateMailHostsFromEnv), never a tenant-config key, so a
+// tenant can never grant themselves the bypass. Shared by both features
+// since a deploy commonly mounts both; declared once in mail-transport-
+// smtp's envSchema (see its feature.ts) to avoid the framework's env-var-
+// conflict check tripping when both features are mounted together.
+
+import type { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { resolvePublicHostname } from "@cosmicdrift/kumiko-framework/http";
+
+export const MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS";
+
+/** Parses the comma-separated operator allowlist env var. Never throws —
+ *  an unset or empty value just means no bypass. */
+export function readAllowedPrivateMailHostsFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): readonly string[] {
+  const raw = env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((host) => host.trim())
+    .filter((host) => host.length > 0);
+}
+
+export type MailHostGuardOptions = {
+  readonly allowedPrivateMailHosts?: readonly string[];
+  readonly lookupFn?: typeof lookup;
+};
+
+export type MailConnectTarget = {
+  readonly host: string;
+  readonly servername?: string;
+};
+
+function isAllowedPrivateMailHost(host: string, allowed: readonly string[]): boolean {
+  return allowed.some((candidate) => candidate.toLowerCase() === host.toLowerCase());
+}
+
+export async function resolveMailConnectTarget(
+  host: string,
+  options: MailHostGuardOptions = {},
+): Promise<MailConnectTarget> {
+  if (isAllowedPrivateMailHost(host, options.allowedPrivateMailHosts ?? [])) {
+    return { host };
+  }
+  const resolved = await resolvePublicHostname(host, options.lookupFn);
+  // An IP-literal host pins to itself — no hostname was ever there for TLS
+  // SNI/cert validation to check, so `servername` stays unset (the mail
+  // libraries themselves skip SNI for an IP host).
+  if (isIP(host) !== 0) {
+    return { host: resolved.address };
+  }
+  return { host: resolved.address, servername: host };
+}
+
+// Re-exported so callers can classify a rejection (policy verdict, no
+// retry) without importing kumiko-http directly.
+export { BlockedHostError, HostResolutionError } from "@cosmicdrift/kumiko-framework/http";

package/src/inbound-provider-imap/__tests__/imap-foundation.integration.test.ts

@@ -40,6 +40,7 @@ import {
   tenantComplianceProfileEntity,
 } from "../../compliance-profiles";
 import { createConfigFeature } from "../../config";
+import { MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR } from "../../foundation-shared";
 import {
   createInboundMailSupervisor,
   InboundMailAccountStatuses,
@@ -63,6 +64,11 @@ const USER = "testuser";
 const PASSWORD = "testpass";
 const ADDRESS = "testuser@example.com";
 
+// greenmail is a local test server, not tenant-supplied — needs the
+// operator escape hatch since HOST is a private/loopback address.
+const originalAllowedPrivateHostsEnv = process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = HOST;
+
 function probe(host: string, port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const socket = connect({ host, port, timeout: 1500 });
@@ -127,6 +133,11 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
+  if (originalAllowedPrivateHostsEnv === undefined) {
+    delete process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+  } else {
+    process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = originalAllowedPrivateHostsEnv;
+  }
   if (!available) return;
   await stack.cleanup();
   resetPiiSubjectKmsForTests();

package/src/inbound-provider-imap/__tests__/imap-live.integration.test.ts

@@ -15,10 +15,11 @@
 // — der volle Dispatcher-Pfad ist in
 // inbound-mail-foundation.integration.test.ts abgedeckt.
 
-import { describe, expect, test } from "bun:test";
+import { afterAll, describe, expect, test } from "bun:test";
 import { connect } from "node:net";
 import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
 import { createTransport } from "nodemailer";
+import { MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR } from "../../foundation-shared";
 import {
   type InboundMailContext,
   isInboundAuthError,
@@ -35,6 +36,18 @@ const USER = "testuser";
 const PASSWORD = "testpass";
 const ADDRESS = "testuser@example.com";
 
+// greenmail is a local test server, not tenant-supplied — needs the
+// operator escape hatch since HOST is a private/loopback address.
+const originalAllowedPrivateHostsEnv = process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = HOST;
+afterAll(() => {
+  if (originalAllowedPrivateHostsEnv === undefined) {
+    delete process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+  } else {
+    process.env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = originalAllowedPrivateHostsEnv;
+  }
+});
+
 function probe(host: string, port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const socket = connect({ host, port, timeout: 1500 });

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