emailengine-app 2.60.1 → 2.61.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [2.61.0](https://github.com/postalsys/emailengine/compare/v2.60.1...v2.61.0) (2025-12-22)
+
+
+### Features
+
+* Add check-bounce CLI command for analyzing bounce emails ([ae3a85d](https://github.com/postalsys/emailengine/commit/ae3a85dd5acdf9c893196284487e536ac3d6d9ec))
+* Add Exim-style bounce detection for diagnostic messages ([b82e588](https://github.com/postalsys/emailengine/commit/b82e588d3e699f3c757c6a01f3fb9933c94bbb4c))
+* Improve ARF complaint detection and add comprehensive tests ([5533552](https://github.com/postalsys/emailengine/commit/55335526a19c6948675d126d1dbb14db353253a0))
+* Improve autoreply detection and add comprehensive tests ([1cf179f](https://github.com/postalsys/emailengine/commit/1cf179f8289eb05e8add420fe02d6410f61718cc))
+* Improve bounce detection coverage for non-standard formats ([5393872](https://github.com/postalsys/emailengine/commit/53938724c699b32177ece83c3d88be9a5432c067))
+* Improve bounce detection for legacy formats ([90a0289](https://github.com/postalsys/emailengine/commit/90a0289f7999e23149e14ff6ea5d703de056d5b0))
+* Replace static help.txt with dynamic CLI help system ([4cd5fb0](https://github.com/postalsys/emailengine/commit/4cd5fb059c2bf7436c4262a7daee1e85f535c322))
+
+
+### Bug Fixes
+
+* Detect "Out of the Office" autoreply subject pattern ([7191c50](https://github.com/postalsys/emailengine/commit/7191c50ae62930a66bf6598cb55f94130e022cf9))
+* Harden bounce detection against edge cases and ReDoS attacks ([d6c72c2](https://github.com/postalsys/emailengine/commit/d6c72c29d4c2bc1a20025204cc0cf20f803b04a6))
+
 ## [2.60.1](https://github.com/postalsys/emailengine/compare/v2.60.0...v2.60.1) (2025-12-17)
 
 

package/bin/emailengine.js

@@ -17,6 +17,309 @@ const argv = require('minimist')(process.argv.slice(2));
 const msgpack = require('msgpack5')();
 const crypto = require('crypto');
 
+// Command definitions for dynamic help generation
+const COMMANDS = {
+    '': {
+        description: 'Start the EmailEngine server'
+    },
+    help: {
+        description: 'Show help for a command'
+    },
+    version: {
+        description: 'Show version number'
+    },
+    license: {
+        description: 'Show license information',
+        subcommands: {
+            export: { description: 'Export license key for backup' },
+            import: {
+                description: 'Import license key',
+                options: [{ name: '--license, -l', description: 'Encoded license key', type: 'string' }]
+            }
+        }
+    },
+    password: {
+        description: 'Set or reset admin password',
+        options: [
+            { name: '--password, -p', description: 'Password to set (auto-generated if not provided)', type: 'string' },
+            { name: '--hash, -r', description: 'Output password hash instead of plaintext', type: 'boolean' }
+        ]
+    },
+    scan: {
+        description: 'Scan Redis keyspace and output as CSV'
+    },
+    encrypt: {
+        description: 'Manage field-level encryption for stored credentials',
+        options: [{ name: '--decrypt', description: 'Previous secret for re-encryption (repeatable)', type: 'string' }]
+    },
+    tokens: {
+        description: 'Manage API access tokens',
+        subcommands: {
+            issue: {
+                description: 'Create a new access token',
+                options: [
+                    { name: '--description, -d', description: 'Token description', type: 'string' },
+                    { name: '--scope, -s', description: 'Access scope', type: 'string', default: '*' },
+                    { name: '--account, -a', description: 'Limit token to specific account', type: 'string' }
+                ]
+            },
+            export: {
+                description: 'Export token for backup',
+                options: [{ name: '--token, -t', description: 'Token to export', type: 'string' }]
+            },
+            import: {
+                description: 'Import previously exported token',
+                options: [{ name: '--token, -t', description: 'Exported token data', type: 'string' }]
+            }
+        }
+    },
+    export: {
+        description: 'Export account data including credentials',
+        options: [{ name: '--account, -a', description: 'Account ID to export', type: 'string' }]
+    },
+    'check-bounce': {
+        description: 'Analyze a bounce email and classify it',
+        options: [{ name: '--file, -f', description: 'Path to EML file', type: 'string' }],
+        example: 'emailengine check-bounce /path/to/bounce.eml'
+    }
+};
+
+const GLOBAL_OPTIONS = [
+    { name: '-h, --help', description: 'Show this help message' },
+    { name: '--dbs.redis', description: 'Redis connection URL', type: 'string', group: 'General' },
+    { name: '--workers.imap', description: 'Number of IMAP worker threads', type: 'number', default: 4, group: 'General' },
+    { name: '--settings', description: 'Pre-configured settings as JSON', type: 'json-string', group: 'General' },
+    { name: '--service.secret', description: 'Secret key for encrypting stored credentials', type: 'string', group: 'General' },
+    { name: '--service.commandTimeout', description: 'Maximum time for IMAP commands', type: 'number/string', default: '10s', group: 'General' },
+    { name: '--service.setupDelay', description: 'Delay between worker connection assignments', type: 'number/string', default: '0ms', group: 'General' },
+    { name: '--log.level', description: 'Logging level', type: 'string', default: 'trace', group: 'General' },
+    { name: '--log.raw', description: 'Log raw IMAP traffic', type: 'boolean', default: false, group: 'General' },
+    { name: '--workers.webhooks', description: 'Number of webhook worker threads', type: 'number', default: 1, group: 'General' },
+    { name: '--api.host', description: 'API server bind address', type: 'string', default: '127.0.0.1', group: 'API server' },
+    { name: '--api.port', description: 'API server port', type: 'number', default: 3000, group: 'API server' },
+    { name: '--api.maxSize', description: 'Maximum attachment size', type: 'number/string', default: '5M', group: 'API server' },
+    { name: '--queues.notify', description: 'Concurrent webhook deliveries', type: 'number', default: 1, group: 'Background tasks' },
+    { name: '--queues.submit', description: 'Concurrent email submissions', type: 'number', default: 1, group: 'Background tasks' },
+    { name: '--smtp.enabled', description: 'Enable SMTP submission server', type: 'boolean', default: false, group: 'SMTP server' },
+    { name: '--smtp.secret', description: 'Shared SMTP password for all accounts', type: 'string', group: 'SMTP server' },
+    { name: '--smtp.host', description: 'SMTP server bind address', type: 'string', default: '127.0.0.1', group: 'SMTP server' },
+    { name: '--smtp.port', description: 'SMTP server port', type: 'number', default: 2525, group: 'SMTP server' },
+    { name: '--smtp.proxy', description: 'Enable HAProxy PROXY protocol', type: 'boolean', default: false, group: 'SMTP server' },
+    { name: '--smtp.maxMessageSize', description: 'Maximum email size', type: 'number/string', default: '25M', group: 'SMTP server' }
+];
+
+// Help formatting functions
+function getTerminalWidth() {
+    // Check stderr first since help outputs there, fallback to stdout, then 80
+    return process.stderr.columns || process.stdout.columns || 80;
+}
+
+function wrapText(text, width, indent) {
+    if (width <= 0) {
+        return text;
+    }
+    const words = text.split(' ');
+    const lines = [];
+    let currentLine = '';
+
+    for (const word of words) {
+        if (currentLine.length === 0) {
+            currentLine = word;
+        } else if (currentLine.length + 1 + word.length <= width) {
+            currentLine += ' ' + word;
+        } else {
+            lines.push(currentLine);
+            currentLine = word;
+        }
+    }
+    if (currentLine) {
+        lines.push(currentLine);
+    }
+
+    return lines.join('\n' + ' '.repeat(indent));
+}
+
+function formatLine(name, description, type, defaultVal, width, nameWidth) {
+    const indent = 2;
+    const gap = 2;
+    let line = ' '.repeat(indent) + name.padEnd(nameWidth);
+
+    let descParts = [description];
+    if (type) {
+        descParts.push(`[${type}]`);
+    }
+    if (defaultVal !== undefined && defaultVal !== null) {
+        descParts.push(`[default: ${defaultVal}]`);
+    }
+
+    const descText = descParts.join(' ');
+    const descWidth = width - nameWidth - indent - gap;
+
+    if (descWidth > 20) {
+        line += ' '.repeat(gap) + wrapText(descText, descWidth, nameWidth + indent + gap);
+    } else {
+        line += ' '.repeat(gap) + descText;
+    }
+
+    return line;
+}
+
+// Calculate global name width for consistent alignment
+function calculateGlobalNameWidth() {
+    let maxWidth = 0;
+
+    // Commands
+    for (const cmd of Object.keys(COMMANDS)) {
+        const cmdName = cmd ? `emailengine ${cmd}` : 'emailengine';
+        maxWidth = Math.max(maxWidth, cmdName.length);
+        if (COMMANDS[cmd].subcommands) {
+            maxWidth = Math.max(maxWidth, `emailengine ${cmd} [command]`.length);
+            for (const subCmd of Object.keys(COMMANDS[cmd].subcommands)) {
+                maxWidth = Math.max(maxWidth, `emailengine ${cmd} ${subCmd}`.length);
+                const subDef = COMMANDS[cmd].subcommands[subCmd];
+                if (subDef.options) {
+                    for (const opt of subDef.options) {
+                        maxWidth = Math.max(maxWidth, opt.name.length);
+                    }
+                }
+            }
+        }
+        if (COMMANDS[cmd].options) {
+            for (const opt of COMMANDS[cmd].options) {
+                maxWidth = Math.max(maxWidth, opt.name.length);
+            }
+        }
+    }
+
+    // Global options
+    for (const opt of GLOBAL_OPTIONS) {
+        maxWidth = Math.max(maxWidth, opt.name.length);
+    }
+
+    return maxWidth;
+}
+
+function generateHelp() {
+    const width = getTerminalWidth();
+    const nameWidth = calculateGlobalNameWidth();
+    const lines = [];
+
+    lines.push('emailengine [command] [options]');
+    lines.push('');
+    lines.push(wrapText(
+        'EmailEngine is the self-hosted service that allows you to access any email account using an easy-to-use REST API.',
+        width,
+        0
+    ));
+    lines.push('');
+    lines.push('Commands:');
+
+    // Output commands
+    for (const [cmd, def] of Object.entries(COMMANDS)) {
+        const cmdName = cmd ? `emailengine ${cmd}` : 'emailengine';
+        lines.push(formatLine(cmdName, def.description, null, null, width, nameWidth));
+        if (def.subcommands) {
+            lines.push(formatLine(
+                `emailengine ${cmd} [command]`,
+                `${cmd.charAt(0).toUpperCase() + cmd.slice(1)} management`,
+                null,
+                null,
+                width,
+                nameWidth
+            ));
+        }
+    }
+
+    // Output global options by group
+    lines.push('');
+    lines.push('Options:');
+
+    let currentGroup = null;
+    for (const opt of GLOBAL_OPTIONS) {
+        if (opt.group && opt.group !== currentGroup) {
+            currentGroup = opt.group;
+            lines.push('');
+            lines.push('  ' + currentGroup + ':');
+        }
+        lines.push(formatLine(opt.name, opt.description, opt.type, opt.default, width, nameWidth));
+    }
+
+    // Output subcommand details
+    for (const [cmd, def] of Object.entries(COMMANDS)) {
+        if (def.subcommands) {
+            lines.push('');
+            lines.push(`${cmd.charAt(0).toUpperCase() + cmd.slice(1)} management commands:`);
+            for (const [subCmd, subDef] of Object.entries(def.subcommands)) {
+                lines.push(formatLine(`emailengine ${cmd} ${subCmd}`, subDef.description, null, null, width, nameWidth));
+                if (subDef.options) {
+                    for (const opt of subDef.options) {
+                        lines.push(formatLine(opt.name, opt.description, opt.type, opt.default, width, nameWidth));
+                    }
+                }
+            }
+        } else if (def.options) {
+            lines.push('');
+            lines.push(`${cmd.charAt(0).toUpperCase() + cmd.slice(1).replace(/-/g, ' ')} options:`);
+            lines.push(formatLine(`emailengine ${cmd}`, def.description, null, null, width, nameWidth));
+            for (const opt of def.options) {
+                lines.push(formatLine(opt.name, opt.description, opt.type, opt.default, width, nameWidth));
+            }
+            if (def.example) {
+                lines.push('');
+                lines.push('  Example: ' + def.example);
+            }
+        }
+    }
+
+    return lines.join('\n');
+}
+
+function generateCommandHelp(cmdName) {
+    const width = getTerminalWidth();
+    const nameWidth = calculateGlobalNameWidth();
+    const lines = [];
+
+    // Check if command exists
+    if (!COMMANDS[cmdName]) {
+        return null;
+    }
+
+    const def = COMMANDS[cmdName];
+
+    lines.push(`emailengine ${cmdName} [options]`);
+    lines.push('');
+    lines.push(wrapText(def.description, width, 0));
+
+    if (def.subcommands) {
+        lines.push('');
+        lines.push('Commands:');
+        for (const [subCmd, subDef] of Object.entries(def.subcommands)) {
+            lines.push(formatLine(`emailengine ${cmdName} ${subCmd}`, subDef.description, null, null, width, nameWidth));
+            if (subDef.options) {
+                lines.push('');
+                lines.push('  Options:');
+                for (const opt of subDef.options) {
+                    lines.push(formatLine(opt.name, opt.description, opt.type, opt.default, width, nameWidth));
+                }
+            }
+        }
+    } else if (def.options) {
+        lines.push('');
+        lines.push('Options:');
+        for (const opt of def.options) {
+            lines.push(formatLine(opt.name, opt.description, opt.type, opt.default, width, nameWidth));
+        }
+    }
+
+    if (def.example) {
+        lines.push('');
+        lines.push('Example:');
+        lines.push('  ' + def.example);
+    }
+
+    return lines.join('\n');
+}
+
 function run() {
     let cmd = ((argv._ && argv._[0]) || '').toLowerCase();
     if (!cmd) {
@@ -88,16 +391,24 @@ function run() {
             break;
 
         case 'help':
-            // Show version
-            fs.readFile(pathlib.join(__dirname, '..', 'help.txt'), (err, helpText) => {
-                if (err) {
-                    console.error('Failed to load help information');
-                    console.error(err);
-                    return process.exit(1);
+            {
+                // Show help for specific command or general help
+                let helpCmd = ((argv._ && argv._[1]) || '').toLowerCase();
+                if (helpCmd) {
+                    let cmdHelp = generateCommandHelp(helpCmd);
+                    if (cmdHelp) {
+                        console.error(cmdHelp);
+                    } else {
+                        console.error(`Unknown command: ${helpCmd}`);
+                        console.error('');
+                        console.error('Run "emailengine help" to see available commands.');
+                        process.exit(1);
+                    }
+                } else {
+                    console.error(generateHelp());
                 }
-                console.error(helpText.toString().trim());
                 process.exit();
-            });
+            }
             break;
 
         case 'version':
@@ -290,6 +601,75 @@ function run() {
             }
             break;
 
+        case 'check-bounce':
+            {
+                process.title = 'emailengine-check-bounce';
+                const { bounceDetect } = require('../lib/bounce-detect');
+                const bounceClassifier = require('@postalsys/bounce-classifier');
+
+                let emlPath = argv._[1] || argv.file || argv.f;
+
+                if (!emlPath) {
+                    console.error('Error: EML file path is required');
+                    console.error('Usage: emailengine check-bounce <path-to-eml-file>');
+                    console.error('       emailengine check-bounce --file <path-to-eml-file>');
+                    return process.exit(1);
+                }
+
+                // Resolve the path
+                emlPath = pathlib.resolve(emlPath);
+
+                // Check if file exists
+                if (!fs.existsSync(emlPath)) {
+                    console.error(`Error: File not found: ${emlPath}`);
+                    return process.exit(1);
+                }
+
+                const checkBounce = async () => {
+                    // Initialize the bounce classifier
+                    await bounceClassifier.initialize();
+
+                    // Read the EML file
+                    const emlStream = fs.createReadStream(emlPath);
+
+                    // Detect bounce information
+                    const bounce = await bounceDetect(emlStream);
+
+                    // Classify the bounce if we have a response message
+                    if (bounce?.response?.message) {
+                        const classification = await bounceClassifier.classify(bounce.response.message);
+
+                        if (classification?.label) {
+                            bounce.response.category = classification.label;
+                        }
+                        if (classification?.action) {
+                            bounce.response.recommendedAction = classification.action;
+                        }
+                        if (classification?.blocklist) {
+                            bounce.response.blocklist = classification.blocklist;
+                        }
+                        if (classification?.retryAfter) {
+                            bounce.response.retryAfter = classification.retryAfter;
+                        }
+                    }
+
+                    return bounce;
+                };
+
+                checkBounce()
+                    .then(result => {
+                        process.stdout.write(JSON.stringify(result, null, 2));
+                        process.stdout.write('\n');
+                        return process.exit(0);
+                    })
+                    .catch(err => {
+                        console.error('Failed to analyze bounce email');
+                        console.error(err);
+                        return process.exit(1);
+                    });
+            }
+            break;
+
         default:
             // run normally
             require('../server');

package/data/google-crawlers.json

@@ -1,5 +1,5 @@
 {
-    "creationTime": "2025-12-16T15:46:10.000000",
+    "creationTime": "2025-12-18T15:45:44.000000",
     "prefixes": [
         {
             "ipv6Prefix": "2001:4860:4801:2008::/64"

package/lib/arf-detect.js

@@ -77,7 +77,9 @@ const arfDetect = async messageInfo => {
             }
 
             case 'message/rfc822':
-            case 'message/rfc822-headers': {
+            case 'message/rfc822-headers':
+            case 'text/rfc822-headers':
+            case 'text/rfc822-header': {
                 let contents = (attachment.content || '').toString();
                 const headerPos = contents.match(/\r?\n\r?\n/);