nstarter-http-request 0.1.8 → 0.1.10

package/dist/types/types/security.d.ts

@@ -65,9 +65,22 @@ 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 防护接口
  */
@@ -75,16 +88,18 @@ 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<{
+    validateAndGetSafeUrl: (url: string, options?: SsrfGuardValidateOptions) => Promise<{
         safeUrl: string;
         result: SsrfGuardResult;
     }>;

package/dist/types/types/security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../src/types/security.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,SAAS;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU;IACV,GAAG,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,WAAW;IACX,KAAK,EAAE,OAAO,CAAC;IACf,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,eAAe;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,qBAAqB;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,WAAW;IACX,KAAK,EAAE,OAAO,CAAC;IACf,UAAU;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,aAAa;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,qBAAqB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IAE9F;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;IAExD;;OAEG;IACH,aAAa,EAAE,MAAM,IAAI,CAAC;IAE1B;;;OAGG;IACH,eAAe,EAAE,MAAM,MAAM,CAAC;IAE9B;;OAEG;IACH,oBAAoB,EAAE,MAAM,IAAI,CAAC;IAEjC;;;OAGG;IACH,SAAS,EAAE,MAAM,cAAc,CAAC;CACnC"}
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../src/types/security.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,SAAS;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU;IACV,GAAG,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,WAAW;IACX,KAAK,EAAE,OAAO,CAAC;IACf,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,eAAe;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,qBAAqB;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,WAAW;IACX,KAAK,EAAE,OAAO,CAAC;IACf,UAAU;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,aAAa;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,uBAAuB;IACvB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,WAAW;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB;IACvB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IAExF;;;;;;OAMG;IACH,qBAAqB,EAAE,CACnB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,wBAAwB,KACjC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IAE3D;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;IAExD;;OAEG;IACH,aAAa,EAAE,MAAM,IAAI,CAAC;IAE1B;;;OAGG;IACH,eAAe,EAAE,MAAM,MAAM,CAAC;IAE9B;;OAEG;IACH,oBAAoB,EAAE,MAAM,IAAI,CAAC;IAEjC;;;OAGG;IACH,SAAS,EAAE,MAAM,cAAc,CAAC;CACnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nstarter-http-request",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "nstarter HTTP 请求客户端插件",
   "license": "MIT",
   "repository": {

package/src/adapter/undici.adapter.ts

@@ -17,6 +17,13 @@ import undici, {
 import { STATUS_CODES } from 'http';
 import { EClientAdapter } from '../const';
 
+interface RequestTimeoutState {
+    signal?: AbortSignal;
+    timeout?: number;
+    readonly timedOut: boolean;
+    cleanup: () => void;
+}
+
 /**
  * Undici 适配器
  */
@@ -42,8 +49,9 @@ export class UndiciAdapter extends BaseHttpAdapter {
         const fullUrl = this.buildUrl(options.url, options.params);
         const headers = this.prepareHeaders(options.headers);
         const body = this.prepareBody(options.body, headers);
-        const dispatcher = this.buildDispatcher(options);
-        const undiciOptions = this.buildUndiciOptions(options, headers, body, dispatcher);
+        const timeoutState = this.createRequestTimeoutState(options);
+        const dispatcher = this.buildDispatcher(options, timeoutState.timeout);
+        const undiciOptions = this.buildUndiciOptions(options, headers, body, dispatcher, timeoutState);
 
         try {
             const startTime = Date.now();
@@ -57,6 +65,10 @@ export class UndiciAdapter extends BaseHttpAdapter {
                 duration
             });
 
+            if (options.responseType === 'stream') {
+                timeoutState.cleanup();
+            }
+
             const data = await this.readResponseBody<T>(response, options.responseType);
 
             const httpResponse: HttpResponse<T> = {
@@ -72,7 +84,18 @@ export class UndiciAdapter extends BaseHttpAdapter {
 
             return httpResponse;
         } catch (error: unknown) {
+            if (timeoutState.timedOut) {
+                throw new HttpError(
+                    `timeout of ${ timeoutState.timeout }ms exceeded`,
+                    'ECONNABORTED',
+                    undefined,
+                    undefined,
+                    options
+                );
+            }
             throw this.handleUndiciError(error, options);
+        } finally {
+            timeoutState.cleanup();
         }
     }
 
@@ -130,13 +153,15 @@ export class UndiciAdapter extends BaseHttpAdapter {
     /**
      * 构建 Dispatcher（代理或 TLS 配置）
      * @param options 请求选项
+     * @param timeout 请求总超时时间
      */
-    private buildDispatcher(options: HttpRequestOptions): Dispatcher | undefined {
+    private buildDispatcher(options: HttpRequestOptions, timeout?: number): Dispatcher | undefined {
         let dispatcher: Dispatcher | undefined;
 
         // 如果 rejectUnauthorized 为 false，需要创建 Agent 来设置 TLS 选项
         if (!this.securityConfig.rejectUnauthorized) {
             dispatcher = new Agent({
+                ...(this.isPositiveTimeout(timeout) ? { connectTimeout: timeout } : {}),
                 connect: {
                     rejectUnauthorized: false
                 }
@@ -145,13 +170,13 @@ export class UndiciAdapter extends BaseHttpAdapter {
 
         // 有代理时，创建 ProxyAgent
         if (this.requestConfig.proxy) {
-            dispatcher = this.createGlobalProxyAgent();
+            dispatcher = this.createGlobalProxyAgent(timeout);
         }
 
         // 设置正向代理（如果请求元数据中包含代理信息，会覆盖全局代理配置）
         const forwardProxyMeta = options.meta?.__forwardProxy;
         if (forwardProxyMeta) {
-            dispatcher = this.createForwardProxyAgent(forwardProxyMeta.proxyUrl);
+            dispatcher = this.createForwardProxyAgent(forwardProxyMeta.proxyUrl, timeout);
         }
 
         return dispatcher;
@@ -159,8 +184,9 @@ export class UndiciAdapter extends BaseHttpAdapter {
 
     /**
      * 创建全局代理 Agent
+     * @param timeout 请求总超时时间
      */
-    private createGlobalProxyAgent(): ProxyAgent {
+    private createGlobalProxyAgent(timeout?: number): ProxyAgent {
         const { protocol, host, port, auth } = this.requestConfig.proxy!;
         let proxyUrl = `${ protocol }://${ host }:${ port }`;
 
@@ -172,6 +198,7 @@ export class UndiciAdapter extends BaseHttpAdapter {
 
         const agent = new ProxyAgent({
             uri: proxyUrl,
+            ...(this.isPositiveTimeout(timeout) ? { connectTimeout: timeout } : {}),
             connect: {
                 rejectUnauthorized: this.securityConfig.rejectUnauthorized
             }
@@ -190,10 +217,12 @@ export class UndiciAdapter extends BaseHttpAdapter {
     /**
      * 创建正向代理 Agent
      * @param proxyUrl 代理 URL
+     * @param timeout 请求总超时时间
      */
-    private createForwardProxyAgent(proxyUrl: string): ProxyAgent {
+    private createForwardProxyAgent(proxyUrl: string, timeout?: number): ProxyAgent {
         const agent = new ProxyAgent({
             uri: proxyUrl,
+            ...(this.isPositiveTimeout(timeout) ? { connectTimeout: timeout } : {}),
             connect: {
                 rejectUnauthorized: this.securityConfig.rejectUnauthorized
             }
@@ -214,19 +243,67 @@ export class UndiciAdapter extends BaseHttpAdapter {
         options: HttpRequestOptions,
         headers: Record<string, string | string[]>,
         body: Dispatcher.DispatchOptions['body'],
-        dispatcher?: Dispatcher
+        dispatcher?: Dispatcher,
+        timeoutState?: RequestTimeoutState
     ): Parameters<typeof undici.request>[1] {
+        const timeout = this.resolveTimeout(options);
         return {
             method: options.method as Dispatcher.HttpMethod,
             headers,
             body,
-            bodyTimeout: options.timeout ?? this.requestConfig.timeout,
-            headersTimeout: options.timeout ?? this.requestConfig.timeout,
+            bodyTimeout: timeout,
+            headersTimeout: timeout,
             maxRedirections: this.requestConfig.maxRedirects,
+            ...(timeoutState?.signal && { signal: timeoutState.signal }),
             ...(dispatcher && { dispatcher }),
         };
     }
 
+    /**
+     * 创建请求总耗时控制器。
+     * undici 的 headersTimeout/bodyTimeout 只覆盖阶段等待；这里补齐 axios timeout 的整次请求预算语义。
+     */
+    private createRequestTimeoutState(options: HttpRequestOptions): RequestTimeoutState {
+        const timeout = this.resolveTimeout(options);
+        if (!this.isPositiveTimeout(timeout)) {
+            return {
+                timedOut: false,
+                cleanup: () => {}
+            };
+        }
+
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        timer.unref?.();
+
+        return {
+            signal: controller.signal,
+            timeout,
+            get timedOut() {
+                return timedOut;
+            },
+            cleanup: () => clearTimeout(timer)
+        };
+    }
+
+    /**
+     * 获取请求级超时时间。
+     */
+    private resolveTimeout(options: HttpRequestOptions): number {
+        return options.timeout ?? this.requestConfig.timeout;
+    }
+
+    /**
+     * 判断超时时间是否启用。
+     */
+    private isPositiveTimeout(timeout?: number): timeout is number {
+        return typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0;
+    }
+
     /**
      * 处理 Undici 错误
      * @param error 错误对象
@@ -347,7 +424,7 @@ export class UndiciAdapter extends BaseHttpAdapter {
                     return (await response.body.formData()) as T;
                 }
                 case 'json': {
-                    return (await response.body.json()) as T;
+                    return await this.readJsonResponseBody<T>(response);
                 }
                 default: {
                     const text = await response.body.text();
@@ -365,6 +442,23 @@ export class UndiciAdapter extends BaseHttpAdapter {
         }
     }
 
+    /**
+     * 按 axios 的默认兼容行为读取 JSON 响应。
+     * 空响应体或非 JSON 文本不应让成功状态码请求因为解析失败变成异常。
+     */
+    private async readJsonResponseBody<T>(response: Dispatcher.ResponseData): Promise<T> {
+        const text = await response.body.text();
+        if (!text) {
+            return text as T;
+        }
+
+        try {
+            return JSON.parse(text) as T;
+        } catch {
+            return text as T;
+        }
+    }
+
     /**
      * 获取状态文本
      * @param statusCode 状态码

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,16 +189,33 @@ 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,
@@ -221,7 +252,7 @@ export class NsHttpClient implements IHttpClient {
 
             // 应用正向代理配置
             if (this.forwardProxy) {
-                this.applyForwardProxy(safeOptions);
+                this.applyForwardProxy(safeOptions, forwardProxyDecision);
             }
 
             // 发起请求
@@ -483,16 +514,40 @@ export class NsHttpClient implements IHttpClient {
     /**
      * 应用正向代理配置
      * @param options 请求选项
+     * @param decision 已解析的正向代理路由决策
+     */
+    private applyForwardProxy(
+        options: HttpRequestOptions,
+        decision = this.resolveForwardProxyDecision(options.url)
+    ): void {
+        this.applyForwardProxyDecision(options, decision);
+    }
+
+    /**
+     * 解析正向代理路由决策
+     * @param url 请求 URL
      */
-    private applyForwardProxy(options: HttpRequestOptions): void {
+    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 规则（使用传统匹配模式）
@@ -500,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,

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;
 }
 
-