postal-mime 2.4.6 → 2.5.0

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.5.0](https://github.com/postalsys/postal-mime/compare/v2.4.7...v2.5.0) (2025-10-07)
+
+
+### Features
+
+* add comprehensive type validation and TypeScript support ([81a6467](https://github.com/postalsys/postal-mime/commit/81a6467b6c5379c502bac9ee7023e2c2dee976cb))
+
+## [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)
 
 

package/README.md

@@ -2,9 +2,18 @@
 
 **postal-mime** is an email parsing library that runs in browser environments (including Web Workers) and serverless functions (like Cloudflare Email Workers). It takes in a raw email message (RFC822 format) and outputs a structured object containing headers, recipients, attachments, and more.
 
-> **Tip**  
+> [!TIP]
 > PostalMime is developed by the makers of [EmailEngine](https://emailengine.app/?utm_source=github&utm_campaign=imapflow&utm_medium=readme-link)—a self-hosted email gateway that provides a REST API for IMAP and SMTP servers and sends webhooks whenever something changes in registered accounts.
 
+## Features
+
+-   **Browser & Node.js compatible** - Works in browsers, Web Workers, Node.js, and serverless environments
+-   **TypeScript support** - Fully typed with comprehensive type definitions
+-   **Zero dependencies** - No external dependencies
+-   **RFC compliant** - Follows RFC 2822/5322 email standards
+-   **Handles complex MIME structures** - Multipart messages, nested parts, attachments
+-   **Security limits** - Built-in protection against deeply nested messages and oversized headers
+
 ## Table of Contents
 
 -   [Source](#source)
@@ -14,6 +23,7 @@
     -   [Browser](#browser)
     -   [Node.js](#nodejs)
     -   [Cloudflare Email Workers](#cloudflare-email-workers)
+-   [TypeScript Support](#typescript-support)
 -   [API](#api)
     -   [PostalMime.parse()](#postalmimeparse)
     -   [Utility Functions](#utility-functions)
@@ -58,6 +68,23 @@ Content-Type: text/html; charset=utf-8
 console.log(email.subject); // "My awesome email 🤓"
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import PostalMime from './node_modules/postal-mime/src/postal-mime.js';
+import type { Email } from 'postal-mime';
+
+const email: Email = await PostalMime.parse(`Subject: My awesome email 🤓
+Content-Type: text/html; charset=utf-8
+
+<p>Hello world 😵‍💫</p>`);
+
+console.log(email.subject); // "My awesome email 🤓"
+```
+
+</details>
+
 ### Node.js
 
 In Node.js (including serverless functions), import it directly from `postal-mime`:
@@ -75,6 +102,29 @@ Content-Type: text/html; charset=utf-8
 console.log(util.inspect(email, false, 22, true));
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import PostalMime from 'postal-mime';
+import type { Email, PostalMimeOptions } from 'postal-mime';
+import util from 'node:util';
+
+const options: PostalMimeOptions = {
+    attachmentEncoding: 'base64'
+};
+
+const email: Email = await PostalMime.parse(`Subject: My awesome email 🤓
+Content-Type: text/html; charset=utf-8
+
+<p>Hello world 😵‍💫</p>`, options);
+
+// Use 'util.inspect' for pretty-printing
+console.log(util.inspect(email, false, 22, true));
+```
+
+</details>
+
 ### Cloudflare Email Workers
 
 Use the `message.raw` as the raw email data for parsing:
@@ -93,6 +143,77 @@ export default {
 };
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import PostalMime from 'postal-mime';
+import type { Email } from 'postal-mime';
+
+export default {
+    async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise<void> {
+        const email: Email = await PostalMime.parse(message.raw);
+
+        console.log('Subject:', email.subject);
+        console.log('HTML:', email.html);
+        console.log('Text:', email.text);
+    }
+};
+```
+
+</details>
+
+---
+
+## TypeScript Support
+
+PostalMime includes comprehensive TypeScript type definitions. All types are exported and can be imported from the main package:
+
+```typescript
+import PostalMime, { addressParser, decodeWords } from 'postal-mime';
+import type {
+    Email,
+    Address,
+    Mailbox,
+    Header,
+    Attachment,
+    PostalMimeOptions,
+    AddressParserOptions,
+    RawEmail
+} from 'postal-mime';
+```
+
+> [!NOTE]
+> PostalMime is written in JavaScript but provides comprehensive TypeScript type definitions. All types are validated through both compile-time type checking and runtime type validation tests to ensure accuracy.
+
+### Available Types
+
+-   **`Email`** - The main parsed email object returned by `PostalMime.parse()`
+-   **`Address`** - Union type representing either a `Mailbox` or an address group
+-   **`Mailbox`** - Individual email address with name and address fields
+-   **`Header`** - Email header with key and value
+-   **`Attachment`** - Email attachment with metadata and content
+-   **`PostalMimeOptions`** - Configuration options for parsing
+-   **`AddressParserOptions`** - Configuration options for address parsing
+-   **`RawEmail`** - Union type for all accepted email input formats
+
+### Type Narrowing
+
+TypeScript users can use type guards to narrow address types:
+
+```typescript
+import type { Address, Mailbox } from 'postal-mime';
+
+function isMailbox(addr: Address): addr is Mailbox {
+    return !('group' in addr) || addr.group === undefined;
+}
+
+// Usage
+if (email.from && isMailbox(email.from)) {
+    console.log(email.from.address); // TypeScript knows this is a Mailbox
+}
+```
+
 ---
 
 ## API
@@ -100,7 +221,7 @@ export default {
 ### PostalMime.parse()
 
 ```js
-PostalMime.parse(email, options) -> Promise<ParsedEmail>
+PostalMime.parse(email, options) -> Promise<Email>
 ```
 
 -   **email**: An RFC822 formatted email. This can be a `string`, `ArrayBuffer/Uint8Array`, `Blob` (browser only), `Buffer` (Node.js), or a [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
@@ -114,29 +235,86 @@ PostalMime.parse(email, options) -> Promise<ParsedEmail>
     -   **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:
+> [!IMPORTANT]
+> The `maxNestingDepth` and `maxHeadersSize` options provide built-in security against malicious emails with deeply nested MIME structures or oversized headers that could cause performance issues or memory exhaustion.
+
+**Returns**: A Promise that resolves to a structured `Email` object with the following properties:
 
--   **headers**: An array of header objects, each containing:
+-   **headers**: An array of `Header` objects, each containing:
     -   `key`: Lowercase header name (e.g., `"dkim-signature"`).
     -   `value`: Unprocessed header value as a string.
--   **from**, **sender**: Processed address objects:
+-   **from**, **sender**: Processed `Address` objects (can be a `Mailbox` or address group):
     -   `name`: Decoded display name, or an empty string if not set.
     -   `address`: Email address.
+    -   `group`: Array of `Mailbox` objects (only for address groups).
 -   **deliveredTo**, **returnPath**: Single email addresses as strings.
--   **to**, **cc**, **bcc**, **replyTo**: Arrays of processed address objects (same structure as `from`).
+-   **to**, **cc**, **bcc**, **replyTo**: Arrays of `Address` objects (same structure as `from`).
 -   **subject**: Subject line of the email.
 -   **messageId**, **inReplyTo**, **references**: Values from their corresponding headers.
--   **date**: The email’s sending time in ISO 8601 format (or the original string if parsing fails).
+-   **date**: The email's sending time in ISO 8601 format (or the original string if parsing fails).
 -   **html**: String containing the HTML content of the email.
 -   **text**: String containing the plain text content of the email.
--   **attachments**: Array of attachment objects:
-    -   `filename`
-    -   `mimeType`
-    -   `disposition` (e.g., `"attachment"`, `"inline"`, or `null`)
-    -   `related` (boolean, `true` if it’s an inline image)
-    -   `contentId`
-    -   `content` (array buffer or string, depending on `attachmentEncoding`)
-    -   `encoding` (e.g., `"base64"`)
+-   **attachments**: Array of `Attachment` objects:
+    -   `filename`: String or `null`
+    -   `mimeType`: String
+    -   `disposition`: `"attachment"`, `"inline"`, or `null`
+    -   `related`: Boolean (optional, `true` if it's an inline image)
+    -   `contentId`: String (optional)
+    -   `content`: `ArrayBuffer` or string, depending on `attachmentEncoding`
+    -   `encoding`: `"base64"` or `"utf8"` (optional)
+
+<details>
+<summary><strong>TypeScript Types</strong></summary>
+
+```typescript
+import type {
+    Email,
+    Address,
+    Mailbox,
+    Header,
+    Attachment,
+    PostalMimeOptions,
+    RawEmail
+} from 'postal-mime';
+
+// Main email parsing
+const email: Email = await PostalMime.parse(rawEmail);
+
+// With options
+const options: PostalMimeOptions = {
+    attachmentEncoding: 'base64',
+    maxNestingDepth: 100
+};
+const email: Email = await PostalMime.parse(rawEmail, options);
+
+// Working with addresses
+if (email.from) {
+    // Address can be either a Mailbox or a Group
+    if ('group' in email.from && email.from.group) {
+        // It's a group
+        email.from.group.forEach((member: Mailbox) => {
+            console.log(member.address);
+        });
+    } else {
+        // It's a mailbox
+        const mailbox = email.from as Mailbox;
+        console.log(mailbox.address);
+    }
+}
+
+// Working with attachments
+email.attachments.forEach((att: Attachment) => {
+    if (att.encoding === 'base64') {
+        // content is a string
+        const base64Content: string = att.content as string;
+    } else {
+        // content is ArrayBuffer (default)
+        const buffer: ArrayBuffer = att.content as ArrayBuffer;
+    }
+});
+```
+
+</details>
 
 ---
 
@@ -147,23 +325,42 @@ PostalMime.parse(email, options) -> Promise<ParsedEmail>
 ```js
 import { addressParser } from 'postal-mime';
 
-addressParser(addressStr, opts) -> Array
+addressParser(addressStr, opts) -> Address[]
 ```
 
 -   **addressStr**: A raw address header string.
 -   **opts**: Optional configuration:
     -   **flatten** (boolean, default: `false`): If `true`, ignores address groups and returns a flat array of addresses.
 
-**Returns**: An array of address objects, which can be nested if address groups are present.
+**Returns**: An array of `Address` objects, which can be nested if address groups are present.
 
 **Example**:
 
 ```js
+import { addressParser } from 'postal-mime';
+
 const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>';
 console.log(addressParser(addressStr));
 // [ { name: 'エポスカード', address: 'support@example.com' } ]
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import { addressParser } from 'postal-mime';
+import type { Address, AddressParserOptions } from 'postal-mime';
+
+const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>';
+const addresses: Address[] = addressParser(addressStr);
+
+// With options
+const options: AddressParserOptions = { flatten: true };
+const flatAddresses: Address[] = addressParser(addressStr, options);
+```
+
+</details>
+
 #### decodeWords()
 
 ```js
@@ -179,11 +376,26 @@ decodeWords(encodedStr) -> string
 **Example**:
 
 ```js
+import { decodeWords } from 'postal-mime';
+
 const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
 console.log(decodeWords(encodedStr));
 // Hello, エポスカード
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import { decodeWords } from 'postal-mime';
+
+const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
+const decoded: string = decodeWords(encodedStr);
+console.log(decoded); // Hello, エポスカード
+```
+
+</details>
+
 ---
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "postal-mime",
-    "version": "2.4.6",
+    "version": "2.5.0",
     "description": "Email parser for browser environments",
     "main": "./src/postal-mime.js",
     "exports": {
@@ -11,7 +11,9 @@
     "type": "module",
     "types": "postal-mime.d.ts",
     "scripts": {
-        "test": "eslint && node --test",
+        "test": "npm run lint && npm run type-check && node --test",
+        "lint": "eslint",
+        "type-check": "tsc --noEmit",
         "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"
@@ -36,6 +38,7 @@
         "eslint": "8.57.0",
         "eslint-cli": "1.1.1",
         "iframe-resizer": "4.3.6",
-        "prettier": "^3.6.2"
+        "prettier": "^3.6.2",
+        "typescript": "^5.9.3"
     }
 }

package/postal-mime.d.ts

@@ -5,12 +5,20 @@ export type Header = {
     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;
@@ -43,20 +51,20 @@ export type Email = {
     attachments: Attachment[];
 };
 
-declare type AddressParserOptions = {
+export type AddressParserOptions = {
     flatten?: boolean
 }
 
-declare function addressParser (
+export function addressParser (
     str: string,
     options?: AddressParserOptions
 ): Address[];
 
-declare function decodeWords (
+export function decodeWords (
     str: string
 ): string;
 
-declare type PostalMimeOptions = {
+export type PostalMimeOptions = {
     rfc822Attachments?: boolean,
     forceRfc822Attachments?: boolean,
     attachmentEncoding?: "base64" | "utf8" | "arraybuffer",
@@ -64,7 +72,7 @@ declare type PostalMimeOptions = {
     maxHeadersSize?: number
 }
 
-declare class PostalMime {
+export default class PostalMime {
     constructor(options?: PostalMimeOptions);
     static parse(
         email: RawEmail,
@@ -72,6 +80,3 @@ declare class PostalMime {
     ): Promise<Email>;
     parse(email: RawEmail): Promise<Email>;
 }
-
-export { addressParser, decodeWords };
-export default 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/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ES2022",
+        "lib": ["ES2022", "DOM"],
+        "moduleResolution": "bundler",
+        "strict": true,
+        "noEmit": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "forceConsistentCasingInFileNames": true,
+        "types": ["node"]
+    },
+    "include": ["test/type-check.test.ts"],
+    "exclude": ["node_modules"]
+}