@ultimat3/mail 1.0.0

package/src/smtp-client.ts

@@ -0,0 +1,246 @@
+// Single responsibility: the SMTP conversation — greeting, EHLO, STARTTLS, AUTH, envelope, DATA.
+// It talks to an `SmtpStream`, never to a socket, so the whole protocol runs in a test with no
+// network. Every refusal becomes `X_MAIL_SEND_FAILED` naming the stage and the server's own reply.
+
+import { base64Utf8 } from './base64';
+import { type MailError, type SendStage, sendFailed } from './errors';
+import {
+  authPlain,
+  createReplyParser,
+  dotStuff,
+  isPositive,
+  isTransient,
+  parseCapabilities,
+  replySummary,
+  type SmtpCapabilities,
+  type SmtpReply,
+} from './smtp-protocol';
+
+/** The byte pipe the conversation runs over. `smtp-socket.ts` implements it over `Bun.connect`. */
+export interface SmtpStream {
+  /** The next chunk the server sent, or `undefined` once it closed the connection. */
+  read(): Promise<string | undefined>;
+  write(data: string): Promise<void>;
+  /** STARTTLS: negotiate TLS in place. Everything read or written after this is encrypted. */
+  startTls(): Promise<void>;
+  close(): void;
+}
+
+export interface SmtpTarget {
+  readonly host: string;
+  readonly port: number;
+  /** Implicit TLS (`smtps://`, usually port 465). `false` starts the session in the clear. */
+  readonly tls: boolean;
+  readonly timeoutMs: number;
+}
+
+export type SmtpConnector = (target: SmtpTarget) => Promise<SmtpStream>;
+
+export interface SmtpEnvelope {
+  /** The bare addr-spec for `MAIL FROM`, never a `Name <addr>` display form. */
+  readonly from: string;
+  readonly recipients: readonly string[];
+  /** The MIME message. Dot-stuffing and the terminator belong to this module. */
+  readonly data: string;
+}
+
+export interface SmtpSessionOptions {
+  /** The `EHLO` argument. A real name the receiving server can resolve, not `localhost`. */
+  readonly clientName: string;
+  /** True when the socket is already TLS, so STARTTLS is neither needed nor offered. */
+  readonly secure: boolean;
+  readonly user?: string | undefined;
+  readonly password?: string | undefined;
+  /** Send — and authenticate — over a cleartext channel. Off by default, for obvious reasons. */
+  readonly allowInsecure: boolean;
+  readonly timeoutMs: number;
+}
+
+/** The goodbye is not worth the read deadline the rest of the conversation gets. */
+const QUIT_TIMEOUT_MS = 5_000;
+
+// Keyed by `SendStage`, so a stage that is added to the union and forgotten here is a lookup that
+// falls back rather than a silent typo. `Partial` because `connect` and `request` never reach a
+// server reply: one belongs to the socket and the other to the HTTPS transport.
+const FIXES: Readonly<Partial<Record<SendStage, string>>> = {
+  greeting: 'correct the host and port in SMTP_URL — the server did not open with 220',
+  ehlo: 'point SMTP_URL at an ESMTP server (submission on 587, implicit TLS on 465)',
+  reply: 'point SMTP_URL at the SMTP port itself — a proxy or an HTTP port answers like this',
+  tls: 'fix the certificate on the implicit-TLS port, or use smtp://host:587 and STARTTLS',
+  starttls: 'set SMTP_URL in .env to smtps://host:465',
+  auth: 'set SMTP_URL in .env to smtps://user:password@host:465 with a valid user and password',
+  from: 'set mail.from in app.config.ts to an address this server is willing to relay for',
+  recipient: 'the reply above names the address the server refused — correct or drop it',
+  data: 'the reply above says why the body was refused (size, content or policy)',
+  quit: 'nothing to fix: the message was already accepted before the goodbye failed',
+};
+
+const refused = (stage: SendStage, reply: SmtpReply): MailError =>
+  sendFailed({
+    driver: 'smtp',
+    stage,
+    detail: replySummary(reply),
+    status: reply.code,
+    retryable: isTransient(reply.code),
+    fix: FIXES[stage] ?? 'run x doctor --json and check the mail section',
+  });
+
+/** Reads whole replies off a chunked stream, with a deadline on every one of them. */
+class Conversation {
+  private readonly parser = createReplyParser();
+  private readonly pending: SmtpReply[] = [];
+
+  constructor(
+    private readonly stream: SmtpStream,
+    private readonly timeoutMs: number,
+  ) {}
+
+  /** Sends one command line and reads the reply it expects. The line is never logged. */
+  async say(stage: SendStage, line: string, wanted: (code: number) => boolean): Promise<SmtpReply> {
+    await this.stream.write(`${line}\r\n`);
+    return this.expect(stage, wanted);
+  }
+
+  async expect(stage: SendStage, wanted: (code: number) => boolean): Promise<SmtpReply> {
+    const reply = await this.next(stage);
+    if (!wanted(reply.code)) throw refused(stage, reply);
+    return reply;
+  }
+
+  /**
+   * Waits for the `221` so the server records a clean close instead of an aborted transaction —
+   * but on a short leash, since the message is already accepted and a rude server that never
+   * answers must not add its own delay to every send. Failures here are deliberately swallowed.
+   */
+  async quit(): Promise<void> {
+    await this.stream.write('QUIT\r\n').catch(() => undefined);
+    await this.next('quit', Math.min(this.timeoutMs, QUIT_TIMEOUT_MS)).catch(() => undefined);
+  }
+
+  private async next(stage: SendStage, timeoutMs = this.timeoutMs): Promise<SmtpReply> {
+    for (;;) {
+      const ready = this.pending.shift();
+      if (ready !== undefined) return ready;
+      this.pending.push(...this.parser.push(await this.chunk(stage, timeoutMs)));
+    }
+  }
+
+  private async chunk(stage: SendStage, timeoutMs: number): Promise<string> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const expired = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          sendFailed({
+            driver: 'smtp',
+            stage,
+            detail: `the server sent nothing for ${timeoutMs}ms, so the read deadline expired`,
+            retryable: true,
+            fix: 'pass timeoutMs: 60_000 to createSmtpDriver() in app.config.ts',
+          }),
+        );
+      }, timeoutMs);
+    });
+    try {
+      const chunk = await Promise.race([this.stream.read(), expired]);
+      if (chunk === undefined) {
+        throw sendFailed({
+          driver: 'smtp',
+          stage,
+          detail:
+            'the server closed the connection mid-conversation, which is usually it ' +
+            'rate-limiting the sessions it keeps open at once',
+          retryable: true,
+          fix: 'pass poolSize: 1 to createSmtpDriver() in app.config.ts',
+        });
+      }
+      return chunk;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * One message, one connection. Returns the server's final `DATA` reply — the receipt an operator
+ * needs when the recipient says the mail never arrived.
+ */
+export async function smtpDeliver(
+  stream: SmtpStream,
+  envelope: SmtpEnvelope,
+  options: SmtpSessionOptions,
+): Promise<SmtpReply> {
+  const talk = new Conversation(stream, options.timeoutMs);
+  await talk.expect('greeting', (code) => code === 220);
+
+  const greet = async (): Promise<SmtpCapabilities> =>
+    parseCapabilities(await talk.say('ehlo', `EHLO ${options.clientName}`, isPositive));
+
+  let capabilities = await greet();
+  let secure = options.secure;
+
+  if (!secure && capabilities.starttls) {
+    await talk.say('starttls', 'STARTTLS', (code) => code === 220);
+    await stream.startTls();
+    // Capabilities before TLS are not the capabilities after it: most servers only advertise AUTH
+    // once the channel is encrypted, and a cleartext EHLO can be stripped in flight anyway.
+    capabilities = await greet();
+    secure = true;
+  }
+
+  if (!secure && !options.allowInsecure) {
+    throw sendFailed({
+      driver: 'smtp',
+      stage: 'starttls',
+      detail:
+        'the server does not advertise STARTTLS and the connection is not already TLS; ' +
+        'allowInsecure: true on createSmtpDriver() would send this in the clear instead',
+      retryable: false,
+      fix: FIXES['starttls'] ?? 'set SMTP_URL in .env to smtps://host:465',
+    });
+  }
+
+  if (options.user !== undefined) await authenticate(talk, capabilities, options);
+
+  await talk.say('from', `MAIL FROM:<${envelope.from}>`, isPositive);
+  for (const recipient of envelope.recipients) {
+    // Fail closed on any refusal: delivering to three of four addresses and reporting success is
+    // the one outcome the caller cannot detect.
+    await talk.say('recipient', `RCPT TO:<${recipient}>`, isPositive);
+  }
+
+  await talk.say('data', 'DATA', (code) => code === 354);
+  const body = dotStuff(envelope.data).replace(/\r\n$/, '');
+  const accepted = await talk.say('data', `${body}\r\n.`, isPositive);
+  await talk.quit();
+  return accepted;
+}
+
+async function authenticate(
+  talk: Conversation,
+  capabilities: SmtpCapabilities,
+  options: SmtpSessionOptions,
+): Promise<void> {
+  const user = options.user ?? '';
+  const password = options.password ?? '';
+  const mechanisms = capabilities.authMechanisms;
+
+  if (mechanisms.includes('PLAIN')) {
+    await talk.say('auth', `AUTH PLAIN ${authPlain(user, password)}`, (code) => code === 235);
+    return;
+  }
+  if (mechanisms.includes('LOGIN')) {
+    await talk.say('auth', 'AUTH LOGIN', (code) => code === 334);
+    await talk.say('auth', base64Utf8(user), (code) => code === 334);
+    await talk.say('auth', base64Utf8(password), (code) => code === 235);
+    return;
+  }
+  throw sendFailed({
+    driver: 'smtp',
+    stage: 'auth',
+    detail: `the server offers no mechanism this client speaks (offered: ${
+      mechanisms.join(', ') || 'none'
+    })`,
+    retryable: false,
+    fix: 'drop user:password from SMTP_URL if the server wants none, or enable AUTH PLAIN on it',
+  });
+}

package/src/smtp-protocol.ts

@@ -0,0 +1,184 @@
+// Single responsibility: pure SMTP protocol parsing and encoding — reply framing, EHLO
+// capability parsing, AUTH payloads, DATA-phase dot-stuffing. No sockets, no IO: `smtp-client.ts`
+// drives the connection and calls into these functions with raw chunks, getting typed values back.
+
+import { base64Utf8 } from './base64';
+import { sendFailed } from './errors';
+
+/** One complete server reply. `text` is every continuation line joined by a space. */
+export interface SmtpReply {
+  readonly code: number;
+  readonly lines: readonly string[];
+  readonly text: string;
+}
+
+export interface SmtpCapabilities {
+  readonly starttls: boolean;
+  /** Upper-cased, in the order the server advertised them: e.g. `['PLAIN','LOGIN']`. */
+  readonly authMechanisms: readonly string[];
+  /** From `SIZE 35882577`. Absent when the server does not advertise one. */
+  readonly maxSizeBytes?: number | undefined;
+  readonly eightBitMime: boolean;
+  readonly pipelining: boolean;
+}
+
+export interface ReplyParser {
+  /** Feed a socket chunk; returns every reply that completed inside it, in order. */
+  push(chunk: string): readonly SmtpReply[];
+  /** True when a partial line is still buffered — a connection closing here died mid-reply. */
+  hasPending(): boolean;
+}
+
+// Three digits then `-` (more lines follow), ` ` (last line) or end-of-line (a bare code with
+// no text, also a last line). Anything else — four digits, no digits, prose — is not a reply
+// line and must be skipped, never crashed on or folded into a neighbouring reply.
+const REPLY_LINE = /^(\d{3})(?:([- ])(.*))?$/;
+
+// RFC 5321 caps a reply line at 512 octets and a full reply is a handful of them, so nothing
+// legitimate comes near this. The cap exists because the read deadline in `smtp-client.ts`
+// measures the gap between chunks: a peer that dribbles bytes with no line ending resets that
+// deadline on every read while this buffer grows, which is an unbounded allocation no timeout
+// ever interrupts. Coded failure > OOM.
+const MAX_REPLY_BYTES = 64 * 1024;
+
+/**
+ * Buffers socket chunks into complete `SmtpReply` values. A chunk can split anywhere — mid-line,
+ * mid-CRLF, or carry several replies at once — so the dangling partial line and any continuation
+ * lines already read for a reply whose final line has not arrived yet both live in the closure
+ * and survive across `push()` calls.
+ */
+export function createReplyParser(): ReplyParser {
+  let buffer = '';
+  let pendingLines: string[] | null = null;
+  // Continuation lines held for a reply whose final line never arrives are the same unbounded
+  // growth as an endless partial line, so both count against the one cap.
+  let pendingBytes = 0;
+
+  const guard = (): void => {
+    if (buffer.length + pendingBytes <= MAX_REPLY_BYTES) return;
+    throw sendFailed({
+      driver: 'smtp',
+      stage: 'reply',
+      detail: `the server sent more than ${MAX_REPLY_BYTES} bytes without completing one reply`,
+      retryable: true,
+      fix: 'point SMTP_URL at the SMTP port itself — a proxy or an HTTP port answers like this',
+    });
+  };
+
+  return {
+    push(chunk: string): readonly SmtpReply[] {
+      buffer += chunk;
+      const rawLines = buffer.split('\n');
+      buffer = rawLines.pop() ?? '';
+
+      const replies: SmtpReply[] = [];
+      for (const rawLine of rawLines) {
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        if (line.length === 0) continue; // blank line: not part of any reply
+
+        const match = REPLY_LINE.exec(line);
+        if (!match) continue; // garbage: skipped, not merged into the surrounding reply
+
+        const codeText = match[1];
+        if (codeText === undefined) continue; // the group is mandatory; narrows the type for TS
+
+        pendingLines ??= [];
+        pendingLines.push(match[3] ?? '');
+        pendingBytes += line.length;
+
+        if (match[2] !== '-') {
+          replies.push({
+            code: Number(codeText),
+            lines: pendingLines,
+            text: pendingLines.join(' '),
+          });
+          pendingLines = null;
+          pendingBytes = 0;
+        }
+      }
+
+      // Checked after the loop so only what is still unresolved counts: every reply this chunk
+      // completed has already drained both counters, and a well-behaved server never accumulates.
+      guard();
+      return replies;
+    },
+    hasPending(): boolean {
+      return buffer.length > 0 || pendingLines !== null;
+    },
+  };
+}
+
+const STARTTLS_LINE = /^STARTTLS$/i;
+const PIPELINING_LINE = /^PIPELINING$/i;
+const EIGHT_BIT_MIME_LINE = /^8BITMIME$/i;
+const SIZE_LINE = /^SIZE(?:\s+(\S+))?$/i;
+// Some servers still send the legacy `AUTH=PLAIN LOGIN` form instead of `AUTH PLAIN LOGIN`;
+// `[=\s]+` accepts either separator, and mechanisms are re-split on any run of spaces too.
+const AUTH_LINE = /^AUTH[=\s]+(.*)$/i;
+
+/** `EHLO` reply -> what the server can do. The greeting line itself is not a capability. */
+export function parseCapabilities(reply: SmtpReply): SmtpCapabilities {
+  let starttls = false;
+  let pipelining = false;
+  let eightBitMime = false;
+  let maxSizeBytes: number | undefined;
+  const authMechanisms: string[] = [];
+
+  for (const raw of reply.lines.slice(1)) {
+    const line = raw.trim();
+    const sizeMatch = SIZE_LINE.exec(line);
+    const authMatch = AUTH_LINE.exec(line);
+
+    if (STARTTLS_LINE.test(line)) {
+      starttls = true;
+    } else if (PIPELINING_LINE.test(line)) {
+      pipelining = true;
+    } else if (EIGHT_BIT_MIME_LINE.test(line)) {
+      eightBitMime = true;
+    } else if (sizeMatch) {
+      const value = sizeMatch[1];
+      // A non-numeric or missing size is silently absent — never `Number('abc')`'s `NaN`.
+      if (value !== undefined && /^\d+$/.test(value)) maxSizeBytes = Number(value);
+    } else if (authMatch) {
+      for (const mechanism of (authMatch[1] ?? '').split(/\s+/)) {
+        if (mechanism.length > 0) authMechanisms.push(mechanism.toUpperCase());
+      }
+    }
+  }
+
+  return { starttls, authMechanisms, maxSizeBytes, eightBitMime, pipelining };
+}
+
+/** RFC 4616: base64 of `\0user\0password`. */
+export function authPlain(user: string, password: string): string {
+  return base64Utf8(`\0${user}\0${password}`);
+}
+
+/** True for a 4xx reply: a greylist or throttle that the job's next attempt can clear. */
+export function isTransient(code: number): boolean {
+  return code >= 400 && code < 500;
+}
+
+/** True for 2xx. 3xx is a continuation (`354` for DATA, `334` for AUTH), never a success. */
+export function isPositive(code: number): boolean {
+  return code >= 200 && code < 300;
+}
+
+const LINE_BREAK = /\r\n|\n/;
+
+/**
+ * RFC 5321 transparency: CRLF-normalise the message and double any leading `.` so a body line
+ * of `.` cannot end the DATA phase early. Does NOT append the `\r\n.\r\n` terminator — the
+ * client owns that.
+ */
+export function dotStuff(body: string): string {
+  return body
+    .split(LINE_BREAK)
+    .map((line) => (line.startsWith('.') ? `.${line}` : line))
+    .join('\r\n');
+}
+
+/** One line fit for an error `cause`: `550 5.1.1 no such user`. Never multi-line. */
+export function replySummary(reply: SmtpReply): string {
+  return reply.text.length === 0 ? `${reply.code}` : `${reply.code} ${reply.text}`;
+}

package/src/smtp-socket.ts

@@ -0,0 +1,266 @@
+// Single responsibility: the one production `SmtpStream`, over `Bun.connect`. Bun pushes bytes at
+// handlers while the conversation pulls replies, so a queue sits between them; `startTls` swaps in
+// the upgraded socket for STARTTLS. Nothing here knows an SMTP verb — that is `smtp-client.ts`.
+
+import { type MailError, sendFailed } from './errors';
+import type { SmtpStream, SmtpTarget } from './smtp-client';
+
+/** Structural view of Bun's socket — declared here so the contract does not depend on bun-types. */
+export interface SocketLike {
+  write(data: Uint8Array): number;
+  end(): void;
+  upgradeTLS(options: {
+    readonly tls: { readonly serverName: string };
+    readonly socket: SocketHandlers;
+  }): readonly SocketLike[];
+}
+
+export interface SocketHandlers {
+  data(socket: SocketLike, data: Uint8Array): void;
+  close(): void;
+  end(): void;
+  drain(): void;
+  error(socket: SocketLike, error: Error): void;
+}
+
+export interface BunConnect {
+  connect(options: {
+    readonly hostname: string;
+    readonly port: number;
+    readonly tls: boolean;
+    readonly socket: SocketHandlers;
+  }): Promise<SocketLike>;
+}
+
+interface Waiter {
+  readonly resolve: (chunk: string | undefined) => void;
+  readonly reject: (error: Error) => void;
+}
+
+/** Chunks the socket pushed, handed out one `read()` at a time — EOF and socket errors included. */
+class ChunkQueue {
+  private readonly chunks: string[] = [];
+  private waiting: Waiter | undefined;
+  private ended = false;
+  private failure: Error | undefined;
+
+  push(chunk: string): void {
+    const waiter = this.take();
+    if (waiter === undefined) {
+      this.chunks.push(chunk);
+      return;
+    }
+    waiter.resolve(chunk);
+  }
+
+  /** EOF. A reader parked on `read()` is released rather than left hanging forever. */
+  end(): void {
+    this.ended = true;
+    this.take()?.resolve(undefined);
+  }
+
+  /** A socket-level failure (TLS, reset) reaches the caller instead of looking like a clean EOF. */
+  fail(error: Error): void {
+    this.failure = error;
+    this.ended = true;
+    this.take()?.reject(error);
+  }
+
+  read(): Promise<string | undefined> {
+    const next = this.chunks.shift();
+    if (next !== undefined) return Promise.resolve(next);
+    if (this.failure !== undefined) return Promise.reject(this.failure);
+    if (this.ended) return Promise.resolve(undefined);
+    return new Promise((resolve, reject) => {
+      this.waiting = { resolve, reject };
+    });
+  }
+
+  private take(): Waiter | undefined {
+    const waiter = this.waiting;
+    this.waiting = undefined;
+    return waiter;
+  }
+}
+
+/** A write parked for backpressure: released by `drain`, failed by whatever ends the socket. */
+interface DrainWaiter {
+  readonly resolve: () => void;
+  readonly reject: (error: MailError) => void;
+}
+
+/**
+ * Which TLS negotiation is in flight, and therefore how a failure now has to be reported: `tls` is
+ * the implicit handshake an `smtps://` connection opens with, `starttls` the in-band upgrade. Both
+ * windows close on the first byte back — encrypted bytes only flow once the handshake completed,
+ * so that first chunk is the proof it did. `undefined` is a channel with no handshake pending.
+ */
+type Handshake = 'tls' | 'starttls' | undefined;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export function bunSmtpStream(target: SmtpTarget): Promise<SmtpStream> {
+  return smtpStreamOver(Bun as unknown as BunConnect, target);
+}
+
+/**
+ * `bunSmtpStream` with the runtime handed in. A `write` that returns `-1`, an `error` during the
+ * TLS handoff and a `drain` that never comes are all unreachable over a real socket, and each one
+ * used to cost a full deadline or a wrong stage — so they are driven by hand in the tests.
+ */
+export function smtpStreamOver(runtime: BunConnect, target: SmtpTarget): Promise<SmtpStream> {
+  const queue = new ChunkQueue();
+  let draining: DrainWaiter | undefined;
+  // `smtps://` hands the socket to TLS before a single SMTP byte is exchanged, so the window is
+  // already open when the connection is made; a plaintext one opens it at `startTls()` or never.
+  let handshake: Handshake = target.tls ? 'tls' : undefined;
+
+  /**
+   * A failed handshake is a refused certificate or a protocol mismatch, and the same attempt fails
+   * identically forever — reporting it as retryable requeues a job against a wall. The two windows
+   * differ only in the command that reproduces them, so they are two stages, not one.
+   */
+  const handshakeFailure = (kind: 'tls' | 'starttls', detail: string): MailError =>
+    sendFailed({
+      driver: 'smtp',
+      stage: kind,
+      detail: `the TLS handshake with ${target.host} failed: ${detail}`,
+      retryable: false,
+      fix:
+        `check the certificate and protocol the host offers: openssl s_client ` +
+        `${kind === 'starttls' ? '-starttls smtp ' : ''}-connect ${target.host}:${target.port}`,
+    });
+
+  /** Outside a handshake, a dead socket really is transient — a reset, a rate limit, a restart. */
+  const socketFailure = (detail: string): MailError =>
+    handshake === undefined
+      ? sendFailed({
+          driver: 'smtp',
+          stage: 'data',
+          detail,
+          retryable: true,
+          fix: `read the SMTP server log on ${target.host} — the job will retry automatically`,
+        })
+      : handshakeFailure(handshake, detail);
+
+  const failDrain = (error: MailError): void => {
+    const waiter = draining;
+    draining = undefined;
+    waiter?.reject(error);
+  };
+
+  /** What an ended socket means, in one place: `close` and `end` differ only in their wording. */
+  const died = (detail: string): void => {
+    // A write parked for `drain` can never get one from a socket that is gone; failing it here is
+    // the difference between an immediate error and burning the whole deadline first.
+    if (draining !== undefined) failDrain(socketFailure(detail));
+    // EOF inside a handshake window is a refused handshake, not the clean end of a conversation.
+    if (handshake !== undefined) queue.fail(socketFailure(detail));
+    else queue.end();
+  };
+
+  const handlers: SocketHandlers = {
+    data: (_socket, data) => {
+      handshake = undefined;
+      queue.push(decoder.decode(data));
+    },
+    close: () => died('the socket closed'),
+    end: () => died('the server half-closed the socket'),
+    drain: () => {
+      const waiter = draining;
+      draining = undefined;
+      waiter?.resolve();
+    },
+    error: (_socket, error) => {
+      const failure = socketFailure(error.message);
+      failDrain(failure);
+      queue.fail(failure);
+    },
+  };
+
+  const opening = runtime.connect({
+    hostname: target.host,
+    port: target.port,
+    tls: target.tls,
+    socket: handlers,
+  });
+
+  return opening.then((opened): SmtpStream => {
+    let socket = opened;
+
+    const waitForDrain = (): Promise<void> =>
+      new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          draining = undefined;
+          reject(
+            sendFailed({
+              driver: 'smtp',
+              stage: 'data',
+              detail: `the socket stopped accepting bytes for ${target.timeoutMs}ms`,
+              retryable: true,
+              fix: 'pass timeoutMs: 60_000 to createSmtpDriver() in app.config.ts',
+            }),
+          );
+        }, target.timeoutMs);
+        draining = {
+          resolve: () => {
+            clearTimeout(timer);
+            resolve();
+          },
+          reject: (error) => {
+            clearTimeout(timer);
+            reject(error);
+          },
+        };
+      });
+
+    const flush = async (bytes: Uint8Array): Promise<void> => {
+      let rest = bytes;
+      while (rest.length > 0) {
+        const written = socket.write(rest);
+        if (written >= rest.length) return;
+        // A negative count is a refusal, not backpressure: no `drain` follows a socket that cannot
+        // emit one, so waiting for it would park this write until the deadline and call a closed
+        // connection a slow one.
+        if (written < 0) throw socketFailure(`the socket refused a ${rest.length}-byte write`);
+        // Backpressure: a 200KB message does not fit one buffer. Wait for `drain`, bounded by the
+        // same deadline as a read so a stalled socket cannot hold a worker slot forever.
+        if (written > 0) rest = rest.subarray(written);
+        await waitForDrain();
+      }
+    };
+
+    return {
+      read: () => queue.read(),
+      write: (data: string) => flush(encoder.encode(data)),
+      startTls: () => {
+        // Bun hands back `[raw, tls]`; every later read and write goes through the second one, and
+        // the handlers are re-registered because the upgraded socket is a different object.
+        const upgraded = socket.upgradeTLS({
+          tls: { serverName: target.host },
+          socket: handlers,
+        })[1];
+        if (upgraded === undefined) {
+          return Promise.reject(
+            sendFailed({
+              driver: 'smtp',
+              stage: 'starttls',
+              detail: 'the runtime returned no TLS socket for the STARTTLS upgrade',
+              retryable: false,
+              fix: 'upgrade the runtime: bun upgrade   # STARTTLS needs bun >= 1.3',
+            }),
+          );
+        }
+        socket = upgraded;
+        // Writes made now are buffered by the runtime until the handshake completes, so the client
+        // may send EHLO straight away — what changes is how a failure from here is reported.
+        handshake = 'starttls';
+        return Promise.resolve();
+      },
+      close: () => {
+        socket.end();
+      },
+    };
+  });
+}