@depup/zone-eu__mailsplit 5.4.16-depup.0

package/lib/headers.d.ts

@@ -0,0 +1,117 @@
+import type { DecodedHeader, HeaderLine, LibmimeOptions } from './types';
+
+/** Mutable parser and builder for RFC-style message header blocks. */
+declare class Headers {
+    /** Whether header lines have been modified after construction. */
+    changed: boolean;
+
+    /** Original unparsed header source, or `false` when constructed from parsed lines. */
+    headers: string | Buffer | false;
+
+    /** Whether `headers` has been parsed into `lines`. */
+    parsed: boolean;
+
+    /** Parsed header lines, or `false` until parsing occurs. */
+    lines: HeaderLine[] | false;
+
+    /** MBOX `From ` prefix line, or `false` when absent. */
+    mbox: string | false;
+
+    /** HTTP request prefix line, or `false` when absent. */
+    http: string | false;
+
+    /**
+     * Creates a mutable header collection.
+     *
+     * @param headers Raw header bytes/string, already parsed header lines, or `false` for an empty collection.
+     * @param config Optional libmime configuration.
+     */
+    constructor(headers?: string | Buffer | HeaderLine[] | false, config?: LibmimeOptions);
+
+    /**
+     * Checks whether at least one header with the requested key exists.
+     *
+     * @param key Header field name to find, case-insensitively.
+     * @returns `true` when the header exists.
+     */
+    hasHeader(key: string): boolean;
+
+    /**
+     * Gets all raw header lines for a key.
+     *
+     * @param key Header field name to find, case-insensitively.
+     * @returns Full decoded header lines, including field names.
+     */
+    get(key: string): string[];
+
+    /**
+     * Gets all decoded structured header values for a key.
+     *
+     * @param key Header field name to decode, case-insensitively.
+     * @returns Decoded header entries with key and value fields.
+     */
+    getDecoded(key: string): DecodedHeader[];
+
+    /**
+     * Gets the first decoded header value for a key.
+     *
+     * @param key Header field name to find, case-insensitively.
+     * @returns Trimmed decoded value, or an empty string when the header is absent.
+     */
+    getFirst(key: string): string;
+
+    /**
+     * Gets the mutable parsed header list.
+     *
+     * @returns Parsed header lines in message order.
+     */
+    getList(): HeaderLine[];
+
+    /**
+     * Adds a folded header line.
+     *
+     * @param key Header field name to add.
+     * @param value Header value; `undefined` leaves the collection unchanged.
+     * @param index Insertion index, where omitted or less than 1 inserts at the top.
+     * @returns Nothing.
+     */
+    add(key: string, value?: string | number | Buffer, index?: number): void;
+
+    /**
+     * Adds a preformatted header line.
+     *
+     * @param key Header field name used for normalized lookup.
+     * @param line Full header line to insert; falsy values leave the collection unchanged.
+     * @param index Insertion index, where omitted or less than 1 inserts at the top.
+     * @returns Nothing.
+     */
+    addFormatted(key: string, line?: string | Buffer | false, index?: number): void;
+
+    /**
+     * Removes all headers matching a key.
+     *
+     * @param key Header field name to remove, case-insensitively.
+     * @returns Nothing.
+     */
+    remove(key: string): void;
+
+    /**
+     * Replaces matching headers with a new folded header value.
+     *
+     * @param key Header field name to update.
+     * @param value Header value to write; `undefined` removes matching values without adding a replacement.
+     * @param relativeIndex Optional zero-based index among headers with the same key.
+     * @returns Nothing.
+     */
+    update(key: string, value?: string | number | Buffer, relativeIndex?: number): void;
+
+    /**
+     * Builds a raw header block.
+     *
+     * @param lineEnd Line ending to use when rebuilding changed headers; defaults to CRLF.
+     * @returns Header bytes ending with an empty header/body separator line.
+     */
+    build(lineEnd?: string | false): Buffer;
+}
+
+export = Headers;

package/lib/headers.js

@@ -0,0 +1,428 @@
+'use strict';
+
+const libmime = require('libmime');
+
+/** @typedef {import('..').HeaderLine} HeaderLine */
+/** @typedef {import('..').LibmimeOptions} LibmimeOptions */
+/** @typedef {import('..').DecodedHeader} DecodedHeader */
+
+const Libmime = /** @type {any} */ (libmime.Libmime);
+
+/**
+ * Parses and builds message headers. A Headers instance allows callers to
+ * inspect, delete, update, and add header lines.
+ */
+class Headers {
+    /**
+     * @param {string | Buffer | HeaderLine[] | false} [headers] Raw header source or already parsed lines.
+     * @param {LibmimeOptions} [config] Optional libmime configuration.
+     */
+    constructor(headers, config) {
+        config = config || {};
+
+        if (Array.isArray(headers)) {
+            // already using parsed headers
+            this.changed = true;
+            /** @type {string | Buffer | false} */
+            this.headers = false;
+            this.parsed = true;
+            /** @type {HeaderLine[] | false} */
+            this.lines = headers;
+        } else {
+            // using original string/buffer headers
+            this.changed = false;
+            /** @type {string | Buffer | false} */
+            this.headers = headers || false;
+            this.parsed = false;
+            /** @type {HeaderLine[] | false} */
+            this.lines = false;
+        }
+        /** @type {string | false} */
+        this.mbox = false;
+        /** @type {string | false} */
+        this.http = false;
+
+        this.libmime = new Libmime({ Iconv: config.Iconv });
+    }
+
+    /**
+     * @param {string} key
+     * @returns {boolean}
+     */
+    hasHeader(key) {
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        let lines = this._getLines();
+        key = this._normalizeHeader(key);
+        return typeof lines.find(line => line.key === key) === 'object';
+    }
+
+    /**
+     * @param {string} key
+     * @returns {string[]}
+     */
+    get(key) {
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        let headerLines = this._getLines();
+        key = this._normalizeHeader(key);
+        let lines = headerLines.filter(line => line.key === key).map(line => this._decodeHeaderValue(line.line));
+
+        return lines;
+    }
+
+    /**
+     * @param {string} key
+     * @returns {DecodedHeader[]}
+     */
+    getDecoded(key) {
+        return this.get(key)
+            .map(line => this.libmime.decodeHeader(line))
+            .filter(line => line && line.value);
+    }
+
+    /**
+     * @param {string} key
+     * @returns {string}
+     */
+    getFirst(key) {
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        let lines = this._getLines();
+        key = this._normalizeHeader(key);
+        let header = lines.find(line => line.key === key);
+        if (!header) {
+            return '';
+        }
+        return ((this.libmime.decodeHeader(this._decodeHeaderValue(header.line)) || {}).value || '').toString().trim();
+    }
+
+    /**
+     * @returns {HeaderLine[]}
+     */
+    getList() {
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        return this._getLines();
+    }
+
+    /**
+     * @param {string} key
+     * @param {string | number | Buffer} [value]
+     * @param {number} [index]
+     * @returns {void}
+     */
+    add(key, value, index) {
+        if (typeof value === 'undefined') {
+            return;
+        }
+
+        if (typeof value === 'number') {
+            value = value.toString();
+        }
+
+        if (typeof value === 'string') {
+            value = Buffer.from(value);
+        }
+
+        value = value.toString('binary');
+        // a header value may not contain line breaks of its own, folding is added by foldLines
+        this.addFormatted(key, this.libmime.foldLines(key + ': ' + value.replace(/[\r\n]/g, ''), 76, false), index);
+    }
+
+    /**
+     * @param {string} key
+     * @param {string | Buffer | false} [line]
+     * @param {number} [index]
+     * @returns {void}
+     */
+    addFormatted(key, line, index) {
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        let lines = this._getLines();
+        index = index || 0;
+        this.changed = true;
+
+        if (!line) {
+            return;
+        }
+
+        if (typeof line !== 'string') {
+            line = line.toString('binary');
+        }
+
+        // every header insertion runs through here, so this is where a value or a key
+        // built from untrusted input is stopped from injecting an extra header line
+        line = this._normalizeInsertedLine(line);
+        if (!line) {
+            return;
+        }
+
+        let header = {
+            key: this._normalizeHeader(key),
+            line
+        };
+
+        if (index < 1) {
+            lines.unshift(header);
+        } else if (index >= lines.length) {
+            lines.push(header);
+        } else {
+            lines.splice(index, 0, header);
+        }
+    }
+
+    /**
+     * @param {string} key
+     * @returns {void}
+     */
+    remove(key) {
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        let lines = this._getLines();
+        key = this._normalizeHeader(key);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (lines[i].key === key) {
+                this.changed = true;
+                lines.splice(i, 1);
+            }
+        }
+    }
+
+    /**
+     * @param {string} key
+     * @param {string | number | Buffer} [value]
+     * @param {number} [relativeIndex]
+     * @returns {void}
+     */
+    update(key, value, relativeIndex) {
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        let lines = this._getLines();
+        let keyName = key;
+        let index = 0;
+        key = this._normalizeHeader(key);
+        let relativeIndexCount = 0;
+        let relativeMatchFound = false;
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (lines[i].key === key) {
+                if (relativeIndex && relativeIndex !== relativeIndexCount) {
+                    relativeIndexCount++;
+                    continue;
+                }
+                index = i;
+                this.changed = true;
+                lines.splice(i, 1);
+                if (relativeIndex) {
+                    relativeMatchFound = true;
+                    break;
+                }
+            }
+        }
+
+        if (relativeIndex && !relativeMatchFound) {
+            return;
+        }
+
+        this.add(keyName, value, index);
+    }
+
+    /**
+     * Serializes the headers. Unmodified headers are returned byte for byte as they
+     * were received, otherwise every line is rebuilt with `lineEnd` line endings.
+     *
+     * @param {string | false} [lineEnd] Line ending to use, defaults to CRLF.
+     * @returns {Buffer}
+     */
+    build(lineEnd) {
+        if (!this.changed && !lineEnd) {
+            return typeof this.headers === 'string' ? Buffer.from(this.headers, 'binary') : this.headers || Buffer.alloc(0);
+        }
+
+        if (!this.parsed) {
+            this._parseHeaders();
+        }
+        let lines = this._getLines();
+
+        const ending = lineEnd || '\r\n';
+
+        let headers = lines
+            .map(line => this._normalizeLineBreaks(line.line, ending))
+            // an empty line would close the header block and demote every later header
+            // into the body, so a line left with nothing in it is dropped instead
+            .filter(line => line !== '')
+            .map(line => this._buildHeaderLine(line))
+            .reduce((joined, line, idx) => {
+                if (idx) {
+                    joined.push(Buffer.from(ending, 'binary'));
+                }
+                joined.push(line);
+                return joined;
+            }, /** @type {Buffer[]} */ ([]));
+
+        headers.push(Buffer.from(ending + ending, 'binary'));
+
+        if (this.mbox) {
+            headers.unshift(Buffer.from(this.mbox + ending, 'binary'));
+        }
+
+        if (this.http) {
+            headers.unshift(Buffer.from(this.http + ending, 'binary'));
+        }
+
+        return Buffer.concat(headers);
+    }
+
+    /**
+     * @param {string} key
+     * @returns {string}
+     */
+    _normalizeHeader(key) {
+        return (key || '').toLowerCase().trim();
+    }
+
+    /**
+     * Rewrites the line breaks of a header line so that the line can only ever parse
+     * back as the single header it was reported as. A line break followed by whitespace
+     * is folding and becomes `lineEnd`, every other line break would start a new header
+     * line and is dropped.
+     *
+     * A bare <CR> is never a line break for _parseHeaders, so promoting one here would
+     * emit a header line that was never reported as parsed.
+     *
+     * @param {string} line Header line to normalize.
+     * @param {string} lineEnd Line ending to fold with.
+     * @returns {string} Line with only folding line breaks left.
+     */
+    _normalizeLineBreaks(line, lineEnd) {
+        return (
+            line
+                // lines are joined with lineEnd, so a line that opens with a break of its own
+                // would close the header block. Dropping only the break leaves any whitespace
+                // behind it folding into the line before, which adds no header of its own.
+                .replace(/^[\r\n]+/, '')
+                .replace(/\r\n|\r|\n/g, (match, offset, source) => (match !== '\r' && this._isFoldingChar(source.charAt(offset + match.length)) ? lineEnd : ''))
+        );
+    }
+
+    /**
+     * Prepares a caller supplied line for insertion. On top of the line break rules an
+     * inserted line has to stand on its own: a leading fold or indent would attach it to
+     * whichever header happens to precede it, and a leading line break would close the
+     * header block outright.
+     *
+     * Lines that were parsed out of a message keep their leading whitespace instead, so
+     * that rebuilding can never turn an indented continuation into a header of its own.
+     *
+     * An inserted line is normalized twice, here with CRLF and again in build() with the
+     * line ending the caller asked for. That is only sound because _normalizeLineBreaks is
+     * idempotent over its own output: the folds this pass emits are still recognized as
+     * folds by the next one. Any change to how a fold is represented has to keep that true.
+     *
+     * @param {string} line Formatted header line supplied by the caller.
+     * @returns {string} Line that inserts as exactly one header, or an empty string.
+     */
+    _normalizeInsertedLine(line) {
+        return this._normalizeLineBreaks(line.replace(/^[\r\n \t]+/, ''), '\r\n');
+    }
+
+    /**
+     * Tells whether a character continues the previous header line rather than
+     * starting a new one. Used by both the parser and the builder so that the two
+     * can not disagree on what folding is.
+     *
+     * @param {string} chr Character that follows a line break.
+     * @returns {boolean} True if the line break is folding.
+     */
+    _isFoldingChar(chr) {
+        return chr === ' ' || chr === '\t';
+    }
+
+    /**
+     * @returns {HeaderLine[]}
+     */
+    _getLines() {
+        if (!this.lines) {
+            this.lines = [];
+        }
+        return this.lines;
+    }
+
+    /**
+     * @returns {void}
+     */
+    _parseHeaders() {
+        if (!this.headers) {
+            this.lines = [];
+            this.parsed = true;
+            return;
+        }
+
+        /** @type {Array<string | HeaderLine>} */
+        let lines = this.headers
+            .toString('binary')
+            .replace(/[\r\n]+$/, '')
+            .split(/\r?\n/);
+
+        for (let i = lines.length - 1; i >= 0; i--) {
+            let currentLine = /** @type {string} */ (lines[i]);
+            if (i && this._isFoldingChar(currentLine.charAt(0))) {
+                lines[i - 1] = /** @type {string} */ (lines[i - 1]) + '\r\n' + currentLine;
+                lines.splice(i, 1);
+            } else {
+                let line = currentLine;
+                if (!i && /^From /i.test(line)) {
+                    // mbox file
+                    this.mbox = line;
+                    lines.splice(i, 1);
+                    continue;
+                } else if (!i && /^POST /i.test(line)) {
+                    // HTTP POST request
+                    this.http = line;
+                    lines.splice(i, 1);
+                    continue;
+                }
+                let key = this._normalizeHeader(line.substr(0, line.indexOf(':')));
+                lines[i] = {
+                    key,
+                    line
+                };
+            }
+        }
+
+        this.lines = /** @type {HeaderLine[]} */ (lines);
+        this.parsed = true;
+    }
+
+    /**
+     * @param {string} line
+     * @returns {Buffer}
+     */
+    _buildHeaderLine(line) {
+        let value = this._decodeHeaderValue(line);
+        return Buffer.from(value, value === line ? 'binary' : 'utf8');
+    }
+
+    /**
+     * @param {string} str
+     * @returns {string}
+     */
+    _decodeHeaderValue(str) {
+        if (!str) {
+            return str;
+        }
+
+        let utf8 = Buffer.from(str, 'binary').toString('utf8');
+        return utf8.includes('\uFFFD') ? str : utf8;
+    }
+}
+
+// expose to the world
+module.exports = Headers;

package/lib/message-joiner.d.ts

@@ -0,0 +1,56 @@
+import { Transform } from 'node:stream';
+
+/** Transform stream that joins splitter objects back into raw email bytes. */
+declare class MessageJoiner extends Transform {
+    /**
+     * Creates a joiner that accepts splitter objects and emits Buffer chunks.
+     */
+    constructor();
+
+    /**
+     * Registers a listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives each generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    on(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Registers a one-time listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives the next generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    once(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Adds a listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives each generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    addListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Prepends a listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives each generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    prependListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Emits a generated message byte chunk.
+     *
+     * @param event Event name.
+     * @param data Buffer chunk to emit.
+     * @returns `true` when the event had listeners.
+     */
+    emit(event: 'data', data: Buffer): boolean;
+}
+
+export = MessageJoiner;

package/lib/message-joiner.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const Transform = require('stream').Transform;
+
+/** @typedef {import('..').SplitterChunk} SplitterChunk */
+
+/**
+ * Transform stream that joins splitter objects back into raw message bytes.
+ */
+class MessageJoiner extends Transform {
+    /**
+     * Creates a joiner that accepts splitter objects and emits Buffer chunks.
+     */
+    constructor() {
+        let options = {
+            readableObjectMode: false,
+            writableObjectMode: true
+        };
+        super(options);
+    }
+
+    /**
+     * @param {SplitterChunk | Buffer} obj
+     * @param {BufferEncoding} encoding
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
+    _transform(obj, encoding, callback) {
+        if (Buffer.isBuffer(obj)) {
+            this.push(obj);
+        } else if (obj.type === 'node') {
+            this.push(obj.getHeaders());
+        } else if (obj.value) {
+            this.push(obj.value);
+        }
+        return callback();
+    }
+
+    /**
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
+    _flush(callback) {
+        return callback();
+    }
+}
+
+module.exports = MessageJoiner;

package/lib/message-splitter.d.ts

@@ -0,0 +1,59 @@
+import { Transform } from 'node:stream';
+import type { SplitterChunk, SplitterOptions } from './types';
+
+/** Transform stream that splits raw email bytes into MIME node and content chunks. */
+declare class MessageSplitter extends Transform {
+    /**
+     * Creates a splitter that accepts Buffer input and emits `SplitterChunk` objects.
+     *
+     * @param config Optional parser limits and embedded-message behavior.
+     */
+    constructor(config?: SplitterOptions);
+
+    /**
+     * Registers a listener for parsed splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    on(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Registers a one-time listener for the next parsed splitter chunk.
+     *
+     * @param event Event name.
+     * @param listener Receives the next parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    once(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Adds a listener for parsed splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    addListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Prepends a listener for parsed splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    prependListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Emits a parsed splitter chunk.
+     *
+     * @param event Event name.
+     * @param data MIME node, data chunk, or body chunk to emit.
+     * @returns `true` when the event had listeners.
+     */
+    emit(event: 'data', data: SplitterChunk): boolean;
+}
+
+export = MessageSplitter;