imapflow 2.3.0 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [2.4.1](https://github.com/postalsys/imapflow/compare/v2.4.0...v2.4.1) (2026-10-14)
+
+
+### Bug Fixes
+
+* **download:** bump libbase64 to decode padded base64 parts in linear memory ([1c83261](https://github.com/postalsys/imapflow/commit/1c832614dda83160de1387f08e7592add65e2779))
+
+## [2.4.0](https://github.com/postalsys/imapflow/compare/v2.3.0...v2.4.0) (2026-10-10)
+
+
+### Features
+
+* re-raise unexpected parser exceptions as coded ParserErrorInternal errors ([dda3f7e](https://github.com/postalsys/imapflow/commit/dda3f7e71e3c227479763a8c6af617fd4f57679a))
+
+
+### Bug Fixes
+
+* keep append literals in sync with their data and fail downloads cleanly ([752248e](https://github.com/postalsys/imapflow/commit/752248e07fd8930cb0943287c32e3bab88484d80))
+
 ## [2.3.0](https://github.com/postalsys/imapflow/compare/v2.2.11...v2.3.0) (2026-10-08)
 
 

package/SECURITY.md

@@ -1,88 +1,159 @@
 # Security Policy
 
-ImapFlow is a Node.js IMAP client library. It opens TLS/cleartext connections to
-IMAP servers, sends account credentials, and parses untrusted protocol responses
-from those servers. Because it handles credentials and processes data from
-remote servers that may be malicious or buggy, we take security reports
-seriously and aim to respond quickly.
+ImapFlow is a Node.js IMAP client library. It opens TLS and cleartext
+connections to IMAP servers, sends account credentials, and parses untrusted
+protocol responses from servers that may be malicious or buggy. We welcome
+responsible reports of vulnerabilities that present a credible security risk to
+users. Please distinguish security vulnerabilities from ordinary bugs, unusual
+edge cases, and hardening suggestions.
 
 ## Supported Versions
 
-Security fixes are released only against the latest version. We do not backport
-patches to older releases - upgrading to the current release line is the
-supported way to receive security updates.
+Security fixes are released only against the latest major version. We do not
+backport patches to older majors, so upgrading to the current release line is
+the supported way to receive security updates.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.x     | :white_check_mark: |
-| < 1.0   | :x:                |
+| 2.x     | :white_check_mark: |
+| < 2.0   | :x:                |
 
-If you are on an older version, please upgrade. See the release notes at
+If you are on an older major, please upgrade. See the release notes at
 <https://github.com/postalsys/imapflow/releases> before updating.
 
+## What Qualifies as a Security Vulnerability
+
+A security report should identify a realistic way for an attacker to cross a
+security boundary in a supported version of ImapFlow. Unexpected behavior, a
+failing test, or a technically correct proof of concept is not sufficient on its
+own to establish security impact.
+
+In particular, explain:
+
+- **Attacker capabilities:** Who is the attacker, and what inputs, systems, or
+  responses can they control _without_ already having the privileges or secrets
+  they are trying to gain?
+- **Attack path:** How does attacker-controlled input reach the affected code
+  through a supported public API or a realistic application integration?
+- **Prerequisites:** What configuration and user actions are required? If the
+  attack depends on unusual options or deliberately malformed input, explain why
+  those conditions could arise in a real application.
+- **Impact:** What confidentiality, integrity, or availability boundary is
+  crossed, and what can the attacker achieve as a result?
+
+A vulnerability involving an optional or less common feature can still qualify
+if these conditions are met. Conversely, the existence of a defensive check in
+the code does not, by itself, establish that every bypass of that check has a
+realistic security impact.
+
 ## Reporting a Vulnerability
 
-**Please do not report security vulnerabilities through public GitHub issues,
-pull requests, or discussions.**
+**Do not disclose suspected exploitable vulnerabilities through public GitHub
+issues, pull requests, or discussions before coordinating with the
+maintainers.**
 
 Report privately through one of the following channels:
 
-1. **GitHub Security Advisories (preferred).** Open a private report at
-   <https://github.com/postalsys/imapflow/security/advisories/new>. This keeps
-   the discussion private until a fix is published and lets us credit you.
-2. **Email.** Send details to **andris@postalsys.com** (the contact listed in
-   [`SECURITY.txt`](SECURITY.txt)). Encrypt sensitive details with the PGP key
-   referenced there if possible.
-
-When reporting, please include as much of the following as you can:
-
-- The affected version(s) and environment (ImapFlow version, Node.js version,
-  OS).
-- The component involved (e.g. the IMAP response stream/parser, literal and line
-  handling, TLS/STARTTLS upgrade, credential handling, the command compiler, or
-  the public client API).
-- A clear description of the issue and its impact (e.g. memory exhaustion or
-  denial of service from a malicious server, parser crash, credential
-  disclosure, TLS verification bypass, injection into the IMAP command stream,
-  prototype pollution, information disclosure).
-- A minimal proof of concept or reproduction steps - ideally a sample server
-  response or a short script that triggers the issue.
-- Any suggested remediation, if you have one.
-
-We are a small team, so there is no guaranteed response time - sometimes reports
-are handled within hours, sometimes they take longer. Accepted issues are fixed
-in a new release and coordinated through a GitHub Security Advisory, and
-reporters who wish to be named are credited.
-
-## CVEs
-
-We track and disclose vulnerabilities through GitHub Security Advisories. We do
-not request or manage CVE identifiers ourselves. If you need a CVE assigned for a
-reported issue, please request one yourself - for example, through GitHub's own
-CVE request flow on the published advisory, or another CNA.
+1. **GitHub Security Advisories (preferred):**
+   <https://github.com/postalsys/imapflow/security/advisories/new>.
+2. **Email:** **andris@postalsys.com**, as listed in
+   [`SECURITY.txt`](SECURITY.txt). Encrypt sensitive details if possible.
+
+### Required Information
+
+Please provide enough information to evaluate both the defect and its security
+impact. Reports should include:
+
+1. The affected ImapFlow version or commit, Node.js version, and relevant
+   configuration.
+2. A concise description of the issue and the affected public API or code path
+   (for example the IMAP response stream and parser, literal and line handling,
+   the TLS/STARTTLS upgrade, credential handling, the command compiler, or the
+   public client API. A sample server response is often the most useful
+   reproduction).
+3. A minimal, tested reproduction, including steps to run it, expected behavior,
+   and observed behavior.
+4. A concrete threat model: attacker control, prerequisites, trust boundary, and
+   resulting impact. Clearly distinguish what your reproduction proves from what
+   you believe might be possible.
+5. An explanation of why the issue affects real deployments beyond a
+   deliberately constructed test setup, where this is not obvious.
+
+A suggested fix is welcome but does not replace an explanation of
+exploitability. A complete real-world exploit is not always necessary, but the
+report must make a credible security impact clear.
+
+### Reports That May Be Treated as Ordinary Bugs
+
+The following generally do **not** qualify for private security handling unless
+you can demonstrate an additional, meaningful security boundary crossing:
+
+- Issues that require the attacker to control trusted application code,
+  administrator-only configuration, or the secret they supposedly extract.
+- Problems caused solely by application-level misuse, exposed credentials, or
+  insecure deployment choices outside ImapFlow's control.
+- Contrived proof-of-concept setups where the tester controls both sides of a
+  request, without explaining how a separate attacker could trigger the issue.
+- Parser quirks, unexpected behavior, and bypasses of internal checks with no
+  demonstrated security impact.
+- Speculative findings based only on static analysis or an automated tool's
+  assessment, without a verified reproduction and credible attack scenario.
+
+These may still be valid bugs and may be considered through the normal issue
+tracker. Please coordinate before making any potentially exploitable details
+public. Classification as a bug does not guarantee a fix or a particular
+priority.
+
+### Automated and AI-Assisted Reports
+
+Automated analysis and AI tools are welcome as research aids, but the person
+submitting a report is responsible for verifying its claims. **Do not submit
+bulk, unverified, or speculative AI-generated findings.** Test each finding
+against a supported release and establish the actual security impact. Reports
+that do not meet the requirements above may be closed without further
+investigation or individual feedback; they can be resubmitted with stronger
+evidence.
+
+## Triage and Disclosure
+
+ImapFlow is maintained by a small team, and there is **no guaranteed response or
+resolution time**. Reports are prioritized based on demonstrated impact,
+exploitability, affected usage, and available maintenance resources.
+
+A private report does not automatically become a security advisory. Confirmed
+vulnerabilities may be fixed and disclosed through GitHub Security Advisories;
+other findings may be closed, deferred, or handled as ordinary bugs. Please do
+not disclose details of an unresolved, potentially exploitable issue publicly
+without coordinating with the maintainers.
+
+## CVEs and Credit
+
+We do not request or manage CVE identifiers. A report being acknowledged, a bug
+being fixed, or a pull request being merged does **not** mean that ImapFlow has
+confirmed a security vulnerability or endorsed a CVE assignment. We do not
+guarantee advisories, CVE identifiers, or public credit for reports. For
+confirmed vulnerabilities disclosed through an advisory, substantive reporters
+may be credited if they wish.
 
 ## Scope
 
-In scope: the ImapFlow library source in this repository - the IMAP response
+In scope: the ImapFlow library source in this repository: the IMAP response
 stream and token parser (including handling of hostile or malformed server
-responses, literals, line lengths, and resource/DoS bounds), the TLS and
-STARTTLS upgrade path and certificate handling, credential handling during
+responses, literals, line lengths, and resource bounds), the TLS and STARTTLS
+upgrade path and certificate handling, credential handling during
 authentication, the command compiler that builds outgoing IMAP commands, and the
 public client API.
 
 Out of scope:
 
 - Vulnerabilities in your own application code that uses ImapFlow.
-- Misconfiguration of your usage - for example, disabling TLS certificate
+- Misconfiguration of your usage, for example disabling TLS certificate
   verification (`tls.rejectUnauthorized: false`), connecting over cleartext when
   TLS is available, or passing untrusted input directly into mailbox paths or
   command arguments without validation.
-- Vulnerabilities in the IMAP servers you connect to, or in third-party
-  dependencies (please report those to their respective maintainers; we will
-  upgrade once a fix is available).
+- Vulnerabilities in the IMAP servers you connect to.
 - Issues that require an already-compromised host or local access to the machine
   running ImapFlow.
-- Social-engineering reports and theoretical issues without a demonstrated,
-  concrete impact.
+- Social-engineering reports.
 
 Thank you for helping keep ImapFlow and its users safe.

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

@@ -19,4 +19,4 @@ export interface AppendResult extends AppendResponseObject {
  * @returns Append result with UID info if available, or undefined if preconditions not met
  * @throws {Error} If the APPEND command fails or message exceeds APPENDLIMIT
  */
-export default function append(connection: ImapFlow, destination: string | string[], content: Buffer | string, flags?: string | string[] | undefined, idate?: Date | string | false | undefined): Promise<AppendResult | undefined>;
+export default function append(connection: ImapFlow, destination: string | string[], content: Buffer | Uint8Array | string, flags?: string | string[] | undefined, idate?: Date | string | false | undefined): Promise<AppendResult | undefined>;

package/dist/cjs/commands/append.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = append;
 const tools_js_1 = require("../tools.js");
+const errors_js_1 = require("../errors.js");
 /**
  * Appends a message to a mailbox.
  *
@@ -18,14 +19,24 @@ async function append(connection, destination, content, flags, idate) {
         // nothing to do here
         return;
     }
+    // The literal size marker is announced from these bytes, so anything that is not
+    // bytes (a Readable, a plain object) is refused here instead of desyncing the session
+    let message;
     if (typeof content === 'string') {
-        content = Buffer.from(content);
+        message = Buffer.from(content);
+    }
+    else if (content instanceof Uint8Array) {
+        // a Buffer as is, any other Uint8Array as a view over the same memory, not a copy
+        message = Buffer.isBuffer(content) ? content : Buffer.from(content.buffer, content.byteOffset, content.byteLength);
+    }
+    else {
+        throw (0, errors_js_1.createImapError)('Message content must be a Buffer, Uint8Array or string', 'InvalidMessageContent');
     }
     // APPENDLIMIT capability (RFC 7889): server may advertise the maximum message
     // size it accepts. Check before sending to avoid a wasted round-trip.
     if (connection.capabilities.has('APPENDLIMIT')) {
         let appendLimit = connection.capabilities.get('APPENDLIMIT');
-        if (typeof appendLimit === 'number' && appendLimit < content.length) {
+        if (typeof appendLimit === 'number' && appendLimit < message.length) {
             let err = new Error('Message content too big for APPENDLIMIT=' + appendLimit);
             err.serverResponseCode = 'APPENDLIMIT';
             throw err;
@@ -82,9 +93,9 @@ async function append(connection, destination, content, flags, idate) {
     // Regular literals cannot contain NUL bytes per the IMAP grammar.
     let isLiteral8 = false;
     if (connection.capabilities.has('BINARY') && !connection.disableBinary) {
-        isLiteral8 = content.indexOf(Buffer.from([0])) >= 0;
+        isLiteral8 = message.indexOf(0) >= 0;
     }
-    attributes.push({ type: 'LITERAL', value: content, isLiteral8 });
+    attributes.push({ type: 'LITERAL', value: message, isLiteral8 });
     let map = { destination };
     if (connection.mailbox && connection.mailbox.path) {
         map.path = connection.mailbox.path;

package/dist/cjs/commands/compress.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = compress;
+const errors_js_1 = require("../errors.js");
 /**
  * Requests DEFLATE compression from the server.
  *
@@ -36,8 +37,7 @@ async function compress(connection) {
     // back its unconsumed tail on unpipe so the transport can feed it into the
     // inflater - not something a command module can reach from here.
     if (response.hasTrailingData) {
-        let error = new Error('Server sent data between the COMPRESS response and the compression layer switch');
-        error.code = 'COMPRESS_TRAILING_DATA';
+        let error = (0, errors_js_1.createImapError)('Server sent data between the COMPRESS response and the compression layer switch', 'COMPRESS_TRAILING_DATA');
         connection.log.error({ err: error, cid: connection.id });
         // Schedule the close before releasing parser backpressure, so the buffered
         // deflate-framed bytes cannot settle anything before teardown begins. This is

package/dist/cjs/commands/idle.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = idle;
 const tools_js_1 = require("../tools.js");
+const errors_js_1 = require("../errors.js");
 const NOOP_INTERVAL = 2 * 60 * 1000;
 /**
  * Marks the connection as idling on behalf of one session and returns a release function.
@@ -192,9 +193,7 @@ async function pollOnce(connection, session) {
                 highestModseq: true
             });
             if (!status) {
-                let err = new Error('STATUS poll failed');
-                err.code = 'PollFailed';
-                throw err;
+                throw (0, errors_js_1.createImapError)('STATUS poll failed', 'PollFailed');
             }
             break;
         }

package/dist/cjs/commands/status.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = status;
 const tools_js_1 = require("../tools.js");
 const status_fields_js_1 = require("./status-fields.js");
+const errors_js_1 = require("../errors.js");
 // STATUS fields that also refresh the live mailbox state when the queried mailbox is the
 // currently selected one. Keyed by the output property name parseStatusList() reports.
 const MAILBOX_UPDATERS = {
@@ -99,10 +100,7 @@ async function status(connection, path, query) {
                 return false;
             });
             if (folders && !folders.length) {
-                let error = new Error(`Mailbox doesn't exist: ${path}`);
-                error.code = 'NotFound';
-                error.response = err;
-                throw error;
+                throw (0, errors_js_1.createImapError)(`Mailbox doesn't exist: ${path}`, 'NotFound', { response: err });
             }
         }
         connection.log.warn({ err, cid: connection.id });

package/dist/cjs/connection-deadline.d.ts

@@ -1,4 +1,4 @@
-import type { ImapFlowError } from './errors.js';
+import { type ImapFlowError } from './errors.js';
 export declare const CONNECT_TIMEOUT: number;
 /**
  * One deadline for an entire connection attempt.

package/dist/cjs/connection-deadline.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectionDeadline = exports.CONNECT_TIMEOUT = void 0;
 const tools_js_1 = require("./tools.js");
+const errors_js_1 = require("./errors.js");
 // Default upper bound for establishing a usable transport, including DNS and proxy negotiation.
 exports.CONNECT_TIMEOUT = 90 * 1000;
 /**
@@ -31,10 +32,7 @@ class ConnectionDeadline {
      * @returns The shared `CONNECT_TIMEOUT` error.
      */
     error() {
-        let err = new Error('Failed to establish connection in required time');
-        err.code = 'CONNECT_TIMEOUT';
-        err.details = { connectionTimeout: this.timeout };
-        return err;
+        return (0, errors_js_1.createImapError)('Failed to establish connection in required time', 'CONNECT_TIMEOUT', { details: { connectionTimeout: this.timeout } });
     }
     /**
      * Maps a dependency's own expiry onto the shared `CONNECT_TIMEOUT` shape, so callers see one

package/dist/cjs/download.js

@@ -18,6 +18,7 @@ const limited_passthrough_js_1 = require("./limited-passthrough.js");
 // What a wait on the head stream listens for: it can take more input, it failed, or it went
 // away (a consumer destroying it closes it without a 'drain')
 const DRAIN_WAIT_EVENTS = ['drain', 'error', 'close'];
+const errors_js_1 = require("./errors.js");
 const tools_js_1 = require("./tools.js");
 const isEmptySection = (value) => !value?.length;
 /**
@@ -88,10 +89,7 @@ async function fetchExpected(client, range, query, options, expected) {
             cid: client.id
         });
         if (attempt >= MAX_FETCH_ATTEMPTS) {
-            let err = new Error('Server kept answering with data of another request');
-            err.code = 'DownloadIncomplete';
-            err.cid = client.id;
-            throw err;
+            throw (0, errors_js_1.createImapError)('Server kept answering with data of another request', 'DownloadIncomplete', { cid: client.id });
         }
     }
 }
@@ -238,6 +236,12 @@ async function downloadMessage(client, range, part, options) {
         };
         let response = await fetchExpected(client, range, query, downloadOptions, expected);
         if (!response) {
+            // An empty answer also comes from a connection that closed while the consumer was
+            // paused between chunks (fetchOne() finds no mailbox then), and that is not a
+            // missing message: a caller that retries would skip it
+            if (!client.usable) {
+                throw client.createNoConnectionError(false, { rejectedFrom: 'download' });
+            }
             return { response: false, chunk: false };
         }
         if (!uid && response.uid) {
@@ -374,13 +378,19 @@ async function downloadMessage(client, range, part, options) {
     // would still pull the entire part off the wire.
     let limiters = [];
     let isLimited = () => limiters.some(entry => entry.limited);
+    // Every stage after the head, so a download that ends early can release all of them
+    let stages = [];
     // Appending a stage means forwarding the current tail's errors to it before piping, so a
-    // failure anywhere reaches the stream the caller is reading
+    // failure anywhere reaches the stream the caller is reading. The stage is destroyed with
+    // the error rather than only emitting it: pipe() does not end its destination on a source
+    // error, so a consumer that only listens for 'finish' or 'close' (a plain .pipe() into a
+    // file) would otherwise wait forever.
     let pipeStage = (stage) => {
         output.on('error', err => {
-            stage.emit('error', err);
+            stage.destroy(err);
         });
         output = output.pipe(stage);
+        stages.push(stage);
         return stage;
     };
     let isTextNode = ['text/html', 'text/plain', 'text/x-amp-html'].includes(meta.contentType) || (part === '1' && !meta.contentType);
@@ -425,8 +435,8 @@ async function downloadMessage(client, range, part, options) {
     // Cleanup function
     const cleanup = () => {
         fetchAborted = true;
-        if (stream && !stream.destroyed) {
-            stream.destroy();
+        for (let entry of [stream, ...stages]) {
+            entry.destroy();
         }
     };
     // Listen for stream destruction
@@ -499,11 +509,7 @@ async function downloadMessage(client, range, part, options) {
                 // Loud on purpose. Everything written downstream by this point holds
                 // duplicated content, and a quiet stop is indistinguishable from a clean EOF,
                 // so the consumer would store a corrupt body believing it intact.
-                let err = new Error('Download exceeded the expected message size');
-                err.code = 'DownloadOverflow';
-                err.maxSize = maxTotalBytes;
-                err.cid = client.id;
-                throw err;
+                throw (0, errors_js_1.createImapError)('Download exceeded the expected message size', 'DownloadOverflow', { maxSize: maxTotalBytes, cid: client.id });
             }
             let { response, chunk } = await getNextPart();
             // A consumer that gave up while the chunk was in flight
@@ -514,10 +520,7 @@ async function downloadMessage(client, range, part, options) {
                 // The message is gone mid-download (expunged by another client, or the
                 // mailbox was closed). Ending the stream here would pass the truncated body
                 // off as complete, so the consumer is told the same way as for an overflow.
-                let err = new Error('Message disappeared before the download completed');
-                err.code = 'DownloadIncomplete';
-                err.cid = client.id;
-                throw err;
+                throw (0, errors_js_1.createImapError)('Message disappeared before the download completed', 'DownloadIncomplete', { cid: client.id });
             }
             if (!chunk) {
                 break;
@@ -547,7 +550,7 @@ async function downloadMessage(client, range, part, options) {
         fetchAllParts(head)
             .catch(err => {
             if (!fetchAborted && stream && !stream.destroyed) {
-                stream.emit('error', err);
+                stream.destroy(err);
                 /* c8 ignore start */ // the else logs when a fetch error arrives after the stream was already torn down (timing-dependent)
             }
             else {
@@ -572,7 +575,7 @@ async function downloadMessage(client, range, part, options) {
             // above rejects a promise nobody holds and takes the process down on
             // unhandledRejection. Reaching it always means an invariant broke - the head
             // stream kept pipeStage()'s error forwarder for the life of the download, so
-            // emit('error') above has somewhere to go - which is why it logs at error even
+            // destroy(err) above has somewhere to go - which is why it logs at error even
             // for a routine-looking connection code.
             .catch(err => client.log.error({ msg: 'Failed to fail the download stream', err, cid: client.id }));
     };

package/dist/cjs/errors.d.ts

@@ -29,6 +29,7 @@ export declare const ImapFlowErrorCode: {
     readonly MissingServerExtension: "MissingServerExtension";
     readonly ParserError: "ParserError";
     readonly ParserErrorExchange: "ParserErrorExchange";
+    readonly ParserErrorInternal: "ParserErrorInternal";
     readonly MAX_IMAP_NESTING_REACHED: "MAX_IMAP_NESTING_REACHED";
     readonly LineTooLarge: "LineTooLarge";
     readonly LiteralTooLarge: "LiteralTooLarge";
@@ -38,6 +39,7 @@ export declare const ImapFlowErrorCode: {
     readonly InvalidTextValue: "InvalidTextValue";
     readonly InvalidSequenceSet: "InvalidSequenceSet";
     readonly InvalidSearchQuery: "InvalidSearchQuery";
+    readonly InvalidMessageContent: "InvalidMessageContent";
     readonly DownloadOverflow: "DownloadOverflow";
     readonly DownloadIncomplete: "DownloadIncomplete";
     readonly ProxyError: "ProxyError";
@@ -48,6 +50,8 @@ export declare const ImapFlowErrorCode: {
 };
 /** One of the {@link ImapFlowErrorCode} values */
 export type ImapFlowErrorCode = (typeof ImapFlowErrorCode)[keyof typeof ImapFlowErrorCode];
+/** A numbered parser error code, `ParserError1` and up */
+export type ParserErrorCode = `ParserError${number}`;
 /**
  * An Error raised by ImapFlow, with the extra properties the library attaches to describe
  * the failure. Every property is optional: which ones are present depends on where the
@@ -132,3 +136,14 @@ export declare class AuthenticationFailure extends Error implements ImapFlowErro
     response?: string | undefined;
     oauthError?: any;
 }
+/**
+ * Creates an {@link ImapFlowError} with a code and optional extra properties. The code is
+ * checked by the compiler against {@link ImapFlowErrorCode}, so a typo or an undeclared
+ * code fails the build instead of reaching consumers.
+ *
+ * @param message - The error message
+ * @param code - The error code
+ * @param props - Extra properties to set on the error
+ * @returns The error, ready to throw or reject with
+ */
+export declare function createImapError(message: string, code: ImapFlowErrorCode | ParserErrorCode, props?: Omit<ImapFlowError, 'name' | 'message' | 'stack' | 'code'> | undefined): ImapFlowError;

package/dist/cjs/errors.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthenticationFailure = exports.ImapFlowErrorCode = void 0;
+exports.createImapError = createImapError;
 /**
  * The `code` values ImapFlow sets on the errors it raises, so they can be matched without
  * string literals: `if (err.code === ImapFlowErrorCode.NoConnection)`.
@@ -35,6 +36,8 @@ exports.ImapFlowErrorCode = {
     // response parsing and size limits
     ParserError: 'ParserError',
     ParserErrorExchange: 'ParserErrorExchange',
+    // an unexpected exception inside the parser, re-raised with a code; a parser bug
+    ParserErrorInternal: 'ParserErrorInternal',
     MAX_IMAP_NESTING_REACHED: 'MAX_IMAP_NESTING_REACHED',
     LineTooLarge: 'LineTooLarge',
     LiteralTooLarge: 'LiteralTooLarge',
@@ -45,6 +48,7 @@ exports.ImapFlowErrorCode = {
     InvalidTextValue: 'InvalidTextValue',
     InvalidSequenceSet: 'InvalidSequenceSet',
     InvalidSearchQuery: 'InvalidSearchQuery',
+    InvalidMessageContent: 'InvalidMessageContent',
     // download()
     DownloadOverflow: 'DownloadOverflow',
     DownloadIncomplete: 'DownloadIncomplete',
@@ -66,3 +70,21 @@ class AuthenticationFailure extends Error {
     }
 }
 exports.AuthenticationFailure = AuthenticationFailure;
+/**
+ * Creates an {@link ImapFlowError} with a code and optional extra properties. The code is
+ * checked by the compiler against {@link ImapFlowErrorCode}, so a typo or an undeclared
+ * code fails the build instead of reaching consumers.
+ *
+ * @param message - The error message
+ * @param code - The error code
+ * @param props - Extra properties to set on the error
+ * @returns The error, ready to throw or reject with
+ */
+function createImapError(message, code, props) {
+    const error = new Error(message);
+    error.code = code;
+    if (props) {
+        Object.assign(error, props);
+    }
+    return error;
+}

package/dist/cjs/handler/imap-compiler.d.ts

@@ -12,13 +12,13 @@ import type { CompilerOptions, ImapCompileInput } from './types.js';
  * @param options.isLogging - If true, redacts sensitive values and truncates long strings/literals for logging purposes.
  * @param options.literalPlus - If true, uses the LITERAL+ extension (appends "+" to literal length markers).
  * @param options.literalMinus - If true, uses the LITERAL- extension for literals up to 4096 bytes.
- * @returns A promise that resolves to an array of Buffers (if asArray is true) or a single concatenated Buffer.
+ * @returns An array of Buffers (if asArray is true) or a single concatenated Buffer.
  */
 declare function compiler(response: ImapCompileInput, options: CompilerOptions & {
     asArray: true;
-}): Promise<Buffer[]>;
+}): Buffer[];
 declare function compiler(response: ImapCompileInput, options?: (CompilerOptions & {
     asArray?: false | undefined;
-}) | undefined): Promise<Buffer>;
-declare function compiler(response: ImapCompileInput, options?: CompilerOptions | undefined): Promise<Buffer | Buffer[]>;
+}) | undefined): Buffer;
+declare function compiler(response: ImapCompileInput, options?: CompilerOptions | undefined): Buffer | Buffer[];
 export default compiler;