chanjs 2.7.4 → 2.7.5

package/middleware/waf.js

@@ -1,259 +1,236 @@
-import crypto from 'crypto';
+import crypto from "crypto";
 import { getIp } from "../utils/ip.js";
 import { checkKeywords } from "../security/checker.js";
 import { filterXSS } from "../security/xss-filter.js";
 import { createRateLimitMiddleware } from "../security/rate-limit.js";
 import { store } from "../storage/store.js";
+import { CODE_BLOCKED } from "../response/code.js";
+import logger from "../utils/logger.js";
 
-/**
- * Web应用防火墙（WAF）中间件
- * 改进点：
- * 1. 封禁状态存服务端（Map+TTL 或 Redis），按 IP+UA 维度
- *    - 彻底废弃 Cookie/localStorage 标记方案（旧版可被任意绕过）
- * 2. 命中恶意关键词后封禁一段时间（默认 30 分钟，可配置）
- * 3. 支持配置阈值：连续命中 N 次后封禁
- * 4. 安全响应头补充 X-Frame-Options / HSTS 等
- * 5. 通过 store 适配层：Redis 启用时走 Redis，否则走内存，运行时异常自动降级
- */
-
-// 封禁状态 Redis Key 前缀
-const BLOCK_KEY_PREFIX = 'waf:block:';
-// 封禁命中次数 Redis Key 前缀
-const STRIKE_KEY_PREFIX = 'waf:strike:';
+const BLOCK_KEY_PREFIX = "waf:block:";
+const STRIKE_KEY_PREFIX = "waf:strike:";
 
-/**
- * 路径白名单 - 这些路径不会被 WAF 检查
- */
+// 放行路径白名单
 const WAF_PATH_WHITELIST = [
-  "/.well-known/appspecific/", // Chrome DevTools
-  "/.well-known/change-password", // 密码管理
-  "/favicon.ico", // 浏览器自动请求
-  "/robots.txt", // 搜索引擎爬虫
-  "/llms.txt", // AI引擎爬虫
-  "/sitemap.xml", // 站点地图
+  "/.well-known/appspecific/",
+  "/.well-known/change-password",
+  "/favicon.ico",
+  "/robots.txt",
+  "/llms.txt",
+  "/sitemap.xml",
 ];
 
-/**
- * 可信 IP 白名单 - 这些 IP 跳过限流和封禁
- * 本机回环 + RFC 1918 三大私有网段，避免开发和内网环境被误限
- */
-const TRUSTED_IPS = new Set(['127.0.0.1', '::1', '0.0.0.0']);
+const TRUSTED_IPS = new Set(["127.0.0.1", "::1"]);
+
+const DEFAULT_BLOCK = {
+  BLOCK_DURATION: 30 * 60 * 1000,
+  STRIKE_THRESHOLD: 3,
+  STRIKE_WINDOW: 60 * 60 * 1000,
+};
 
 /**
- * 检查 IP 是否可信（本机回环或 RFC 1918 内网）
- * RFC 1918 私有网段：
- *   10.0.0.0/8        (10.x.x.x)
- *   172.16.0.0/12     (172.16.x.x ~ 172.31.x.x)
- *   192.168.0.0/16    (192.168.x.x)
+ * 判断内网/回环可信IP
  */
-function isTrustedIp(ip) {
+const isTrustedIp = ip => {
   if (!ip) return false;
   if (TRUSTED_IPS.has(ip)) return true;
-  // 10.x.x.x
-  if (ip.startsWith('10.')) return true;
-  // 192.168.x.x
-  if (ip.startsWith('192.168.')) return true;
-  // 172.16.x.x ~ 172.31.x.x
-  if (ip.startsWith('172.')) {
-    const second = parseInt(ip.split('.')[1], 10);
-    if (second >= 16 && second <= 31) return true;
+  if (ip.startsWith("10.") || ip.startsWith("192.168.")) return true;
+  if (ip.startsWith("172.")) {
+    const seg = Number(ip.split(".")[1]);
+    return seg >= 16 && seg <= 31;
   }
   return false;
-}
+};
 
 /**
- * 检查路径是否在白名单中
+ * 路径白名单匹配
  */
-function isWhitelistedPath(path) {
-  return WAF_PATH_WHITELIST.some(whitelistPath =>
-    path.startsWith(whitelistPath) || path === whitelistPath
-  );
-}
+const isWhitelistedPath = path => WAF_PATH_WHITELIST.some(p => path === p || path.startsWith(p));
 
 /**
- * 生成 IP+UA 维度的标识（sha256 摘要，避免 UA 中特殊字符影响 Key）
- * @param {string} ip - 客户端 IP
- * @param {string} ua - User-Agent
- * @returns {string} 32 位十六进制摘要
+ * IP+UA指纹 sha256(前32位)
  */
-function buildFingerprint(ip, ua) {
-  return crypto
-    .createHash('sha256')
-    .update(`${ip}|${ua || ''}`)
-    .digest('hex')
-    .slice(0, 32);
-}
+const buildFingerprint = (ip, ua = "") =>
+  crypto.createHash("sha256").update(`${ip}|${ua}`).digest("hex").slice(0, 32);
 
 /**
- * 创建 WAF 中间件
- * @private
- * @param {Object} wafConfig - WAF 配置对象
+ * 覆盖Express5只读req.query
  */
-function createWafMiddleware(wafConfig) {
-  const rateLimitMiddleware = createRateLimitMiddleware(wafConfig.rateLimit);
+const overrideQuery = (req, cleanQuery) => {
+  Object.defineProperty(req, "query", {
+    value: cleanQuery,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+};
 
-  // 封禁配置（默认 30 分钟，命中 3 次恶意关键词后封禁）
-  const blockConfig = wafConfig.block || {};
-  const BLOCK_DURATION = blockConfig.duration || 30 * 60 * 1000; // 30 分钟
-  const STRIKE_THRESHOLD = blockConfig.strikeThreshold || 3;       // 命中 3 次封禁
-  const STRIKE_WINDOW = blockConfig.strikeWindow || 60 * 60 * 1000; // 1 小时内累计
+/**
+ * 统一 WAF 拦截响应
+ */
+const respondWaf = (res, status, msg, data) =>
+  res.status(status).json({ code: CODE_BLOCKED, success: false, msg, data });
+
+/**
+ * 关键词命中计数+封禁逻辑
+ */
+async function handleStrike(fingerprint, clientIp, keyword, blockCfg) {
+  const strikeKey = `${STRIKE_KEY_PREFIX}${fingerprint}`;
+  const strikes = await store.incrAndExpire(strikeKey, blockCfg.STRIKE_WINDOW);
+
+  if (strikes >= blockCfg.STRIKE_THRESHOLD) {
+    const blockKey = `${BLOCK_KEY_PREFIX}${fingerprint}`;
+    await store.set(blockKey, { ip: clientIp, reason: keyword, expireAt: Date.now() + blockCfg.BLOCK_DURATION }, blockCfg.BLOCK_DURATION);
+    logger.error(`[WAF封禁] IP:${clientIp} 累计命中:${strikes}次 封禁${blockCfg.BLOCK_DURATION / 60000}分钟`);
+    return { blocked: true, strikes };
+  }
+  return { blocked: false, strikes };
+}
+
+/** 执行限流，返回是否已响应 */
+const runRateLimit = (rateLimit, req, res) =>
+  new Promise(rateLimit.bind(null, req, res, r)).then(() => res.headersSent);
+
+/**
+ * 前置WAF中间件（body前）
+ */
+const createWafMiddleware = wafConfig => {
+  const rateLimit = createRateLimitMiddleware(wafConfig.rateLimit);
+  const blockCfg = { ...DEFAULT_BLOCK, ...wafConfig.block };
 
   return async (req, res, next) => {
     try {
-      if (!wafConfig.enabled) {
+      if (!wafConfig.enabled) return next();
+
+      const clientIp = getIp(req);
+      const path = req.path || "";
+      const ua = req.headers["user-agent"] || "";
+      const fp = buildFingerprint(clientIp, ua);
+      const whitePath = isWhitelistedPath(path);
+
+      // 可信IP直接放行，仅做query XSS过滤
+      if (isTrustedIp(clientIp)) {
+        if (req.query && Object.keys(req.query).length) overrideQuery(req, filterXSS(req.query));
         return next();
       }
 
-      const clientIp = getIp(req);
+      // 限流
+      if (await runRateLimit(rateLimit, req, res)) return;
 
-      // 可信 IP（本机/内网）仅跳过限流和封禁状态检查（硬约束：避免误限内网）
-      // 但仍执行关键词检查和 XSS 过滤，防止 X-Forwarded-For 伪造内网 IP 绕过 WAF（S-09 修复点）
-      const isTrusted = isTrustedIp(clientIp);
-
-      const requestPath = req.path || "";
-      const userAgent = req.headers['user-agent'] || '';
-      const fingerprint = buildFingerprint(clientIp, userAgent);
-
-      // 安全响应头
-      res.setHeader("X-Content-Type-Options", "nosniff");
-      res.setHeader("Content-Security-Policy", "frame-ancestors 'self'");
-      res.setHeader("X-Frame-Options", "DENY");
-
-      // 可信 IP 跳过封禁状态检查（避免误封内网）；非可信 IP 才查封禁状态
-      if (!isTrusted && !isWhitelistedPath(requestPath)) {
-        const blockKey = `${BLOCK_KEY_PREFIX}${fingerprint}`;
-        const blocked = await store.get(blockKey);
-
-        if (blocked) {
-          const remaining = Math.ceil((blocked.expireAt - Date.now()) / 60000);
-          console.error(`[WAF 封禁拦截] IP:${clientIp} UA:${userAgent.slice(0, 50)} 剩余:${remaining}分钟`);
-          return res.status(403).json({
-            code: 403,
-            success: false,
-            msg: '您的访问已被限制，请稍后再试',
-            retryAfter: Math.ceil(BLOCK_DURATION / 1000),
-          });
-        }
+      // 已封禁直接拦截
+      const blockInfo = await store.get(`${BLOCK_KEY_PREFIX}${fp}`);
+      if (blockInfo) {
+        logger.error(`[WAF拦截封禁] IP:${clientIp} UA:${ua.slice(0, 50)}`);
+        return respondWaf(res, 403, "检测到恶意访问，您的访问已被限制", { retryAfter: Math.ceil(blockCfg.BLOCK_DURATION / 1000) });
       }
 
-      // 可信 IP 跳过限流（避免误限内网）；非可信 IP 才执行限流
-      if (!isTrusted) {
-        await new Promise((resolve) => {
-          rateLimitMiddleware(req, res, resolve);
-        });
-        // 如果限流中间件已经响应（429），不再继续
-        if (res.headersSent) return;
+      // 白名单路径跳过关键词检测
+      if (whitePath) {
+        if (req.query && Object.keys(req.query).length) overrideQuery(req, filterXSS(req.query));
+        return next();
       }
 
-      // 收集待检查文本：路径 + query + body
-      let checkText = requestPath;
-      if (req.query && Object.keys(req.query).length > 0) {
-        const queryStr = Object.entries(req.query)
-          .map(([k, v]) => `${k}=${v}`)
-          .join(" ");
+      // 路径+query拼接检测恶意关键词
+      let checkText = path;
+      if (Object.keys(req.query ?? {}).length) {
+        const queryStr = Object.entries(req.query).map(([k, v]) => `${k}=${v}`).join(" ");
         checkText += ` ${queryStr}`;
       }
+      const hit = checkKeywords(checkText);
+      if (hit) {
+        const { keyword, category } = hit;
+        logger.error(`[WAF拦截-URL] IP:${clientIp} Path:${path} Key:${keyword} Type:${category}`);
+        const { blocked, strikes } = await handleStrike(fp, clientIp, keyword, blockCfg);
+        if (blocked) return respondWaf(res, 403, "检测到恶意访问，您的访问已被限制", { retryAfter: Math.ceil(blockCfg.BLOCK_DURATION / 1000) });
+        return respondWaf(res, 403, "检测到非法内容，请求已被拦截", { strikes, threshold: blockCfg.STRIKE_THRESHOLD });
+      }
 
-      let bodyText = "";
-      const contentType = req.headers["content-type"]?.toLowerCase() || "";
-      const isMultipart = contentType.includes("multipart/form-data");
-
-      if (!isMultipart && req.body) {
-        try {
-          // 先判断 body 长度再决定是否序列化，避免不必要的 CPU 消耗
-          const bodyStr = typeof req.body === "string" ? req.body : JSON.stringify(req.body);
-          if (bodyStr.length < 10000) {
-            bodyText = ` ${bodyStr}`;
-          }
-        } catch (e) {
-          console.error(`[WAF 警告] body序列化失败 | IP:${clientIp} 错误:${e.message}`);
-        }
+      // query XSS净化
+      try {
+        if (req.query && Object.keys(req.query).length) overrideQuery(req, filterXSS(req.query));
+      } catch (e) {
+        logger.error(`[WAF警告] query过滤失败 IP:${clientIp} Err:${e.message}`);
       }
 
-      const fullText = checkText + bodyText;
+      next();
+    } catch (err) {
+      logger.error(`[WAF前置异常] IP:${getIp(req)} Msg:${err.message}`, err.stack);
+      return respondWaf(res, 403, "安全检查异常，请求被拒绝");
+    }
+  };
+};
 
-      // 关键词检查（仅对非白名单路径）
-      if (!isWhitelistedPath(requestPath)) {
-        const matched = checkKeywords(fullText);
+/**
+ * 已登录用户的管理接口路径前缀（跳过 body 关键词检测，避免误杀富文本/代码内容）
+ */
+const BODY_CHECK_SKIP_PREFIXES = ["/cms/", "/base/", "/member/", "/book/", "/oss/", "/vip/"];
 
-        if (matched) {
-          const { category, keyword } = matched;
-          console.error(`[WAF 拦截] IP:${clientIp} 路径:${requestPath} 关键词:${keyword} 类别:${category}`);
+/**
+ * Body层WAF中间件（body解析后）
+ */
+const createWafBodyMiddleware = wafConfig => {
+  const blockCfg = { ...DEFAULT_BLOCK, ...wafConfig.block };
 
-          // 记录命中次数，达到阈值则封禁
-          const strikeKey = `${STRIKE_KEY_PREFIX}${fingerprint}`;
-          const strikes = await store.incrAndExpire(strikeKey, STRIKE_WINDOW);
+  return async (req, res, next) => {
+    try {
+      if (!wafConfig.enabled) return next();
+      const path = req.path || "";
+      if (isWhitelistedPath(path)) return next();
 
-          if (strikes >= STRIKE_THRESHOLD) {
-            // 封禁：写入封禁状态，TTL = BLOCK_DURATION
-            const blockKey = `${BLOCK_KEY_PREFIX}${fingerprint}`;
-            await store.set(blockKey, { ip: clientIp, reason: keyword, expireAt: Date.now() + BLOCK_DURATION }, BLOCK_DURATION);
-            console.error(`[WAF 封禁触发] IP:${clientIp} 命中次数:${strikes} 封禁时长:${BLOCK_DURATION / 60000}分钟`);
+      const clientIp = getIp(req);
+      const contentType = req.headers["content-type"]?.toLowerCase() || "";
+      // 上传文件跳过body文本检测
+      if (contentType.includes("multipart/form-data")) return next();
+      // 空body直接放行
+      if (!req.body || (typeof req.body === "object" && !Object.keys(req.body).length)) return next();
 
-            return res.status(403).json({
-              code: 403,
-              success: false,
-              msg: '检测到恶意访问，您的访问已被限制',
-              retryAfter: Math.ceil(BLOCK_DURATION / 1000),
-            });
-          }
+      // 已登录用户的管理接口：跳过关键词检测（富文本/代码内容会误杀），仅做 XSS 过滤
+      const isAuthedAdmin = req.user?.uid && BODY_CHECK_SKIP_PREFIXES.some(p => path.startsWith(p));
 
-          // 未达阈值，仅拦截本次请求
-          return res.status(403).json({
-            code: 403,
-            success: false,
-            msg: '检测到非法内容，请求已被拦截',
-            data: { strikes, threshold: STRIKE_THRESHOLD },
-          });
+      if (!isAuthedAdmin) {
+        // 序列化body文本，截断1w字符防绕过
+        let bodyText = "";
+        try {
+          bodyText = (typeof req.body === "string" ? req.body : JSON.stringify(req.body)).slice(0, 10000);
+        } catch (e) {
+          logger.error(`[WAF警告] body序列化失败 IP:${clientIp} Err:${e.message}`);
         }
-      }
 
-      // XSS 过滤
-      try {
-        if (req.query && typeof req.query === 'object') {
-          const filteredQuery = filterXSS(req.query);
-          Object.keys(req.query).forEach(key => delete req.query[key]);
-          Object.assign(req.query, filteredQuery);
+        // body关键词检测拦截
+        if (bodyText) {
+          const hit = checkKeywords(bodyText);
+          if (hit) {
+            const { keyword, category } = hit;
+            const fp = buildFingerprint(clientIp, req.headers["user-agent"] || "");
+            logger.error(`[WAF拦截-Body] IP:${clientIp} Path:${path} Key:${keyword} Type:${category}`);
+            const { blocked, strikes } = await handleStrike(fp, clientIp, keyword, blockCfg);
+            if (blocked) return respondWaf(res, 403, "检测到恶意访问，您的访问已被限制", { retryAfter: Math.ceil(blockCfg.BLOCK_DURATION / 1000) });
+            return respondWaf(res, 403, "检测到非法内容，请求已被拦截", { strikes, threshold: blockCfg.STRIKE_THRESHOLD });
+          }
         }
+      }
 
-        if (req.body && typeof req.body === 'object') {
-          req.body = filterXSS(req.body);
-        }
+      // body XSS过滤
+      try {
+        if (typeof req.body === "object") req.body = filterXSS(req.body);
       } catch (e) {
-        console.error(`[WAF 警告] XSS过滤失败 | IP:${clientIp} 错误:${e.message}`);
+        logger.error(`[WAF警告] body过滤失败 IP:${clientIp} Err:${e.message}`);
       }
 
       next();
-    } catch (error) {
-      console.error(`[WAF 异常] IP:${getIp(req)} 错误:${error.message}`, error.stack);
-      // 异常时拒绝请求，避免 WAF 故障时被绕过（fail-closed）
-      return res.status(403).json({
-        code: 403,
-        success: false,
-        msg: '安全检查异常，请求被拒绝',
-      });
+    } catch (err) {
+      logger.error(`[WAF Body异常] IP:${getIp(req)} Msg:${err.message}`);
+      return respondWaf(res, 403, "安全检查异常，请求被拒绝");
     }
   };
-}
+};
 
 /**
- * 设置 WAF 中间件
- * @param {Object} app - Express 应用实例
- * @param {Object} config - WAF 配置对象
- * @param {boolean} config.enabled - 是否启用 WAF
- * @param {Object} config.rateLimit - 限流配置
- * @param {Object} [config.block] - 封禁配置
- * @param {number} [config.block.duration=1800000] - 封禁时长（毫秒），默认 30 分钟
- * @param {number} [config.block.strikeThreshold=3] - 命中恶意关键词几次后封禁
- * @param {number} [config.block.strikeWindow=3600000] - 命中累计窗口（毫秒）
- * @example
- * waf(app, {
- *   enabled: true,
- *   rateLimit: { windowMs: 60000, max: 100 },
- *   block: { duration: 1800000, strikeThreshold: 3, strikeWindow: 3600000 }
- * });
+ * 注册WAF前置中间件（body前）
  */
-export const waf = function (app, config) {
-  const middleware = createWafMiddleware(config);
-  app.use(middleware);
-};
+export const waf = (app, config) => app.use(createWafMiddleware(config));
+
+/**
+ * 注册WAF Body中间件（body后）
+ */
+export const wafBody = (app, config) => app.use(createWafBodyMiddleware(config));

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.7.4",
+  "version": "2.7.5",
   "description": "chanjs基于express5 纯js研发的轻量级mvc框架。",
   "main": "index.js",
   "module": "index.js",
@@ -32,8 +32,15 @@
     "morgan": "^1.10.1",
     "mysql2": "^3.22.3",
     "serve-favicon": "^2.5.1",
-    "ws": "^8.18.0",
     "xss": "^1.0.15",
     "ioredis": "^5.4.6"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   }
 }

package/response/code.js

@@ -0,0 +1,73 @@
+/**
+ * 业务状态码统一规范：与HTTP状态码解耦，0为成功，分段划分错误域
+ */
+
+// 业务码-默认提示文案映射
+export const CODE = Object.freeze({
+  // 成功
+  0: "操作成功",
+  // 1xxx 通用业务错误
+  1001: "认证失败",
+  1002: "令牌已过期",
+  1003: "权限不足",
+  1004: "资源不存在",
+  1005: "资源已存在",
+  1006: "参数无效",
+  1007: "参数缺失",
+  1008: "业务处理失败",
+  1009: "请求过于频繁",
+  1010: "登录设备异常",
+  1011: "访问已被限制",
+  // 5xxx 系统错误
+  5001: "系统内部错误",
+  5002: "服务繁忙，请稍后再试",
+  // 6xxx 数据库错误
+  6001: "数据库连接失败",
+  6002: "数据库访问被拒绝",
+  6003: "存在关联数据，操作失败",
+  6004: "数据库字段错误",
+  6005: "数据重复，违反唯一性约束",
+  6006: "目标表不存在",
+  6007: "数据库操作超时",
+  6008: "数据库语法错误，请检查查询语句",
+  6009: "数据库连接已关闭，请重试",
+});
+
+// 语义化常量（框架内直接引用，避免硬编码数字）
+export const CODE_OK = 0;
+export const CODE_AUTH_FAILED = 1001;
+export const CODE_TOKEN_EXPIRED = 1002;
+export const CODE_FORBIDDEN = 1003;
+export const CODE_NOT_FOUND = 1004;
+export const CODE_CONFLICT = 1005;
+export const CODE_PARAM_INVALID = 1006;
+export const CODE_PARAM_MISSING = 1007;
+export const CODE_BUSINESS_FAIL = 1008;
+export const CODE_RATE_LIMIT = 1009;
+export const CODE_DEVICE_ERROR = 1010;
+export const CODE_BLOCKED = 1011;
+export const CODE_SYSTEM_ERROR = 5001;
+export const CODE_SERVICE_BUSY = 5002;
+export const CODE_DB_CONNECTION_ERROR = 6001;
+export const CODE_DB_ACCESS_DENIED = 6002;
+export const CODE_DB_OPERATION_TIMEOUT = 6007;
+
+// 数据库原生错误标识 → 业务码映射
+export const DB_ERROR = Object.freeze({
+  ECONNREFUSED: 6001,
+  ER_ACCESS_DENIED_ERROR: 6002,
+  ER_ROW_IS_REFERENCED_2: 6003,
+  ER_BAD_FIELD_ERROR: 6004,
+  ER_DUP_ENTRY: 6005,
+  ER_NO_SUCH_TABLE: 6006,
+  ETIMEOUT: 6007,
+  ER_TABLE_EXISTS_ERROR: 1005,
+});
+
+/**
+ * 根据业务码获取默认提示文案
+ * @param {number} code 业务状态码
+ * @param {string} [fallback="操作失败"] 兜底文案
+ * @returns {string}
+ */
+export const getCodeMsg = (code, fallback = "操作失败") => CODE[code] ?? fallback;

package/response/index.js

@@ -1,12 +1,15 @@
 /**
- * 响应格式化模块 - 统一响应结构 + 数据库错误解析
- * 响应码体系：0 成功 / 1xxx 业务 / 5xxx 系统 / 6xxx 数据库
+ * response 模块聚合导出
+ * 对外暴露：success / fail / routeNotFound / serializeError
  */
 export {
   success,
   fail,
-  error,
-  parseDatabaseError,
-  notFoundResponse,
-  errorResponse,
+  routeNotFound,
+  serializeError,
+  buildErrorHtml,
+  respondError,
 } from "./response.js";
+
+// CODE 字典对外暴露（业务侧 common.CODE 需要）
+export { CODE } from "./code.js";