tina4-nodejs 3.13.137 → 3.13.139

package/packages/core/src/graphql.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 GraphQL — Zero-dependency GraphQL engine.
  *
@@ -62,12 +70,14 @@ const TOKEN_PATTERNS: Array<[string, RegExp]> = [
   ["EQUALS", /=/y],
   ["AT", /@/y],
   ["DOLLAR", /\$/y],
-  ["COMMA", /,/y],
   ["STRING", /"(?:[^"\\]|\\.)*"/y],
   ["NUMBER", /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y],
   ["BOOL", /\b(?:true|false)\b/y],
   ["NULL", /\bnull\b/y],
   ["NAME", /[_a-zA-Z]\w*/y],
+  // GraphQL spec 2.1.7: a comma is insignificant, exactly like whitespace. It
+  // used to be a COMMA token that only the argument and variable loops
+  // consumed, so a comma between fields or list values was a parse error.
   ["SKIP", /[\s,]+/y],
   ["COMMENT", /#[^\n]*/y],
 ];
@@ -165,10 +175,17 @@ type ParsedDefinition = ParsedOperation | ParsedFragment;
 class Parser {
   private tokens: Token[];
   private pos: number;
+  // F2: bound the parser's own recursion. A deeply nested query
+  // ("{a{a{a...}}}") otherwise recurses in parseSelectionSet until the call
+  // stack overflows — BEFORE the execution-time depth guard can run. Reusing
+  // TINA4_GRAPHQL_MAX_DEPTH keeps parse and execution on one bound.
+  private depth = 0;
+  private readonly maxDepth: number;
 
   constructor(tokens: Token[]) {
     this.tokens = tokens;
     this.pos = 0;
+    this.maxDepth = graphqlMaxDepth();
   }
 
   peek(): Token | null {
@@ -262,6 +279,18 @@ class Parser {
   }
 
   private parseSelectionSet(): ParsedSelection[] {
+    this.depth++;
+    if (this.maxDepth > 0 && this.depth > this.maxDepth) {
+      throw new Error(`Query exceeds maximum depth of ${this.maxDepth}`);
+    }
+    try {
+      return this.parseSelectionSetInner();
+    } finally {
+      this.depth--;
+    }
+  }
+
+  private parseSelectionSetInner(): ParsedSelection[] {
     this.expect("LBRACE");
     const selections: ParsedSelection[] = [];
     while (!this.match("RBRACE")) {
@@ -331,7 +360,6 @@ class Parser {
       const name = this.expect("NAME").value;
       this.expect("COLON");
       args[name] = this.parseValue();
-      this.match("COMMA");
     }
     return args;
   }
@@ -416,7 +444,6 @@ class Parser {
         defaultVal = this.parseValue();
       }
       defs.push({ name, type: typeName, default: defaultVal });
-      this.match("COMMA");
     }
     return defs;
   }
@@ -480,6 +507,24 @@ export function graphqlMaxDepth(): number {
   return Number.isNaN(n) ? 50 : n;
 }
 
+/**
+ * F2: maximum number of expanded selection nodes a single query may request.
+ * The depth guard bounds NESTING but not WIDTH: a fragment that spreads another
+ * fragment many times (a "fragment bomb") stays shallow while expanding to
+ * millions of fields, and a query with thousands of aliases of one field is not
+ * deep at all. This budget bounds the expanded selection tree (fragments
+ * expanded, aliases counted) so both are rejected before any resolver runs.
+ * `TINA4_GRAPHQL_MAX_NODES` overrides the default (1000); `<= 0` disables it.
+ */
+export function graphqlMaxNodes(): number {
+  const raw = (process.env.TINA4_GRAPHQL_MAX_NODES ?? "1000").trim();
+  const n = parseInt(raw, 10);
+  return Number.isNaN(n) ? 1000 : n;
+}
+
+/** Thrown when a query's expanded selection count exceeds the node budget (F2). */
+class ComplexityError extends Error {}
+
 // ── GraphQL Engine ───────────────────────────────────────────
 
 export class GraphQL {
@@ -507,6 +552,13 @@ export class GraphQL {
    */
   public maxDepth: number = graphqlMaxDepth();
 
+  /**
+   * Maximum expanded selection nodes per query (from `TINA4_GRAPHQL_MAX_NODES`,
+   * default 1000; `<= 0` disables). Bounds query WIDTH — fragment bombs and
+   * alias explosions — which the depth guard does not. See {@link graphqlMaxNodes}.
+   */
+  public maxNodes: number = graphqlMaxNodes();
+
   /**
    * Decorator-style resolver registration.
    *
@@ -684,6 +736,20 @@ export class GraphQL {
     }
 
     const op = operations[0];
+
+    // F2: reject an over-complex query (fragment bomb / alias explosion) before
+    // any resolver runs.
+    if (this.maxNodes > 0) {
+      try {
+        this.assertComplexity(op.selections, fragments);
+      } catch (e: unknown) {
+        if (e instanceof ComplexityError) {
+          return { data: null, errors: [{ message: e.message }] };
+        }
+        throw e;
+      }
+    }
+
     const resolvers = op.operation === "query" ? this.queries : this.mutations;
 
     // Apply variable defaults
@@ -715,6 +781,40 @@ export class GraphQL {
    * instead of recursing until the interpreter stack overflows. Top-level
    * starts at depth 1; `maxDepth <= 0` disables the guard.
    */
+  /**
+   * Count the expanded selection nodes, throwing {@link ComplexityError} past
+   * `maxNodes` (F2). Fragment spreads are expanded (so a fragment bomb is
+   * counted, not the small unexpanded document) and every field — including
+   * each alias — counts once. The count is capped by `maxNodes` and the walk by
+   * `maxDepth`, so a circular fragment trips the budget instead of looping and
+   * the check itself can never cost more than the budget.
+   */
+  private assertComplexity(
+    selections: ParsedSelection[],
+    fragments: Map<string, ParsedFragment>,
+  ): void {
+    const depthCap = this.maxDepth > 0 ? this.maxDepth : 1000;
+    let count = 0;
+    const walk = (sels: ParsedSelection[], depth: number): void => {
+      if (depth > depthCap) return;
+      for (const sel of sels) {
+        count++;
+        if (count > this.maxNodes) {
+          throw new ComplexityError(`Query exceeds maximum complexity of ${this.maxNodes} nodes`);
+        }
+        if (sel.kind === "fragment_spread") {
+          const frag = fragments.get(sel.name);
+          if (frag) walk(frag.selections, depth + 1);
+        } else if (sel.kind === "inline_fragment") {
+          walk(sel.selections, depth + 1);
+        } else if (sel.kind === "field" && sel.selections) {
+          walk(sel.selections, depth + 1);
+        }
+      }
+    };
+    walk(selections, 1);
+  }
+
   private async resolveSelectionsInto(
     selections: ParsedSelection[],
     resolvers: Map<string, QueryConfig>,
@@ -930,7 +1030,9 @@ export class GraphQL {
       className,
       (root, args) => {
         const db = getDb();
-        const fieldNames = Object.keys(args);
+        // Declared fields only: the executor passes every argument the query
+        // names, declared or not, and each one becomes a column (ADR-0069).
+        const fieldNames = Object.keys(args).filter((k) => Object.hasOwn(mutationArgs, k));
         const placeholders = fieldNames.map(() => "?");
         const values = fieldNames.map((f) => args[f]);
 
@@ -960,7 +1062,8 @@ export class GraphQL {
         const values: unknown[] = [];
 
         for (const [k, v] of Object.entries(args)) {
-          if (k !== "id") {
+          // Declared fields only (see create above).
+          if (k !== "id" && Object.hasOwn(mutationArgs, k)) {
             setClauses.push(`"${k}" = ?`);
             values.push(v);
           }

package/packages/core/src/health.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { RouteDefinition, RouteHandler } from "./types.js";
 
 /** Server start time, set when health route is created */

package/packages/core/src/htmlElement.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Programmatic HTML builder — avoids string concatenation.
  *

package/packages/core/src/i18n.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 // Tina4 i18n — Internationalization and localization, zero dependencies.
 // Load JSON translation files, support nested keys, parameter substitution, locale fallback.
 

package/packages/core/src/index.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 export type {
   Tina4Request,
   Tina4Response,
@@ -82,6 +90,7 @@ export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from
 export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, sweep, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api, ApiStreamError, parseLineStream, parseSseStream } from "./api.js";
+export { guardUrl, isBlockedAddress, allowPrivateRequests, SsrfError, ALLOW_PRIVATE_ENV } from "./ssrf.js";
 export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions, StreamOptions, SseEvent } from "./api.js";
 export { Context, defaultContext, existingContext, fts5Supported, _sharedContexts } from "./context/index.js";
 export type { SearchHit } from "./context/index.js";

package/packages/core/src/job.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 Queue Job — a single queue job with lifecycle methods.
  */
@@ -39,6 +47,7 @@ export type QueueJob = JobData & JobLifecycle;
 
 export interface JobQueueBridge {
   _failJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
+  _rejectJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
   _retryJob(topic: string, job: QueueJob, delaySeconds?: number): void;
   _completeJob(topic: string, job: QueueJob): void;
   getMaxRetries(): number;
@@ -66,7 +75,13 @@ export function createJob(data: JobData, queue: JobQueueBridge): QueueJob {
       queue._failJob(job.topic, job, reason, queue.getMaxRetries());
     },
     reject(reason = "") {
-      job.fail(reason);
+      // Reject permanently — dead-letter NOW, no retry (ADR-0023). Distinct
+      // from fail(): fail() retries until maxRetries is spent; reject() is for
+      // a message the consumer KNOWS is poison and sends it straight to the
+      // dead-letter store. Was a literal alias for fail() before 3.13.139.
+      job.status = "dead";
+      job.error = reason;
+      queue._rejectJob(job.topic, job, reason, queue.getMaxRetries());
     },
     retry(delaySeconds?: number) {
       queue._retryJob(job.topic, job, delaySeconds);

package/packages/core/src/logger.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import {
   appendFileSync,
   closeSync,

package/packages/core/src/mcp.test.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Unit tests for the MCP (Model Context Protocol) implementation.
  * Run with: npx tsx packages/core/src/mcp.test.ts

package/packages/core/src/mcp.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 // Tina4 MCP Server — Model Context Protocol for AI tool integration.
 //
 // Built-in MCP server for dev tools + developer API for custom MCP servers.
@@ -230,7 +238,9 @@ function envTruthy(val: string | undefined): boolean {
  * Python master parity: tina4_python.mcp.is_loopback.
  */
 export function isLoopback(ip: string | undefined | null): boolean {
-  if (ip == null || ip === "") return true;
+  // An empty or missing peer is UNKNOWN and is not loopback: a runtime path
+  // that lost its socket address must fail closed (ADR-0079 s4).
+  if (ip == null || ip === "") return false;
   let addr = ip.trim().toLowerCase();
   if (addr.startsWith("::ffff:")) addr = addr.slice(7);
   return addr === "::1" || addr === "localhost" || addr.startsWith("127.");

package/packages/core/src/messenger.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 Messenger — SMTP email client using Node.js built-in modules only.
  *
@@ -32,15 +40,80 @@ import { isTruthy } from "./dotenv.js";
 import { DevMailbox } from "./devMailbox.js";
 import { Log } from "./logger.js";
 
+// ── Transport security (ADR-0071) ───────────────────────────
+//
+// `encryption` means what it says. Port 465 is always implicit TLS; `ssl` is
+// implicit TLS on ANY port; `tls` / `starttls` upgrade with STARTTLS and FAIL
+// when the server does not offer it; `none` never upgrades. An unknown value
+// is refused when the Messenger is built, so a typo never means cleartext.
+//
+// Every TLS connection verifies the certificate and the host name. There is
+// no Tina4 switch to turn that off (TINA4_MAIL_TLS_INSECURE is withdrawn);
+// `rejectUnauthorized: true` is passed explicitly so NODE_TLS_REJECT_UNAUTHORIZED=0
+// cannot turn it off either. Trust a private CA the standard Node way:
+// NODE_EXTRA_CA_CERTS=/path/ca.pem.
+
+const MAIL_ENCRYPTION_VALUES = ["ssl", "tls", "starttls", "none"];
+
+/** Trim + lowercase an encryption setting, refusing anything that is not a known value. */
+function normaliseEncryption(value: string, kind: "mail" | "IMAP"): string {
+  const normalised = value.trim().toLowerCase();
+  if (!MAIL_ENCRYPTION_VALUES.includes(normalised)) {
+    throw new Error(`Unknown ${kind} encryption '${value}'. Valid values: ${MAIL_ENCRYPTION_VALUES.join(", ")}.`);
+  }
+  return normalised;
+}
+
+type SmtpTransport = "implicit_tls" | "starttls" | "plain";
+
+/** Matches Python's smtplib timeouts: 30 s for a send, 10 s for a connection check. */
+const SMTP_SEND_TIMEOUT_MS = 30_000;
+const SMTP_CHECK_TIMEOUT_MS = 10_000;
+
 /**
- * TLS certificate validation defaults to SECURE (rejectUnauthorized: true).
- * Set TINA4_MAIL_TLS_INSECURE=true to disable validation for dev / self-signed
- * certificates ONLY — never in production. Previously this was hard-coded to
- * `rejectUnauthorized: false`, silently disabling certificate validation for
- * every TLS connection (a man-in-the-middle risk).
+ * Give a socket an idle timeout that fails it with a clear error. Without one a
+ * client that waits for a greeting the server never sends (a plaintext client
+ * on a TLS-only port) hangs forever.
  */
-function tlsRejectUnauthorized(): boolean {
-  return !isTruthy(process.env.TINA4_MAIL_TLS_INSECURE);
+function failOnIdle<T extends net.Socket>(socket: T, timeoutMs: number, what: string): T {
+  socket.setTimeout(timeoutMs, () => {
+    socket.destroy(new Error(`${what} timed out after ${timeoutMs / 1000}s`));
+  });
+  return socket;
+}
+
+/** Open a verified TLS connection (implicit TLS), or upgrade `socket` (STARTTLS). */
+function connectVerifiedTls(host: string, port: number, socket?: net.Socket): Promise<tls.TLSSocket> {
+  const secureSocket = tls.connect({
+    host,
+    port,
+    socket,
+    servername: net.isIP(host) ? undefined : host,
+    rejectUnauthorized: true,
+  });
+  return new Promise((resolve, reject) => {
+    secureSocket.once("secureConnect", () => {
+      secureSocket.removeListener("error", reject);
+      resolve(secureSocket);
+    });
+    secureSocket.once("error", reject);
+  });
+}
+
+function connectPlain(host: string, port: number): Promise<net.Socket> {
+  const socket = net.createConnection({ host, port });
+  return new Promise((resolve, reject) => {
+    socket.once("connect", () => {
+      socket.removeListener("error", reject);
+      resolve(socket);
+    });
+    socket.once("error", reject);
+  });
+}
+
+/** Does this EHLO reply advertise the STARTTLS extension? */
+function offersStarttls(ehloReply: string): boolean {
+  return /^\d{3}[ -]STARTTLS\b/im.test(ehloReply);
 }
 
 /**
@@ -384,7 +457,6 @@ export class Messenger {
   private fromAddress: string;
   private fromName: string;
   private encryption: string;
-  private useTls: boolean;
   /** Whether an SMTP host was actually configured (see the constructor). */
   private smtpConfigured: boolean = false;
   /** The local mailbox, present only when this messenger captures. */
@@ -421,17 +493,18 @@ export class Messenger {
       ?? process.env.TINA4_MAIL_FROM_NAME
       ?? "";
 
-    // Encryption: constructor > .env > backward-compat useTls > default "tls"
-    const envEncryption = options?.encryption
+    // Encryption: constructor > .env > backward-compat useTls > default "tls".
+    // A configured value is validated (ADR-0071): an unknown one, an empty one
+    // included, raises here rather than sending in cleartext later.
+    const configuredEncryption = options?.encryption
       ?? process.env.TINA4_MAIL_ENCRYPTION;
-    if (envEncryption) {
-      this.encryption = envEncryption.toLowerCase();
+    if (configuredEncryption !== undefined) {
+      this.encryption = normaliseEncryption(configuredEncryption, "mail");
     } else if (options?.useTls !== undefined) {
       this.encryption = options.useTls ? "tls" : "none";
     } else {
       this.encryption = "tls";
     }
-    this.useTls = ["tls", "starttls"].includes(this.encryption);
 
     this.imapHost = options?.imapHost
       ?? process.env.TINA4_MAIL_IMAP_HOST
@@ -448,10 +521,23 @@ export class Messenger {
     // IMAP encryption — separate from SMTP encryption because IMAP almost
     // always uses port 993 + implicit TLS while SMTP toggles between 587
     // (STARTTLS) and 465 (implicit TLS). Default is "tls" to match
-    // industry-standard IMAPS port 993 behaviour.
-    this.imapEncryption = (options?.imapEncryption
+    // industry-standard IMAPS port 993 behaviour. "tls" and "ssl" are implicit
+    // TLS, "starttls" is a REQUIRED STARTTLS upgrade, "none" is plaintext; any
+    // other value raises here.
+    this.imapEncryption = normaliseEncryption(options?.imapEncryption
       ?? process.env.TINA4_MAIL_IMAP_ENCRYPTION
-      ?? "tls").toLowerCase();
+      ?? "tls", "IMAP");
+  }
+
+  /**
+   * How the SMTP connection is secured (ADR-0071 section 1). Port 465 is the
+   * implicit-TLS submission port whatever the setting; `ssl` is implicit TLS on
+   * any port; `tls` / `starttls` upgrade with a required STARTTLS; `none` is
+   * plaintext on purpose.
+   */
+  private smtpTransport(): SmtpTransport {
+    if (this.port === 465 || this.encryption === "ssl") return "implicit_tls";
+    return this.encryption === "none" ? "plain" : "starttls";
   }
 
   /**
@@ -507,21 +593,12 @@ export class Messenger {
     return { toList, ccList, bccList, allRecipients };
   }
 
-  private async connectSmtpSocket(): Promise<SmtpSocket> {
-    if (this.port === 465) {
-      const socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
-      await new Promise<void>((resolve, reject) => {
-        socket.once("secureConnect", resolve);
-        socket.once("error", reject);
-      });
-      return socket;
+  private async connectSmtpSocket(timeoutMs: number): Promise<SmtpSocket> {
+    const what = `SMTP connection to ${this.host}:${this.port}`;
+    if (this.smtpTransport() === "implicit_tls") {
+      return failOnIdle(await connectVerifiedTls(this.host, this.port), timeoutMs, what);
     }
-    const socket = net.createConnection({ host: this.host, port: this.port });
-    await new Promise<void>((resolve, reject) => {
-      socket.once("connect", resolve);
-      socket.once("error", reject);
-    });
-    return socket;
+    return failOnIdle(await connectPlain(this.host, this.port), timeoutMs, what);
   }
 
   private async requireSmtpResponse(socket: SmtpSocket, command: string, expected: number, failure: string): Promise<{ code: number; text: string }> {
@@ -530,20 +607,23 @@ export class Messenger {
     return response;
   }
 
-  private async openSmtpSession(): Promise<SmtpSocket> {
-    let socket = await this.connectSmtpSocket();
+  /**
+   * Connect, read the greeting, EHLO, and - for the STARTTLS transport - upgrade.
+   * STARTTLS is REQUIRED: when the server does not offer it the session fails
+   * here, before AUTH or MAIL FROM is ever sent.
+   */
+  private async openSmtpSession(timeoutMs: number = SMTP_SEND_TIMEOUT_MS): Promise<SmtpSocket> {
+    let socket = await this.connectSmtpSocket(timeoutMs);
     try {
       await this.requireSmtpResponse(socket, "", 220, "SMTP greeting failed");
       const ehlo = await this.requireSmtpResponse(socket, `EHLO ${this.host}`, 250, "EHLO failed");
-      if (this.useTls && this.port !== 465 && ehlo.text.includes("STARTTLS")) {
+      if (this.smtpTransport() === "starttls") {
+        if (!offersStarttls(ehlo.text)) {
+          throw new SmtpCommandError(`STARTTLS was requested but ${this.host}:${this.port} does not offer it`);
+        }
         await this.requireSmtpResponse(socket, "STARTTLS", 220, "STARTTLS failed");
-        const plainSocket = socket as net.Socket;
-        const secureSocket = tls.connect({ socket: plainSocket, host: this.host, rejectUnauthorized: tlsRejectUnauthorized() });
-        await new Promise<void>((resolve, reject) => {
-          secureSocket.once("secureConnect", resolve);
-          secureSocket.once("error", reject);
-        });
-        socket = secureSocket;
+        socket = failOnIdle(await connectVerifiedTls(this.host, this.port, socket as net.Socket), timeoutMs,
+          `SMTP connection to ${this.host}:${this.port}`);
         await this.requireSmtpResponse(socket, `EHLO ${this.host}`, 250, "EHLO after STARTTLS failed");
       }
       return socket;
@@ -679,42 +759,19 @@ export class Messenger {
    * Test the SMTP connection without sending an email.
    */
   async testConnection(): Promise<{ success: boolean; message: string }> {
+    // Same transport rules as send(): implicit TLS / required STARTTLS / plain,
+    // certificates verified.
+    let socket: SmtpSocket | null = null;
     try {
-      let socket: net.Socket | tls.TLSSocket;
-
-      if (this.port === 465) {
-        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
-        await new Promise<void>((resolve, reject) => {
-          socket.once("secureConnect", resolve);
-          socket.once("error", reject);
-        });
-      } else {
-        socket = net.createConnection({ host: this.host, port: this.port });
-        await new Promise<void>((resolve, reject) => {
-          socket.once("connect", resolve);
-          socket.once("error", reject);
-        });
-      }
-
-      const greeting = await readResponse(socket);
-      if (greeting.code !== 220) {
-        socket.destroy();
-        return { success: false, message: `SMTP greeting failed: ${greeting.text}` };
-      }
-
-      const ehlo = await sendCommand(socket, `EHLO ${this.host}`);
-      if (ehlo.code !== 250) {
-        socket.destroy();
-        return { success: false, message: `EHLO failed: ${ehlo.text}` };
-      }
-
+      socket = await this.openSmtpSession(SMTP_CHECK_TIMEOUT_MS);
       await sendCommand(socket, "QUIT");
-      socket.destroy();
-
       return { success: true, message: `Connected to ${this.host}:${this.port}` };
     } catch (err) {
+      if (err instanceof SmtpCommandError) return { success: false, message: err.message };
       const errMsg = err instanceof Error ? err.message : String(err);
       return { success: false, message: `Connection failed: ${errMsg}` };
+    } finally {
+      socket?.destroy();
     }
   }
 
@@ -731,28 +788,28 @@ export class Messenger {
 
     let socket: net.Socket | tls.TLSSocket;
 
-    // Honour TINA4_MAIL_IMAP_ENCRYPTION when set; otherwise infer from port.
-    // "tls" / "ssl" → implicit TLS connect; anything else → plain connect.
-    const useTls = this.imapEncryption === "tls" || this.imapEncryption === "ssl"
-      || (this.imapEncryption === "" && this.imapPort === 993);
-
-    if (useTls) {
-      socket = tls.connect({ host: this.imapHost, port: this.imapPort, rejectUnauthorized: tlsRejectUnauthorized() });
-      await new Promise<void>((resolve, reject) => {
-        socket.once("secureConnect", resolve);
-        socket.once("error", reject);
-      });
+    // "tls" / "ssl" → implicit TLS; "starttls" → plain connect, then a REQUIRED
+    // STARTTLS upgrade before LOGIN; "none" → plaintext. (Validated in the constructor.)
+    if (this.imapEncryption === "tls" || this.imapEncryption === "ssl") {
+      socket = await connectVerifiedTls(this.imapHost, this.imapPort);
     } else {
-      socket = net.createConnection({ host: this.imapHost, port: this.imapPort });
-      await new Promise<void>((resolve, reject) => {
-        socket.once("connect", resolve);
-        socket.once("error", reject);
-      });
+      socket = await connectPlain(this.imapHost, this.imapPort);
     }
 
     // Read server greeting
     await imapReadLine(socket);
 
+    if (this.imapEncryption === "starttls") {
+      try {
+        await imapCommand(socket, "STARTTLS");
+      } catch {
+        socket.destroy();
+        throw new MessengerConnectionError(
+          `STARTTLS was requested but ${this.imapHost}:${this.imapPort} does not offer it`);
+      }
+      socket = await connectVerifiedTls(this.imapHost, this.imapPort, socket);
+    }
+
     // Login
     if (this.imapUser && this.imapPass) {
       const loginResp = await imapCommand(socket, `LOGIN ${imapQuote(this.imapUser)} ${imapQuote(this.imapPass)}`);