@nimbus-dev/connectors 0.2.0 → 0.2.2

package/shared/graphql-json.ts

@@ -0,0 +1,60 @@
+/**
+ * graphql-json — one GraphQL-over-HTTP request, for the connectors whose API is a
+ * GraphQL endpoint read as plain JSON (dagster, wiz).
+ *
+ * Both had written out the same request and the same reading of the response
+ * envelope: a present `errors` member fails the call even when `data` came back
+ * too, and an absent `data` member fails it as well. That reading is a rule about
+ * what a partial GraphQL answer means, and it belongs in one place.
+ *
+ * Linear and Monte Carlo read the envelope differently (an `errors` ARRAY that
+ * must be non-empty, messages joined, a result union) and keep their own clients.
+ */
+
+/** Body-snippet length in the thrown errors. The value both connectors used. */
+const SNIPPET_MAX = 400;
+
+export interface GraphqlRequest {
+  /** The GraphQL endpoint. */
+  readonly url: string;
+  /** Service name that prefixes every failure, e.g. `"Wiz 401: ..."`. */
+  readonly label: string;
+  /** Auth headers; `Content-Type` and `Accept` (both `application/json`) are added after them. */
+  readonly headers: Readonly<Record<string, string>>;
+  readonly query: string;
+  /** Omitted from the request body entirely when undefined. */
+  readonly variables?: Record<string, unknown>;
+}
+
+/**
+ * POST `query` (and `variables`) to `url` and resolve to the response's `data`.
+ *
+ * Throws `"<label> <status>: <body snippet>"` on a non-2xx,
+ * `"<label> GraphQL error: <errors snippet>"` when the response carries `errors`,
+ * and `"<label> GraphQL: response missing \`data\` field"` when it carries no `data`.
+ */
+export async function postGraphql<T>(request: GraphqlRequest): Promise<T> {
+  const res = await fetch(request.url, {
+    method: "POST",
+    headers: {
+      ...request.headers,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify({ query: request.query, variables: request.variables }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`${request.label} ${String(res.status)}: ${text.slice(0, SNIPPET_MAX)}`);
+  }
+  const parsed = JSON.parse(text) as { data?: T; errors?: unknown };
+  if (parsed.errors !== undefined) {
+    throw new Error(
+      `${request.label} GraphQL error: ${JSON.stringify(parsed.errors).slice(0, SNIPPET_MAX)}`,
+    );
+  }
+  if (parsed.data === undefined) {
+    throw new Error(`${request.label} GraphQL: response missing \`data\` field`);
+  }
+  return parsed.data;
+}

package/shared/imap-mail-core.ts

@@ -55,3 +55,94 @@ export function formatAddress(a: MailAddress): string {
   }
   return addr;
 }
+
+/**
+ * Message ENVELOPE — RFC 2822 header fields only.
+ *
+ * These five declarations were written out identically in `imap/src/imap-core.ts`
+ * and `protonmail/src/mail-core.ts`, differing only in the `Imap`/`Mail` name
+ * prefix. Both connectors index the same thing through the same protocol, so
+ * there was never a second shape here — only a second copy. Each core now
+ * aliases these, keeping its own names for its own callers.
+ */
+export interface MailEnvelope {
+  readonly date?: Date | string | null;
+  readonly subject?: string | null;
+  readonly messageId?: string | null;
+  readonly from?: readonly MailAddress[];
+  readonly to?: readonly MailAddress[];
+  readonly cc?: readonly MailAddress[];
+}
+
+/**
+ * Attachment METADATA only — filename, size, mimetype. NEVER the bytes.
+ * Derived from BODYSTRUCTURE.
+ */
+export interface MailAttachmentMeta {
+  readonly filename: string | null;
+  readonly sizeBytes: number | null;
+  readonly mimeType: string | null;
+}
+
+/**
+ * A single mailbox message reduced to header + attachment-metadata + a capped
+ * text preview. This is the ONLY shape these connectors ever materialize; it
+ * has no field that could carry attachment content or a full body.
+ */
+export interface MailMessageMeta {
+  readonly uid: number;
+  readonly mailbox: string;
+  readonly uidValidity: string | null;
+  readonly envelope: MailEnvelope;
+  readonly attachments: readonly MailAttachmentMeta[];
+  /** Plain-text body preview, already capped to {@link PREVIEW_MAX_CHARS}. */
+  readonly preview: string;
+}
+
+/** Listing options. */
+export interface MailListOptions {
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+/** Search options — searches header/envelope fields, never body-content scans. */
+export interface MailSearchOptions {
+  readonly query: string;
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+/**
+ * Minimal IMAP client surface these connectors depend on. Implemented for real
+ * by `shared/imapflow-adapter.ts` and by a fake in tests. Deliberately exposes
+ * ONLY header/attachment-metadata + capped-preview reads.
+ */
+export interface MailClient {
+  /** List the most recent messages (header + attachment metadata + preview). */
+  list(options: MailListOptions): Promise<MailMessageMeta[]>;
+  /** Fetch one message's header + attachment metadata + preview by uid. */
+  get(uid: number, mailbox?: string): Promise<MailMessageMeta | null>;
+  /** Search by subject/from/to substring; returns matching message metas. */
+  search(options: MailSearchOptions): Promise<MailMessageMeta[]>;
+}
+
+/** Outgoing message for the SMTP send tool. */
+export interface SendMailInput {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+}
+
+/** Result of a send (message id assigned by the SMTP server, if any). */
+export interface SendMailResult {
+  readonly messageId: string | null;
+  readonly accepted: readonly string[];
+  readonly rejected: readonly string[];
+}
+
+/** Minimal SMTP mailer surface; implemented for real over nodemailer. */
+export interface SmtpMailer {
+  send(input: SendMailInput): Promise<SendMailResult>;
+}

package/shared/imap-tool-kit.ts

@@ -1,4 +1,4 @@
-import type { WriteToolRegistrar } from "./consent-kit.ts";
+import type { WriteToolConfig, WriteToolRegistrar } from "./consent-kit.ts";
 /**
  * Shared tool-layer helpers for the IMAP/JMAP email connectors (imap, protonmail).
  * Extracted to eliminate byte-identical duplication in tools.ts across those two
@@ -10,6 +10,10 @@ import type { WriteToolRegistrar } from "./consent-kit.ts";
  * connector-specific envelope/meta mappers are deliberately NOT extracted here
  * (they implement different local interfaces and are out of scope per the dedup
  * brief).
+ *
+ * The mail-SEND pieces — `sendArgs`, {@link outgoingMail} and {@link mailSendConsent} —
+ * serve every email connector that sends, whatever its transport: imap, protonmail and
+ * apple through the factory below, and fastmail (JMAP), gmail and outlook directly.
  */
 
 import { z } from "zod";
@@ -54,6 +58,55 @@ export const emailToolSchemas = {
   sendArgs,
 } as const;
 
+// ---------------------------------------------------------------------------
+// Shared mail-send helpers (every connector that sends or drafts a new message)
+// ---------------------------------------------------------------------------
+
+/** What a send or draft tool hands its transport. */
+export interface OutgoingMail {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+}
+
+/**
+ * The outgoing message for validated `sendArgs`-shaped input: an empty `cc` or `bcc` is
+ * left out rather than handed on as an empty header.
+ */
+export function outgoingMail(args: {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string | undefined;
+  readonly bcc?: string | undefined;
+}): OutgoingMail {
+  return {
+    to: args.to,
+    subject: args.subject,
+    body: args.body,
+    ...(args.cc !== undefined && args.cc !== "" ? { cc: args.cc } : {}),
+    ...(args.bcc !== undefined && args.bcc !== "" ? { bcc: args.bcc } : {}),
+  };
+}
+
+/**
+ * The consent declaration every mail-send tool shares, given its action type (`mutates`).
+ * A sent mail cannot be recalled and nothing remains to query, so the recipient and
+ * subject ARE the pre-state; the recipient is what the write scope is checked against.
+ */
+export function mailSendConsent<T extends { readonly to: string; readonly subject: string }>(
+  mutates: string,
+): WriteToolConfig<T> {
+  return {
+    mutates,
+    recoverable: false,
+    capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
+    scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Shared view transformer (imap + protonmail tools.ts — viewMessage)
 // ---------------------------------------------------------------------------
@@ -259,30 +312,11 @@ export function registerEmailConnectorTools(opts: {
 
   registerWriteTool(
     `${toolPrefix}_mail_send`,
-    {
-      mutates: `${toolPrefix}.mail.send`,
-      // A sent mail cannot be recalled and nothing remains to query, so the recipient and
-      // subject ARE the pre-state.
-      recoverable: false,
-      capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
-      scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
-    },
+    mailSendConsent(`${toolPrefix}.mail.send`),
     descriptions.send,
     sendArgs,
-    async (parsedData): Promise<McpListResult> => {
-      const parsed = { success: true as const, data: parsedData };
-      const input: { to: string; subject: string; body: string; cc?: string; bcc?: string } = {
-        to: parsed.data.to,
-        subject: parsed.data.subject,
-        body: parsed.data.body,
-      };
-      if (parsed.data.cc !== undefined && parsed.data.cc !== "") {
-        input.cc = parsed.data.cc;
-      }
-      if (parsed.data.bcc !== undefined && parsed.data.bcc !== "") {
-        input.bcc = parsed.data.bcc;
-      }
-      const res = await mailer.send(input);
+    async (args): Promise<McpListResult> => {
+      const res = await mailer.send(outgoingMail(args));
       return mcpJsonResult({
         messageId: res.messageId,
         accepted: res.accepted,

package/shared/imapflow-adapter.ts

@@ -0,0 +1,417 @@
+/**
+ * imapflow-adapter — the real IMAP client + SMTP mailer over `imapflow` and
+ * `nodemailer`, shared by every IMAP-based mail connector (imap, protonmail).
+ *
+ * These two class bodies were previously written out in full in each
+ * connector's `server.ts`. `imap-tool-kit.ts` deliberately left them alone at
+ * the time ("class bodies … are out of scope per the dedup brief"), and the
+ * cost of that was measurable on both axes Sonar reports:
+ *
+ *   - duplication: `imap/src/server.ts` 41.2% and `protonmail/src/server.ts`
+ *     38.8%, 186 duplicated lines between them — the largest pair in the repo;
+ *   - coverage: both files were 0%. An entry point that constructs its adapters
+ *     at module scope cannot be imported by a test without opening real
+ *     sockets, so every line of transport logic in them was unasserted.
+ *
+ * Extracting the classes here fixes both: one copy, and one that a test can
+ * construct because the `imapflow` client and the `nodemailer` transport are
+ * injected seams rather than direct `new` calls. The two connectors differ only
+ * in configuration (TLS mode, ports, env var names, mailbox default), so all of
+ * it is passed in.
+ *
+ * HARD SCOPE CONSTRAINT (security), inherited from both connectors: the fetch
+ * query below requests ONLY `envelope` + `bodyStructure` + a `PREVIEW_FETCH_BYTES`-
+ * capped text part. There is no surface here to request `BODY[]` or an
+ * attachment part, so no caller can make this adapter download message bodies
+ * or attachment bytes.
+ */
+
+import {
+  type FetchMessageObject,
+  type FetchQueryObject,
+  ImapFlow,
+  type MessageAddressObject,
+} from "imapflow";
+import { createTransport, type Transporter } from "nodemailer";
+import {
+  type BodyStructureNode,
+  extractAttachments,
+  findTextPlainPart,
+} from "./imap-bodystructure.ts";
+import { clampLimit, type MailAddress, PREVIEW_FETCH_BYTES } from "./imap-mail-core.ts";
+import {
+  type EmailMessageMeta,
+  type EmailReadClient,
+  type EmailSendMailer,
+  previewFromParts,
+} from "./imap-tool-kit.ts";
+
+/** Mailbox used when a tool call does not name one. */
+export const DEFAULT_MAILBOX = "INBOX";
+
+/** Connection settings for one IMAP endpoint. Read from `process.env` by the caller. */
+export interface ImapEndpointConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly pass: string;
+  /**
+   * Implicit TLS on connect. `true` for a normal IMAPS endpoint on 993; `false`
+   * for the ProtonMail Bridge, which speaks STARTTLS on loopback.
+   */
+  readonly secure: boolean;
+  /**
+   * Chain verification. Omit (the default) for a real endpoint. Only the
+   * ProtonMail Bridge passes `false`, for its self-signed loopback certificate;
+   * the connection never leaves 127.0.0.1.
+   */
+  readonly rejectUnauthorized?: boolean;
+  /** Mailbox used when a call does not name one. Defaults to {@link DEFAULT_MAILBOX}. */
+  readonly defaultMailbox?: string;
+}
+
+/** Connection settings for one SMTP endpoint. */
+export interface SmtpEndpointConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly pass: string;
+  readonly secure: boolean;
+  readonly rejectUnauthorized?: boolean;
+}
+
+/**
+ * There is deliberately no `requireTLS` option.
+ *
+ * When `secure` is false this adapter ALWAYS demands STARTTLS, and that is not
+ * a default a caller can override — an unencrypted SMTP session is not a
+ * configuration this module offers. Without it nodemailer falls back to
+ * plaintext when the server does not advertise STARTTLS, and the password goes
+ * out in the clear.
+ *
+ * The gap was live, not hypothetical: `imap` computes `secure: port === 465`,
+ * so an operator setting `IMAP_SMTP_PORT=587` — the standard submission port —
+ * got `secure: false` with no `requireTLS` at all. Of the three copies this
+ * adapter replaced, only Apple's set it.
+
+/** Constructs the `imapflow` client. Overridden in tests so no socket is opened. */
+export type ImapFlowFactory = (options: ConstructorParameters<typeof ImapFlow>[0]) => ImapFlow;
+
+/**
+ * The transport options this adapter builds. Declared here rather than reused
+ * from nodemailer: `Parameters<typeof createTransport>[0]` resolves to the
+ * union `Transport | TransportOptions`, and a plain SMTP option literal is not
+ * assignable to that union.
+ */
+export interface SmtpTransportOptions {
+  readonly host: string;
+  readonly port: number;
+  readonly secure: boolean;
+  readonly auth: { readonly user: string; readonly pass: string };
+  /** Always set by this module, and always `true` when `secure` is false. */
+  readonly requireTLS: boolean;
+  readonly tls?: { readonly rejectUnauthorized: boolean };
+}
+
+/** Constructs the `nodemailer` transport. Overridden in tests so no socket is opened. */
+export type TransportFactory = (options: SmtpTransportOptions) => Transporter;
+
+/**
+ * Build a {@link MailAddress} from an imapflow envelope address, omitting
+ * `name`/`address` when absent — the interface uses `exactOptionalPropertyTypes`,
+ * so an explicit `undefined` is not assignable.
+ *
+ * The parameter is imapflow's own `MessageAddressObject`, not a restated
+ * `{ name?: string; address?: string }`. imapflow 2 generates its declarations,
+ * which spell the fields `name?: string | undefined`, and under
+ * `exactOptionalPropertyTypes` a hand-written shape without the `| undefined`
+ * stops accepting the library's value.
+ */
+function toMailAddress(a: MessageAddressObject): MailAddress {
+  const out: { name?: string; address?: string } = {};
+  if (a.name !== undefined) {
+    out.name = a.name;
+  }
+  if (a.address !== undefined) {
+    out.address = a.address;
+  }
+  return out;
+}
+
+function envelopeFromImap(env: FetchMessageObject["envelope"]): EmailMessageMeta["envelope"] {
+  if (env === undefined) {
+    return {};
+  }
+  return {
+    date: env.date ?? null,
+    subject: env.subject ?? null,
+    messageId: env.messageId ?? null,
+    from: (env.from ?? []).map(toMailAddress),
+    to: (env.to ?? []).map(toMailAddress),
+    cc: (env.cc ?? []).map(toMailAddress),
+  };
+}
+
+/** Reduce one fetched message to the header + attachment-metadata + preview view. */
+export function toMessageMeta(
+  msg: FetchMessageObject,
+  mailbox: string,
+  uidValidity: string | null,
+): EmailMessageMeta {
+  const structure = (msg.bodyStructure ?? null) as BodyStructureNode | null;
+  const partKey = findTextPlainPart(structure);
+  return {
+    uid: msg.uid,
+    mailbox,
+    uidValidity,
+    envelope: envelopeFromImap(msg.envelope),
+    attachments: extractAttachments(structure),
+    preview: previewFromParts(msg.bodyParts, partKey),
+  };
+}
+
+/**
+ * Fetch query that requests ONLY headers + structure + a truncated text body
+ * part. There is no `source` / full-body request here by construction.
+ */
+export function previewFetchQuery(): FetchQueryObject {
+  return {
+    uid: true,
+    envelope: true,
+    bodyStructure: true,
+    internalDate: true,
+    // Two candidate text part keys, each capped to PREVIEW_FETCH_BYTES bytes.
+    bodyParts: [
+      { key: "1", start: 0, maxLength: PREVIEW_FETCH_BYTES },
+      { key: "TEXT", start: 0, maxLength: PREVIEW_FETCH_BYTES },
+    ],
+  };
+}
+
+/**
+ * imapflow answers `undefined` from `fetchOne` and `search` when it has no
+ * mailbox selected — reachable under the lock `withMailbox` holds only if the
+ * connection closed after it was taken.
+ *
+ * imapflow 1.x did the same at runtime but declared no such return, so the
+ * value reached `toMessageMeta` / `.length` and failed as a bare TypeError. The
+ * generated declarations of 2.x surface it. It stays a FAILURE, now one that
+ * says what happened — not "no such message" or "no results", which would
+ * report a dropped connection as an answer.
+ */
+function mailboxNotSelected(mailbox: string): Error {
+  return new Error(`imap: mailbox "${mailbox}" is no longer selected (connection closed?)`);
+}
+
+/**
+ * Real IMAP client over imapflow. Per-call connect/lock/logout keeps it
+ * stateless, so nothing is held open between tool calls.
+ */
+class ImapFlowClient implements EmailReadClient {
+  private readonly defaultMailbox: string;
+
+  constructor(
+    private readonly config: ImapEndpointConfig,
+    private readonly newImapFlow: ImapFlowFactory,
+  ) {
+    this.defaultMailbox = config.defaultMailbox ?? DEFAULT_MAILBOX;
+  }
+
+  private newClient(): ImapFlow {
+    const { host, port, secure, user, pass, rejectUnauthorized } = this.config;
+    return this.newImapFlow({
+      host,
+      port,
+      secure,
+      auth: { user, pass },
+      logger: false,
+      // Only set when the caller asked to relax it — see ImapEndpointConfig.
+      ...(rejectUnauthorized === undefined ? {} : { tls: { rejectUnauthorized } }),
+    });
+  }
+
+  private async withMailbox<T>(
+    mailbox: string,
+    fn: (client: ImapFlow, uidValidity: string | null) => Promise<T>,
+  ): Promise<T> {
+    const client = this.newClient();
+    await client.connect();
+    // `logout` sits in an OUTER finally so the connection is closed even when
+    // `getMailboxLock` throws. Acquiring the lock BEFORE the try — which is how
+    // imap and protonmail both had it — leaks the connected socket on a locking
+    // failure (a mailbox that does not exist, or one another client holds), and
+    // this client connects per call, so every such failure leaks another.
+    // Apple's copy already nested it this way; the correction travelled the
+    // wrong direction when these were three separate copies.
+    try {
+      const lock = await client.getMailboxLock(mailbox);
+      try {
+        const mb = client.mailbox;
+        const uidValidity = mb === false ? null : String(mb.uidValidity);
+        return await fn(client, uidValidity);
+      } finally {
+        lock.release();
+      }
+    } finally {
+      await client.logout();
+    }
+  }
+
+  async list(options: { mailbox?: string; limit?: number }): Promise<EmailMessageMeta[]> {
+    const mailbox = options.mailbox ?? this.defaultMailbox;
+    const limit = clampLimit(options.limit);
+    return this.withMailbox(mailbox, async (client, uidValidity) => {
+      const out: EmailMessageMeta[] = [];
+      const status = await client.status(mailbox, { messages: true });
+      // `false` is a STATUS the server rejected, read as an empty mailbox. That
+      // is what this did under imapflow 1.x too, which returned the same `false`
+      // but declared only `StatusObject`, so `status.messages ?? 0` made it 0.
+      const total = status === false ? 0 : (status.messages ?? 0);
+      if (total === 0) {
+        return out;
+      }
+      const start = Math.max(1, total - limit + 1);
+      const range = `${start}:${total}`;
+      for await (const msg of client.fetch(range, previewFetchQuery())) {
+        out.push(toMessageMeta(msg, mailbox, uidValidity));
+      }
+      // Most-recent first.
+      out.sort((a, b) => b.uid - a.uid);
+      return out;
+    });
+  }
+
+  async get(uid: number, mailbox?: string): Promise<EmailMessageMeta | null> {
+    const box = mailbox ?? this.defaultMailbox;
+    return this.withMailbox(box, async (client, uidValidity) => {
+      const msg = await client.fetchOne(String(uid), previewFetchQuery(), { uid: true });
+      if (msg === undefined) {
+        throw mailboxNotSelected(box);
+      }
+      return msg === false ? null : toMessageMeta(msg, box, uidValidity);
+    });
+  }
+
+  async search(options: {
+    query: string;
+    mailbox?: string;
+    limit?: number;
+  }): Promise<EmailMessageMeta[]> {
+    const mailbox = options.mailbox ?? this.defaultMailbox;
+    const limit = clampLimit(options.limit);
+    const q = options.query;
+    return this.withMailbox(mailbox, async (client, uidValidity) => {
+      const uids = await client.search(
+        { or: [{ subject: q }, { from: q }, { to: q }] },
+        { uid: true },
+      );
+      if (uids === undefined) {
+        throw mailboxNotSelected(mailbox);
+      }
+      if (uids === false || uids.length === 0) {
+        return [];
+      }
+      const picked = uids.slice(-limit).sort((a, b) => b - a);
+      const out: EmailMessageMeta[] = [];
+      for await (const msg of client.fetch(picked, previewFetchQuery(), { uid: true })) {
+        out.push(toMessageMeta(msg, mailbox, uidValidity));
+      }
+      out.sort((a, b) => b.uid - a.uid);
+      return out;
+    });
+  }
+}
+
+/**
+ * Real SMTP mailer over nodemailer.
+ *
+ * The envelope `from` is PINNED to the authenticated user and is not a `send`
+ * parameter, so no caller can send as someone else (the forced-sender contract
+ * the mail connectors document).
+ */
+class NodemailerMailer implements EmailSendMailer {
+  private readonly transport: Transporter;
+  private readonly from: string;
+
+  constructor(config: SmtpEndpointConfig, makeTransport: TransportFactory) {
+    const { host, port, secure, user, pass, rejectUnauthorized } = config;
+    this.from = user;
+    this.transport = makeTransport({
+      host,
+      port,
+      secure,
+      auth: { user, pass },
+      // Implicit TLS already encrypts the session; otherwise STARTTLS is
+      // required. Not a default — there is no input to this mailer that
+      // produces a transport willing to send in the clear.
+      requireTLS: !secure,
+      ...(rejectUnauthorized === undefined ? {} : { tls: { rejectUnauthorized } }),
+    });
+  }
+
+  async send(input: {
+    to: string;
+    subject: string;
+    body: string;
+    cc?: string;
+    bcc?: string;
+  }): Promise<{
+    messageId: string | null;
+    accepted: readonly string[];
+    rejected: readonly string[];
+  }> {
+    const info = await this.transport.sendMail({
+      from: this.from,
+      to: input.to,
+      subject: input.subject,
+      text: input.body,
+      ...(input.cc === undefined ? {} : { cc: input.cc }),
+      ...(input.bcc === undefined ? {} : { bcc: input.bcc }),
+    });
+    return {
+      messageId: info.messageId ?? null,
+      accepted: (info.accepted ?? []).map(String),
+      rejected: (info.rejected ?? []).map(String),
+    };
+  }
+}
+
+/**
+ * The IMAP read client for `config`. `newImapFlow` defaults to the real
+ * `imapflow` constructor; tests pass a fake so no socket is opened.
+ */
+export function createImapFlowClient(
+  config: ImapEndpointConfig,
+  newImapFlow: ImapFlowFactory = (options) => new ImapFlow(options),
+): EmailReadClient {
+  return new ImapFlowClient(config, newImapFlow);
+}
+
+/**
+ * Construct the real nodemailer transport.
+ *
+ * Written as two explicit branches rather than passing `options` straight
+ * through. `NodemailerMailer` has already computed the guarantee, but a
+ * computed value is not something a reader — or a static analyser — can check
+ * at the call that actually opens the socket. Here it is a literal on both
+ * paths: implicit TLS, or STARTTLS required. There is no third branch.
+ */
+function realTransport(options: SmtpTransportOptions): Transporter {
+  const { host, port, auth } = options;
+  const tls = options.tls === undefined ? {} : { tls: options.tls };
+  if (options.secure) {
+    return createTransport({ host, port, auth, ...tls, secure: true });
+  }
+  return createTransport({ host, port, auth, ...tls, secure: false, requireTLS: true });
+}
+
+/**
+ * The SMTP mailer for `config`. `makeTransport` defaults to the real nodemailer
+ * transport; tests pass a fake so no socket is opened.
+ */
+export function createNodemailerMailer(
+  config: SmtpEndpointConfig,
+  makeTransport: TransportFactory = realTransport,
+): EmailSendMailer {
+  return new NodemailerMailer(config, makeTransport);
+}