nstarter-http-request 0.1.0

package/src/security/dns.validator.ts

@@ -0,0 +1,170 @@
+/**
+ * DNS 验证器
+ */
+
+import { promises as dns } from 'node:dns';
+import { LRUCache } from 'lru-cache';
+import { CommonUtils } from '../utils';
+import {
+    DEFAULT_DNS_CACHE_TTL,
+    DEFAULT_DNS_RESOLVE_TIMEOUT,
+    DEFAULT_DNS_CACHE_MAX_SIZE
+} from '../const';
+import type {
+    DnsResult
+} from '../types';
+import { IpValidator } from './ip.validator';
+
+
+/**
+ * DNS 验证器类
+ */
+export class DnsValidator {
+    private cache: LRUCache<string, DnsResult>;
+    private cacheTtl: number;
+    private resolveTimeout: number;
+
+    constructor(
+        cacheTtl = DEFAULT_DNS_CACHE_TTL,
+        resolveTimeout = DEFAULT_DNS_RESOLVE_TIMEOUT,
+        maxCacheSize = DEFAULT_DNS_CACHE_MAX_SIZE
+    ) {
+        this.cacheTtl = cacheTtl;
+        this.resolveTimeout = resolveTimeout;
+        this.cache = new LRUCache<string, DnsResult>({
+            max: maxCacheSize,
+            ttl: cacheTtl,
+            // 启用 TTL 自动清理
+            ttlAutopurge: true,
+            // 更新访问时间，实现真正的 LRU
+            updateAgeOnGet: true,
+            // 更新访问时间时也更新 has() 调用
+            updateAgeOnHas: true,
+        });
+    }
+
+    /**
+     * 解析域名
+     * @param hostname 域名
+     * @returns DNS 解析结果
+     */
+    public async resolve(hostname: string): Promise<DnsResult> {
+        // 检查缓存
+        const cached = this.cache.get(hostname);
+        if (cached) {
+            return cached;
+        }
+
+        try {
+            // 尝试解析 IPv4 和 IPv6
+            const addresses: string[] = [];
+
+            try {
+                const ipv4Addresses = await CommonUtils.withTimeout(dns.resolve4(hostname), this.resolveTimeout, 'DNS resolution timed out');
+                addresses.push(...ipv4Addresses);
+            } catch {
+                // IPv4 解析失败，继续尝试 IPv6
+            }
+
+            try {
+                const ipv6Addresses = await CommonUtils.withTimeout(dns.resolve6(hostname), this.resolveTimeout, 'DNS resolution timed out');
+                addresses.push(...ipv6Addresses);
+            } catch {
+                // IPv6 解析失败
+            }
+
+            if (addresses.length === 0) {
+                throw new Error(`Unable to resolve hostname: ${ hostname }`);
+            }
+
+            const result: DnsResult = {
+                hostname,
+                addresses,
+                timestamp: Date.now(),
+                ttl: this.cacheTtl
+            };
+
+            // 存入缓存，LRUCache 会自动处理 TTL 和容量限制
+            this.cache.set(hostname, result);
+
+            return result;
+        } catch (error) {
+            throw new Error(
+                `DNS resolution failed for ${ hostname }: ${ error instanceof Error ? error.message : String(error) }`
+            );
+        }
+    }
+
+
+    /**
+     * 解析并验证域名（包括 IP 安全检查）
+     * @param hostname 域名
+     * @param allowPrivateIp 是否允许私有 IP
+     * @returns DNS 解析结果和验证结果
+     */
+    public async resolveAndValidate(
+        hostname: string,
+        allowPrivateIp = false
+    ): Promise<{ dnsResult: DnsResult, allValid: boolean, invalidIps: string[] }> {
+        const dnsResult = await this.resolve(hostname);
+        const validationResults = IpValidator.validateMany(dnsResult.addresses, allowPrivateIp);
+
+        const invalidIps = validationResults
+            .filter(result => !result.valid)
+            .map(result => result.ip);
+
+        return {
+            dnsResult,
+            allValid: invalidIps.length === 0,
+            invalidIps
+        };
+    }
+
+    /**
+     * 清空缓存
+     */
+    public clearCache(): void {
+        this.cache.clear();
+    }
+
+    /**
+     * 清除指定域名的缓存
+     * @param hostname 域名
+     */
+    public clearCacheFor(hostname: string): void {
+        this.cache.delete(hostname);
+    }
+
+    /**
+     * 获取缓存大小
+     * @returns 缓存条目数量
+     */
+    public getCacheSize(): number {
+        return this.cache.size;
+    }
+
+    /**
+     * 清理过期的缓存条目
+     * LRUCache 会自动清理过期条目（ttlAutopurge: true），此方法主动触发清理
+     */
+    public cleanExpiredCache(): void {
+        this.cache.purgeStale();
+    }
+
+    /**
+     * 获取缓存的最大容量
+     * @returns 最大缓存条目数量
+     */
+    public getMaxCacheSize(): number {
+        return this.cache.max;
+    }
+
+    /**
+     * 检查缓存中是否存在指定域名
+     * @param hostname 域名
+     * @returns 是否存在
+     */
+    public hasCache(hostname: string): boolean {
+        return this.cache.has(hostname);
+    }
+}

package/src/security/index.ts

@@ -0,0 +1,4 @@
+export * from './dns.validator';
+export * from './ip.validator';
+export * from './url.validator';
+export * from './ssrf.guard';

package/src/security/ip.validator.ts

@@ -0,0 +1,124 @@
+/**
+ * IP 地址验证器
+ */
+
+import {
+    isIPv4,
+    isIPv6
+} from 'node:net';
+import type { IpValidationResult } from '../types';
+import { IpRangeUtils } from '../utils';
+import {
+    COMPILED_IPV4_RANGES,
+    COMPILED_IPV6_RANGES
+} from '../const';
+
+
+/**
+ * IP 地址验证器类
+ */
+export class IpValidator {
+    /**
+     * 验证 IP 地址是否安全
+     * @param ip IP 地址
+     * @param allowPrivateIp 是否允许私有 IP
+     * @returns 验证结果
+     */
+    public static validate(ip: string, allowPrivateIp = false): IpValidationResult {
+        // 检查是否为有效的 IP 地址
+        const isV4 = isIPv4(ip);
+        const isV6 = isIPv6(ip);
+
+        if (!isV4 && !isV6) {
+            return {
+                valid: false,
+                ip,
+                isPrivate: false,
+                isLoopback: false,
+                isLinkLocal: false,
+                isMulticast: false,
+                isReserved: false,
+                reason: 'Invalid IP address format'
+            };
+        }
+
+        // 使用预编译的范围进行高性能检查
+        let isPrivate: boolean;
+        let isLoopback: boolean;
+        let isLinkLocal: boolean;
+        let isMulticast: boolean;
+        let isReserved: boolean;
+
+        if (isV4) {
+            isPrivate = IpRangeUtils.isIpv4InAnyCompiledRange(ip, COMPILED_IPV4_RANGES.private);
+            isLoopback = IpRangeUtils.isIpv4InAnyCompiledRange(ip, COMPILED_IPV4_RANGES.loopback);
+            isLinkLocal = IpRangeUtils.isIpv4InAnyCompiledRange(ip, COMPILED_IPV4_RANGES.linkLocal);
+            isMulticast = IpRangeUtils.isIpv4InAnyCompiledRange(ip, COMPILED_IPV4_RANGES.multicast);
+            isReserved = IpRangeUtils.isIpv4InAnyCompiledRange(ip, COMPILED_IPV4_RANGES.reserved);
+        } else {
+            isPrivate = IpRangeUtils.isIpv6InAnyCompiledRange(ip, COMPILED_IPV6_RANGES.private);
+            isLoopback = IpRangeUtils.isIpv6InAnyCompiledRange(ip, COMPILED_IPV6_RANGES.loopback);
+            isLinkLocal = IpRangeUtils.isIpv6InAnyCompiledRange(ip, COMPILED_IPV6_RANGES.linkLocal);
+            isMulticast = IpRangeUtils.isIpv6InAnyCompiledRange(ip, COMPILED_IPV6_RANGES.multicast);
+            isReserved = IpRangeUtils.isIpv6InAnyCompiledRange(ip, COMPILED_IPV6_RANGES.reserved);
+        }
+
+        // 基础验证信息
+        const baseResult = {
+            ip,
+            isPrivate,
+            isLoopback,
+            isLinkLocal,
+            isMulticast,
+            isReserved
+        };
+
+        // 检查是否为受限 IP - 按优先级顺序检查
+        const restrictions = [
+            { condition: isLoopback, reason: 'Loopback address is not allowed' },
+            { condition: isLinkLocal, reason: 'Link-local address is not allowed' },
+            { condition: isMulticast, reason: 'Multicast address is not allowed' },
+            { condition: isReserved, reason: 'Reserved address is not allowed' },
+            { condition: isPrivate && !allowPrivateIp, reason: 'Private IP address is not allowed' }
+        ];
+
+        for (const { condition, reason } of restrictions) {
+            if (condition) {
+                return {
+                    valid: false,
+                    ...baseResult,
+                    reason
+                };
+            }
+        }
+
+        return {
+            valid: true,
+            ...baseResult
+        };
+    }
+
+    /**
+     * 批量验证 IP 地址
+     * @param ips IP 地址列表
+     * @param allowPrivateIp 是否允许私有 IP
+     * @returns 验证结果列表
+     */
+    public static validateMany(
+        ips: string[],
+        allowPrivateIp = false
+    ): IpValidationResult[] {
+        return ips.map(ip => this.validate(ip, allowPrivateIp));
+    }
+
+    /**
+     * 检查是否所有 IP 地址都有效
+     * @param ips IP 地址列表
+     * @param allowPrivateIp 是否允许私有 IP
+     * @returns 是否所有 IP 都有效
+     */
+    public static validateAll(ips: string[], allowPrivateIp = false): boolean {
+        return this.validateMany(ips, allowPrivateIp).every(result => result.valid);
+    }
+}
+

package/src/security/ssrf.guard.ts

@@ -0,0 +1,224 @@
+/**
+ * SSRF 防护
+ * 整合 IP、DNS 和 URL 验证，防止服务器端请求伪造攻击
+ */
+
+import { URL } from 'node:url';
+import { isIP } from 'node:net';
+import type {
+    ISsrfGuard,
+    SecurityConfig,
+    SsrfGuardResult,
+} from '../types';
+import { SecurityError } from '../types';
+import { DnsValidator } from './dns.validator';
+import { IpValidator } from './ip.validator';
+import { UrlValidator } from './url.validator';
+
+/**
+ * SSRF 防护类
+ */
+export class SsrfGuard implements ISsrfGuard {
+    private dnsValidator: DnsValidator;
+    private urlValidator: UrlValidator;
+    private config: SecurityConfig;
+
+    constructor(config: SecurityConfig) {
+        this.config = config;
+        this.dnsValidator = new DnsValidator(
+            config.dnsCacheTtl,
+            undefined,  // 使用默认的 DNS 解析超时
+            config.dnsCacheMaxSize
+        );
+        this.urlValidator = new UrlValidator(config.whitelist, config.blacklist);
+    }
+
+    /**
+     * 验证 URL 是否安全
+     * @param url 要验证的 URL
+     * @returns 验证结果
+     */
+    public async validate(url: string): Promise<SsrfGuardResult> {
+        let parsedUrl: URL;
+
+        try {
+            parsedUrl = new URL(url);
+        } catch (error) {
+            return {
+                passed: false,
+                originalUrl: url,
+                hostname: '',
+                reason: 'Invalid URL format'
+            };
+        }
+
+        const hostname = parsedUrl.hostname;
+
+        // 第一步：URL 验证（黑白名单）
+        const urlValidation = this.urlValidator.validate(url);
+        if (!urlValidation.valid) {
+            return {
+                passed: false,
+                originalUrl: url,
+                hostname,
+                reason: urlValidation.reason
+            };
+        }
+
+        // 第二步：检查是否为 IP 地址
+        const ipVersion = isIP(hostname);
+        if (ipVersion !== 0) {
+            // 直接使用 IP 地址，需要验证 IP 安全性
+            if (!this.config.enableIpValidation) {
+                return {
+                    passed: true,
+                    originalUrl: url,
+                    hostname,
+                    resolvedIps: [hostname],
+                    safeIp: hostname
+                };
+            }
+
+            const ipValidation = IpValidator.validate(hostname, this.config.allowPrivateIp);
+            if (!ipValidation.valid) {
+                return {
+                    passed: false,
+                    originalUrl: url,
+                    hostname,
+                    resolvedIps: [hostname],
+                    reason: ipValidation.reason
+                };
+            }
+
+            return {
+                passed: true,
+                originalUrl: url,
+                hostname,
+                resolvedIps: [hostname],
+                safeIp: hostname
+            };
+        }
+
+        // 第三步：DNS 解析和验证
+        if (!this.config.enableDnsValidation) {
+            return {
+                passed: true,
+                originalUrl: url,
+                hostname
+            };
+        }
+
+        try {
+            const { dnsResult, allValid, invalidIps } = await this.dnsValidator.resolveAndValidate(
+                hostname,
+                this.config.allowPrivateIp
+            );
+
+            if (!allValid) {
+                return {
+                    passed: false,
+                    originalUrl: url,
+                    hostname,
+                    resolvedIps: dnsResult.addresses,
+                    reason: `DNS resolved to unsafe IP addresses: ${ invalidIps.join(', ') }`
+                };
+            }
+
+            // 选择第一个有效的 IP 地址
+            const safeIp = dnsResult.addresses[0];
+
+            return {
+                passed: true,
+                originalUrl: url,
+                hostname,
+                resolvedIps: dnsResult.addresses,
+                safeIp
+            };
+        } catch (error) {
+            return {
+                passed: false,
+                originalUrl: url,
+                hostname,
+                reason: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+
+    /**
+     * 验证并返回安全的 URL
+     * @param url 要验证的 URL
+     * @returns 安全的 URL 和验证结果
+     * @throws {SecurityError} 验证失败时抛出错误
+     */
+    public async validateAndGetSafeUrl(url: string): Promise<{ safeUrl: string, result: SsrfGuardResult }> {
+        const result = await this.validate(url);
+
+        if (!result.passed) {
+            throw new SecurityError(
+                result.reason || 'URL validation failed',
+                'SSRF_VALIDATION_FAILED',
+                url
+            );
+        }
+
+        return {
+            safeUrl: url,
+            result
+        };
+    }
+
+    /**
+     * 更新配置
+     * @param config 新的安全配置
+     */
+    public updateConfig(config: Partial<SecurityConfig>): void {
+        this.config = { ...this.config, ...config };
+
+        // 如果 DNS 缓存配置变更，需要重新创建 DNS 验证器
+        if (config.dnsCacheTtl !== undefined || config.dnsCacheMaxSize !== undefined) {
+            this.dnsValidator = new DnsValidator(
+                this.config.dnsCacheTtl,
+                undefined,
+                this.config.dnsCacheMaxSize
+            );
+        }
+
+        if (config.whitelist !== undefined || config.blacklist !== undefined) {
+            this.urlValidator = new UrlValidator(
+                config.whitelist ?? this.config.whitelist,
+                config.blacklist ?? this.config.blacklist
+            );
+        }
+    }
+
+    /**
+     * 清空 DNS 缓存
+     */
+    public clearDnsCache(): void {
+        this.dnsValidator.clearCache();
+    }
+
+    /**
+     * 获取 DNS 缓存大小
+     * @returns 缓存条目数量
+     */
+    public getDnsCacheSize(): number {
+        return this.dnsValidator.getCacheSize();
+    }
+
+    /**
+     * 清理过期的 DNS 缓存
+     */
+    public cleanExpiredDnsCache(): void {
+        this.dnsValidator.cleanExpiredCache();
+    }
+
+    /**
+     * 获取当前配置
+     * @returns 安全配置副本
+     */
+    public getConfig(): SecurityConfig {
+        return { ...this.config };
+    }
+}
+

package/src/security/url.validator.ts

@@ -0,0 +1,192 @@
+/**
+ * URL 验证器
+ */
+
+import { URL } from 'node:url';
+import type { UrlValidationResult } from '../types';
+import { DomainUtils } from '../utils';
+
+/**
+ * URL 验证器类
+ */
+export class UrlValidator {
+    private whitelist: string[];
+    private blacklist: string[];
+    private whitelistRegexps: RegExp[];
+    private blacklistRegexps: RegExp[];
+
+    constructor(whitelist: string[] = [], blacklist: string[] = []) {
+        this.whitelist = whitelist;
+        this.blacklist = blacklist;
+        // 预生成正则表达式，提高匹配性能和安全性
+        this.whitelistRegexps = DomainUtils.createDomainMatchers(whitelist);
+        this.blacklistRegexps = DomainUtils.createDomainMatchers(blacklist);
+    }
+
+    /**
+     * 验证 URL
+     * @param url URL 字符串
+     * @returns 验证结果
+     */
+    public validate(url: string): UrlValidationResult {
+        let parsedUrl: URL;
+
+        try {
+            parsedUrl = new URL(url);
+        } catch {
+            return {
+                valid: false,
+                url,
+                inWhitelist: false,
+                inBlacklist: false,
+                reason: 'Invalid URL format'
+            };
+        }
+
+        // 只允许 http 和 https 协议
+        if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+            return {
+                valid: false,
+                url,
+                inWhitelist: false,
+                inBlacklist: false,
+                reason: `Protocol ${ parsedUrl.protocol } is not allowed. Only http and https are supported.`
+            };
+        }
+
+        const hostname = parsedUrl.hostname;
+
+        // 检查白名单（使用预生成的正则表达式）
+        const inWhitelist = this.matchesAny(hostname, this.whitelistRegexps);
+        // 检查黑名单（使用预生成的正则表达式）
+        const inBlacklist = this.matchesAny(hostname, this.blacklistRegexps);
+
+        // 配了白名单, 优先使用白名单模式, 在名单内的域名通过, 其余拒绝.
+        // 同时配有黑名单, 黑名单辅助拒绝其余通过的域名.
+        if (this.whitelist.length > 0 && !inWhitelist) {
+            return {
+                valid: false,
+                url,
+                inWhitelist,
+                inBlacklist,
+                reason: 'Domain is not in whitelist'
+            };
+        }
+
+        // 配了黑名单, 使用黑名单模式, 在黑名单内的域名拒绝, 其余通过.
+        if (this.blacklist.length > 0 && inBlacklist) {
+            return {
+                valid: false,
+                url,
+                inWhitelist,
+                inBlacklist,
+                reason: 'Domain is in blacklist'
+            };
+        }
+
+        // 黑白名单没配的, 默认通过.
+        return {
+            valid: true,
+            url,
+            inWhitelist,
+            inBlacklist
+        };
+    }
+
+    /**
+     * 检查域名是否匹配任一模式（使用预生成的正则表达式）
+     * @param hostname 域名
+     * @param regexps 正则表达式列表
+     * @returns 是否匹配
+     */
+    private matchesAny(hostname: string, regexps: RegExp[]): boolean {
+        return regexps.some(regex => regex.test(hostname));
+    }
+
+    /**
+     * 更新白名单
+     * @param whitelist 新的白名单
+     */
+    public setWhitelist(whitelist: string[]): void {
+        this.whitelist = whitelist;
+        this.whitelistRegexps = DomainUtils.createDomainMatchers(whitelist);
+    }
+
+    /**
+     * 更新黑名单
+     * @param blacklist 新的黑名单
+     */
+    public setBlacklist(blacklist: string[]): void {
+        this.blacklist = blacklist;
+        this.blacklistRegexps = DomainUtils.createDomainMatchers(blacklist);
+    }
+
+    /**
+     * 添加到白名单
+     * @param patterns 要添加的模式
+     */
+    public addToWhitelist(...patterns: string[]): void {
+        this.whitelist.push(...patterns);
+        this.whitelistRegexps = DomainUtils.createDomainMatchers(this.whitelist);
+    }
+
+    /**
+     * 添加到黑名单
+     * @param patterns 要添加的模式
+     */
+    public addToBlacklist(...patterns: string[]): void {
+        this.blacklist.push(...patterns);
+        this.blacklistRegexps = DomainUtils.createDomainMatchers(this.blacklist);
+    }
+
+    /**
+     * 从白名单移除
+     * @param patterns 要移除的模式
+     */
+    public removeFromWhitelist(...patterns: string[]): void {
+        this.whitelist = this.whitelist.filter(p => !patterns.includes(p));
+        this.whitelistRegexps = DomainUtils.createDomainMatchers(this.whitelist);
+    }
+
+    /**
+     * 从黑名单移除
+     * @param patterns 要移除的模式
+     */
+    public removeFromBlacklist(...patterns: string[]): void {
+        this.blacklist = this.blacklist.filter(p => !patterns.includes(p));
+        this.blacklistRegexps = DomainUtils.createDomainMatchers(this.blacklist);
+    }
+
+    /**
+     * 获取白名单
+     * @returns 白名单副本
+     */
+    public getWhitelist(): string[] {
+        return [...this.whitelist];
+    }
+
+    /**
+     * 获取黑名单
+     * @returns 黑名单副本
+     */
+    public getBlacklist(): string[] {
+        return [...this.blacklist];
+    }
+
+    /**
+     * 清空白名单
+     */
+    public clearWhitelist(): void {
+        this.whitelist = [];
+        this.whitelistRegexps = [];
+    }
+
+    /**
+     * 清空黑名单
+     */
+    public clearBlacklist(): void {
+        this.blacklist = [];
+        this.blacklistRegexps = [];
+    }
+}
+