@flun/mailer 2.1.4

package/lib/dkim/message-parser.js

@@ -0,0 +1,114 @@
+import { Transform } from 'stream';
+import { regexs } from '../regexs.js';
+
+/**
+ * MessageParser实例是一个转换流,用于将消息头与消息体分离;
+ * 头信息通过'headers'事件发射,消息体作为结果流传递;
+ * >查看定义:@see {@link MessageParser}
+ */
+class MessageParser extends Transform {
+    constructor(options) {
+        super(options);
+        this.lastBytes = Buffer.alloc(4), this.headersParsed = false, this.rawHeaders = false;
+        this.bodySize = 0, this.headerBytes = 0, this.headerChunks = [];
+    }
+
+    // 处理下一个数据块
+    _transform(chunk, encoding, callback) {
+        if (!chunk?.length) return callback();                                 // 忽略空块
+        if (typeof chunk === 'string') chunk = Buffer.from(chunk, encoding);   // 确保块是一个Buffer
+
+        try {
+            const headersFound = this.checkHeaders(chunk);                     // 检查并处理头信息
+            if (headersFound) this.bodySize += chunk.length, this.push(chunk); // 如果找到了头信息,推送剩余的消息体
+            setImmediate(callback);
+        } catch (E) {
+            return callback(E);
+        }
+    }
+
+    // 在流结束时处理任何剩余的头信息
+    _flush(callback) {
+        // 如果还有未处理的头信息块，则推送它们
+        if (this.headerChunks) {
+            const chunk = Buffer.concat(this.headerChunks, this.headerBytes);
+            this.bodySize += chunk.length, this.push(chunk), this.headerChunks = null;
+        }
+        callback(); // 完成
+    }
+
+    /**
+     * 更新记录最后4个字节，以便在块边界检测换行符
+     *
+     * @param {Buffer} data 来自流的下一个数据块
+     */
+    updateLastBytes(data) {
+        const lblen = this.lastBytes.length, nblen = Math.min(data.length, lblen);
+
+        // 移动现有字节
+        for (let i = 0, len = lblen - nblen; i < len; i++) this.lastBytes[i] = this.lastBytes[i + nblen];
+        // 添加新字节
+        for (let i = 1; i <= nblen; i++) this.lastBytes[lblen - i] = data[data.length - i];
+    }
+
+    /**
+     * 从剩余的消息体中查找并移除消息头。将头信息保持分离，直到最终投递，以便修改
+     *
+     * @param {Buffer} data 下一个数据块
+     * @return {Boolean} 如果已经找到头信息则返回true，否则返回false
+     */
+    checkHeaders(data) {
+        if (this.headersParsed) return true; // 如果已经找到头信息，则不需要检查
+
+        const lblen = this.lastBytes.length;
+        let headerPos = 0;
+        this.curLinePos = 0;
+        // 检查是否有两个连续的换行符，表示头信息的结尾
+        for (let i = 0; i < lblen + data.length; i++) {
+            const chr = i < lblen ? this.lastBytes[i] : data[i - lblen]; // 如果小于长度,使用lastBytes中的字节,否则使用data中的字节
+            // 检查是否有两个连续的换行符
+            if (chr === 0x0a && i) {
+                const pr1 = i - 1 < lblen ? this.lastBytes[i - 1] : data[i - 1 - lblen], // 定义pr1为当前字节的前一个字节的值
+                    // 定义pr2为当前字节的前两个字节的值(如果存在)
+                    pr2 = i > 1 ? (i - 2 < lblen ? this.lastBytes[i - 2] : data[i - 2 - lblen]) : false;
+
+                // 如果前一个字符是0x0a，或者前两个字符是0x0d 0x0a，则表示头信息结束
+                if (pr1 === 0x0a || (pr1 === 0x0d && pr2 === 0x0a)) {
+                    this.headersParsed = true, headerPos = i - lblen + 1, this.headerBytes += headerPos;
+                    break;
+                }
+            }
+        }
+
+        // 如果找到了头信息
+        if (this.headersParsed) {
+            this.headerChunks.push(data.subarray(0, headerPos)), this.rawHeaders = Buffer.concat(this.headerChunks, this.headerBytes);
+            this.headerChunks = null, this.emit('headers', this.parseHeaders());
+            // 如果数据块中还有剩余的消息体，则推送剩余的消息体
+            if (data.length - 1 > headerPos) {
+                const chunk = data.subarray(headerPos);
+                this.bodySize += chunk.length, setImmediate(() => this.push(chunk));
+            }
+            return true;
+        }
+        // 否则将整个数据块添加到头信息块中
+        else this.headerBytes += data.length, this.headerChunks.push(data);
+
+        this.updateLastBytes(data);  // 更新最后的字节
+        return false;
+    }
+
+    // 解析原始头信息为键值对数组
+    parseHeaders() {
+        const lines = (this.rawHeaders || '').toString().split(regexs.LINE_SEPARATOR); // 按行拆分(丢弃换行符)
+        // 处理折叠的头信息行
+        for (let i = lines.length - 1; i > 0; i--)
+            // 如果当前行是空白行，则将其与前一行合并
+            if (regexs.FOLDED_HEADER_LINE.test(lines[i])) lines[i - 1] += `\n${lines[i]}`, lines.splice(i, 1);
+
+        return lines.filter(line => line.trim())
+            .map(line => { key: line.slice(0, line.indexOf(':')).trim().toLowerCase(), line });
+    }
+}
+
+export { MessageParser };

package/lib/dkim/relaxed-body.js

@@ -0,0 +1,133 @@
+import { Transform } from 'stream';
+import { createHash } from 'crypto';
+import { regexs, resetRegex } from '../regexs.js';
+
+/**
+ * 宽松规范化邮件正文的转换流,实现DKIM签名中的relaxed body canonicalization
+ * - 主要功能：
+ * 1. 将所有的行结束符统一为CRLF
+ * 2. 移除每行末尾的空白字符(WSP)
+ * 3. 将行内的多个空白字符替换为单个空格
+ * 4. 计算规范化后内容的哈希值
+ * >查看定义:@see {@link RelaxedBody}
+ */
+class RelaxedBody extends Transform {
+    /**
+     * 构造函数
+     * @param {Object} options - 配置选项
+     * @param {string} options.hashAlgo - 哈希算法，默认为'sha1'
+     * @param {boolean} options.debug - 是否启用调试模式
+     */
+    constructor(options = {}) {
+        super(options);
+        const { hashAlgo, debug } = options;
+        // 初始化哈希计算器,存储未处理完的数据片段(跨块的未完成行),记录已处理的字节长度
+        this.bodyHash = createHash(hashAlgo || 'sha1'), this.remainder = '', this.byteLength = 0;
+        this.debug = debug, this._debugBody = debug ? [] : false; // 调试模式相关设置
+    }
+
+    /**
+     * 处理数据块并更新哈希值
+     * 应用宽松规范化规则：
+     * 1. 将所有行结束符统一为CRLF
+     * 2. 移除行尾空白字符(WSP)
+     * 3. 将行内多个空白字符替换为单个空格
+     * @param {Buffer} chunk - 输入数据块
+     */
+    updateHash(chunk) {
+        // 将当前数据块转换为字符串并与之前的余数合并
+        const fullStr = this.remainder + chunk.toString('latin1');
+        if (fullStr.length === 0) return;                       // 如果合并后字符串为空，无需处理
+        this.remainder = '';                                    // 清空余数，将在处理过程中重新收集
+        const lines = fullStr.split(regexs.SPLIT_KEEP_NEWLINE); // 使用正则表达式按行分割，保留行结束符信息
+        if (!regexs.TRAILING_LINE_BREAK.test(fullStr)) this.remainder = lines.pop() || ''; // 如最后不是完整的行结束符,保留作为余数
+
+        // 处理每一行内容（跳过行结束符部分）
+        const processedLines = [];
+        for (let i = 0; i < lines.length; i++) {
+            // 如果是行结束符，直接添加
+            if (i % 2 === 1) {
+                processedLines.push(lines[i]);
+                continue;
+            }
+
+            // 处理行内容
+            let line = lines[i];
+            line = line.replace(regexs.TRAILING_WSP, '');               // 移除行尾空白字符（WSP）
+            const M_WPS = resetRegex(regexs.MULTIPLE_WSP);
+            line = line.replace(M_WPS, ' '), processedLines.push(line); // 将行内多个空白字符替换为单个空格并添加到结果中
+
+        }
+
+        // 重新组装处理后的内容
+        let processedStr = processedLines.join('');
+        // 如果有余数，需要特殊处理（可能是不完整的行）
+        if (this.remainder) {
+            // 余数中的空白字符处理（但不移除行尾空白，因为可能不是完整行）
+            const rMW = resetRegex(regexs.MULTIPLE_WSP), pRemainder = this.remainder.replace(rMW, ' ');
+            processedStr += pRemainder;
+        }
+
+        const processedChunk = Buffer.from(processedStr, 'latin1');      // 将处理后的字符串转换回Buffer
+        if (this.debug) this._debugBody.push(processedChunk);            // 如果启用调试模,则记录处理后的数据块
+        this.bodyHash.update(processedChunk), this.push(processedChunk); // 更新哈希值并将处理后的数据推送到输出流
+
+    }
+
+    /**
+     * 转换流的核心方法，处理输入数据
+     * @param {Buffer|string} chunk - 输入数据块
+     * @param {string} encoding - 编码方式
+     * @param {function} callback - 完成回调
+     */
+    _transform(chunk, encoding, callback) {
+        try {
+            // 如果是空块，更新哈希并完成
+            if (!chunk?.length) {
+                this.updateHash(Buffer.alloc(0));
+                return callback();
+            }
+            if (typeof chunk === 'string') chunk = Buffer.from(chunk, encoding); // 如果块是字符串,转换为Buffer
+
+            // 处理数据块并更新哈希,更新已处理的字节长度,最后通知转换完成
+            this.updateHash(chunk); this.byteLength += chunk.length; callback();
+        } catch (err) {
+            callback(err);
+        }
+    }
+
+    /**
+     * 流结束时的处理逻辑
+     * 处理剩余数据并发出哈希值
+     * @param {function} callback - 完成回调
+     */
+    _flush(callback) {
+        try {
+            // 处理剩余的余数
+            if (this.remainder) {
+                // 对余数应用规范化规则
+                const rMW = resetRegex(regexs.MULTIPLE_WSP),
+                    pRemainder = this.remainder.replace(regexs.TRAILING_WSP, '').replace(rMW, ' '),
+                    remainderChunk = Buffer.from(pRemainder, 'latin1');
+
+                if (this.debug) this._debugBody.push(remainderChunk); // 调试模式：记录处理后的余数
+                // 更新哈希值,将处理后的余数推送到输出流,然后更新已处理的字节长
+                this.bodyHash.update(remainderChunk); this.push(remainderChunk); this.byteLength += remainderChunk.length;
+            }
+
+            // 确保以CRLF结束（如果消息体为空，或者余数不以CRLF结束）
+            if (this.byteLength === 0 || !this.remainder?.endsWith('\r\n')) {
+                const crlf = Buffer.from('\r\n');
+                this.bodyHash.update(crlf), this.push(crlf);
+            }
+
+            // 发出哈希计算完成事件
+            this.emit('hash', this.bodyHash.digest('base64'), this.debug ? Buffer.concat(this._debugBody) : false);
+            callback(); // 通知刷新完成
+        } catch (err) {
+            callback(err);
+        }
+    }
+}
+
+export { RelaxedBody };

package/lib/dkim/sign.js

@@ -0,0 +1,121 @@
+// 引入必要的模块
+import { createSign } from 'crypto';                // Node.js加密模块，用于生成签名
+import { toASCII } from '../punycode.js';           // 用于处理Unicode域名的punycode转换
+import { foldLines } from '../mime-funcs/index.js'; // 提供MIME相关工具函数
+import { regexs, resetRegex } from '../regexs.js';
+
+/**
+ * 生成DKIM签名头（不含签名值部分）
+ *
+ * @param {String} domainName 域名
+ * @param {String} keySelector 密钥选择器
+ * @param {String} fieldNames 参与签名的头字段列表
+ * @param {String} hashAlgo 哈希算法
+ * @param {String} bodyHash 正文哈希值
+ * @return {String} 生成的DKIM签名头字符串
+ */
+const _generateDKIMHeader = (domainName, keySelector, fieldNames, hashAlgo, bodyHash) => {
+    // 构建DKIM签名头的各个部分
+    let dkim = [
+        'v=1',                      // 版本
+        `a=rsa-${hashAlgo}`,        // 算法
+        'c=relaxed/relaxed',        // 规范化方法（头/正文）
+        `d=${toASCII(domainName)}`, // 域名（转换为ASCII）
+        'q=dns/txt',                // 查询方式
+        `s=${keySelector}`,         // 密钥选择器
+        `bh=${bodyHash}`,           // 正文哈希
+        `h=${fieldNames}`           // 参与签名的头字段
+    ].join('; ');                   // 用分号加空格连接
+
+    return `${foldLines(`DKIM-Signature:${dkim}`, 76)};\r\n b=`; // 对长行进行折行处理,并添加头名称和签名开始标记
+},
+
+    /**
+     * 从邮件头中提取并规范化指定字段的数据
+     *
+     * @param {Array} headers 邮件头数组
+     * @param {String} fieldNames 需要处理的字段列表（冒号分隔）
+     * @param {String} skipFields 需要跳过的字段列表（冒号分隔）
+     * @return {Object} 包含规范化后的头数据和字段列表的对象
+     */
+    _relaxedHeaders = (headers, fieldNames = '', skipFields = '') => {
+        // 存储最终需要包含的字段,需要跳过的字段,字段名和对应的规范化值
+        const includedFields = new Set(), skip = new Set(), headerFields = new Map();
+
+        // 处理需要跳过的字段列表(去除空白并添加到跳过集合)
+        skipFields.toLowerCase().split(':').forEach(field => skip.add(field.trim()));
+
+        // 处理需要包含的字段，过滤掉跳过的字段(添加到包含字段集合)
+        fieldNames.toLowerCase().split(':').filter(field => !skip.has(field.trim()))
+            .forEach(field => includedFields.add(field.trim()));
+
+        // 从后向前遍历头（确保获取每个字段的最后出现值）
+        for (let i = headers.length - 1; i >= 0; i--) {
+            const { key, line } = headers[i];
+            // 只包含第一个遇到的值（从底部到顶部）
+            if (includedFields.has(key) && !headerFields.has(key)) headerFields.set(key, _relaxedHeaderLine(line));
+        }
+
+        // 构建规范化后的头数据行和字段列表
+        const headersList = [], fields = [];
+        includedFields.forEach(field => {
+            // 如果字段在头中存在，则将其添加到规范化数据中
+            if (headerFields.has(field)) fields.push(field), headersList.push(`${field}:${headerFields.get(field)}`);
+        });
+
+        // 用CRLF连接所有头行,用冒号连接字段名
+        return { headers: `${headersList.join('\r\n')}\r\n`, fieldNames: fields.join(':') };
+    },
+
+    /**
+     * 对单行头数据进行"relaxed"规范化
+     *
+     * @param {String} line 头行字符串
+     * @return {String} 规范化后的头值
+     */
+    _relaxedHeaderLine = line => {
+        const rGCOL = resetRegex(regexs.GLOBAL_CRLF_OR_LF), rGW = resetRegex(regexs.GLOBAL_WHITESPACE);
+        // 去除字段名部分,移除换行符,将连续空白压缩为单个空格,去除首尾空格
+        return line.substring(line.indexOf(':') + 1).replace(rGCOL, '').replace(rGW, ' ').trim();
+    };
+
+/**
+ * 生成DKIM签名头行
+ * >查看定义:@see {@link generateDKIMSignature}
+ * @param {Object} headers 由MessageParser解析得到的邮件头对象
+ * @param {String} bodyHash 邮件正文的Base64编码哈希值
+ * @param {Object} options DKIM配置选项
+ * @param {String} options.domainName 要进行签名的域名
+ * @param {String} options.keySelector 使用的DKIM密钥选择器
+ * @param {String} options.privateKey 用于签名的DKIM私钥
+ * @return {String} 完整的DKIM签名头行
+ */
+const generateDKIMSignature = (headers, hashAlgo, bodyHash, options = {}) => {
+    // RFC4871 #5.5中列出的默认签名头字段
+    const defaultFieldNames =
+        'From:Sender:Reply-To:Subject:Date:Message-ID:To:' +
+        'Cc:MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID:' +
+        'Content-Description:Resent-Date:Resent-From:Resent-Sender:' +
+        'Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To:References:' +
+        'List-Id:List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive',
+
+        { headerFieldNames, skipFields, domainName, keySelector, privateKey } = options,
+        fieldNames = headerFieldNames || defaultFieldNames,            // 使用选项中的头字段列表或默认列表
+        result = _relaxedHeaders(headers, fieldNames, skipFields),     // 获取经过"relaxed"规范化的头数据及字段列表
+
+        // 生成DKIM签名头（不包含签名值部分）
+        dkimHeader = _generateDKIMHeader(domainName, keySelector, result.fieldNames, hashAlgo, bodyHash);
+
+    let signer, signature;
+    result.headers += `dkim-signature:${_relaxedHeaderLine(dkimHeader)}`; // 将DKIM签名头自身添加到规范化数据中(用于生成签名)
+    // 创建签名对象，使用指定的哈希算法;更新要签名的数据（规范化后的头数据）
+    signer = createSign((`rsa-${hashAlgo}`).toUpperCase()), signer.update(result.headers);
+    try {
+        signature = signer.sign(privateKey, 'base64');                    // 使用私钥进行签名,输出Base64格式
+    } catch (E) { return false; }
+
+    const rSF = resetRegex(regexs.SIGNATURE_FOLDING);
+    return dkimHeader + signature.replace(rSF, '$&\r\n ').trim();         // 返回完整的DKIM签名头,并对长签名进行折行处理
+};
+
+export { generateDKIMSignature };

package/lib/fetch/cookies.js

@@ -0,0 +1,224 @@
+// Cookie处理模块
+const SESSION_TIMEOUT = 1800; // 会话默认超时时间：30分钟（1800秒）
+
+/**
+ * 创建一个Biskviit Cookie存储容器,用于内存中的Cookie管理
+ * >查看定义:@see {@link Cookies}
+ * @constructor
+ * @param {Object} [options] 可选的配置对象
+ */
+class Cookies {
+    constructor(options = {}) {
+        this.options = options, this.cookies = [];
+    }
+
+    // 检查主机名是否匹配Cookie域名
+    #isDomainMatch(hostname, domain) {
+        if (hostname === domain) return true; // 精确匹配
+        // 如果域名以点开头，则匹配所有子域名,否则返回false
+        return domain.startsWith('.') ? (`.${hostname}`).endsWith(domain) : false;
+    }
+
+    /**
+     * 尝试将给定的字符串解析为URL对象
+     * @param {string} str - 需要解析的URL字符串，默认为空字符串
+     * @returns {URL|boolean} 如果解析成功返回URL对象，否则返回false
+     */
+    #newURL(str = '') {
+        try {
+            return str = new URL(str);
+        } catch (e) {
+            return false;
+        }
+    }
+
+    /**
+     * 将Cookie字符串存储到Cookie存储中
+     *
+     * @param {String} cookieStr 来自'Set-Cookie:'头的值
+     * @param {String} url 当前URL
+     */
+    set(cookieStr, url) {
+        const urlObj = this.#newURL(url)
+        if (!urlObj) throw new Error('提供的URL无效');
+
+        const cookie = this.parse(cookieStr), // 解析Cookie字符串
+            { hostname, pathname } = urlObj, { domain, path, expires } = cookie;
+
+        // 当域名不存在时或域名存在但不匹配时，直接使用主机名;否则当域名存在且匹配时，保留原始值
+        cookie.domain = !domain || !this.#isDomainMatch(hostname, domain) ? hostname : domain;
+
+        if (!path) cookie.path = this.getPath(pathname);  // 如果没有设置路径，使用URL的路径
+        // 如果没有过期时间，使用会话超时时间
+        if (!expires) cookie.expires = new Date(Date.now() + Number(this.options.sessionTimeout ?? SESSION_TIMEOUT) * 1000);
+
+        return this.add(cookie); // 添加Cookie到存储
+    }
+
+    /**
+     * 获取适用于指定URL的Cookie字符串，用于'Cookie:'请求头
+     *
+     * @param {String} url 要检查的URL
+     * @returns {String} Cookie头字符串，如果没有匹配则返回空字符串
+     */
+    get(url) {
+        // 将Cookie对象转换为name=value格式,用分号和空格连接所有Cookie
+        return this.list(url).map(cookie => `${cookie.name}=${cookie.value}`).join('; ');
+    }
+
+    /**
+     * 列出适用于指定URL的所有有效Cookie对象
+     *
+     * @param {String} url 要检查的URL
+     * @returns {Array} Cookie对象数组
+     */
+    list(url) {
+        const result = [];
+        let cookie;
+
+        // 倒序遍历Cookie数组（便于删除过期Cookie）
+        for (let i = this.cookies.length - 1; i >= 0; i--) {
+            cookie = this.cookies[i];
+
+            // 检查Cookie是否过期
+            if (this.isExpired(cookie)) {
+                this.cookies.splice(i, 1);                      // 移除过期Cookie
+                continue;
+            }
+            if (this.match(cookie, url)) result.unshift(cookie); // 如果Cookie匹配URL,则将匹配的Cookie添加到结果数组开头
+        }
+
+        return result;
+    }
+
+    /**
+     * 解析来自'Set-Cookie:'头的Cookie字符串
+     *
+     * @param {String} cookieStr 来自'Set-Cookie:'头的字符串
+     * @returns {Object} Cookie对象
+     */
+    parse(cookieStr = '') {
+        const cookie = {}; // 初始化空Cookie对象
+
+        cookieStr.toString().split(';')
+            .forEach(cookiePart => {
+                // 按等号分割键值对,获取键名并规范化并获取值
+                const valueParts = cookiePart.split('='), key = valueParts.shift().trim().toLowerCase();
+                let value = valueParts.join('=').trim(), domain;
+
+                if (!key) return; // 如果键名为空则跳过
+                // 根据键名处理不同的Cookie属性
+                switch (key) {
+                    case 'expires': // 过期时间
+                        value = new Date(value);
+                        if (value.toString() !== 'Invalid Date') cookie.expires = value; // 如果日期解析失败则忽略
+                        break;
+                    case 'path':
+                        cookie.path = value;
+                        break;
+                    case 'domain': // 域名
+                        domain = value.toLowerCase();
+                        // 如果域名存在且没有前导点，则添加前导点
+                        if (domain.length && !domain.startsWith('.')) domain = `.${domain}`;
+                        cookie.domain = domain;
+                        break;
+                    case 'max-age': // 最大存活时间（秒）
+                        cookie.expires = new Date(Date.now() + (Number(value) || 0) * 1000);
+                        break;
+                    case 'secure': // 安全标志
+                        cookie.secure = true;
+                        break;
+                    case 'httponly': // 仅HTTP标志
+                        cookie.httponly = true;
+                        break;
+                    default:
+                        // 如果没有匹配的属性，则默认处理Cookie的名称和值
+                        if (!cookie.name) cookie.name = key, cookie.value = value;
+                }
+            });
+
+        return cookie;
+    }
+
+    /**
+     * 检查Cookie对象是否适用于指定URL
+     *
+     * @param {Object} cookie Cookie对象
+     * @param {String} url 要检查的URL
+     * @returns {Boolean} 如果Cookie适用于指定URL则返回true
+     */
+    match(cookie, url) {
+        const urlObj = _newURL(str)
+        if (!urlObj) return false;
+        if (!this.#isDomainMatch(urlObj.hostname, cookie.domain)) return false; // 检查主机名是否不匹配Cookie域名
+
+        const path = this.getPath(urlObj.pathname);                             // 检查路径是否匹配
+        if (!path.startsWith(cookie.path)) return false;                        // 如果路径不以Cookie路径开头，则不匹配
+        return cookie.secure && urlObj.protocol !== 'https:' ? false : true; // 如果Cookie是安全的但URL不是https，则不匹配,否则匹配
+    }
+
+    /**
+     * 添加（或更新/删除）Cookie对象到Cookie存储
+     *
+     * @param {Object} cookie 要存储的Cookie值
+     */
+    add(cookie) {
+        if (!cookie || !cookie.name) return false; // 如果Cookie无效则直接返回
+
+        // 检查是否有相同参数的Cookie（用于更新）
+        for (let i = 0; i < this.cookies.length; i++) {
+            if (this.compare(this.cookies[i], cookie)) {
+                // 检查是否需要删除Cookie（如果已过期）
+                if (this.isExpired(cookie)) {
+                    this.cookies.splice(i, 1);
+                    return false;
+                }
+
+                this.cookies[i] = cookie;           // 更新现有Cookie
+                return true;
+            }
+        }
+
+        if (!this.isExpired(cookie)) this.cookies.push(cookie); // 如果没有过期，则添加为新Cookie
+        return true;
+    }
+
+    /**
+     * 检查两个Cookie对象是否相同
+     *
+     * @param {Object} a Cookie-对象a
+     * @param {Object} b Cookie-对象b
+     * @returns {Boolean} 如果Cookie相同则返回true
+     */
+    compare(a, b) {
+        return ['name', 'path', 'domain', 'secure', 'httponly'].every(key => a[key] === b[key]);
+    }
+
+    /**
+     * 检查Cookie是否已过期
+     *
+     * @param {Object} cookie 要检查的Cookie对象
+     * @returns {Boolean} 如果Cookie已过期则返回true
+     */
+    isExpired(cookie) {
+        return !cookie.value || (cookie.expires?.getTime() < Date.now())
+    }
+
+    /**
+     * 返回URL路径参数的规范化Cookie路径
+     *
+     * @param {String} pathname 路径名
+     * @returns {String} 规范化后的路径
+     */
+    getPath(pathname) {
+        let path = pathname || '/'; // 处理空值，默认为根路径
+
+        // 直接找到最后一个斜杠的位置，保留到该位置（包含斜杠）
+        const lastIndex = path.lastIndexOf('/');
+        path = path.substring(0, lastIndex + 1);
+
+        return path.startsWith('/') ? path : `/${path}`; // 确保以/开头
+    }
+}
+
+export { Cookies };