postal-mime 2.4.5 → 2.4.7

package/.prettierignore

@@ -6,4 +6,5 @@ coverage
 .DS_Store
 yarn.lock
 package-lock.json
-CLAUDE.md
+CLAUDE.md
+CHANGELOG.md

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.4.7](https://github.com/postalsys/postal-mime/compare/v2.4.6...v2.4.7) (2025-10-07)
+
+
+### Bug Fixes
+
+* prevent email extraction from quoted strings in addressParser ([837d679](https://github.com/postalsys/postal-mime/commit/837d679b48cde95a111b8508a7aea23a28cbc12a))
+
+## [2.4.6](https://github.com/postalsys/postal-mime/compare/v2.4.5...v2.4.6) (2025-10-01)
+
+
+### Bug Fixes
+
+* add security limits for MIME parsing ([defbf11](https://github.com/postalsys/postal-mime/commit/defbf11e85c8233e6ff01a3d6fc10534b784c499))
+
 ## [2.4.5](https://github.com/postalsys/postal-mime/compare/v2.4.4...v2.4.5) (2025-09-29)
 
 

package/README.md

@@ -111,6 +111,8 @@ PostalMime.parse(email, options) -> Promise<ParsedEmail>
         -   `"base64"`
         -   `"utf8"`
         -   `"arraybuffer"` (no decoding, returns `ArrayBuffer`)
+    -   **maxNestingDepth** (number, default: `256`): Maximum allowed MIME part nesting depth. Throws an error if exceeded.
+    -   **maxHeadersSize** (number, default: `2097152`): Maximum allowed total header size in bytes (default 2MB). Throws an error if exceeded.
 
 **Returns**: A Promise that resolves to a structured object with the following properties:
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "postal-mime",
-    "version": "2.4.5",
+    "version": "2.4.7",
     "description": "Email parser for browser environments",
     "main": "./src/postal-mime.js",
     "exports": {
@@ -11,7 +11,8 @@
     "type": "module",
     "types": "postal-mime.d.ts",
     "scripts": {
-        "test": "eslint && node --test",
+        "test": "npm run lint && node --test",
+        "lint": "eslint",
         "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
         "format": "prettier --write \"**/*.{js,mjs,json}\" --ignore-path .prettierignore",
         "format:check": "prettier --check \"**/*.{js,mjs,json}\" --ignore-path .prettierignore"

package/postal-mime.d.ts

@@ -1,13 +1,24 @@
 export type RawEmail = string | ArrayBuffer | Uint8Array | Blob | Buffer | ReadableStream;
 
-export type Header = Record<string, string>;
+export type Header = {
+    key: string;
+    value: string;
+};
 
-export type Address = {
+export type Mailbox = {
     name: string;
-    address?: string;
-    group?: Address[]
+    address: string;
+    group?: undefined;
 };
 
+export type Address =
+    | Mailbox
+    | {
+          name: string;
+          address?: undefined;
+          group: Mailbox[];
+      };
+
 export type Attachment = {
     filename: string | null;
     mimeType: string;
@@ -22,7 +33,7 @@ export type Attachment = {
 
 export type Email = {
     headers: Header[];
-    from: Address;
+    from?: Address;
     sender?: Address;
     replyTo?: Address[];
     deliveredTo?: string;
@@ -31,7 +42,7 @@ export type Email = {
     cc?: Address[];
     bcc?: Address[];
     subject?: string;
-    messageId: string;
+    messageId?: string;
     inReplyTo?: string;
     references?: string;
     date?: string;
@@ -56,7 +67,9 @@ declare function decodeWords (
 declare type PostalMimeOptions = {
     rfc822Attachments?: boolean,
     forceRfc822Attachments?: boolean,
-    attachmentEncoding?: "base64" | "utf8" | "arraybuffer"
+    attachmentEncoding?: "base64" | "utf8" | "arraybuffer",
+    maxNestingDepth?: number,
+    maxHeadersSize?: number
 }
 
 declare class PostalMime {

package/src/address-parser.js

@@ -7,7 +7,6 @@ import { decodeWords } from './decode-strings.js';
  * @return {Object} Address object
  */
 function _handleAddress(tokens) {
-    let token;
     let isGroup = false;
     let state = 'text';
     let address;
@@ -16,28 +15,41 @@ function _handleAddress(tokens) {
         address: [],
         comment: [],
         group: [],
-        text: []
+        text: [],
+        textWasQuoted: [] // Track which text tokens came from inside quotes
     };
     let i;
     let len;
+    let insideQuotes = false; // Track if we're currently inside a quoted string
 
     // Filter out <addresses>, (comments) and regular text
     for (i = 0, len = tokens.length; i < len; i++) {
-        token = tokens[i];
+        let token = tokens[i];
+        let prevToken = i ? tokens[i - 1] : null;
         if (token.type === 'operator') {
             switch (token.value) {
                 case '<':
                     state = 'address';
+                    insideQuotes = false;
                     break;
                 case '(':
                     state = 'comment';
+                    insideQuotes = false;
                     break;
                 case ':':
                     state = 'group';
                     isGroup = true;
+                    insideQuotes = false;
+                    break;
+                case '"':
+                    // Track quote state for text tokens
+                    insideQuotes = !insideQuotes;
+                    state = 'text';
                     break;
                 default:
                     state = 'text';
+                    insideQuotes = false;
+                    break;
             }
         } else if (token.value) {
             if (state === 'address') {
@@ -46,7 +58,19 @@ function _handleAddress(tokens) {
                 // and so will we
                 token.value = token.value.replace(/^[^<]*<\s*/, '');
             }
-            data[state].push(token.value);
+
+            if (prevToken && prevToken.noBreak && data[state].length) {
+                // join values
+                data[state][data[state].length - 1] += token.value;
+                if (state === 'text' && insideQuotes) {
+                    data.textWasQuoted[data.textWasQuoted.length - 1] = true;
+                }
+            } else {
+                data[state].push(token.value);
+                if (state === 'text') {
+                    data.textWasQuoted.push(insideQuotes);
+                }
+            }
         }
     }
 
@@ -59,16 +83,36 @@ function _handleAddress(tokens) {
     if (isGroup) {
         // http://tools.ietf.org/html/rfc2822#appendix-A.1.3
         data.text = data.text.join(' ');
+
+        // Parse group members, but flatten any nested groups (RFC 5322 doesn't allow nesting)
+        let groupMembers = [];
+        if (data.group.length) {
+            let parsedGroup = addressParser(data.group.join(','));
+            // Flatten: if any member is itself a group, extract its members into the sequence
+            parsedGroup.forEach(member => {
+                if (member.group) {
+                    // Nested group detected - flatten it by adding its members directly
+                    groupMembers = groupMembers.concat(member.group);
+                } else {
+                    groupMembers.push(member);
+                }
+            });
+        }
+
         addresses.push({
             name: decodeWords(data.text || (address && address.name)),
-            group: data.group.length ? addressParser(data.group.join(',')) : []
+            group: groupMembers
         });
     } else {
         // If no address was found, try to detect one from regular text
         if (!data.address.length && data.text.length) {
             for (i = data.text.length - 1; i >= 0; i--) {
-                if (data.text[i].match(/^[^@\s]+@[^@\s]+$/)) {
+                // Security fix: Do not extract email addresses from quoted strings
+                // RFC 5321 allows @ inside quoted local-parts like "user@domain"@example.com
+                // Extracting emails from quoted text leads to misrouting vulnerabilities
+                if (!data.textWasQuoted[i] && data.text[i].match(/^[^@\s]+@[^@\s]+$/)) {
                     data.address = data.text.splice(i, 1);
+                    data.textWasQuoted.splice(i, 1);
                     break;
                 }
             }
@@ -85,10 +129,13 @@ function _handleAddress(tokens) {
             // still no address
             if (!data.address.length) {
                 for (i = data.text.length - 1; i >= 0; i--) {
-                    // fixed the regex to parse email address correctly when email address has more than one @
-                    data.text[i] = data.text[i].replace(/\s*\b[^@\s]+@[^\s]+\b\s*/, _regexHandler).trim();
-                    if (data.address.length) {
-                        break;
+                    // Security fix: Do not extract email addresses from quoted strings
+                    if (!data.textWasQuoted[i]) {
+                        // fixed the regex to parse email address correctly when email address has more than one @
+                        data.text[i] = data.text[i].replace(/\s*\b[^@\s]+@[^\s]+\b\s*/, _regexHandler).trim();
+                        if (data.address.length) {
+                            break;
+                        }
                     }
                 }
             }
@@ -180,11 +227,12 @@ class Tokenizer {
      * @return {Array} An array of operator|text tokens
      */
     tokenize() {
-        let chr,
-            list = [];
+        let list = [];
+
         for (let i = 0, len = this.str.length; i < len; i++) {
-            chr = this.str.charAt(i);
-            this.checkChar(chr);
+            let chr = this.str.charAt(i);
+            let nextChr = i < len - 1 ? this.str.charAt(i + 1) : null;
+            this.checkChar(chr, nextChr);
         }
 
         this.list.forEach(node => {
@@ -202,7 +250,7 @@ class Tokenizer {
      *
      * @param {String} chr Character from the address field
      */
-    checkChar(chr) {
+    checkChar(chr, nextChr) {
         if (this.escaped) {
             // ignore next condition blocks
         } else if (chr === this.operatorExpecting) {
@@ -210,10 +258,16 @@ class Tokenizer {
                 type: 'operator',
                 value: chr
             };
+
+            if (nextChr && ![' ', '\t', '\r', '\n', ',', ';'].includes(nextChr)) {
+                this.node.noBreak = true;
+            }
+
             this.list.push(this.node);
             this.node = null;
             this.operatorExpecting = '';
             this.escaped = false;
+
             return;
         } else if (!this.operatorExpecting && chr in this.operators) {
             this.node = {

package/src/mime-node.js

@@ -4,20 +4,31 @@ import Base64Decoder from './base64-decoder.js';
 import QPDecoder from './qp-decoder.js';
 
 export default class MimeNode {
-    constructor(opts) {
-        opts = opts || {};
+    constructor(options) {
+        this.options = options || {};
 
-        this.postalMime = opts.postalMime;
+        this.postalMime = this.options.postalMime;
 
-        this.root = !!opts.parentNode;
+        this.root = !!this.options.parentNode;
         this.childNodes = [];
-        if (opts.parentNode) {
-            opts.parentNode.childNodes.push(this);
+
+        if (this.options.parentNode) {
+            this.parentNode = this.options.parentNode;
+
+            this.depth = this.parentNode.depth + 1;
+            if (this.depth > this.options.maxNestingDepth) {
+                throw new Error(`Maximum MIME nesting depth of ${this.options.maxNestingDepth} levels exceeded`);
+            }
+
+            this.options.parentNode.childNodes.push(this);
+        } else {
+            this.depth = 0;
         }
 
         this.state = 'header';
 
         this.headerLines = [];
+        this.headerSize = 0;
 
         this.contentType = {
             value: 'text/plain',
@@ -262,6 +273,14 @@ export default class MimeNode {
                     this.state = 'body';
                     return this.processHeaders();
                 }
+
+                this.headerSize += line.length;
+
+                if (this.headerSize > this.options.maxHeadersSize) {
+                    let error = new Error(`Maximum header size of ${this.options.maxHeadersSize} bytes exceeded`);
+                    throw error;
+                }
+
                 this.headerLines.push(getDecoder().decode(line));
                 break;
             case 'body': {

package/src/postal-mime.js

@@ -6,6 +6,9 @@ import { base64ArrayBuffer } from './base64-encoder.js';
 
 export { addressParser, decodeWords };
 
+const MAX_NESTING_DEPTH = 256;
+const MAX_HEADERS_SIZE = 2 * 1024 * 1024;
+
 export default class PostalMime {
     static parse(buf, options) {
         const parser = new PostalMime(options);
@@ -14,9 +17,14 @@ export default class PostalMime {
 
     constructor(options) {
         this.options = options || {};
+        this.mimeOptions = {
+            maxNestingDepth: this.options.maxNestingDepth || MAX_NESTING_DEPTH,
+            maxHeadersSize: this.options.maxHeadersSize || MAX_HEADERS_SIZE
+        };
 
         this.root = this.currentNode = new MimeNode({
-            postalMime: this
+            postalMime: this,
+            ...this.mimeOptions
         });
         this.boundaries = [];
 
@@ -78,7 +86,8 @@ export default class PostalMime {
 
                     this.currentNode = new MimeNode({
                         postalMime: this,
-                        parentNode: boundary.node
+                        parentNode: boundary.node,
+                        ...this.mimeOptions
                     });
                 }