imapflow 2.2.5 → 2.2.7

package/dist/esm/search-compiler.js

@@ -50,17 +50,12 @@ let toSequenceValue = (value) => [].concat(value).join(',');
 let toSearchValue = (value) => UNICODE_PATTERN.test(value) && !value.includes('\0') ? { type: 'LITERAL', value: Buffer.from(value) } : { type: 'ATOM', value };
 /**
  * Adds a search option with its value(s) to the attributes array.
- * Handles NOT operations and array values.
  *
  * @param attributes - Array to append the attribute to
  * @param term - The search term (e.g., 'FROM', 'SUBJECT')
- * @param value - The value for the search term (string, array, or falsy for NOT)
+ * @param value - The value for the search term (string or array)
  */
 let setOpt = (attributes, term, value) => {
-    // Handle NOT operations for false or null values
-    if (value === false || value === null) {
-        attributes.push({ type: 'ATOM', value: 'NOT' });
-    }
     attributes.push({ type: 'ATOM', value: term.toUpperCase() });
     // Handle array values (e.g. HEADER name/value pairs)
     if (Array.isArray(value)) {
@@ -250,6 +245,11 @@ export const searchCompiler = (connection, query) => {
                     break;
                 // Email ID support (OBJECTID or Gmail extension)
                 case 'EMAILID':
+                    // A falsy value means no criterion, as for the text fields. It used to
+                    // compile into NOT EMAILID "false", which matched every message
+                    if (!params[term]) {
+                        break;
+                    }
                     if (connection.capabilities.has('OBJECTID')) {
                         setOpt(attributes, 'EMAILID', params[term]);
                     }
@@ -257,7 +257,7 @@ export const searchCompiler = (connection, query) => {
                         // Fallback to Gmail message ID
                         setOpt(attributes, 'X-GM-MSGID', params[term]);
                     }
-                    else if (params[term]) {
+                    else {
                         // Dropping the criterion would widen the search to every message
                         // matching the rest of the query, which a delete or move acts on
                         fail('MissingServerExtension', 'Server does not support OBJECTID or X-GM-EXT-1 extension required for EMAILID');
@@ -265,6 +265,11 @@ export const searchCompiler = (connection, query) => {
                     break;
                 // Thread ID support (OBJECTID or Gmail extension)
                 case 'THREADID':
+                    // A falsy value means no criterion, as for the text fields. It used to
+                    // compile into NOT THREADID "false", which matched every message
+                    if (!params[term]) {
+                        break;
+                    }
                     if (connection.capabilities.has('OBJECTID')) {
                         setOpt(attributes, 'THREADID', params[term]);
                     }
@@ -272,7 +277,7 @@ export const searchCompiler = (connection, query) => {
                         // Fallback to Gmail thread ID
                         setOpt(attributes, 'X-GM-THRID', params[term]);
                     }
-                    else if (params[term]) {
+                    else {
                         // Dropping the criterion would widen the search to every message
                         // matching the rest of the query, which a delete or move acts on
                         fail('MissingServerExtension', 'Server does not support OBJECTID or X-GM-EXT-1 extension required for THREADID');
@@ -335,11 +340,11 @@ export const searchCompiler = (connection, query) => {
                         if (!value) {
                             break;
                         }
-                        // Use WITHIN extension for better timezone handling if available
-                        if (connection.capabilities.has('WITHIN')) {
-                            // Convert to seconds ago from now
-                            const now = Date.now();
-                            const withinSeconds = Math.round(Math.max(0, now - value.getTime()) / 1000);
+                        // Use WITHIN extension for better timezone handling if available.
+                        // The interval is an nz-number (RFC 5032), so a date that is not in the
+                        // past (OLDER 0 would be answered with BAD) takes the date path instead
+                        const withinSeconds = Math.round((Date.now() - value.getTime()) / 1000);
+                        if (connection.capabilities.has('WITHIN') && withinSeconds >= 1) {
                             const withinKeyword = term.toUpperCase() === 'BEFORE' ? 'OLDER' : 'YOUNGER';
                             setOpt(attributes, withinKeyword, withinSeconds.toString());
                             break;
@@ -359,7 +364,15 @@ export const searchCompiler = (connection, query) => {
                 case 'KEYWORD':
                 case 'UNKEYWORD':
                     {
+                        if (typeof params[term] !== 'string') {
+                            fail('InvalidSearchQuery', `Search value for ${term.toLowerCase()} must be a string`);
+                        }
                         let flag = formatFlag(params[term]);
+                        // formatFlag() refuses \Recent, which is not a keyword. Dropping the
+                        // criterion would widen the search, so the query is refused instead
+                        if (flag === false) {
+                            fail('InvalidSearchQuery', `${params[term]} can not be searched as a keyword, use the "recent" search key instead`);
+                        }
                         // Compiled even when the mailbox does not allow the keyword: the
                         // correct answer is then the empty set, which dropping the
                         // criterion would turn into every message matching the rest
@@ -386,8 +399,12 @@ export const searchCompiler = (connection, query) => {
                     }
                     break;
                 // NOT operator
+                // A falsy operand means no NOT clause (`not: cond && {...}`). Any other one goes
+                // through walkOperand(), which refuses a value that is not a query object or
+                // compiles to nothing: dropping it would turn the filter into a search that
+                // matches everything
                 case 'NOT':
-                    if (params[term] && typeof params[term] === 'object') {
+                    if (params[term]) {
                         attributes.push({ type: 'ATOM', value: 'NOT' });
                         walkOperand('NOT', params[term]);
                     }
@@ -400,8 +417,8 @@ export const searchCompiler = (connection, query) => {
                         }
                         // Single element - just process it directly
                         if (params[term].length === 1) {
-                            if (typeof params[term][0] === 'object' && params[term][0]) {
-                                walk(params[term][0]);
+                            if (params[term][0]) {
+                                walkOperand('OR', params[term][0]);
                             }
                             break;
                         }
@@ -453,6 +470,10 @@ export const searchCompiler = (connection, query) => {
                         walkOrTree(genOrTree(params[term]));
                     }
                     break;
+                default:
+                    // An unknown key is refused: dropping it silently widened the search (a
+                    // query of only unknown keys matched every message)
+                    fail('InvalidSearchQuery', `Unknown search key "${term}"`);
             }
         });
     };

package/dist/esm/special-use.js

@@ -74,6 +74,7 @@ const TOKEN_SPLIT = /[\s\-_/.,()[\]]+/;
 // we fall back to matching folder names against these lists of known
 // translations in various languages (including non-Latin scripts).
 export const flags = ['\\All', '\\Archive', '\\Drafts', '\\Flagged', '\\Junk', '\\Sent', '\\Trash'];
+const LOWERCASE_FLAGS = flags.map(flag => flag.toLowerCase());
 export const names = {
     '\\Sent': [
         'aika',
@@ -860,9 +861,10 @@ for (let flag of Object.keys(names)) {
     }
 }
 // Fold a folder name into the form the name tables are stored in.
-// 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.
+// Remove U+200E and U+200F (LEFT-TO-RIGHT and RIGHT-TO-LEFT 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. U+200B
+// (ZERO WIDTH SPACE) is kept, Khmer names in the tables use it as their word separator.
 // Normalize with NFKC last: the same folder name can arrive in different but
 // equivalent forms depending on the client that created it, and matching is exact.
 // NFKC rather than NFC because the compatibility folding is what maps halfwidth
@@ -871,7 +873,7 @@ for (let flag of Object.keys(names)) {
 function normalizeName(name) {
     return name
         .toLowerCase()
-        .replace(/\u200e/g, '')
+        .replace(/[\u200e\u200f]/g, '')
         .trim()
         .normalize('NFKC');
 }
@@ -880,7 +882,10 @@ export const specialUse = (hasSpecialUseExtension, folder) => {
     // Extension-provided flags take precedence over name-based detection because they
     // are authoritative - the server explicitly marks the folder's role.
     if (hasSpecialUseExtension) {
-        const flag = flags.find(flag => folder.flags.has(flag));
+        // Flags are atoms and compare case-insensitively (RFC 9051 section 9)
+        const listed = new Set();
+        folder.flags.forEach(flag => listed.add(flag.toLowerCase()));
+        const flag = flags.find((flag, i) => listed.has(LOWERCASE_FLAGS[i]));
         if (flag) {
             return { flag, source: 'extension' };
         }

package/dist/esm/tools.d.ts

@@ -119,6 +119,14 @@ export declare function unrefTimer<T extends NodeJS.Timeout | null | undefined>(
  * @param err - The error to log
  */
 export declare function logConnectionError(connection: ImapFlow, msg: string, err: ImapFlowError | null | undefined): void;
+/**
+ * Whether a command failed because the server answered it with a tagged NO or BAD, as opposed
+ * to a lost connection, a timeout or a local failure that says nothing about the server's answer.
+ *
+ * @param err - The error the command failed with
+ * @returns True for a tagged NO or BAD
+ */
+export declare function isServerRefusal(err: ImapFlowError | null | undefined): boolean;
 /**
  * Checks whether IMAP4rev2 semantics are active for the connection: either the
  * client enabled IMAP4rev2 explicitly, or the server is rev2-only (advertises
@@ -407,7 +415,8 @@ export declare function isUnsafeKey(key: unknown): boolean;
 /**
  * Reads a parsed attribute list of atoms or strings (a flag list, a capability list) into
  * an array of strings. Any element can be a parsed NIL, and the list itself can be NIL,
- * so both levels are guarded here rather than at each call site.
+ * so both levels are guarded here rather than at each call site. A literal (a Gmail label
+ * the server could not send quoted) arrives as a Buffer and is decoded as UTF-8.
  *
  * @param list - Parsed attribute list from a response.
  * @returns The string values, in order, with unusable entries dropped.

package/dist/esm/tools.js

@@ -211,6 +211,16 @@ export function logConnectionError(connection, msg, err) {
     let routine = !!err && CONNECTION_GONE_CODES.has(err.code) && !err.reason;
     connection.log[routine ? 'debug' : 'warn']({ msg, err, cid: connection.id });
 }
+/**
+ * Whether a command failed because the server answered it with a tagged NO or BAD, as opposed
+ * to a lost connection, a timeout or a local failure that says nothing about the server's answer.
+ *
+ * @param err - The error the command failed with
+ * @returns True for a tagged NO or BAD
+ */
+export function isServerRefusal(err) {
+    return !!err && (err.responseStatus === 'NO' || err.responseStatus === 'BAD');
+}
 /**
  * Checks whether IMAP4rev2 semantics are active for the connection: either the
  * client enabled IMAP4rev2 explicitly, or the server is rev2-only (advertises
@@ -538,7 +548,12 @@ export function getFolderTree(folders) {
         }
         return node;
     };
-    for (let folder of folders) {
+    // Parents are inserted before their children, as getTreeNode() can only descend into nodes
+    // that already exist. LIST gives no ordering guarantee, and the LIST command sorts special-use
+    // mailboxes first, which put a child such as "[Gmail]/Sent Mail" ahead of "[Gmail]" and left
+    // it at the root. The sort is stable, so siblings keep their listing order
+    let byDepth = [...folders].sort((a, b) => (a.parent ? a.parent.length : 0) - (b.parent ? b.parent.length : 0));
+    for (let folder of byDepth) {
         let parent = getTreeNode(folder.parent);
         // see if entry already exists
         let existing = parent.folders && parent.folders.find(existing => existing.name === folder.name);
@@ -1357,7 +1372,8 @@ export function isUnsafeKey(key) {
 /**
  * Reads a parsed attribute list of atoms or strings (a flag list, a capability list) into
  * an array of strings. Any element can be a parsed NIL, and the list itself can be NIL,
- * so both levels are guarded here rather than at each call site.
+ * so both levels are guarded here rather than at each call site. A literal (a Gmail label
+ * the server could not send quoted) arrives as a Buffer and is decoded as UTF-8.
  *
  * @param list - Parsed attribute list from a response.
  * @returns The string values, in order, with unusable entries dropped.
@@ -1366,7 +1382,17 @@ export function getStringList(list) {
     if (!Array.isArray(list)) {
         return [];
     }
-    return list.map(entry => (entry && typeof entry.value === 'string' ? entry.value : false)).filter(entry => entry);
+    let strings = [];
+    for (let entry of list) {
+        let value = entry && entry.value;
+        if (Buffer.isBuffer(value)) {
+            value = value.toString();
+        }
+        if (value && typeof value === 'string') {
+            strings.push(value);
+        }
+    }
+    return strings;
 }
 /**
  * Parses an untrusted decimal value from a server response into a BigInt.

package/dist/esm/types.d.ts

@@ -155,7 +155,15 @@ export interface ImapFlowOptions {
      * 30 minutes. Set to 0 or false to disable.
      */
     maxLockHoldTime?: number | false | undefined;
-    /** If true, uses TLS. If false, uses cleartext. If not set, upgrades to TLS if available */
+    /**
+     * STARTTLS policy for a connection that was not opened with `secure: true`. If true, the
+     * connection must upgrade to TLS, and connecting fails when the server does not offer
+     * STARTTLS. If false, the connection stays in cleartext. If not set, the connection upgrades
+     * when the server offers STARTTLS and otherwise continues in cleartext with a warning logged:
+     * the capability list that decides this was itself received in cleartext, so an attacker on
+     * the path can strip it. Set `doSTARTTLS: true` whenever the credentials must never cross the
+     * wire unencrypted.
+     */
     doSTARTTLS?: boolean | undefined;
     /** Custom instance ID string for logs */
     id?: string | undefined;
@@ -646,8 +654,8 @@ export interface DownloadOptions {
     /** How large content parts to ask from the server. Defaults to 65536 */
     chunkSize?: number | undefined;
 }
-/** Options for downloadMany(), the same shape as the download() options */
-export type DownloadManyOptions = DownloadOptions;
+/** Options for downloadMany(): the download() options without `chunkSize`, as the parts come in one FETCH */
+export type DownloadManyOptions = Pick<DownloadOptions, 'uid' | 'maxBytes'>;
 export interface DownloadManyPart {
     meta: DownloadMeta;
     content?: Buffer | null | undefined;
@@ -769,6 +777,13 @@ export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
  */
 export type InternalLogger = {
     [level in LogLevel]: (obj: any) => void;
+} & {
+    /**
+     * Whether an entry logged at this level reaches anyone (the logger, or a 'log' event
+     * listener). Set on the logger the connection builds; a logger assigned from outside may
+     * lack it, and every level then counts as enabled
+     */
+    isLevelEnabled?: ((level: LogLevel) => boolean) | undefined;
 };
 export interface LogEvent {
     /** Log level */
@@ -802,7 +817,7 @@ export interface ESearchResult {
     partial?: {
         /** The requested range, e.g. "1:100" */
         range: string;
-        /** Matching UIDs in that range as compact sequence-set */
+        /** Matching UIDs in that range as compact sequence-set, an empty string when the range lies past the end of the results */
         messages: string;
     } | undefined;
     /** Highest mod-sequence of the matching messages (RFC 7162, present when the search used a modseq criterion on a CONDSTORE session) */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.2.5",
+    "version": "2.2.7",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -45,6 +45,7 @@
         "pretest:workers": "npm run build",
         "test:workers": "node --import tsx --test test/cloudflare/cloudflare-test.ts",
         "test:rev2": "bash test/integration/run-rev2-tests.sh",
+        "test:mutation": "node scripts/mutation-test.js",
         "format": "prettier --write \"**/*.{js,cjs,ts,json,md,yml,yaml}\"",
         "format:check": "prettier --check \"**/*.{js,cjs,ts,json,md,yml,yaml}\"",
         "lint": "npm run typecheck && eslint .",
@@ -77,7 +78,7 @@
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",
-        "typescript-eslint": "8.71.0",
+        "typescript-eslint": "8.71.1",
         "wrangler": "4.147.0"
     },
     "dependencies": {