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

package/http-client/utils/proxy-environment.util.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyEnvironmentParser = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * 代理环境变量解析工具
+ * 支持标准的代理环境变量：HTTP_PROXY, HTTPS_PROXY, NO_PROXY
+ */
+class ProxyEnvironmentParser {
+    /**
+     * 从环境变量解析代理配置
+     * @param protocol 请求协议 (http 或 https)
+     * @param targetUrl 目标 URL（用于检查 NO_PROXY）
+     * @returns 解析后的代理配置，如果不应使用代理则返回 false
+     */
+    static parseFromEnvironment(protocol = 'http', targetUrl) {
+        // 获取代理环境变量 (大写和小写都支持)
+        const proxyEnv = protocol === 'https'
+            ? process.env.HTTPS_PROXY ||
+                process.env.https_proxy ||
+                process.env.HTTP_PROXY ||
+                process.env.http_proxy
+            : process.env.HTTP_PROXY || process.env.http_proxy;
+        // 检查是否应该跳过代理
+        if (targetUrl && this.shouldBypassProxy(targetUrl)) {
+            this.logger.debug(`Bypassing proxy for ${targetUrl} due to NO_PROXY`);
+            return false;
+        }
+        if (!proxyEnv) {
+            this.logger.debug('No proxy environment variable found');
+            return false;
+        }
+        try {
+            const proxyConfig = this.parseProxyUrl(proxyEnv);
+            this.logger.debug(`Parsed proxy configuration from environment: ${JSON.stringify(proxyConfig)}`);
+            return proxyConfig;
+        }
+        catch (error) {
+            this.logger.warn(`Failed to parse proxy URL from environment: ${error.message}`);
+            return false;
+        }
+    }
+    /**
+     * 解析代理 URL
+     * 支持格式: http://proxy:port, http://user:pass@proxy:port
+     */
+    static parseProxyUrl(proxyUrl) {
+        try {
+            const url = new URL(proxyUrl);
+            const config = {
+                protocol: url.protocol.replace(':', '') || 'http',
+                host: url.hostname,
+                port: url.port ? parseInt(url.port, 10) : url.protocol === 'https:' ? 443 : 80,
+                auth: undefined,
+            };
+            // 解析认证信息
+            if (url.username || url.password) {
+                config.auth = {
+                    username: decodeURIComponent(url.username),
+                    password: decodeURIComponent(url.password),
+                };
+            }
+            return config;
+        }
+        catch (error) {
+            throw new Error(`Invalid proxy URL format: ${proxyUrl}`);
+        }
+    }
+    /**
+     * 检查是否应该绕过代理
+     * 基于 NO_PROXY 环境变量
+     */
+    static shouldBypassProxy(targetUrl) {
+        const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+        if (!noProxy) {
+            return false;
+        }
+        try {
+            const url = new URL(targetUrl);
+            const hostname = url.hostname;
+            // NO_PROXY 可以是逗号分隔的列表
+            const bypassList = noProxy.split(',').map((item) => item.trim().toLowerCase());
+            for (const bypass of bypassList) {
+                if (!bypass)
+                    continue;
+                // 精确匹配
+                if (hostname.toLowerCase() === bypass) {
+                    return true;
+                }
+                // 通配符匹配 (例如 .example.com)
+                if (bypass.startsWith('.') && hostname.toLowerCase().endsWith(bypass)) {
+                    return true;
+                }
+                // 后缀匹配 (例如 example.com 匹配 api.example.com)
+                if (hostname.toLowerCase().endsWith('.' + bypass)) {
+                    return true;
+                }
+                // 特殊值 * 表示所有域名都绕过
+                if (bypass === '*') {
+                    return true;
+                }
+                // IP 地址范围匹配 (简单实现)
+                if (this.isIpMatch(hostname, bypass)) {
+                    return true;
+                }
+            }
+        }
+        catch (error) {
+            this.logger.warn(`Failed to parse target URL for NO_PROXY check: ${error.message}`);
+        }
+        return false;
+    }
+    /**
+     * 简单的 IP 地址匹配
+     * 支持精确匹配和 CIDR 表示法
+     */
+    static isIpMatch(hostname, pattern) {
+        // 精确 IP 匹配
+        if (hostname === pattern) {
+            return true;
+        }
+        // CIDR 匹配 (简化版本，不做完整的 CIDR 计算)
+        if (pattern.includes('/')) {
+            const [baseIp] = pattern.split('/');
+            return hostname.startsWith(baseIp.substring(0, baseIp.lastIndexOf('.')));
+        }
+        return false;
+    }
+    /**
+     * 获取所有代理相关的环境变量
+     */
+    static getProxyEnvironmentVariables() {
+        return {
+            HTTP_PROXY: process.env.HTTP_PROXY || process.env.http_proxy,
+            HTTPS_PROXY: process.env.HTTPS_PROXY || process.env.https_proxy,
+            NO_PROXY: process.env.NO_PROXY || process.env.no_proxy,
+        };
+    }
+    /**
+     * 检查是否设置了代理环境变量
+     */
+    static hasProxyEnvironment() {
+        const vars = this.getProxyEnvironmentVariables();
+        return !!(vars.HTTP_PROXY || vars.HTTPS_PROXY);
+    }
+}
+exports.ProxyEnvironmentParser = ProxyEnvironmentParser;
+ProxyEnvironmentParser.logger = new common_1.Logger(ProxyEnvironmentParser.name);

package/http-client/utils/request-id.util.d.ts

@@ -1,4 +1,22 @@
+/**
+ * 生成请求ID
+ * @returns 唯一的请求ID
+ */
 export declare function generateRequestId(): string;
+/**
+ * 生成短请求ID（用于日志）
+ * @returns 短格的请求ID
+ */
 export declare function generateShortRequestId(): string;
+/**
+ * 验证请求ID格式
+ * @param requestId 请求ID
+ * @returns 是否为有效的请求ID
+ */
 export declare function isValidRequestId(requestId: string): boolean;
+/**
+ * 从请求头中提取请求ID
+ * @param headers 请求头
+ * @returns 请求ID或null
+ */
 export declare function extractRequestId(headers: Record<string, string>): string | null;

package/http-client/utils/request-id.util.js

@@ -5,17 +5,37 @@ exports.generateShortRequestId = generateShortRequestId;
 exports.isValidRequestId = isValidRequestId;
 exports.extractRequestId = extractRequestId;
 const crypto_1 = require("crypto");
+/**
+ * 生成请求ID
+ * @returns 唯一的请求ID
+ */
 function generateRequestId() {
     return (0, crypto_1.randomUUID)();
 }
+/**
+ * 生成短请求ID（用于日志）
+ * @returns 短格的请求ID
+ */
 function generateShortRequestId() {
     return Math.random().toString(36).substring(2, 15);
 }
+/**
+ * 验证请求ID格式
+ * @param requestId 请求ID
+ * @returns 是否为有效的请求ID
+ */
 function isValidRequestId(requestId) {
+    // UUID格式验证
     const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
     return uuidRegex.test(requestId);
 }
+/**
+ * 从请求头中提取请求ID
+ * @param headers 请求头
+ * @returns 请求ID或null
+ */
 function extractRequestId(headers) {
+    // 常见的请求ID头名称
     const requestIdHeaders = [
         'x-request-id',
         'x-trace-id',

package/http-client/utils/retry-recorder.util.d.ts

@@ -1,14 +1,41 @@
 import { AxiosError, AxiosRequestConfig } from 'axios';
 import { RetryRecord } from '../entities/http-log.entity';
+/**
+ * 请求重试记录器
+ */
 export declare class RetryRecorder {
     private records;
+    /**
+     * 记录重试尝试
+     */
     static recordRetry(attempt: number, error: AxiosError | any, config: AxiosRequestConfig, delay: number): RetryRecord;
+    /**
+     * 创建重试记录器实例
+     */
     static create(): RetryRecorder;
+    /**
+     * 格式化错误信息
+     */
     private static formatError;
+    /**
+     * 获取重试原因
+     */
     private static getRetryReason;
+    /**
+     * 过滤敏感头信息
+     */
     private static sanitizeHeaders;
+    /**
+     * 添加重试记录
+     */
     addRecord(record: RetryRecord): void;
+    /**
+     * 获取所有重试记录
+     */
     getRecords(): RetryRecord[];
+    /**
+     * 获取重试统计
+     */
     getStats(): {
         totalRetries: number;
         maxAttempts: number;
@@ -16,10 +43,25 @@ export declare class RetryRecorder {
         averageDelay: number;
         reasons: Record<string, number>;
     };
+    /**
+     * 重置记录
+     */
     reset(): void;
+    /**
+     * 获取最后一次重试记录
+     */
     getLastRecord(): RetryRecord | null;
+    /**
+     * 检查是否有重试记录
+     */
     hasRetries(): boolean;
+    /**
+     * 获取指定尝试次数的记录
+     */
     getRecordByAttempt(attempt: number): RetryRecord | null;
+    /**
+     * 获取重试时间线
+     */
     getTimeline(): Array<{
         attempt: number;
         timestamp: Date;

package/http-client/utils/retry-recorder.util.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RetryRecorder = void 0;
+/**
+ * 请求重试记录器
+ */
 class RetryRecorder {
     constructor() {
         this.records = [];
     }
+    /**
+     * 记录重试尝试
+     */
     static recordRetry(attempt, error, config, delay) {
         var _a;
         return {
@@ -20,9 +26,15 @@ class RetryRecorder {
             },
         };
     }
+    /**
+     * 创建重试记录器实例
+     */
     static create() {
         return new RetryRecorder();
     }
+    /**
+     * 格式化错误信息
+     */
     static formatError(error) {
         var _a;
         if (!error)
@@ -38,8 +50,12 @@ class RetryRecorder {
         }
         return formatted;
     }
+    /**
+     * 获取重试原因
+     */
     static getRetryReason(error) {
         if (!error.response) {
+            // 网络错误
             if (error.code === 'ECONNRESET') {
                 return 'Connection reset';
             }
@@ -54,6 +70,7 @@ class RetryRecorder {
             }
             return 'Network error';
         }
+        // HTTP错误
         const status = error.response.status;
         if (status >= 500) {
             return `Server error: ${status}`;
@@ -66,6 +83,9 @@ class RetryRecorder {
         }
         return `HTTP error: ${status}`;
     }
+    /**
+     * 过滤敏感头信息
+     */
     static sanitizeHeaders(headers) {
         const sanitized = {};
         const sensitiveKeys = [
@@ -89,12 +109,21 @@ class RetryRecorder {
         });
         return sanitized;
     }
+    /**
+     * 添加重试记录
+     */
     addRecord(record) {
         this.records.push(record);
     }
+    /**
+     * 获取所有重试记录
+     */
     getRecords() {
         return [...this.records];
     }
+    /**
+     * 获取重试统计
+     */
     getStats() {
         const totalRetries = this.records.length;
         const maxAttempts = Math.max(...this.records.map((r) => r.attempt), 0);
@@ -112,20 +141,35 @@ class RetryRecorder {
             reasons,
         };
     }
+    /**
+     * 重置记录
+     */
     reset() {
         this.records = [];
     }
+    /**
+     * 获取最后一次重试记录
+     */
     getLastRecord() {
         return this.records.length > 0
             ? this.records[this.records.length - 1]
             : null;
     }
+    /**
+     * 检查是否有重试记录
+     */
     hasRetries() {
         return this.records.length > 0;
     }
+    /**
+     * 获取指定尝试次数的记录
+     */
     getRecordByAttempt(attempt) {
         return this.records.find((r) => r.attempt === attempt) || null;
     }
+    /**
+     * 获取重试时间线
+     */
     getTimeline() {
         let cumulativeDelay = 0;
         return this.records.map((record) => {

package/http-client/utils/security-validator.util.d.ts

@@ -0,0 +1,118 @@
+/**
+ * SSRF防护配置
+ */
+export interface SSRFProtectionConfig {
+    /** 是否启用SSRF防护 */
+    enabled: boolean;
+    /** 允许的URL协议 */
+    allowedProtocols: string[];
+    /** 禁止访问的IP段（私有网络、本地回环等） */
+    blockedIPRanges: string[];
+    /** 允许的主机名白名单 */
+    allowedHostnames?: string[];
+    /** 禁止的主机名黑名单 */
+    blockedHostnames?: string[];
+}
+/**
+ * URL验证配置
+ */
+export interface URLValidationConfig {
+    /** 最大URL长度 */
+    maxURLLength: number;
+    /** 是否允许本地回环地址 */
+    allowLoopback: boolean;
+    /** 是否允许私有网络地址 */
+    allowPrivateNetwork: boolean;
+    /** 是否允许Link-local地址 */
+    allowLinkLocal: boolean;
+}
+/**
+ * 安全验证工具类
+ * 提供URL验证、SSRF防护等功能
+ */
+export declare class SecurityValidator {
+    private static readonly logger;
+    /**
+     * 默认SSRF防护配置
+     */
+    private static readonly defaultSSRFConfig;
+    /**
+     * 默认URL验证配置
+     */
+    private static readonly defaultURLConfig;
+    /**
+     * 验证URL安全性
+     * @param url 要验证的URL字符串
+     * @param urlConfig URL验证配置
+     * @returns 验证结果和错误信息
+     */
+    static validateURL(url: string, urlConfig?: Partial<URLValidationConfig>): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * SSRF防护检查
+     * @param url 要检查的URL
+     * @param ssrfConfig SSRF防护配置
+     * @returns 检查结果和错误信息
+     */
+    static checkSSRF(url: string, ssrfConfig?: Partial<SSRFProtectionConfig>): {
+        safe: boolean;
+        error?: string;
+    };
+    /**
+     * 清理和验证URL
+     * 综合验证和SSRF防护
+     * @param url 要清理的URL
+     * @param config 完整的安全配置
+     * @returns 清理后的URL和验证结果
+     */
+    static sanitizeURL(url: string, config?: {
+        urlConfig?: Partial<URLValidationConfig>;
+        ssrfConfig?: Partial<SSRFProtectionConfig>;
+    }): {
+        url: string;
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * 从主机名中提取IP地址
+     */
+    private static extractIPAddress;
+    /**
+     * 验证IP地址
+     */
+    private static validateIPAddress;
+    /**
+     * 检查IP地址是否在阻止的范围内
+     */
+    private static checkIPRange;
+    /**
+     * 检查IP地址是否在指定范围内
+     * 简化版本，主要用于常见CIDR范围
+     */
+    private static isIPInRange;
+    /**
+     * 验证主机名格式
+     */
+    private static isValidHostname;
+    /**
+     * 敏感数据检测
+     * 检查数据中是否包含敏感信息（如密码、token等）
+     * @param data 要检查的数据对象
+     * @param additionalPatterns 额外的敏感数据模式
+     * @returns 检测结果
+     */
+    static detectSensitiveData(data: any, additionalPatterns?: RegExp[]): {
+        hasSensitiveData: boolean;
+        fields: string[];
+    };
+    /**
+     * 获取默认SSRF防护配置
+     */
+    static getDefaultSSRFConfig(): SSRFProtectionConfig;
+    /**
+     * 获取默认URL验证配置
+     */
+    static getDefaultURLConfig(): URLValidationConfig;
+}