@flun/mailer 2.1.4

package/index.js

@@ -0,0 +1,109 @@
+/**
+ * mailer 主模块
+ *
+ * 模块依赖说明：
+ * - Mailer: 核心邮件发送器，负责管理传输器和邮件发送流程
+ * - SmtpPool: SMTP连接池传输器，支持连接复用和并发发送
+ * - SmtpTransport: 标准SMTP传输器，用于通过SMTP服务器发送邮件
+ * - SendmailTransport: 本地sendmail传输器，使用系统sendmail命令发送
+ * - StreamTransport: 流传输器，将邮件输出为流格式，主要用于测试
+ * - JsonTransport: JSON传输器，将邮件转换为JSON格式输出，用于调试
+ * - SesTransport: Amazon SES传输器，通过AWS Simple Email Service发送邮件
+ * - shared: 共享工具函数模块，包含URL解析,正则常量等通用功能
+ */
+import { Mailer } from './lib/mailer/index.js';
+import { SmtpPool } from './lib/smtp-pool/index.js';
+import { SmtpTransport } from './lib/smtp-transport.js';
+import { SendmailTransport } from './lib/sendmail-transport.js';
+import { StreamTransport } from './lib/stream-transport.js';
+import { JsonTransport } from './lib/json-transport.js';
+import { SesTransport } from './lib/ses-transport.js';
+import { parseConnectionUrl, regexs } from './lib/shared.js';
+
+// 创建传输器
+const createTransport = (transporter, defaults) => {
+    const urlConfig = typeof transporter === 'string' ? transporter : transporter.url;
+    let options;
+
+    // 如果传入的transporter是配置对象而非传输器插件,或者看起来像是连接URL
+    if ((typeof transporter === 'object' && typeof transporter.send !== 'function') ||
+        (typeof transporter === 'string' && regexs.TRANSPORTER_PROTOCOL.test(transporter))) {
+        options = urlConfig && parseConnectionUrl(urlConfig) || transporter;  // 将配置URL解析为配置选项
+
+        if (options.pool) transporter = new SmtpPool(options);
+        else if (options.sendmail) transporter = new SendmailTransport(options);
+        else if (options.streamTransport) transporter = new StreamTransport(options);
+        else if (options.jsonTransport) transporter = new JsonTransport(options);
+        else if (options.SES) {
+            if (options.SES.ses && options.SES.aws) {
+                let error = new Error('检测到旧版SES配置,请使用@aws-sdk/client-sesv2');
+                error.code = 'LegacyConfig';
+                throw error;
+            }
+            transporter = new SesTransport(options);
+        }
+        else transporter = new SmtpTransport(options);
+    }
+
+    const mailer = new Mailer(transporter, options, defaults);
+    return mailer;
+},
+    // 验证配置
+    validateConfig = config => {
+        const errors = [], warnings = [];
+
+        // 检查配置类型
+        if (!config) {
+            errors.push('配置不能为空');
+            return { valid: false, errors, warnings };
+        }
+        const { host, service, auth, port, secure, tls, pool, maxConnections, maxMessages, sendmail, SES } = config;
+
+        // 如果是字符串（URL格式）
+        if (typeof config === 'string' && !regexs.TRANSPORTER_PROTOCOL.test(config))
+            errors.push('URL格式不正确，应以 smtp://, smtps:// 或 direct:// 开头');
+        // 否则,如果是配置对象
+        else if (typeof config === 'object') {
+            // 检查传输器类型
+            const transportTypes = ['SMTP', 'Sendmail', 'Stream', 'JSON', 'SES'],
+                hasTransportType = transportTypes.some(type =>
+                    config[type.toLowerCase()] || config[type] || config[`${type}Transport`]
+                );
+
+            if (!hasTransportType && typeof config.send !== 'function') {
+                // 默认为SMTP传输器，验证SMTP相关配置
+                if (!host && !service) errors.push('必须指定 host 或 service');
+
+                if (auth) {
+                    if (!auth.user) errors.push('认证配置中缺少 user 字段');
+                    if (!auth.pass && !auth.oauth2 && !auth.xoauth2) warnings.push('(pass,oauth2,xoauth2)都无配置,将尝试无密码连接');
+                }
+                // 非25端口通常需要认证
+                else if (port !== 25) warnings.push('未提供认证信息，某些邮件服务器可能拒绝连接');
+
+                if (port && (port < 1 || port > 65535)) errors.push('端口号应在 1-65535 范围内');
+                // 检查TLS/SSL配置
+                if (secure !== undefined && typeof secure !== 'boolean') errors.push('secure 字段应为布尔值');
+                if (tls !== undefined && typeof tls !== 'object' && typeof tls !== 'boolean') errors.push('tls 字段应为对象或布尔值');
+            }
+
+            // 验证池配置
+            if (pool && typeof pool !== 'boolean') errors.push('pool 字段应为布尔值');
+            if (maxConnections && (typeof maxConnections !== 'number' || maxConnections < 1)) errors.push('maxConnections 应为大于0的数字');
+            if (maxMessages && (typeof maxMessages !== 'number' || maxMessages < 1)) errors.push('maxMessages 应为大于0的数字');
+
+            // 验证Sendmail配置
+            if (sendmail && sendmail !== true && typeof sendmail !== 'string') errors.push('sendmail 字段应为布尔值或字符串路径');
+
+            // 验证SES配置
+            if (SES) {
+                if (typeof SES !== 'object') errors.push('SES 配置应为对象');
+                else if (SES.ses && SES.aws) warnings.push('检测到旧版SES配置，建议使用新版AWS SDK');
+            }
+        }
+        else errors.push('配置应为字符串或对象');
+
+        return { valid: errors.length === 0, errors, warnings: warnings.length > 0 ? warnings : undefined };
+    };
+
+export { createTransport, validateConfig };

package/lib/addressparser.js

@@ -0,0 +1,230 @@
+import { regexs } from './regexs.js';
+
+/**
+ * 用于标记地址字段字符串的标记器
+ * @constructor
+ * @param {String} str 需要解析的地址字段字符串
+ */
+class Tokenizer {
+    constructor(str = '') {
+        this.str = str.toString(), this.operatorExpecting = '', this.node = null, this.escaped = false, this.list = [];
+
+        // 操作符映射：开始操作符到期望的结束操作符(引号,注释,邮件地址,地址分隔符,组定义开始,组定义结束)
+        this.operators = { '"': '"', '(': ')', '<': '>', ',': '', ':': ';', ';': '' };
+    }
+
+    /**
+     * 将输入字符串标记化为操作符和文本令牌
+     * @return {Array} 令牌对象数组
+     */
+    tokenize() {
+        const list = [];
+
+        for (let i = 0, len = this.str.length; i < len; i++) {
+            const chr = this.str.charAt(i), nextChr = i < len - 1 ? this.str.charAt(i + 1) : null;
+            this.#processChar(chr, nextChr);
+        }
+
+        // 过滤并清理令牌
+        this.list.forEach(node => {
+            node.value = (node.value || '').toString().trim();
+            if (node.value) list.push(node); // 忽略空文本节点
+        });
+
+        return list;
+    }
+
+    /**
+     * 处理单个字符，识别操作符或文本内容
+     * @param {String} chr 当前字符
+     * @param {String} nextChr 下一个字符（用于前瞻）
+     */
+    #processChar(chr, nextChr) {
+        const { escaped, operatorExpecting: oExpecting, operators } = this;
+        // 检查是否是期望的结束操作符
+        if (!escaped && chr === oExpecting) return this.#addOperatorToken(chr, nextChr);
+
+        // 检查是否是新的开始操作符
+        else if (!escaped && !oExpecting && chr in operators) return this.#addOperatorToken(chr, nextChr, operators[chr]);
+
+        // 检查转义字符（在引号或注释中）
+        else if (!escaped && ['"', "'"].includes(oExpecting) && chr === '\\') return this.escaped = true;
+        this.#addTextChar(chr), this.escaped = false;  // 处理文本字符并重置转义标志
+    }
+
+    /**
+     * 添加操作符令牌到列表
+     * @param {String} chr 操作符字符
+     * @param {String} nextChr 下一个字符（用于设置noBreak标志）
+     * @param {String} newExpecting 新的期望操作符
+     */
+    #addOperatorToken(chr, nextChr, newExpecting = '') {
+        const node = { type: 'operator', value: chr };
+        // 如果下一个字符不是空白或分隔符，设置noBreak标志
+        if (nextChr && ![' ', '\t', '\r', '\n', ',', ';'].includes(nextChr)) node.noBreak = true;
+        this.list.push(node), this.node = null, this.escaped = false, this.operatorExpecting = newExpecting;
+    }
+
+    /**
+     * 添加文本字符到当前文本节点
+     * @param {String} chr 文本字符
+     */
+    #addTextChar(chr) {
+        if (!this.node) this.node = { type: 'text', value: '' }, this.list.push(this.node); // 如果没有当前文本节点,则创建一个新的
+
+        const processedChr = chr === '\n' ? ' ' : chr; // 规范化空白字符
+        if (chr.charCodeAt(0) >= 0x21 || [' ', '\t'].includes(chr)) this.node.value += processedChr;// 如果是可见字符或空格,则添加
+    }
+}
+
+/**
+ * 如果文本数据为空但存在注释数据，则用注释数据替换文本数据
+ * @param {Object} data 包含文本和注释数据的对象
+ * @return {Object} 处理后的数据对象
+ */
+const _replaceTextWithComment = data => {
+    if (!data.text.length && data.comment.length) data.text = data.comment, data.comment = [];
+    return data;
+},
+
+    /**
+     * 从文本数据中检测并提取电子邮件地址
+     * @param {Object} data 包含地址和文本数据的对象
+     */
+    _extractEmailFromText = data => {
+        let foundAddress = false;
+        const { text } = data,
+            regexHandler = address => {
+                if (!foundAddress) {
+                    data.address = [address.trim()], foundAddress = true;
+                    return '';
+                }
+                return address;
+            };
+
+        for (let i = text.length - 1; i >= 0; i--) {
+            const currentText = text[i];
+            if (currentText.match(regexs.EMAIL_EXACT)) {
+                data.address = text.splice(i, 1), foundAddress = true;
+                break;
+            }
+            if (!foundAddress) {
+                // ✅ 移除 .trim(),保留原始空格,后续 join 会自然合并
+                text[i] = currentText.replace(regexs.EMAIL_LOOSE, regexHandler);
+                if (foundAddress) break;
+            }
+        }
+        // 清理文本数组中可能产生的多余空白项
+        data.text = data.text.filter(t => t.trim() !== '');
+    },
+
+    /**
+     * 将单个地址的令牌转换为地址对象
+     * @param {Array} tokens 令牌对象数组
+     * @return {Array} 地址对象数组
+     */
+    _handleAddress = tokens => {
+        let isGroup = false, state = 'text';
+        const data = { address: [], comment: [], group: [], text: [] };
+
+        // 解析令牌，分类到地址、注释、组或文本
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i], prevToken = i ? tokens[i - 1] : null;
+            if (token.type === 'operator')
+                switch (token.value) {
+                    case '<':
+                        state = 'address';
+                        break;
+                    case '(':
+                        state = 'comment';
+                        break;
+                    case ':':
+                        state = 'group';
+                        isGroup = true;
+                        break;
+                    default:
+                        state = 'text';
+                        break;
+                }
+            else if (token.value) {
+                // 清理地址令牌中的多余字符(如未引用的名称中的"<")
+                if (state === 'address') token.value = token.value.replace(regexs.ADDRESS_CLEAN, '');
+
+                // 如果前一个令牌设置了noBreak，则附加到最后一个元素,否则创建新的元素
+                const dLen = data[state].length;
+                prevToken?.noBreak && dLen ? data[state][dLen - 1] += token.value : data[state].push(token.value);
+            }
+        }
+        const { text, group, address } = _replaceTextWithComment(data);             // 如果没有文本但有注释，用注释替换文本
+        // 如果组存在，处理组地址：组名和组成员列表
+        if (isGroup) return [{ name: text.join(' ') || '', group: group.length ? addressparser(group.join(',')) : [] }];
+        else {
+            if (!address.length && text.length) _extractEmailFromText(data);         // 如果没有地址，从文本中提取电子邮件地址
+
+            const { text: newTxt, address: newAdd } = _replaceTextWithComment(data); // 再次检查是否需要将注释转换为文本
+            if (newAdd.length > 1) newTxt.push(...newAdd.splice(1));                 // 如果找到多个地址,只保留第一个,其余的转到文本数组
+            const addressText = newTxt.join(' ').trim(), addressValue = newAdd.join(' ').trim(),// 合并文本和地址数据
+                // 创建地址对象
+                addressObj = { address: addressValue || addressText || '', name: addressText || addressValue || '' };
+
+            // 如果地址和名称相同，根据内容决定清除哪个(如果是邮件地址,清除名称,否则,清除地址)
+            if (addressObj.address === addressObj.name)
+                addressObj.address.includes('@') ? addressObj.name = '' : addressObj.address = '';
+
+            return [addressObj];
+        }
+    };
+
+/**
+ * 解析地址字段字符串为结构化的电子邮件地址对象数组
+ * >查看定义:@see {@link addressparser}
+ * - 示例:
+ *   '姓名 <user@example.com>'
+ *   转换为 [{name: '姓名', address: 'user@example.com'}]
+ *
+ * 支持:
+ *   - 单个地址: 'user@example.com'
+ *   - 带姓名地址: '姓名 <user@example.com>'
+ *   - 带注释地址: '姓名 (注释) <user@example.com>'
+ *   - 地址组: '组名: member1@example.com, member2@example.com;'
+ *
+ * @param {String} str 需要解析的地址字段字符串
+ * @param {Object} options 解析选项
+ * @param {Boolean} options.flatten 是否将组地址展平为单个地址列表
+ * @return {Array} 地址对象数组
+ */
+const addressparser = (str, options = {}) => {
+    const tokenizer = new Tokenizer(str), tokens = tokenizer.tokenize(), addresses = [];
+    let currentAddress = [];
+
+    // 根据分隔符将令牌分组为各个地址
+    tokens.forEach(token => {
+        if (token.type === 'operator' && [',', ';'].includes(token.value)) {
+            if (currentAddress.length) addresses.push(currentAddress);
+            currentAddress = [];
+        }
+        else currentAddress.push(token);
+    });
+
+    if (currentAddress.length) addresses.push(currentAddress);  // 处理最后一个地址
+    let parsedAddresses = []; // 解析每个地址组
+    addresses.forEach(addressTokens => {
+        const address = _handleAddress(addressTokens);
+        if (address.length) parsedAddresses = parsedAddresses.concat(address);
+    });
+
+    // 如果要求展平，将组地址转换为平面列表
+    if (options.flatten) {
+        const flattenedAddresses = [],
+            walkAddressList = list => {
+                list.forEach(({ group, ...address }) => group ? walkAddressList(group) : flattenedAddresses.push(address));
+            };
+
+        walkAddressList(parsedAddresses);
+        return flattenedAddresses;
+    }
+
+    return parsedAddresses;
+}
+
+export { addressparser };

package/lib/base64.js

@@ -0,0 +1,103 @@
+import { Transform } from 'stream';
+
+/**
+ * 将Buffer编码为base64字符串
+ * >查看定义:@see {@link base64Encode}
+ * @param {Buffer} buffer 要转换的Buffer
+ * @returns {String} base64编码的字符串
+ */
+const base64Encode = buffer => {
+    if (typeof buffer === 'string') buffer = Buffer.from(buffer, 'utf-8');
+    return buffer.toString('base64');
+},
+
+    /**
+     * 为base64字符串添加软换行
+     *
+     * @param {String} str 可能需要换行的base64编码字符串
+     * @param {Number} [lineLength=76] 每行的最大允许长度
+     * @returns {String} 软换行的base64编码字符串
+     */
+    base64Wrap = (str = '', lineLength = 76) => {
+        str = str.toString();
+        if (str.length <= lineLength) return str;
+
+        let pos = 0;
+        const result = [], chunkLength = lineLength * 1024;
+
+        // 每行最多允许lineLength个字符，每1024行进行一次处理
+        while (pos < str.length) {
+            const end = pos + chunkLength, wLines = str.substring(pos, end).replace(new RegExp(`.{${lineLength}}`, 'g'), '$&\r\n');
+            result.push(wLines), pos = end;
+        }
+
+        return result.join('');
+    };
+
+/**
+ * 创建用于将数据编码为base64的转换流
+ * >查看定义:@see {@link Base64Encoder}
+ * @constructor
+ * @param {Object} options 流选项
+ * @param {Number} [options.lineLength=76] 行最大长度，设置为false可禁用换行
+ */
+class Base64Encoder extends Transform {
+    constructor(options = {}) {
+        super();
+        this.options = options;
+
+        // 默认每行76个字符
+        const { lineLength } = this.options;
+        if (lineLength !== false) this.options.lineLength = lineLength || 76;
+        // 当前行内容,上次剩余的字节,输入字节数,输出字节数
+        this._curLine = '', this._remainingBytes = false, this.inputBytes = 0, this.outputBytes = 0;
+    }
+
+    _transform(chunk, encoding, done) {
+        if (encoding !== 'buffer') chunk = Buffer.from(chunk, encoding); // 如果不是Buffer，则按指定编码转换为Buffer
+        if (!chunk?.length) return setImmediate(done);                   // 如果没有数据，直接返回
+
+        this.inputBytes += chunk.length;
+        // 如果上次有剩余的字节，先补齐
+        const rLen = this._remainingBytes?.length ?? 0;
+        if (rLen)
+            chunk = Buffer.concat([this._remainingBytes, chunk], rLen + chunk.length), this._remainingBytes = false;
+
+        // base64每3个字节编码为4个字符，如果不是3的倍数，则剩余的字节留到下次处理
+        const remain = chunk.length % 3;
+        if (remain) {
+            const chunkEnd = chunk.length - remain;
+            this._remainingBytes = chunk.slice(chunkEnd), chunk = chunk.slice(0, chunkEnd);
+        }
+        else this._remainingBytes = false;
+
+        let b64 = this._curLine + base64Encode(chunk);
+        const lineLength = this.options.lineLength;
+        if (lineLength) {
+            b64 = base64Wrap(b64, lineLength);
+            const indexLF = b64.lastIndexOf('\n');              // 最后一个换行符位置
+            if (indexLF < 0) this._curLine = b64, b64 = '';
+            else {
+                const nextIndex = indexLF + 1;
+                this._curLine = b64.substring(nextIndex), b64 = b64.substring(0, nextIndex);
+                if (b64 && !b64.endsWith('\r\n')) b64 += '\r\n'; // 确保以换行符结尾
+            }
+        }
+        else this._curLine = ''; // 不换行
+
+        if (b64) this.outputBytes += b64.length, this.push(Buffer.from(b64, 'ascii')); // 输出编码后的数据
+        setImmediate(done);
+    }
+
+    // 处理剩余的字节(​Nodejs流机制在适当时候自动调用_flush)
+    _flush(done) {
+        const _rBytes = this._remainingBytes;
+        if (_rBytes?.length) this._curLine += base64Encode(_rBytes);
+        const _curLine = this._curLine;
+        // 输出剩余的数据
+        if (_curLine) this.outputBytes += _curLine.length, this.push(Buffer.from(_curLine, 'ascii')), this._curLine = '';
+        done();
+    }
+}
+
+export { base64Encode, Base64Encoder };

package/lib/dkim/index.js

@@ -0,0 +1,211 @@
+/**
+ * 用于邮件服务器或邮件发送系统,为外发邮件添加DKIM签名，
+ * 提高邮件的可信度和防伪造能力,帮助通过SPF、DKIM、DMARC等反垃圾邮件验证
+ */
+import { unlink, createReadStream, createWriteStream } from 'fs';
+import { join as pJoin } from 'path';
+import { PassThrough } from 'stream';
+import { randomBytes } from 'crypto';
+import { MessageParser } from './message-parser.js';
+import { RelaxedBody } from './relaxed-body.js';
+import { generateDKIMSignature as signer } from './sign.js';  // 用于生成DKIM签名字段
+
+// DKIM签名的默认哈希算法,最大保存消息;
+const DKIM_ALGO = 'sha256', MAX_MESSAGE_SIZE = 2 * 1024 * 1024;
+
+/**
+ * DKIMSigner 类 - 实现 DKIM 签名的流式处理
+ *
+ * @class DKIMSigner
+ * @description 该类负责在邮件传输过程中对邮件内容进行 DKIM 签名;
+ * 它通过管道流的方式读取原始邮件数据,解析邮件头和邮件体,
+ * 计算邮件体的哈希值,并使用提供的私钥生成 DKIM 签名头,
+ * 最终将签名后的邮件数据写入输出流,支持多密钥签名、缓存
+ * 溢出处理及宽松正文规范化;
+ */
+class DKIMSigner {
+    // 初始化 DKIM 签名器实例
+    constructor(options = {}, keys, input, output) {
+        this.options = options;
+        const { cacheTreshold, hashAlgo, cacheDir } = this.options;
+        this.cacheTreshold = Number(cacheTreshold) || MAX_MESSAGE_SIZE;
+        this.hashAlgo = hashAlgo || DKIM_ALGO, this.cacheDir = cacheDir || false;
+        this.keys = keys, this.chunks = [], this.chunklen = 0, this.readPos = 0;
+        this.cachePath =
+            this.cacheDir ? pJoin(this.cacheDir, `message.${Date.now()}-${randomBytes(14).toString('hex')}`) : false;
+
+        this.input = input, this.output = output;
+        this.cache = false, this.headers = false, this.bodyHash = false, this.parser = false, this.relaxedBody = false;
+        this.output.usingCache = false, this.hasErrored = false;
+        this.input.on('error', err => {
+            this.hasErrored = true, this.cleanup(), output.emit('error', err);
+        });
+    }
+
+    // 清理缓存文件
+    cleanup() {
+        if (!this.cache || !this.cachePath) return; // 如果没有缓存文件则不需要清理
+        unlink(this.cachePath, () => false);     // 删除缓存文件(忽略错误)
+    }
+
+    // 创建读取缓存流
+    createReadCache() {
+        // 将剩余数据管道传输到缓存文件
+        this.cache = createReadStream(this.cachePath);
+        this.cache.once('error', err => {
+            this.cleanup(), this.output.emit('error', err);
+        }).once('close', () => this.cleanup());
+        this.cache.pipe(this.output);
+    }
+
+    // 发送下一个数据块
+    sendNextChunk() {
+        if (this.hasErrored) return; // 如果已经出错则不继续发送数据
+
+        // 如果没有缓存文件则结束输出,否则创建读取缓存流
+        if (this.readPos >= this.chunks.length) return !this.cache ? this.output.end() : this.createReadCache();
+        // 写入数据，如果返回false则等待'drain'事件
+        const chunk = this.chunks[this.readPos++];
+        if (this.output.write(chunk) === false) return this.output.once('drain', () => this.sendNextChunk());
+        setImmediate(() => this.sendNextChunk());
+    }
+
+    // 发送签名后的输出
+    sendSignedOutput() {
+        let keyPos = 0;
+        const signNextKey = () => {
+            // 所有密钥都已处理，发送原始头部并继续发送数据块
+            if (keyPos >= this.keys.length) {
+                this.output.write(this.parser.rawHeaders);
+                return setImmediate(() => this.sendNextChunk());
+            }
+            const { domainName, keySelector, privateKey } = this.keys[keyPos++], { headerFieldNames, skipFields } = this.options,
+                // 定义 DKIM 签名字段
+                dkimField = signer(this.headers, this.hashAlgo, this.bodyHash,
+                    { domainName, keySelector, privateKey, headerFieldNames, skipFields });
+            if (dkimField) this.output.write(Buffer.from(`${dkimField}\r\n`)); // 如果签名成功则写入 DKIM 字段
+            return setImmediate(signNextKey);
+        };
+
+        if (this.bodyHash && this.headers) return signNextKey();               // 如果已经有bodyHash和headers则直接签名
+        this.output.write(this.parser.rawHeaders), this.sendNextChunk();
+    }
+
+    // 创建写入缓存流
+    createWriteCache() {
+        this.output.usingCache = true, this.cache = createWriteStream(this.cachePath);  // 将剩余数据管道传输到缓存文件
+        // 处理缓存流的错误和关闭事件
+        this.cache.once('error', err => {
+            this.cleanup(), this.relaxedBody.unpipe(this.cache);    // 清理缓存文件,停止传输到缓存
+            this.relaxedBody.resume();                              // 自动消耗剩余数据
+            this.hasErrored = true, this.output.emit('error', err); // 触发错误事件
+        }).once('close', () => this.sendSignedOutput());
+        this.relaxedBody.removeAllListeners('readable'), this.relaxedBody.pipe(this.cache);
+    }
+
+    // 开始签名流处理
+    signStream() {
+        this.parser = new MessageParser();
+        this.relaxedBody = new RelaxedBody({ hashAlgo: this.hashAlgo }); // 使用宽松的正文处理
+        this.parser.on('headers', value => this.headers = value);        // 监听解析器的头部事件
+        this.relaxedBody.on('hash', value => this.bodyHash = value);     // 监听宽松正文的哈希事件
+
+        // 监听宽松正文的可读事件
+        this.relaxedBody.on('readable', () => {
+            let chunk;
+            if (this.cache) return; // 如果已经是缓存模式则不继续处理
+            while ((chunk = this.relaxedBody.read()) !== null) {
+                this.chunks.push(chunk), this.chunklen += chunk.length;
+                // 如果数据块长度超过阈值且有缓存路径则切换到缓存模式
+                if (this.chunklen >= this.cacheTreshold && this.cachePath) return this.createWriteCache();
+            }
+        });
+
+        // 监听宽松正文的结束事件
+        this.relaxedBody.on('end', () => {
+            if (this.cache) return; // 如果已经是缓存模式则不继续处理
+            this.sendSignedOutput();
+        });
+
+        this.parser.pipe(this.relaxedBody), setImmediate(() => this.input.pipe(this.parser));
+    }
+}
+
+/**
+ * DKIM 类 - DomainKeys Identified Mail 签名处理类
+ * >查看定义:@see {@link DKIM}
+ * @class DKIM
+ * @description 用于对邮件内容进行 DKIM 签名,支持从配置中加载多个域名密钥;
+ *              将字符串、Buffer 或流形式的邮件输入转换为经过签名的输出流;
+ *              签名过程通过内部 DKIMSigner 完成;通常与邮件发送流程集成使用;
+ *
+ * @example
+ * ```js
+ *   // 1. 创建DKIM实例
+ *   const dkim = new DKIM({
+ *       domainName: 'example.com',        // 域名,用于标识签名来源
+ *        keySelector: 'key-selector',     // 密钥选择器,用于在DNS中查找公钥
+ *        privateKey, // RSA 私钥,PEM 格式字符串（包含 -----BEGIN RSA PRIVATE KEY----- 等）,用于生成 DKIM 签名
+ *        cacheDir: '/tmp'                 // 缓存目录,用于处理大邮件时的临时存储
+ *    });
+ *
+ *    // 2. 对邮件进行签名
+ *    dkim.sign(input).pipe(process.stdout);
+ * ```
+ *  参数说明：
+ *    input: 输入邮件内容，可以是以下类型：
+ *    Stream (流)：可读流，包含RFC822格式的原始邮件
+ *    String (字符串)：邮件内容的字符串形式
+ *    Buffer (缓冲区)：邮件内容的二进制缓冲区
+ *
+ *  - 返回值：一个可读流，包含已添加DKIM签名的完整邮件
+ *
+ *  工作流程：
+ *  1. 解析输入邮件的头部和正文
+ *  2. 对邮件正文进行规范化处理并计算哈希值
+ *  3. 使用私钥对指定邮件头字段和正文哈希进行签名
+ *  4. 在邮件头部添加DKIM-Signature字段
+ *  5. 输出完整的已签名邮件
+ */
+class DKIM {
+    // 初始化 DKIM 实例
+    constructor(options = {}) {
+        this.options = options;
+        const { keys, domainName, keySelector, privateKey } = this.options;
+        this.keys = [].concat(keys || { domainName, keySelector, privateKey });
+    }
+
+    // 签名输入数据
+    sign(input, extraOptions = {}) {
+        const output = new PassThrough();
+        let inputStream = input, writeValue = false;
+
+        // 如果输入是字符串或Buffer，则转换为流
+        if (Buffer.isBuffer(input)) writeValue = input, inputStream = new PassThrough();
+        // 否则如果输入是字符串，则转换为Buffer
+        else if (typeof input === 'string') writeValue = Buffer.from(input), inputStream = new PassThrough();
+
+        const options = this.options;
+        let newOptions = {};
+        // 如果有额外选项，则合并选项
+        if (extraOptions && Object.keys(extraOptions).length) {
+            newOptions = { ...options };
+            // 仅添加不存在的选项
+            Object.keys(extraOptions).forEach(key => {
+                if (!(key in newOptions)) newOptions[key] = extraOptions[key]
+            });
+        }
+        else newOptions = options;
+
+        const signer = new DKIMSigner(newOptions, this.keys, inputStream, output); // 创建 DKIM 签名器实例,使用最终的合并选项
+        // 异步启动签名流处理
+        setImmediate(() => {
+            signer.signStream();
+            if (writeValue) setImmediate(() => inputStream.end(writeValue));       // 如果有写入值,则在下一个事件循环中结束输入流
+        });
+
+        return output;
+    }
+}
+
+export { DKIM };