imapflow 1.4.6 → 1.4.8

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.4.6"
+    ".": "1.4.8"
 }

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.4.8](https://github.com/postalsys/imapflow/compare/v1.4.7...v1.4.8) (2026-07-21)
+
+
+### Bug Fixes
+
+* **auth:** describe the real connection in the OAUTHBEARER payload ([aca7cb3](https://github.com/postalsys/imapflow/commit/aca7cb3ab7e67704cb692ad59f6db0792040a888))
+* default a non-secure connection to IMAP port 143, not POP3 110 ([5896488](https://github.com/postalsys/imapflow/commit/589648821c5dd1b1750959fa2917b3571ba93db5))
+
+## [1.4.7](https://github.com/postalsys/imapflow/compare/v1.4.6...v1.4.7) (2026-07-10)
+
+
+### Bug Fixes
+
+* treat \NonExistent mailboxes as \Noselect in LIST responses ([af21245](https://github.com/postalsys/imapflow/commit/af21245dab4e1320afc4c4458afe33d1508180c1))
+
 ## [1.4.6](https://github.com/postalsys/imapflow/compare/v1.4.5...v1.4.6) (2026-07-05)
 
 

package/lib/commands/authenticate.js

@@ -40,7 +40,14 @@ async function authOauth(connection, username, accessToken) {
         // OAUTHBEARER payload per RFC 7628: fields separated by \x01 (SASL GS2 framing).
         // Format: "n,a=<user>," \x01 "host=..." \x01 "port=..." \x01 "auth=Bearer <token>" \x01 \x01
         // The trailing empty strings produce the required double-\x01 terminator.
-        oauthbearer = [`n,a=${username},`, `host=${connection.servername}`, `port=993`, `auth=Bearer ${accessToken}`, '', ''].join('\x01');
+        // Both fields must describe the connection actually in use. The port was hardcoded to 993,
+        // so an OAuth2 server reached over 143/STARTTLS advertised a payload that did not match, and
+        // `servername` is set to false for a bare-IP host, which rendered as a literal "host=false".
+        // A server validating either field rejects with status `invalid_request` - a permanent
+        // failure that refreshing the access token can never clear.
+        oauthbearer = [`n,a=${username},`, `host=${connection.servername || connection.host}`, `port=${connection.port}`, `auth=Bearer ${accessToken}`, '', ''].join(
+            '\x01'
+        );
         command = 'OAUTHBEARER';
         // "AQ==" is base64 for \x01 -- sent as the error continuation to abort the SASL exchange
         breaker = 'AQ==';

package/lib/commands/list.js

@@ -87,6 +87,15 @@ module.exports = async (connection, reference, mailbox, options) => {
             specialUseMatches[type].push({ entry, source });
         };
 
+        // RFC 5258: the \NonExistent attribute implies \Noselect. Some servers only
+        // return \NonExistent for phantom folders, so add \Noselect as well to keep
+        // the flags consistent for consumers that only check \Noselect.
+        let normalizeFlags = entry => {
+            if (entry.flags.has('\\NonExistent')) {
+                entry.flags.add('\\Noselect');
+            }
+        };
+
         // User-provided hints map mailbox paths to special-use types (e.g., {sent: "Sent Items"}).
         // These override server-reported flags and name-based guesses. Converted to a
         // path-keyed lookup: { "Sent Items" => "\\Sent" }
@@ -132,6 +141,8 @@ module.exports = async (connection, reference, mailbox, options) => {
                             listed: true
                         };
 
+                        normalizeFlags(entry);
+
                         // Check user-provided hints first (highest priority)
                         if (specialUseHints[entry.path]) {
                             addSpecialUseMatch(entry, specialUseHints[entry.path], 'user');
@@ -300,6 +311,7 @@ module.exports = async (connection, reference, mailbox, options) => {
                             existing.subscribed = true;
                             // Merge any additional flags from LSUB into the LIST entry
                             entry.flags.forEach(flag => existing.flags.add(flag));
+                            normalizeFlags(existing);
                         }
                         // Non-listed subscribed folders are intentionally ignored
                     }

package/lib/imap-flow.js

@@ -277,12 +277,14 @@ class ImapFlow extends EventEmitter {
          */
         this.secureConnection = !!this.options.secure;
 
-        this.port = Number(this.options.port) || (this.secureConnection ? 993 : 110);
+        // 993 is IMAPS, 143 is IMAP over cleartext/STARTTLS. The non-secure default used to be 110,
+        // which is POP3 - a client created without an explicit port could never connect.
+        this.port = Number(this.options.port) || (this.secureConnection ? 993 : 143);
         this.host = this.options.host || 'localhost';
         this.servername = this.options.servername ? this.options.servername : !net.isIP(this.host) ? this.host : false;
 
         if (typeof this.options.secure === 'undefined' && this.port === 993) {
-            // if secure option is not set but port is 465, then default to secure
+            // if secure option is not set but port is 993, then default to secure
             this.secureConnection = true;
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.4.6",
+    "version": "1.4.8",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -28,18 +28,18 @@
     "homepage": "https://imapflow.com/",
     "devDependencies": {
         "@eslint/js": "10.0.1",
-        "@types/node": "26.1.0",
-        "c8": "11.0.0",
-        "eslint": "10.6.0",
+        "@types/node": "26.1.1",
+        "c8": "12.0.0",
+        "eslint": "10.7.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
         "grunt": "1.6.2",
         "grunt-cli": "1.5.0",
         "grunt-contrib-nodeunit": "5.0.0",
         "grunt-eslint": "26.0.0",
-        "prettier": "3.9.4",
+        "prettier": "3.9.5",
         "proxyquire": "^2.1.3",
-        "typescript": "6.0.3"
+        "typescript": "7.0.2"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.14",

package/test/commands-integration-test.js

@@ -30,6 +30,9 @@ const createMockConnection = (overrides = {}) => {
         states,
         state: overrides.state || states.SELECTED,
         id: 'test-connection-id',
+        // Mirrors imap-flow.js, which always resolves a port before authenticating. Without a
+        // default the OAUTHBEARER payload builds `port=undefined`.
+        port: overrides.port || 993,
         capabilities: new Map(overrides.capabilities || [['IMAP4rev1', true]]),
         enabled: new Set(overrides.enabled || []),
         authCapabilities: new Map(),
@@ -58,6 +61,9 @@ const createMockConnection = (overrides = {}) => {
     };
 };
 
+// Decodes the base64 SASL payload that authenticate() hands to exec().
+const decodeSaslPayload = execArgs => Buffer.from(execArgs.args[1].value, 'base64').toString();
+
 // ============================================
 // CAPABILITY Command Tests
 // ============================================
@@ -3550,6 +3556,94 @@ module.exports['Commands: list skips Noselect folders for status'] = async test
     test.done();
 };
 
+module.exports['Commands: list adds Noselect to NonExistent mailboxes'] = async test => {
+    const connection = createMockConnection({
+        state: 3,
+        exec: async (cmd, attrs, opts) => {
+            if (cmd === 'LIST' && opts && opts.untagged && opts.untagged.LIST) {
+                await opts.untagged.LIST({
+                    attributes: [[{ value: '\\HasNoChildren' }], { value: '/' }, { value: 'INBOX' }]
+                });
+                await opts.untagged.LIST({
+                    attributes: [[{ value: '\\NonExistent' }], { value: '/' }, { value: 'Phantom' }]
+                });
+            }
+            return { next: () => {} };
+        }
+    });
+
+    const result = await listCommand(connection, '', '*');
+    const phantom = result.find(e => e.path === 'Phantom');
+    test.ok(phantom);
+    // RFC 5258: \\NonExistent implies \\Noselect
+    test.equal(phantom.flags.has('\\Noselect'), true);
+    // The original flag is preserved, not replaced
+    test.equal(phantom.flags.has('\\NonExistent'), true);
+    const inbox = result.find(e => e.path === 'INBOX');
+    test.ok(inbox);
+    test.equal(inbox.flags.has('\\Noselect'), false);
+    test.done();
+};
+
+module.exports['Commands: list LSUB merge adds Noselect to NonExistent'] = async test => {
+    const connection = createMockConnection({
+        state: 3,
+        exec: async (cmd, attrs, opts) => {
+            if (cmd === 'LIST' && opts && opts.untagged && opts.untagged.LIST) {
+                await opts.untagged.LIST({
+                    attributes: [[{ value: '\\HasNoChildren' }], { value: '/' }, { value: 'Folder1' }]
+                });
+            }
+            if (cmd === 'LSUB' && opts && opts.untagged && opts.untagged.LSUB) {
+                // Some servers only report \\NonExistent in LSUB responses
+                await opts.untagged.LSUB({
+                    attributes: [[{ value: '\\NonExistent' }], { value: '/' }, { value: 'Folder1' }]
+                });
+            }
+            return { next: () => {} };
+        }
+    });
+
+    const result = await listCommand(connection, '', '*');
+    const folder = result.find(e => e.path === 'Folder1');
+    test.ok(folder);
+    test.equal(folder.subscribed, true);
+    test.equal(folder.flags.has('\\NonExistent'), true);
+    // RFC 5258: \\NonExistent merged from LSUB implies \\Noselect
+    test.equal(folder.flags.has('\\Noselect'), true);
+    test.done();
+};
+
+module.exports['Commands: list does not STATUS NonExistent mailboxes'] = async test => {
+    let statusPaths = [];
+    const connection = createMockConnection({
+        state: 3,
+        capabilities: new Map(),
+        run: async (cmd, path) => {
+            if (cmd === 'STATUS') {
+                statusPaths.push(path);
+                return { messages: 10 };
+            }
+        },
+        exec: async (cmd, attrs, opts) => {
+            if (cmd === 'LIST' && opts && opts.untagged && opts.untagged.LIST) {
+                await opts.untagged.LIST({
+                    attributes: [[{ value: '\\HasNoChildren' }], { value: '/' }, { value: 'INBOX' }]
+                });
+                await opts.untagged.LIST({
+                    attributes: [[{ value: '\\NonExistent' }], { value: '/' }, { value: 'Phantom' }]
+                });
+            }
+            return { next: () => {} };
+        }
+    });
+
+    await listCommand(connection, '', '*', { statusQuery: { messages: true } });
+    // STATUS runs for the selectable mailbox only
+    test.deepEqual(statusPaths, ['INBOX']);
+    test.done();
+};
+
 module.exports['Commands: list XLIST removes Inbox flag from non-INBOX'] = async test => {
     const connection = createMockConnection({
         state: 3,
@@ -7353,6 +7447,55 @@ module.exports['Commands: authenticate with OAUTHBEARER'] = async test => {
     test.equal(execArgs.cmd, 'AUTHENTICATE');
     test.equal(execArgs.args[0].value, 'OAUTHBEARER');
     test.ok(connection.authCapabilities.has('AUTH=OAUTHBEARER'));
+    test.ok(decodeSaslPayload(execArgs).includes('port=993'), 'the payload should report the connection port');
+    test.done();
+};
+
+module.exports['Commands: OAUTHBEARER payload reports the port actually in use'] = async test => {
+    // Regression: the port field was hardcoded to 993 - see lib/commands/authenticate.js.
+    let execArgs = null;
+    const connection = createMockConnection({
+        state: 1,
+        capabilities: new Map([['AUTH=OAUTHBEARER', true]]),
+        servername: 'imap.example.com',
+        port: 143,
+        authCapabilities: new Map(),
+        exec: async (cmd, args) => {
+            execArgs = { cmd, args };
+            return { next: () => {} };
+        },
+        write: () => {}
+    });
+
+    await authenticateCommand(connection, 'user@example.com', { accessToken: 'token123' });
+
+    const payload = decodeSaslPayload(execArgs);
+    test.ok(payload.includes('port=143'), `expected port=143 in the SASL payload, got: ${JSON.stringify(payload)}`);
+    test.ok(payload.includes('host=imap.example.com'), 'the host field should still describe the connection');
+    test.done();
+};
+
+module.exports['Commands: OAUTHBEARER payload falls back to host when servername is false'] = async test => {
+    // imap-flow.js sets servername = false for a bare-IP host, which rendered as "host=false".
+    let execArgs = null;
+    const connection = createMockConnection({
+        state: 1,
+        capabilities: new Map([['AUTH=OAUTHBEARER', true]]),
+        servername: false,
+        host: '198.51.100.7',
+        authCapabilities: new Map(),
+        exec: async (cmd, args) => {
+            execArgs = { cmd, args };
+            return { next: () => {} };
+        },
+        write: () => {}
+    });
+
+    await authenticateCommand(connection, 'user@example.com', { accessToken: 'token123' });
+
+    const payload = decodeSaslPayload(execArgs);
+    test.ok(payload.includes('host=198.51.100.7'), `expected the host as fallback, got: ${JSON.stringify(payload)}`);
+    test.ok(!payload.includes('host=false'), 'the literal "host=false" must never be sent');
     test.done();
 };
 

package/test/connection-edge-cases-test.js

@@ -143,7 +143,7 @@ module.exports['Connection Edge: Connection with default values'] = test => {
     });
 
     test.ok(client, 'Client should be created with defaults');
-    test.equal(client.port, 110, 'Should use default port');
+    test.equal(client.port, 143, 'Should use default port');
     test.equal(client.secureConnection, false, 'Should default to non-secure');
     test.done();
 };
@@ -155,7 +155,7 @@ module.exports['Connection Edge: Port number handling'] = test => {
         secure: false,
         auth: { user: 'test', pass: 'test' }
     });
-    test.equal(client1.port, 110, 'Default non-secure port');
+    test.equal(client1.port, 143, 'Default non-secure port');
 
     let client2 = new ImapFlow({
         host: 'imap.example.com',

package/test/connection-test.js

@@ -20,7 +20,7 @@ module.exports['Connection: Default options'] = test => {
         auth: { user: 'test', pass: 'test' }
     });
 
-    test.equal(client.port, 110);
+    test.equal(client.port, 143);
     test.equal(client.secureConnection, false);
     test.done();
 };

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

@@ -1,12 +0,0 @@
-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

@@ -1,102 +0,0 @@
-# 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@v6
-
-    # 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}}"