imapflow 2.2.7 → 2.2.9

package/dist/esm/tools.d.ts

@@ -293,9 +293,10 @@ export declare function getColorFlags(color: string | null | undefined): {
  * @param untagged - Parsed untagged IMAP response
  * @param mailbox - Current mailbox state object
  * @param idHashAlgorithm - Hash for the fallback message id, `md5` unless the client was told otherwise
+ * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
-export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string): Promise<FetchMessageObject>;
+export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string, connection?: ImapFlow): Promise<FetchMessageObject>;
 /**
  * Strips surrounding double quotes from a name string.
  *
@@ -364,8 +365,8 @@ export declare function formatDate(value: unknown): string | undefined;
  */
 export declare function formatDateTime(value: unknown): string | undefined;
 /**
- * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
- * and capitalizes system flags properly.
+ * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent) and for
+ * values that are not valid flags (keywords must be atoms), and capitalizes system flags properly.
  *
  * @param flag - Flag string to normalize
  * @returns Normalized flag string, or false if the flag cannot be set

package/dist/esm/tools.js

@@ -2,6 +2,7 @@
 import libmime from 'libmime';
 import { resolveCharset } from './charsets.js';
 import { compiler } from './handler/imap-handler.js';
+import imapFormalSyntax from './handler/imap-formal-syntax.js';
 import { createHash } from 'node:crypto';
 import { JPDecoder } from './jp-decoder.js';
 import iconv from 'iconv-lite';
@@ -280,7 +281,8 @@ export function buildStatusQueryAttributes(connection, statusQuery) {
                 }
                 break;
             case 'HIGHESTMODSEQ':
-                if (connection.capabilities.has('CONDSTORE')) {
+                // QRESYNC implies CONDSTORE (RFC 7162 3.2.3)
+                if (connection.capabilities.has('CONDSTORE') || connection.capabilities.has('QRESYNC')) {
                     attributes.push({ type: 'ATOM', value: key.toUpperCase() });
                 }
                 break;
@@ -661,24 +663,40 @@ export function getColorFlags(color) {
  * @param untagged - Parsed untagged IMAP response
  * @param mailbox - Current mailbox state object
  * @param idHashAlgorithm - Hash for the fallback message id, `md5` unless the client was told otherwise
+ * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
-export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm) {
+export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm, connection) {
     let map = {};
     // The sequence number indexes into mailbox state, so an unusable one is dropped rather
     // than coerced to NaN or Infinity
     map.seq = parseUintValue(untagged.command, MAX_UINT32_DIGITS) || undefined;
     let key;
+    // the <origin> of a partial section ("BODY[2]<1024>"), kept for the value that follows
+    let origin = false;
+    let partialOrigins;
+    let recordOrigin = (sectionKey) => {
+        if (origin !== false) {
+            if (!partialOrigins) {
+                partialOrigins = new Map();
+            }
+            partialOrigins.set(sectionKey, origin);
+        }
+    };
     let attributes = ((untagged.attributes && untagged.attributes[1]) || []);
     for (let i = 0, len = attributes.length; i < len; i++) {
         let attribute = attributes[i];
         if (i % 2 === 0) {
+            origin = false;
             key = (await compiler({
                 attributes: [attribute]
             }))
                 .toString()
                 .toLowerCase()
-                .replace(/<\d+(\.\d+)?>$/, '');
+                .replace(/<(\d+)(\.\d+)?>$/, (match, start) => {
+                origin = parseUintValue(start, MAX_UINT32_DIGITS);
+                return '';
+            });
             continue;
         }
         /* c8 ignore start */ // defensive: key is always a string produced by the compiler above
@@ -723,6 +741,7 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
             case 'body[]':
             case 'binary[]':
                 map.source = getBuffer(attribute);
+                recordOrigin('');
                 break;
             case 'uid':
                 // A UID feeds mailbox.uidNext one line below, and from there every range
@@ -769,7 +788,8 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
                 map.threadId = getString(attribute);
                 break;
             case 'x-gm-labels':
-                map.labels = new Set(getArray(attribute));
+                // labels are mailbox names, modified UTF-7 unless UTF-8 is enabled
+                map.labels = new Set(getArray(attribute).map(label => (connection ? decodePath(connection, label) : label)));
                 break;
             case 'rfc822.size':
                 map.size = getUint(attribute) || 0;
@@ -815,6 +835,7 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
                         map.bodyParts = new Map();
                     }
                     map.bodyParts.set(partKey, value);
+                    recordOrigin(partKey);
                     if (match[1].toLowerCase() === 'binary') {
                         // The part arrived via FETCH BINARY (RFC 3516, FETCH side folded
                         // into IMAP4rev2), so the server has already removed the
@@ -856,6 +877,10 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm)
                     .update([path, mailbox.uidValidity?.toString() || '', map.uid.toString()].join(':'))
                     .digest('hex');
     }
+    if (partialOrigins) {
+        // non-enumerable, so it stays out of logged and serialized fetch results
+        Object.defineProperty(map, 'partialOrigins', { value: partialOrigins, writable: true, configurable: true });
+    }
     if (map.flags) {
         let flagColor = getFlagColor(map.flags);
         if (flagColor) {
@@ -1298,14 +1323,22 @@ export function formatDateTime(value) {
     let timeStr = date.toISOString().substring(11, 19);
     return `${dateStr} ${timeStr} +0000`;
 }
+// the memoized ATOM-CHAR set of RFC 9051 section 9
+const atomChars = imapFormalSyntax['ATOM-CHAR'];
 /**
- * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
- * and capitalizes system flags properly.
+ * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent) and for
+ * values that are not valid flags (keywords must be atoms), and capitalizes system flags properly.
  *
  * @param flag - Flag string to normalize
  * @returns Normalized flag string, or false if the flag cannot be set
  */
 export function formatFlag(flag) {
+    // RFC 9051 section 9: flag-keyword is an atom and flag-extension is "\\" atom, the same check
+    // the compiler uses to decide what it can send unquoted
+    let atom = flag.charAt(0) === '\\' ? flag.slice(1) : flag;
+    if (!atom || imapFormalSyntax.verify(atom, atomChars()) >= 0) {
+        return false;
+    }
     switch (flag.toLowerCase()) {
         case '\\recent':
             // can not set or remove

package/dist/esm/types.d.ts

@@ -499,6 +499,8 @@ export interface FetchQueryObject {
         /** Include full message in the response, up to maxLength bytes */
         maxLength?: number | undefined;
     } | undefined;
+    /** Email ID (OBJECTID EMAILID or Gmail X-GM-MSGID) is always requested when the server supports either extension, so this is accepted but changes nothing */
+    emailId?: boolean | undefined;
     /** If true then include thread ID in the response (only if server supports either OBJECTID or X-GM-EXT-1 extensions) */
     threadId?: boolean | undefined;
     /** If true then include GMail labels in the response (only if server supports X-GM-EXT-1 extension) */
@@ -653,9 +655,11 @@ export interface DownloadOptions {
     maxBytes?: number | undefined;
     /** How large content parts to ask from the server. Defaults to 65536 */
     chunkSize?: number | undefined;
+    /** If true then requests the content with FETCH BINARY when the server supports it (BINARY or IMAP4rev2), so the server removes the transfer encoding */
+    binary?: boolean | undefined;
 }
 /** Options for downloadMany(): the download() options without `chunkSize`, as the parts come in one FETCH */
-export type DownloadManyOptions = Pick<DownloadOptions, 'uid' | 'maxBytes'>;
+export type DownloadManyOptions = Pick<DownloadOptions, 'uid' | 'maxBytes' | 'binary'>;
 export interface DownloadManyPart {
     meta: DownloadMeta;
     content?: Buffer | null | undefined;
@@ -706,6 +710,10 @@ export interface MailboxOpenOptions {
     readOnly?: boolean | undefined;
     /** Optional description for mailbox lock tracking */
     description?: string | undefined;
+    /** QRESYNC (RFC 7162): HIGHESTMODSEQ from an earlier session. With `uidValidity` and QRESYNC enabled, changes since then are reported as `flags` and `expunge` events. getMailboxLock() only applies it when it selects the mailbox, not when the mailbox is already open */
+    changedSince?: bigint | number | string | undefined;
+    /** QRESYNC (RFC 7162): the UIDVALIDITY known from the previous session, required with `changedSince` */
+    uidValidity?: bigint | number | string | undefined;
 }
 export interface MailboxLockOptions extends MailboxOpenOptions {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.2.7",
+    "version": "2.2.9",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -51,7 +51,8 @@
         "lint": "npm run typecheck && eslint .",
         "lint:fix": "eslint . --fix",
         "prepare": "npm run build",
-        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
+        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
+        "test:james": "bash test/integration/run-james-tests.sh"
     },
     "repository": {
         "type": "git",
@@ -74,12 +75,13 @@
         "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
         "globals": "17.13.0",
+        "imapkit": "4.1.0",
         "prettier": "3.9.9",
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",
         "typescript-eslint": "8.71.1",
-        "wrangler": "4.147.0"
+        "wrangler": "4.148.0"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.20",