chanjs 2.7.2 → 2.7.3

package/security/sign.js

@@ -0,0 +1,210 @@
+import crypto from "crypto";
+
+/**
+ * 加密和签名工具函数
+ * 提供安全的 AES-256-GCM 加密解密和 HMAC-SHA256 数据签名
+ *
+ * 安全改进：
+ * 1. 弃用 CryptoJS（默认用 EVP_BytesToKey 派生密钥，安全性不足）
+ * 2. 改用 Node.js 原生 crypto 模块，AES-256-GCM 提供机密性 + 完整性
+ * 3. 密钥派生用 scrypt（抗暴力破解，NIST 推荐）
+ * 4. verifySign 用 crypto.timingSafeEqual 替换 ===，防止时序攻击
+ *
+ * 兼容性说明：
+ * - 新版 AES 密文格式：base64(iv:tag:ciphertext)，与 CryptoJS 不兼容
+ * - 旧版 Cookie 失效后业务层 catch 会自动重新生成（Share.js 已处理）
+ */
+
+/**
+ * 密钥派生缓存（避免每次加解密都派生一遍）
+ * 改为 LRU：命中时先 delete 再 set，刷新访问顺序
+ */
+const keyCache = new Map();
+const KEY_CACHE_MAX = 100;
+
+/**
+ * 从用户密钥派生固定长度的 AES-256 密钥
+ * 用 scrypt 算法，参数选择 N=16384, r=8, p=1，约 100ms 派生时间，抗暴力破解
+ *
+ * 安全改进：
+ * - salt 优先用 AES_SALT 环境变量（部署期固定），不再从 secret 推导
+ * - 未设置 AES_SALT 时降级到原行为并打印警告
+ * @private
+ */
+function deriveKey(secret) {
+  if (!secret || typeof secret !== 'string') return null;
+  if (keyCache.has(secret)) {
+    // LRU 命中：先 delete 再 set，刷新到 Map 末尾
+    const cached = keyCache.get(secret);
+    keyCache.delete(secret);
+    keyCache.set(secret, cached);
+    return cached;
+  }
+
+  // salt 优先用 AES_SALT 环境变量；未配置时降级到 secret 哈希
+  const aesSalt = process.env.AES_SALT;
+  let salt;
+  if (aesSalt) {
+    salt = crypto.createHash('sha256').update(aesSalt).digest();
+  } else {
+    if (!deriveKey._warned) {
+      console.warn('[安全警告] 未配置 AES_SALT 环境变量，回退到基于 secret 的 salt，建议设置 AES_SALT');
+      deriveKey._warned = true;
+    }
+    salt = crypto.createHash('sha256').update(secret).digest();
+  }
+  const key = crypto.scryptSync(secret, salt, 32);  // AES-256 需要 32 字节密钥
+
+  // LRU 缓存上限：超过时淘汰 Map 头部（最久未访问）
+  if (keyCache.size >= KEY_CACHE_MAX) {
+    const oldestKey = keyCache.keys().next().value;
+    if (oldestKey !== undefined) keyCache.delete(oldestKey);
+  }
+  keyCache.set(secret, key);
+  return key;
+}
+
+/**
+ * AES 加密（AES-256-GCM）
+ * @param {Object|string} obj - 要加密的对象或字符串
+ * @param {string} key - 加密密钥（用户提供的密钥，会通过 scrypt 派生）
+ * @returns {string|null} 加密后的字符串（base64 编码，格式：iv:tag:ciphertext），失败时返回 null
+ * @description
+ * 使用 AES-256-GCM 算法加密数据
+ * - GCM 模式提供机密性 + 完整性校验
+ * - 每次加密生成随机 IV（12 字节），防止相同明文产生相同密文
+ * - 输出格式：base64(iv + tag + ciphertext)
+ * @example
+ * const encrypted = aesEncrypt({ id: 1, name: '张三' }, 'my-secret-key');
+ */
+export const aesEncrypt = (obj, key) => {
+  if (!key) {
+    console.error('[安全错误] AES_SALT 必须配置');
+    return null;
+  }
+  try {
+    const derivedKey = deriveKey(key);
+    if (!derivedKey) return null;
+
+    // 随机 IV（12 字节，GCM 推荐长度）
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', derivedKey, iv);
+
+    const plaintext = typeof obj === 'string' ? obj : JSON.stringify(obj);
+    const encrypted = Buffer.concat([
+      cipher.update(plaintext, 'utf8'),
+      cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();  // 16 字节认证标签
+
+    // 格式：base64(iv + tag + ciphertext)
+    return Buffer.concat([iv, tag, encrypted]).toString('base64');
+  } catch (error) {
+    console.error("AES加密失败:", error.message);
+    return null;
+  }
+};
+
+/**
+ * AES 解密（AES-256-GCM）
+ * @param {string} str - 要解密的字符串（base64 编码，格式：iv:tag:ciphertext）
+ * @param {string} key - 解密密钥
+ * @returns {string|null} 解密后的字符串，失败时返回 null
+ * @description
+ * 使用 AES-256-GCM 算法解密数据
+ * - 自动校验 GCM 认证标签，密文被篡改会抛错
+ * - 与 aesEncrypt 配对使用
+ * @example
+ * const decrypted = aesDecrypt(encryptedStr, 'my-secret-key');
+ */
+export const aesDecrypt = (str, key) => {
+  if (!key) {
+    console.error('[安全错误] AES_SALT 必须配置');
+    return null;
+  }
+  try {
+    const derivedKey = deriveKey(key);
+    if (!derivedKey) return null;
+
+    const data = Buffer.from(str, 'base64');
+    // 前 12 字节是 IV，接下来 16 字节是 GCM tag，剩下是密文
+    if (data.length < 28) return null;  // 12 + 16 最小长度
+    const iv = data.subarray(0, 12);
+    const tag = data.subarray(12, 28);
+    const ciphertext = data.subarray(28);
+
+    const decipher = crypto.createDecipheriv('aes-256-gcm', derivedKey, iv);
+    decipher.setAuthTag(tag);
+
+    const decrypted = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]);
+    return decrypted.toString('utf8');
+  } catch (error) {
+    console.error("AES解密失败:", error.message);
+    return null;
+  }
+};
+
+/**
+ * 数据签名（HMAC-SHA256）
+ * @param {Object} data - 要签名的数据对象
+ * @param {string} secret - 签名密钥
+ * @returns {string|null} 签名字符串（hex 编码），失败时返回 null
+ * @description
+ * 使用 HMAC-SHA256 算法对数据进行签名
+ * 原生 crypto 实现，与 CryptoJS.HmacSHA256 输出格式兼容（hex 字符串）
+ * @example
+ * const signature = signData({ userId: 123 }, 'my-sign-key');
+ */
+export function signData(data, secret) {
+  if (!secret) {
+    console.error('[安全错误] 签名密钥必须配置');
+    return null;
+  }
+  try {
+    const hmac = crypto.createHmac('sha256', secret);
+    hmac.update(JSON.stringify(data));
+    return hmac.digest('hex');
+  } catch (error) {
+    console.error("数据签名失败:", error.message);
+    return null;
+  }
+}
+
+/**
+ * 验证数据签名
+ * @param {Object} data - 原始数据对象
+ * @param {string} signature - 待验证的签名
+ * @param {string} secret - 签名密钥
+ * @returns {boolean} 签名是否有效
+ * @description
+ * 重新计算签名并使用 crypto.timingSafeEqual 进行常量时间比对
+ * 防止时序攻击：攻击者无法通过响应时间推断签名前缀
+ *
+ * 安全要点：
+ * 1. 两边长度不同直接返回 false（不进入 timingSafeEqual，避免越界）
+ * 2. 长度相同才用 timingSafeEqual 进行常量时间比较
+ * 3. 返回值不抛异常，只返回 true/false
+ * @example
+ * const isValid = verifySign({ userId: 123 }, signature, 'my-sign-key');
+ */
+export function verifySign(data, signature, secret) {
+  try {
+    const computedSign = signData(data, secret);
+    if (!computedSign || !signature) return false;
+
+    // 长度不同直接返回 false（timingSafeEqual 要求两边等长）
+    if (computedSign.length !== signature.length) return false;
+
+    // 常量时间比较，防止时序攻击
+    return crypto.timingSafeEqual(
+      Buffer.from(computedSign),
+      Buffer.from(String(signature))
+    );
+  } catch (error) {
+    console.error("签名验证失败:", error.message);
+    return false;
+  }
+}

package/security/xss-filter.js

@@ -0,0 +1,63 @@
+import xss from 'xss';
+
+/**
+ * XSS 过滤工具
+ * 提供跨站脚本攻击过滤功能
+ */
+
+/**
+ * 过滤 XSS 攻击代码
+ * @param {*} data - 要过滤的数据，可以是字符串、数组或对象
+ * @returns {*} 过滤后的数据
+ * @description
+ * 递归过滤数据中的所有字符串值
+ * 使用 xss 库清除危险的 HTML 和 JavaScript 代码
+ * 支持字符串、数组和对象的递归处理
+ *
+ * 安全加固（P2 #22）：
+ * 用 WeakSet 跟踪已访问对象，避免循环引用导致栈溢出
+ * - 首次遇到对象时加入 visited
+ * - 递归处理子属性时传递 visited
+ * - 遇到已访问对象直接返回（断开循环）
+ *
+ * @example
+ * const clean = filterXSS({
+ *   name: '<script>alert(1)</script>',
+ *   items: ['<img src=x onerror=alert(1)>']
+ * });
+ */
+export function filterXSS(data, visited) {
+  // 字符串：xss 过滤
+  if (typeof data === 'string') {
+    return xss(data);
+  }
+
+  // 数组：递归处理每个元素
+  if (Array.isArray(data)) {
+    // 数组本身不加入 visited（数组循环引用极少见，且会破坏数组的正常处理）
+    // 只跟踪对象的循环引用
+    return data.map(item => filterXSS(item, visited));
+  }
+
+  // 对象：递归处理每个属性
+  if (data && typeof data === 'object') {
+    // 循环引用检测
+    if (!visited) visited = new WeakSet();
+    if (visited.has(data)) {
+      // 已访问过，返回空对象断开循环（保留类型一致性）
+      return {};
+    }
+    visited.add(data);
+
+    const result = {};
+    for (const key in data) {
+      if (Object.prototype.hasOwnProperty.call(data, key)) {
+        result[key] = filterXSS(data[key], visited);
+      }
+    }
+    return result;
+  }
+
+  // 其他类型（number / boolean / null / undefined / function）：原样返回
+  return data;
+}

package/storage/cache.js

@@ -0,0 +1,258 @@
+/**
+ * incr 默认 TTL（毫秒）
+ * 用于 incr 新建 key 时自动附加过期，避免永久占用内存
+ * 与 redis.js 的 DEFAULT_INCR_TTL 保持一致
+ */
+const DEFAULT_INCR_TTL = 60 * 1000;
+
+/**
+ * LRU（最近最少使用）缓存类
+ * @class Cache
+ * @description
+ * 基于内存的 LRU 缓存，支持 TTL 和自动过期清理。
+ * 改进点：
+ * 1. 单 Map 实现 LRU（删除再插入保证顺序），避免双 Map 开销
+ * 2. 修复 TTL 续期 bug：get 时仅刷新 LRU 顺序，不再续期 TTL（避免热点 key 永不过期）
+ * 3. 默认上限 10 万条（约 20MB），可配置
+ * 4. 惰性批量清理：set 时按频率触发过期清理，不使用定时器
+ * 5. incr/incrAndExpire：自增不刷新 TTL（与 Redis 行为对齐）
+ * @example
+ * const cache = new Cache({ maxSize: 100000, defaultTTL: 60000 });
+ * cache.set('user:123', { name: '张三' }, 30000);
+ * const user = cache.get('user:123');
+ */
+class Cache {
+  /**
+   * 创建缓存实例
+   * @param {Object} [options={}] - 配置选项
+   * @param {number} [options.maxSize=100000] - 最大缓存条目数，默认 10 万条约 20MB
+   * @param {number} [options.defaultTTL=300000] - 默认过期时间（毫秒），默认 5 分钟
+   */
+  constructor(options = {}) {
+    this.map = new Map();
+    this.maxSize = options.maxSize || 100000;
+    this.defaultTTL = options.defaultTTL || 5 * 60 * 1000;
+    // 惰性清理控制
+    this._lastCleanup = Date.now();
+    this._cleanupInterval = 10 * 1000; // 最少间隔 10 秒
+    this._cleanupBatch = 200;           // 每次最多检查 200 条
+  }
+
+  /**
+   * 设置缓存值
+   * @param {string} key - 缓存键
+   * @param {*} value - 要缓存的值
+   * @param {number} [ttl=this.defaultTTL] - 过期时间（毫秒）
+   */
+  set(key, value, ttl = this.defaultTTL) {
+    this._maybeCleanup();
+
+    // 达到上限且是新 key → 淘汰 Map 头部（最久未访问）
+    if (this.map.size >= this.maxSize && !this.map.has(key)) {
+      this._evictLRU();
+    }
+
+    // 先删除再插入，保证 Map 末尾是最新访问
+    this.map.delete(key);
+    this.map.set(key, { value, expireAt: Date.now() + ttl });
+  }
+
+  /**
+   * 获取缓存值
+   * @param {string} key - 缓存键
+   * @returns {*} 缓存的值，如果键不存在或已过期则返回 null
+   * @description
+   * 仅刷新 LRU 顺序，不续期 TTL（修复旧版 bug）
+   */
+  get(key) {
+    const item = this.map.get(key);
+    if (!item) return null;
+
+    const now = Date.now();
+    if (now > item.expireAt) {
+      this.map.delete(key);
+      return null;
+    }
+
+    // LRU：删除再插入，刷新到 Map 末尾
+    this.map.delete(key);
+    this.map.set(key, item);
+    return item.value;
+  }
+
+  /**
+   * 删除缓存条目
+   */
+  del(key) {
+    return this.map.delete(key);
+  }
+
+  /**
+   * 清空所有缓存
+   */
+  clear() {
+    this.map.clear();
+  }
+
+  /**
+   * 检查键是否存在
+   * 与 get 行为对齐：命中也刷新 LRU 访问顺序
+   * 避免高频 has 查询的 key 被提前淘汰
+   */
+  has(key) {
+    const item = this.map.get(key);
+    if (!item) return false;
+    if (Date.now() > item.expireAt) {
+      this.map.delete(key);
+      return false;
+    }
+    // LRU：删除再插入，刷新到末尾
+    this.map.delete(key);
+    this.map.set(key, item);
+    return true;
+  }
+
+  /**
+   * 获取当前缓存大小（触发一次完整清理）
+   */
+  size() {
+    this._cleanupAll();
+    return this.map.size;
+  }
+
+  /**
+   * 自增，新建 key 自动附加默认 TTL
+   * @param {string} key - 缓存键
+   * @param {number} [ttlMs=DEFAULT_INCR_TTL] - 新建 key 时的 TTL（毫秒）
+   * @returns {number} 自增后的值
+   * @description
+   * - 新建 key：设置值为 1，TTL = ttlMs
+   * - 已存在 key：值 +1，**不刷新 TTL**（与 Redis INCR 行为对齐）
+   *
+   * 重要：自增不会续期 TTL，这是有意设计。
+   * Rate Limit 场景下，每个 IP 的窗口由首次请求决定，后续请求只递增不续期。
+   */
+  incr(key, ttlMs = DEFAULT_INCR_TTL) {
+    this._maybeCleanup();
+    const item = this.map.get(key);
+    const now = Date.now();
+
+    if (!item || now > item.expireAt) {
+      // 新建 key，设置默认 TTL
+      if (this.map.size >= this.maxSize && !this.map.has(key)) {
+        this._evictLRU();
+      }
+      this.map.set(key, { value: 1, expireAt: now + ttlMs });
+      return 1;
+    }
+
+    // 已存在：自增，**不刷新 TTL**（保持原 expireAt）
+    item.value = (typeof item.value === 'number' ? item.value : 0) + 1;
+    return item.value;
+  }
+
+  /**
+   * 自增并首次设置过期时间
+   * @param {string} key - 缓存键
+   * @param {number} ttlMs - TTL 毫秒
+   * @returns {number} 自增后的值
+   * @description
+   * 与 incr 区别：新建时用调用方指定的 ttlMs，而非默认 TTL
+   * - 新建 key：设置值为 1，TTL = ttlMs
+   * - 已存在 key：值 +1，**不刷新 TTL**
+   *
+   * 用于 Rate Limit 场景：第一次访问设置窗口 TTL，后续访问只递增不续期
+   */
+  incrAndExpire(key, ttlMs) {
+    this._maybeCleanup();
+    const item = this.map.get(key);
+    const now = Date.now();
+
+    if (!item || now > item.expireAt) {
+      // 新建 key，设置指定 TTL
+      if (this.map.size >= this.maxSize && !this.map.has(key)) {
+        this._evictLRU();
+      }
+      this.map.set(key, { value: 1, expireAt: now + ttlMs });
+      return 1;
+    }
+
+    // 已存在：自增，**不刷新 TTL**
+    item.value = (typeof item.value === 'number' ? item.value : 0) + 1;
+    return item.value;
+  }
+
+  /**
+   * 刷新过期时间
+   * @param {string} key - 缓存键
+   * @param {number} ttlMs - TTL 毫秒
+   * @returns {boolean} 是否设置成功
+   */
+  expire(key, ttlMs) {
+    const item = this.map.get(key);
+    if (!item || Date.now() > item.expireAt) {
+      return false;
+    }
+    item.expireAt = Date.now() + ttlMs;
+    return true;
+  }
+
+  /**
+   * 循环淘汰最久未使用的条目，直到 size < maxSize
+   * 修复旧版只淘汰 1 条导致批量插入超出上限的问题
+   * Map 的 keys().next() 返回最早插入的 key（O(1)）
+   * @private
+   */
+  _evictLRU() {
+    while (this.map.size >= this.maxSize) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey === undefined) break;
+      this.map.delete(oldestKey);
+    }
+  }
+
+  /**
+   * 惰性批量清理过期项
+   * 控制频率：每 10 秒最多清理一次
+   * 控制单轮清理量：每轮最多 1000 条，避免大缓存全量遍历阻塞事件循环
+   *
+   * 修复说明：
+   *   旧版在遇到第一个未过期条目时 break，假设 Map 按过期时间有序插入。
+   *   实际上 Map 按插入顺序遍历，与过期时间无关。
+   *   后插入但 TTL 短的条目可能先过期，导致旧版无法清理被前面长 TTL 条目挡住的过期条目。
+   *   现改为分批清理（每轮最多 1000 条），剩余的会在下次触发时继续清理。
+   * @private
+   */
+  _maybeCleanup() {
+    const now = Date.now();
+    if (now - this._lastCleanup < this._cleanupInterval) return;
+    this._lastCleanup = now;
+
+    // 分批清理，单轮最多 1000 条，避免大缓存全量遍历阻塞事件循环
+    let count = 0;
+    for (const [key, item] of this.map) {
+      if (now > item.expireAt) {
+        this.map.delete(key);
+      }
+      if (++count >= 1000) break;
+    }
+  }
+
+  /**
+   * 完整清理所有过期项
+   * 仅在调用 size() 时触发
+   * @private
+   */
+  _cleanupAll() {
+    const now = Date.now();
+    for (const [key, item] of this.map) {
+      if (now > item.expireAt) {
+        this.map.delete(key);
+      }
+    }
+  }
+}
+
+export { DEFAULT_INCR_TTL };
+export const cache = new Cache();
+export default Cache;

package/storage/index.js

@@ -0,0 +1,9 @@
+/**
+ * 存储模块 - 缓存/Redis/存储适配层
+ * - cache: 同步内存缓存（LRU + TTL）
+ * - redis: 异步 Redis 后端
+ * - store: 统一异步 API，自动选 Redis/内存 + 降级兜底
+ */
+export { cache, DEFAULT_INCR_TTL } from "./cache.js";
+export { default as RedisBackend } from "./redis.js";
+export { store } from "./store.js";