imapflow 1.2.8 → 1.2.10

package/lib/jp-decoder.js

@@ -3,6 +3,11 @@
 const { Transform } = require('stream');
 const encodingJapanese = require('encoding-japanese');
 
+// 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 Transform {
     constructor(charset) {
         super();
@@ -12,6 +17,8 @@ class JPDecoder extends Transform {
         this.chunklen = 0;
     }
 
+    // Buffer all incoming chunks; 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);
@@ -22,6 +29,9 @@ class JPDecoder extends Transform {
         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 {

package/lib/limited-passthrough.js

@@ -2,26 +2,33 @@
 
 const { Transform } = require('stream');
 
+// 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 Transform {
     constructor(options) {
         super();
         this.options = options || {};
         this.maxBytes = this.options.maxBytes || Infinity;
         this.processed = 0;
+        // Once set to true, all subsequent chunks are dropped without error
         this.limited = false;
     }
 
     _transform(chunk, encoding, done) {
+        // If the limit was already reached, discard the chunk immediately
         if (this.limited) {
             return done();
         }
 
-        if (this.processed + chunk.length > this.maxBytes) {
-            if (this.maxBytes - this.processed < 1) {
-                return done();
-            }
+        const remainingBytes = this.maxBytes - this.processed;
+        if (remainingBytes < 1) {
+            return done();
+        }
 
-            chunk = chunk.slice(0, this.maxBytes - this.processed);
+        // Slice the chunk to fit within the remaining byte budget
+        if (chunk.length > remainingBytes) {
+            chunk = chunk.slice(0, remainingBytes);
         }
 
         this.processed += chunk.length;

package/lib/proxy-connection.js

@@ -7,11 +7,22 @@ const httpProxyClientAsync = util.promisify(httpProxyClient);
 const dns = require('dns').promises;
 const net = require('net');
 
+// Redacts the password from a parsed URL object before it is logged,
+// preventing credentials from appearing in log output.
+const hidePassword = proxyUrl => {
+    if (proxyUrl.password) {
+        proxyUrl.password = '(hidden)';
+    }
+};
+
 const proxyConnection = async (logger, connectionUrl, host, port) => {
     let proxyUrl = new URL(connectionUrl);
 
     let protocol = proxyUrl.protocol.replace(/:$/, '').toLowerCase();
 
+    // Pre-resolve the IMAP server hostname to an IP address before passing it to the proxy.
+    // Some proxy implementations (especially SOCKS4) do not support hostname resolution,
+    // so we resolve DNS on the client side to ensure compatibility.
     if (!net.isIP(host)) {
         let resolveResult = await dns.resolve(host);
         if (resolveResult && resolveResult.length) {
@@ -26,9 +37,7 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
             try {
                 let socket = await httpProxyClientAsync(proxyUrl.href, port, host);
                 if (socket) {
-                    if (proxyUrl.password) {
-                        proxyUrl.password = '(hidden)';
-                    }
+                    hidePassword(proxyUrl);
                     logger.info({
                         msg: 'Established a socket via HTTP proxy',
                         proxyUrl: proxyUrl.href,
@@ -38,9 +47,7 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
                 }
                 return socket;
             } catch (err) {
-                if (proxyUrl.password) {
-                    proxyUrl.password = '(hidden)';
-                }
+                hidePassword(proxyUrl);
                 logger.error({
                     msg: 'Failed to establish a socket via HTTP proxy',
                     proxyUrl: proxyUrl.href,
@@ -59,6 +66,9 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
         case 'socks4a': {
             let proxyType = Number(protocol.replace(/\D/g, '')) || 5;
 
+            // targetHost here is the SOCKS proxy server's hostname (not the final IMAP destination).
+            // The SOCKS library needs a resolved IP for the proxy host it connects to.
+            // The final IMAP destination (host/port) is passed separately as 'destination'.
             let targetHost = proxyUrl.hostname;
             if (!net.isIP(targetHost)) {
                 let resolveResult = await dns.resolve(targetHost);
@@ -89,9 +99,7 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
             try {
                 const info = await SocksClient.createConnection(connectionOpts);
                 if (info && info.socket) {
-                    if (proxyUrl.password) {
-                        proxyUrl.password = '(hidden)';
-                    }
+                    hidePassword(proxyUrl);
                     logger.info({
                         msg: 'Established a socket via SOCKS proxy',
                         proxyUrl: proxyUrl.href,
@@ -101,9 +109,7 @@ const proxyConnection = async (logger, connectionUrl, host, port) => {
                 }
                 return info.socket;
             } catch (err) {
-                if (proxyUrl.password) {
-                    proxyUrl.password = '(hidden)';
-                }
+                hidePassword(proxyUrl);
                 logger.error({
                     msg: 'Failed to establish a socket via SOCKS proxy',
                     proxyUrl: proxyUrl.href,

package/lib/search-compiler.js

@@ -105,8 +105,8 @@ let isUnicodeString = str => {
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
  *
  * @param {Object} connection - IMAP connection object
- * @param {Object} connection.capabilities - Set of server capabilities
- * @param {Object} connection.enabled - Set of enabled extensions
+ * @param {Map} connection.capabilities - Map of server capabilities
+ * @param {Set} connection.enabled - Set of enabled extensions
  * @param {Object} connection.mailbox - Current mailbox information
  * @param {Set} connection.mailbox.flags - Available flags in the mailbox
  * @param {Object} query - Search query object
@@ -259,15 +259,7 @@ module.exports.searchCompiler = (connection, query) => {
                             // Convert to seconds ago from now
                             const now = Date.now();
                             const withinSeconds = Math.round(Math.max(0, now - params[term].getTime()) / 1000);
-                            let withinKeyword;
-                            switch (term.toUpperCase()) {
-                                case 'BEFORE':
-                                    withinKeyword = 'OLDER';
-                                    break;
-                                case 'SINCE':
-                                    withinKeyword = 'YOUNGER';
-                                    break;
-                            }
+                            const withinKeyword = term.toUpperCase() === 'BEFORE' ? 'OLDER' : 'YOUNGER';
                             setOpt(attributes, withinKeyword, withinSeconds.toString());
                             break;
                         }

package/lib/special-use.js

@@ -1,5 +1,9 @@
 'use strict';
 
+// Localized folder name mappings for detecting special-use mailboxes.
+// When the server does not advertise the SPECIAL-USE extension (RFC 6154),
+// we fall back to matching folder names against these lists of known
+// translations in various languages (including non-Latin scripts).
 module.exports = {
     flags: ['\\All', '\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash'],
     names: {
@@ -281,27 +285,30 @@ module.exports = {
     },
 
     specialUse(hasSpecialUseExtension, folder) {
-        let result;
-
+        // If the server supports SPECIAL-USE (RFC 6154), check for special-use flags first.
+        // Extension-provided flags take precedence over name-based detection because they
+        // are authoritative -- the server explicitly marks the folder's role.
         if (hasSpecialUseExtension) {
-            result = {
-                flag: module.exports.flags.find(flag => folder.flags.has(flag)),
-                source: 'extension'
-            };
+            const flag = module.exports.flags.find(flag => folder.flags.has(flag));
+            if (flag) {
+                return { flag, source: 'extension' };
+            }
         }
 
-        if (!result || !result.flag) {
-            let name = folder.name
-                .toLowerCase()
-                .replace(/\u200e/g, '')
-                .trim();
+        // Fallback: match folder name against known localized names.
+        // Remove U+200E (LEFT-TO-RIGHT MARK) which some mail clients (especially for
+        // RTL languages like Arabic, Hebrew) insert into folder names for display purposes.
+        // These invisible marks would otherwise prevent exact string matching.
+        let name = folder.name
+            .toLowerCase()
+            .replace(/\u200e/g, '')
+            .trim();
 
-            result = {
-                flag: Object.keys(module.exports.names).find(flag => module.exports.names[flag].includes(name)),
-                source: 'name'
-            };
+        const flag = Object.keys(module.exports.names).find(flag => module.exports.names[flag].includes(name));
+        if (flag) {
+            return { flag, source: 'name' };
         }
 
-        return result && result.flag ? result : { flag: null };
+        return { flag: null };
     }
 };