postal-mime 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.7.0](https://github.com/postalsys/postal-mime/compare/v2.6.1...v2.7.0) (2025-12-22)
+
+
+### Features
+
+* add headerLines property exposing raw header lines ([c79a02a](https://github.com/postalsys/postal-mime/commit/c79a02ab05d9cac44e05e95a433752ff292aa5eb))
+
+## [2.6.1](https://github.com/postalsys/postal-mime/compare/v2.6.0...v2.6.1) (2025-11-26)
+
+
+### Bug Fixes
+
+* prevent DoS from deeply nested address groups ([f509eaf](https://github.com/postalsys/postal-mime/commit/f509eafec31bf448482133041c086f7aefa2b3fa))
+* update TypeScript typings to match source code ([df5640a](https://github.com/postalsys/postal-mime/commit/df5640a3166b0a1fe3ca563e1364301bb4e6a025))
+
 ## [2.6.0](https://github.com/postalsys/postal-mime/compare/v2.5.0...v2.6.0) (2025-10-24)
 
 

package/README.md

@@ -39,7 +39,7 @@ The source code is available on [GitHub](https://github.com/postalsys/postal-mim
 
 ## Demo
 
-Try out a live demo using the [example page](https://kreata.ee/postal-mime/example/).
+Try out a live demo using the [example page](https://postal-mime.postalsys.com/demo).
 
 ## Installation
 

package/dist/address-parser.cjs

@@ -22,7 +22,7 @@ __export(address_parser_exports, {
 });
 module.exports = __toCommonJS(address_parser_exports);
 var import_decode_strings = require("./decode-strings.cjs");
-function _handleAddress(tokens) {
+function _handleAddress(tokens, depth) {
   let isGroup = false;
   let state = "text";
   let address;
@@ -90,7 +90,7 @@ function _handleAddress(tokens) {
     data.text = data.text.join(" ");
     let groupMembers = [];
     if (data.group.length) {
-      let parsedGroup = addressParser(data.group.join(","));
+      let parsedGroup = addressParser(data.group.join(","), { _depth: depth + 1 });
       parsedGroup.forEach((member) => {
         if (member.group) {
           groupMembers = groupMembers.concat(member.group);
@@ -258,8 +258,13 @@ class Tokenizer {
     this.escaped = false;
   }
 }
+const MAX_NESTED_GROUP_DEPTH = 50;
 function addressParser(str, options) {
   options = options || {};
+  let depth = options._depth || 0;
+  if (depth > MAX_NESTED_GROUP_DEPTH) {
+    return [];
+  }
   let tokenizer = new Tokenizer(str);
   let tokens = tokenizer.tokenize();
   let addresses = [];
@@ -279,7 +284,7 @@ function addressParser(str, options) {
     addresses.push(address);
   }
   addresses.forEach((address2) => {
-    address2 = _handleAddress(address2);
+    address2 = _handleAddress(address2, depth);
     if (address2.length) {
       parsedAddresses = parsedAddresses.concat(address2);
     }

package/dist/mime-node.cjs

@@ -193,31 +193,40 @@ class MimeNode {
       if (i && /^\s/.test(line)) {
         this.headerLines[i - 1] += "\n" + line;
         this.headerLines.splice(i, 1);
-      } else {
-        line = line.replace(/\s+/g, " ");
-        let sep = line.indexOf(":");
-        let key = sep < 0 ? line.trim() : line.substr(0, sep).trim();
-        let value = sep < 0 ? "" : line.substr(sep + 1).trim();
-        this.headers.push({ key: key.toLowerCase(), originalKey: key, value });
-        switch (key.toLowerCase()) {
-          case "content-type":
-            if (this.contentType.default) {
-              this.contentType = { value, parsed: {} };
-            }
-            break;
-          case "content-transfer-encoding":
-            this.contentTransferEncoding = { value, parsed: {} };
-            break;
-          case "content-disposition":
-            this.contentDisposition = { value, parsed: {} };
-            break;
-          case "content-id":
-            this.contentId = value;
-            break;
-          case "content-description":
-            this.contentDescription = value;
-            break;
-        }
+      }
+    }
+    this.rawHeaderLines = [];
+    for (let i = this.headerLines.length - 1; i >= 0; i--) {
+      let rawLine = this.headerLines[i];
+      let sep = rawLine.indexOf(":");
+      let rawKey = sep < 0 ? rawLine.trim() : rawLine.substr(0, sep).trim();
+      this.rawHeaderLines.push({
+        key: rawKey.toLowerCase(),
+        line: rawLine
+      });
+      let normalizedLine = rawLine.replace(/\s+/g, " ");
+      sep = normalizedLine.indexOf(":");
+      let key = sep < 0 ? normalizedLine.trim() : normalizedLine.substr(0, sep).trim();
+      let value = sep < 0 ? "" : normalizedLine.substr(sep + 1).trim();
+      this.headers.push({ key: key.toLowerCase(), originalKey: key, value });
+      switch (key.toLowerCase()) {
+        case "content-type":
+          if (this.contentType.default) {
+            this.contentType = { value, parsed: {} };
+          }
+          break;
+        case "content-transfer-encoding":
+          this.contentTransferEncoding = { value, parsed: {} };
+          break;
+        case "content-disposition":
+          this.contentDisposition = { value, parsed: {} };
+          break;
+        case "content-id":
+          this.contentId = value;
+          break;
+        case "content-description":
+          this.contentDescription = value;
+          break;
       }
     }
     this.contentType.parsed = this.parseStructuredHeader(this.contentType.value);

package/dist/postal-mime.cjs

@@ -426,6 +426,7 @@ class PostalMime {
       message.text = this.textContent.plain;
     }
     message.attachments = this.attachments;
+    message.headerLines = (this.root.rawHeaderLines || []).slice().reverse();
     switch (this.attachmentEncoding) {
       case "arraybuffer":
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "postal-mime",
-    "version": "2.6.0",
+    "version": "2.7.0",
     "description": "Email parser for browser environments",
     "main": "./dist/postal-mime.cjs",
     "module": "./src/postal-mime.js",
@@ -34,17 +34,18 @@
     "bugs": {
         "url": "https://github.com/postalsys/postal-mime/issues"
     },
+    "homepage": "https://postal-mime.postalsys.com",
     "author": "Andris Reinman",
     "license": "MIT-0",
     "devDependencies": {
-        "@types/node": "24.0.4",
+        "@types/node": "24.10.1",
         "cross-blob": "3.0.2",
-        "cross-env": "7.0.3",
-        "esbuild": "^0.25.11",
+        "cross-env": "10.1.0",
+        "esbuild": "0.27.0",
         "eslint": "8.57.0",
         "eslint-cli": "1.1.1",
         "iframe-resizer": "4.3.6",
-        "prettier": "^3.6.2",
-        "typescript": "^5.9.3"
+        "prettier": "3.6.2",
+        "typescript": "5.9.3"
     }
 }

package/postal-mime.d.ts

@@ -2,9 +2,17 @@ export type RawEmail = string | ArrayBuffer | Uint8Array | Blob | Buffer | Reada
 
 export type Header = {
     key: string;
+    originalKey: string;
     value: string;
 };
 
+export type HeaderLine = {
+    /** Lowercase header name */
+    key: string;
+    /** Complete raw header line including key and value (with folded lines merged) */
+    line: string;
+};
+
 export type Mailbox = {
     name: string;
     address: string;
@@ -27,12 +35,13 @@ export type Attachment = {
     description?: string;
     contentId?: string;
     method?: string;
-    content: ArrayBuffer | string;
+    content: ArrayBuffer | Uint8Array | string;
     encoding?: "base64" | "utf8";
 };
 
 export type Email = {
     headers: Header[];
+    headerLines: HeaderLine[];
     from?: Address;
     sender?: Address;
     replyTo?: Address[];

package/src/address-parser.js

@@ -4,9 +4,10 @@ import { decodeWords } from './decode-strings.js';
  * Converts tokens for a single address into an address object
  *
  * @param {Array} tokens Tokens object
+ * @param {Number} depth Current recursion depth for nested group protection
  * @return {Object} Address object
  */
-function _handleAddress(tokens) {
+function _handleAddress(tokens, depth) {
     let isGroup = false;
     let state = 'text';
     let address;
@@ -87,7 +88,7 @@ function _handleAddress(tokens) {
         // 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(','));
+            let parsedGroup = addressParser(data.group.join(','), { _depth: depth + 1 });
             // Flatten: if any member is itself a group, extract its members into the sequence
             parsedGroup.forEach(member => {
                 if (member.group) {
@@ -307,6 +308,13 @@ class Tokenizer {
     }
 }
 
+/**
+ * Maximum recursion depth for parsing nested groups.
+ * RFC 5322 doesn't allow nested groups, so this is a safeguard against
+ * malicious input that could cause stack overflow.
+ */
+const MAX_NESTED_GROUP_DEPTH = 50;
+
 /**
  * Parses structured e-mail addresses from an address field
  *
@@ -319,10 +327,18 @@ class Tokenizer {
  *     [{name: 'Name', address: 'address@domain'}]
  *
  * @param {String} str Address field
+ * @param {Object} options Optional options object
+ * @param {Number} options._depth Internal recursion depth counter (do not set manually)
  * @return {Array} An array of address objects
  */
 function addressParser(str, options) {
     options = options || {};
+    let depth = options._depth || 0;
+
+    // Prevent stack overflow from deeply nested groups (DoS protection)
+    if (depth > MAX_NESTED_GROUP_DEPTH) {
+        return [];
+    }
 
     let tokenizer = new Tokenizer(str);
     let tokens = tokenizer.tokenize();
@@ -347,7 +363,7 @@ function addressParser(str, options) {
     }
 
     addresses.forEach(address => {
-        address = _handleAddress(address);
+        address = _handleAddress(address, depth);
         if (address.length) {
             parsedAddresses = parsedAddresses.concat(address);
         }

package/src/mime-node.js

@@ -208,38 +208,59 @@ export default class MimeNode {
     }
 
     processHeaders() {
+        // First pass: merge folded headers (backward iteration)
         for (let i = this.headerLines.length - 1; i >= 0; i--) {
             let line = this.headerLines[i];
             if (i && /^\s/.test(line)) {
                 this.headerLines[i - 1] += '\n' + line;
                 this.headerLines.splice(i, 1);
-            } else {
-                // remove folding and extra WS
-                line = line.replace(/\s+/g, ' ');
-                let sep = line.indexOf(':');
-                let key = sep < 0 ? line.trim() : line.substr(0, sep).trim();
-                let value = sep < 0 ? '' : line.substr(sep + 1).trim();
-                this.headers.push({ key: key.toLowerCase(), originalKey: key, value });
-
-                switch (key.toLowerCase()) {
-                    case 'content-type':
-                        if (this.contentType.default) {
-                            this.contentType = { value, parsed: {} };
-                        }
-                        break;
-                    case 'content-transfer-encoding':
-                        this.contentTransferEncoding = { value, parsed: {} };
-                        break;
-                    case 'content-disposition':
-                        this.contentDisposition = { value, parsed: {} };
-                        break;
-                    case 'content-id':
-                        this.contentId = value;
-                        break;
-                    case 'content-description':
-                        this.contentDescription = value;
-                        break;
-                }
+            }
+        }
+
+        // Initialize rawHeaderLines to store unmodified lines
+        this.rawHeaderLines = [];
+
+        // Second pass: process headers (MUST be backward to maintain this.headers order)
+        // The existing code iterates backward and postal-mime.js calls .reverse()
+        // We must preserve this behavior to avoid breaking changes
+        for (let i = this.headerLines.length - 1; i >= 0; i--) {
+            let rawLine = this.headerLines[i];
+
+            // Extract key from raw line for rawHeaderLines
+            let sep = rawLine.indexOf(':');
+            let rawKey = sep < 0 ? rawLine.trim() : rawLine.substr(0, sep).trim();
+
+            // Store raw line with lowercase key
+            this.rawHeaderLines.push({
+                key: rawKey.toLowerCase(),
+                line: rawLine
+            });
+
+            // Normalize for this.headers (existing behavior - order preserved)
+            let normalizedLine = rawLine.replace(/\s+/g, ' ');
+            sep = normalizedLine.indexOf(':');
+            let key = sep < 0 ? normalizedLine.trim() : normalizedLine.substr(0, sep).trim();
+            let value = sep < 0 ? '' : normalizedLine.substr(sep + 1).trim();
+            this.headers.push({ key: key.toLowerCase(), originalKey: key, value });
+
+            switch (key.toLowerCase()) {
+                case 'content-type':
+                    if (this.contentType.default) {
+                        this.contentType = { value, parsed: {} };
+                    }
+                    break;
+                case 'content-transfer-encoding':
+                    this.contentTransferEncoding = { value, parsed: {} };
+                    break;
+                case 'content-disposition':
+                    this.contentDisposition = { value, parsed: {} };
+                    break;
+                case 'content-id':
+                    this.contentId = value;
+                    break;
+                case 'content-description':
+                    this.contentDescription = value;
+                    break;
             }
         }
 

package/src/postal-mime.js

@@ -517,6 +517,9 @@ export default class PostalMime {
 
         message.attachments = this.attachments;
 
+        // Expose raw header lines (reversed to match headers array order)
+        message.headerLines = (this.root.rawHeaderLines || []).slice().reverse();
+
         switch (this.attachmentEncoding) {
             case 'arraybuffer':
                 break;