befly-weixin-utils 1.1.0

package/README.md

@@ -0,0 +1,9 @@
+# befly-weixin-utils
+
+微信通用底层能力包，提供 HTTP 请求、RSA 签名验签、AES-GCM 解密、字段转换、基础 hash/nonce/url/cache 工具和微信消息 XML 解析/生成。
+
+```js
+import { createNonceStr, parseWeixinXml, sha1Hex, signSha256WithRsa } from "befly-weixin-utils";
+```
+
+XML 工具只覆盖微信消息 XML 场景，不实现完整 XML 标准。

package/aesgcm.js

@@ -0,0 +1,11 @@
+import crypto from "node:crypto";
+
+export function decryptAes256Gcm(options) {
+    const ciphertextBuffer = Buffer.from(options.ciphertext, "base64");
+    const authTag = ciphertextBuffer.subarray(ciphertextBuffer.length - 16);
+    const data = ciphertextBuffer.subarray(0, ciphertextBuffer.length - 16);
+    const decipher = crypto.createDecipheriv("aes-256-gcm", options.key, options.nonce);
+    decipher.setAuthTag(authTag);
+    decipher.setAAD(Buffer.from(options.associatedData));
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString("utf8");
+}

package/cache.js

@@ -0,0 +1,3 @@
+export function getSafeExpiresIn(expiresIn, reserveSeconds = 100, defaultSeconds = 7200) {
+    return expiresIn && expiresIn > reserveSeconds ? expiresIn - reserveSeconds : defaultSeconds;
+}

package/config.js

@@ -0,0 +1,18 @@
+export function validateConfigFields(config, fields, moduleName) {
+    const missingFields = [];
+
+    for (const field of fields) {
+        if (!config[field]) {
+            missingFields.push(field);
+        }
+    }
+
+    if (missingFields.length > 0) {
+        throw new Error(`${moduleName}配置缺少必填字段: ${missingFields.join(", ")}`, {
+            cause: null,
+            code: "validation",
+            subsystem: "weixin",
+            operation: "validateConfigFields"
+        });
+    }
+}

package/hash.js

@@ -0,0 +1,5 @@
+export function sha1Hex(value) {
+    const hasher = new Bun.CryptoHasher("sha1");
+    hasher.update(value);
+    return hasher.digest("hex");
+}

package/http.js

@@ -0,0 +1,123 @@
+function sleep(ms) {
+    return new Promise(function (resolve) {
+        setTimeout(resolve, ms);
+    });
+}
+
+function shouldRetry(response) {
+    return [408, 429, 500, 502, 503, 504].includes(response.status);
+}
+
+function normalizeHeaders(headers) {
+    const result = {};
+    headers.forEach(function (value, key) {
+        result[String(key).toLowerCase()] = value;
+    });
+    return result;
+}
+
+async function fetchWithRetry(url, requestOptions, options = {}) {
+    const retryCount = options.retryCount ?? 3;
+    const timeoutMs = options.timeoutMs ?? 30000;
+    let lastError = null;
+    let lastResponse = null;
+
+    for (let attempt = 1; attempt <= retryCount; attempt += 1) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(function () {
+            controller.abort();
+        }, timeoutMs);
+
+        try {
+            const finalOptions = Object.assign({}, requestOptions, {
+                signal: controller.signal
+            });
+            const response = await fetch(url, finalOptions);
+            clearTimeout(timeoutId);
+
+            if (response.ok || !shouldRetry(response)) {
+                return response;
+            }
+
+            lastResponse = response;
+            if (attempt < retryCount) {
+                const delay = 1000 * attempt;
+                options.logger?.warn?.({
+                    msg: "请求返回可重试状态码，准备重试",
+                    url: url,
+                    status: response.status,
+                    attempt: attempt,
+                    maxRetries: retryCount,
+                    delayMs: delay
+                });
+                await sleep(delay);
+            }
+        } catch (error) {
+            clearTimeout(timeoutId);
+            lastError = error;
+            if (attempt < retryCount) {
+                const delay = 1000 * attempt;
+                options.logger?.warn?.({
+                    msg: error.name === "AbortError" ? "请求超时，准备重试" : "请求失败，准备重试",
+                    url: url,
+                    attempt: attempt,
+                    maxRetries: retryCount,
+                    delayMs: delay,
+                    error: error.message
+                });
+                await sleep(delay);
+            }
+        }
+    }
+
+    if (lastResponse) {
+        return lastResponse;
+    }
+    throw (
+        lastError ||
+        new Error("请求失败，已达最大重试次数", {
+            cause: null,
+            code: "runtime",
+            subsystem: "weixin",
+            operation: "fetchWithRetry"
+        })
+    );
+}
+
+export async function requestJson(url, options, logger) {
+    const response = await fetchWithRetry(url, options, {
+        logger: logger
+    });
+    const responseHeaders = normalizeHeaders(response.headers);
+
+    if (response.status === 204) {
+        return {
+            status: 204,
+            ok: true,
+            data: {},
+            rawBody: "",
+            responseHeaders: responseHeaders
+        };
+    }
+
+    const rawBody = await response.text();
+    return {
+        status: response.status,
+        ok: response.ok,
+        data: rawBody ? JSON.parse(rawBody) : {},
+        rawBody: rawBody,
+        responseHeaders: responseHeaders
+    };
+}
+
+export async function requestArrayBuffer(url, options, logger) {
+    const response = await fetchWithRetry(url, options, {
+        logger: logger
+    });
+    return {
+        status: response.status,
+        ok: response.ok,
+        data: await response.arrayBuffer(),
+        responseHeaders: normalizeHeaders(response.headers)
+    };
+}

package/index.js

@@ -0,0 +1,10 @@
+export { decryptAes256Gcm } from "./aesgcm.js";
+export { getSafeExpiresIn } from "./cache.js";
+export { validateConfigFields } from "./config.js";
+export { sha1Hex } from "./hash.js";
+export { requestJson, requestArrayBuffer } from "./http.js";
+export { createNonceStr } from "./nonce.js";
+export { signSha256WithRsa, verifySha256WithRsa, buildWechatpayAuthorization } from "./rsa.js";
+export { deepTransformKeys } from "./transform.js";
+export { normalizeUrlWithoutHash } from "./url.js";
+export { parseWeixinXml, buildWeixinXml, escapeXml, cdata } from "./xml.js";

package/nonce.js

@@ -0,0 +1,10 @@
+export function createNonceStr(length = 16) {
+    const chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    let result = "";
+
+    for (let index = 0; index < length; index += 1) {
+        result += chars[Math.floor(Math.random() * chars.length)];
+    }
+
+    return result;
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+    "name": "befly-weixin-utils",
+    "version": "1.1.0",
+    "private": false,
+    "description": "Befly Weixin Utils - 微信通用工具能力",
+    "keywords": [
+        "befly",
+        "utils",
+        "wechat",
+        "weixin"
+    ],
+    "homepage": "https://chensuiyi.me",
+    "license": "Apache-2.0",
+    "author": "chensuiyi <bimostyle@qq.com>",
+    "files": [
+        "aesgcm.js",
+        "cache.js",
+        "config.js",
+        "hash.js",
+        "http.js",
+        "index.js",
+        "nonce.js",
+        "README.md",
+        "rsa.js",
+        "transform.js",
+        "url.js",
+        "xml.js",
+        "package.json"
+    ],
+    "type": "module",
+    "exports": {
+        ".": {
+            "import": "./index.js",
+            "default": "./index.js"
+        },
+        "./aesgcm": {
+            "import": "./aesgcm.js",
+            "default": "./aesgcm.js"
+        },
+        "./config": {
+            "import": "./config.js",
+            "default": "./config.js"
+        },
+        "./cache": {
+            "import": "./cache.js",
+            "default": "./cache.js"
+        },
+        "./hash": {
+            "import": "./hash.js",
+            "default": "./hash.js"
+        },
+        "./http": {
+            "import": "./http.js",
+            "default": "./http.js"
+        },
+        "./nonce": {
+            "import": "./nonce.js",
+            "default": "./nonce.js"
+        },
+        "./rsa": {
+            "import": "./rsa.js",
+            "default": "./rsa.js"
+        },
+        "./transform": {
+            "import": "./transform.js",
+            "default": "./transform.js"
+        },
+        "./url": {
+            "import": "./url.js",
+            "default": "./url.js"
+        },
+        "./xml": {
+            "import": "./xml.js",
+            "default": "./xml.js"
+        }
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org"
+    },
+    "engines": {
+        "bun": ">=1.3.0"
+    }
+}

package/rsa.js

@@ -0,0 +1,13 @@
+import crypto from "node:crypto";
+
+export function signSha256WithRsa(content, privateKey) {
+    return crypto.createSign("RSA-SHA256").update(content).sign(privateKey, "base64");
+}
+
+export function verifySha256WithRsa(content, signature, publicKey) {
+    return crypto.createVerify("RSA-SHA256").update(content).verify(publicKey, signature, "base64");
+}
+
+export function buildWechatpayAuthorization(options) {
+    return `WECHATPAY2-SHA256-RSA2048 mchid="${options.mchId}",nonce_str="${options.nonceStr}",timestamp="${options.timestamp}",signature="${options.signature}",serial_no="${options.serialNo}"`;
+}

package/transform.js

@@ -0,0 +1,72 @@
+function camelCase(input) {
+    const normalized = String(input)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+
+    if (!normalized) {
+        return "";
+    }
+
+    const words = normalized.split(" ").map(function (part) {
+        return part.toLowerCase();
+    });
+
+    return (
+        words[0] +
+        words
+            .slice(1)
+            .map(function (part) {
+                return part.charAt(0).toUpperCase() + part.slice(1);
+            })
+            .join("")
+    );
+}
+
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+
+export function deepTransformKeys(data, mode = "camel") {
+    const transformKey =
+        mode === "camel"
+            ? camelCase
+            : function (key) {
+                  return key;
+              };
+    const visited = new WeakSet();
+
+    function transform(value) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+
+        if (Array.isArray(value)) {
+            if (visited.has(value)) {
+                return value;
+            }
+            visited.add(value);
+            const result = value.map(transform);
+            visited.delete(value);
+            return result;
+        }
+
+        if (isPlainObject(value)) {
+            if (visited.has(value)) {
+                return value;
+            }
+            visited.add(value);
+            const result = {};
+            for (const [key, val] of Object.entries(value)) {
+                result[transformKey(key)] = transform(val);
+            }
+            visited.delete(value);
+            return result;
+        }
+
+        return value;
+    }
+
+    return transform(data);
+}

package/url.js

@@ -0,0 +1,9 @@
+export function normalizeUrlWithoutHash(rawUrl) {
+    try {
+        const targetUrl = new URL(String(rawUrl || "").trim());
+        targetUrl.hash = "";
+        return targetUrl.toString();
+    } catch {
+        return "";
+    }
+}

package/xml.js

@@ -0,0 +1,215 @@
+function decodeXmlText(value) {
+    return String(value)
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&")
+        .replace(/&apos;/g, "'")
+        .replace(/&quot;/g, '"');
+}
+
+function assignNodeValue(target, key, value) {
+    if (Object.hasOwn(target, key)) {
+        if (Array.isArray(target[key])) {
+            target[key].push(value);
+            return;
+        }
+        target[key] = [target[key], value];
+        return;
+    }
+
+    target[key] = value;
+}
+
+function skipIgnoredMarkup(rawXml, startIndex) {
+    let index = startIndex;
+
+    while (index < rawXml.length) {
+        while (/\s/.test(rawXml[index])) {
+            index += 1;
+        }
+
+        if (rawXml.startsWith("<?", index)) {
+            const declarationEnd = rawXml.indexOf("?>", index);
+            if (declarationEnd < 0) {
+                throw new Error("XML 声明未闭合", {
+                    cause: null,
+                    code: "validation",
+                    subsystem: "weixinXml",
+                    operation: "skipIgnoredMarkup"
+                });
+            }
+            index = declarationEnd + 2;
+            continue;
+        }
+
+        if (rawXml.startsWith("<!--", index)) {
+            const commentEnd = rawXml.indexOf("-->", index);
+            if (commentEnd < 0) {
+                throw new Error("XML 注释未闭合", {
+                    cause: null,
+                    code: "validation",
+                    subsystem: "weixinXml",
+                    operation: "skipIgnoredMarkup"
+                });
+            }
+            index = commentEnd + 3;
+            continue;
+        }
+
+        return index;
+    }
+
+    return index;
+}
+
+function parseNode(rawXml, startIndex) {
+    const openEnd = rawXml.indexOf(">", startIndex);
+    if (openEnd < 0) {
+        throw new Error("XML 开始标签不完整", {
+            cause: null,
+            code: "validation",
+            subsystem: "weixinXml",
+            operation: "parseNode"
+        });
+    }
+
+    const tagName = rawXml
+        .slice(startIndex + 1, openEnd)
+        .trim()
+        .split(/\s+/)[0];
+    if (!tagName || tagName.startsWith("/")) {
+        throw new Error("XML 标签格式不正确", {
+            cause: null,
+            code: "validation",
+            subsystem: "weixinXml",
+            operation: "parseNode"
+        });
+    }
+
+    let index = openEnd + 1;
+    let text = "";
+    const children = {};
+    let hasChild = false;
+
+    while (index < rawXml.length) {
+        index = skipIgnoredMarkup(rawXml, index);
+
+        if (rawXml.startsWith("<![CDATA[", index)) {
+            const cdataEnd = rawXml.indexOf("]]>", index);
+            if (cdataEnd < 0) {
+                throw new Error("XML CDATA 未闭合", {
+                    cause: null,
+                    code: "validation",
+                    subsystem: "weixinXml",
+                    operation: "parseNode"
+                });
+            }
+            text += rawXml.slice(index + 9, cdataEnd);
+            index = cdataEnd + 3;
+            continue;
+        }
+
+        if (rawXml.startsWith(`</${tagName}>`, index)) {
+            index += tagName.length + 3;
+            return {
+                key: tagName,
+                value: hasChild ? children : decodeXmlText(text.trim()),
+                index: index
+            };
+        }
+
+        if (rawXml[index] === "<") {
+            const child = parseNode(rawXml, index);
+            hasChild = true;
+            assignNodeValue(children, child.key, child.value);
+            index = child.index;
+            continue;
+        }
+
+        const nextTagIndex = rawXml.indexOf("<", index);
+        if (nextTagIndex < 0) {
+            throw new Error("XML 结束标签缺失", {
+                cause: null,
+                code: "validation",
+                subsystem: "weixinXml",
+                operation: "parseNode"
+            });
+        }
+        text += rawXml.slice(index, nextTagIndex);
+        index = nextTagIndex;
+    }
+
+    throw new Error("XML 标签未闭合", {
+        cause: null,
+        code: "validation",
+        subsystem: "weixinXml",
+        operation: "parseNode"
+    });
+}
+
+export function parseWeixinXml(rawXml) {
+    const normalized = String(rawXml || "").trim();
+    if (!normalized) {
+        throw new Error("parseWeixinXml 输入必须是非空字符串", {
+            cause: null,
+            code: "validation",
+            subsystem: "weixinXml",
+            operation: "parseWeixinXml"
+        });
+    }
+
+    const startIndex = skipIgnoredMarkup(normalized, 0);
+    if (normalized[startIndex] !== "<") {
+        throw new Error("XML 根节点缺失", {
+            cause: null,
+            code: "validation",
+            subsystem: "weixinXml",
+            operation: "parseWeixinXml"
+        });
+    }
+    const node = parseNode(normalized, startIndex);
+    return node.key === "xml" && Object.prototype.toString.call(node.value) === "[object Object]" ? node.value : node.value;
+}
+
+export function escapeXml(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+
+export function cdata(value) {
+    return `<![CDATA[${String(value ?? "").replace(/\]\]>/g, "]]]]><![CDATA[>")}]]>`;
+}
+
+function buildNode(key, value) {
+    if (Array.isArray(value)) {
+        return value
+            .map(function (item) {
+                return buildNode(key, item);
+            })
+            .join("");
+    }
+
+    if (value && Object.prototype.toString.call(value) === "[object Object]") {
+        const body = Object.entries(value)
+            .map(function ([childKey, childValue]) {
+                return buildNode(childKey, childValue);
+            })
+            .join("");
+        return `<${key}>${body}</${key}>`;
+    }
+
+    return `<${key}>${cdata(value)}</${key}>`;
+}
+
+export function buildWeixinXml(data) {
+    const body = Object.entries(data || {})
+        .map(function ([key, value]) {
+            return buildNode(key, value);
+        })
+        .join("");
+    return `<xml>${body}</xml>`;
+}