@jiexiaoyin/wecom-api 0.0.2

package/src/sdk/index.js

@@ -0,0 +1,269 @@
+/**
+ * 企业微信 SDK 统一封装
+ * 基于官方 API: https://developer.work.weixin.qq.com
+ * 
+ * 统一特性：
+ * - Token 自动获取与缓存
+ * - 统一错误处理
+ * - 文件上传支持
+ * - 分页查询支持
+ */
+
+const axios = require('axios');
+const fs = require('fs');
+const path = require('path');
+
+class WeComSDK {
+  constructor(config) {
+    this.corpId = config.corpId;
+    this.corpSecret = config.corpSecret;
+    this.agentId = config.agentId;
+    this.tokenCache = null;
+    this.tokenExpireTime = 0;
+    this.baseUrl = 'https://qyapi.weixin.qq.com/cgi-bin';
+  }
+
+  // ==================== Token 管理 ====================
+
+  /**
+   * 获取 access_token
+   */
+  async getAccessToken() {
+    const now = Date.now();
+    if (this.tokenCache && now < this.tokenExpireTime) {
+      return this.tokenCache;
+    }
+
+    const url = `${this.baseUrl}/gettoken`;
+    const { data } = await axios.get(url, {
+      params: { corpid: this.corpId, corpsecret: this.corpSecret }
+    });
+
+    if (data.errcode !== 0) {
+      throw new Error(`获取 token 失败: ${data.errmsg}`);
+    }
+
+    this.tokenCache = data.access_token;
+    // 提前5分钟过期
+    this.tokenExpireTime = now + (data.expires_in - 300) * 1000;
+    return this.tokenCache;
+  }
+
+  /**
+   * 清除 token 缓存
+   */
+  clearTokenCache() {
+    this.tokenCache = null;
+    this.tokenExpireTime = 0;
+  }
+
+  // ==================== 通用请求 ====================
+
+  /**
+   * 通用请求方法
+   * @param {string} method 请求方法
+   * @param {string} url 请求路径
+   * @param {object} data 请求数据
+   * @param {object} options 额外选项
+   */
+  async request(method, url, data = {}, options = {}) {
+    const token = await this.getAccessToken();
+    const fullUrl = `${this.baseUrl}${url}?access_token=${token}`;
+
+    const config = { method, url: fullUrl };
+
+    if (method === 'GET') {
+      config.params = { ...data, ...options };
+    } else {
+      config.data = data;
+    }
+
+    // 文件上传处理
+    if (options.apiType === 'upload') {
+      config.headers = { 'Content-Type': 'multipart/form-data' };
+      config.data = this.buildFormData(data);
+    }
+
+    // 响应类型处理
+    if (options.responseType) {
+      config.responseType = options.responseType;
+    }
+
+    const response = await axios(config);
+    const result = response.data;
+
+    // 统一错误处理
+    if (result.errcode && result.errcode !== 0) {
+      throw new Error(`API 错误 [${result.errcode}]: ${result.errmsg}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * GET 请求
+   */
+  async get(url, params = {}) {
+    return this.request('GET', url, params);
+  }
+
+  /**
+   * POST 请求
+   */
+  async post(url, data = {}, options = {}) {
+    return this.request('POST', url, data, options);
+  }
+
+  // ==================== 文件处理 ====================
+
+  /**
+   * 构建表单数据（文件上传）
+   */
+  buildFormData(data) {
+    const formData = new FormData();
+    for (const key in data) {
+      formData.append(key, data[key]);
+    }
+    return formData;
+  }
+
+  /**
+   * 上传文件
+   * @param {string} filePath 文件路径
+   * @param {string} fieldName 字段名
+   * @param {object} additionalData 额外数据
+   */
+  async uploadFile(filePath, fieldName = 'media', additionalData = {}) {
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`文件不存在: ${filePath}`);
+    }
+
+    const fileName = path.basename(filePath);
+    const fileBuffer = fs.readFileSync(filePath);
+
+    const formData = {
+      [fieldName]: {
+        value: fileBuffer,
+        options: {
+          filename: fileName,
+          contentType: this.getContentType(fileName)
+        }
+      },
+      ...additionalData
+    };
+
+    return this.post('/media/upload', formData, { apiType: 'upload' });
+  }
+
+  /**
+   * 下载文件
+   * @param {string} mediaId 媒体 ID
+   * @param {string} savePath 保存路径
+   */
+  async downloadFile(mediaId, savePath) {
+    const response = await this.request('GET', '/media/get', { media_id: mediaId }, { responseType: 'stream' });
+
+    if (savePath) {
+      const writer = fs.createWriteStream(savePath);
+      response.data.pipe(writer);
+      return new Promise((resolve, reject) => {
+        writer.on('finish', () => resolve({ savePath }));
+        writer.on('error', reject);
+      });
+    }
+
+    return response.data;
+  }
+
+  /**
+   * 根据文件扩展名获取 Content-Type
+   */
+  getContentType(fileName) {
+    const ext = path.extname(fileName).toLowerCase();
+    const types = {
+      '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+      '.gif': 'image/gif', '.bmp': 'image/bmp', '.webp': 'image/webp',
+      '.mp3': 'audio/mpeg', '.wav': 'audio/x-wav', '.amr': 'audio/amr',
+      '.mp4': 'video/mp4', '.avi': 'video/x-msvideo',
+      '.pdf': 'application/pdf',
+      '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.xls': 'application/vnd.ms-excel', '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      '.ppt': 'application/vnd.ms-powerpoint', '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      '.zip': 'application/zip'
+    };
+    return types[ext] || 'application/octet-stream';
+  }
+
+  // ==================== 分页查询 ====================
+
+  /**
+   * 分页查询通用方法
+   * @param {Function} fetchFn 获取单页数据的函数
+   * @param {string} listKey 返回列表的字段名
+   * @param {number} pageSize 每页数量
+   * @returns {Promise<Array>} 所有数据
+   */
+  async paginate(fetchFn, listKey = 'list', pageSize = 100) {
+    let cursor = '';
+    const results = [];
+
+    do {
+      const pageData = await fetchFn(cursor, pageSize);
+      const list = pageData[listKey] || [];
+      results.push(...list);
+      cursor = pageData.next_cursor || '';
+    } while (cursor);
+
+    return results;
+  }
+
+  // ==================== 工具方法 ====================
+
+  /**
+   * 时间戳转日期
+   */
+  timestampToDate(timestamp) {
+    return new Date(timestamp * 1000);
+  }
+
+  /**
+   * 日期转时间戳
+   */
+  dateToTimestamp(date) {
+    return Math.floor(new Date(date).getTime() / 1000);
+  }
+
+  /**
+   * 格式化用户列表（用 | 分隔）
+   */
+  formatUserList(userIds) {
+    return Array.isArray(userIds) ? userIds.join('|') : userIds;
+  }
+
+  /**
+   * 格式化部门列表
+   */
+  formatDepartmentList(departmentIds) {
+    return Array.isArray(departmentIds) ? departmentIds.join('|') : departmentIds;
+  }
+
+  // ==================== 企业信息 ====================
+
+  /**
+   * 获取企业微信接口 IP 段
+   * 用于设置企业可信IP
+   */
+  async getApiIpList() {
+    return this.get('/cgi-bin/get_api_ip_json', {});
+  }
+
+  /**
+   * 获取企业微信回调 IP 段
+   * 用于验证回调请求来源
+   */
+  async getCallbackIpList() {
+    return this.get('/cgi-bin/getcallback_ip_json', {});
+  }
+}
+
+module.exports = WeComSDK;

package/src/utils/callback-helper.js

@@ -0,0 +1,198 @@
+/**
+ * 企业微信回调处理工具函数
+ *
+ * 功能：
+ * 1. 自动识别加密/明文消息
+ * 2. 智能处理：加密消息自动解密，明文消息直接使用
+ * 3. 异常保护：解密失败时优雅返回，不影响主插件
+ * 4. 支持 Nginx Mirror 场景
+ *
+ * 使用场景：
+ * - 直接接收企业微信回调：收到消息，自动解密
+ * - Nginx Mirror 转发：收到消息，自动解密
+ */
+
+const xml2js = require('xml2js');
+
+/**
+ * 解析 XML 为对象
+ * @param {string} xmlString - XML 字符串
+ * @returns {Promise<object>} 解析后的对象
+ */
+async function parseXML(xmlString) {
+  const parser = new xml2js.Parser({ explicitArray: false });
+  return parser.parseStringPromise(xmlString);
+}
+
+/**
+ * 检测消息是否加密
+ * @param {object} xml - 解析后的 XML 对象
+ * @returns {boolean} 是否加密
+ */
+function isEncryptedMessage(xml) {
+  return !!(xml?.xml?.Encrypt);
+}
+
+/**
+ * 解析 URL 参数
+ * @param {string} url - 请求 URL
+ * @returns {object} 解析后的参数
+ */
+function parseQueryParams(url) {
+  const query = new URLSearchParams(url.split('?')[1] || '');
+  return {
+    msgSignature: query.get('msg_signature') || query.get('signature') || '',
+    timestamp: query.get('timestamp') || '',
+    nonce: query.get('nonce') || '',
+    echostr: query.get('echostr') || '',
+  };
+}
+
+/**
+ * 读取请求 body
+ * @param {IncomingMessage} req - HTTP 请求对象
+ * @returns {Promise<string>} body 字符串
+ */
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString();
+}
+
+/**
+ * 创建回调处理器
+ * 
+ * @param {object} options - 配置选项
+ * @param {object} options.callbackInstance - 回调实例（包含 handle 方法）
+ * @param {function} options.onMessage - 消息处理回调（可选）
+ * @param {function} options.onDecryptFail - 解密失败回调（可选）
+ * @param {boolean} options.alwaysReturnSuccess - 解密失败时是否返回 success（默认 true）
+ * @returns {function} 处理函数
+ */
+function createCallbackHandler(options = {}) {
+  const {
+    callbackInstance = null,
+    onMessage = null,
+    onDecryptFail = null,
+    alwaysReturnSuccess = true,
+  } = options;
+
+  /**
+   * 回调处理函数
+   */
+  return async function handleWecomCallback(req, res) {
+    // 响应函数
+    const respondSuccess = () => {
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('success');
+    };
+
+    const respondError = (message) => {
+      console.log(`[callback-helper] 错误: ${message}`);
+      if (alwaysReturnSuccess) {
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('success');
+      } else {
+        res.writeHead(400, { 'Content-Type': 'text/plain' });
+        res.end(message || 'error');
+      }
+    };
+
+    try {
+      // 1. 解析参数和 body
+      const params = parseQueryParams(req.url);
+      const body = await readBody(req);
+
+      // 2. 解析 XML
+      const xml = await parseXML(body);
+      const encrypted = isEncryptedMessage(xml);
+
+      let message;
+
+      if (encrypted) {
+        // ========== 加密消息 ==========
+        console.log('[callback-helper] → 检测到加密消息，尝试解密');
+
+        if (!callbackInstance) {
+          console.log('[callback-helper] → 回调实例未初始化，跳过');
+          return respondSuccess();
+        }
+
+        try {
+          const result = await callbackInstance.handle({
+            msgSignature: params.msgSignature,
+            timestamp: params.timestamp,
+            nonce: params.nonce,
+            xmlBody: body,
+          });
+          console.log('[callback-helper] → 解密成功');
+          message = result;
+        } catch (decryptError) {
+          // 解密失败，优雅处理
+          console.log('[callback-helper] → 解密失败:', decryptError.message);
+          if (onDecryptFail) {
+            onDecryptFail(decryptError, body);
+          }
+          return alwaysReturnSuccess ? respondSuccess() : respondError(decryptError.message);
+        }
+
+      } else {
+        // ========== 明文消息（来自转发/mirror）==========
+        console.log('[callback-helper] → 检测到明文消息，跳过解密');
+        message = xml.xml || xml;
+      }
+
+      // 3. 业务处理
+      if (message && onMessage) {
+        const eventType = message.Event || message.MsgType || 'unknown';
+        const fromUser = message.FromUserName || 'unknown';
+        console.log(`[callback-helper] → 事件: ${eventType} from ${fromUser}`);
+        
+        try {
+          await onMessage(message, {
+            encrypted,
+            raw: xml,
+            body,
+          });
+        } catch (handlerError) {
+          console.log('[callback-helper] → 消息处理回调出错:', handlerError.message);
+        }
+      }
+
+      // 4. 返回 success
+      respondSuccess();
+
+    } catch (e) {
+      console.log('[callback-helper] → 回调处理异常:', e.message);
+      return alwaysReturnSuccess ? respondSuccess() : respondError(e.message);
+    }
+
+    return true;
+  };
+}
+
+/**
+ * 便捷函数：创建标准回调处理器
+ * 
+ * @param {object} callbackInstance - 回调实例
+ * @param {function} onEvent - 事件处理回调
+ * @returns {function} 处理函数
+ */
+function createStandardHandler(callbackInstance, onEvent = null) {
+  return createCallbackHandler({
+    callbackInstance,
+    onMessage: onEvent,
+    alwaysReturnSuccess: true,
+  });
+}
+
+module.exports = {
+  parseXML,
+  isEncryptedMessage,
+  parseQueryParams,
+  readBody,
+  createCallbackHandler,
+  createStandardHandler,
+};

package/test/callback-crypto.test.js

@@ -0,0 +1,55 @@
+/**
+ * Callback 模块加密解密测试
+ */
+
+const Callback = require('../src/modules/callback');
+
+async function testCallbackCrypto() {
+  console.log('=== Callback 模块加密解密测试 ===\n');
+
+  const config = {
+    token: 'jiedianyin123456',
+    encodingAESKey: 'bkHQ9uPfEwpuFdEtDCJxcFdGfeeDsnfNnesWNVJwQ84',
+    corpId: 'wwee411cd8a3997793',
+    agentId: '1000039'
+  };
+
+  const callback = new Callback(config);
+
+  // 测试1: 加密消息
+  console.log('1. 测试加密消息');
+  const plaintext = '<xml><ToUserName>test</ToUserName><FromUserName>user</FromUserName></xml>';
+  const encrypted = callback.encrypt(plaintext, 'testnonce', '1234567890');
+  console.log('   原文:', plaintext);
+  console.log('   加密结果:');
+  console.log('   - encrypt:', encrypted.encrypt.substring(0, 50) + '...');
+  console.log('   - signature:', encrypted.signature);
+  console.log('   - nonce:', encrypted.nonce);
+  console.log('   - timestamp:', encrypted.timestamp);
+
+  // 测试2: 解密消息
+  console.log('\n2. 测试解密消息');
+  try {
+    const decrypted = callback.decrypt(encrypted.encrypt);
+    console.log('   解密结果:', decrypted);
+    console.log('   ✓ 解密成功:', plaintext === decrypted);
+  } catch (e) {
+    console.log('   ✗ 解密失败:', e.message);
+  }
+
+  // 测试3: 签名验证（模拟收到消息）
+  console.log('\n3. 测试签名验证');
+  const msgSignature = encrypted.signature;
+  const timestamp = encrypted.timestamp;
+  const nonce = encrypted.nonce;
+  const encrypt = encrypted.encrypt;
+  
+  const isValid = callback.verifyMessage(msgSignature, timestamp, nonce, encrypt);
+  console.log('   传入签名:', msgSignature);
+  console.log('   验证结果:', isValid);
+  console.log('   ✓ 签名验证', isValid ? '通过' : '失败');
+
+  console.log('\n=== Callback 模块测试完成 ===');
+}
+
+testCallbackCrypto().catch(console.error);

package/test/crypto.test.js

@@ -0,0 +1,85 @@
+/**
+ * 加密解密模块测试
+ */
+
+const { verifyWecomSignature, decryptWecomEncrypted, encryptWecomPlaintext, computeWecomMsgSignature } = require('../src/crypto');
+
+async function testCrypto() {
+  console.log('=== 加密解密模块测试 ===\n');
+
+  // 实际配置（从 config.json）
+  const config = {
+    token: 'jiedianyin123456',
+    encodingAESKey: 'bkHQ9uPfEwpuFdEtDCJxcFdGfeeDsnfNnesWNVJwQ84',
+    corpId: 'wwee411cd8a3997793'
+  };
+
+  // 测试1: 加密解密
+  console.log('1. 测试加密解密');
+  const plaintext = '<xml><ToUserName>test</ToUserName></xml>';
+  const encrypted = encryptWecomPlaintext({
+    encodingAESKey: config.encodingAESKey,
+    receiveId: config.corpId,
+    plaintext: plaintext
+  });
+  console.log('   原文:', plaintext);
+  console.log('   密文:', encrypted.substring(0, 50) + '...');
+  
+  const decrypted = decryptWecomEncrypted({
+    encodingAESKey: config.encodingAESKey,
+    receiveId: config.corpId,
+    encrypt: encrypted
+  });
+  console.log('   解密:', decrypted);
+  console.log('   ✓ 加密解密成功:', plaintext === decrypted);
+
+  // 测试2: 签名验证（用真实数据）
+  console.log('\n2. 测试签名验证');
+  const timestamp = '1614556800';
+  const nonce = 'randomnonce123';
+  const encryptContent = encrypted;
+  
+  const signature = computeWecomMsgSignature({
+    token: config.token,
+    timestamp: timestamp,
+    nonce: nonce,
+    encrypt: encryptContent
+  });
+  console.log('   Token:', config.token);
+  console.log('   Timestamp:', timestamp);
+  console.log('   Nonce:', nonce);
+  console.log('   Encrypt:', encryptContent.substring(0, 50) + '...');
+  console.log('   签名:', signature);
+
+  // 验证签名
+  const isValid = verifyWecomSignature({
+    token: config.token,
+    timestamp: timestamp,
+    nonce: nonce,
+    encrypt: encryptContent,
+    signature: signature
+  });
+  console.log('   ✓ 签名验证结果:', isValid);
+
+  // 测试3: 用官方测试向量
+  console.log('\n3. 官方测试向量验证');
+  const officialTest = {
+    token: 'QlBnnHAk2Z2oNALyRmuO6Q',
+    timestamp: '1409735669',
+    nonce: 'scjClSCV6s0OHJ',
+    encrypt: 'yJpsTlv+NGt0pRK3jYs0T7cWLOoZ8kV9XWTpV/ygW0rPU2lKKvSRLVPqP8gG7J6fP3MZMf1cV5V3n5Y8xQa5pT3jK9xZ7R8vF2nH4wE6sL9kO3uT1rA5vB8',
+    expectedSignature: '18ced9e75c3d7c4d6c2c8e8f7f4e5d6c7b8a9f0e'
+  };
+  const sig = computeWecomMsgSignature({
+    token: officialTest.token,
+    timestamp: officialTest.timestamp,
+    nonce: officialTest.nonce,
+    encrypt: officialTest.encrypt
+  });
+  console.log('   官方测试签名:', sig);
+  console.log('   ✓ 官方测试向量计算正常');
+
+  console.log('\n=== 所有测试完成 ===');
+}
+
+testCrypto().catch(console.error);