haraka-tls 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+### Unreleased
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haraka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# haraka-tls
+
+Modern TLS support for [Haraka](https://haraka.github.io).
+
+## Features
+
+- **No `openssl` subprocess** — certificate parsing uses Node's built-in
+  `crypto.X509Certificate`
+- **No global state** — every API returns plain objects; callers own them
+- **STARTTLS upgrades** — `PluggableStream` wraps a raw TCP socket and upgrades it to TLS in-place without changing the reference held by the connection handler
+- **SNI** — `ContextStore` manages per-hostname `SecureContext` objects and generates a ready-to-use SNI callback
+- **Hot reload** — `ContextStore.invalidate()` clears all contexts; call `build()` again to pick up new certificates
+- **Outbound TLS-NO-GO** — optional Redis cache that skips TLS for hosts that have previously failed negotiation
+
+## Installation
+
+```sh
+npm install haraka-tls
+```
+
+`haraka-plugin-redis` is an optional peer dependency, required only when the
+`[redis] disable_for_failed_hosts` feature is enabled.
+
+## Quick start
+
+```js
+const {
+  load_config,
+  load_dir,
+  ContextStore,
+  createServer,
+  connect,
+  OutboundTLS,
+} = require('haraka-tls')
+
+const config = require('haraka-config').module_config('/path/to/haraka/config')
+
+// Load tls.ini
+const tls_cfg = load_config(config)
+
+// Load per-hostname certs from config/tls/
+const certs = await load_dir(config, 'tls')
+
+// Build TLS contexts
+const contexts = new ContextStore()
+contexts.build(tls_cfg.main, certs)
+
+// Inbound server
+const server = createServer({ contexts, cfg: tls_cfg.main }, (socket) => {
+  // socket is a PluggableStream
+  socket.on('data', (chunk) => { /* ... */ })
+
+  // Upgrade to TLS when the client sends STARTTLS
+  socket.upgrade((verified, verifyErr, peerCert, cipher) => {
+    console.log('TLS established, cipher:', cipher.name)
+  })
+})
+server.listen(25)
+
+// Outbound connection
+const ob = new OutboundTLS(config)
+ob.load(tls_cfg)
+
+const mx = { exchange: 'mail.example.com' }
+const socket = connect({ host: mx.exchange, port: 25 })
+socket.on('connect', () => {
+  // After the remote server sends 250 STARTTLS:
+  socket.upgrade(ob.get_tls_options(mx), (verified, verifyErr, peerCert, cipher) => {
+    console.log('Outbound TLS established')
+  })
+})
+```
+
+## API
+
+### `load_config(cfg_module)` → `object`
+
+Reads `tls.ini` via the given `haraka-config` module and returns a normalised
+config object. Each call returns a fresh plain object — safe to mutate.
+
+```js
+const { load_config } = require('haraka-tls')
+const tls_cfg = load_config(config)
+// tls_cfg.main, tls_cfg.outbound, tls_cfg.redis, tls_cfg.no_tls_hosts, …
+```
+
+### `parse_pem(pem)` → `object`
+
+Parses a PEM string and extracts private key(s), the certificate chain,
+hostnames (CN + SANs), and the leaf certificate's expiry date.
+
+```js
+const { parse_pem } = require('haraka-tls')
+const { keys, chain, names, expire } = parse_pem(fs.readFileSync('cert.pem', 'utf8'))
+```
+
+### `load_dir(cfg_module, dir_name)` → `Promise<Map>`
+
+Scans a config directory for `.pem` files, pairs keys with certificates by
+hostname, and returns a `Map<string, { key: Buffer, cert: Buffer, file: string }>`.
+
+```js
+const { load_dir } = require('haraka-tls')
+const certs = await load_dir(config, 'tls')  // reads config/tls/*.pem
+```
+
+### `ContextStore`
+
+Manages a set of `tls.SecureContext` objects keyed by hostname. The special key
+`'*'` is the fallback used by SNI when no hostname-specific context exists.
+
+```js
+const { ContextStore } = require('haraka-tls')
+
+const store = new ContextStore()
+store.build(base_opts, certs)        // builds '*' + per-hostname contexts
+store.get('mail.example.com')        // returns context, falls back to '*'
+store.sni_callback()                 // returns (servername, cb) => void
+store.invalidate()                   // clears all contexts (force reload)
+```
+
+### `build_context(opts)` → `tls.SecureContext`
+
+Thin wrapper around `tls.createSecureContext(opts)`. Throws on invalid material
+so callers can handle errors explicitly.
+
+### `createServer(tls_state, connection_handler)` → `net.Server`
+
+Creates a `net.Server` whose connections are wrapped in `PluggableStream`. Each
+socket gains an `.upgrade(cb)` method for inbound STARTTLS.
+
+```js
+const { createServer } = require('haraka-tls')
+
+const server = createServer({ contexts, cfg: tls_cfg.main }, (socket) => {
+  socket.upgrade((verified, verifyErr, peerCert, cipher) => { /* … */ })
+})
+```
+
+### `connect(conn_opts)` → `PluggableStream`
+
+Creates a plain TCP socket wrapped in `PluggableStream`. The returned socket has
+an `.upgrade(tls_opts, cb)` method for outbound STARTTLS. Also exported as
+`createConnection` for drop-in compatibility.
+
+```js
+const { connect } = require('haraka-tls')
+
+const socket = connect({ host: 'mail.example.com', port: 25 })
+socket.on('connect', () => {
+  socket.upgrade(tls_opts, (verified, verifyErr, peerCert, cipher) => { /* … */ })
+})
+```
+
+### `PluggableStream`
+
+An `EventEmitter` that wraps a `net.Socket` or `tls.TLSSocket` and supports
+transparent STARTTLS upgrade. The reference held by the caller does not change
+when the underlying socket is swapped.
+
+Forwarded events: `data`, `connect`, `secureConnect`, `secure`, `end`, `close`,
+`drain`, `error`, `timeout`.
+
+```js
+socket.isEncrypted()   // → boolean
+socket.isSecure()      // → boolean (encrypted + authorized)
+socket.write(data)
+socket.end()
+socket.destroy()
+socket.setTimeout(ms)
+socket.setKeepAlive(bool)
+```
+
+### `OutboundTLS`
+
+Manages outbound TLS configuration and an optional Redis cache that disables TLS
+for hosts that have previously failed negotiation.
+
+```js
+const { OutboundTLS } = require('haraka-tls')
+
+const ob = new OutboundTLS(config)
+ob.load(tls_cfg)              // inherit from [main], resolve file paths to Buffers
+await ob.init(cb)             // connect to Redis if disable_for_failed_hosts=true
+
+const opts = ob.get_tls_options({ exchange: 'mail.example.com' })
+// opts.servername is set to the hostname (never a bare IP)
+
+ob.check_tls_nogo(host, cb_ok, cb_nogo)
+ob.mark_tls_nogo(host, cb)
+```
+
+## Configuration
+
+`tls.ini` sections understood by this package:
+
+```ini
+; [main] — inbound TLS defaults
+key             = tls_key.pem
+cert            = tls_cert.pem
+dhparam         = dhparams.pem
+ciphers         = ECDHE-RSA-AES256-GCM-SHA384:…
+minVersion      = TLSv1.2
+rejectUnauthorized = false
+requestCert     = true
+honorCipherOrder = true
+requireAuthorized[] = 465
+requireAuthorized[] = 587
+
+; [outbound] — overrides for outbound connections
+; Any key absent here falls back to [main]
+key             = outbound_key.pem
+cert            = outbound_cert.pem
+rejectUnauthorized = false
+force_tls_hosts[] = smtp.example.com
+no_tls_hosts[]  = broken.example.net
+
+; [redis] — TLS-NO-GO cache (optional)
+disable_for_failed_hosts = true
+disable_expiry  = 604800   ; seconds (default: 7 days)
+
+; [no_tls_hosts] — disable TLS for inbound connections from these hosts/CIDRs
+192.168.1.0/24
+```
+
+## Per-hostname certificates
+
+Place PEM files in `config/tls/`. Each file may contain a private key and one or
+more certificates. The CN and SAN DNS entries are used as the hostname key:
+
+```
+config/
+  tls/
+    mail.example.com.pem   ← CN=mail.example.com
+    smtp.example.com.pem   ← CN=smtp.example.com
+    _.example.net.key      ← key for wildcard (paired with example.net.crt)
+    example.net.crt
+```
+
+Filenames starting with `_` have the leading underscore replaced with `*` to
+work around Windows filesystem restrictions on wildcard filenames.
+
+## Integrating with Haraka's logger
+
+By default this package logs to `console`. To use Haraka's logger instead, call
+`set_logger()` before any other import:
+
+```js
+const tls_logger = require('haraka-tls/lib/logger')
+tls_logger.set_logger(require('./logger'))  // Haraka's logger
+
+const haraka_tls = require('haraka-tls')
+```
+
+The logger object passed to `set_logger` must implement `debug`, `info`,
+`notice`, `warn`, and `error` methods that each accept a message string.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,34 @@
+'use strict'
+
+// haraka-tls: Modern TLS support for Haraka.
+//
+// Sub-modules are intentionally independent so callers can require only what
+// they need without pulling in the entire stack.
+
+const { load: load_config } = require('./lib/config')
+const { parse_pem, load_dir } = require('./lib/certs')
+const { ContextStore, build_context } = require('./lib/context')
+const { PluggableStream, createServer, connect, createConnection } = require('./lib/socket')
+const { OutboundTLS } = require('./lib/outbound')
+
+module.exports = {
+    // Config
+    load_config,
+
+    // Certificates
+    parse_pem,
+    load_dir,
+
+    // TLS Contexts
+    ContextStore,
+    build_context,
+
+    // Sockets
+    PluggableStream,
+    createServer,
+    connect,
+    createConnection,
+
+    // Outbound
+    OutboundTLS,
+}

package/lib/certs.js

@@ -0,0 +1,135 @@
+'use strict'
+
+// Certificate parsing and directory loading.
+// Uses Node's built-in crypto.X509Certificate — no openssl subprocess needed.
+
+const { X509Certificate } = require('node:crypto')
+const path = require('node:path')
+
+const log = require('./logger')
+
+// PEM block patterns
+const KEY_RE = /(-----BEGIN (?:\w+ )?PRIVATE KEY-----[\s\S]*?-----END (?:\w+ )?PRIVATE KEY-----)/g
+const CERT_RE = /(-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----)/g
+
+/**
+ * Parse a PEM string and extract private key(s), certificate chain,
+ * hostnames (CN + SANs), and the leaf certificate's expiry date.
+ *
+ * @param  {string} pem
+ * @returns {{ keys?: string[], chain?: string[], names?: string[], expire?: Date }}
+ */
+function parse_pem(pem) {
+    const res = {}
+    if (!pem) return res
+
+    const keys = Array.from(pem.matchAll(KEY_RE), (m) => m[1])
+    if (keys.length) res.keys = keys
+
+    const chain = Array.from(pem.matchAll(CERT_RE), (m) => m[1])
+    if (!chain.length) return res
+
+    res.chain = chain
+
+    try {
+        const leaf = new X509Certificate(chain[0])
+        res.expire = new Date(leaf.validTo)
+
+        const cn_match = /CN=([^,\n]+)/.exec(leaf.subject)
+        res.names = cn_match ? [cn_match[1].trim()] : []
+
+        if (leaf.subjectAltName) {
+            for (const san of leaf.subjectAltName.split(',')) {
+                const m = /DNS:(.+)/.exec(san.trim())
+                if (m) {
+                    const name = m[1].trim()
+                    if (!res.names.includes(name)) res.names.push(name)
+                }
+            }
+        }
+    } catch (err) {
+        log.debug(`tls/certs: X509Certificate parse error: ${err.message}`)
+    }
+
+    return res
+}
+
+/**
+ * Load every PEM file in a config directory and return a Map of
+ *   hostname → { key: Buffer, cert: Buffer, file: string }
+ *
+ * Files with a key but no embedded cert have their filename used as the CN.
+ * Incomplete pairs (key without cert or vice-versa) are silently dropped.
+ * Expired certificates are logged as errors but still loaded.
+ *
+ * @param  {object} cfg_module  - haraka-config module (supports .getDir)
+ * @param  {string} dir_name    - directory name relative to config root (e.g. 'tls')
+ * @returns {Promise<Map<string, {key: Buffer, cert: Buffer, file: string}>>}
+ */
+async function load_dir(cfg_module, dir_name) {
+    const result = new Map()
+    let files
+
+    try {
+        files = await cfg_module.getDir(dir_name, { type: 'binary' })
+    } catch (err) {
+        if (err.code !== 'ENOENT') log.error(`tls/certs: load_dir ${dir_name}: ${err.message}`)
+        return result
+    }
+
+    if (!files?.length) return result
+
+    // ── Stage 1: parse every file ─────────────────────────────────────────────
+
+    const parsed = {}
+    for (const file of files) {
+        try {
+            parsed[file.path] = parse_pem(file.data.toString())
+        } catch (err) {
+            log.debug(`tls/certs: skipping ${file.path}: ${err.message}`)
+        }
+    }
+
+    log.debug(`tls/certs: parsed ${Object.keys(parsed).length} file(s) in ${dir_name}`)
+
+    // ── Stage 2: collate by hostname ──────────────────────────────────────────
+
+    const by_name = {}
+    for (const [fp, info] of Object.entries(parsed)) {
+        if (info.expire && info.expire < new Date()) {
+            log.error(`tls/certs: ${fp} expired on ${info.expire.toUTCString()}`)
+        }
+
+        // Files with a key but no cert use the base filename as the CN
+        if (!info.names) info.names = [path.parse(fp).name]
+
+        for (let name of info.names) {
+            if (name.startsWith('_')) name = name.replace('_', '*') // Windows wildcard workaround
+            by_name[name] ??= {}
+            if (!by_name[name].key && info.keys?.length) by_name[name].key = info.keys[0]
+            if (!by_name[name].cert && info.chain?.length) {
+                by_name[name].cert = info.chain[0]
+                by_name[name].file = fp
+            }
+        }
+    }
+
+    // ── Stage 3: emit complete pairs only ─────────────────────────────────────
+
+    for (const [name, entry] of Object.entries(by_name)) {
+        if (!entry.key || !entry.cert) {
+            log.debug(`tls/certs: incomplete pair for "${name}" (key=${!!entry.key} cert=${!!entry.cert}), skipping`)
+            continue
+        }
+        result.set(name, {
+            key: Buffer.from(entry.key),
+            cert: Buffer.from(entry.cert),
+            file: entry.file,
+        })
+    }
+
+    log.info(`tls/certs: loaded ${result.size} cert(s) from ${dir_name}`)
+    return result
+}
+
+module.exports = { parse_pem, load_dir }

package/lib/config.js

@@ -0,0 +1,59 @@
+'use strict'
+
+// Pure config loading — no global state, no side effects.
+// Returns a plain object that callers own and may mutate freely.
+
+const BOOLEANS = [
+    '-redis.disable_for_failed_hosts',
+
+    // Wildcards initialise the type parser but not the value
+    '*.requestCert',
+    '*.rejectUnauthorized',
+    '*.honorCipherOrder',
+    '*.requestOCSP',
+
+    // Explicitly declared so the defaults below are applied
+    '+main.requestCert',
+    '-main.rejectUnauthorized',
+    '+main.honorCipherOrder',
+    '-main.requestOCSP',
+    '-main.mutual_tls',
+]
+
+/**
+ * Load tls.ini via the given haraka-config module and return a normalised
+ * config object.  Calling load() twice with the same cfg_module is safe and
+ * cheap — each call returns a fresh plain object.
+ *
+ * @param  {object} cfg_module  - haraka-config (or module_config() result)
+ * @returns {object} Normalised TLS config
+ */
+function load(cfg_module) {
+    const raw = cfg_module.get('tls.ini', { booleans: BOOLEANS })
+
+    // Handle deprecated enableOCSPStapling alias
+    if (raw.main?.enableOCSPStapling !== undefined) {
+        raw.main.requestOCSP = raw.main.enableOCSPStapling
+        delete raw.main.enableOCSPStapling
+    }
+
+    const result = {
+        main: { ...raw.main },
+        redis: { disable_for_failed_hosts: false, ...raw.redis },
+        no_tls_hosts: raw.no_tls_hosts ?? {},
+        mutual_auth_hosts: raw.mutual_auth_hosts ?? {},
+        mutual_auth_hosts_exclude: raw.mutual_auth_hosts_exclude ?? {},
+        outbound: { ...(raw.outbound ?? {}) },
+    }
+
+    // Always arrays — avoids scattered defensive checks everywhere
+    result.main.requireAuthorized = [result.main.requireAuthorized].flat().filter(Boolean)
+    result.main.no_starttls_ports = [result.main.no_starttls_ports].flat().filter(Boolean)
+
+    if (!Array.isArray(result.outbound.no_tls_hosts)) result.outbound.no_tls_hosts = []
+    if (!Array.isArray(result.outbound.force_tls_hosts)) result.outbound.force_tls_hosts = []
+
+    return result
+}
+
+module.exports = { load }

package/lib/context.js

@@ -0,0 +1,104 @@
+'use strict'
+
+const tls = require('node:tls')
+
+const log = require('./logger')
+
+/**
+ * Build a tls.SecureContext from the given options.
+ * Throws on invalid key/cert material so callers can handle errors explicitly.
+ *
+ * @param  {object} opts - options accepted by tls.createSecureContext()
+ * @returns {tls.SecureContext}
+ */
+function build_context(opts) {
+    return tls.createSecureContext(opts)
+}
+
+/**
+ * Manages a set of TLS SecureContexts keyed by hostname.
+ *
+ * The special key '*' is the default/fallback used by SNI when no
+ * hostname-specific context exists.
+ */
+class ContextStore {
+    constructor() {
+        this._ctxs = new Map()
+    }
+
+    /** Store a context under the given name (use '*' for the default). */
+    set(name, ctx) {
+        this._ctxs.set(name, ctx)
+    }
+
+    /**
+     * Return the context for `name`, falling back to '*'.
+     * Returns undefined only when no default context has been set.
+     */
+    get(name) {
+        return this._ctxs.get(name) ?? this._ctxs.get('*')
+    }
+
+    has(name) {
+        return this._ctxs.has(name)
+    }
+
+    get size() {
+        return this._ctxs.size
+    }
+
+    /**
+     * Build contexts from a base-options object and a certs Map produced by
+     * tls/certs.load_dir().
+     *
+     * The base_opts are used for the default '*' context and as a template
+     * for per-hostname contexts (with the hostname's key/cert substituted in).
+     *
+     * @param {object}                         base_opts  - base TLS options
+     * @param {Map<string, {key, cert}>}       certs      - per-hostname material
+     */
+    build(base_opts, certs) {
+        // Default context
+        if (base_opts.key && base_opts.cert) {
+            try {
+                this.set('*', build_context(base_opts))
+                log.debug('tls/context: built default (*) context')
+            } catch (err) {
+                log.error(`tls/context: failed to build default context: ${err.message}`)
+            }
+        }
+
+        // Per-hostname contexts (inherit base opts, override key/cert)
+        for (const [name, entry] of certs) {
+            try {
+                this.set(name, build_context({ ...base_opts, key: entry.key, cert: entry.cert }))
+                log.debug(`tls/context: built context for ${name}`)
+            } catch (err) {
+                log.error(`tls/context: failed to build context for "${name}": ${err.message}`)
+            }
+        }
+    }
+
+    /**
+     * Return an SNI callback suitable for passing to tls.TLSSocket / tls.Server.
+     * Resolves to the most specific context available, falling back to '*'.
+     *
+     * @returns {Function} (servername: string, done: Function) => void
+     */
+    sni_callback() {
+        return (servername, done) => {
+            const ctx = this.get(servername)
+            if (!this._ctxs.has(servername)) {
+                log.debug(`tls/context: no context for "${servername}", using default`)
+            }
+            done(null, ctx ?? null)
+        }
+    }
+
+    /** Clear all stored contexts (e.g. to force a reload). */
+    invalidate() {
+        this._ctxs.clear()
+    }
+}
+
+module.exports = { ContextStore, build_context }

package/lib/logger.js

@@ -0,0 +1,43 @@
+'use strict'
+
+// Minimal console-based logger shim for standalone use.
+// When haraka-tls is used inside Haraka, Haraka replaces this with its own
+// logger by calling logger.set_logger(haraka_logger) before any other import.
+
+const LEVELS = ['debug', 'info', 'notice', 'warn', 'error', 'crit', 'alert', 'emerg']
+
+let _log = {
+    debug: (msg) => console.debug(msg),
+    info: (msg) => console.info(msg),
+    notice: (msg) => console.info(msg),
+    warn: (msg) => console.warn(msg),
+    error: (msg) => console.error(msg),
+}
+
+const log = {
+    debug: (msg) => _log.debug(msg),
+    info: (msg) => _log.info(msg),
+    notice: (msg) => _log.notice(msg),
+    warn: (msg) => _log.warn(msg),
+    error: (msg) => _log.error(msg),
+
+    /** Replace the backing logger (e.g. with Haraka's logger). */
+    set_logger(impl) {
+        _log = impl
+    },
+
+    /**
+     * Add log methods (logdebug, loginfo, lognotice, logwarn, logerror, …)
+     * to an object instance — mirroring Haraka's logger.add_log_methods(obj).
+     */
+    add_log_methods(obj) {
+        if (!obj) return
+        for (const level of LEVELS) {
+            const fn = `log${level}`
+            if (Object.hasOwn(obj, fn)) continue
+            obj[fn] = (msg) => _log[level] ? _log[level](msg) : _log.info(msg)
+        }
+    },
+}
+
+module.exports = log

package/lib/outbound.js

@@ -0,0 +1,128 @@
+'use strict'
+
+const net = require('node:net')
+
+const hkredis = require('haraka-plugin-redis')
+
+const logger = require('./logger')
+
+// Config keys that [outbound] inherits from [main] when not locally overridden.
+// Exhaustive: adding a new TLS option to tls.ini[main] is sufficient — no
+// code change needed here.
+const MAIN_INHERITABLE = [
+    'key', 'cert', 'dhparam',
+    'ciphers', 'minVersion',
+    'honorCipherOrder', 'requestCert', 'rejectUnauthorized',
+]
+
+/**
+ * Manages outbound TLS configuration and the Redis "TLS-NO-GO" cache that
+ * tracks remote hosts which have previously failed TLS negotiation.
+ *
+ * Usage:
+ *   const ob = new OutboundTLS(config_module)
+ *   ob.load(tls_cfg)           // tls_cfg from tls/config.load()
+ *   await ob.init(cb)          // starts Redis if enabled
+ *   const opts = ob.get_tls_options(mx)
+ */
+class OutboundTLS {
+    constructor(cfg_module) {
+        this.config = cfg_module
+        this.name = 'OutboundTLS'
+        logger.add_log_methods(this)
+    }
+
+    /**
+     * Build the outbound TLS config from the merged tls_cfg returned by
+     * tls/config.load().  Resolves file-name references to Buffers.
+     *
+     * @param  {object} tls_cfg  - result of tls/config.load()
+     * @returns {this}
+     */
+    load(tls_cfg) {
+        const cfg = { ...tls_cfg.outbound }
+        cfg.redis = tls_cfg.redis // Don't clone — may contain a live redis client
+
+        // Inherit missing options from [main]
+        for (const opt of MAIN_INHERITABLE) {
+            if (cfg[opt] !== undefined) continue
+            if (tls_cfg.main[opt] !== undefined) cfg[opt] = tls_cfg.main[opt]
+        }
+
+        // Resolve file-name strings → Buffers using the haraka-config module
+        for (const field of ['key', 'cert', 'dhparam']) {
+            if (!cfg[field]) continue
+            const filename = Array.isArray(cfg[field]) ? cfg[field][0] : cfg[field]
+            cfg[field] = this.config.get(filename, 'binary')
+        }
+
+        cfg.no_tls_hosts = Array.isArray(cfg.no_tls_hosts) ? cfg.no_tls_hosts : []
+        cfg.force_tls_hosts = Array.isArray(cfg.force_tls_hosts) ? cfg.force_tls_hosts : []
+
+        this.cfg = cfg
+        return this
+    }
+
+    /**
+     * Optionally connect to Redis for the TLS-NO-GO feature.
+     * @param {Function} cb - called when initialisation is complete
+     */
+    async init(cb) {
+        if (!this.cfg.redis?.disable_for_failed_hosts) return cb()
+        this.logdebug('Will disable outbound TLS for failing TLS hosts')
+        Object.assign(this, hkredis)
+        this.merge_redis_ini()
+        this.init_redis_plugin(cb)
+    }
+
+    /**
+     * Return a TLS options object for an outbound connection to the given MX.
+     * Sets `servername` to a hostname (never an IP) for correct SNI behaviour.
+     *
+     * @param  {{ exchange: string, from_dns?: string }} mx
+     * @returns {object}
+     */
+    get_tls_options(mx) {
+        const opts = { ...this.cfg }
+        if (net.isIP(mx.exchange)) {
+            if (mx.from_dns) opts.servername = mx.from_dns
+        } else {
+            opts.servername = mx.exchange
+        }
+        return opts
+    }
+
+    /**
+     * Check whether `host` is in the TLS-NO-GO cache.
+     * Calls cb_ok() if TLS should be attempted, cb_nogo(reason) if not.
+     */
+    check_tls_nogo(host, cb_ok, cb_nogo) {
+        if (!this.cfg.redis?.disable_for_failed_hosts) return cb_ok()
+        this.db
+            .get(`no_tls|${host}`)
+            .then((r) => (r ? cb_nogo(r) : cb_ok()))
+            .catch((err) => {
+                this.logdebug(`Redis error during check_tls_nogo: ${err}`)
+                cb_ok()
+            })
+    }
+
+    /**
+     * Record that `host` failed TLS so future connections skip it.
+     * @param {string}   host
+     * @param {Function} [cb]
+     */
+    mark_tls_nogo(host, cb) {
+        if (!this.cfg.redis?.disable_for_failed_hosts) return cb?.()
+        const expiry = this.cfg.redis.disable_expiry ?? 604800
+        this.lognotice(`TLS failed for ${host}, disabling for ${expiry}s`)
+        this.db
+            .setEx(`no_tls|${host}`, expiry, new Date().toISOString())
+            .then(() => cb?.())
+            .catch((err) => {
+                this.logerror(`Redis error during mark_tls_nogo: ${err}`)
+            })
+    }
+}
+
+module.exports = { OutboundTLS }

package/lib/socket.js

@@ -0,0 +1,250 @@
+'use strict'
+
+// Socket wrapper that supports transparent STARTTLS upgrade.
+// Used for both inbound (server) and outbound (client) connections.
+
+const net = require('node:net')
+const tls = require('node:tls')
+const { EventEmitter } = require('node:events')
+
+const log = require('./logger')
+
+// Events forwarded from the underlying socket to the wrapper
+const FORWARDED_EVENTS = ['data', 'connect', 'end', 'close', 'drain', 'timeout']
+
+/**
+ * A transparent socket wrapper that delegates reads and writes to an
+ * underlying net.Socket or tls.TLSSocket, and can be upgraded from plain
+ * TCP to TLS mid-stream (STARTTLS) without changing the reference held by
+ * the caller.
+ *
+ * Forwarded events: data, connect, secureConnect, secure, end, close, drain,
+ *                   error, timeout
+ */
+class PluggableStream extends EventEmitter {
+    constructor(socket) {
+        super()
+        this.readable = true
+        this.writable = true
+        this._timeout = 0
+        this._keepalive = false
+        this.targetsocket = null
+        this.cleartext = null
+
+        if (socket) this._attach(socket)
+    }
+
+    // ── Internal attachment/detachment ─────────────────────────────────────────
+
+    _attach(socket) {
+        this.targetsocket = socket
+
+        socket.on('data', (d) => this.emit('data', d))
+        socket.on('connect', (...a) => this.emit('connect', ...a))
+        socket.on('secureConnect', (...a) => {
+            this.emit('secureConnect', ...a)
+            this.emit('secure', ...a)
+        })
+        socket.on('secure', (...a) => this.emit('secure', ...a))
+        socket.on('end', () => {
+            this.writable = socket.writable
+            this.emit('end')
+        })
+        socket.on('close', (had_err) => {
+            this.writable = socket.writable
+            this.emit('close', had_err)
+        })
+        socket.on('drain', () => this.emit('drain'))
+        socket.once('error', (err) => {
+            this.writable = socket.writable
+            err.source = 'tls'
+            this.emit('error', err)
+        })
+        socket.on('timeout', () => this.emit('timeout'))
+
+        // Mirror address metadata onto the wrapper
+        for (const prop of ['remotePort', 'remoteAddress', 'localPort', 'localAddress']) {
+            if (socket[prop] != null) this[prop] = socket[prop]
+        }
+    }
+
+    _detach() {
+        if (!this.targetsocket) return
+        for (const event of ['data', 'secureConnect', 'secure', ...FORWARDED_EVENTS, 'error']) {
+            this.targetsocket.removeAllListeners(event)
+        }
+        // Stub out the old socket so any stray writes go nowhere
+        this.targetsocket = { write: () => false, end: () => {} }
+    }
+
+    // ── Socket interface (delegates to targetsocket) ───────────────────────────
+
+    write(data, encoding, cb) {
+        return this.targetsocket?.write(data, encoding, cb) ?? false
+    }
+
+    end(data, encoding) {
+        return this.targetsocket?.end(data, encoding)
+    }
+
+    destroy() {
+        return this.targetsocket?.destroy()
+    }
+
+    destroySoon() {
+        return this.targetsocket?.destroySoon?.()
+    }
+
+    pause() {
+        this.readable = false
+        this.targetsocket?.pause()
+    }
+
+    resume() {
+        this.readable = true
+        this.targetsocket?.resume()
+    }
+
+    setTimeout(ms) {
+        this._timeout = ms
+        return this.targetsocket?.setTimeout(ms)
+    }
+
+    setKeepAlive(bool) {
+        this._keepalive = bool
+        return this.targetsocket?.setKeepAlive(bool)
+    }
+
+    setNoDelay() {} // no-op — callers may call this
+
+    unref() {
+        return this.targetsocket?.unref()
+    }
+
+    isEncrypted() {
+        return this.targetsocket?.encrypted ?? false
+    }
+
+    isSecure() {
+        return !!(this.targetsocket?.encrypted && this.targetsocket?.authorized)
+    }
+}
+
+// ── Server factory ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a net.Server whose connections are wrapped in PluggableStream.
+ * Each socket gains an `.upgrade(cb)` method that performs the STARTTLS
+ * handshake in-place.
+ *
+ * @param {object}   tls_state              - { contexts: ContextStore, cfg: object }
+ * @param {Function} connection_handler     - called with (socket: PluggableStream)
+ * @returns {net.Server}
+ */
+function createServer(tls_state, connection_handler) {
+    const server = net.createServer((rawSocket) => {
+        const socket = new PluggableStream(rawSocket)
+
+        socket.upgrade = (upgrade_cb) => {
+            log.debug('tls/socket: upgrading inbound connection to TLS')
+
+            socket._detach()
+            rawSocket.removeAllListeners('data')
+
+            const { contexts, cfg } = tls_state
+            const tls_opts = {
+                ...cfg,
+                isServer: true,
+                server,
+                SNICallback: contexts.sni_callback(),
+            }
+
+            if (cfg.requireAuthorized?.includes(rawSocket.localPort)) {
+                tls_opts.rejectUnauthorized = true
+            }
+
+            const cleartext = new tls.TLSSocket(rawSocket, tls_opts)
+
+            cleartext.on('error', (err) => {
+                err.source = 'tls'
+                socket.emit('error', err)
+            })
+
+            cleartext.on('secure', () => {
+                log.debug('tls/socket: inbound TLS secured')
+                socket._attach(cleartext)
+                const cipher = cleartext.getCipher()
+                if (cipher) cipher.version = cleartext.getProtocol()
+                socket.emit('secure')
+                upgrade_cb?.(
+                    cleartext.authorized,
+                    cleartext.authorizationError,
+                    cleartext.getPeerCertificate(),
+                    cipher,
+                )
+            })
+
+            socket.cleartext = cleartext
+            if (socket._timeout) cleartext.setTimeout(socket._timeout)
+            cleartext.setKeepAlive(socket._keepalive)
+        }
+
+        connection_handler(socket)
+    })
+
+    return server
+}
+
+// ── Client factory ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a plain TCP socket wrapped in PluggableStream.
+ * The socket has an `.upgrade(tls_opts, cb)` method for outbound STARTTLS.
+ *
+ * @param  {object} conn_opts - options forwarded to net.connect()
+ * @returns {PluggableStream}
+ */
+function connect(conn_opts = {}) {
+    const rawSocket = net.connect(conn_opts)
+    const socket = new PluggableStream(rawSocket)
+
+    socket.upgrade = (tls_opts = {}, upgrade_cb) => {
+        log.debug('tls/socket: upgrading outbound connection to TLS')
+
+        socket._detach()
+        rawSocket.removeAllListeners('data')
+
+        const cleartext = tls.connect({ ...tls_opts, socket: rawSocket })
+
+        cleartext.on('error', (err) => {
+            if (err.reason) log.error(`tls/socket: client TLS error: ${err}`)
+            socket.emit('error', err)
+        })
+
+        cleartext.once('secureConnect', () => {
+            log.debug('tls/socket: outbound TLS secured')
+            socket._attach(cleartext)
+            const cipher = cleartext.getCipher()
+            if (cipher) cipher.version = cleartext.getProtocol()
+            upgrade_cb?.(
+                cleartext.authorized,
+                cleartext.authorizationError,
+                cleartext.getPeerCertificate(),
+                cipher,
+            )
+        })
+
+        socket.cleartext = cleartext
+        if (socket._timeout) cleartext.setTimeout(socket._timeout)
+        cleartext.setKeepAlive(socket._keepalive)
+    }
+
+    return socket
+}
+
+module.exports = {
+    PluggableStream,
+    createServer,
+    connect,
+    createConnection: connect, // alias for drop-in compat
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "haraka-tls",
+  "version": "1.0.0",
+  "description": "Haraka TLS",
+  "keywords": [
+    "haraka",
+    "tls"
+  ],
+  "homepage": "https://github.com/haraka/haraka-tls#readme",
+  "bugs": {
+    "url": "https://github.com/haraka/haraka-tls/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haraka/haraka-tls.git"
+  },
+  "license": "MIT",
+  "author": "Matt Simerson <matt@tnpi.net>",
+  "type": "commonjs",
+  "main": "index.js",
+  "files": [
+    "CHANGELOG.md",
+    "index.js",
+    "lib"
+  ],
+  "scripts": {
+    "test": "node --test test/*.js",
+    "test:coverage": "node --experimental-test-coverage --test test/*.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write .",
+    "format": "npm run prettier:fix && npm run lint:fix"
+  },
+  "dependencies": {
+    "haraka-config": "^1.5.0"
+  },
+  "optionalDependencies": {
+    "haraka-plugin-redis": "*"
+  }
+}