@nest-omni/core 4.1.3-2 → 4.1.3-20

package/http-client/utils/security-validator.util.js

@@ -0,0 +1,352 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityValidator = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * 安全验证工具类
+ * 提供URL验证、SSRF防护等功能
+ */
+class SecurityValidator {
+    /**
+     * 验证URL安全性
+     * @param url 要验证的URL字符串
+     * @param urlConfig URL验证配置
+     * @returns 验证结果和错误信息
+     */
+    static validateURL(url, urlConfig = {}) {
+        const config = Object.assign(Object.assign({}, this.defaultURLConfig), urlConfig);
+        // 检查URL长度
+        if (url.length > config.maxURLLength) {
+            return {
+                valid: false,
+                error: `URL length exceeds maximum allowed length of ${config.maxURLLength}`,
+            };
+        }
+        let parsedURL;
+        try {
+            parsedURL = new URL(url);
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: `Invalid URL format: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        // 检查协议
+        if (!['http:', 'https:', 'ws:', 'wss:'].includes(parsedURL.protocol)) {
+            return {
+                valid: false,
+                error: `Unsupported protocol: ${parsedURL.protocol}`,
+            };
+        }
+        // 检查主机名
+        if (!parsedURL.hostname) {
+            return {
+                valid: false,
+                error: 'Hostname is required',
+            };
+        }
+        // 检查是否为IP地址
+        const ipAddress = this.extractIPAddress(parsedURL.hostname);
+        if (ipAddress) {
+            return this.validateIPAddress(ipAddress, config);
+        }
+        // 检查主机名格式
+        if (!this.isValidHostname(parsedURL.hostname)) {
+            return {
+                valid: false,
+                error: `Invalid hostname format: ${parsedURL.hostname}`,
+            };
+        }
+        return { valid: true };
+    }
+    /**
+     * SSRF防护检查
+     * @param url 要检查的URL
+     * @param ssrfConfig SSRF防护配置
+     * @returns 检查结果和错误信息
+     */
+    static checkSSRF(url, ssrfConfig = {}) {
+        const config = Object.assign(Object.assign({}, this.defaultSSRFConfig), ssrfConfig);
+        if (!config.enabled) {
+            return { safe: true };
+        }
+        let parsedURL;
+        try {
+            parsedURL = new URL(url);
+        }
+        catch (error) {
+            return {
+                safe: false,
+                error: `Invalid URL format: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        // 检查协议
+        if (!config.allowedProtocols.includes(parsedURL.protocol)) {
+            return {
+                safe: false,
+                error: `Protocol not allowed: ${parsedURL.protocol}`,
+            };
+        }
+        // 检查黑名单主机名
+        if (config.blockedHostnames) {
+            if (config.blockedHostnames.includes(parsedURL.hostname)) {
+                return {
+                    safe: false,
+                    error: `Hostname is blocked: ${parsedURL.hostname}`,
+                };
+            }
+        }
+        // 检查白名单主机名（如果配置了）
+        if (config.allowedHostnames && config.allowedHostnames.length > 0) {
+            if (!config.allowedHostnames.includes(parsedURL.hostname)) {
+                return {
+                    safe: false,
+                    error: `Hostname not in whitelist: ${parsedURL.hostname}`,
+                };
+            }
+        }
+        // 检查IP地址范围
+        const ipAddress = this.extractIPAddress(parsedURL.hostname);
+        if (ipAddress) {
+            const ipCheck = this.checkIPRange(ipAddress, config.blockedIPRanges);
+            if (!ipCheck.allowed) {
+                return {
+                    safe: false,
+                    error: `IP address is blocked: ${ipAddress} (${ipCheck.reason})`,
+                };
+            }
+        }
+        return { safe: true };
+    }
+    /**
+     * 清理和验证URL
+     * 综合验证和SSRF防护
+     * @param url 要清理的URL
+     * @param config 完整的安全配置
+     * @returns 清理后的URL和验证结果
+     */
+    static sanitizeURL(url, config = {}) {
+        // 去除首尾空格
+        let sanitizedURL = url.trim();
+        // 移除可能的换行符和控制字符
+        sanitizedURL = sanitizedURL.replace(/[\r\n\t]/g, '');
+        // 验证URL格式
+        const validationResult = this.validateURL(sanitizedURL, config.urlConfig);
+        if (!validationResult.valid) {
+            return { url: sanitizedURL, valid: false, error: validationResult.error };
+        }
+        // SSRF防护检查
+        const ssrfResult = this.checkSSRF(sanitizedURL, config.ssrfConfig);
+        if (!ssrfResult.safe) {
+            return { url: sanitizedURL, valid: false, error: ssrfResult.error };
+        }
+        return { url: sanitizedURL, valid: true };
+    }
+    /**
+     * 从主机名中提取IP地址
+     */
+    static extractIPAddress(hostname) {
+        // IPv4地址
+        const ipv4Regex = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+        const ipv4Match = hostname.match(ipv4Regex);
+        if (ipv4Match) {
+            return hostname;
+        }
+        // IPv6地址（简化版）
+        if (hostname.includes(':') && !hostname.includes('.')) {
+            return hostname;
+        }
+        return null;
+    }
+    /**
+     * 验证IP地址
+     */
+    static validateIPAddress(ipAddress, config) {
+        // 检查是否为本地回环地址
+        if (!config.allowLoopback) {
+            if (ipAddress === '127.0.0.1' || ipAddress === '::1' || ipAddress.startsWith('127.')) {
+                return {
+                    valid: false,
+                    error: 'Loopback addresses are not allowed',
+                };
+            }
+        }
+        // 检查是否为私有网络地址
+        if (!config.allowPrivateNetwork) {
+            if (ipAddress.startsWith('10.') ||
+                ipAddress.startsWith('172.16.') ||
+                ipAddress.startsWith('192.168.') ||
+                ipAddress.startsWith('fc00:') ||
+                ipAddress.startsWith('fd')) {
+                return {
+                    valid: false,
+                    error: 'Private network addresses are not allowed',
+                };
+            }
+        }
+        // 检查是否为Link-local地址
+        if (!config.allowLinkLocal) {
+            if (ipAddress.startsWith('169.254.') || ipAddress.startsWith('fe80:')) {
+                return {
+                    valid: false,
+                    error: 'Link-local addresses are not allowed',
+                };
+            }
+        }
+        return { valid: true };
+    }
+    /**
+     * 检查IP地址是否在阻止的范围内
+     */
+    static checkIPRange(ipAddress, blockedRanges) {
+        for (const range of blockedRanges) {
+            if (this.isIPInRange(ipAddress, range)) {
+                return {
+                    allowed: false,
+                    reason: `IP address is in blocked range: ${range}`,
+                };
+            }
+        }
+        return { allowed: true };
+    }
+    /**
+     * 检查IP地址是否在指定范围内
+     * 简化版本，主要用于常见CIDR范围
+     */
+    static isIPInRange(ipAddress, cidrRange) {
+        // 处理IPv4 CIDR
+        const [range, prefixStr] = cidrRange.split('/');
+        const prefix = parseInt(prefixStr, 10);
+        // 精确匹配
+        if (ipAddress === range) {
+            return true;
+        }
+        // 简化的CIDR匹配（仅支持常见范围）
+        if (cidrRange.includes('/')) {
+            // IPv4范围检查
+            if (range.includes('.') && ipAddress.includes('.')) {
+                const rangeParts = range.split('.').map(Number);
+                const ipParts = ipAddress.split('.').map(Number);
+                if (prefix === 8) {
+                    return ipParts[0] === rangeParts[0];
+                }
+                else if (prefix === 16) {
+                    return ipParts[0] === rangeParts[0] && ipParts[1] === rangeParts[1];
+                }
+                else if (prefix === 24) {
+                    return (ipParts[0] === rangeParts[0] &&
+                        ipParts[1] === rangeParts[1] &&
+                        ipParts[2] === rangeParts[2]);
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * 验证主机名格式
+     */
+    static isValidHostname(hostname) {
+        // RFC 1123主机名规范
+        const hostnameRegex = /^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*$/;
+        return hostnameRegex.test(hostname);
+    }
+    /**
+     * 敏感数据检测
+     * 检查数据中是否包含敏感信息（如密码、token等）
+     * @param data 要检查的数据对象
+     * @param additionalPatterns 额外的敏感数据模式
+     * @returns 检测结果
+     */
+    static detectSensitiveData(data, additionalPatterns = []) {
+        const sensitiveFields = [];
+        // 默认敏感字段名模式
+        const defaultPatterns = [
+            /password/i,
+            /secret/i,
+            /token/i,
+            /api[_-]?key/i,
+            /authorization/i,
+            /credential/i,
+            /private[_-]?key/i,
+            /access[_-]?token/i,
+            /refresh[_-]?token/i,
+            /session[_-]?id/i,
+            /csrf/i,
+            /ssn/i,
+            /credit[_-]?card/i,
+        ];
+        const allPatterns = [...defaultPatterns, ...additionalPatterns];
+        const checkObject = (obj, path = '') => {
+            if (!obj || typeof obj !== 'object') {
+                return;
+            }
+            for (const key in obj) {
+                if (!obj.hasOwnProperty(key)) {
+                    continue;
+                }
+                const currentPath = path ? `${path}.${key}` : key;
+                // 检查键名是否匹配敏感模式
+                if (allPatterns.some((pattern) => pattern.test(key))) {
+                    sensitiveFields.push(currentPath);
+                }
+                // 递归检查嵌套对象
+                if (typeof obj[key] === 'object' && obj[key] !== null) {
+                    checkObject(obj[key], currentPath);
+                }
+            }
+        };
+        checkObject(data);
+        return {
+            hasSensitiveData: sensitiveFields.length > 0,
+            fields: sensitiveFields,
+        };
+    }
+    /**
+     * 获取默认SSRF防护配置
+     */
+    static getDefaultSSRFConfig() {
+        return Object.assign({}, this.defaultSSRFConfig);
+    }
+    /**
+     * 获取默认URL验证配置
+     */
+    static getDefaultURLConfig() {
+        return Object.assign({}, this.defaultURLConfig);
+    }
+}
+exports.SecurityValidator = SecurityValidator;
+SecurityValidator.logger = new common_1.Logger(SecurityValidator.name);
+/**
+ * 默认SSRF防护配置
+ */
+SecurityValidator.defaultSSRFConfig = {
+    enabled: true,
+    allowedProtocols: ['http:', 'https:'],
+    blockedIPRanges: [
+        '127.0.0.0/8', // Loopback
+        '10.0.0.0/8', // Private Class A
+        '172.16.0.0/12', // Private Class B
+        '192.168.0.0/16', // Private Class C
+        '169.254.0.0/16', // Link-local
+        '::1/128', // IPv6 loopback
+        'fc00::/7', // IPv6 private
+        'fe80::/10', // IPv6 link-local
+        '0.0.0.0/8', // Current network
+    ],
+    allowedHostnames: undefined,
+    blockedHostnames: [
+        'localhost',
+        'metadata.google.internal', // GCP metadata
+        '169.254.169.254', // AWS/GCP/Azure metadata
+    ],
+};
+/**
+ * 默认URL验证配置
+ */
+SecurityValidator.defaultURLConfig = {
+    maxURLLength: 2000,
+    allowLoopback: false,
+    allowPrivateNetwork: false,
+    allowLinkLocal: false,
+};

package/index.d.ts

@@ -1,3 +1,4 @@
+export * from './common';
 export * from './constants';
 export * from './decorators';
 export * from './exceptions';
@@ -7,7 +8,6 @@ export * from './interceptors';
 export * from './shared';
 export * from './middlewares';
 export * from './validators';
-export * from './common';
 export * from './validator-json';
 export * from './helpers';
 export * from './providers';
@@ -18,3 +18,5 @@ export * from './vault';
 export * from './setup';
 export * from './health-checker';
 export * from './audit';
+export * from './file-upload';
+export * from '@nest-omni/transaction';

package/index.js

@@ -14,6 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// Core modules
+__exportStar(require("./common"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./exceptions"), exports);
@@ -23,14 +25,23 @@ __exportStar(require("./interceptors"), exports);
 __exportStar(require("./shared"), exports);
 __exportStar(require("./middlewares"), exports);
 __exportStar(require("./validators"), exports);
-__exportStar(require("./common"), exports);
 __exportStar(require("./validator-json"), exports);
 __exportStar(require("./helpers"), exports);
 __exportStar(require("./providers"), exports);
+// Lock module
 __exportStar(require("./redis-lock"), exports);
+// Cache module
 __exportStar(require("./cache"), exports);
+// HTTP Client module
 __exportStar(require("./http-client"), exports);
+// Vault module
 __exportStar(require("./vault"), exports);
+// Setup and bootstrap
 __exportStar(require("./setup"), exports);
+// Health checker
 __exportStar(require("./health-checker"), exports);
+// Audit module
 __exportStar(require("./audit"), exports);
+// File upload module
+__exportStar(require("./file-upload"), exports);
+__exportStar(require("@nest-omni/transaction"), exports);

package/interceptors/translation-interceptor.service.js

@@ -9,12 +9,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TranslationInterceptor = void 0;
 const common_1 = require("@nestjs/common");
 const operators_1 = require("rxjs/operators");
+// import { TranslationService } from '../shared/services/translation.service';
+// FIXME: add implementation
 let TranslationInterceptor = class TranslationInterceptor {
+    // constructor(private readonly translationService: TranslationService) {}
     intercept(context, next) {
         const ctx = context.switchToHttp();
         const req = ctx.getRequest();
         const res = ctx.getResponse();
         return next.handle().pipe((0, operators_1.map)((data) => {
+            // const newData = this.translationService.translateNecessaryKeys(data);
+            // status 201 => 200
             if (res.statusCode === common_1.HttpStatus.CREATED) {
                 res.status(common_1.HttpStatus.OK);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nest-omni/core",
-  "version": "4.1.3-2",
+  "version": "4.1.3-20",
   "description": "A comprehensive NestJS framework for building enterprise-grade applications with best practices",
   "main": "index.js",
   "types": "index.d.ts",
@@ -36,7 +36,7 @@
   "author": "Jinpy",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=18.0.0",
+    "node": ">=22.0.0",
     "npm": ">=9.0.0"
   },
   "devDependencies": {
@@ -45,15 +45,16 @@
     "@types/express-session": "^1.18.2",
     "@types/lodash": "^4.17.20",
     "@types/node": "^24.9.1",
+    "@types/sharp": "^0.31.1",
     "@types/sprintf-js": "^1.1.4",
     "@types/uuid": "^11.0.0",
+    "sqlite3": "^5.1.7",
     "typescript": "^5.9.3"
   },
   "dependencies": {
     "@dataui/crud": "^5.3.4",
     "@dataui/crud-typeorm": "^5.3.4",
-    "@nestjs-cls/transactional": "^3.1.0",
-    "@nestjs-cls/transactional-adapter-typeorm": "^1.3.0",
+    "@nest-omni/transaction": "*",
     "@nestjs/bull": "^11.0.4",
     "@nestjs/common": "^11.1.7",
     "@nestjs/config": "^4.0.2",
@@ -67,7 +68,7 @@
     "@sentry/profiling-node": "^10.22.0",
     "@songkeys/nestjs-redis": "^11.0.0",
     "@songkeys/nestjs-redis-health": "^11.0.0",
-    "axios": "^1.12.2",
+    "axios": "^1.13.2",
     "axios-retry": "^4.5.0",
     "bcrypt": "^6.0.0",
     "body-parser": "^2.2.0",
@@ -79,6 +80,7 @@
     "dotenv": "^17.2.3",
     "express": "^5.1.0",
     "express-session": "^1.18.2",
+    "fast-csv": "^5.0.5",
     "hygen": "^6.2.11",
     "ioredis": "^5.8.2",
     "libphonenumber-js": "^1.12.25",
@@ -89,6 +91,7 @@
     "nestjs-cls": "^6.0.1",
     "nestjs-i18n": "^10.5.1",
     "nestjs-pino": "^4.4.1",
+    "node-vault": "^0.10.9",
     "pino-http": "^11.0.0",
     "pino-pretty": "^13.1.2",
     "reflect-metadata": "^0.2.2",
@@ -97,6 +100,7 @@
     "sprintf-js": "^1.1.3",
     "typeorm": "^0.3.27",
     "uuid": "^13.0.0",
-    "node-vault": "^0.10.9"
-  }
+    "xlsx": "git+https://git.sheetjs.com/sheetjs/sheetjs.git#v0.20.3"
+  },
+  "peerDependencies": {}
 }

package/providers/context.provider.js

@@ -8,6 +8,7 @@ class ContextProvider {
         const store = nestjs_cls_1.ClsServiceManager.getClsService();
         return store.get(ContextProvider.getKeyWithNamespace(key));
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static set(key, value) {
         const store = nestjs_cls_1.ClsServiceManager.getClsService();
         store.set(ContextProvider.getKeyWithNamespace(key), value);
@@ -24,6 +25,7 @@ class ContextProvider {
     static getRouter() {
         const value = ContextProvider.get(ContextProvider.routerKey);
         if (value) {
+            // @ts-ignore
             return value;
         }
         return {

package/providers/generator.provider.d.ts

@@ -5,5 +5,9 @@ export declare class GeneratorProvider {
     static getS3Key(publicUrl: string): string;
     static generateVerificationCode(): string;
     static generatePassword(): string;
+    /**
+     * generate random string
+     * @param length
+     */
     static generateRandomString(length: number): string;
 }

package/providers/generator.provider.js

@@ -40,6 +40,10 @@ class GeneratorProvider {
         }
         return text;
     }
+    /**
+     * generate random string
+     * @param length
+     */
     static generateRandomString(length) {
         return Math.random()
             .toString(36)

package/redis-lock/comprehensive-lock-cleanup.service.d.ts

@@ -0,0 +1,94 @@
+import { OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
+import { RedisLockService } from './redis-lock.service';
+import { LockHeartbeatService } from './lock-heartbeat.service';
+/**
+ * Comprehensive lock cleanup service
+ *
+ * Provides safe and comprehensive lock cleanup mechanism for distributed environments.
+ * Combines instance-based precise cleanup with heartbeat-based dead instance detection.
+ *
+ * **Cleanup Strategy:**
+ * 1. **Immediate Precise Cleanup (0s):**
+ *    - Only cleans locks from the current instance
+ *    - Safe during rolling updates - won't affect other running instances
+ *
+ * 2. **Delayed Conservative Cleanup (60s):**
+ *    - Checks heartbeat of other instances
+ *    - Only cleans locks from dead instances (no heartbeat)
+ *    - Gives enough time for rolling updates to complete
+ *
+ * 3. **Graceful Shutdown Cleanup:**
+ *    - On SIGTERM/SIGINT, immediately cleans own locks
+ *    - Ensures locks are released before process exits
+ *    - Works with PM2 reload and Kubernetes rolling updates
+ *
+ * @example
+ * ```typescript
+ * // In your module
+ * @Module({
+ *   providers: [
+ *     RedisLockService,
+ *     LockHeartbeatService,
+ *     ComprehensiveLockCleanupService,
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class ComprehensiveLockCleanupService implements OnModuleInit, OnApplicationShutdown {
+    private readonly lockService;
+    private readonly heartbeatService;
+    private readonly logger;
+    private readonly instanceId;
+    /**
+     * Grace period before cleaning other instances' locks (milliseconds)
+     * @default 60000 (60 seconds)
+     */
+    private readonly gracePeriod;
+    constructor(lockService: RedisLockService, heartbeatService: LockHeartbeatService);
+    onModuleInit(): Promise<void>;
+    /**
+     * Clean up locks from the current instance
+     * Safe to run immediately - only affects locks created by this instance
+     */
+    private cleanupOwnLocks;
+    /**
+     * Clean up locks from dead instances
+     * Only runs after grace period to avoid cleaning locks during rolling updates
+     */
+    private cleanupDeadInstanceLocks;
+    /**
+     * Check if a lock belongs to the current instance
+     *
+     * @param lockValue - Lock value to check
+     * @returns True if lock belongs to current instance
+     */
+    private isOwnLock;
+    /**
+     * Extract instance ID from lock value
+     * Lock value format: instanceId:timestamp:random:pid
+     *
+     * @param lockValue - Lock value
+     * @returns Instance ID or null if cannot be extracted
+     */
+    private extractInstanceId;
+    /**
+     * Get instance identifier
+     */
+    private getInstanceId;
+    /**
+     * Manually trigger cleanup of all stale locks
+     * Use with caution - this will clean both own and dead instance locks
+     */
+    manualCleanup(): Promise<{
+        ownLocks: number;
+        deadLocks: number;
+    }>;
+    private cleanupOwnLocksCount;
+    private cleanupDeadInstanceLocksCount;
+    /**
+     * Cleanup own locks on application shutdown
+     * Called when receiving SIGTERM/SIGINT (graceful shutdown)
+     */
+    onApplicationShutdown(signal?: string): Promise<void>;
+}