imapflow 1.3.5 → 1.3.7

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.5"
+    ".": "1.3.7"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.3.7](https://github.com/postalsys/imapflow/compare/v1.3.6...v1.3.7) (2026-06-08)
+
+
+### Bug Fixes
+
+* harden FLAGS guard and bring lib to full test coverage ([6666bec](https://github.com/postalsys/imapflow/commit/6666bec7f82072e5aa8a1e63736e35d5c6644d4c))
+
+## [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)
 
 

package/lib/commands/authenticate.js

@@ -7,7 +7,7 @@ const { getStatusCode, getErrorText } = require('../tools.js');
  *
  * @param {Error} err - The original authentication error
  * @param {Object} [errorResponse] - Optional OAuth error response from the server
- * @throws {Error} Always throws the enriched error
+ * @returns {Error} The enriched error; the caller is expected to throw it
  */
 async function handleAuthError(err, errorResponse) {
     let errorCode = getStatusCode(err.response);
@@ -19,7 +19,7 @@ async function handleAuthError(err, errorResponse) {
     if (errorResponse) {
         err.oauthError = errorResponse;
     }
-    throw err;
+    return err;
 }
 
 /**
@@ -84,7 +84,7 @@ async function authOauth(connection, username, accessToken) {
 
         return username;
     } catch (err) {
-        await handleAuthError(err, errorResponse);
+        throw await handleAuthError(err, errorResponse);
     }
 }
 
@@ -132,7 +132,7 @@ async function authLogin(connection, username, password) {
 
         return username;
     } catch (err) {
-        await handleAuthError(err, errorResponse);
+        throw await handleAuthError(err, errorResponse);
     }
 }
 
@@ -169,7 +169,7 @@ async function authPlain(connection, username, password, authzid) {
         // Return the identity we're authorized as (authzid if provided, otherwise username)
         return authzid || username;
     } catch (err) {
-        await handleAuthError(err, errorResponse);
+        throw await handleAuthError(err, errorResponse);
     }
 }
 

package/lib/commands/fetch.js

@@ -41,6 +41,7 @@ module.exports = async (connection, range, query, options) => {
 
         let response;
         try {
+            /* c8 ignore next */ // range is guaranteed truthy by the early-return guard above, so the '*' fallback is unreachable
             let attributes = [{ type: 'SEQUENCE', value: (range || '*').toString() }];
 
             let queryStructure = [];

package/lib/commands/logout.js

@@ -30,6 +30,7 @@ module.exports = async connection => {
         }
         connection.log.warn({ err, cid: connection.id });
         return false;
+        /* c8 ignore next */ // the catch above is exhaustive (never re-throws), so finally is only ever reached via normal completion
     } finally {
         // Set state to LOGOUT before closing to prevent any further commands from
         // being queued. The socket is closed unconditionally in this finally block

package/lib/commands/select.js

@@ -70,6 +70,7 @@ module.exports = async (connection, path, options) => {
         // 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 || [])
         };
 
@@ -164,7 +165,7 @@ module.exports = async (connection, path, options) => {
                 // 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]))) {
+                    if (!untagged.attributes || !untagged.attributes.length || !Array.isArray(untagged.attributes[0])) {
                         return;
                     }
                     let flags = untagged.attributes[0].map(flag => (typeof flag.value === 'string' ? flag.value : false)).filter(flag => flag);

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

@@ -22,6 +22,7 @@ module.exports = async (connection, range, flags, options) => {
         return false;
     }
 
+    /* c8 ignore next */ // options.useLabels is dereferenced in the guard above, so options is always defined here
     options = options || {};
 
     // Build the IMAP STORE operation name. The format is:

package/lib/handler/imap-stream.js

@@ -43,6 +43,9 @@ class ImapStream extends Transform {
      *   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({
@@ -65,8 +68,16 @@ 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.
-        this.maxLineLength = this.options.maxLineLength || MAX_LINE_SIZE;
+        // 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;
@@ -125,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;
                 }
@@ -197,8 +208,14 @@ 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 });
                                 });
                             }
                         }

package/lib/handler/token-parser.js

@@ -10,7 +10,6 @@ const STATE_NORMAL = 0x003;
 const STATE_PARTIAL = 0x004;
 const STATE_SEQUENCE = 0x005;
 const STATE_STRING = 0x006;
-const STATE_TEXT = 0x007;
 
 const RE_DIGITS = /^\d+$/;
 const RE_SINGLE_DIGIT = /^\d$/;
@@ -706,10 +705,6 @@ class TokenParser {
 
                     this.currentNode.value += chr;
                     break;
-
-                case STATE_TEXT:
-                    this.currentNode.value += chr;
-                    break;
             }
         }
     }

package/lib/imap-flow.d.ts

@@ -66,6 +66,11 @@ export interface ImapFlowOptions {
      * 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