imapflow 1.4.9 → 1.6.0

package/test/imap-flow-fetch-download-test.js

@@ -300,6 +300,62 @@ module.exports['Download: base64 body part is decoded'] = async test => {
     test.done();
 };
 
+module.exports['Download: binary-fetched part skips the client-side transfer decoding'] = async test => {
+    let client = makeClient();
+    // BINARY fetch (RFC 3516, FETCH side folded into IMAP4rev2): the server
+    // decodes the content-transfer-encoding itself, so the client gets raw bytes
+    // even though the MIME headers still declare base64 - decoding again would
+    // corrupt the data. formatMessageResponse records the parts that arrived via
+    // BINARY[...] in the binaryParts set, which the mock mirrors here.
+    let mime = Buffer.from('Content-Type: text/plain\r\nContent-Transfer-Encoding: base64\r\n\r\n');
+    let decoded = Buffer.from('Hello World');
+    client.fetchOne = async () => {
+        let bodyParts = new Map();
+        bodyParts.set('2.mime', mime);
+        bodyParts.set('2', decoded);
+        return { uid: 1, size: decoded.length, bodyParts, binaryParts: new Set(['2']) };
+    };
+    let { meta, content } = await client.download('1', '2', { chunkSize: 1024, binary: true });
+    test.equal(meta.encoding, 'base64');
+    let data = await collect(content);
+    test.equal(data.toString(), 'Hello World');
+    test.done();
+};
+
+module.exports['DownloadMany: binary-fetched parts skip the client-side transfer decoding'] = async test => {
+    let client = makeClient();
+    let mime = Buffer.from('Content-Type: text/plain\r\nContent-Transfer-Encoding: base64\r\n\r\n');
+    client.fetchOne = async () => {
+        let bodyParts = new Map();
+        bodyParts.set('2.mime', mime);
+        bodyParts.set('2', Buffer.from('part two'));
+        return { uid: 1, bodyParts, binaryParts: new Set(['2']) };
+    };
+    let res = await client.downloadMany('1', ['2'], { binary: true });
+    test.equal(res['2'].content.toString(), 'part two');
+    test.equal(res['2'].meta.encoding, 'base64');
+    test.done();
+};
+
+module.exports['Download: BODY-answered part is still decoded even when binary was requested'] = async test => {
+    let client = makeClient();
+    // RFC 3516 lets a server answer a BINARY request with a NO or a BODY response
+    // (e.g. [UNKNOWN-CTE]) - decoding must follow what actually arrived, so a part
+    // absent from binaryParts gets the client-side decoder despite options.binary
+    let mime = Buffer.from('Content-Type: text/plain\r\nContent-Transfer-Encoding: base64\r\n\r\n');
+    let encoded = Buffer.from(libbase64.encode(Buffer.from('Hello World')));
+    client.fetchOne = async () => {
+        let bodyParts = new Map();
+        bodyParts.set('2.mime', mime);
+        bodyParts.set('2', encoded);
+        return { uid: 1, size: encoded.length, bodyParts };
+    };
+    let { content } = await client.download('1', '2', { chunkSize: 1024, binary: true });
+    let data = await collect(content);
+    test.equal(data.toString(), 'Hello World');
+    test.done();
+};
+
 module.exports['Download: quoted-printable inline text with charset + filename'] = async test => {
     let client = makeClient();
     let mime = Buffer.from(

package/test/imap-flow-internals-test.js

@@ -38,16 +38,39 @@ module.exports['Internals: emitError routes to upgrade rejector while upgrading'
     client.socket = { destroyed: true, destroy: () => {} };
     client.upgrading = true;
     let rejected = null;
+    // Stands in for the upgrade's settle() helper, which owns clearing `upgrading`,
+    // the upgrade timer and the temporary handshake handlers.
     client._upgradeReject = err => {
         rejected = err;
+        client.upgrading = false;
     };
     let err = new Error('tls boom');
     client.emitError(err);
     test.equal(rejected, err);
+    test.equal(client._upgradeReject, null, 'the rejector is consumed exactly once');
     test.equal(client.upgrading, false);
     test.done();
 };
 
+module.exports['Internals: emitError closes when an upgrade has no rejector'] = test => {
+    let client = makeClient();
+    client.socket = { destroyed: true, destroy: () => {} };
+    client.upgrading = true;
+    client._upgradeReject = null;
+
+    let emitted = false;
+    client.on('error', () => {
+        emitted = true;
+    });
+
+    client.emitError(new Error('tls boom'));
+
+    test.equal(client.upgrading, false, 'the upgrade flag is cleared');
+    test.equal(emitted, false, 'no duplicate error event while the upgrade owns reporting');
+    client.close();
+    test.done();
+};
+
 module.exports['Internals: emitError rejects pending connect promise'] = test => {
     let client = makeClient();
     client.socket = { destroyed: true, destroy: () => {} };

package/test/imap-flow-proxy-paths-test.js

@@ -8,6 +8,7 @@ const net = require('net');
 const tls = require('tls');
 const proxyquire = require('proxyquire');
 const { cert, key } = require('./fixtures/test-tls');
+const { ImapFlow } = require('../lib/imap-flow');
 
 const CAPS = 'IMAP4rev1 ID ENABLE NAMESPACE';
 
@@ -213,3 +214,153 @@ module.exports['Proxy: proxyConnection throwing rejects connect'] = async test =
     client.close();
     test.done();
 };
+
+// ---------------------------------------------------------------------------
+// End to end through a real HTTP CONNECT proxy (ImapFlow's own CONNECT helper)
+// ---------------------------------------------------------------------------
+
+// Minimal HTTP CONNECT proxy. `onConnect(socket, headers)` may take over the exchange (used to
+// simulate a proxy that never answers); otherwise the tunnel is established and piped. With
+// `coalesce`, the 200 response is held back until the destination speaks and then written in the
+// same segment as the destination's greeting - which is what a real proxy often does.
+const createHttpProxy = (onConnect, { coalesce = false } = {}) =>
+    net.createServer(socket => {
+        socket.on('error', () => {});
+        let buf = '';
+        const onData = data => {
+            buf += data.toString('binary');
+            let idx = buf.indexOf('\r\n\r\n');
+            if (idx < 0) {
+                return;
+            }
+            socket.removeListener('data', onData);
+            let headers = buf.slice(0, idx);
+            let rest = buf.slice(idx + 4);
+            let authority = (headers.split('\r\n')[0].match(/^CONNECT (\S+)/) || [])[1] || '';
+
+            if (onConnect && onConnect(socket, headers)) {
+                return;
+            }
+
+            let [, targetPort] = authority.split(':');
+            let upstream = net.connect(Number(targetPort), '127.0.0.1', () => {
+                if (rest) {
+                    upstream.write(Buffer.from(rest, 'binary'));
+                }
+
+                const startTunnel = () => {
+                    socket.pipe(upstream);
+                    upstream.pipe(socket);
+                };
+
+                if (!coalesce) {
+                    socket.write('HTTP/1.1 200 Connection established\r\n\r\n');
+                    return startTunnel();
+                }
+
+                // Hold the CONNECT response until the destination sends something, then emit both
+                // in a single write so the client has to preserve the trailing bytes itself.
+                upstream.once('data', firstChunk => {
+                    socket.write(Buffer.concat([Buffer.from('HTTP/1.1 200 Connection established\r\n\r\n'), firstChunk]));
+                    startTunnel();
+                });
+            });
+            upstream.on('error', () => socket.destroy());
+        };
+        socket.on('data', onData);
+    });
+
+module.exports['Proxy: session established through a real HTTP CONNECT proxy'] = async test => {
+    let imapServer = createServer();
+    let imapPort = await listen(imapServer);
+    let proxy = createHttpProxy();
+    let proxyPort = await listen(proxy);
+
+    let client = new ImapFlow({
+        host: '127.0.0.1',
+        port: imapPort,
+        secure: false,
+        proxy: `http://127.0.0.1:${proxyPort}`,
+        disableAutoIdle: true,
+        disableCompression: true,
+        logger: false,
+        auth: { user: 'test', pass: 'secret' }
+    });
+    client.on('error', () => {});
+
+    await client.connect();
+    test.ok(client.usable, 'session established through the CONNECT tunnel');
+    test.ok(client.authenticated);
+
+    await client.logout();
+    client.close();
+    proxy.close();
+    imapServer.close();
+    test.done();
+};
+
+module.exports['Proxy: a greeting coalesced with the CONNECT response is not lost'] = async test => {
+    // The proxy answers CONNECT and the destination greeting in one segment. The bytes after the
+    // header terminator belong to the tunnel, so they have to reach the parser - otherwise the
+    // greeting is swallowed and connect() only fails at the greeting timeout.
+    let imapServer = createServer();
+    let imapPort = await listen(imapServer);
+    let proxy = createHttpProxy(null, { coalesce: true });
+    let proxyPort = await listen(proxy);
+
+    let client = new ImapFlow({
+        host: '127.0.0.1',
+        port: imapPort,
+        secure: false,
+        proxy: `http://127.0.0.1:${proxyPort}`,
+        greetingTimeout: 1500,
+        disableAutoIdle: true,
+        disableCompression: true,
+        logger: false,
+        auth: { user: 'test', pass: 'secret' }
+    });
+    client.on('error', () => {});
+
+    await client.connect();
+    test.ok(client.usable, 'the coalesced greeting was parsed, so the session came up');
+    test.ok(client.capabilities.has('IMAP4rev1'), 'capabilities from the coalesced greeting are present');
+
+    await client.logout();
+    client.close();
+    proxy.close();
+    imapServer.close();
+    test.done();
+};
+
+module.exports['Proxy: a stalled proxy negotiation is bounded by connectionTimeout'] = async test => {
+    // The proxy accepts the CONNECT request and then goes silent
+    let proxy = createHttpProxy(() => true);
+    let proxyPort = await listen(proxy);
+
+    let client = new ImapFlow({
+        host: '127.0.0.1',
+        port: 143,
+        secure: false,
+        proxy: `http://127.0.0.1:${proxyPort}`,
+        connectionTimeout: 150,
+        disableAutoIdle: true,
+        disableCompression: true,
+        logger: false,
+        auth: { user: 'test', pass: 'secret' }
+    });
+    client.on('error', () => {});
+
+    let started = Date.now();
+    let err = await client.connect().then(
+        () => null,
+        e => e
+    );
+
+    test.ok(err, 'connect rejected instead of hanging in proxy negotiation');
+    test.equal(err.code, 'CONNECT_TIMEOUT', 'the documented connection timeout covers proxy negotiation');
+    test.ok(Date.now() - started < 3000, 'the deadline applied to the proxy phase, not only to the transport');
+
+    client.close();
+    proxy.close();
+    test.done();
+};

package/test/imap-flow-secure-test.js

@@ -13,13 +13,17 @@ const CAPS = 'IMAP4rev1 ID ENABLE NAMESPACE';
 
 // Shared per-connection IMAP line handler used by both the plaintext and the
 // upgraded TLS phases. Returns responses for the minimal session commands.
-const handleLine = (sock, line, onStartTls) => {
+// `caps` is the full capability list to advertise for this phase - the STARTTLS
+// test uses different pre- and post-TLS sets to prove the client discards the
+// plaintext capabilities and re-fetches them over TLS (RFC 9051 6.2.1).
+const handleLine = (sock, line, onStartTls, caps) => {
+    caps = caps || `${CAPS} STARTTLS`;
     let parts = line.split(' ');
     let tag = parts[0];
     let cmd = (parts[1] || '').toUpperCase();
     switch (cmd) {
         case 'CAPABILITY':
-            sock.write(`* CAPABILITY ${CAPS} STARTTLS\r\n${tag} OK CAPABILITY done\r\n`);
+            sock.write(`* CAPABILITY ${caps}\r\n${tag} OK CAPABILITY done\r\n`);
             break;
         case 'STARTTLS':
             sock.write(`${tag} OK Begin TLS\r\n`);
@@ -79,21 +83,93 @@ module.exports['Secure: STARTTLS upgrade completes a session'] = async test => {
     let server = net.createServer(rawSocket => {
         rawSocket.on('error', () => {});
 
+        let detachPlain;
+        detachPlain = lineReader(rawSocket, line => {
+            handleLine(
+                rawSocket,
+                line,
+                () => {
+                    // Upgrade: stop reading plaintext, wrap the socket in TLS
+                    detachPlain();
+                    let tlsSocket = new tls.TLSSocket(rawSocket, { isServer: true, key, cert });
+                    tlsSocket.on('error', () => {});
+                    tlsSocket.on('secure', () => {});
+                    // post-TLS phase advertises a different capability set
+                    lineReader(tlsSocket, l => handleLine(tlsSocket, l, null, `${CAPS} POSTTLS-ONLY`));
+                },
+                `${CAPS} STARTTLS PRETLS-ONLY`
+            );
+        });
+
+        rawSocket.write(`* OK [CAPABILITY ${CAPS} STARTTLS PRETLS-ONLY] ready\r\n`);
+    });
+
+    let port = await listen(server);
+    let client = new ImapFlow({
+        host: '127.0.0.1',
+        port,
+        secure: false,
+        doSTARTTLS: true,
+        servername: 'localhost',
+        tls: { rejectUnauthorized: false },
+        disableAutoIdle: true,
+        disableCompression: true,
+        logger: false,
+        auth: { user: 'test', pass: 'secret' }
+    });
+    client.on('error', () => {});
+
+    await client.connect();
+    test.ok(client.secureConnection, 'connection upgraded to TLS');
+    test.ok(client.authenticated, 'authenticated over TLS');
+    test.ok(client.usable);
+    // RFC 9051 6.2.1: capabilities cached before STARTTLS MUST be discarded and
+    // re-fetched over the TLS channel
+    test.ok(client.capabilities.has('POSTTLS-ONLY'), 'post-TLS capabilities were re-fetched');
+    test.ok(!client.capabilities.has('PRETLS-ONLY'), 'pre-TLS capabilities were discarded');
+
+    await client.noop();
+    await client.logout();
+    client.close();
+    server.close();
+    test.done();
+};
+
+// Builds the STARTTLS happy-path server used by the watchdog and cleanup tests below.
+const createStartTlsServer = () =>
+    net.createServer(rawSocket => {
+        rawSocket.on('error', () => {});
+
         let detachPlain;
         detachPlain = lineReader(rawSocket, line => {
             handleLine(rawSocket, line, () => {
-                // Upgrade: stop reading plaintext, wrap the socket in TLS
                 detachPlain();
                 let tlsSocket = new tls.TLSSocket(rawSocket, { isServer: true, key, cert });
                 tlsSocket.on('error', () => {});
-                tlsSocket.on('secure', () => {});
-                lineReader(tlsSocket, l => handleLine(tlsSocket, l));
+                lineReader(tlsSocket, l => handleLine(tlsSocket, l, null, CAPS));
             });
         });
 
         rawSocket.write(`* OK [CAPABILITY ${CAPS} STARTTLS] ready\r\n`);
     });
 
+// Records every socket that went through configureSocket(), which is the single place the
+// transport options (keepalive + inactivity watchdog) are applied.
+const trackConfiguredSockets = client => {
+    let sockets = [];
+    let original = client.configureSocket.bind(client);
+    client.configureSocket = socket => {
+        sockets.push(socket);
+        return original(socket);
+    };
+    return sockets;
+};
+
+module.exports['Secure: STARTTLS session keeps the inactivity watchdog'] = async test => {
+    // Regression: the inactivity timer was armed on the plain socket only, while the timeout
+    // listener was attached to the TLS socket, so an upgraded session had no watchdog at all
+    // and a dead connection was never noticed.
+    let server = createStartTlsServer();
     let port = await listen(server);
     let client = new ImapFlow({
         host: '127.0.0.1',
@@ -102,25 +178,122 @@ module.exports['Secure: STARTTLS upgrade completes a session'] = async test => {
         doSTARTTLS: true,
         servername: 'localhost',
         tls: { rejectUnauthorized: false },
+        socketTimeout: 200,
         disableAutoIdle: true,
         disableCompression: true,
         logger: false,
         auth: { user: 'test', pass: 'secret' }
     });
-    client.on('error', () => {});
+
+    let errors = [];
+    client.on('error', err => errors.push(err));
+    let closed = new Promise(resolve => client.once('close', resolve));
+    let configured = trackConfiguredSockets(client);
 
     await client.connect();
     test.ok(client.secureConnection, 'connection upgraded to TLS');
-    test.ok(client.authenticated, 'authenticated over TLS');
-    test.ok(client.usable);
+    test.equal(configured.length, 2, 'both the plain socket and the upgraded socket are configured');
+    test.equal(client.socket.timeout, 200, 'the upgraded socket carries the configured inactivity timeout');
+    test.equal(configured[0].timeout, 0, 'the superseded plain-socket timer is cleared, not left armed');
+
+    // No traffic from here on: the watchdog has to fire and take the connection down.
+    await closed;
+
+    test.ok(
+        errors.some(err => err.code === 'ETIMEOUT'),
+        'the inactivity watchdog reported a socket timeout'
+    );
+    test.ok(client.isClosed, 'the connection closed after the timeout');
+
+    client.close();
+    server.close();
+    test.done();
+};
+
+module.exports['Secure: STARTTLS leaves no upgrade state behind on success'] = async test => {
+    // Item 8: every terminal path of the upgrade runs through one settlement helper, so after
+    // a successful handshake no timer, rejector, flag or temporary handler survives.
+    let server = createStartTlsServer();
+    let port = await listen(server);
+    let client = new ImapFlow({
+        host: '127.0.0.1',
+        port,
+        secure: false,
+        doSTARTTLS: true,
+        servername: 'localhost',
+        tls: { rejectUnauthorized: false },
+        disableAutoIdle: true,
+        disableCompression: true,
+        logger: false,
+        auth: { user: 'test', pass: 'secret' }
+    });
+    client.on('error', () => {});
+
+    await client.connect();
+
+    test.equal(client.upgrading, false, 'upgrading flag cleared');
+    test.equal(client._upgradeReject, null, 'upgrade rejector cleared');
+    test.equal(client.upgradeTimeout, null, 'upgrade timer cleared');
+    // The handshake-only handler is gone, leaving the generic socket error handler as the single
+    // error path (during the handshake it is the other way round, which is what prevents a
+    // handshake error from firing two handlers at once).
+    test.equal(client.socket.listenerCount('error'), 1, 'the TLS socket keeps exactly one error path');
 
-    await client.noop();
     await client.logout();
     client.close();
     server.close();
     test.done();
 };
 
+module.exports['Secure: close() during a STARTTLS upgrade settles the upgrade'] = async test => {
+    // The server acknowledges STARTTLS but never performs a handshake. close() has to settle
+    // the pending upgrade instead of leaving the session promise dangling forever.
+    let server = net.createServer(rawSocket => {
+        rawSocket.on('error', () => {});
+        let detach = lineReader(rawSocket, line => {
+            handleLine(rawSocket, line, () => {
+                detach(); // silence: no ServerHello, no data at all
+            });
+        });
+        rawSocket.write(`* OK [CAPABILITY ${CAPS} STARTTLS] ready\r\n`);
+    });
+    let port = await listen(server);
+    let client = new ImapFlow({
+        host: '127.0.0.1',
+        port,
+        secure: false,
+        doSTARTTLS: true,
+        servername: 'localhost',
+        tls: { rejectUnauthorized: false },
+        disableAutoIdle: true,
+        disableCompression: true,
+        logger: false,
+        auth: { user: 'test', pass: 'secret' }
+    });
+    client.on('error', () => {});
+
+    let connectResult = client.connect().then(
+        () => null,
+        err => err
+    );
+
+    // Wait until the upgrade is in flight, then close the connection under it.
+    while (!client.upgrading) {
+        await new Promise(resolve => setTimeout(resolve, 10));
+    }
+    client.close();
+
+    let err = await connectResult;
+    test.ok(err, 'connect rejected rather than hanging on the abandoned upgrade');
+    test.ok(['ClosedAfterConnectText', 'ClosedAfterConnectTLS', 'NoConnection'].includes(err.code), `connect rejected with ${err.code}`);
+    test.equal(client.upgrading, false, 'upgrading flag cleared');
+    test.equal(client._upgradeReject, null, 'upgrade rejector cleared');
+    test.equal(client.upgradeTimeout, null, 'upgrade timer cleared');
+
+    server.close();
+    test.done();
+};
+
 // ---------------------------------------------------------------------------
 // Direct TLS connection
 // ---------------------------------------------------------------------------