wxpay-nodejs-sdk 0.2.1 → 0.2.3

package/dist/index.js

@@ -1,12 +1,14 @@
 'use strict';
 
 var fs = require('fs');
-var crypto4 = require('crypto');
+var os = require('os');
+var crypto2 = require('crypto');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var fs__default = /*#__PURE__*/_interopDefault(fs);
-var crypto4__default = /*#__PURE__*/_interopDefault(crypto4);
+var os__default = /*#__PURE__*/_interopDefault(os);
+var crypto2__default = /*#__PURE__*/_interopDefault(crypto2);
 
 // src/core/client.ts
 var CertificateManager = class {
@@ -18,6 +20,8 @@ var CertificateManager = class {
   wxpayPublicKeyId = null;
   /** API V3 密钥 */
   apiV3Key;
+  /** 自动更新定时器 */
+  autoUpdateTimer = null;
   constructor(apiV3Key, certificates) {
     this.apiV3Key = apiV3Key;
     if (certificates) {
@@ -32,6 +36,21 @@ var CertificateManager = class {
   get serialNos() {
     return Array.from(this.certificates.keys());
   }
+  /**
+   * 获取最新的证书序列号或公钥ID
+   *
+   * 优先返回微信支付公钥ID（公钥模式），否则返回第一个平台证书序列号。
+   * 用于设置请求头 Wechatpay-Serial，告知微信支付客户端支持验签的证书。
+   *
+   * @returns 序列号字符串，无配置时返回 undefined
+   */
+  getNewestSerial() {
+    if (this.wxpayPublicKeyId) {
+      return this.wxpayPublicKeyId;
+    }
+    const keys = Array.from(this.certificates.keys());
+    return keys.length > 0 ? keys[0] : void 0;
+  }
   /**
    * 设置微信支付公钥（公钥模式）
    *
@@ -64,7 +83,7 @@ var CertificateManager = class {
       return Buffer.from(ciphertext, "base64").toString("utf-8");
     }
     try {
-      const decipher = crypto4__default.default.createDecipheriv(
+      const decipher = crypto2__default.default.createDecipheriv(
         "aes-256-gcm",
         Buffer.from(this.apiV3Key, "utf-8"),
         Buffer.from(nonce, "utf-8")
@@ -115,9 +134,63 @@ var CertificateManager = class {
     this.wxpayPublicKey = null;
     this.wxpayPublicKeyId = null;
   }
+  /**
+   * 启动自动更新
+   *
+   * 定期调用更新函数刷新平台证书。适用于生产环境的证书自动维护。
+   *
+   * @param updateFn - 证书更新函数，返回最新的证书 Map
+   * @param options - 自动更新配置选项
+   * @returns 停止更新的函数
+   *
+   * @example
+   * ```ts
+   * const manager = new CertificateManager(apiV3Key);
+   * const stop = manager.startAutoUpdate(
+   *   async () => {
+   *     const certs = await downloadCertificates();
+   *     return certs;
+   *   },
+   *   { intervalMs: 60 * 60 * 1000 }
+   * );
+   * // 稍后停止
+   * stop();
+   * ```
+   */
+  startAutoUpdate(updateFn, options) {
+    const intervalMs = options?.intervalMs ?? 60 * 60 * 1e3;
+    this.stopAutoUpdate();
+    const doUpdate = async () => {
+      try {
+        const certs = await updateFn();
+        for (const [serialNo, publicKey] of certs) {
+          this.setPublicKey(serialNo, publicKey);
+        }
+        options?.onSuccess?.(Array.from(certs.keys()));
+      } catch (error) {
+        options?.onError?.(error instanceof Error ? error : new Error(String(error)));
+      }
+    };
+    void doUpdate();
+    this.autoUpdateTimer = setInterval(() => {
+      void doUpdate();
+    }, intervalMs);
+    return () => {
+      this.stopAutoUpdate();
+    };
+  }
+  /**
+   * 停止自动更新
+   */
+  stopAutoUpdate() {
+    if (this.autoUpdateTimer) {
+      clearInterval(this.autoUpdateTimer);
+      this.autoUpdateTimer = null;
+    }
+  }
 };
 
-// src/utils/http.ts
+// src/utils/exceptions.ts
 var WxPayError = class extends Error {
   /** HTTP 状态码 */
   status;
@@ -140,7 +213,64 @@ var WxPayError = class extends Error {
   get isServerError() {
     return this.status >= 500 && this.status < 600;
   }
+  /**
+   * 判断是否为特定错误码
+   *
+   * @param code - 错误码
+   * @returns 是否匹配
+   */
+  isApiError(code) {
+    return this.detail.code === code;
+  }
+};
+var ServiceException = class extends WxPayError {
+  /** 微信支付业务错误码 */
+  errorCode;
+  /** 微信支付业务错误信息 */
+  errorMessage;
+  constructor(status, headers, detail) {
+    super(status, headers, detail);
+    this.name = "ServiceException";
+    this.errorCode = detail.code;
+    this.errorMessage = detail.message;
+  }
+};
+var HttpException = class extends WxPayError {
+  constructor(message, cause) {
+    super(0, {}, { code: "NETWORK_ERROR", message });
+    this.name = "HttpException";
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+};
+var ValidationException = class extends WxPayError {
+  constructor(message) {
+    super(0, {}, { code: "SIGN_ERROR", message });
+    this.name = "ValidationException";
+  }
 };
+var DecryptionException = class extends WxPayError {
+  constructor(message) {
+    super(0, {}, { code: "DECRYPT_ERROR", message });
+    this.name = "DecryptionException";
+  }
+};
+var MalformedMessageException = class extends WxPayError {
+  constructor(message) {
+    super(0, {}, { code: "PARSE_ERROR", message });
+    this.name = "MalformedMessageException";
+  }
+};
+
+// src/utils/http.ts
+var SDK_VERSION = "0.2.1";
+function getUserAgent() {
+  const platform = os__default.default.platform();
+  const arch = os__default.default.arch();
+  const nodeVersion = process.version;
+  return `wxpay-nodejs-sdk/${SDK_VERSION} (${platform} ${arch}) Node.js/${nodeVersion}`;
+}
 function buildUrl(base, path, params) {
   const url = new URL(path, base);
   if (params) {
@@ -170,13 +300,16 @@ function parseResponseHeaders(headers) {
   return result;
 }
 function createRequestHeaders(options) {
-  return {
+  const headers = {
     Authorization: options.authorization,
     Accept: options.accept ?? "application/json",
     "Content-Type": options.contentType ?? "application/json",
-    "User-Agent": "wxpay-nodejs-sdk/0.1.0",
-    ...options.additional
+    "User-Agent": getUserAgent()
   };
+  if (options.wechatPaySerial) {
+    headers["Wechatpay-Serial"] = options.wechatPaySerial;
+  }
+  return { ...headers, ...options.additional };
 }
 async function parseResponse(response, verify) {
   const headers = parseResponseHeaders(response.headers);
@@ -199,7 +332,7 @@ async function parseResponse(response, verify) {
         message: `HTTP ${response.status}: ${response.statusText}`
       };
     }
-    throw new WxPayError(response.status, headers, errorDetail);
+    throw new ServiceException(response.status, headers, errorDetail);
   }
   if (verify) {
     const signature = headers["wechatpay-signature"];
@@ -209,10 +342,7 @@ async function parseResponse(response, verify) {
     if (signature && timestamp && nonce && serial) {
       const valid = verify(rawBody, signature, timestamp, nonce, serial);
       if (!valid) {
-        throw new WxPayError(response.status, headers, {
-          code: "SIGN_ERROR",
-          message: "\u5E94\u7B54\u7B7E\u540D\u9A8C\u8BC1\u5931\u8D25"
-        });
+        throw new ValidationException("\u5E94\u7B54\u7B7E\u540D\u9A8C\u8BC1\u5931\u8D25");
       }
     }
   }
@@ -224,10 +354,9 @@ async function parseResponse(response, verify) {
     }
     data = parsed;
   } catch (error) {
-    throw new WxPayError(response.status, headers, {
-      code: "PARSE_ERROR",
-      message: error instanceof Error ? error.message : "\u54CD\u5E94\u6570\u636E\u89E3\u6790\u5931\u8D25"
-    });
+    throw new MalformedMessageException(
+      error instanceof Error ? error.message : "\u54CD\u5E94\u6570\u636E\u89E3\u6790\u5931\u8D25"
+    );
   }
   return {
     status: response.status,
@@ -245,7 +374,13 @@ ${body}
 `;
 }
 function sign(signString, privateKey) {
-  const signer = crypto4__default.default.createSign("RSA-SHA256");
+  if (!signString) {
+    throw new Error("\u7B7E\u540D\u4E32\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!privateKey) {
+    throw new Error("\u5546\u6237\u79C1\u94A5\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  const signer = crypto2__default.default.createSign("RSA-SHA256");
   signer.update(signString);
   signer.end();
   return signer.sign(privateKey, "base64");
@@ -254,36 +389,92 @@ function buildAuthorization(mchid, serialNo, timestamp, nonce, signature) {
   return `WECHATPAY2-SHA256-RSA2048 mchid="${mchid}",nonce_str="${nonce}",timestamp="${timestamp}",serial_no="${serialNo}",signature="${signature}"`;
 }
 function generateNonce() {
-  return crypto4__default.default.randomUUID().replace(/-/g, "");
+  return crypto2__default.default.randomUUID().replace(/-/g, "");
+}
+var RESPONSE_EXPIRED_SECONDS = 5 * 60;
+function isTimestampValid(timestamp) {
+  const responseTime = parseInt(timestamp, 10);
+  if (isNaN(responseTime)) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  return Math.abs(now - responseTime) < RESPONSE_EXPIRED_SECONDS;
 }
 function verifySignature(body, signature, timestamp, nonce, publicKey) {
+  if (!signature) {
+    throw new Error("\u7B7E\u540D\u503C(signature)\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!timestamp) {
+    throw new Error("\u65F6\u95F4\u6233(timestamp)\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!nonce) {
+    throw new Error("\u968F\u673A\u4E32(nonce)\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!publicKey) {
+    throw new Error("\u516C\u94A5(publicKey)\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!isTimestampValid(timestamp)) {
+    return false;
+  }
   const signString = `${timestamp}
 ${nonce}
 ${body}
 `;
-  const verifier = crypto4__default.default.createVerify("RSA-SHA256");
+  const verifier = crypto2__default.default.createVerify("RSA-SHA256");
   verifier.update(signString);
   verifier.end();
   return verifier.verify(publicKey, signature, "base64");
 }
 function oaepEncrypt(plaintext, publicKey) {
-  const encrypted = crypto4__default.default.publicEncrypt(
+  if (!publicKey) {
+    throw new Error("\u52A0\u5BC6\u516C\u94A5\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!plaintext) {
+    return "";
+  }
+  const encrypted = crypto2__default.default.publicEncrypt(
     {
       key: publicKey,
-      padding: crypto4__default.default.constants.RSA_PKCS1_OAEP_PADDING,
-      oaepHash: "sha256"
+      padding: crypto2__default.default.constants.RSA_PKCS1_OAEP_PADDING,
+      oaepHash: "sha1"
     },
     Buffer.from(plaintext, "utf-8")
   );
   return encrypted.toString("base64");
 }
+function oaepDecrypt(ciphertext, privateKey) {
+  if (!privateKey) {
+    throw new Error("\u89E3\u5BC6\u79C1\u94A5\u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (!ciphertext) {
+    return "";
+  }
+  const decrypted = crypto2__default.default.privateDecrypt(
+    {
+      key: privateKey,
+      padding: crypto2__default.default.constants.RSA_PKCS1_OAEP_PADDING,
+      oaepHash: "sha1"
+    },
+    Buffer.from(ciphertext, "base64")
+  );
+  return decrypted.toString("utf-8");
+}
 
 // src/core/client.ts
 var WxPayClient = class _WxPayClient {
-  /** 生产环境 API 地址 */
+  /** 生产环境 API 主域名 */
   static PRODUCTION_BASE = "https://api.mch.weixin.qq.com";
+  /** 生产环境 API 备用域名（跨城容灾） */
+  static PRODUCTION_BACKUP = "https://api2.mch.weixin.qq.com";
   /** 沙箱环境 API 地址 */
   static SANDBOX_BASE = "https://api.mch.weixin.qq.com/sandboxnew";
+  /** SDK 版本号 */
+  static SDK_VERSION = "0.2.1";
+  /** 动态 User-Agent 字符串 */
+  static USER_AGENT = (() => {
+    const platform = os__default.default.platform();
+    const arch = os__default.default.arch();
+    const nodeVersion = process.version;
+    return `wxpay-nodejs-sdk/${_WxPayClient.SDK_VERSION} (${platform} ${arch}) Node.js/${nodeVersion}`;
+  })();
   /** 商户号 */
   mchid;
   apiV3Key;
@@ -291,6 +482,7 @@ var WxPayClient = class _WxPayClient {
   privateKey;
   timeout;
   baseUrl;
+  backupUrl;
   enableResponseVerification;
   /** 平台证书管理器 */
   certificates;
@@ -301,6 +493,7 @@ var WxPayClient = class _WxPayClient {
     this.privateKey = this.resolvePrivateKey(options.privateKey);
     this.timeout = options.timeout ?? 3e4;
     this.baseUrl = options.sandbox ? _WxPayClient.SANDBOX_BASE : _WxPayClient.PRODUCTION_BASE;
+    this.backupUrl = options.sandbox ? null : _WxPayClient.PRODUCTION_BACKUP;
     this.enableResponseVerification = options.enableResponseVerification ?? true;
     this.certificates = new CertificateManager(this.apiV3Key, options.platformCertificates);
     if (options.wxpayPublicKeyId && options.wxpayPublicKey) {
@@ -372,8 +565,12 @@ var WxPayClient = class _WxPayClient {
     const headers = {
       Authorization: authorization,
       Accept: "application/json",
-      "User-Agent": "wxpay-nodejs-sdk/0.1.0"
+      "User-Agent": _WxPayClient.USER_AGENT
     };
+    const serial = this.certificates.getNewestSerial();
+    if (serial) {
+      headers["Wechatpay-Serial"] = serial;
+    }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => {
       controller.abort();
@@ -495,8 +692,12 @@ var WxPayClient = class _WxPayClient {
       Authorization: authorization,
       Accept: "application/json",
       "Content-Type": `multipart/form-data; boundary=${boundary}`,
-      "User-Agent": "wxpay-nodejs-sdk/0.1.0"
+      "User-Agent": _WxPayClient.USER_AGENT
     };
+    const serial = this.certificates.getNewestSerial();
+    if (serial) {
+      headers["Wechatpay-Serial"] = serial;
+    }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => {
       controller.abort();
@@ -537,67 +738,90 @@ var WxPayClient = class _WxPayClient {
   }
   /**
    * 通用 HTTP 请求方法
+   *
+   * 支持跨城容灾：当主域名请求失败（网络错误、超时）时，自动切换到备用域名重试。
    */
   async request(method, path, params, body, extraHeaders) {
-    const url = buildUrl(this.baseUrl, path, params);
     const bodyStr = body ? JSON.stringify(body) : "";
     const timestamp = Math.floor(Date.now() / 1e3);
     const nonce = generateNonce();
-    const urlObj = new URL(url);
-    const signPath = urlObj.pathname + urlObj.search;
-    const signString = buildSignString({
-      method: method.toUpperCase(),
-      path: signPath,
-      timestamp,
-      nonce,
-      body: bodyStr
+    const headers = createRequestHeaders({
+      authorization: "",
+      wechatPaySerial: this.certificates.getNewestSerial(),
+      additional: extraHeaders
     });
-    const signature = sign(signString, this.privateKey);
-    const authorization = buildAuthorization(
-      this.mchid,
-      this.serialNo,
-      timestamp,
-      nonce,
-      signature
-    );
-    const headers = createRequestHeaders({ authorization, additional: extraHeaders });
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => {
-      controller.abort();
-    }, this.timeout);
-    try {
-      const response = await fetch(url, {
-        method,
-        headers,
-        body: bodyStr || void 0,
-        signal: controller.signal
+    const urls = [this.baseUrl];
+    if (this.backupUrl) {
+      urls.push(this.backupUrl);
+    }
+    let lastError;
+    for (const baseUrl of urls) {
+      const url = buildUrl(baseUrl, path, params);
+      const urlObj = new URL(url);
+      const signPath = urlObj.pathname + urlObj.search;
+      const signString = buildSignString({
+        method: method.toUpperCase(),
+        path: signPath,
+        timestamp,
+        nonce,
+        body: bodyStr
       });
-      return await parseResponse(response, this.createVerifier());
-    } catch (error) {
-      if (error instanceof WxPayError) {
-        throw error;
-      }
-      if (error instanceof DOMException && error.name === "AbortError") {
-        throw new WxPayError(
-          0,
-          {},
-          {
-            code: "REQUEST_TIMEOUT",
-            message: `\u8BF7\u6C42\u8D85\u65F6 (${this.timeout}ms)`
+      const signature = sign(signString, this.privateKey);
+      headers["Authorization"] = buildAuthorization(
+        this.mchid,
+        this.serialNo,
+        timestamp,
+        nonce,
+        signature
+      );
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, this.timeout);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: bodyStr || void 0,
+          signal: controller.signal
+        });
+        return await parseResponse(response, this.createVerifier());
+      } catch (error) {
+        lastError = error;
+        const isNetworkError = !(error instanceof WxPayError) && !(error instanceof DOMException && error.name === "AbortError");
+        if (!isNetworkError || urls.indexOf(baseUrl) === urls.length - 1) {
+          if (error instanceof WxPayError) throw error;
+          if (error instanceof DOMException && error.name === "AbortError") {
+            throw new WxPayError(
+              0,
+              {},
+              {
+                code: "REQUEST_TIMEOUT",
+                message: `\u8BF7\u6C42\u8D85\u65F6 (${this.timeout}ms)`
+              }
+            );
           }
-        );
-      }
-      throw new WxPayError(
-        0,
-        {},
-        {
-          code: "NETWORK_ERROR",
-          message: error instanceof Error ? error.message : "\u7F51\u7EDC\u8BF7\u6C42\u5931\u8D25"
+          throw new WxPayError(
+            0,
+            {},
+            {
+              code: "NETWORK_ERROR",
+              message: error instanceof Error ? error.message : "\u7F51\u7EDC\u8BF7\u6C42\u5931\u8D25"
+            }
+          );
         }
-      );
-    } finally {
-      clearTimeout(timeoutId);
+      } finally {
+        clearTimeout(timeoutId);
+      }
     }
+    throw new WxPayError(
+      0,
+      {},
+      {
+        code: "NETWORK_ERROR",
+        message: lastError instanceof Error ? lastError.message : "\u7F51\u7EDC\u8BF7\u6C42\u5931\u8D25"
+      }
+    );
   }
   /**
    * 解析私钥：支持直接传入内容或文件路径
@@ -638,6 +862,117 @@ var WxPayClient = class _WxPayClient {
   }
 };
 
+// src/utils/sensitive.ts
+var sensitiveFields = /* @__PURE__ */ new Map();
+function registerSensitiveFields(typeName, fields) {
+  sensitiveFields.set(typeName, new Set(fields));
+}
+function getSensitiveFields(typeName) {
+  return sensitiveFields.get(typeName) ?? /* @__PURE__ */ new Set();
+}
+function encryptSensitiveFields(obj, typeName, publicKey) {
+  const fields = getSensitiveFields(typeName);
+  if (fields.size === 0) return obj;
+  const result = { ...obj };
+  for (const field of fields) {
+    const value = result[field];
+    if (typeof value === "string" && value.length > 0) {
+      result[field] = oaepEncrypt(value, publicKey);
+    }
+  }
+  return result;
+}
+function decryptSensitiveFields(obj, typeName, privateKey) {
+  const fields = getSensitiveFields(typeName);
+  if (fields.size === 0) return obj;
+  const result = { ...obj };
+  for (const field of fields) {
+    const value = result[field];
+    if (typeof value === "string" && value.length > 0) {
+      try {
+        result[field] = oaepDecrypt(value, privateKey);
+      } catch {
+      }
+    }
+  }
+  return result;
+}
+function encryptSensitiveFieldsInArray(arr, typeName, publicKey) {
+  return arr.map((item) => encryptSensitiveFields(item, typeName, publicKey));
+}
+function decryptSensitiveFieldsInArray(arr, typeName, privateKey) {
+  return arr.map((item) => decryptSensitiveFields(item, typeName, privateKey));
+}
+var CertificateService = class {
+  client;
+  apiV3Key;
+  certificateManager;
+  constructor(client, apiV3Key, certificateManager) {
+    this.client = client;
+    this.apiV3Key = apiV3Key;
+    this.certificateManager = certificateManager;
+  }
+  /**
+   * 下载平台证书列表
+   *
+   * 调用微信支付 /v3/certificates 接口获取当前可用的平台证书。
+   * 返回的证书内容已解密为 PEM 格式。
+   *
+   * @returns 解密后的平台证书列表
+   */
+  async downloadCertificates() {
+    const response = await this.client.get("/v3/certificates");
+    const decryptedCerts = response.data.data.map((cert) => {
+      const pem = this.decryptCertificate(cert.encryptCertificate);
+      return {
+        serialNo: cert.serialNo,
+        effectiveTime: cert.effectiveTime,
+        expireTime: cert.expireTime,
+        certificatePem: pem
+      };
+    });
+    return {
+      status: response.status,
+      headers: response.headers,
+      data: decryptedCerts
+    };
+  }
+  /**
+   * 下载并更新本地平台证书缓存
+   *
+   * 下载最新的平台证书列表，解密后自动更新 CertificateManager 中的缓存。
+   * 适用于定时更新证书的场景。
+   *
+   * @returns 更新后的证书列表
+   */
+  async downloadAndUpdate() {
+    const response = await this.downloadCertificates();
+    for (const cert of response.data) {
+      this.certificateManager.setPublicKey(cert.serialNo, cert.certificatePem);
+    }
+    return response.data;
+  }
+  /**
+   * 使用 AES-256-GCM 解密证书内容
+   *
+   * @param encrypted - 加密的证书信息
+   * @returns PEM 格式的证书内容
+   */
+  decryptCertificate(encrypted) {
+    const key = Buffer.from(this.apiV3Key, "utf-8");
+    const nonce = Buffer.from(encrypted.nonce, "utf-8");
+    const aad = Buffer.from(encrypted.associatedData, "utf-8");
+    const ciphertextBuffer = Buffer.from(encrypted.ciphertext, "base64");
+    const authTag = ciphertextBuffer.subarray(-16);
+    const encryptedData = ciphertextBuffer.subarray(0, -16);
+    const decipher = crypto2__default.default.createDecipheriv("aes-256-gcm", key, nonce);
+    decipher.setAuthTag(authTag);
+    decipher.setAAD(aad);
+    const decrypted = Buffer.concat([decipher.update(encryptedData), decipher.final()]);
+    return decrypted.toString("utf-8");
+  }
+};
+
 // src/services/jsapi.ts
 var JsapiService = class {
   client;
@@ -2428,6 +2763,9 @@ var BillService = class {
     return this.client.downloadRaw(downloadUrl);
   }
 };
+var SUPPORTED_SIGNATURE_TYPES = /* @__PURE__ */ new Set(["WECHATPAY2-SHA256-RSA2048"]);
+var DEFAULT_SIGNATURE_TYPE = "WECHATPAY2-SHA256-RSA2048";
+var SUPPORTED_ALGORITHMS = /* @__PURE__ */ new Set(["AEAD_AES_256_GCM"]);
 var CallbackHandler = class {
   apiV3Key;
   certificates;
@@ -2439,12 +2777,30 @@ var CallbackHandler = class {
    * 验证回调通知签名
    *
    * 使用微信支付平台公钥验证回调通知的签名。
+   * 支持读取 Wechatpay-Signature-Type 头识别签名类型。
    *
    * @param headers - 回调请求头
    * @param body - 回调请求体（原始 JSON 字符串）
    * @returns 签名验证是否通过
+   * @throws 如果必填参数缺失、签名类型不支持或找不到对应的证书
    */
   verifySignature(headers, body) {
+    if (!headers["wechatpay-serial"]) {
+      throw new Error("\u56DE\u8C03\u5934 wechatpay-serial \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!headers["wechatpay-signature"]) {
+      throw new Error("\u56DE\u8C03\u5934 wechatpay-signature \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!headers["wechatpay-timestamp"]) {
+      throw new Error("\u56DE\u8C03\u5934 wechatpay-timestamp \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!headers["wechatpay-nonce"]) {
+      throw new Error("\u56DE\u8C03\u5934 wechatpay-nonce \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    const signatureType = headers["wechatpay-signature-type"] ?? DEFAULT_SIGNATURE_TYPE;
+    if (!SUPPORTED_SIGNATURE_TYPES.has(signatureType)) {
+      throw new Error(`\u4E0D\u652F\u6301\u7684\u7B7E\u540D\u7C7B\u578B: ${signatureType}`);
+    }
     const serialNo = headers["wechatpay-serial"];
     const publicKey = this.certificates.getPublicKey(serialNo);
     if (!publicKey) {
@@ -2465,10 +2821,22 @@ var CallbackHandler = class {
    *
    * @param notification - 回调通知 JSON 对象
    * @returns 解密后的业务数据
-   * @throws 如果解密后的数据为空或格式无效
+   * @throws 如果通知结构无效、算法不匹配或解密失败
    */
   decryptNotification(notification) {
     const { resource } = notification;
+    if (!resource.algorithm) {
+      throw new Error("\u56DE\u8C03\u901A\u77E5 resource \u7F3A\u5C11 algorithm \u5B57\u6BB5");
+    }
+    if (!resource.ciphertext) {
+      throw new Error("\u56DE\u8C03\u901A\u77E5 resource \u7F3A\u5C11 ciphertext \u5B57\u6BB5");
+    }
+    if (!resource.nonce) {
+      throw new Error("\u56DE\u8C03\u901A\u77E5 resource \u7F3A\u5C11 nonce \u5B57\u6BB5");
+    }
+    if (!SUPPORTED_ALGORITHMS.has(resource.algorithm)) {
+      throw new Error(`\u4E0D\u652F\u6301\u7684\u52A0\u5BC6\u7B97\u6CD5: ${resource.algorithm}`);
+    }
     const plaintext = this.aesGcmDecrypt(
       resource.ciphertext,
       resource.associated_data,
@@ -2716,13 +3084,26 @@ var CallbackHandler = class {
    * @param associatedData - 附加数据（用于 AEAD 认证）
    * @param nonce - 随机串
    * @returns 解密后的明文字符串
+   * @throws 如果密文格式无效或解密失败
    */
   aesGcmDecrypt(ciphertext, associatedData, nonce) {
+    if (!ciphertext) {
+      throw new Error("\u5BC6\u6587(ciphertext)\u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (!nonce) {
+      throw new Error("\u968F\u673A\u4E32(nonce)\u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    if (this.apiV3Key.length !== 32) {
+      throw new Error("APIv3 \u5BC6\u94A5\u65E0\u6548\uFF0C\u957F\u5EA6\u5FC5\u987B\u4E3A 32 \u4E2A\u5B57\u8282");
+    }
     const key = Buffer.from(this.apiV3Key, "utf-8");
     const ciphertextBuffer = Buffer.from(ciphertext, "base64");
+    if (ciphertextBuffer.length <= 16) {
+      throw new Error("\u5BC6\u6587\u957F\u5EA6\u65E0\u6548\uFF0C\u5FC5\u987B\u5927\u4E8E 16 \u5B57\u8282\uFF08\u542B AuthTag\uFF09");
+    }
     const authTag = ciphertextBuffer.subarray(-16);
     const encryptedData = ciphertextBuffer.subarray(0, -16);
-    const decipher = crypto4__default.default.createDecipheriv("aes-256-gcm", key, Buffer.from(nonce, "utf-8"));
+    const decipher = crypto2__default.default.createDecipheriv("aes-256-gcm", key, Buffer.from(nonce, "utf-8"));
     decipher.setAuthTag(authTag);
     decipher.setAAD(Buffer.from(associatedData, "utf-8"));
     const decrypted = Buffer.concat([decipher.update(encryptedData), decipher.final()]);
@@ -3850,13 +4231,327 @@ var SecurityService = class {
     return this.client.post("/v3/security/echo", request);
   }
 };
+
+// src/services/payrollcard.ts
+var PayrollCardService = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 查询授权关系
+   *
+   * 查询商户与用户之间的微工卡授权关系。
+   *
+   * @param params - 查询参数
+   * @returns 授权关系信息
+   */
+  async queryAuthorization(params) {
+    return this.client.get("/v3/payroll-card/relations", params);
+  }
+  /**
+   * 生成预授权 token
+   *
+   * 生成微工卡预授权 token，用于后续核身操作。
+   *
+   * @param request - 预授权请求参数
+   * @returns 预授权 token 信息
+   */
+  async createToken(request) {
+    return this.client.post("/v3/payroll-card/tokens", request);
+  }
+  /**
+   * 核身预下单
+   *
+   * 创建核身预下单，获取核身参数。
+   *
+   * @param request - 核身预下单请求参数
+   * @returns 核身参数信息
+   */
+  async createAuthentication(request) {
+    return this.client.post("/v3/payroll-card/authentications", request);
+  }
+  /**
+   * 查询核身结果
+   *
+   * 根据商户请求号查询核身结果。
+   *
+   * @param outRequestNo - 商户请求号
+   * @param params - 查询参数
+   * @returns 核身结果信息
+   */
+  async queryAuthentication(outRequestNo, params) {
+    return this.client.get(
+      `/v3/payroll-card/authentications/out-request-no/${outRequestNo}`,
+      params
+    );
+  }
+  /**
+   * 发起批量转账
+   *
+   * 通过工资卡渠道发起批量转账。
+   *
+   * @param request - 批量转账请求参数
+   * @returns 批量转账结果
+   */
+  async createTransferBatch(request) {
+    return this.client.post("/v3/payroll-card/transfer-batches", request);
+  }
+};
+
+// src/services/scanandride.ts
+var ScanAndRideService = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 开通用户服务
+   *
+   * 用户授权开通刷码乘车服务。
+   *
+   * @param request - 开通服务请求参数
+   * @returns 开通结果
+   */
+  async createUserService(request) {
+    return this.client.post("/v3/qrcode/user-services", request);
+  }
+  /**
+   * 查询用户服务状态
+   *
+   * 查询用户是否已开通刷码乘车服务。
+   *
+   * @param outRequestNo - 商户请求号
+   * @param params - 查询参数
+   * @returns 用户服务状态
+   */
+  async queryUserService(outRequestNo, params) {
+    return this.client.get(`/v3/qrcode/user-services/out-request-no/${outRequestNo}`, params);
+  }
+  /**
+   * 扣费受理
+   *
+   * 发起刷码乘车扣费请求。
+   *
+   * @param request - 扣费请求参数
+   * @returns 扣费受理结果
+   */
+  async createTransaction(request) {
+    return this.client.post("/v3/qrcode/transactions", request);
+  }
+  /**
+   * 查询扣费订单
+   *
+   * 根据商户订单号查询扣费订单状态。
+   *
+   * @param outTradeNo - 商户订单号
+   * @param params - 查询参数
+   * @returns 订单信息
+   */
+  async queryTransaction(outTradeNo, params) {
+    return this.client.get(`/v3/qrcode/transactions/out-trade-no/${outTradeNo}`, params);
+  }
+};
+
+// src/services/retailstore.ts
+var RetailStoreService = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 创建门店活动
+   *
+   * @param request - 活动创建请求参数
+   * @returns 创建结果
+   */
+  async createActivity(request) {
+    return this.client.post("/v3/marketing/goldplan/retailstore/activities", request);
+  }
+  /**
+   * 查询门店活动详情
+   *
+   * @param activityId - 活动ID
+   * @returns 活动详情
+   */
+  async queryActivity(activityId) {
+    return this.client.get(`/v3/marketing/goldplan/retailstore/activities/${activityId}`);
+  }
+  /**
+   * 更新门店活动
+   *
+   * @param activityId - 活动ID
+   * @param request - 更新请求参数
+   * @returns 更新结果
+   */
+  async updateActivity(activityId, request) {
+    return this.client.patch(
+      `/v3/marketing/goldplan/retailstore/activities/${activityId}`,
+      request
+    );
+  }
+  /**
+   * 创建门店资质
+   *
+   * @param request - 资质创建请求参数
+   * @returns 创建结果
+   */
+  async createQualification(request) {
+    return this.client.post("/v3/marketing/goldplan/retailstore/qualifications", request);
+  }
+  /**
+   * 查询门店资质
+   *
+   * @param qualificationId - 资质ID
+   * @returns 资质详情
+   */
+  async queryQualification(qualificationId) {
+    return this.client.get(`/v3/marketing/goldplan/retailstore/qualifications/${qualificationId}`);
+  }
+};
+
+// src/services/goldplan.ts
+var GoldPlanService = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 查询商户零钱余额
+   *
+   * @param mchid - 商户号
+   * @returns 零钱余额信息
+   */
+  async queryBalance(mchid) {
+    return this.client.get(`/v3/merchant/fund/balance/${mchid}`);
+  }
+  /**
+   * 查询商户零钱流水
+   *
+   * @param mchid - 商户号
+   * @param params - 查询参数
+   * @returns 零钱流水列表
+   */
+  async queryFlow(mchid, params) {
+    return this.client.get(`/v3/merchant/fund/flow`, { mchid, ...params });
+  }
+  /**
+   * 查询商家零钱状态
+   *
+   * @param mchid - 商户号
+   * @returns 零钱状态信息
+   */
+  async queryStatus(mchid) {
+    return this.client.get(`/v3/merchant/fund/status/${mchid}`);
+  }
+};
+
+// src/services/lovefeast.ts
+var LoveFeastService = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 创建爱心餐品牌
+   *
+   * @param request - 品牌创建请求参数
+   * @returns 创建结果
+   */
+  async createBrand(request) {
+    return this.client.post("/v3/lovefeast/brands", request);
+  }
+  /**
+   * 查询爱心餐品牌
+   *
+   * @param brandId - 品牌ID
+   * @returns 品牌详情
+   */
+  async queryBrand(brandId) {
+    return this.client.get(`/v3/lovefeast/brands/${brandId}`);
+  }
+  /**
+   * 创建爱心餐订单
+   *
+   * @param request - 订单创建请求参数
+   * @returns 订单创建结果
+   */
+  async createOrder(request) {
+    return this.client.post("/v3/lovefeast/orders", request);
+  }
+  /**
+   * 查询爱心餐订单
+   *
+   * @param outTradeNo - 商户订单号
+   * @param params - 查询参数
+   * @returns 订单详情
+   */
+  async queryOrder(outTradeNo, params) {
+    return this.client.get(`/v3/lovefeast/orders/out-trade-no/${outTradeNo}`, params);
+  }
+};
+
+// src/services/merchant-exclusive-coupon.ts
+var MerchantExclusiveCouponService = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 创建优惠券批次
+   *
+   * @param request - 批次创建请求参数
+   * @returns 创建结果
+   */
+  async createCouponStock(request) {
+    return this.client.post("/v3/marketing/busifavor/stocks", request);
+  }
+  /**
+   * 查询优惠券批次详情
+   *
+   * @param stockId - 批次ID
+   * @returns 批次详情
+   */
+  async queryCouponStock(stockId) {
+    return this.client.get(`/v3/marketing/busifavor/stocks/${stockId}`);
+  }
+  /**
+   * 发放优惠券
+   *
+   * @param request - 发放请求参数
+   * @returns 发放结果
+   */
+  async sendCoupon(request) {
+    return this.client.post("/v3/marketing/busifavor/coupons", request);
+  }
+  /**
+   * 查询用户优惠券
+   *
+   * @param openid - 用户标识
+   * @param params - 查询参数
+   * @returns 用户优惠券列表
+   */
+  async queryUserCoupons(openid, params) {
+    return this.client.get(`/v3/marketing/busifavor/users/${openid}/coupons`, params);
+  }
+  /**
+   * 查询优惠券详情
+   *
+   * @param couponId - 优惠券ID
+   * @param params - 查询参数
+   * @returns 优惠券详情
+   */
+  async queryCoupon(couponId, params) {
+    return this.client.get(`/v3/marketing/busifavor/users/coupons/${couponId}`, params);
+  }
+};
 function generateAppPaySign(appId, timeStamp, nonceStr, prepayId, privateKey) {
   const signString = `${appId}
 ${timeStamp}
 ${nonceStr}
 prepay_id=${prepayId}
 `;
-  const signer = crypto4__default.default.createSign("RSA-SHA256");
+  const signer = crypto2__default.default.createSign("RSA-SHA256");
   signer.update(signString);
   signer.end();
   return signer.sign(privateKey, "base64");
@@ -3881,13 +4576,13 @@ ${timeStamp}
 ${nonceStr}
 prepay_id=${prepayId}
 `;
-  const signer = crypto4__default.default.createSign("RSA-SHA256");
+  const signer = crypto2__default.default.createSign("RSA-SHA256");
   signer.update(signString);
   signer.end();
   return signer.sign(privateKey, "base64");
 }
 function generateNonceStr() {
-  return crypto4__default.default.randomUUID().replace(/-/g, "");
+  return crypto2__default.default.randomUUID().replace(/-/g, "");
 }
 function buildJsapiBridgeConfig(appId, prepayId, privateKey) {
   const timeStamp = String(Math.floor(Date.now() / 1e3));
@@ -3921,7 +4616,7 @@ ${timeStamp}
 ${nonceStr}
 ${packageStr}
 `;
-  const signer = crypto4__default.default.createSign("RSA-SHA256");
+  const signer = crypto2__default.default.createSign("RSA-SHA256");
   signer.update(signString);
   signer.end();
   return signer.sign(privateKey, "base64");
@@ -4071,7 +4766,7 @@ function buildH5CouponUrl(params, signKey) {
   }
   const sortedKeys = Object.keys(signFields).sort();
   const signStr = sortedKeys.map((k) => `${k}=${signFields[k]}`).join("&") + `&key=${signKey}`;
-  const sign2 = crypto4__default.default.createHmac("sha256", signKey).update(signStr).digest("hex").toUpperCase();
+  const sign2 = crypto2__default.default.createHmac("sha256", signKey).update(signStr).digest("hex").toUpperCase();
   const urlParams = new URLSearchParams({
     stock_id: params.stock_id,
     out_request_no: params.out_request_no,
@@ -4173,7 +4868,7 @@ ${timestamp}
 ${nonceStr}
 ${packageStr}
 `;
-  const signer = crypto4__default.default.createSign("RSA-SHA256");
+  const signer = crypto2__default.default.createSign("RSA-SHA256");
   signer.update(signString);
   signer.end();
   const sign2 = signer.sign(privateKey, "base64");
@@ -4193,6 +4888,7 @@ exports.BillService = BillService;
 exports.BusinessCircleService = BusinessCircleService;
 exports.CallbackHandler = CallbackHandler;
 exports.CertificateManager = CertificateManager;
+exports.CertificateService = CertificateService;
 exports.CombineAppService = CombineAppService;
 exports.CombineH5Service = CombineH5Service;
 exports.CombineMiniProgramService = CombineMiniProgramService;
@@ -4200,19 +4896,30 @@ exports.CombineNativeService = CombineNativeService;
 exports.CombineService = CombineService;
 exports.ComplaintService = ComplaintService;
 exports.CouponService = CouponService;
+exports.DecryptionException = DecryptionException;
+exports.GoldPlanService = GoldPlanService;
 exports.H5Service = H5Service;
+exports.HttpException = HttpException;
 exports.JsapiService = JsapiService;
+exports.LoveFeastService = LoveFeastService;
+exports.MalformedMessageException = MalformedMessageException;
 exports.MedInsService = MedInsService;
 exports.MediaService = MediaService;
+exports.MerchantExclusiveCouponService = MerchantExclusiveCouponService;
 exports.MerchantTransferService = MerchantTransferService;
 exports.NativeService = NativeService;
 exports.ParkingService = ParkingService;
 exports.PartnershipService = PartnershipService;
 exports.PayGiftActivityService = PayGiftActivityService;
 exports.PayScoreService = PayScoreService;
+exports.PayrollCardService = PayrollCardService;
 exports.ProfitSharingService = ProfitSharingService;
+exports.RetailStoreService = RetailStoreService;
+exports.ScanAndRideService = ScanAndRideService;
 exports.SecurityService = SecurityService;
+exports.ServiceException = ServiceException;
 exports.SmartGuideService = SmartGuideService;
+exports.ValidationException = ValidationException;
 exports.WxPayClient = WxPayClient;
 exports.WxPayError = WxPayError;
 exports.buildAppBridgeConfig = buildAppBridgeConfig;
@@ -4236,12 +4943,19 @@ exports.buildPayScoreDetailMiniProgramBridgeConfig = buildPayScoreDetailMiniProg
 exports.buildPayScoreJsapiBridgeConfig = buildPayScoreJsapiBridgeConfig;
 exports.buildPayScoreMiniProgramBridgeConfig = buildPayScoreMiniProgramBridgeConfig;
 exports.buildSignString = buildSignString;
+exports.decryptSensitiveFields = decryptSensitiveFields;
+exports.decryptSensitiveFieldsInArray = decryptSensitiveFieldsInArray;
+exports.encryptSensitiveFields = encryptSensitiveFields;
+exports.encryptSensitiveFieldsInArray = encryptSensitiveFieldsInArray;
 exports.generateAppPaySign = generateAppPaySign;
 exports.generateNonce = generateNonce;
 exports.generateNonceStr = generateNonceStr;
 exports.generatePayScorePaySign = generatePayScorePaySign;
 exports.generatePaySign = generatePaySign;
+exports.isTimestampValid = isTimestampValid;
+exports.oaepDecrypt = oaepDecrypt;
 exports.oaepEncrypt = oaepEncrypt;
+exports.registerSensitiveFields = registerSensitiveFields;
 exports.sign = sign;
 exports.verifySignature = verifySignature;
 //# sourceMappingURL=index.js.map