imapflow 1.7.8 → 2.0.1

package/dist/cjs/commands/search.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = search;
+const tools_js_1 = require("../tools.js");
+const search_compiler_js_1 = require("../search-compiler.js");
+const esearch_parser_js_1 = require("./esearch-parser.js");
+/**
+ * Strips the leading (TAG "X") correlator list and the optional UID atom from an
+ * ESEARCH untagged response, leaving only the result keyword/value pairs.
+ * The IMAP parser represents parenthesized groups as plain Arrays, not objects
+ * with type: 'LIST'.
+ *
+ * @param attrs - Raw attribute array from the IMAP parser
+ * @returns Attribute array starting at the first result keyword
+ */
+const stripEsearchPrefix = (attrs) => {
+    let start = 0;
+    if (attrs[start] && Array.isArray(attrs[start]))
+        start++;
+    if (attrs[start] && typeof attrs[start].value === 'string' && attrs[start].value.toUpperCase() === 'UID')
+        start++;
+    return attrs.slice(start);
+};
+/**
+ * Searches for messages matching the specified criteria.
+ *
+ * @param connection - IMAP connection instance
+ * @param query - Search query object, or true/empty object to match all messages
+ * @param options - Search options
+ * @param options.uid - If true, use UID SEARCH instead of SEARCH
+ * @param options.returnOptions - ESEARCH RETURN options. When present AND the
+ *   server advertises ESEARCH capability, triggers ESEARCH and returns an ESearchResult.
+ *   Items are strings ('MIN','MAX','COUNT','ALL') or objects ({ partial: '1:100' }).
+ *   When server lacks ESEARCH, falls back to plain SEARCH and returns number[].
+ */
+async function search(connection, query, options) {
+    if (connection.state !== connection.states.SELECTED) {
+        // nothing to do here
+        return false;
+    }
+    options = options || {};
+    let attributes;
+    // Three query branches:
+    // 1. Empty/truthy/all-only query -> use IMAP "SEARCH ALL" to match every message
+    // 2. Non-empty object -> compile into IMAP SEARCH criteria via searchCompiler
+    // 3. Anything else (unexpected type) -> bail out with false
+    if (!query || query === true || (typeof query === 'object' && (!Object.keys(query).length || (Object.keys(query).length === 1 && query.all)))) {
+        // search for all messages
+        attributes = [{ type: 'ATOM', value: 'ALL' }];
+    }
+    else if (query && typeof query === 'object') {
+        // normal query
+        attributes = (0, search_compiler_js_1.searchCompiler)(connection, query);
+    }
+    else {
+        return false;
+    }
+    // ESEARCH is part of base IMAP4rev2
+    const useEsearch = options.returnOptions && options.returnOptions.length > 0 && (0, tools_js_1.hasCapability)(connection, 'ESEARCH');
+    if (useEsearch) {
+        // Build RETURN (...) item list
+        const returnItems = [];
+        for (const opt of options.returnOptions) {
+            if (typeof opt === 'string') {
+                returnItems.push({ type: 'ATOM', value: opt.toUpperCase() });
+            }
+            else if (opt && typeof opt.partial === 'string') {
+                // RFC 9394: PARTIAL is an atom followed by the range atom, both inside RETURN (...)
+                returnItems.push({ type: 'ATOM', value: 'PARTIAL' });
+                returnItems.push({ type: 'ATOM', value: opt.partial });
+            }
+        }
+        // If all returnOptions entries were invalid (e.g. objects lacking a string
+        // `partial` field), returnItems would be empty. Emitting "RETURN ()" is
+        // technically valid per RFC 4731 but returns nothing useful. Fall through
+        // to the legacy SEARCH path instead so the caller gets a usable result.
+        if (returnItems.length > 0) {
+            const returnClause = [{ type: 'ATOM', value: 'RETURN' }, returnItems];
+            let esearchResult = {};
+            let response;
+            try {
+                response = await connection.exec(options.uid ? 'UID SEARCH' : 'SEARCH', [...returnClause, ...attributes], {
+                    untagged: {
+                        ESEARCH: async (untagged) => {
+                            if (!untagged || !untagged.attributes)
+                                return;
+                            esearchResult = (0, esearch_parser_js_1.parseEsearchResponse)(stripEsearchPrefix(untagged.attributes));
+                        }
+                    }
+                });
+                response.next();
+                return esearchResult;
+            }
+            catch (err) {
+                await (0, tools_js_1.enhanceCommandError)(err);
+                connection.log.warn({ err, cid: connection.id });
+                return false;
+            }
+        }
+        // returnItems was empty - fall through to legacy SEARCH path below
+    }
+    // Legacy SEARCH path (no returnOptions, or server lacks ESEARCH)
+    // Use a Set to deduplicate sequence numbers/UIDs - servers may return
+    // duplicates across multiple untagged SEARCH responses.
+    let results = new Set();
+    let response;
+    try {
+        response = await connection.exec(options.uid ? 'UID SEARCH' : 'SEARCH', attributes, {
+            untagged: {
+                SEARCH: async (untagged) => {
+                    if (untagged && untagged.attributes && untagged.attributes.length) {
+                        let truncated = false;
+                        let discarded = false;
+                        for (let attribute of untagged.attributes) {
+                            // The result set is server-controlled and accumulated across
+                            // responses, so stop at the same absolute ceiling expandRange()
+                            // uses - a server streaming SEARCH responses could otherwise
+                            // grow the set until the process runs out of memory
+                            /* c8 ignore next 4 */ // reaching the ceiling needs 2^24 accumulated results, which no unit test can produce in reasonable time
+                            if (results.size >= tools_js_1.EXPANDED_RANGE_LIMIT) {
+                                truncated = true;
+                                break;
+                            }
+                            // Same nz-number check the ESEARCH branch below applies. isNaN()
+                            // is not enough: it passes '1e400' (Infinity), '-3' and '2.5', and
+                            // a single one of those makes the sequence set compiled from this
+                            // result set invalid, failing the caller's whole follow-up command
+                            let value = attribute && typeof attribute.value === 'string' ? Number(attribute.value) : NaN;
+                            if (!(0, tools_js_1.isValidSequenceValue)(value)) {
+                                discarded = true;
+                                continue;
+                            }
+                            results.add(value);
+                        }
+                        if (truncated || discarded) {
+                            connection.log.warn({
+                                msg: 'Invalid entries in the SEARCH result',
+                                truncated,
+                                discarded,
+                                cid: connection.id
+                            });
+                        }
+                    }
+                },
+                // IMAP4rev2 servers answer even a plain SEARCH with an untagged
+                // ESEARCH response (RFC 9051 deprecated the SEARCH response), so
+                // both forms are collected into the same result set
+                ESEARCH: async (untagged) => {
+                    if (!untagged || !untagged.attributes) {
+                        return;
+                    }
+                    let parsed = (0, esearch_parser_js_1.parseEsearchResponse)(stripEsearchPrefix(untagged.attributes));
+                    if (parsed.all) {
+                        // Walk the compact sequence-set directly into the Set - the ALL
+                        // result may cover the entire mailbox, so expanding it into an
+                        // intermediate array first would double the peak memory use.
+                        // The set comes from an untrusted server: endpoints must be
+                        // valid nz-numbers ('Infinity' would otherwise loop forever)
+                        // and the expansion stops at the mailbox EXISTS count - a
+                        // conforming server cannot match more messages than exist, so
+                        // a hostile range like 1:4294967295 cannot exhaust memory.
+                        // A '*' means "largest number in use": that is exactly EXISTS
+                        // for message sequence numbers, while server-sent UID sets may
+                        // not contain '*' at all (RFC 9051 section 4.1.1), so UID
+                        // parts with '*' are dropped
+                        let existsCount = () => (connection.mailbox && connection.mailbox.exists) || 0;
+                        // The mailbox EXISTS count is itself server-supplied and can be
+                        // absurdly large, so the budget is additionally capped at the same
+                        // absolute ceiling expandRange() uses - a hostile server cannot
+                        // bypass it by inflating EXISTS first
+                        let overBudget = () => results.size >= existsCount() || results.size >= tools_js_1.EXPANDED_RANGE_LIMIT;
+                        let resolveId = (part) => (part === '*' ? (options.uid ? 0 : existsCount()) : Number(part));
+                        let truncated = false;
+                        let discarded = false;
+                        sequenceSetLoop: for (let part of parsed.all.split(',')) {
+                            part = part.trim();
+                            let colon = part.indexOf(':');
+                            if (colon < 0) {
+                                let value = resolveId(part);
+                                if (!(0, tools_js_1.isValidSequenceValue)(value)) {
+                                    discarded = true;
+                                    continue;
+                                }
+                                if (overBudget()) {
+                                    truncated = true;
+                                    break;
+                                }
+                                results.add(value);
+                                continue;
+                            }
+                            let first = resolveId(part.substr(0, colon));
+                            let second = resolveId(part.substr(colon + 1));
+                            if (!(0, tools_js_1.isValidSequenceValue)(first) || !(0, tools_js_1.isValidSequenceValue)(second)) {
+                                discarded = true;
+                                continue;
+                            }
+                            for (let id = Math.min(first, second); id <= Math.max(first, second); id++) {
+                                if (overBudget()) {
+                                    truncated = true;
+                                    break sequenceSetLoop;
+                                }
+                                results.add(id);
+                            }
+                        }
+                        if (truncated || discarded) {
+                            connection.log.warn({
+                                msg: 'Invalid entries in the ESEARCH ALL result',
+                                truncated,
+                                discarded,
+                                cid: connection.id
+                            });
+                        }
+                    }
+                }
+            }
+        });
+        response.next();
+        // Sort numerically for consistent, predictable output order
+        return Array.from(results).sort((a, b) => a - b);
+    }
+    catch (err) {
+        await (0, tools_js_1.enhanceCommandError)(err);
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/select.d.ts

@@ -0,0 +1,25 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { MailboxObject, MailboxOpenOptions } from '../types.js';
+/**
+ * Options for SELECT/EXAMINE: the public open options plus the QRESYNC resynchronization
+ * parameters, which are only honored when the QRESYNC extension has been enabled
+ */
+export interface SelectOptions extends MailboxOpenOptions {
+    /** QRESYNC modseq value to fetch changes since */
+    changedSince?: bigint | number | string | undefined;
+    /** QRESYNC UID validity value */
+    uidValidity?: bigint | number | string | undefined;
+}
+/**
+ * Selects or examines a mailbox, making it the current mailbox for subsequent operations.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to select
+ * @param options - Select options
+ * @param options.readOnly - If true, use EXAMINE instead of SELECT (read-only access)
+ * @param options.changedSince - QRESYNC modseq value to fetch changes since
+ * @param options.uidValidity - QRESYNC UID validity value
+ * @returns Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
+ * @throws If the SELECT/EXAMINE command fails
+ */
+export default function select(connection: ImapFlow, pathInput: string | string[], options?: SelectOptions | undefined): Promise<MailboxObject | undefined>;

package/dist/cjs/commands/select.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = select;
+const tools_js_1 = require("../tools.js");
+// Response codes carrying a value that SELECT/EXAMINE may write to the mailbox object, keyed by
+// the lowercased code, mapped to the fixed public property name and the parser for the value.
+// Every parser returns false for a value it cannot use, and the field is then left unset.
+//
+// This is an allowlist on purpose. The mailbox object is API surface: without one, an arbitrary
+// server-sent [KEY value] code could overwrite `path` (defeating the DELETE/RENAME guards that
+// compare paths) or `flags`, and a parenthesized value under "__proto__" would replace the
+// object's prototype. The lookup itself is on a null-prototype object for the same reason - the
+// key is lowercased, so "constructor" would otherwise resolve to an inherited member.
+const VALUED_RESPONSE_CODES = Object.assign(Object.create(null), {
+    // CONDSTORE (RFC 7162): highest mod-sequence value for the mailbox, used for incremental
+    // sync. Stored as a BigInt since modseq values can exceed Number.MAX_SAFE_INTEGER.
+    //
+    // A value that is not a bounded digit run is dropped rather than stored raw: every consumer
+    // compares highestModseq relationally, and a relational compare against a non-numeric string
+    // is false in both directions, so the value could never advance and delta sync would stop.
+    highestmodseq: { key: 'highestModseq', parse: (value) => (0, tools_js_1.parseBigIntValue)(value) },
+    // Unique identifier validity. If this changes between sessions, all previously cached UIDs
+    // are invalid and the client must re-sync from scratch. Nominally 32-bit, but stored as a
+    // BigInt precisely so a server that exceeds that still round-trips, hence the wider bound.
+    uidvalidity: { key: 'uidValidity', parse: (value) => (0, tools_js_1.parseBigIntValue)(value) },
+    // The next UID to be assigned in this mailbox, useful for detecting new arrivals. A huge
+    // digit run would coerce to Infinity and corrupt every later UID range computation.
+    uidnext: { key: 'uidNext', parse: (value) => (0, tools_js_1.parseUintValue)(value, tools_js_1.MAX_UINT32_DIGITS) },
+    // Sequence number of the first unseen message (RFC 3501 section 7.1). Not a count of unseen
+    // messages - use mailboxStatus() with {unseen: true} for that.
+    unseen: { key: 'unseen', parse: (value) => (0, tools_js_1.parseUintValue)(value, tools_js_1.MAX_UINT32_DIGITS) },
+    // APPENDLIMIT (RFC 7889): largest message size in octets the server accepts for APPEND into
+    // this mailbox. Spelled all lowercase, unlike the camelCase fields around it, because that is
+    // the name this object has always exposed.
+    appendlimit: { key: 'appendlimit', parse: (value) => (0, tools_js_1.parseUintValue)(value) },
+    // OBJECTID (RFC 8474): server-assigned mailbox identifier that survives renames. Sent as a
+    // parenthesized list, but servers in the wild send it bare too.
+    mailboxid: {
+        key: 'mailboxId',
+        parse: (value) => (Array.isArray(value) ? value.length > 0 && value[0] : typeof value === 'string' && value)
+    },
+    // Flags the client may change permanently on messages in this mailbox, including \* if the
+    // server allows custom flags. Only the parenthesized form carries flags, and a malformed
+    // value must leave permanentFlags unset rather than set an empty Set: canUseFlag() reads
+    // unset as permissive and empty as deny-all, so an empty Set would turn every later flag
+    // update into a silent no-op for the rest of the session.
+    permanentflags: { key: 'permanentFlags', parse: (value) => Array.isArray(value) && new Set(value) }
+});
+/**
+ * Selects or examines a mailbox, making it the current mailbox for subsequent operations.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to select
+ * @param options - Select options
+ * @param options.readOnly - If true, use EXAMINE instead of SELECT (read-only access)
+ * @param options.changedSince - QRESYNC modseq value to fetch changes since
+ * @param options.uidValidity - QRESYNC UID validity value
+ * @returns Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
+ * @throws If the SELECT/EXAMINE command fails
+ */
+async function select(connection, pathInput, options) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
+        // nothing to do here
+        return;
+    }
+    options = options || {};
+    let path = (0, tools_js_1.normalizePath)(connection, pathInput);
+    // Ensure we have folder metadata (delimiter, flags, specialUse) by running LIST if needed.
+    // This is cached in connection.folders to avoid repeated LIST calls.
+    // Note: this uses run() rather than runInternal(), so it terminates a running IDLE first,
+    // which is what a caller-issued mailboxOpen() needs. Fallback polling reaches SELECT through
+    // runInternal(), and on a cache miss this LIST awaits the polling session's own preCheck and
+    // so cancels that session. Not a deadlock, and only reachable when the folder is uncached,
+    // but a polled SELECT of an unlisted folder ends the poll early.
+    if (!connection.folders.has(path)) {
+        let folders = await connection.run('LIST', '', path);
+        if (!folders) {
+            throw new Error('Failed to fetch folders');
+        }
+        folders.forEach(folder => {
+            connection.folders.set(folder.path, folder);
+        });
+    }
+    let folderListData = connection.folders.has(path) ? connection.folders.get(path) : false;
+    let response;
+    try {
+        let map = { path };
+        if (folderListData) {
+            ['delimiter', 'specialUse', 'subscribed', 'listed'].forEach(key => {
+                if (folderListData[key]) {
+                    map[key] = folderListData[key];
+                }
+            });
+        }
+        // QRESYNC (RFC 7162): allows efficient mailbox resynchronization by sending
+        // the last known UIDVALIDITY and HIGHESTMODSEQ. Server responds with only
+        // the changes (new flags, expunged UIDs) since that point.
+        let extraArgs = [];
+        if (connection.enabled.has('QRESYNC') && options.changedSince && options.uidValidity) {
+            extraArgs.push([
+                { type: 'ATOM', value: 'QRESYNC' },
+                [
+                    { type: 'ATOM', value: options.uidValidity?.toString() },
+                    { type: 'ATOM', value: options.changedSince.toString() }
+                ]
+            ]);
+            map.qresync = true;
+        }
+        let encodedPath = (0, tools_js_1.encodePath)(connection, path);
+        // SELECT opens the mailbox read-write; EXAMINE opens it read-only.
+        // Path encoding: if the encoded path contains '&' (UTF-7 encoding marker),
+        // send as quoted STRING to avoid parser issues with the ampersand.
+        let selectCommand = {
+            command: !options.readOnly ? 'SELECT' : 'EXAMINE',
+            /* c8 ignore next */ // extraArgs is always initialised to an array, so the [] fallback is unreachable
+            arguments: [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }].concat(extraArgs || [])
+        };
+        response = await connection.exec(selectCommand.command, selectCommand.arguments, {
+            untagged: {
+                // Untagged OK responses carry response codes in brackets, e.g.:
+                // * OK [UIDVALIDITY 1234] UIDs valid
+                // * OK [PERMANENTFLAGS (\Seen \Answered \*)] Flags permitted
+                // The section array holds the parsed bracket contents: section[0] is the
+                // key (e.g., "UIDVALIDITY"), section[1] is the value or list.
+                OK: async (untagged) => {
+                    if (!untagged.attributes || !untagged.attributes.length) {
+                        return;
+                    }
+                    let section = !untagged.attributes[0].value && untagged.attributes[0].section;
+                    // Handle response codes with a key-value pair (section has 2+ elements)
+                    if (section && section.length > 1 && section[0] && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
+                        let key = section[0].value.toLowerCase();
+                        let value;
+                        // Value can be a single string or a list of strings (e.g., PERMANENTFLAGS).
+                        // section[1] can be a parsed NIL (null), and so can any element inside a
+                        // parenthesized list, so both levels need the guard
+                        if (section[1] && typeof section[1].value === 'string') {
+                            value = section[1].value;
+                        }
+                        else if (Array.isArray(section[1])) {
+                            value = (0, tools_js_1.getStringList)(section[1]);
+                        }
+                        let field = VALUED_RESPONSE_CODES[key];
+                        if (field) {
+                            let parsed = field.parse(value);
+                            if (parsed !== false) {
+                                map[field.key] = parsed;
+                            }
+                        }
+                    }
+                    // Handle response codes with only a keyword (no value), e.g., [NOMODSEQ].
+                    // NOMODSEQ means the mailbox does not support mod-sequences, so the
+                    // CONDSTORE/QRESYNC features are unavailable for it.
+                    if (section &&
+                        section.length === 1 &&
+                        section[0] &&
+                        section[0].type === 'ATOM' &&
+                        section[0].value?.toUpperCase() === 'NOMODSEQ') {
+                        map.noModseq = true;
+                    }
+                },
+                // Untagged FLAGS response lists all flags defined for this mailbox
+                // (both system flags and custom flags). Example: * FLAGS (\Seen \Answered \Flagged)
+                FLAGS: async (untagged) => {
+                    if (!untagged.attributes || !untagged.attributes.length || !Array.isArray(untagged.attributes[0])) {
+                        return;
+                    }
+                    map.flags = new Set((0, tools_js_1.getStringList)(untagged.attributes[0]));
+                },
+                // Untagged EXISTS response: "* <count> EXISTS" tells us the total number
+                // of messages in the mailbox. The count is in the command field (numeric prefix).
+                EXISTS: async (untagged) => {
+                    // Not a usable count: anything but a bounded digit run. A long digit run
+                    // coerces to Infinity, which would corrupt every later range computation
+                    let num = (0, tools_js_1.parseUintValue)(untagged.command, tools_js_1.MAX_UINT32_DIGITS);
+                    if (num === false) {
+                        return false;
+                    }
+                    map.exists = num;
+                },
+                // VANISHED responses (QRESYNC): server reports UIDs that have been expunged
+                // since the client's last known state. Only received when QRESYNC was requested.
+                // A dummy mailbox object is passed because the mailbox isn't officially open yet.
+                VANISHED: async (untagged) => {
+                    await connection.untaggedVanished(untagged, { path, uidNext: false, uidValidity: false });
+                },
+                // Untagged FETCH during SELECT/EXAMINE: only occurs with QRESYNC, delivering
+                // updated flags for messages that changed since the client's last modseq.
+                FETCH: async (untagged) => {
+                    await connection.untaggedFetch(untagged, { path, uidNext: false, uidValidity: false });
+                }
+            }
+        });
+        // The tagged OK response to SELECT/EXAMINE includes [READ-ONLY] or [READ-WRITE]
+        // in its response code, indicating the access mode the server granted. A tagged OK
+        // with no resp-text has no `attributes` property at all, and unlike the untagged
+        // handlers above this runs in the command body, where a throw would tear down the
+        // mailbox state the server has actually selected.
+        let okAttributes = (response.response && response.response.attributes) || [];
+        let section = okAttributes[0] && !okAttributes[0].value && okAttributes[0].section;
+        if (section && section.length && section[0] && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
+            map.readOnly = section[0].value.toUpperCase() === 'READ-ONLY';
+        }
+        // Validate QRESYNC preconditions (RFC 7162 Section 3.2.5):
+        // QRESYNC results are only valid if UIDVALIDITY matches, HIGHESTMODSEQ is
+        // present, and the mailbox supports mod-sequences. If any condition fails,
+        // the client cannot trust the incremental updates and must do a full resync.
+        if (map.qresync && (options.uidValidity !== map.uidValidity || !map.highestModseq || map.noModseq)) {
+            map.qresync = false;
+        }
+        // Transition mailbox state: save previous mailbox reference, temporarily
+        // clear it, then emit events and set the new mailbox.
+        let currentMailbox = connection.mailbox;
+        connection.mailbox = false;
+        // Emit mailboxClose if we're switching from a different mailbox.
+        // Re-selecting the same mailbox (e.g., for resync) does not trigger close/open.
+        if (currentMailbox && currentMailbox.path !== path) {
+            connection.emit('mailboxClose', currentMailbox);
+        }
+        connection.mailbox = map;
+        // Save the SELECT command for potential re-use (e.g., NOOP fallback polling
+        // re-issues the SELECT to detect changes on servers without IDLE support).
+        connection.currentSelectCommand = selectCommand;
+        connection.state = connection.states.SELECTED;
+        if (!currentMailbox || currentMailbox.path !== path) {
+            connection.emit('mailboxOpen', connection.mailbox);
+        }
+        response.next();
+        return map;
+    }
+    catch (err) {
+        await (0, tools_js_1.enhanceCommandError)(err);
+        // If SELECT/EXAMINE fails while a mailbox was already selected, we must
+        // reset to AUTHENTICATED state since the server has implicitly deselected
+        // the previous mailbox on failure (RFC 3501 Section 6.3.1).
+        if (connection.state === connection.states.SELECTED) {
+            let currentMailbox = connection.mailbox;
+            connection.mailbox = false;
+            connection.currentSelectCommand = false;
+            connection.state = connection.states.AUTHENTICATED;
+            if (currentMailbox) {
+                connection.emit('mailboxClose', currentMailbox);
+            }
+        }
+        connection.log.warn({ err, cid: connection.id });
+        throw err;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/starttls.d.ts

@@ -0,0 +1,8 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Initiates STARTTLS connection upgrade.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True if STARTTLS was initiated, false if not supported or already secure
+ */
+export default function starttls(connection: ImapFlow): Promise<boolean>;

package/dist/cjs/commands/starttls.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = starttls;
+/**
+ * Initiates STARTTLS connection upgrade.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True if STARTTLS was initiated, false if not supported or already secure
+ */
+async function starttls(connection) {
+    if (!connection.capabilities.has('STARTTLS') || connection.secureConnection) {
+        // nothing to do here
+        return false;
+    }
+    let response;
+    try {
+        response = await connection.exec('STARTTLS');
+        // Whether the server sent anything after the STARTTLS OK and before the TLS
+        // handshake. upgradeToSTARTTLS() uses this to reject a plaintext injection.
+        connection._starttlsHadTrailingData = !!(response && response.hasTrailingData);
+        response.next();
+        return true;
+    }
+    catch (err) {
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/status-fields.d.ts

@@ -0,0 +1,14 @@
+import type { ImapAttributeList } from '../handler/types.js';
+/**
+ * A parsed STATUS value: counts and sizes as numbers, UIDVALIDITY and HIGHESTMODSEQ as BigInts
+ */
+export type StatusFieldValue = number | bigint;
+/**
+ * Walks a STATUS data-item list - alternating item-name and item-value tokens - and reports
+ * every recognized field that parsed successfully. Unknown item names and unusable values are
+ * skipped, so one bad field never costs the rest of the response.
+ *
+ * @param list - Parsed attribute list from the untagged STATUS response.
+ * @param onField - Called as (key, value) for each usable field.
+ */
+export declare const parseStatusList: (list: ImapAttributeList, onField: (key: string, value: StatusFieldValue) => void) => void;

package/dist/cjs/commands/status-fields.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStatusList = void 0;
+const tools_js_1 = require("../tools.js");
+// STATUS data items (RFC 3501 section 6.3.10, RFC 7162 for HIGHESTMODSEQ, RFC 9051 for SIZE
+// and DELETED) mapped to the property name each one is exposed under, together with the
+// parser that turns the raw response token into a usable value. Shared by the STATUS command
+// and by the inline STATUS responses of LIST-STATUS (RFC 5819) so the two cannot drift apart.
+//
+// Every parser rejects anything that is not a bounded decimal digit run, returning false.
+// These values are server-controlled and several of them are written straight into the live
+// mailbox state, where a NaN or a value coerced to Infinity corrupts every later range
+// computation. A plain isNaN() test is not enough: it passes '1e5', ' 12 ' and 'Infinity',
+// and BigInt() throws on all three, aborting the walk over the remaining fields.
+const uint32 = (value) => (0, tools_js_1.parseUintValue)(value, tools_js_1.MAX_UINT32_DIGITS);
+const STATUS_FIELDS = {
+    MESSAGES: { key: 'messages', parser: uint32 },
+    RECENT: { key: 'recent', parser: uint32 },
+    UIDNEXT: { key: 'uidNext', parser: uint32 },
+    // Nominally 32-bit, but stored as a BigInt precisely so a server that exceeds that still
+    // round-trips, so the wider bound applies
+    UIDVALIDITY: { key: 'uidValidity', parser: value => (0, tools_js_1.parseBigIntValue)(value) },
+    UNSEEN: { key: 'unseen', parser: uint32 },
+    HIGHESTMODSEQ: { key: 'highestModseq', parser: value => (0, tools_js_1.parseBigIntValue)(value) },
+    // IMAP4rev2 additions (RFC 9051): total mailbox size in octets (number64, exact as a JS
+    // number up to 2^53-1) and count of messages carrying the \Deleted flag
+    SIZE: { key: 'size', parser: value => (0, tools_js_1.parseUintValue)(value) },
+    DELETED: { key: 'deleted', parser: uint32 }
+};
+/**
+ * Walks a STATUS data-item list - alternating item-name and item-value tokens - and reports
+ * every recognized field that parsed successfully. Unknown item names and unusable values are
+ * skipped, so one bad field never costs the rest of the response.
+ *
+ * @param list - Parsed attribute list from the untagged STATUS response.
+ * @param onField - Called as (key, value) for each usable field.
+ */
+const parseStatusList = (list, onField) => {
+    let name;
+    list.forEach((entry, i) => {
+        if (i % 2 === 0) {
+            name = entry && typeof entry.value === 'string' ? entry.value : false;
+            return;
+        }
+        if (!name || !entry) {
+            return;
+        }
+        // The item name is server-controlled, but uppercasing it before the lookup means no
+        // Object.prototype member can be reached: every builtin name has a lowercase letter.
+        const field = STATUS_FIELDS[name.toUpperCase()];
+        if (!field) {
+            return;
+        }
+        const value = field.parser(entry.value);
+        if (value === false) {
+            return;
+        }
+        onField(field.key, value);
+    });
+};
+exports.parseStatusList = parseStatusList;

package/dist/cjs/commands/status.d.ts

@@ -0,0 +1,12 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { StatusObject, StatusQuery } from '../types.js';
+/**
+ * Requests status information about a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to query
+ * @param query - Status data items to request (e.g., {messages: true, uidNext: true, unseen: true})
+ * @returns Status information object, or false if preconditions not met or on failure
+ * @throws {Error} If the mailbox does not exist
+ */
+export default function status(connection: ImapFlow, path: string | string[], query: StatusQuery | undefined): Promise<StatusObject | false>;