imapflow 1.3.5 → 1.3.7

package/test/starttls-injection-test.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const net = require('net');
+const { ImapFlow } = require('../lib/imap-flow');
+const { ImapStream } = require('../lib/handler/imap-stream');
+
+// Minimal pre-STARTTLS IMAP server. Sends the greeting, advertises STARTTLS, and on the
+// STARTTLS command invokes `onStartTls(socket, tag)` so each test controls what (if
+// anything) is written after the tagged OK. It never performs a real TLS handshake.
+const createStartTlsServer = onStartTls =>
+    net.createServer(socket => {
+        socket.on('error', () => {});
+        socket.write('* OK [CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED] ready\r\n');
+
+        let buf = '';
+        socket.on('data', data => {
+            buf += data.toString('binary');
+            let idx;
+            while ((idx = buf.indexOf('\r\n')) >= 0) {
+                let line = buf.slice(0, idx);
+                buf = buf.slice(idx + 2);
+                let parts = line.split(' ');
+                let tag = parts[0];
+                let command = (parts[1] || '').toUpperCase();
+                if (command === 'CAPABILITY') {
+                    socket.write('* CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED\r\n');
+                    socket.write(`${tag} OK CAPABILITY done\r\n`);
+                } else if (command === 'STARTTLS') {
+                    onStartTls(socket, tag);
+                }
+            }
+        });
+    });
+
+const makeClient = port =>
+    new ImapFlow({
+        host: '127.0.0.1',
+        port,
+        secure: false,
+        doSTARTTLS: true,
+        servername: 'localhost',
+        tls: { rejectUnauthorized: false },
+        disableAutoIdle: true,
+        logger: false,
+        auth: { user: 'test', pass: 'test' }
+    });
+
+// A MITM injects a response in the SAME segment as the STARTTLS OK, before the handshake.
+// This is caught by the parser-level trailing-data flag (Check 1 in upgradeToSTARTTLS).
+// Injection that instead arrives after the OK in a separate segment is caught by the
+// socket-level read after unpipe (Check 2) or, failing that, by TLS handshake corruption;
+// those fragmented cases are timing-dependent and not asserted deterministically here.
+module.exports['STARTTLS: rejects same-segment plaintext injection'] = async test => {
+    let server = createStartTlsServer((socket, tag) => {
+        // OK and an injected untagged CAPABILITY in a single write, no TLS handshake.
+        socket.write(`${tag} OK Begin TLS\r\n* CAPABILITY IMAP4rev1 INJECTED\r\n`);
+    });
+
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    let port = server.address().port;
+
+    let client = makeClient(port);
+    client.on('error', () => {});
+
+    let connectErr = null;
+    try {
+        await client.connect();
+        test.ok(false, 'connect() must reject when data is injected after the STARTTLS OK');
+    } catch (err) {
+        connectErr = err;
+    }
+
+    test.ok(connectErr, 'connect() rejected');
+    test.equal(connectErr.code, 'STARTTLS_INJECTION', 'rejection is flagged as an injection');
+    test.ok(connectErr.tlsFailed, 'rejection is treated as a TLS failure');
+    // The connection must fail closed: it never becomes usable and never authenticates.
+    // (The injected untagged response may be parsed transiently before teardown, so asserting
+    // it never reaches the capability set would be a timing-fragile false assurance.)
+    test.ok(!client.usable, 'the connection did not become usable (failed closed)');
+    test.ok(!client.authenticated, 'the connection never authenticated');
+
+    client.close();
+    server.close();
+    test.done();
+};
+
+// A compliant server stays silent after the STARTTLS OK. The injection guard must NOT
+// fire (no false positive); the upgrade proceeds to the TLS handshake, which then fails
+// here only because this stub server never speaks TLS — proving the guard let it through.
+module.exports['STARTTLS: clean OK is not flagged as injection'] = async test => {
+    let server = createStartTlsServer((socket, tag) => {
+        // Only the tagged OK, nothing after it, then drop the connection.
+        socket.write(`${tag} OK Begin TLS\r\n`);
+        setImmediate(() => socket.destroy());
+    });
+
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    let port = server.address().port;
+
+    let client = makeClient(port);
+    client.on('error', () => {});
+
+    let connectErr = null;
+    try {
+        await client.connect();
+        test.ok(false, 'connect() rejects because the stub never completes the TLS handshake');
+    } catch (err) {
+        connectErr = err;
+    }
+
+    test.ok(connectErr, 'connect() rejected (no TLS handshake on the stub server)');
+    test.notEqual(connectErr.code, 'STARTTLS_INJECTION', 'a clean OK must not be flagged as injection');
+
+    client.close();
+    server.close();
+    test.done();
+};
+
+// A STARTTLS handshake failure must reject connect() through a single error path: it must
+// not also emit an 'error' event (which would double-report and crash a listener-less client).
+module.exports['STARTTLS: handshake failure has a single error path'] = async test => {
+    let server = createStartTlsServer((socket, tag) => {
+        // Acknowledge STARTTLS, then drop the connection instead of doing TLS.
+        socket.write(`${tag} OK Begin TLS\r\n`);
+        setImmediate(() => socket.destroy());
+    });
+
+    await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+    let port = server.address().port;
+
+    let client = makeClient(port);
+
+    // A second error path would emit here (and crash a listener-less client).
+    let errorEvents = 0;
+    client.on('error', () => {
+        errorEvents++;
+    });
+
+    let connectErr = null;
+    try {
+        await client.connect();
+        test.ok(false, 'connect() should reject on STARTTLS handshake failure');
+    } catch (err) {
+        connectErr = err;
+    }
+
+    // Give any stray async error handler a chance to (wrongly) fire.
+    await new Promise(r => setTimeout(r, 50));
+
+    test.ok(connectErr, 'connect() rejected');
+    test.ok(connectErr.tlsFailed, 'rejection is flagged as a TLS failure');
+    test.equal(errorEvents, 0, 'no duplicate error event emitted (single error path)');
+
+    client.close();
+    server.close();
+    test.done();
+};
+
+// Unit-level check of the per-command trailing flag the guard relies on: each pushed
+// command records whether more input followed it, independently of later commands.
+module.exports['STARTTLS: parser flags trailing data per command'] = test => {
+    const stream = new ImapStream({ cid: 'test' });
+    let flags = [];
+
+    stream.on('readable', () => {
+        let cmd;
+        while ((cmd = stream.read()) !== null) {
+            flags.push(cmd.trailingAfterLine);
+            cmd.next();
+        }
+    });
+    stream.on('error', err => test.ifError(err));
+    stream.on('end', () => {
+        // First command had a second command after it -> true; the last one -> false.
+        test.deepEqual(flags, [true, false], 'trailingAfterLine is per-command and not overwritten');
+        test.done();
+    });
+
+    // Two complete commands in a single write.
+    stream.end(Buffer.from('A OK first\r\nB OK second\r\n'));
+};

package/test/token-parser-test.js

@@ -390,3 +390,67 @@ module.exports['Token Parser: malformed REFERRAL with no closing bracket consume
         test.equal(section[0].value, 'REFERRAL');
         test.equal(section[1].value, 'imap://user@host/INBOX');
     });
+
+// ---------------------------------------------------------------------------
+// Additional error-path and edge-case coverage (E11, E12, E16, E17, E19-E22,
+// E24, E27) plus the bare-"*" sequence and "~"-as-atom normalization paths.
+// All use a non-status command (FETCH) so the TokenParser is actually invoked.
+// ---------------------------------------------------------------------------
+
+const expectParserError = (input, code) => test =>
+    asyncWrapper(test, async test => {
+        let err;
+        try {
+            await parser(input);
+        } catch (e) {
+            err = e;
+        }
+        if (!err) throw new Error('Expected parser to throw but it did not');
+        test.equal(err.code, code);
+    });
+
+module.exports['Token Parser: E11: unexpected ] throws ParserError11'] = expectParserError('* 1 FETCH (])', 'ParserError11');
+module.exports['Token Parser: E12: ~ not followed by { throws ParserError12'] = expectParserError('* 1 FETCH ~%', 'ParserError12');
+module.exports['Token Parser: E16: \\* followed by char throws ParserError17'] = expectParserError('* 1 FETCH \\*x', 'ParserError17');
+module.exports['Token Parser: E19: partial ending with . throws ParserError19'] = expectParserError('* 1 FETCH BODY[]<0.>', 'ParserError19');
+module.exports['Token Parser: E20: partial leading . throws ParserError20'] = expectParserError('* 1 FETCH BODY[]<.>', 'ParserError20');
+module.exports['Token Parser: E21: non-digit in partial throws ParserError21'] = expectParserError('* 1 FETCH BODY[]<0.x>', 'ParserError21');
+module.exports['Token Parser: E22: invalid leading-zero partial throws ParserError22'] = expectParserError('* 1 FETCH BODY[]<00>', 'ParserError22');
+module.exports['Token Parser: E24: literal prefix not followed by CRLF throws ParserError24'] = expectParserError('* 1 FETCH {3}xyz', 'ParserError24');
+module.exports['Token Parser: E27: whitespace mid-sequence throws ParserError27'] = expectParserError('* 1 FETCH 1: 2', 'ParserError27');
+
+module.exports['Token Parser: bare * is normalized to an ATOM'] = test =>
+    asyncWrapper(test, async test => {
+        let r = await parser('* 1 FETCH *');
+        let last = r.attributes[r.attributes.length - 1];
+        test.equal(last.type, 'ATOM');
+        test.equal(last.value, '*');
+    });
+
+module.exports['Token Parser: ~ followed by atom chars becomes an ATOM'] = test =>
+    asyncWrapper(test, async test => {
+        let r = await parser('* 1 FETCH ~abc');
+        let last = r.attributes[r.attributes.length - 1];
+        test.equal(last.type, 'ATOM');
+        test.equal(last.value, '~abc');
+    });
+
+module.exports['Token Parser: E16: invalid char in atom throws ParserError16'] = expectParserError('* 1 FETCH 3* 4', 'ParserError16');
+
+module.exports['Token Parser: literal+ (non-synchronizing) marker is accepted'] = test =>
+    asyncWrapper(test, async test => {
+        // {3+} is a LITERAL+ prefix; with literalPlus enabled and no pre-parsed
+        // literals, the parser reads the literal bytes inline.
+        let r = await parser('* 1 FETCH {3+}\r\nabc', { literalPlus: true });
+        let lit = r.attributes[r.attributes.length - 1];
+        test.equal(lit.type, 'LITERAL');
+        test.equal(lit.value.toString(), 'abc');
+    });
+
+module.exports['Token Parser: literal prefix terminated by bare LF is accepted'] = test =>
+    asyncWrapper(test, async test => {
+        let r = await parser('* 1 FETCH {3}\nabc');
+        let lit = r.attributes[r.attributes.length - 1];
+        test.equal(lit.type, 'LITERAL');
+        test.equal(lit.value.toString(), 'abc');
+    });

package/test/tools-test.js

@@ -1188,6 +1188,366 @@ module.exports['Tools: formatMessageResponse normalizes non-ASCII mailbox path f
     test.done();
 };
 
+module.exports['Tools: formatMessageResponse parses the full attribute set'] = async test => {
+    let untagged = await parser(
+        '* 3 FETCH (UID 100 RFC822.SIZE 5000 FLAGS (\\Seen \\Flagged) MODSEQ (12345) ' +
+            'X-GM-MSGID 999 X-GM-THRID 888 X-GM-LABELS (\\Important Work) ' +
+            'INTERNALDATE "12-Jan-2020 10:00:00 +0000" BODY[1] {3}\r\n BODY[HEADER] {2}\r\n)',
+        { literals: [Buffer.from('abc'), Buffer.from('hi')] }
+    );
+    let mailbox = { path: 'INBOX', uidValidity: 1n }; // no uidNext/highestModseq -> exercise the bump branches
+    let r = await tools.formatMessageResponse(untagged, mailbox);
+    test.equal(r.uid, 100);
+    test.equal(r.size, 5000);
+    test.ok(r.flags.has('\\Seen'));
+    test.equal(r.modseq, 12345n);
+    test.equal(r.emailId, '999'); // X-GM-MSGID
+    test.equal(r.threadId, '888'); // X-GM-THRID
+    test.ok(r.labels.has('Work'));
+    test.ok(r.internalDate instanceof Date);
+    test.ok(Buffer.isBuffer(r.headers));
+    test.ok(r.bodyParts.get('1'));
+    // mailbox estimates bumped from the FETCH data
+    test.equal(mailbox.uidNext, 101);
+    test.equal(mailbox.highestModseq, 12345n);
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse parses envelope and bodystructure'] = async test => {
+    let untagged = await parser(
+        '* 1 FETCH (ENVELOPE ("Mon, 2 Sep 2013 05:30:13 -0700" "Subject" ((NIL NIL "a" "b.com")) NIL NIL NIL NIL NIL NIL "<id@x>") ' +
+            'BODYSTRUCTURE ("TEXT" "PLAIN" ("CHARSET" "utf-8") NIL NIL "7BIT" 12 0 NIL NIL NIL))'
+    );
+    let r = await tools.formatMessageResponse(untagged, { path: 'INBOX' });
+    test.ok(r.envelope);
+    test.equal(r.envelope.subject, 'Subject');
+    test.ok(r.bodyStructure);
+    test.equal(r.bodyStructure.type, 'text/plain');
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse source from BODY[] and BINARY[] literals'] = async test => {
+    let untagged = await parser('* 1 FETCH (BODY[] {5}\r\n)', { literals: [Buffer.from('HELLO')] });
+    let r = await tools.formatMessageResponse(untagged, { path: 'INBOX' });
+    test.ok(Buffer.isBuffer(r.source));
+    test.equal(r.source.toString(), 'HELLO');
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse keeps invalid INTERNALDATE as raw string'] = async test => {
+    let untagged = await parser('* 1 FETCH (INTERNALDATE "not a date")');
+    let r = await tools.formatMessageResponse(untagged, { path: 'INBOX' });
+    test.equal(r.internalDate, 'not a date');
+    test.done();
+};
+
+module.exports['Tools: parseEnvelope parses every field'] = async test => {
+    let untagged = await parser(
+        '* 1 FETCH (ENVELOPE ("Mon, 2 Sep 2013 05:30:13 -0700" "Hello" ' +
+            '((NIL NIL "from" "x.com")) ((NIL NIL "sender" "x.com")) ((NIL NIL "reply" "x.com")) ' +
+            '((NIL NIL "to" "x.com")) ((NIL NIL "cc" "x.com")) ((NIL NIL "bcc" "x.com")) ' +
+            '"<inreplyto@x>" "<msgid@x>"))'
+    );
+    let env = tools.parseEnvelope(untagged.attributes[1][1]);
+    test.ok(env.date instanceof Date);
+    test.equal(env.subject, 'Hello');
+    test.equal(env.from[0].address, 'from@x.com');
+    test.equal(env.sender[0].address, 'sender@x.com');
+    test.equal(env.replyTo[0].address, 'reply@x.com');
+    test.equal(env.to[0].address, 'to@x.com');
+    test.equal(env.cc[0].address, 'cc@x.com');
+    test.equal(env.bcc[0].address, 'bcc@x.com');
+    test.equal(env.inReplyTo, '<inreplyto@x>');
+    test.equal(env.messageId, '<msgid@x>');
+    test.done();
+};
+
+module.exports['Tools: parseEnvelope keeps invalid date as string'] = async test => {
+    let untagged = await parser('* 1 FETCH (ENVELOPE ("not a date" "Subj" NIL NIL NIL NIL NIL NIL NIL NIL))');
+    let env = tools.parseEnvelope(untagged.attributes[1][1]);
+    test.equal(env.date, 'not a date');
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure parses all single-part extension fields'] = async test => {
+    let bs =
+        '("TEXT" "PLAIN" ("CHARSET" "utf-8") "<cid@x>" "a description" "BASE64" 100 5 ' +
+        '"d41d8cd9" ("attachment" ("filename" "f.txt")) ("en" "de") "http://loc/")';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, 'text/plain');
+    test.equal(node.id, '<cid@x>');
+    test.equal(node.description, 'a description');
+    test.equal(node.encoding, 'base64');
+    test.equal(node.size, 100);
+    test.equal(node.lineCount, 5);
+    test.equal(node.md5, 'd41d8cd9');
+    test.equal(node.disposition, 'attachment');
+    test.equal(node.dispositionParameters.filename, 'f.txt');
+    test.deepEqual(node.language, ['en', 'de']);
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure parses message/rfc822 with envelope and child'] = async test => {
+    let bs =
+        '("MESSAGE" "RFC822" NIL NIL NIL "7BIT" 200 ' +
+        '("date" "subj" NIL NIL NIL NIL NIL NIL "<reply>" "<msgid>") ' +
+        '("TEXT" "PLAIN" NIL NIL NIL "7BIT" 10 1) 3)';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, 'message/rfc822');
+    test.ok(node.envelope);
+    test.equal(node.childNodes.length, 1);
+    test.equal(node.lineCount, 3);
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure parses multipart with params and disposition'] = async test => {
+    let bs =
+        '(("TEXT" "PLAIN" NIL NIL NIL "7BIT" 10 1)("TEXT" "HTML" NIL NIL NIL "7BIT" 20 2) ' +
+        '"ALTERNATIVE" ("BOUNDARY" "xyz") ("inline" NIL) ("en"))';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, 'multipart/alternative');
+    test.equal(node.childNodes.length, 2);
+    test.equal(node.parameters.boundary, 'xyz');
+    test.equal(node.disposition, 'inline');
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse handles NIL, Buffer and unknown keys'] = async test => {
+    let untagged = await parser('* 1 FETCH (UID NIL RFC822.SIZE NIL X-GM-MSGID {3}\r\n BODY[] NIL FOOBAR 123)', {
+        literals: [Buffer.from('999')]
+    });
+    let r = await tools.formatMessageResponse(untagged, { path: 'INBOX' });
+    test.equal(r.uid, 0); // NIL value -> getString returns false -> Number(false) = 0
+    test.equal(r.size, 0);
+    test.equal(r.emailId, '999'); // Buffer literal value -> getString stringifies it
+    test.equal(r.source, false); // BODY[] NIL -> getBuffer returns false
+    test.done();
+};
+
+module.exports['Tools: getFolderTree merges duplicate folder entries'] = test => {
+    let tree = tools.getFolderTree([
+        { name: 'Parent', path: 'Parent', parent: [], flags: new Set(['\\HasChildren']), delimiter: '/' },
+        { name: 'Parent', path: 'Parent', parent: [], flags: new Set(['\\Noselect', '\\HasChildren']), specialUse: '\\Sent', delimiter: '/' }
+    ]);
+    test.equal(tree.folders.length, 1);
+    test.equal(tree.folders[0].disabled, true);
+    test.equal(tree.folders[0].specialUse, '\\Sent');
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure handles minimal NIL fields'] = async test => {
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ("APPLICATION" "OCTET-STREAM" NIL NIL NIL NIL NIL))');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, 'application/octet-stream');
+    test.equal(node.id, undefined);
+    test.equal(node.encoding, undefined);
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure decodes RFC 2231 charset continuation params'] = async test => {
+    let bs = "(\"TEXT\" \"PLAIN\" (\"name*0*\" \"utf-8''%E2%82%AC abc\" \"name*1\" \"def\") NIL NIL \"7BIT\" 10 1)";
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.parameters.name, '€ abcdef');
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure handles empty-string extension fields'] = async test => {
+    // Empty-string values exercise the `|| ''` / `|| 0` fallbacks in each field.
+    let bs = '("TEXT" "PLAIN" ("CHARSET" "") "" "" "" 0 0 "" ("" ("" "")) ("") "")';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.id, '');
+    test.equal(node.description, '');
+    test.equal(node.size, 0);
+    test.equal(node.md5, '');
+    test.deepEqual(node.language, ['']);
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse with no data list returns just seq'] = async test => {
+    let untagged = await parser('* 5 FETCH');
+    let r = await tools.formatMessageResponse(untagged, { path: 'INBOX' });
+    test.equal(r.seq, 5);
+    test.done();
+};
+
+module.exports['Tools: getFolderTree adds folders array when existing entry gains HasChildren'] = test => {
+    let tree = tools.getFolderTree([
+        { name: 'P', path: 'P', parent: [], flags: new Set([]), delimiter: '/' },
+        { name: 'P', path: 'P', parent: [], flags: new Set(['\\HasChildren']), delimiter: '/' }
+    ]);
+    test.ok(Array.isArray(tree.folders[0].folders), 'folders array created on merge');
+    test.done();
+};
+
+module.exports['Tools: normalizePath joins array with empty delimiter fallback'] = test => {
+    // namespace present but without a delimiter -> the (... || '') fallback joins directly
+    let connection = { namespace: { prefix: '' } };
+    test.equal(tools.normalizePath(connection, ['a', 'b']), 'ab');
+    test.done();
+};
+
+module.exports['Tools: updateCapabilities defaults non-numeric APPENDLIMIT to 0'] = test => {
+    let caps = tools.updateCapabilities([{ value: 'APPENDLIMIT=abc' }]);
+    test.equal(caps.get('APPENDLIMIT'), 0);
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse skips non-string label entries'] = async test => {
+    let untagged = await parser('* 1 FETCH (X-GM-LABELS (\\Important NIL))');
+    let r = await tools.formatMessageResponse(untagged, { path: 'INBOX' });
+    test.deepEqual([...r.labels], ['\\Important']); // NIL entry filtered out
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse does not lower highestModseq'] = async test => {
+    let mailbox = { path: 'INBOX', highestModseq: 99999n };
+    let untagged = await parser('* 1 FETCH (MODSEQ (5) FLAGS (\\Seen))');
+    await tools.formatMessageResponse(untagged, mailbox);
+    test.equal(mailbox.highestModseq, 99999n); // unchanged: incoming modseq is lower
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure multipart with NIL subtype'] = async test => {
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE (("TEXT" "PLAIN" NIL NIL NIL "7BIT" 1 1) NIL))');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, 'multipart/');
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure content type with NIL type/subtype'] = async test => {
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE (NIL NIL NIL NIL NIL "7BIT" 1))');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, '/');
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure message/rfc822 with NIL envelope/linecount'] = async test => {
+    let bs = '("MESSAGE" "RFC822" NIL NIL NIL "7BIT" 100 NIL ("TEXT" "PLAIN" NIL NIL NIL "7BIT" 1 1) NIL NIL (NIL) NIL)';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, 'message/rfc822');
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure text with NIL language/location entries'] = async test => {
+    let bs = '("TEXT" "PLAIN" NIL NIL NIL "7BIT" 100 NIL "md5" ("inline" NIL) (NIL) NIL)';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.deepEqual(node.language, ['']);
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure empty-string size/linecount/language/location'] = async test => {
+    let bs = '("TEXT" "PLAIN" NIL NIL NIL "7BIT" "" "" "" ("inline" NIL) ("") "")';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.size, 0);
+    test.equal(node.lineCount, 0);
+    test.deepEqual(node.language, ['']);
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure message/rfc822 empty-string linecount'] = async test => {
+    let bs =
+        '("MESSAGE" "RFC822" NIL NIL NIL "7BIT" 100 ("d" "s" NIL NIL NIL NIL NIL NIL NIL NIL) ' +
+        '("TEXT" "PLAIN" NIL NIL NIL "7BIT" 1 1) "")';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.type, 'message/rfc822');
+    test.equal(node.lineCount, 0);
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure decodes RFC 2231 with empty charset and special chars'] = async test => {
+    // Empty charset before the first quote defaults to utf-8; '=' / '?' in the value
+    // exercise the 2-char hex escape branch; the empty *1* continuation segment too.
+    // value includes '=' / '?' (2-char hex escapes), a space (-> '_') and a TAB
+    // (a <0x10 control char -> single-hex-digit escape needing a '0' pad).
+    let bs = "(\"TEXT\" \"PLAIN\" (\"name*0*\" \"''a=b?c d\te\" \"name*1*\" \"\") NIL NIL \"7BIT\" 1 1)";
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.ok(node.parameters.name.includes('a=b?c'));
+    test.done();
+};
+
+module.exports['Tools: parseBodystructure parses empty-string body location'] = async test => {
+    // A trailing element after location makes the (i < length-1) guard pass so the
+    // empty-string location value goes through the `|| ''` fallback.
+    let bs = '("TEXT" "PLAIN" NIL NIL NIL "7BIT" 1 1 NIL NIL NIL "" NIL)';
+    let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
+    let node = tools.parseBodystructure(untagged.attributes[1][1]);
+    test.equal(node.location, '');
+    test.done();
+};
+
+module.exports['Tools: expandRange descending range to non-numeric second bound'] = test => {
+    test.deepEqual(tools.expandRange('5:abc'), [5, 4, 3, 2, 1, 0]);
+    test.done();
+};
+
+module.exports['Tools: expandRange tolerates non-numeric entries'] = test => {
+    test.deepEqual(tools.expandRange('abc,:5,1:3'), [0, 0, 1, 2, 3, 4, 5, 1, 2, 3]);
+    test.done();
+};
+
+module.exports['Tools: expandRange handles descending ranges'] = test => {
+    test.deepEqual(tools.expandRange('5:3'), [5, 4, 3]);
+    test.done();
+};
+
+module.exports['Tools: encodePath keeps name as-is when iconv encode throws'] = test => {
+    // The iconv module object is shared by reference; patch encode to throw so the
+    // defensive catch is exercised, then restore.
+    let original = iconv.encode;
+    iconv.encode = () => {
+        throw new Error('encode boom');
+    };
+    try {
+        let connection = { enabled: new Set() };
+        let result = tools.encodePath(connection, 'Tärä');
+        test.equal(result, 'Tärä', 'falls back to the raw path');
+    } finally {
+        iconv.encode = original;
+    }
+    test.done();
+};
+
+module.exports['Tools: decodePath keeps name as-is when iconv decode throws'] = test => {
+    let original = iconv.decode;
+    iconv.decode = () => {
+        throw new Error('decode boom');
+    };
+    try {
+        let connection = { enabled: new Set() };
+        let result = tools.decodePath(connection, 'Inbox&AOk-');
+        test.equal(result, 'Inbox&AOk-');
+    } finally {
+        iconv.decode = original;
+    }
+    test.done();
+};
+
+module.exports['Tools: formatMessageResponse id falls back when iconv encode throws'] = async test => {
+    let original = iconv.encode;
+    iconv.encode = () => {
+        throw new Error('encode boom');
+    };
+    try {
+        let untagged = await parser('* 1 FETCH (UID 5 FLAGS (\\Seen))');
+        // non-ASCII path triggers the encode branch; the throw is swallowed
+        let r = await tools.formatMessageResponse(untagged, { path: 'Tärä', uidValidity: 1n });
+        test.ok(r.id, 'an id is still produced');
+    } finally {
+        iconv.encode = original;
+    }
+    test.done();
+};
+
 // ============================================
 // packMessageRange
 // ============================================