@jiexiaoyin/wecom-api 0.0.2

package/src/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.message;
+        } 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/src/config.cjs

@@ -0,0 +1,286 @@
+/**
+ * 企业微信插件配置管理
+ * 
+ * 支持多环境配置、敏感信息分离、便捷部署
+ * 
+ * 配置文件优先级：
+ * 1. .env 文件（敏感信息）
+ * 2. config.{env}.json（环境配置）
+ * 3. config.json（默认配置）
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class Config {
+  constructor(options = {}) {
+    this.env = options.env || process.env.NODE_ENV || 'development';
+    this.configDir = options.configDir || './';
+    this.envPrefix = options.envPrefix || 'WECOM_';
+    
+    // 加载配置
+    this._config = this._loadConfig(options);
+  }
+
+  /**
+   * 加载配置
+   */
+  _loadConfig(options) {
+    let config = {};
+    
+    // 1. 加载默认配置
+    config = this._mergeConfig(config, 'config.json');
+    
+    // 2. 加载环境配置
+    if (this.env !== 'development') {
+      config = this._mergeConfig(config, `config.${this.env}.json`);
+    }
+    
+    // 3. 加载代码传入的配置
+    if (Object.keys(options).length > 0) {
+      config = { ...config, ...options };
+    }
+    
+    // 4. 从环境变量加载（覆盖其他配置）
+    config = this._loadFromEnv(config);
+    
+    // 5. 加载 .env 文件（敏感信息）
+    config = this._loadEnvFile(config);
+    
+    return config;
+  }
+
+  /**
+   * 合并配置文件
+   */
+  _mergeConfig(config, filename) {
+    const filePath = path.join(this.configDir, filename);
+    if (fs.existsSync(filePath)) {
+      try {
+        const fileConfig = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return { ...config, ...fileConfig };
+      } catch (e) {
+        console.warn(`配置文件 ${filename} 加载失败:`, e.message);
+      }
+    }
+    return config;
+  }
+
+  /**
+   * 从环境变量加载
+   */
+  _loadFromEnv(config) {
+    const envMappings = {
+      'CORP_ID': 'corpId',
+      'CORP_SECRET': 'corpSecret', 
+      'AGENT_ID': 'agentId',
+      'TOKEN': 'token',
+      'ENCODING_AES_KEY': 'encodingAESKey',
+      'CALLBACK_URL': 'callbackUrl'
+    };
+
+    for (const [envKey, configKey] of Object.entries(envMappings)) {
+      const envValue = process.env[`${this.envPrefix}${envKey}`];
+      if (envValue !== undefined) {
+        config[configKey] = envValue;
+      }
+    }
+    return config;
+  }
+
+  /**
+   * 加载 .env 文件
+   */
+  _loadEnvFile(config) {
+    const envPath = path.join(this.configDir, '.env');
+    if (fs.existsSync(envPath)) {
+      try {
+        const envContent = fs.readFileSync(envPath, 'utf8');
+        const envVars = this._parseEnv(envContent);
+        
+        const envMappings = {
+          'WECOM_CORP_ID': 'corpId',
+          'WECOM_CORP_SECRET': 'corpSecret',
+          'WECOM_AGENT_ID': 'agentId',
+          'WECOM_TOKEN': 'token',
+          'WECOM_ENCODING_AES_KEY': 'encodingAESKey'
+        };
+
+        for (const [envKey, configKey] of Object.entries(envMappings)) {
+          if (envVars[envKey]) {
+            config[configKey] = envVars[envKey];
+          }
+        }
+      } catch (e) {
+        console.warn('.env 文件加载失败:', e.message);
+      }
+    }
+    return config;
+  }
+
+  /**
+   * 解析 .env 内容
+   */
+  _parseEnv(content) {
+    const result = {};
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#')) {
+        const [key, ...valueParts] = trimmed.split('=');
+        if (key && valueParts.length > 0) {
+          result[key.trim()] = valueParts.join('=').trim();
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 获取配置值
+   */
+  get(key, defaultValue = null) {
+    return this.config[key] || defaultValue;
+  }
+
+  /**
+   * 设置配置值
+   */
+  set(key, value) {
+    this.config[key] = value;
+  }
+
+  /**
+   * 获取完整配置
+   */
+  getAll() {
+    return { ...this.config };
+  }
+
+  /**
+   * 获取企业基本配置（用于 SDK）
+   */
+  getCorpConfig() {
+    return {
+      corpId: this.get('corpId'),
+      corpSecret: this.get('corpSecret'),
+      agentId: this.get('agentId')
+    };
+  }
+
+  /**
+   * 获取回调配置
+   */
+  getCallbackConfig() {
+    return {
+      token: this.get('token'),
+      encodingAESKey: this.get('encodingAESKey'),
+      corpId: this.get('corpId'),
+      callbackUrl: this.get('callbackUrl')
+    };
+  }
+
+  /**
+   * 验证配置
+   */
+  validate() {
+    const required = ['corpId', 'corpSecret'];
+    const missing = required.filter(key => !this.get(key));
+    return { valid: missing.length === 0, missing };
+  }
+
+  /**
+   * 导出安全配置（不含敏感信息）
+   */
+  exportSafeConfig() {
+    const safe = { ...this.config };
+    delete safe.corpSecret;
+    delete safe.token;
+    delete safe.encodingAESKey;
+    return safe;
+  }
+
+  /**
+   * 创建配置文件
+   */
+  static init(options = {}) {
+    const configDir = options.configDir || './';
+    
+    // 1. 创建 config.json
+    const defaultConfig = {
+      env: "development",
+      callbackUrl: "https://your-domain.com/wecom/callback",
+      maxHistorySize: 5000
+    };
+    fs.writeFileSync(
+      path.join(configDir, 'config.json'),
+      JSON.stringify(defaultConfig, null, 2)
+    );
+    
+    // 2. 创建 .env.example
+    const envExample = `# 企业微信配置
+# 请复制此文件为 .env 并填入真实值
+
+WECOM_CORP_ID=your_corp_id
+WECOM_CORP_SECRET=your_corp_secret
+WECOM_AGENT_ID=your_agent_id
+WECOM_TOKEN=your_callback_token
+WECOM_ENCODING_AES_KEY=your_encoding_aes_key
+`;
+    fs.writeFileSync(
+      path.join(configDir, '.env.example'),
+      envExample
+    );
+    
+    // 3. 创建 .gitignore
+    const gitignore = `# 敏感配置
+.env
+config.local.json
+*.local.json
+
+# 日志
+logs/
+*.log
+
+# 事件记录
+events_*.json
+`;
+    fs.writeFileSync(
+      path.join(configDir, '.gitignore'),
+      gitignore
+    );
+    
+    console.log(`
+✅ 配置文件已创建：
+
+1. config.json       - 基础配置（可提交到代码仓库）
+2. .env.example      - 环境变量示例（可提交）
+3. .gitignore        - Git 忽略配置
+
+请执行以下步骤：
+
+1. 复制 .env.example 为 .env
+   cp .env.example .env
+
+2. 编辑 .env 填入真实配置
+   vim .env
+
+3. 开始使用
+   npm run callback
+`);
+  }
+}
+
+// 导出类和便捷函数
+module.exports = Config;
+module.exports.Config = Config;
+
+// 便捷函数：加载配置
+module.exports.loadConfig = function(options = {}) {
+  const config = new Config(options);
+  return config.getAll();
+};
+
+// ESM 导出
+module.exports.__esModule = true;
+module.exports.default = Config;