imapflow 1.7.8 → 2.0.1

package/dist/cjs/jp-decoder.d.ts

@@ -0,0 +1,12 @@
+import { Transform, type TransformCallback } from 'node:stream';
+export declare class JPDecoder extends Transform {
+    charset: string;
+    chunks: Buffer[];
+    chunklen: number;
+    maxBytes: number;
+    limited: boolean;
+    constructor(charset: string, maxBytes?: number | undefined);
+    _transform(chunk: Buffer | string, encoding: BufferEncoding, done: TransformCallback): void;
+    _flush(done: TransformCallback): void;
+    _destroy(err: Error | null, callback: (error: Error | null) => void): void;
+}

package/dist/cjs/jp-decoder.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JPDecoder = void 0;
+const node_stream_1 = require("node:stream");
+const encoding_japanese_1 = __importDefault(require("encoding-japanese"));
+const limited_passthrough_js_1 = require("./limited-passthrough.js");
+// A Transform stream for decoding Japanese character sets (Shift_JIS, EUC-JP, ISO-2022-JP).
+// Unlike iconv-lite which can decode incrementally, encoding-japanese requires the complete
+// input buffer for accurate charset detection and stateful decoding (especially ISO-2022-JP
+// which uses escape sequences to switch between ASCII and multi-byte modes). Therefore,
+// this stream buffers all input during _transform and performs the actual decoding in _flush.
+class JPDecoder extends node_stream_1.Transform {
+    constructor(charset, maxBytes) {
+        super();
+        this.charset = charset;
+        this.chunks = [];
+        this.chunklen = 0;
+        // Upper bound for the buffered bytes, normalized the same way LimitedPassthrough
+        // normalizes its own. The whole-input buffering defeats a downstream maxBytes limiter
+        // (nothing is emitted until _flush), so without an internal bound a server could force
+        // unbounded memory use through a caller that asked for a limited download. Excess input
+        // is truncated, mirroring the truncation a maxBytes download applies anyway.
+        this.maxBytes = (0, limited_passthrough_js_1.normalizeByteLimit)(maxBytes);
+        // Also mirroring LimitedPassthrough: true once the bound is reached and every further
+        // chunk is being discarded. The download loop reads this to stop pulling from the
+        // server, which the limiter at the tail of the pipeline cannot tell it, because nothing
+        // is emitted from here until _flush().
+        this.limited = false;
+    }
+    // Buffer all incoming chunks (up to maxBytes); no decoding happens here because
+    // Japanese charsets require the complete input for accurate conversion.
+    _transform(chunk, encoding, done) {
+        if (typeof chunk === 'string') {
+            chunk = Buffer.from(chunk, encoding);
+        }
+        if (this.chunklen + chunk.length > this.maxBytes) {
+            chunk = chunk.slice(0, Math.max(0, this.maxBytes - this.chunklen));
+        }
+        if (chunk.length) {
+            this.chunks.push(chunk);
+            this.chunklen += chunk.length;
+        }
+        if (this.chunklen >= this.maxBytes) {
+            this.limited = true;
+        }
+        done();
+    }
+    // Perform the actual charset conversion once all input has been received.
+    // Uses the encoding-japanese library to convert from the source charset to Unicode.
+    // On failure (corrupt or unrecognizable data), passes through the raw bytes unchanged.
+    _flush(done) {
+        let input = Buffer.concat(this.chunks, this.chunklen);
+        try {
+            let output = encoding_japanese_1.default.convert(input, {
+                to: 'UNICODE', // to_encoding
+                from: this.charset, // from_encoding
+                type: 'string'
+            });
+            if (typeof output === 'string') {
+                output = Buffer.from(output);
+            }
+            this.push(output);
+        }
+        catch {
+            // keep as is on errors
+            this.push(input);
+        }
+        done();
+    }
+    _destroy(err, callback) {
+        this.chunks = [];
+        this.chunklen = 0;
+        callback(err);
+    }
+}
+exports.JPDecoder = JPDecoder;

package/dist/cjs/limited-passthrough.d.ts

@@ -0,0 +1,25 @@
+import { Transform, type TransformCallback } from 'node:stream';
+/**
+ * Normalizes a byte budget for the download pipeline. Any finite positive number is honored and
+ * floored, because byte counts are integers: with a fractional bound a counter can only ever
+ * reach its floor, so a stage would never report itself full and a loop polling that flag would
+ * keep pulling forever. Anything else - 0, NaN, a non-numeric value - means "no limit".
+ *
+ * Lives here rather than in tools.ts because tools.ts imports jp-decoder.ts, which needs this.
+ *
+ * @param value - The configured budget.
+ * @returns The normalized budget, or Infinity when unbounded.
+ */
+export declare const normalizeByteLimit: (value: unknown) => number;
+export interface LimitedPassthroughOptions {
+    /** Maximum number of bytes to pass through. Anything else means "no limit" */
+    maxBytes?: number | undefined;
+}
+export declare class LimitedPassthrough extends Transform {
+    options: LimitedPassthroughOptions;
+    maxBytes: number;
+    processed: number;
+    limited: boolean;
+    constructor(options?: LimitedPassthroughOptions | undefined);
+    _transform(chunk: Buffer, encoding: BufferEncoding, done: TransformCallback): void;
+}

package/dist/cjs/limited-passthrough.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LimitedPassthrough = exports.normalizeByteLimit = void 0;
+const node_stream_1 = require("node:stream");
+/**
+ * Normalizes a byte budget for the download pipeline. Any finite positive number is honored and
+ * floored, because byte counts are integers: with a fractional bound a counter can only ever
+ * reach its floor, so a stage would never report itself full and a loop polling that flag would
+ * keep pulling forever. Anything else - 0, NaN, a non-numeric value - means "no limit".
+ *
+ * Lives here rather than in tools.ts because tools.ts imports jp-decoder.ts, which needs this.
+ *
+ * @param value - The configured budget.
+ * @returns The normalized budget, or Infinity when unbounded.
+ */
+const normalizeByteLimit = (value) => {
+    let bytes = Number(value);
+    // Math.max keeps a sub-1 budget from flooring to 0, which would read back as "no limit"
+    return Number.isFinite(bytes) && bytes > 0 ? Math.max(Math.floor(bytes), 1) : Infinity;
+};
+exports.normalizeByteLimit = normalizeByteLimit;
+// A Transform stream that passes through data up to a maximum byte limit,
+// then silently discards all subsequent chunks. Used to enforce download
+// size limits when fetching message content from the IMAP server.
+class LimitedPassthrough extends node_stream_1.Transform {
+    constructor(options) {
+        super();
+        this.options = options || {};
+        this.maxBytes = (0, exports.normalizeByteLimit)(this.options.maxBytes);
+        this.processed = 0;
+        this.limited = false;
+    }
+    _transform(chunk, encoding, done) {
+        // If the limit was already reached, discard the chunk immediately
+        if (this.limited) {
+            return done();
+        }
+        const remainingBytes = this.maxBytes - this.processed;
+        if (remainingBytes < 1) {
+            return done();
+        }
+        // Slice the chunk to fit within the remaining byte budget
+        if (chunk.length > remainingBytes) {
+            chunk = chunk.subarray(0, remainingBytes);
+        }
+        this.processed += chunk.length;
+        if (this.processed >= this.maxBytes) {
+            this.limited = true;
+        }
+        this.push(chunk);
+        done();
+    }
+}
+exports.LimitedPassthrough = LimitedPassthrough;

package/dist/cjs/logger.d.ts

@@ -0,0 +1,3 @@
+import pino from 'pino';
+declare const logger: pino.Logger<never, boolean>;
+export default logger;

package/dist/cjs/logger.js

@@ -0,0 +1,11 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const pino_1 = __importDefault(require("pino"));
+const logger = (0, pino_1.default)();
+logger.level = 'trace';
+exports.default = logger;
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/package-info.d.ts

@@ -0,0 +1,3 @@
+export declare const name = "imapflow";
+export declare const version = "2.0.1";
+export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -0,0 +1,7 @@
+"use strict";
+// Generated by scripts/build.js from package.json. Do not edit by hand.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.homepage = exports.version = exports.name = void 0;
+exports.name = 'imapflow';
+exports.version = '2.0.1';
+exports.homepage = 'https://imapflow.com/';

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "commonjs"
+}

package/dist/cjs/proxy-connection.d.ts

@@ -0,0 +1,33 @@
+import net from 'node:net';
+import { ConnectionDeadline } from './connection-deadline.js';
+import type { InternalLogger } from './types.js';
+/**
+ * A socket handed out by the proxy helpers, carrying the early error handler installed by
+ * attachEarlyErrorHandler() until the caller takes ownership
+ */
+export type ProxySocket = net.Socket & {
+    _earlyErrorHandler?: ((err: Error) => void) | null | undefined;
+};
+export interface ProxyConnectionOptions {
+    /**
+     * Shared connection deadline. Proxy DNS and negotiation run inside it, so a stalled proxy
+     * cannot exceed the configured connectionTimeout.
+     */
+    deadline?: ConnectionDeadline | undefined;
+    /** Used to build a deadline when none was passed */
+    connectionTimeout?: number | undefined;
+}
+declare const detachEarlyErrorHandler: (socket: ProxySocket | false | null | undefined) => void;
+/**
+ * Opens a socket to `host`:`port` through the configured proxy.
+ *
+ * @param logger Logger instance.
+ * @param connectionUrl Proxy URL (http, https, socks, socks4, socks4a, socks5).
+ * @param host Destination host, passed through unresolved wherever the proxy protocol
+ *   can resolve it itself.
+ * @param port Destination port.
+ * @param options Deadline options, see ProxyConnectionOptions.
+ * @returns The tunnelled socket, or undefined for an unknown protocol.
+ */
+declare const proxyConnection: (logger: InternalLogger, connectionUrl: string, host: string, port: number, options?: ProxyConnectionOptions | undefined) => Promise<ProxySocket | undefined>;
+export { proxyConnection, detachEarlyErrorHandler };

package/dist/cjs/proxy-connection.js

@@ -0,0 +1,392 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detachEarlyErrorHandler = exports.proxyConnection = void 0;
+const socks_1 = require("socks");
+const node_dns_1 = __importDefault(require("node:dns"));
+const node_net_1 = __importDefault(require("node:net"));
+const node_tls_1 = __importDefault(require("node:tls"));
+const connection_deadline_js_1 = require("./connection-deadline.js");
+const tools_js_1 = require("./tools.js");
+// Cap the CONNECT response buffered before the header terminator, so a proxy that never sends
+// \r\n\r\n cannot grow memory without bound.
+const MAX_RESPONSE_HEADER_BYTES = 64 * 1024;
+const DEFAULT_SOCKS_PORT = 1080;
+// URL hostnames keep the brackets around an IPv6 literal ("[2001:db8::1]"), which is neither a
+// valid input for net.isIP() nor an address net/tls/socks can connect to. Strip them for socket
+// options; the parsed URL itself stays intact for logging and credentials.
+const unbracketAddress = (host) => (typeof host === 'string' && host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host);
+// CONNECT request lines and Host headers need an IPv6 destination wrapped in brackets. Hostnames
+// and IPv4 literals are used as-is, and an already bracketed literal is not bracketed twice.
+const formatAuthority = (host, port) => {
+    let address = unbracketAddress(host);
+    return node_net_1.default.isIPv6(address) ? `[${address}]:${port}` : `${address}:${port}`;
+};
+// Password-free rendering of the proxy URL, used in every log path. The caller's URL object is
+// left untouched so credentials stay available for authentication.
+const redactUrl = (proxyUrl) => {
+    let redacted = new URL(proxyUrl.href);
+    if (redacted.password) {
+        redacted.password = '(hidden)';
+    }
+    return redacted.href;
+};
+const proxyError = (message, code) => {
+    let err = new Error(message);
+    err.code = code || 'ProxyError';
+    return err;
+};
+// URL userinfo is percent-encoded, so it has to be decoded before it can be used as credentials.
+// A password containing a bare '%' is not valid percent-encoding and makes decodeURIComponent
+// throw, so such values are used as they came in rather than failing the connection.
+const decodeUserInfo = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+// The socks client attaches its full options object - proxy password included - to the errors it
+// throws, and Node's URL errors carry the rejected string in `input`. Any logger that serializes
+// error properties would then write that password out in clear text, so the credentials are
+// dropped before the error is logged or handed to the caller.
+const stripProxyCredentials = (err) => {
+    if (err && typeof err === 'object') {
+        delete err.options;
+        delete err.input;
+    }
+    return err;
+};
+// Attaches a benign 'error' listener as soon as the proxied socket exists, so an early
+// socket error (before ImapFlow installs its own handlers) cannot surface as an unhandled
+// 'error' event and crash the process. The handler is stored on the socket so the caller
+// can remove it once it takes ownership of the socket.
+const attachEarlyErrorHandler = (logger, socket) => {
+    if (!socket || typeof socket.on !== 'function') {
+        return;
+    }
+    socket._earlyErrorHandler = (err) => {
+        logger.error({ msg: 'Proxy socket error before connection setup', err });
+    };
+    socket.on('error', socket._earlyErrorHandler);
+};
+// Removes the handler installed by attachEarlyErrorHandler once the caller takes ownership
+// of the socket. Keeps the internal `_earlyErrorHandler` contract inside this module.
+const detachEarlyErrorHandler = (socket) => {
+    if (socket && socket._earlyErrorHandler) {
+        socket.removeListener('error', socket._earlyErrorHandler);
+        socket._earlyErrorHandler = null;
+    }
+};
+exports.detachEarlyErrorHandler = detachEarlyErrorHandler;
+/**
+ * Establishes a tunnel through an HTTP or HTTPS proxy with a CONNECT request.
+ *
+ * ImapFlow owns this instead of using a bundled helper because the connection-wide deadline has
+ * to apply here: the socket is retained as soon as it exists, so an expiry destroys the in-flight
+ * socket immediately, and concurrent connections cannot share a single process-global timeout.
+ *
+ * The destination hostname is passed through unresolved - resolving it is the proxy's job, which
+ * is also what keeps DNS traffic off the client for HTTP proxies.
+ *
+ * @returns The established socket, tunnelled to the destination.
+ */
+const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort, host, port, deadline }) => {
+    // Reject CRLF in the destination before it reaches the CONNECT request line and Host header.
+    // A tainted host/port could otherwise inject additional headers (HTTP request splitting).
+    let destinationPort = Number(port) || 0;
+    if (!destinationPort || /[\r\n]/.test(host)) {
+        throw proxyError('Invalid proxy destination', 'EPROXY');
+    }
+    let authority = formatAuthority(host, destinationPort);
+    let remaining = deadline.remaining();
+    if (!remaining) {
+        throw deadline.error();
+    }
+    let socket = null;
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let timer = null;
+        let headers = '';
+        const onSocketData = (chunk) => {
+            // Scan only the newly arrived bytes (plus the 3 that a terminator could straddle),
+            // so a proxy that dribbles its headers cannot turn this into a quadratic rescan.
+            let searchFrom = Math.max(0, headers.length - 3);
+            headers += chunk.toString('binary');
+            let terminator = headers.indexOf('\r\n\r\n', searchFrom);
+            if (terminator < 0) {
+                if (headers.length > MAX_RESPONSE_HEADER_BYTES) {
+                    fail(proxyError('Proxy response headers too large', 'EPROXY'));
+                }
+                return;
+            }
+            // The header block is complete, so this listener must stop consuming before anything
+            // is put back: unshifting while still subscribed re-emits the data straight back into
+            // this handler, which would swallow it. Pausing hands the socket over cleanly - the
+            // next owner resumes it (ImapFlow pipes it into the parser).
+            socket.removeListener('data', onSocketData);
+            socket.pause();
+            // Anything after the header terminator already belongs to the tunnelled stream (a
+            // server greeting that the proxy coalesced with its own response) and has to be
+            // preserved for the next consumer. It is put back as the original bytes, taken from
+            // this chunk rather than round-tripped through a string.
+            let headerBytes = terminator + 4;
+            let consumedFromChunk = chunk.length - (headers.length - headerBytes);
+            if (consumedFromChunk < chunk.length) {
+                socket.unshift(chunk.subarray(consumedFromChunk));
+            }
+            headers = headers.slice(0, terminator);
+            let status = headers.match(/^HTTP\/\d+\.\d+ (\d+)/i);
+            if (!status || (status[1] || '').charAt(0) !== '2') {
+                return fail(proxyError(`Invalid response from proxy${status ? `: ${status[1]}` : ''}`, 'EPROXY'));
+            }
+            succeed();
+        };
+        // Single settlement path: temporary listeners and the deadline timer are dropped exactly
+        // once, so a late socket event cannot settle the promise twice or leave a timer armed.
+        const cleanup = () => {
+            (0, tools_js_1.clearTimer)(timer);
+            timer = null;
+            if (socket) {
+                // Every temporary listener goes, the connect callback included: after settlement
+                // no socket event may run any of this again.
+                socket.removeListener('connect', onConnected);
+                socket.removeListener('data', onSocketData);
+                socket.removeListener('error', fail);
+                socket.removeListener('close', onEarlyClose);
+            }
+        };
+        function fail(err) {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            if (socket) {
+                socket.destroy();
+            }
+            reject(err);
+        }
+        function succeed() {
+            settled = true;
+            cleanup();
+            resolve(socket);
+        }
+        function onEarlyClose() {
+            fail(proxyError('Proxy closed the connection before the tunnel was established', 'EPROXY'));
+        }
+        timer = setTimeout(() => fail(deadline.error()), remaining);
+        let connectOptions = { host: proxyHost, port: proxyPort };
+        if (secureProxy) {
+            // Verify the proxy's certificate (Node default) and target SNI plus hostname
+            // verification at the proxy endpoint rather than the IMAP destination. An IP-literal
+            // endpoint gets no servername, which would be an invalid SNI value.
+            if (!node_net_1.default.isIP(proxyHost)) {
+                connectOptions.servername = proxyHost;
+            }
+        }
+        // Declared as a function so cleanup() above can detach it (the connect callback is
+        // registered as a one-shot 'connect' listener by net/tls).
+        function onConnected() {
+            let requestHeaders = {
+                Host: authority,
+                Connection: 'close'
+            };
+            if (proxyUrl.username || proxyUrl.password) {
+                let credentials = `${decodeUserInfo(proxyUrl.username)}:${decodeUserInfo(proxyUrl.password)}`;
+                requestHeaders['Proxy-Authorization'] = `Basic ${Buffer.from(credentials).toString('base64')}`;
+            }
+            socket.write(`CONNECT ${authority} HTTP/1.1\r\n` +
+                Object.keys(requestHeaders)
+                    .map(key => `${key}: ${requestHeaders[key]}`)
+                    .join('\r\n') +
+                '\r\n\r\n');
+            socket.on('data', onSocketData);
+        }
+        // The socket is retained as soon as it is created, so an expiry can destroy it at once.
+        socket = secureProxy ? node_tls_1.default.connect(connectOptions, onConnected) : node_net_1.default.connect(connectOptions, onConnected);
+        socket.once('error', fail);
+        socket.once('close', onEarlyClose);
+    })
+        .then(established => {
+        logger.info({
+            msg: `Established a socket via HTTP proxy`,
+            proxyUrl: redactUrl(proxyUrl),
+            port,
+            host
+        });
+        attachEarlyErrorHandler(logger, established);
+        return established;
+    })
+        .catch(err => {
+        logger.error({
+            msg: 'Failed to establish a socket via HTTP proxy',
+            proxyUrl: redactUrl(proxyUrl),
+            port,
+            host,
+            err
+        });
+        throw err;
+    });
+};
+/**
+ * Resolves a destination hostname to an IPv4 address. Only used for SOCKS4, which has no IPv6
+ * destination address type and no hostname form of its own.
+ *
+ * @param hostname Destination hostname.
+ * @param deadline Shared connection deadline.
+ * @returns An IPv4 address.
+ */
+const resolveIPv4 = async (hostname, deadline) => {
+    let addresses = await deadline.race(node_dns_1.default.promises.resolve4(hostname));
+    if (!addresses || !addresses.length) {
+        throw proxyError(`Could not resolve an IPv4 address for ${hostname}`, 'EPROXY');
+    }
+    return addresses[0];
+};
+/**
+ * Establishes a tunnel through a SOCKS proxy.
+ *
+ * DNS policy per protocol, because the `socks` client picks the SOCKS4 or SOCKS4a wire format from
+ * the destination value alone and offers no switch of its own:
+ *   * SOCKS4  - destination hostnames are resolved locally to IPv4. Passing a hostname would
+ *               silently produce a SOCKS4a request that a plain SOCKS4 proxy cannot answer.
+ *   * SOCKS4a - destination hostnames are preserved for remote DNS.
+ *   * SOCKS5  - destination hostnames are preserved for remote DNS, IP literals pass through.
+ * IPv6 destination literals are rejected for both SOCKS4 and SOCKS4a: neither can carry them, and
+ * the dependency would write the literal into the SOCKS4a hostname field instead.
+ *
+ * @returns The established socket, tunnelled to the destination.
+ */
+const socksConnect = async ({ logger, proxyUrl, protocol, proxyHost, proxyPort, host, port, deadline }) => {
+    let proxyType = protocol === 'socks4' || protocol === 'socks4a' ? 4 : 5;
+    let destinationHost = unbracketAddress(host);
+    try {
+        if (proxyType === 4) {
+            if (node_net_1.default.isIPv6(destinationHost)) {
+                throw proxyError(`SOCKS4 and SOCKS4a cannot address IPv6 destinations (${destinationHost})`, 'UnsupportedProxyAddress');
+            }
+            if (protocol === 'socks4' && !node_net_1.default.isIP(destinationHost)) {
+                destinationHost = await resolveIPv4(destinationHost, deadline);
+            }
+        }
+        let connectionOpts = {
+            proxy: {
+                // The endpoint is handed to net.Socket.connect() by the dependency, so a hostname
+                // is left unresolved and gets Node's normal lookup and connection behavior.
+                host: proxyHost,
+                port: proxyPort,
+                type: proxyType
+            },
+            destination: {
+                host: destinationHost,
+                port
+            },
+            command: 'connect',
+            set_tcp_nodelay: true
+        };
+        if (proxyUrl.username || proxyUrl.password) {
+            connectionOpts.proxy.userId = proxyUrl.username;
+            connectionOpts.proxy.password = proxyUrl.password;
+        }
+        // The dependency treats a zero timeout as its own 30 second default, so only a strictly
+        // positive remaining budget may be passed.
+        let remaining = deadline.remaining();
+        if (!remaining) {
+            throw deadline.error();
+        }
+        connectionOpts.timeout = remaining;
+        const info = await deadline.race(socks_1.SocksClient.createConnection(connectionOpts));
+        if (!info || !info.socket) {
+            throw proxyError('SOCKS proxy did not return a socket', 'EPROXY');
+        }
+        logger.info({
+            msg: 'Established a socket via SOCKS proxy',
+            proxyUrl: redactUrl(proxyUrl),
+            port,
+            host
+        });
+        attachEarlyErrorHandler(logger, info.socket);
+        return info.socket;
+    }
+    catch (caught) {
+        // A dependency expiry and the shared deadline are reported with the same
+        // CONNECT_TIMEOUT shape, so a caller does not need to know which noticed first.
+        let err = deadline.normalize(stripProxyCredentials(caught));
+        stripProxyCredentials(err._err);
+        logger.error({
+            msg: 'Failed to establish a socket via SOCKS proxy',
+            proxyUrl: redactUrl(proxyUrl),
+            port,
+            host,
+            err
+        });
+        throw err;
+    }
+};
+/**
+ * Opens a socket to `host`:`port` through the configured proxy.
+ *
+ * @param logger Logger instance.
+ * @param connectionUrl Proxy URL (http, https, socks, socks4, socks4a, socks5).
+ * @param host Destination host, passed through unresolved wherever the proxy protocol
+ *   can resolve it itself.
+ * @param port Destination port.
+ * @param options Deadline options, see ProxyConnectionOptions.
+ * @returns The tunnelled socket, or undefined for an unknown protocol.
+ */
+const proxyConnection = async (logger, connectionUrl, host, port, options) => {
+    options = options || {};
+    let deadline = options.deadline || new connection_deadline_js_1.ConnectionDeadline(options.connectionTimeout);
+    deadline.check();
+    let proxyUrl;
+    try {
+        proxyUrl = new URL(connectionUrl);
+    }
+    catch (err) {
+        // new URL() attaches the string it rejected to err.input, which here is the full proxy
+        // endpoint including its password. Any logger that serializes error properties would
+        // write that out in clear text, so the cause is reported without carrying the value.
+        throw proxyError('Invalid proxy URL', err.code || 'ERR_INVALID_URL');
+    }
+    let protocol = proxyUrl.protocol.replace(/:$/, '').toLowerCase();
+    // ImapFlow performs no DNS lookup of its own for the proxy endpoint: net, tls and the SOCKS
+    // client all resolve a hostname endpoint themselves, which keeps Node's normal connection
+    // behavior (including address-family selection) instead of pinning one address.
+    let proxyHost = unbracketAddress(proxyUrl.hostname);
+    switch (protocol) {
+        // Connect using a HTTP CONNECT method
+        case 'http':
+        case 'https':
+            return await httpConnect({
+                logger,
+                proxyUrl,
+                secureProxy: protocol === 'https',
+                proxyHost,
+                proxyPort: Number(proxyUrl.port) || (protocol === 'https' ? 443 : 80),
+                host,
+                port,
+                deadline
+            });
+        // SOCKS proxy
+        case 'socks':
+        case 'socks5':
+        case 'socks4':
+        case 'socks4a':
+            return await socksConnect({
+                logger,
+                proxyUrl,
+                protocol,
+                proxyHost,
+                proxyPort: Number(proxyUrl.port) || DEFAULT_SOCKS_PORT,
+                host,
+                port,
+                deadline
+            });
+    }
+    return undefined;
+};
+exports.proxyConnection = proxyConnection;

package/dist/cjs/search-compiler.d.ts

@@ -0,0 +1,34 @@
+import type { ImapFlow } from './imap-flow.js';
+import type { ImapAttributeNode } from './handler/types.js';
+import type { SearchObject } from './types.js';
+/**
+ * A compiled search attribute: a token, or a parenthesized group of tokens
+ */
+export type SearchAttribute = ImapAttributeNode | SearchAttribute[];
+/**
+ * Compiles a JavaScript object query into IMAP search command attributes.
+ * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
+ *
+ * @param connection - IMAP connection object (capabilities, enabled extensions and the current mailbox are read)
+ * @param query - Search query object
+ * @returns Array of IMAP search attributes
+ * @throws {Error} When required server extensions are not available
+ *
+ * @example
+ * // Simple search for unseen messages from a sender
+ * searchCompiler(connection, {
+ *   unseen: true,
+ *   from: 'sender@example.com'
+ * });
+ *
+ * @example
+ * // Complex OR search with date range
+ * searchCompiler(connection, {
+ *   or: [
+ *     { from: 'alice@example.com' },
+ *     { from: 'bob@example.com' }
+ *   ],
+ *   since: new Date('2024-01-01')
+ * });
+ */
+export declare const searchCompiler: (connection: ImapFlow, query: SearchObject) => SearchAttribute[];