postal-mime 2.4.4 → 2.4.6

package/.prettierignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+.git
+*.min.js
+coverage
+.DS_Store
+yarn.lock
+package-lock.json
+CLAUDE.md

package/.prettierrc.json

@@ -0,0 +1,10 @@
+{
+    "semi": true,
+    "trailingComma": "none",
+    "singleQuote": true,
+    "printWidth": 120,
+    "tabWidth": 4,
+    "useTabs": false,
+    "bracketSpacing": true,
+    "arrowParens": "avoid"
+}

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Bug Fixes
+
+* handle broken quoted-printable sequences and add prettier formatter ([ec3bc64](https://github.com/postalsys/postal-mime/commit/ec3bc647f6e262a7ac3a51e30bbe3b07b6e7db7a))
+
 ## [2.4.4](https://github.com/postalsys/postal-mime/compare/v2.4.3...v2.4.4) (2025-06-26)
 
 

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.4",
+    "version": "2.4.6",
     "description": "Email parser for browser environments",
     "main": "./src/postal-mime.js",
     "exports": {
@@ -12,7 +12,9 @@
     "types": "postal-mime.d.ts",
     "scripts": {
         "test": "eslint && node --test",
-        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
+        "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"
     },
     "keywords": [
         "mime",
@@ -33,6 +35,7 @@
         "cross-env": "7.0.3",
         "eslint": "8.57.0",
         "eslint-cli": "1.1.1",
-        "iframe-resizer": "4.3.6"
+        "iframe-resizer": "4.3.6",
+        "prettier": "^3.6.2"
     }
 }

package/postal-mime.d.ts

@@ -1,6 +1,9 @@
 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 = {
     name: string;
@@ -22,7 +25,7 @@ export type Attachment = {
 
 export type Email = {
     headers: Header[];
-    from: Address;
+    from?: Address;
     sender?: Address;
     replyTo?: Address[];
     deliveredTo?: string;
@@ -31,7 +34,7 @@ export type Email = {
     cc?: Address[];
     bcc?: Address[];
     subject?: string;
-    messageId: string;
+    messageId?: string;
     inReplyTo?: string;
     references?: string;
     date?: string;
@@ -56,7 +59,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/decode-strings.js

@@ -81,7 +81,11 @@ export async function blobToArrayBuffer(blob) {
 }
 
 export function getHex(c) {
-    if ((c >= 0x30 /* 0 */ && c <= 0x39) /* 9 */ || (c >= 0x61 /* a */ && c <= 0x66) /* f */ || (c >= 0x41 /* A */ && c <= 0x46) /* F */) {
+    if (
+        (c >= 0x30 /* 0 */ && c <= 0x39) /* 9 */ ||
+        (c >= 0x61 /* a */ && c <= 0x66) /* f */ ||
+        (c >= 0x41 /* A */ && c <= 0x46) /* F */
+    ) {
         return String.fromCharCode(c);
     }
     return false;
@@ -152,36 +156,44 @@ export function decodeWords(str) {
         let result = (str || '')
             .toString()
             // find base64 words that can be joined
-            .replace(/(=\?([^?]+)\?[Bb]\?([^?]*)\?=)\s*(?==\?([^?]+)\?[Bb]\?[^?]*\?=)/g, (match, left, chLeft, encodedLeftStr, chRight) => {
-                if (!joinString) {
+            .replace(
+                /(=\?([^?]+)\?[Bb]\?([^?]*)\?=)\s*(?==\?([^?]+)\?[Bb]\?[^?]*\?=)/g,
+                (match, left, chLeft, encodedLeftStr, chRight) => {
+                    if (!joinString) {
+                        return match;
+                    }
+                    // only mark b64 chunks to be joined if charsets match and left side does not end with =
+                    if (chLeft === chRight && encodedLeftStr.length % 4 === 0 && !/=$/.test(encodedLeftStr)) {
+                        // set a joiner marker
+                        return left + '__\x00JOIN\x00__';
+                    }
+
                     return match;
                 }
-                // only mark b64 chunks to be joined if charsets match and left side does not end with =
-                if (chLeft === chRight && encodedLeftStr.length % 4 === 0 && !/=$/.test(encodedLeftStr)) {
-                    // set a joiner marker
-                    return left + '__\x00JOIN\x00__';
-                }
-
-                return match;
-            })
+            )
             // find QP words that can be joined
-            .replace(/(=\?([^?]+)\?[Qq]\?[^?]*\?=)\s*(?==\?([^?]+)\?[Qq]\?[^?]*\?=)/g, (match, left, chLeft, chRight) => {
-                if (!joinString) {
+            .replace(
+                /(=\?([^?]+)\?[Qq]\?[^?]*\?=)\s*(?==\?([^?]+)\?[Qq]\?[^?]*\?=)/g,
+                (match, left, chLeft, chRight) => {
+                    if (!joinString) {
+                        return match;
+                    }
+                    // only mark QP chunks to be joined if charsets match
+                    if (chLeft === chRight) {
+                        // set a joiner marker
+                        return left + '__\x00JOIN\x00__';
+                    }
                     return match;
                 }
-                // only mark QP chunks to be joined if charsets match
-                if (chLeft === chRight) {
-                    // set a joiner marker
-                    return left + '__\x00JOIN\x00__';
-                }
-                return match;
-            })
+            )
             // join base64 encoded words
             .replace(/(\?=)?__\x00JOIN\x00__(=\?([^?]+)\?[QqBb]\?)?/g, '')
             // remove spaces between mime encoded words
             .replace(/(=\?[^?]+\?[QqBb]\?[^?]*\?=)\s+(?==\?[^?]+\?[QqBb]\?[^?]*\?=)/g, '$1')
             // decode words
-            .replace(/=\?([\w_\-*]+)\?([QqBb])\?([^?]*)\?=/g, (m, charset, encoding, text) => decodeWord(charset, encoding, text));
+            .replace(/=\?([\w_\-*]+)\?([QqBb])\?([^?]*)\?=/g, (m, charset, encoding, text) =>
+                decodeWord(charset, encoding, text)
+            );
 
         if (joinString && result.indexOf('\ufffd') >= 0) {
             // text contains \ufffd (EF BF BD), so unicode conversion failed, retry without joining strings

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
                     });
                 }
 
@@ -190,7 +199,8 @@ export default class PostalMime {
 
                 // is it an attachment
                 else if (node.content) {
-                    const filename = node.contentDisposition.parsed.params.filename || node.contentType.parsed.params.name || null;
+                    const filename =
+                        node.contentDisposition.parsed.params.filename || node.contentType.parsed.params.name || null;
                     const attachment = {
                         filename: filename ? decodeWords(filename) : null,
                         mimeType: node.contentType.parsed.value,
@@ -214,7 +224,10 @@ export default class PostalMime {
                         case 'text/calendar':
                         case 'application/ics': {
                             if (node.contentType.parsed.params.method) {
-                                attachment.method = node.contentType.parsed.params.method.toString().toUpperCase().trim();
+                                attachment.method = node.contentType.parsed.params.method
+                                    .toString()
+                                    .toUpperCase()
+                                    .trim();
                             }
 
                             // Enforce into unicode
@@ -341,7 +354,8 @@ export default class PostalMime {
         if (node.contentType.parsed.value !== 'message/rfc822') {
             return false;
         }
-        let disposition = node.contentDisposition.parsed.value || (this.options.rfc822Attachments ? 'attachment' : 'inline');
+        let disposition =
+            node.contentDisposition.parsed.value || (this.options.rfc822Attachments ? 'attachment' : 'inline');
         return disposition === 'inline';
     }
 

package/src/qp-decoder.js

@@ -1,5 +1,11 @@
 import { blobToArrayBuffer } from './decode-strings.js';
 
+// Regex patterns compiled once for performance
+const VALID_QP_REGEX = /^=[a-f0-9]{2}$/i;
+const QP_SPLIT_REGEX = /(?==[a-f0-9]{2})/i;
+const SOFT_LINE_BREAK_REGEX = /=\r?\n/g;
+const PARTIAL_QP_ENDING_REGEX = /=[a-fA-F0-9]?$/;
+
 export default class QPDecoder {
     constructor(opts) {
         opts = opts || {};
@@ -24,9 +30,9 @@ export default class QPDecoder {
 
     decodeChunks(str) {
         // unwrap newlines
-        str = str.replace(/=\r?\n/g, '');
+        str = str.replace(SOFT_LINE_BREAK_REGEX, '');
 
-        let list = str.split(/(?==)/);
+        let list = str.split(QP_SPLIT_REGEX);
         let encodedBytes = [];
         for (let part of list) {
             if (part.charAt(0) !== '=') {
@@ -39,17 +45,38 @@ export default class QPDecoder {
             }
 
             if (part.length === 3) {
-                encodedBytes.push(part.substr(1));
+                // Validate that this is actually a valid QP sequence
+                if (VALID_QP_REGEX.test(part)) {
+                    encodedBytes.push(part.substr(1));
+                } else {
+                    // Not a valid QP sequence, treat as literal text
+                    if (encodedBytes.length) {
+                        this.chunks.push(this.decodeQPBytes(encodedBytes));
+                        encodedBytes = [];
+                    }
+                    this.chunks.push(part);
+                }
                 continue;
             }
 
             if (part.length > 3) {
-                encodedBytes.push(part.substr(1, 2));
-                this.chunks.push(this.decodeQPBytes(encodedBytes));
-                encodedBytes = [];
+                // First 3 chars should be a valid QP sequence
+                const firstThree = part.substr(0, 3);
+                if (VALID_QP_REGEX.test(firstThree)) {
+                    encodedBytes.push(part.substr(1, 2));
+                    this.chunks.push(this.decodeQPBytes(encodedBytes));
+                    encodedBytes = [];
 
-                part = part.substr(3);
-                this.chunks.push(part);
+                    part = part.substr(3);
+                    this.chunks.push(part);
+                } else {
+                    // Not a valid QP sequence, treat entire part as literal
+                    if (encodedBytes.length) {
+                        this.chunks.push(this.decodeQPBytes(encodedBytes));
+                        encodedBytes = [];
+                    }
+                    this.chunks.push(part);
+                }
             }
         }
         if (encodedBytes.length) {
@@ -71,7 +98,7 @@ export default class QPDecoder {
 
         this.remainder = '';
 
-        let partialEnding = str.match(/=[a-fA-F0-9]?$/);
+        let partialEnding = str.match(PARTIAL_QP_ENDING_REGEX);
         if (partialEnding) {
             if (partialEnding.index === 0) {
                 this.remainder = str;

package/src/text-format.js

@@ -177,7 +177,10 @@ function foldLines(str, lineLength, afterSpace) {
             result += line;
             pos += line.length;
             continue;
-        } else if ((match = line.match(/(\s+)[^\s]*$/)) && match[0].length - (afterSpace ? (match[1] || '').length : 0) < line.length) {
+        } else if (
+            (match = line.match(/(\s+)[^\s]*$/)) &&
+            match[0].length - (afterSpace ? (match[1] || '').length : 0) < line.length
+        ) {
             line = line.substr(0, line.length - (match[0].length - (afterSpace ? (match[1] || '').length : 0)));
         } else if ((match = str.substr(pos + line.length).match(/^[^\s]+(\s*)/))) {
             line = line + match[0].substr(0, match[0].length - (!afterSpace ? (match[1] || '').length : 0));
@@ -215,7 +218,10 @@ export function formatTextHeader(message) {
             hour12: false
         };
 
-        let dateStr = typeof Intl === 'undefined' ? message.date : new Intl.DateTimeFormat('default', dateOptions).format(new Date(message.date));
+        let dateStr =
+            typeof Intl === 'undefined'
+                ? message.date
+                : new Intl.DateTimeFormat('default', dateOptions).format(new Date(message.date));
 
         rows.push({ key: 'Date', val: dateStr });
     }
@@ -283,7 +289,9 @@ export function formatHtmlHeader(message) {
     let rows = [];
 
     if (message.from) {
-        rows.push(`<div class="postal-email-header-key">From</div><div class="postal-email-header-value">${formatHtmlAddress(message.from)}</div>`);
+        rows.push(
+            `<div class="postal-email-header-key">From</div><div class="postal-email-header-value">${formatHtmlAddress(message.from)}</div>`
+        );
     }
 
     if (message.subject) {
@@ -305,7 +313,10 @@ export function formatHtmlHeader(message) {
             hour12: false
         };
 
-        let dateStr = typeof Intl === 'undefined' ? message.date : new Intl.DateTimeFormat('default', dateOptions).format(new Date(message.date));
+        let dateStr =
+            typeof Intl === 'undefined'
+                ? message.date
+                : new Intl.DateTimeFormat('default', dateOptions).format(new Date(message.date));
 
         rows.push(
             `<div class="postal-email-header-key">Date</div><div class="postal-email-header-value postal-email-header-date" data-date="${escapeHtml(
@@ -315,15 +326,21 @@ export function formatHtmlHeader(message) {
     }
 
     if (message.to && message.to.length) {
-        rows.push(`<div class="postal-email-header-key">To</div><div class="postal-email-header-value">${formatHtmlAddresses(message.to)}</div>`);
+        rows.push(
+            `<div class="postal-email-header-key">To</div><div class="postal-email-header-value">${formatHtmlAddresses(message.to)}</div>`
+        );
     }
 
     if (message.cc && message.cc.length) {
-        rows.push(`<div class="postal-email-header-key">Cc</div><div class="postal-email-header-value">${formatHtmlAddresses(message.cc)}</div>`);
+        rows.push(
+            `<div class="postal-email-header-key">Cc</div><div class="postal-email-header-value">${formatHtmlAddresses(message.cc)}</div>`
+        );
     }
 
     if (message.bcc && message.bcc.length) {
-        rows.push(`<div class="postal-email-header-key">Bcc</div><div class="postal-email-header-value">${formatHtmlAddresses(message.bcc)}</div>`);
+        rows.push(
+            `<div class="postal-email-header-key">Bcc</div><div class="postal-email-header-value">${formatHtmlAddresses(message.bcc)}</div>`
+        );
     }
 
     let template = `<div class="postal-email-header">${rows.length ? '<div class="postal-email-header-row">' : ''}${rows.join(