imapflow 1.7.8 → 2.0.1

package/{lib → dist/esm}/proxy-connection.js

@@ -1,69 +1,59 @@
-'use strict';
-
-const { SocksClient } = require('socks');
-const dns = require('dns').promises;
-const net = require('net');
-const tls = require('tls');
-
-const { ConnectionDeadline } = require('./connection-deadline');
-
+import { SocksClient } from 'socks';
+import dns from 'node:dns';
+import net from 'node:net';
+import tls from 'node:tls';
+import { ConnectionDeadline } from './connection-deadline.js';
+import { clearTimer } from './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);
-
+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 net.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 => {
+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 => {
+const decodeUserInfo = (value) => {
     try {
         return decodeURIComponent(value);
-    } catch {
+    }
+    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 => {
+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
@@ -72,21 +62,19 @@ const attachEarlyErrorHandler = (logger, socket) => {
     if (!socket || typeof socket.on !== 'function') {
         return;
     }
-    socket._earlyErrorHandler = err => {
+    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 => {
+const detachEarlyErrorHandler = (socket) => {
     if (socket && socket._earlyErrorHandler) {
         socket.removeListener('error', socket._earlyErrorHandler);
         socket._earlyErrorHandler = null;
     }
 };
-
 /**
  * Establishes a tunnel through an HTTP or HTTPS proxy with a CONNECT request.
  *
@@ -97,16 +85,7 @@ const detachEarlyErrorHandler = socket => {
  * 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.
  *
- * @param {Object} params
- * @param {Object} params.logger Logger instance.
- * @param {URL} params.proxyUrl Parsed proxy URL (credentials intact).
- * @param {Boolean} params.secureProxy Whether the proxy endpoint itself speaks TLS.
- * @param {String} params.proxyHost Proxy endpoint host, IPv6 literals unbracketed.
- * @param {Number} params.proxyPort Proxy endpoint port.
- * @param {String} params.host Destination host (hostname or IP literal).
- * @param {Number} params.port Destination port.
- * @param {ConnectionDeadline} params.deadline Shared connection deadline.
- * @returns {Promise<Object>} The established socket, tunnelled to the destination.
+ * @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.
@@ -115,27 +94,21 @@ const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort
     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 => {
+        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) {
@@ -143,14 +116,12 @@ const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort
                 }
                 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
@@ -161,19 +132,16 @@ const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort
                 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 = () => {
-            clearTimeout(timer);
+            clearTimer(timer);
             timer = null;
             if (socket) {
                 // Every temporary listener goes, the connect callback included: after settlement
@@ -184,7 +152,6 @@ const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort
                 socket.removeListener('close', onEarlyClose);
             }
         };
-
         function fail(err) {
             if (settled) {
                 return;
@@ -196,19 +163,15 @@ const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort
             }
             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
@@ -218,7 +181,6 @@ const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort
                 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() {
@@ -226,66 +188,58 @@ const httpConnect = async ({ logger, proxyUrl, secureProxy, proxyHost, proxyPort
                 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.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 ? tls.connect(connectOptions, onConnected) : net.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;
-        })
+        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;
+        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 {String} hostname Destination hostname.
- * @param {ConnectionDeadline} deadline Shared connection deadline.
- * @returns {Promise<String>} An IPv4 address.
+ * @param hostname Destination hostname.
+ * @param deadline Shared connection deadline.
+ * @returns An IPv4 address.
  */
 const resolveIPv4 = async (hostname, deadline) => {
-    let addresses = await deadline.race(dns.resolve4(hostname));
+    let addresses = await deadline.race(dns.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.
  *
@@ -298,32 +252,20 @@ const resolveIPv4 = async (hostname, deadline) => {
  * 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.
  *
- * @param {Object} params
- * @param {Object} params.logger Logger instance.
- * @param {URL} params.proxyUrl Parsed proxy URL (credentials intact).
- * @param {String} params.protocol Configured proxy protocol (socks, socks4, socks4a, socks5).
- * @param {String} params.proxyHost Proxy endpoint host, IPv6 literals unbracketed.
- * @param {Number} params.proxyPort Proxy endpoint port.
- * @param {String} params.host Destination host (hostname or IP literal).
- * @param {Number} params.port Destination port.
- * @param {ConnectionDeadline} params.deadline Shared connection deadline.
- * @returns {Promise<Object>} The established socket, tunnelled to the destination.
+ * @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 (net.isIPv6(destinationHost)) {
                 throw proxyError(`SOCKS4 and SOCKS4a cannot address IPv6 destinations (${destinationHost})`, 'UnsupportedProxyAddress');
             }
-
             if (protocol === 'socks4' && !net.isIP(destinationHost)) {
                 destinationHost = await resolveIPv4(destinationHost, deadline);
             }
         }
-
         let connectionOpts = {
             proxy: {
                 // The endpoint is handed to net.Socket.connect() by the dependency, so a hostname
@@ -339,12 +281,10 @@ const socksConnect = async ({ logger, proxyUrl, protocol, proxyHost, proxyPort,
             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();
@@ -352,12 +292,10 @@ const socksConnect = async ({ logger, proxyUrl, protocol, proxyHost, proxyPort,
             throw deadline.error();
         }
         connectionOpts.timeout = remaining;
-
         const info = await deadline.race(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),
@@ -365,14 +303,13 @@ const socksConnect = async ({ logger, proxyUrl, protocol, proxyHost, proxyPort,
             host
         });
         attachEarlyErrorHandler(logger, info.socket);
-
         return info.socket;
-    } catch (caught) {
+    }
+    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),
@@ -383,43 +320,36 @@ const socksConnect = async ({ logger, proxyUrl, protocol, proxyHost, proxyPort,
         throw err;
     }
 };
-
 /**
  * Opens a socket to `host`:`port` through the configured proxy.
  *
- * @param {Object} logger Logger instance.
- * @param {String} connectionUrl Proxy URL (http, https, socks, socks4, socks4a, socks5).
- * @param {String} host Destination host, passed through unresolved wherever the proxy protocol
+ * @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 {Number} port Destination port.
- * @param {Object} [options]
- * @param {ConnectionDeadline} [options.deadline] Shared connection deadline. Proxy DNS and
- *   negotiation run inside it, so a stalled proxy cannot exceed the configured connectionTimeout.
- * @param {Number} [options.connectionTimeout] Used to build a deadline when none was passed.
- * @returns {Promise<Object|undefined>} The tunnelled socket, or undefined for an unknown protocol.
+ * @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 ConnectionDeadline(options.connectionTimeout);
     deadline.check();
-
     let proxyUrl;
     try {
         proxyUrl = new URL(connectionUrl);
-    } catch (err) {
+    }
+    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':
@@ -434,7 +364,6 @@ const proxyConnection = async (logger, connectionUrl, host, port, options) => {
                 port,
                 deadline
             });
-
         // SOCKS proxy
         case 'socks':
         case 'socks5':
@@ -451,6 +380,6 @@ const proxyConnection = async (logger, connectionUrl, host, port, options) => {
                 deadline
             });
     }
+    return undefined;
 };
-
-module.exports = { proxyConnection, detachEarlyErrorHandler };
+export { proxyConnection, detachEarlyErrorHandler };

package/dist/esm/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[];