imapflow 1.4.7 → 1.4.9

package/test/search-test.js

@@ -14,6 +14,7 @@ function makeConnection({ hasEsearch = true } = {}) {
         state: 'SELECTED',
         states: { SELECTED: 'SELECTED' },
         capabilities: caps,
+        enabled: new Set(),
         exec: async () => ({ next: () => {} }),
         log: { warn: () => {} }
     };
@@ -72,23 +73,6 @@ module.exports['ESEARCH: parseEsearchResponse PARTIAL (Array form)'] = test => {
     test.done();
 };
 
-module.exports['ESEARCH: parseEsearchResponse PARTIAL (LIST object form)'] = test => {
-    // Also handle {type: 'LIST', attributes: [...]} form for robustness
-    const attrs = [
-        { type: 'ATOM', value: 'PARTIAL' },
-        {
-            type: 'LIST',
-            attributes: [
-                { type: 'ATOM', value: '1:100' },
-                { type: 'ATOM', value: '1001,1003:1010,1015' }
-            ]
-        }
-    ];
-    const result = parseEsearchResponse(attrs);
-    test.deepEqual(result.partial, { range: '1:100', messages: '1001,1003:1010,1015' });
-    test.done();
-};
-
 module.exports['ESEARCH: parseEsearchResponse COUNT + PARTIAL combined'] = test => {
     const attrs = [
         { type: 'ATOM', value: 'COUNT' },
@@ -116,12 +100,14 @@ module.exports['ESEARCH: emits RETURN clause when returnOptions present and serv
         capturedAttributes = JSON.stringify(attributes);
         return { next: () => {} };
     };
-    searchCmd(conn, { seen: false }, { uid: true, returnOptions: ['COUNT'] }).then(() => {
-        test.equal(capturedCommand, 'UID SEARCH');
-        test.ok(capturedAttributes.includes('"RETURN"'), 'should include RETURN atom');
-        test.ok(capturedAttributes.includes('"COUNT"'), 'should include COUNT in return list');
-        test.done();
-    }).catch(err => test.done(err));
+    searchCmd(conn, { seen: false }, { uid: true, returnOptions: ['COUNT'] })
+        .then(() => {
+            test.equal(capturedCommand, 'UID SEARCH');
+            test.ok(capturedAttributes.includes('"RETURN"'), 'should include RETURN atom');
+            test.ok(capturedAttributes.includes('"COUNT"'), 'should include COUNT in return list');
+            test.done();
+        })
+        .catch(err => test.done(err));
 };
 
 module.exports['ESEARCH: RETURN clause includes PARTIAL range atom'] = test => {
@@ -131,11 +117,13 @@ module.exports['ESEARCH: RETURN clause includes PARTIAL range atom'] = test => {
         capturedAttributes = JSON.stringify(attributes);
         return { next: () => {} };
     };
-    searchCmd(conn, { seen: false }, { uid: true, returnOptions: [{ partial: '1:100' }] }).then(() => {
-        test.ok(capturedAttributes.includes('"PARTIAL"'), 'should include PARTIAL atom');
-        test.ok(capturedAttributes.includes('"1:100"'), 'should include range string');
-        test.done();
-    }).catch(err => test.done(err));
+    searchCmd(conn, { seen: false }, { uid: true, returnOptions: [{ partial: '1:100' }] })
+        .then(() => {
+            test.ok(capturedAttributes.includes('"PARTIAL"'), 'should include PARTIAL atom');
+            test.ok(capturedAttributes.includes('"1:100"'), 'should include range string');
+            test.done();
+        })
+        .catch(err => test.done(err));
 };
 
 module.exports['ESEARCH: no RETURN clause when server lacks ESEARCH capability'] = test => {
@@ -152,12 +140,14 @@ module.exports['ESEARCH: no RETURN clause when server lacks ESEARCH capability']
         }
         return { next: () => {} };
     };
-    searchCmd(conn, { seen: false }, { uid: true, returnOptions: ['COUNT', 'ALL'] }).then(result => {
-        test.ok(!capturedAttributes.includes('"RETURN"'), 'should NOT include RETURN when no ESEARCH');
-        test.ok(Array.isArray(result), 'should return number[] when ESEARCH unavailable');
-        test.deepEqual(result, [1, 2, 3]);
-        test.done();
-    }).catch(err => test.done(err));
+    searchCmd(conn, { seen: false }, { uid: true, returnOptions: ['COUNT', 'ALL'] })
+        .then(result => {
+            test.ok(!capturedAttributes.includes('"RETURN"'), 'should NOT include RETURN when no ESEARCH');
+            test.ok(Array.isArray(result), 'should return number[] when ESEARCH unavailable');
+            test.deepEqual(result, [1, 2, 3]);
+            test.done();
+        })
+        .catch(err => test.done(err));
 };
 
 module.exports['ESEARCH: parseEsearchResponse skips non-ATOM tokens'] = test => {
@@ -247,11 +237,13 @@ module.exports['ESEARCH: backward compat — no returnOptions returns number[]']
         return { next: () => {} };
     };
     // No returnOptions — must return number[] even if server has ESEARCH
-    searchCmd(conn, { seen: true }, { uid: true }).then(result => {
-        test.ok(Array.isArray(result));
-        test.deepEqual(result, [10, 20]);
-        test.done();
-    }).catch(err => test.done(err));
+    searchCmd(conn, { seen: true }, { uid: true })
+        .then(result => {
+            test.ok(Array.isArray(result));
+            test.deepEqual(result, [10, 20]);
+            test.done();
+        })
+        .catch(err => test.done(err));
 };
 
 // ── imap-flow.js public API fallback test ─────────────────────────────────
@@ -271,16 +263,19 @@ module.exports['imap-flow: search() derives ESearchResult when server has no ESE
     // Stub run() to return a sorted number[]
     client.run = async () => [10, 20, 30, 40, 50];
 
-    client.search({ seen: false }, { uid: true, returnOptions: ['COUNT', 'MIN', 'MAX', 'ALL'] }).then(result => {
-        test.equal(typeof result, 'object', 'should return object, not array');
-        test.ok(!Array.isArray(result), 'should not be an array');
-        test.equal(result.count, 5);
-        test.equal(result.min, 10);
-        test.equal(result.max, 50);
-        // packMessageRange([10,20,30,40,50]) → "10,20,30,40,50" (non-contiguous)
-        test.ok(typeof result.all === 'string' && result.all.length > 0, 'all should be non-empty compact string');
-        test.done();
-    }).catch(err => test.done(err));
+    client
+        .search({ seen: false }, { uid: true, returnOptions: ['COUNT', 'MIN', 'MAX', 'ALL'] })
+        .then(result => {
+            test.equal(typeof result, 'object', 'should return object, not array');
+            test.ok(!Array.isArray(result), 'should not be an array');
+            test.equal(result.count, 5);
+            test.equal(result.min, 10);
+            test.equal(result.max, 50);
+            // packMessageRange([10,20,30,40,50]) → "10,20,30,40,50" (non-contiguous)
+            test.ok(typeof result.all === 'string' && result.all.length > 0, 'all should be non-empty compact string');
+            test.done();
+        })
+        .catch(err => test.done(err));
 };
 
 module.exports['imap-flow: search() fallback with empty result set'] = test => {
@@ -294,9 +289,12 @@ module.exports['imap-flow: search() fallback with empty result set'] = test => {
     client.state = client.states.SELECTED;
     client.capabilities = new Map();
     client.run = async () => [];
-    client.search({}, { uid: true, returnOptions: ['COUNT', 'ALL'] }).then(result => {
-        test.equal(result.count, 0);
-        test.equal(result.all, undefined, 'all should be absent for empty result');
-        test.done();
-    }).catch(err => test.done(err));
+    client
+        .search({}, { uid: true, returnOptions: ['COUNT', 'ALL'] })
+        .then(result => {
+            test.equal(result.count, 0);
+            test.equal(result.all, undefined, 'all should be absent for empty result');
+            test.done();
+        })
+        .catch(err => test.done(err));
 };

package/test/tools-test.js

@@ -7,7 +7,8 @@ const iconv = require('iconv-lite');
 
 // Mock connection for testing
 let createMockConnection = (options = {}) => ({
-    enabled: new Set(options.utf8 ? ['UTF8=ACCEPT'] : []),
+    enabled: new Set(options.enabled || (options.utf8 ? ['UTF8=ACCEPT'] : [])),
+    capabilities: new Map(options.capabilities || []),
     namespace: options.namespace || null
 });
 
@@ -162,6 +163,102 @@ module.exports['Tools: updateCapabilities with valid list'] = test => {
     test.done();
 };
 
+module.exports['Tools: updateCapabilities normalizes IMAP4rev2 casing'] = test => {
+    let list = [{ value: 'IMAP4rev2' }, { value: 'imap4rev1' }];
+    let result = tools.updateCapabilities(list);
+    // Wire tokens are uppercased, but the rev1/rev2 keys use the RFC spelling
+    test.equal(result.get('IMAP4rev2'), true);
+    test.equal(result.get('IMAP4rev1'), true);
+    test.equal(result.has('IMAP4REV2'), false);
+    test.done();
+};
+
+module.exports['Tools: isRev2Active for rev2-only server'] = test => {
+    // rev2 without rev1 means rev2 is the base protocol, no ENABLE needed
+    let connection = createMockConnection({ capabilities: [['IMAP4rev2', true]] });
+    test.equal(tools.isRev2Active(connection), true);
+    test.done();
+};
+
+module.exports['Tools: isRev2Active for dual server without ENABLE'] = test => {
+    // Advertising both keeps the session in rev1 mode until ENABLE IMAP4rev2
+    let connection = createMockConnection({
+        capabilities: [
+            ['IMAP4rev1', true],
+            ['IMAP4rev2', true]
+        ]
+    });
+    test.equal(tools.isRev2Active(connection), false);
+    test.done();
+};
+
+module.exports['Tools: isRev2Active for dual server with ENABLE'] = test => {
+    let connection = createMockConnection({
+        capabilities: [
+            ['IMAP4rev1', true],
+            ['IMAP4rev2', true]
+        ],
+        enabled: ['IMAP4REV2']
+    });
+    test.equal(tools.isRev2Active(connection), true);
+    test.done();
+};
+
+module.exports['Tools: isRev2Active for rev1-only server'] = test => {
+    let connection = createMockConnection({ capabilities: [['IMAP4rev1', true]] });
+    test.equal(tools.isRev2Active(connection), false);
+    test.done();
+};
+
+module.exports['Tools: hasCapability with advertised token'] = test => {
+    let connection = createMockConnection({
+        capabilities: [
+            ['IMAP4rev1', true],
+            ['UIDPLUS', true]
+        ]
+    });
+    test.equal(tools.hasCapability(connection, 'UIDPLUS'), true);
+    test.equal(tools.hasCapability(connection, 'MOVE'), false);
+    test.done();
+};
+
+module.exports['Tools: hasCapability folds extensions into active rev2'] = test => {
+    let connection = createMockConnection({ capabilities: [['IMAP4rev2', true]] });
+    // RFC 9051 Appendix E folds these into base IMAP4rev2
+    for (let capability of ['UIDPLUS', 'MOVE', 'NAMESPACE', 'ESEARCH', 'LITERAL-', 'LIST-EXTENDED', 'LIST-STATUS', 'SPECIAL-USE', 'ENABLE']) {
+        test.equal(tools.hasCapability(connection, capability), true, `${capability} should be folded into rev2`);
+    }
+    // BINARY is intentionally not folded
+    test.equal(tools.hasCapability(connection, 'BINARY'), false);
+    test.done();
+};
+
+module.exports['Tools: hasCapability does not fold on unenabled dual server'] = test => {
+    let connection = createMockConnection({
+        capabilities: [
+            ['IMAP4rev1', true],
+            ['IMAP4rev2', true]
+        ]
+    });
+    // Session is in rev1 mode - only explicitly advertised tokens count
+    test.equal(tools.hasCapability(connection, 'UIDPLUS'), false);
+    test.done();
+};
+
+module.exports['Tools: encodePath keeps UTF-8 when rev2 is active'] = test => {
+    let connection = createMockConnection({ capabilities: [['IMAP4rev2', true]] });
+    // rev2 mailbox names are native UTF-8, modified UTF-7 must not be applied
+    test.equal(tools.encodePath(connection, 'T\u00f5rva'), 'T\u00f5rva');
+    test.done();
+};
+
+module.exports['Tools: decodePath keeps ampersand sequences when rev2 is active'] = test => {
+    let connection = createMockConnection({ capabilities: [['IMAP4rev2', true]] });
+    // Under rev2 an "&"-sequence is a literal name, not modified UTF-7
+    test.equal(tools.decodePath(connection, 'A&AOQ-B'), 'A&AOQ-B');
+    test.done();
+};
+
 module.exports['Tools: updateCapabilities with APPENDLIMIT'] = test => {
     let list = [{ value: 'APPENDLIMIT=52428800' }];
     let result = tools.updateCapabilities(list);
@@ -493,6 +590,30 @@ module.exports['Tools: expandRange with same start/end'] = test => {
     test.done();
 };
 
+module.exports['Tools: expandRange skips entries that are not valid nz-numbers'] = test => {
+    // Server-supplied garbage must not produce bogus ids or endless loops
+    test.deepEqual(tools.expandRange('Infinity:5'), []);
+    test.deepEqual(tools.expandRange('0:3'), []);
+    test.deepEqual(tools.expandRange('abc,4,1:x'), [4]);
+    test.deepEqual(tools.expandRange('*'), []);
+    test.deepEqual(tools.expandRange('4294967296'), []);
+    test.done();
+};
+
+module.exports['Tools: expandRange caps hostile range spans'] = test => {
+    // A hostile range like 1:4294967295 is cut off at the expansion limit
+    // instead of exhausting memory
+    let result = tools.expandRange('1:4294967295');
+    test.equal(result.length, 0x1000000);
+    test.equal(result[0], 1);
+    test.equal(result[result.length - 1], 0x1000000);
+
+    let reverse = tools.expandRange('4294967295:4278190080');
+    test.equal(reverse.length, 0x1000000);
+    test.equal(reverse[0], 4294967295);
+    test.done();
+};
+
 // ============================================
 // packMessageRange tests
 // ============================================
@@ -1303,9 +1424,7 @@ module.exports['Tools: parseBodystructure parses message/rfc822 with envelope an
 };
 
 module.exports['Tools: parseBodystructure parses multipart with params and disposition'] = async test => {
-    let bs =
-        '(("TEXT" "PLAIN" NIL NIL NIL "7BIT" 10 1)("TEXT" "HTML" NIL NIL NIL "7BIT" 20 2) ' +
-        '"ALTERNATIVE" ("BOUNDARY" "xyz") ("inline" NIL) ("en"))';
+    let bs = '(("TEXT" "PLAIN" NIL NIL NIL "7BIT" 10 1)("TEXT" "HTML" NIL NIL NIL "7BIT" 20 2) "ALTERNATIVE" ("BOUNDARY" "xyz") ("inline" NIL) ("en"))';
     let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
     let node = tools.parseBodystructure(untagged.attributes[1][1]);
     test.equal(node.type, 'multipart/alternative');
@@ -1348,7 +1467,7 @@ module.exports['Tools: parseBodystructure handles minimal NIL fields'] = async t
 };
 
 module.exports['Tools: parseBodystructure decodes RFC 2231 charset continuation params'] = async test => {
-    let bs = "(\"TEXT\" \"PLAIN\" (\"name*0*\" \"utf-8''%E2%82%AC abc\" \"name*1\" \"def\") NIL NIL \"7BIT\" 10 1)";
+    let bs = '("TEXT" "PLAIN" ("name*0*" "utf-8\'\'%E2%82%AC abc" "name*1" "def") NIL NIL "7BIT" 10 1)';
     let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
     let node = tools.parseBodystructure(untagged.attributes[1][1]);
     test.equal(node.parameters.name, '€ abcdef');
@@ -1453,9 +1572,7 @@ module.exports['Tools: parseBodystructure empty-string size/linecount/language/l
 };
 
 module.exports['Tools: parseBodystructure message/rfc822 empty-string linecount'] = async test => {
-    let bs =
-        '("MESSAGE" "RFC822" NIL NIL NIL "7BIT" 100 ("d" "s" NIL NIL NIL NIL NIL NIL NIL NIL) ' +
-        '("TEXT" "PLAIN" NIL NIL NIL "7BIT" 1 1) "")';
+    let bs = '("MESSAGE" "RFC822" NIL NIL NIL "7BIT" 100 ("d" "s" NIL NIL NIL NIL NIL NIL NIL NIL) ("TEXT" "PLAIN" NIL NIL NIL "7BIT" 1 1) "")';
     let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
     let node = tools.parseBodystructure(untagged.attributes[1][1]);
     test.equal(node.type, 'message/rfc822');
@@ -1468,7 +1585,7 @@ module.exports['Tools: parseBodystructure decodes RFC 2231 with empty charset an
     // exercise the 2-char hex escape branch; the empty *1* continuation segment too.
     // value includes '=' / '?' (2-char hex escapes), a space (-> '_') and a TAB
     // (a <0x10 control char -> single-hex-digit escape needing a '0' pad).
-    let bs = "(\"TEXT\" \"PLAIN\" (\"name*0*\" \"''a=b?c d\te\" \"name*1*\" \"\") NIL NIL \"7BIT\" 1 1)";
+    let bs = '("TEXT" "PLAIN" ("name*0*" "\'\'a=b?c d\te" "name*1*" "") NIL NIL "7BIT" 1 1)';
     let untagged = await parser('* 1 FETCH (BODYSTRUCTURE ' + bs + ')');
     let node = tools.parseBodystructure(untagged.attributes[1][1]);
     test.ok(node.parameters.name.includes('a=b?c'));
@@ -1485,13 +1602,15 @@ module.exports['Tools: parseBodystructure parses empty-string body location'] =
     test.done();
 };
 
-module.exports['Tools: expandRange descending range to non-numeric second bound'] = test => {
-    test.deepEqual(tools.expandRange('5:abc'), [5, 4, 3, 2, 1, 0]);
+module.exports['Tools: expandRange skips descending range to non-numeric second bound'] = test => {
+    // Endpoints that are not valid nz-numbers make the whole entry invalid -
+    // the pre-hardening behavior expanded '5:abc' down to 0
+    test.deepEqual(tools.expandRange('5:abc'), []);
     test.done();
 };
 
-module.exports['Tools: expandRange tolerates non-numeric entries'] = test => {
-    test.deepEqual(tools.expandRange('abc,:5,1:3'), [0, 0, 1, 2, 3, 4, 5, 1, 2, 3]);
+module.exports['Tools: expandRange skips non-numeric entries but keeps valid ones'] = test => {
+    test.deepEqual(tools.expandRange('abc,:5,1:3'), [1, 2, 3]);
     test.done();
 };
 
@@ -1508,7 +1627,7 @@ module.exports['Tools: encodePath keeps name as-is when iconv encode throws'] =
         throw new Error('encode boom');
     };
     try {
-        let connection = { enabled: new Set() };
+        let connection = { enabled: new Set(), capabilities: new Map() };
         let result = tools.encodePath(connection, 'Tärä');
         test.equal(result, 'Tärä', 'falls back to the raw path');
     } finally {
@@ -1523,7 +1642,7 @@ module.exports['Tools: decodePath keeps name as-is when iconv decode throws'] =
         throw new Error('decode boom');
     };
     try {
-        let connection = { enabled: new Set() };
+        let connection = { enabled: new Set(), capabilities: new Map() };
         let result = tools.decodePath(connection, 'Inbox&AOk-');
         test.equal(result, 'Inbox&AOk-');
     } finally {

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}}"