chanjs 2.7.3 → 2.7.5

package/index.js

@@ -1,37 +1,75 @@
-// 核心基础类导出
-export { default as Controller } from "./base/Controller.js";
-export { default as Repository } from "./base/Repository.js";
-export { default as DB } from "./base/Database.js";
-export { Container } from "./base/Container.js";
-export { Aop, aop } from "./base/Aop.js";
-export { Event, event } from "./base/Event.js";
-
-// 工具模块导出（按职责拆分，替代原 helper 大杂烩）
-export * as storage from "./storage/index.js";     // 缓存/Redis/存储适配
-export * as security from "./security/index.js";   // 关键词/XSS/签名/JWT/限流
-export * as realtime from "./realtime/index.js";   // SSE/WebSocket
-export * as loader from "./loader/index.js";       // 加载器
-export * as response from "./response/index.js";   // 响应格式化
-export * as utils from "./utils/index.js";         // 通用工具（时间/文件/HTML/IP/数据解析/树/过滤）
-export * as helper from "./helper/index.js";       // 聚合导出层（从各子模块 re-export，业务侧兼容）
-export * as middleware from "./middleware/index.js";
-export * as config from "./config/index.js";
-export * as common from "./common/index.js";
-
-// 常用工具函数直接导出（顶层快捷访问）
-export { loadConfig, loaderSort, loadController } from "./loader/index.js";
-export { cache } from "./storage/index.js";
-
-// 定时任务调度器
-export { schedule, Schedule } from "./schedule/schedule.js";
-
-// 实时通信：SSE + WebSocket
-export { sse, SSEManager } from "./realtime/index.js";
-export { websocket, WebSocketManager } from "./realtime/index.js";
-
-// 路径配置
-export { Paths } from "./config/paths.js";
-
-// 默认导出应用主类
-import Chan from "./App.js";
-export default Chan;
+/**
+ * chanjs 包入口
+ *
+ * 默认导出：Chan 应用主类
+ *   import Chan from "chanjs";
+ *   const chan = new Chan();
+ *   await chan.start();
+ *
+ * 命名导出：
+ *   import { Controller, Repository, Service, helper, cache, Paths, loader, utils, getApp } from "chanjs";
+ *   import { validate, validateAll } from "chanjs";  // zod 校验中间件
+ *   import { AppError, NotFoundError, ValidationError } from "chanjs";  // 错误类
+ *
+ * 多实例：
+ *   每个 Chan 实例持有独立 config/db/paths/dbManager（注册表管理），
+ *   业务代码统一通过 getApp() 或 this.app（Controller/Service 内）访问当前实例。
+ */
+
+// ===================== 核心基础类 =====================
+export { default as Controller } from "./core/Controller.js";
+export { default as Repository } from "./core/Repository.js";
+export { Service } from "./core/Service.js";
+
+// ===================== 错误体系 =====================
+export {
+  AppError, AuthError, TokenExpiredError, ForbiddenError,
+  NotFoundError, ConflictError, ValidationError, ParamMissingError,
+  BusinessError, RateLimitError, BlockedError, SystemError, ServiceBusyError,
+  describeError, errorExtraProps, parseStack, isAppError, wrapDbError,
+} from "./core/errors.js";
+
+// ===================== 统一响应工具（纯函数，可复用于接口 / 定时任务 / RPC）=====================
+export { success, fail, routeNotFound, serializeError, buildErrorHtml, respondError } from "./response/index.js";
+
+// ===================== 安全工具 =====================
+export { setToken, getToken, verifyToken } from "./security/jwt.js";
+export { aesEncrypt, aesDecrypt } from "./security/sign.js";
+export { createRateLimitMiddleware } from "./security/rate-limit.js";
+export { filterXSS, checkKeywords } from "./security/index.js";
+
+// ===================== 统一日志 =====================
+export { default as logger, createLogger } from "./utils/logger.js";
+
+// ===================== 校验中间件 =====================
+export { validate, validateAll } from "./middleware/validate.js";
+
+// ===================== 应用实例（单实例）=====================
+export { setApp, getApp } from "./core/registry.js";
+
+// ===================== 命名空间导出（业务侧 router/service 使用）=====================
+export * as loader from "./core/loader.js";
+export * as utils from "./utils/index.js";
+
+// ===================== 常用工具直接导出 =====================
+export { cache, store } from "./storage/index.js";
+export { Paths } from "./utils/paths.js";
+
+// ===================== helper 聚合对象 =====================
+// 为兼容老代码 import { helper } from "chanjs"，薄封装：单一来源 = 命名导出 + 工具命名空间
+import * as utilsNs from "./utils/index.js";
+import { cache, store } from "./storage/index.js";
+import { success, fail } from "./response/index.js";
+import { setToken, getToken, aesEncrypt, aesDecrypt } from "./security/index.js";
+import { createRateLimitMiddleware } from "./security/rate-limit.js";
+import { filterXSS, checkKeywords } from "./security/index.js";
+
+export const helper = Object.assign(Object.create(null), utilsNs, {
+  cache, store, success, fail,
+  setToken, getToken, aesEncrypt, aesDecrypt,
+  createRateLimitMiddleware, filterXSS, checkKeywords,
+});
+
+// ===================== 默认导出应用主类 =====================
+import Chan from "./core/App.js";
+export default Chan;

package/middleware/body.js

@@ -0,0 +1,17 @@
+import express from "express";
+
+/**
+ * @description 请求体解析中间件，支持 JSON/URL-XML
+ * 安全限制：请求体上限、参数数量防攻击，支持嵌套对象
+ * @param {express.Application} app Express实例
+ * @param {string} [bodyLimit='10mb'] 请求体大小限制
+ */
+export function body(app, bodyLimit = '10mb') {
+  app.use(express.raw({ type: "application/xml", limit: bodyLimit }));
+  app.use(express.json({ limit: bodyLimit }));
+  app.use(express.urlencoded({
+    extended: true,
+    limit: bodyLimit,
+    parameterLimit: 100,
+  }));
+}

package/middleware/cookie.js

@@ -1,20 +1,12 @@
 import cookieParser from "cookie-parser";
+import logger from "../utils/logger.js";
 
 /**
- * Cookie 中间件配置
- * 配置 Express 应用的 cookie 解析功能
+ * Cookie解析中间件，支持签名校验
+ * @param {express.Application} app Express实例
+ * @param {string} [cookieKey] Cookie签名密钥
  */
-
-/**
- * 设置 Cookie 解析中间件
- * @param {Object} app - Express 应用实例
- * @param {string} cookieKey - Cookie 签名密钥
- * @description
- * 为 Express 应用配置 cookie-parser 中间件
- * 使用密钥对 cookie 进行签名验证
- * @example
- * setCookie(app, 'my-secret-key');
- */
-export const setCookie = (app, cookieKey) => {
+export const cookie = (app, cookieKey) => {
+  !cookieKey && logger.warn("[Cookie] 未配置签名密钥，Cookie无法加密签名");
   app.use(cookieParser(cookieKey));
-};
+};

package/middleware/cors.js

@@ -1,36 +1,18 @@
 import cors from "cors";
 
 /**
- * CORS 中间件配置
- * 配置跨域资源共享
- */
-
-/**
- * 设置 CORS 中间件
- * @param {Object} app - Express 应用实例
- * @param {Object} [_cors={}] - CORS 配置选项
- * @description
- * 为 Express 应用配置 CORS 中间件
- *
- * 安全改进：
- * - 默认拒绝跨域（origin=false），避免未配置时全开放
- * - 默认仅允许 GET/POST 方法
- * - credentials 默认 false，避免 Cookie 跨域携带
- * - 业务侧需显式开放时再传入完整 _cors 配置
- * @example
- * Cors(app, {
- *   origin: 'https://example.com',
- *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
- *   credentials: true
- * });
+ * CORS跨域中间件，内置安全默认值
+ * @param {express.Application} app Express实例
+ * @param {cors.CorsOptions} [_cors={}] 自定义跨域配置
+ * 默认安全策略：禁止跨域、仅GET/POST、不携带Cookie
  */
 export const Cors = (app, _cors = {}) => {
   const safeOptions = {
-    origin: _cors.origin || false,
-    methods: _cors.methods || ['GET', 'POST'],
-    allowedHeaders: _cors.allowedHeaders || ['Content-Type', 'Authorization'],
+    origin: _cors.origin ?? false,
+    methods: _cors.methods ?? ["GET", "POST"],
+    allowedHeaders: _cors.allowedHeaders ?? ["Content-Type", "Authorization"],
     credentials: !!_cors.credentials,
-    maxAge: _cors.maxAge || 600,
+    maxAge: _cors.maxAge ?? 600,
   };
   app.use(cors(safeOptions));
-};
+};

package/middleware/favicon.js

@@ -1,21 +1,11 @@
 import path from "path";
-import favicon from "serve-favicon";
-import { Paths } from "../config/paths.js";
+import serveFavicon from "serve-favicon";
+import { Paths } from "../utils/paths.js";
 
 /**
- * Favicon 中间件配置
- * 配置网站图标
+ * 网站图标中间件，读取public目录favicon.ico
+ * @param {express.Application} app Express实例
  */
-
-/**
- * 设置 Favicon 中间件
- * @param {Object} app - Express 应用实例
- * @description
- * 为 Express 应用配置 favicon 服务
- * 从 public 目录加载 favicon.ico 文件
- * @example
- * setFavicon(app);
- */
-export const setFavicon = (app) => {
-  app.use(favicon(path.join(Paths.publicPath, "favicon.ico")));
-};
+export const favicon = app => {
+  app.use(serveFavicon(path.join(Paths.publicPath, "favicon.ico")));
+};

package/middleware/header.js

@@ -1,21 +1,20 @@
 /**
- * 响应头中间件配置
- * 设置应用相关的响应头信息
+ * 自定义响应头中间件，隐藏原生Express标识，统一输出ChanCMS
+ * @param {express.Application} app Express实例
+ * @param {{APP_NAME?: string, APP_VERSION?: string}} [opts] 配置选项
  */
+export const header = (app, opts = {}) => {
+  const appName = opts.APP_NAME || "ChanCMS";
+  const appVer = opts.APP_VERSION || "";
+  const poweredBy = appVer ? `${appName}/${appVer}` : appName;
 
-/**
- * 设置响应头中间件
- * @param {Object} app - Express 应用实例
- * @param {Object} options - 配置选项（保留参数兼容旧调用，不再使用 APP_VERSION）
- * @description
- * 为所有响应添加技术栈标识响应头
- * 保留 ChanCMS 标识，移除版本号防止信息泄露
- * @example
- * setHeader(app, { APP_NAME: 'MyApp' });
- */
-export let setHeader = (app) => {
-  app.use((req, res, next) => {
-    res.setHeader("X-Powered-By", "ChanCMS");
+  app.use((_, res, next) => {
+    res.setHeader("X-Powered-By", poweredBy);
+    // 常驻安全响应头：无论 WAF 是否启用都生效
+    // 禁止 MIME 嗅探（防 XSS 利用 Content-Type 歧义）
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    // 防点击劫持：仅允许同源 iframe 嵌套（如需被第三方嵌入请按需放宽）
+    res.setHeader("Content-Security-Policy", "frame-ancestors 'self'");
     next();
   });
-};
+};

package/middleware/index.js

@@ -1,15 +1,15 @@
 /**
- * 中间件模块入口
- * 导出所有中间件配置函数
+ * middleware 模块聚合导出
+ *
+ * 说明：响应压缩（compress）已从框架移除——生产环境由 Nginx gzip 统一处理，
+ * 无需在 Node 层重复实现。
  */
-
-export { setCookie } from "./cookie.js";
-export { setFavicon } from "./favicon.js";
-export { setBody } from "./setBody.js";
-export { setStatic } from "./static.js";
-export { setHeader } from "./header.js";
-export { setTemplate } from "./template.js";
 export { Cors } from "./cors.js";
-export { waf } from "./waf.js";
-export { compress } from "./compress.js";
+export { body } from "./body.js";
+export { cookie } from "./cookie.js";
+export { favicon } from "./favicon.js";
+export { header } from "./header.js";
+export { staticMw } from "./static.js";
+export { template } from "./template.js";
+export { waf, wafBody } from "./waf.js";
 export { log } from "./log.js";

package/middleware/log.js

@@ -1,65 +1,35 @@
 import morgan from "morgan";
 import { getIp } from "../utils/ip.js";
 
-/**
- * morgan 输出格式白名单
- * 仅允许使用以下格式，避免任意 level 注入导致 morgan 内部异常
- */
-const ALLOWED_FORMATS = new Set([
-  'chancms',
-  'combined',
-  'common',
-  'dev',
-  'short',
-  'tiny',
-]);
-
-// 自定义 IP 令牌
-morgan.token("ip", (req, res) => {
-  return getIp(req);
-});
-
-// 自定义用户信息令牌
-morgan.token("user", (req, res) => {
-  if (req.user) {
-    return `${req.user.uid}:${req.user.username}`;
-  }
-  return "-";
-});
+// 日志格式白名单，防止非法格式注入
+const ALLOWED_FORMATS = new Set(["chancms", "combined", "common", "dev", "short", "tiny"]);
 
-// 自定义时间令牌（带日期）
-morgan.token("datetime", (req, res) => {
-  return new Date().toISOString();
-});
+// 自定义token
+morgan.token("ip", req => getIp(req));
+morgan.token("user", req => req.user ? `${req.user.uid}:${req.user.username}` : "-");
+morgan.token("datetime", () => new Date().toISOString());
 
-// 自定义 morgan 格式：时间 IP 用户 Method URL Status Length - Response-Time ms
-morgan.format("chancms", (tokens, req, res) => {
-  return [
-    tokens.datetime(req, res),
-    tokens.ip(req, res),
-    tokens.user(req, res),
-    tokens.method(req, res),
-    tokens.url(req, res),
-    tokens.status(req, res),
-    tokens.res(req, res, "content-length") || "-",
-    "-",
-    tokens["response-time"](req, res),
-    "ms",
-  ].join(" ");
-});
+// 自定义ChanCMS日志输出模板
+morgan.format("chancms", (tokens, req, res) => [
+  tokens.datetime(req, res),
+  tokens.ip(req, res),
+  tokens.user(req, res),
+  tokens.method(req, res),
+  tokens.url(req, res),
+  tokens.status(req, res),
+  tokens.res(req, res, "content-length") || "-",
+  "-",
+  tokens["response-time"](req, res),
+  "ms"
+].join(" "));
 
 /**
- * 注册 morgan 日志中间件
- * @param {Object} app - Express 应用实例
- * @param {Object} [logger] - 日志配置
- * @param {string} [logger.level='chancms'] - 日志格式，仅允许白名单内的格式
- * @description
- * 安全改进：
- * - level 必须在白名单内，未配置或非法值默认 'chancms'
- * - 避免任意字符串传入 morgan 导致格式解析异常
+ * 请求日志中间件(morgan)，内置格式白名单防注入
+ * @param {express.Application} app Express实例
+ * @param {{level?: string}} [logger={}] 日志配置
  */
-export const log = (app, logger) => {
-  const level = logger?.level;
-  const format = ALLOWED_FORMATS.has(level) ? level : 'chancms';
+export const log = (app, logger = {}) => {
+  const level = logger.level;
+  const format = ALLOWED_FORMATS.has(level) ? level : "chancms";
   app.use(morgan(format));
-};
+};

package/middleware/static.js

@@ -1,32 +1,19 @@
 import express from "express";
+import { safePath } from "../utils/file.js";
+import logger from "../utils/logger.js";
 
 /**
- * 静态文件服务中间件配置
- * 配置静态资源访问
+ * 批量挂载静态资源中间件，内置目录安全校验
+ * @param {express.Application} app Express实例
+ * @param {Array<{prefix:string;dir:string;maxAge?:number}>} statics 静态目录配置数组
  */
-
-/**
- * 设置静态文件服务中间件
- * @param {Object} app - Express 应用实例
- * @param {Array<Object>} statics - 静态资源配置数组
- * @param {string} statics[].prefix - URL 前缀
- * @param {string} statics[].dir - 静态文件目录
- * @param {number} [statics[].maxAge] - 缓存时间（秒）
- * @description
- * 为 Express 应用配置多个静态文件服务
- * 每个静态资源可以指定不同的 URL 前缀和目录
- * @example
- * setStatic(app, [
- *   { prefix: '/public', dir: './public', maxAge: 3600 },
- *   { prefix: '/uploads', dir: './uploads', maxAge: 0 }
- * ]);
- */
-export const setStatic = async function (app, statics) {
-  if (statics.length > 0) {
-    statics.forEach((item) => {
-      const { prefix, dir, maxAge } = item;
-      // dotfile: 'deny' 显式拒绝访问点文件（.env / .git/config 等），避免敏感配置泄漏
-      app.use(prefix, express.static(dir, { maxAge: maxAge || 0, dotfile: 'deny' }));
-    });
-  }
-};
+export const staticMw = async (app, statics) => {
+  if (!Array.isArray(statics) || !statics.length) return;
+  statics.forEach(({ prefix, dir, maxAge }) => {
+    if (!safePath(dir)) {
+      logger.error(`[Static] 不安全目录拦截：${dir}`);
+      return;
+    }
+    app.use(prefix, express.static(dir, { maxAge: maxAge ?? 0, dotfile: "deny" }));
+  });
+};