nstarter-http-request 0.1.7 → 0.1.9

package/src/client.ts

@@ -41,6 +41,20 @@ import {
 } from 'node:stream';
 import { MetricsTransform } from './stream';
 
+type ForwardProxyDecision = {
+    shouldProxy: false,
+    reason: 'disabled' | 'invalid_url' | 'unsupported_protocol' | 'no_proxy' | 'missing_proxy_url',
+    hostname?: string,
+    protocol?: string,
+    pattern?: string
+} | {
+    shouldProxy: true,
+    hostname: string,
+    protocol: string,
+    isHttps: boolean,
+    proxyUrl: string
+};
+
 /**
  * HTTP 客户端
  */
@@ -175,27 +189,44 @@ export class NsHttpClient implements IHttpClient {
         const startTime = Date.now();
 
         try {
+            const forwardProxyDecision = this.resolveForwardProxyDecision(options.url);
+
             // 安全验证
-            const { safeUrl, result: ssrfResult } = await this.ssrfGuard.validateAndGetSafeUrl(options.url);
+            const { safeUrl, result: ssrfResult } = await this.ssrfGuard.validateAndGetSafeUrl(
+                options.url,
+                {
+                    skipDnsValidation: forwardProxyDecision.shouldProxy,
+                    skipDnsValidationReason: forwardProxyDecision.shouldProxy ? 'forward_proxy' : undefined
+                }
+            );
 
             this.logger.debug('URL validation passed', {
                 originalUrl: options.url,
                 safeUrl,
                 resolvedIps: ssrfResult.resolvedIps,
+                dnsValidationSkipped: ssrfResult.dnsValidationSkipped,
+                dnsValidationSkipReason: ssrfResult.dnsValidationSkipReason,
                 scenario: options.scenario
             });
 
+            if (ssrfResult.dnsValidationSkipped && forwardProxyDecision.shouldProxy) {
+                this.logger.debug('Skipped target DNS validation because request uses forward proxy', {
+                    hostname: forwardProxyDecision.hostname,
+                    proxyUrl: forwardProxyDecision.proxyUrl
+                });
+            }
+
             // 使用安全的 URL 发起请求
             const safeOptions: HttpRequestOptions = {
                 ...options,
                 url: safeUrl
             };
 
-            // 如果 URL 被替换为 IP，需要设置 Host 头
-            if (ssrfResult.safeIp && ssrfResult.hostname !== ssrfResult.safeIp) {
+            // 如果 URL 被替换为 IP，需要设置 Host 头；调用方显式传入 Host 时优先尊重业务覆盖值。
+            if (ssrfResult.safeIp && ssrfResult.hostname !== ssrfResult.safeIp && !this.hasRequestHeader(safeOptions.headers, 'host')) {
                 safeOptions.headers = {
                     ...safeOptions.headers,
-                    Host: ssrfResult.hostname
+                    host: ssrfResult.hostname
                 };
             }
 
@@ -221,7 +252,7 @@ export class NsHttpClient implements IHttpClient {
 
             // 应用正向代理配置
             if (this.forwardProxy) {
-                this.applyForwardProxy(safeOptions);
+                this.applyForwardProxy(safeOptions, forwardProxyDecision);
             }
 
             // 发起请求
@@ -246,6 +277,17 @@ export class NsHttpClient implements IHttpClient {
         }
     }
 
+    /**
+     * 按 HTTP 头大小写不敏感规则判断请求头是否已存在。
+     */
+    private hasRequestHeader(headers: HttpRequestOptions['headers'], headerName: string): boolean {
+        if (!headers) {
+            return false;
+        }
+        const lowerHeaderName = headerName.toLowerCase();
+        return Object.keys(headers).some(key => key.toLowerCase() === lowerHeaderName);
+    }
+
     /**
      * 便捷方法：GET 请求
      */
@@ -472,16 +514,40 @@ export class NsHttpClient implements IHttpClient {
     /**
      * 应用正向代理配置
      * @param options 请求选项
+     * @param decision 已解析的正向代理路由决策
      */
-    private applyForwardProxy(options: HttpRequestOptions): void {
+    private applyForwardProxy(
+        options: HttpRequestOptions,
+        decision = this.resolveForwardProxyDecision(options.url)
+    ): void {
+        this.applyForwardProxyDecision(options, decision);
+    }
+
+    /**
+     * 解析正向代理路由决策
+     * @param url 请求 URL
+     */
+    private resolveForwardProxyDecision(url: string): ForwardProxyDecision {
         if (!this.forwardProxy || !this.forwardProxy.enabled) {
-            return;
+            return {
+                shouldProxy: false,
+                reason: 'disabled'
+            };
         }
 
         const { https_proxy, http_proxy, no_proxy } = this.forwardProxy;
 
         // 解析目标 URL
-        const targetUrl = new URL(options.url);
+        let targetUrl: URL;
+        try {
+            targetUrl = new URL(url);
+        } catch {
+            return {
+                shouldProxy: false,
+                reason: 'invalid_url'
+            };
+        }
+
         const hostname = targetUrl.hostname;
 
         // 检查 no_proxy 规则（使用传统匹配模式）
@@ -489,26 +555,72 @@ export class NsHttpClient implements IHttpClient {
         if (noProxyRegExps.length > 0 && hostname) {
             for (const noProxyRegex of noProxyRegExps) {
                 if (noProxyRegex.test(hostname)) {
-                    this.logger.debug('Skip proxy for no_proxy matched host', {
+                    return {
+                        shouldProxy: false,
+                        reason: 'no_proxy',
                         hostname,
                         pattern: noProxyRegex.source
-                    });
-                    return;
+                    };
                 }
             }
         }
 
         const protocol = targetUrl.protocol || 'http:';
-        const isHttps = /https:?/.test(protocol);
+        if (protocol !== 'http:' && protocol !== 'https:') {
+            return {
+                shouldProxy: false,
+                reason: 'unsupported_protocol',
+                hostname,
+                protocol
+            };
+        }
+
+        const isHttps = protocol === 'https:';
         const proxyUrl = isHttps ? https_proxy : http_proxy;
 
         if (!proxyUrl) {
-            this.logger.warn('Forward proxy enabled but proxy URL not configured', {
+            return {
+                shouldProxy: false,
+                reason: 'missing_proxy_url',
+                hostname,
                 protocol
-            });
+            };
+        }
+
+        return {
+            shouldProxy: true,
+            hostname,
+            protocol,
+            isHttps,
+            proxyUrl
+        };
+    }
+
+    /**
+     * 根据已解析的路由决策应用正向代理配置
+     * @param options 请求选项
+     * @param decision 正向代理路由决策
+     */
+    private applyForwardProxyDecision(options: HttpRequestOptions, decision: ForwardProxyDecision): void {
+        if (!decision.shouldProxy) {
+            if (decision.reason === 'no_proxy') {
+                this.logger.debug('Skip proxy for no_proxy matched host', {
+                    hostname: decision.hostname,
+                    pattern: decision.pattern
+                });
+                return;
+            }
+
+            if (decision.reason === 'missing_proxy_url') {
+                this.logger.warn('Forward proxy enabled but proxy URL not configured', {
+                    protocol: decision.protocol
+                });
+            }
             return;
         }
 
+        const { proxyUrl, isHttps, protocol } = decision;
+
         // 将代理信息附加到请求元数据中，由适配器处理
         options.meta = {
             ...options.meta,
@@ -543,4 +655,3 @@ export class NsHttpClient implements IHttpClient {
         return this.ssrfGuard.getDnsCacheSize();
     }
 }
-

package/src/config.ts

@@ -10,25 +10,41 @@ import {
     MAX_DNS_CACHE_TTL
 } from './const';
 
+function omitNil<T extends object>(config?: Partial<T> | null): Partial<T> {
+    if (!config) {
+        return {};
+    }
+
+    return Object.fromEntries(
+        Object.entries(config).filter(([, value]) => value !== undefined && value !== null)
+    ) as Partial<T>;
+}
+
 /**
  * 合并配置
  * @param userConfig 用户配置
  * @returns 完整配置
  */
 export function mergeConfig(userConfig: PartialHttpClientConfig = {}): HttpClientConfig {
+    // 调用方常用 options?.xxx 或空值占位组装 Partial 配置，null/undefined 不能覆盖库内默认值。
+    const normalizedUserConfig = userConfig ?? {};
+    const securityConfig = omitNil(normalizedUserConfig.security);
+    const loggingConfig = omitNil(normalizedUserConfig.logging);
+    const requestConfig = omitNil(normalizedUserConfig.request);
+
     return {
-        adapter: userConfig.adapter ?? DEFAULT_HTTP_CLIENT_CONFIG.adapter,
+        adapter: normalizedUserConfig.adapter ?? DEFAULT_HTTP_CLIENT_CONFIG.adapter,
         security: {
             ...DEFAULT_SECURITY_CONFIG,
-            ...userConfig.security
+            ...securityConfig
         },
         logging: {
             ...DEFAULT_LOGGING_CONFIG,
-            ...userConfig.logging
+            ...loggingConfig
         },
         request: {
             ...DEFAULT_REQUEST_CONFIG,
-            ...userConfig.request
+            ...requestConfig
         }
     };
 }
@@ -83,4 +99,3 @@ export function validateConfig(config: HttpClientConfig): void {
         throw new Error('Body max length must be positive.');
     }
 }
-

package/src/security/ssrf.guard.ts

@@ -9,6 +9,7 @@ import type {
     ISsrfGuard,
     SecurityConfig,
     SsrfGuardResult,
+    SsrfGuardValidateOptions
 } from '../types';
 import { SecurityError } from '../types';
 import { DnsValidator } from './dns.validator';
@@ -36,9 +37,10 @@ export class SsrfGuard implements ISsrfGuard {
     /**
      * 验证 URL 是否安全
      * @param url 要验证的 URL
+     * @param options 验证选项
      * @returns 验证结果
      */
-    public async validate(url: string): Promise<SsrfGuardResult> {
+    public async validate(url: string, options: SsrfGuardValidateOptions = {}): Promise<SsrfGuardResult> {
         let parsedUrl: URL;
 
         try {
@@ -100,11 +102,17 @@ export class SsrfGuard implements ISsrfGuard {
         }
 
         // 第三步：DNS 解析和验证
-        if (!this.config.enableDnsValidation) {
+        if (!this.config.enableDnsValidation || options.skipDnsValidation) {
+            // 走正向代理时，目标域名由代理侧解析，本机 DNS 结果不代表实际连接目标。
+            const dnsValidationSkipped = Boolean(this.config.enableDnsValidation && options.skipDnsValidation);
             return {
                 passed: true,
                 originalUrl: url,
-                hostname
+                hostname,
+                ...(dnsValidationSkipped && {
+                    dnsValidationSkipped,
+                    dnsValidationSkipReason: options.skipDnsValidationReason
+                })
             };
         }
 
@@ -147,11 +155,15 @@ export class SsrfGuard implements ISsrfGuard {
     /**
      * 验证并返回安全的 URL
      * @param url 要验证的 URL
+     * @param options 验证选项
      * @returns 安全的 URL 和验证结果
      * @throws {SecurityError} 验证失败时抛出错误
      */
-    public async validateAndGetSafeUrl(url: string): Promise<{ safeUrl: string, result: SsrfGuardResult }> {
-        const result = await this.validate(url);
+    public async validateAndGetSafeUrl(
+        url: string,
+        options: SsrfGuardValidateOptions = {}
+    ): Promise<{ safeUrl: string, result: SsrfGuardResult }> {
+        const result = await this.validate(url, options);
 
         if (!result.passed) {
             throw new SecurityError(
@@ -221,4 +233,3 @@ export class SsrfGuard implements ISsrfGuard {
         return { ...this.config };
     }
 }
-

package/src/types/security.ts

@@ -71,10 +71,24 @@ export interface SsrfGuardResult {
     resolvedIps?: string[];
     /** 安全的 IP 地址（如果进行了 DNS 解析且通过验证） */
     safeIp?: string;
+    /** 是否因外部路由决策跳过目标域名 DNS 校验 */
+    dnsValidationSkipped?: boolean;
+    /** 跳过目标域名 DNS 校验的原因 */
+    dnsValidationSkipReason?: string;
     /** 失败原因 */
     reason?: string;
 }
 
+/**
+ * SSRF 防护验证选项
+ */
+export interface SsrfGuardValidateOptions {
+    /** 跳过目标域名 DNS 校验，通常用于目标域名由正向代理解析的场景 */
+    skipDnsValidation?: boolean;
+    /** 跳过目标域名 DNS 校验的原因 */
+    skipDnsValidationReason?: string;
+}
+
 /**
  * SSRF 防护接口
  */
@@ -82,17 +96,22 @@ export interface ISsrfGuard {
     /**
      * 验证 URL 是否安全
      * @param url 要验证的 URL
+     * @param options 验证选项
      * @returns 验证结果
      */
-    validate: (url: string) => Promise<SsrfGuardResult>;
+    validate: (url: string, options?: SsrfGuardValidateOptions) => Promise<SsrfGuardResult>;
 
     /**
      * 验证并返回安全的 URL
      * @param url 要验证的 URL
+     * @param options 验证选项
      * @returns 安全的 URL 和验证结果
      * @throws {SecurityError} 验证失败时抛出错误
      */
-    validateAndGetSafeUrl: (url: string) => Promise<{ safeUrl: string, result: SsrfGuardResult }>;
+    validateAndGetSafeUrl: (
+        url: string,
+        options?: SsrfGuardValidateOptions
+    ) => Promise<{ safeUrl: string, result: SsrfGuardResult }>;
 
     /**
      * 更新配置
@@ -123,4 +142,3 @@ export interface ISsrfGuard {
     getConfig: () => SecurityConfig;
 }
 
-