imapflow 1.3.4 → 1.3.6

package/.github/codeql/codeql-config.yml

@@ -0,0 +1,12 @@
+name: "ImapFlow CodeQL config"
+
+# Exclude code that is not part of the published library runtime from analysis.
+# These paths generate only false-positive noise:
+#   - test fixtures intentionally feed malformed/hostile input and exercise
+#     edge cases that are not representative of production usage
+#   - the example scripts hardcode demo credentials and connection details for
+#     local experimentation and are not maintained as production code
+paths-ignore:
+    - test
+    - '**/test/**'
+    - examples

package/.github/workflows/codeql.yml

@@ -0,0 +1,102 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+  schedule:
+    - cron: '40 17 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: javascript-typescript
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        config-file: ./.github/codeql/codeql-config.yml
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

package/.github/workflows/stale.yml

@@ -3,6 +3,11 @@ on:
     schedule:
         - cron: '30 1 * * *'
 
+permissions:
+    contents: read
+    issues: write
+    pull-requests: write
+
 jobs:
     stale:
         runs-on: ubuntu-latest

package/.github/workflows/test.yml

@@ -4,6 +4,9 @@ on:
     push:
     pull_request:
 
+permissions:
+    contents: read
+
 jobs:
     test:
         strategy:

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.3.4"
+    ".": "1.3.6"
 }

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.3.6](https://github.com/postalsys/imapflow/compare/v1.3.5...v1.3.6) (2026-06-05)
+
+
+### Bug Fixes
+
+* harden STARTTLS upgrade, literal bounds, and connection error paths ([35eca81](https://github.com/postalsys/imapflow/commit/35eca81075401e89f0b3aca84e26c41710a62c28))
+
+## [1.3.5](https://github.com/postalsys/imapflow/compare/v1.3.4...v1.3.5) (2026-06-01)
+
+
+### Bug Fixes
+
+* correct flag removal, literal parsing, path normalization, and harden the parser ([d15c053](https://github.com/postalsys/imapflow/commit/d15c0536f4b7db2ebca5e258fc885da0d194b5fd))
+* prevent host process crash from socket errors after unbind() when COMPRESS=DEFLATE is active ([e30fca1](https://github.com/postalsys/imapflow/commit/e30fca1a42a4d2ab6f7a6a766effafe3df6b1aff))
+
 ## [1.3.4](https://github.com/postalsys/imapflow/compare/v1.3.3...v1.3.4) (2026-05-29)
 
 

package/SECURITY.md

@@ -0,0 +1,88 @@
+# 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.
+
+## 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.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x     | :white_check_mark: |
+| < 1.0   | :x:                |
+
+If you are on an older version, please upgrade. See the release notes at
+<https://github.com/postalsys/imapflow/releases> before updating.
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues,
+pull requests, or discussions.**
+
+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.
+
+## Scope
+
+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
+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
+  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).
+- 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.
+
+Thank you for helping keep ImapFlow and its users safe.

package/SECURITY.txt

@@ -0,0 +1,27 @@
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA256
+
+Contact: https://github.com/postalsys/imapflow/security/advisories/new
+Contact: mailto:andris@postalsys.com
+Expires: 2027-06-01T00:00:00.000Z
+Encryption: https://keys.openpgp.org/vks/v1/by-fingerprint/5D952A46E1D8C931F6364E01DC6C83F4D584D364
+Preferred-Languages: en, et
+Canonical: https://github.com/postalsys/imapflow/blob/master/SECURITY.txt
+Policy: https://github.com/postalsys/imapflow/blob/master/SECURITY.md
+-----BEGIN PGP SIGNATURE-----
+
+iQJiBAEBCABMFiEEXZUqRuHYyTH2Nk4B3GyD9NWE02QFAmodTFwbFIAAAAAABAAO
+bWFudTIsMi41KzEuMTIsMCwzEhxhbmRyaXNAcmVpbm1hbi5ldQAKCRDcbIP01YTT
+ZGcgD/42Wdd07wEclXDm/lM0Ax+aX9sPjwV33DAICqhDoILf8yG4yPkCRuuTCayw
+QLTB1pCi+tk8xVs9TH88bDwinfGVqzbmUyHSa2h32TDx/0/b+rg2LO2Ru8JtJkX8
+CMY8/UhkouaQnHKDjkbLniF8HpQsBzOiPzvkfX91BY4HBwzE8aCC8MXC0zyjBkQX
+dqVJ/fYMQKPkblKemnrMB/XM1jui2M7vgzpqilLcZqYv5oNFQhgpd+JOEVKMDUZv
+0WaLrFWRegFvFApS/cIvzu5RLIhDWuL0ao577Cpdj1QE7nznfbBqBfGEzZotOShs
+CdzdGloSt9C1gVLWItsncXByXVuNrF8l67hoOAnRwO4c8PKg3b4CvzBelmDiCWrS
+73LGWmFwp1luyLrfZREUYsF5hqHCr6ULmDEAVp0MRtzxL56YjiS20d1sa9v96P4O
+KFCvOT5LbCK/KqAFzhRzRXd3sawt5SXcR2FGgjFrRYNriyHNSk0k1h5IYv1kNoPb
+VN+DxsOhORd2EsqqOBqHoEES472OOsmLTYa0A5z+zyA0IcaY5hXsMDrX9OMIUHUW
+4JAOviDYyejefVJd8SsLrAmQ82p1jPY0LnuIyLz/sXDoe7QduNZIFKoUYw3KVybM
+y0X7yP92/buzcZY41FOQT8dBFGDzboWQo+RPEh16qXEV75ss2A==
+=Wlrz
+-----END PGP SIGNATURE-----

package/lib/commands/starttls.js

@@ -15,6 +15,9 @@ module.exports = async connection => {
     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) {

package/lib/commands/store.js

@@ -57,7 +57,7 @@ module.exports = async (connection, range, flags, options) => {
         .map(flag => {
             flag = formatFlag(flag);
 
-            if (!canUseFlag(connection.mailbox, flag) && operation !== 'remove') {
+            if (!canUseFlag(connection.mailbox, flag) && options.operation !== 'remove') {
                 return false;
             }
 

package/lib/handler/imap-stream.js

@@ -16,6 +16,11 @@ const CURLY_CLOSE = 0x7d;
 // Maximum allowed literal size: 1GB (1073741824 bytes)
 const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
 
+// Default maximum length of a single line (a response without a literal). Matches the literal cap:
+// large literal-free responses (e.g. big SEARCH/LIST results) are legitimate, so this bound exists
+// only to stop a server that never sends a line terminator, not to constrain normal traffic.
+const MAX_LINE_SIZE = MAX_LITERAL_SIZE;
+
 /**
  * A Transform stream that parses raw IMAP protocol data from a socket into structured
  * command/response objects. Reads binary input, splits it into lines delimited by LF,
@@ -34,6 +39,13 @@ class ImapStream extends Transform {
      * @param {Object} [options.logger] - A pino-compatible logger instance. If not provided, a default child logger is created.
      * @param {boolean} [options.logRaw] - If true, logs raw socket data at trace level.
      * @param {boolean} [options.secureConnection] - Whether the connection uses TLS.
+     * @param {number} [options.maxLineLength] - Maximum allowed length (in bytes) of a single
+     *   line (a response without a literal). Defaults to MAX_LITERAL_SIZE (1GB). Guards against a
+     *   malicious or broken server that never sends a line terminator, which would otherwise grow
+     *   the internal line buffer without bound.
+     * @param {number} [options.maxLiteralSize] - Maximum allowed size (in bytes) of a single
+     *   literal block. Defaults to MAX_LITERAL_SIZE (1GB). Lower it to bound peak memory
+     *   allocation against a malicious or broken server announcing an oversized literal.
      */
     constructor(options) {
         super({
@@ -55,10 +67,23 @@ class ImapStream extends Transform {
 
         this.readBytesCounter = 0;
 
+        // Maximum length of a single line (response without a literal). Bounds the line buffer
+        // so a server that never sends a line terminator cannot exhaust memory. A non-negative
+        // integer is honored as-is (including 0); anything else falls back to the default, so an
+        // explicit 0 is not silently swallowed into the 1GB default the way `|| MAX_LINE_SIZE` was.
+        this.maxLineLength = Number.isInteger(this.options.maxLineLength) && this.options.maxLineLength >= 0 ? this.options.maxLineLength : MAX_LINE_SIZE;
+
+        // Maximum size of a single literal block. Bounds peak memory allocation so a server
+        // announcing an oversized literal cannot exhaust memory. As above, a non-negative integer
+        // (including an explicit 0, meaning "reject all non-empty literals") is honored as-is.
+        this.maxLiteralSize =
+            Number.isInteger(this.options.maxLiteralSize) && this.options.maxLiteralSize >= 0 ? this.options.maxLiteralSize : MAX_LITERAL_SIZE;
+
         this.state = LINE;
         this.literalWaiting = 0;
         this.inputBuffer = []; // lines
         this.lineBuffer = []; // current line
+        this.lineBytes = 0; // bytes currently buffered for the in-progress line
         this.literalBuffer = [];
         this.literals = [];
 
@@ -102,7 +127,7 @@ class ImapStream extends Transform {
         // Scan backwards through the line to find an IMAP literal marker: {size}\r\n
         // The format is: '{' followed by one or more ASCII digits followed by '}'
         let numBytes = [];
-        for (; pos > 0; pos--) {
+        for (; pos >= 0; pos--) {
             let c = line[pos];
             if (c >= NUM_0 && c <= NUM_9) {
                 numBytes.unshift(c);
@@ -111,11 +136,11 @@ class ImapStream extends Transform {
             if (c === CURLY_OPEN && numBytes.length) {
                 const literalSize = Number(Buffer.from(numBytes).toString());
 
-                if (literalSize > MAX_LITERAL_SIZE) {
-                    const err = new Error(`Literal size ${literalSize} exceeds maximum allowed size of ${MAX_LITERAL_SIZE} bytes`);
+                if (literalSize > this.maxLiteralSize) {
+                    const err = new Error(`Literal size ${literalSize} exceeds maximum allowed size of ${this.maxLiteralSize} bytes`);
                     err.code = 'LiteralTooLarge';
                     err.literalSize = literalSize;
-                    err.maxSize = MAX_LITERAL_SIZE;
+                    err.maxSize = this.maxLiteralSize;
                     this.emit('error', err);
                     return false;
                 }
@@ -158,6 +183,7 @@ class ImapStream extends Transform {
 
                         this.inputBuffer.push(line);
                         this.lineBuffer = [];
+                        this.lineBytes = 0;
 
                         // try to detect if this is a literal start
                         if (this.checkLiteralMarker(line)) {
@@ -182,15 +208,35 @@ class ImapStream extends Transform {
                             }
 
                             if (payload.length) {
+                                // Whether more buffered input already followed this command on the
+                                // wire — more bytes in this chunk or another queued chunk. Captured
+                                // per emitted command (immutable on the pushed object) so a later
+                                // command cannot overwrite it; consumers that care about pipelining
+                                // boundaries can read it from the pushed object.
+                                let trailingAfterLine = lineStart < chunk.length || this.inputQueue.length > 0;
                                 await new Promise(resolve => {
-                                    this.push({ payload, literals, next: resolve });
+                                    this.push({ payload, literals, next: resolve, trailingAfterLine });
                                 });
                             }
                         }
                     }
                 }
                 if (lineStart < chunk.length) {
-                    this.lineBuffer.push(chunk.slice(lineStart));
+                    // No line terminator was found in the remaining bytes; carry the tail over to
+                    // the next chunk. Enforce the line-length cap here, since this is the only
+                    // path that grows the line buffer across chunks.
+                    let tail = chunk.slice(lineStart);
+                    let lineLength = this.lineBytes + tail.length;
+                    if (lineLength > this.maxLineLength) {
+                        const err = new Error(`Line length ${lineLength} exceeds maximum allowed size of ${this.maxLineLength} bytes`);
+                        err.code = 'LineTooLarge';
+                        err.lineLength = lineLength;
+                        err.maxSize = this.maxLineLength;
+                        this.emit('error', err);
+                        return;
+                    }
+                    this.lineBytes = lineLength;
+                    this.lineBuffer.push(tail);
                 }
                 break;
             }
@@ -303,6 +349,7 @@ class ImapStream extends Transform {
     _destroy(err, callback) {
         this.inputBuffer = [];
         this.lineBuffer = [];
+        this.lineBytes = 0;
         this.literalBuffer = [];
         this.literals = [];
         // Clear inputQueue and call any pending callbacks

package/lib/handler/token-parser.js

@@ -349,6 +349,13 @@ class TokenParser {
                                     this.currentNode.type = 'ATOM';
                                     // jump i to the ']'
                                     i = this.str.indexOf(']', i + 10);
+                                    if (i < 0) {
+                                        // Malformed REFERRAL with no closing ']'. Consume the rest
+                                        // of the string (there is no ']' to exclude) instead of
+                                        // computing a negative-index substring, which would yield
+                                        // garbage.
+                                        i = this.str.length;
+                                    }
                                     this.currentNode.endPos = this.pos + i - 1;
                                     this.currentNode.value = this.str.substring(this.currentNode.startPos - this.pos, this.currentNode.endPos - this.pos + 1);
                                     this.currentNode = this.currentNode.parentNode;

package/lib/imap-flow.d.ts

@@ -60,6 +60,17 @@ export interface ImapFlowOptions {
     greetingTimeout?: number;
     /** How long to wait for socket inactivity before timing out the connection. Defaults to 5 minutes */
     socketTimeout?: number;
+    /**
+     * Maximum allowed length in bytes of a single response line (a response without a literal).
+     * Guards against a malicious or broken server that never sends a line terminator. Defaults to
+     * 1GB.
+     */
+    maxLineLength?: number;
+    /**
+     * Maximum allowed size in bytes of a single IMAP literal block. Bounds peak memory allocation
+     * against a malicious or broken server announcing an oversized literal. Defaults to 1GB.
+     */
+    maxLiteralSize?: number;
     /**
      * Threshold in milliseconds for warning that a mailbox lock has been held
      * for a long time (diagnostic for forgotten release() calls). Defaults to