whistle.easy-proxy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EasyProxy Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# whistle.easy-proxy
+
+> 基于 whistle 的 GitHub 直连加速插件 — DNS 防污染 + DoH 解析 + SNI 改写 + 智能 IP 选路，一键解决国内 GitHub 访问慢/不稳定问题。
+
+[![npm version](https://img.shields.io/npm/v/whistle.easy-proxy.svg)](https://www.npmjs.com/package/whistle.easy-proxy)
+[![license](https://img.shields.io/npm/l/whistle.easy-proxy.svg)](https://github.com/sqlwwx/easy-proxy/blob/master/LICENSE)
+[![node version](https://img.shields.io/node/v/whistle.easy-proxy.svg)](https://nodejs.org/)
+
+## 功能特性
+
+- **DNS 防污染**：通过 DoH 解析真实 IP，绕过 DNS 污染
+- **智能 IP 选路**：多候选 IP 自动选择最优线路
+- **SNI 改写**：绕过 SNI 检测，支持默认 SNI 和域名映射
+- **上游代理**：灵活配置域名级别的代理转发
+- **拦截规则**：内置 80+ 条 GitHub / npm / CDN 优化规则
+- **Web 管理面板**：测速、选路、配置修改，所见即所得
+- **跨平台**：支持 macOS / Windows，系统代理一键切换
+
+## 快速开始
+
+### 前置依赖
+
+- Node.js >= 22.0.0
+
+### 3 步启动
+
+```bash
+# 1. 全局安装
+npm i -g whistle.easy-proxy
+
+# 2. 启动 whistle（自动设系统代理 + 安装根证书）
+easy-proxy start --init
+
+# 3. 开启 GitHub 加速
+easy-proxy accel on
+```
+
+现在访问 `github.com`，流量会自动走最优线路。
+
+### 验证加速效果
+
+```bash
+# 检查加速状态
+easy-proxy accel status
+
+# 检测网络延迟
+easy-proxy network delay
+
+# 打开 Web 管理面板
+open http://local.whistlejs.com/plugin.easy-proxy/
+```
+
+## 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `easy-proxy start --init` | 启动 whistle + 自动设代理 + 安装证书 |
+| `easy-proxy stop` | 停止 whistle |
+| `easy-proxy accel on / off` | 开启 / 关闭 GitHub 加速 |
+| `easy-proxy accel status` | 查看加速状态 |
+| `easy-proxy accel dns` | 刷新 DNS 缓存 |
+| `easy-proxy host add <域名> <IP>` | 添加手动 IP 覆盖 |
+| `easy-proxy health` | 综合健康检查 |
+| `easy-proxy status` | 查看整体状态 |
+
+**完整命令参考** → [docs/cli.md](docs/cli.md)
+
+## 配置文件
+
+配置文件路径：`~/.easy-proxy/config.json`
+
+```jsonc
+{
+  "enabled": true,              // 加速总开关
+  "doh": {
+    "bootstrapIp": "8.8.8.8",  // DoH 引导 IP
+    "host": "dns.google",       // DoH 服务器域名
+    "path": "/resolve",         // DoH 解析路径
+    "port": 443                 // DoH 端口
+  },
+  "ipCacheTtl": 600,            // IP 缓存时间（秒），默认 10 分钟
+  "sniRewrite": {
+    "enabled": false,           // SNI 改写开关（默认关闭）
+    "defaultSni": null,         // 默认 SNI 域名
+    "sniMap": {}                // 域名 → SNI 映射
+  },
+  "hosts": [],                  // 手动覆盖列表
+  "upstreamProxies": [],        // 上游代理列表
+  "proxyBypassDomains": null,   // 跳过代理的域名列表（null 表示默认 150+ 条）
+  "interceptEnabled": true,     // 拦截规则总开关
+  "interceptRules": {}           // 自定义拦截规则（空对象使用默认 80+ 条）
+}
+```
+
+**配置说明 / 热重载 / 验证规则** → [docs/architecture.md](docs/architecture.md)
+
+## Web 管理面板
+
+启动 whistle 后访问 `http://local.whistlejs.com/plugin.easy-proxy/`，可以：
+
+| 功能 | 说明 |
+|------|------|
+| 加速总开关 | 一键开关 GitHub 加速 |
+| 域名列表 | 查看所有 GitHub 域名的解析 IP 和延迟 |
+| 测速 | 并行测试所有候选 IP，一键选用最优 |
+| 手动覆盖 | Web 界面添加/删除域名→IP 覆盖 |
+| SNI 映射 | Web 界面管理 SNI 改写映射 |
+| 刷新 IP | 刷新全部或单个域名的 DNS 解析缓存 |
+
+**Web 面板 API 列表** → [docs/cli.md#web-面板-api](docs/cli.md)
+
+## 加速原理
+
+```
+用户请求 github.com
+    ↓
+┌─ whistle host:// 规则（覆盖 95% 场景）──────────┐
+│  DoH 解析真实 IP（绕过 DNS 污染）               │
+│  映射到降速域名，走国内 CDN 或最优路由           │
+└────────────────────────────────────────────────┘
+    ↓（可选）
+┌─ SNI 改写钩子（覆盖剩余 5% 场景）──────────────┐
+│  直连真实 IP + 改写 ClientHello SNI             │
+└────────────────────────────────────────────────┘
+    ↓
+TCP 隧道 → IP 直连 + TLS 握手
+```
+
+**完整原理 / IP 选择策略 / 技术细节** → [docs/architecture.md](docs/architecture.md)
+
+## 故障排查
+
+最常见的 3 个问题：
+
+| 问题 | 快速解决 |
+|------|---------|
+| GitHub 无法访问 | `easy-proxy start --init && easy-proxy accel on && easy-proxy proxy on` |
+| 访问速度慢 | `easy-proxy accel dns` 刷新缓存，或在 Web 面板测速选 IP |
+| 证书不受信任 | `easy-proxy cert install` 重新安装根证书 |
+
+**完整故障排查** → [docs/troubleshooting.md](docs/troubleshooting.md)
+
+## 与其他 whistle 插件配合
+
+`w2` 命令会随 whistle.easy-proxy 一起安装：
+
+```bash
+w2 install whistle.chii     # 远程调试（替代 Chrome DevTools）
+w2 install whistle.script   # 脚本扩展（自定义请求/响应修改）
+w2 install whistle.vase     # Mock 数据服务
+```
+
+## 贡献
+
+欢迎贡献代码！请参阅 [贡献指南](docs/contributing.md) 了解开发环境设置、代码规范和提交流程。
+
+## License
+
+MIT

package/bin/easy-proxy.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { registerAllCommands } = require('../lib/cli/commands');
+
+program
+  .name('easy-proxy')
+  .description('EasyProxy CLI — GitHub 加速、SNI 改写、Hosts 管理')
+  .version('1.0.0');
+
+// 注册所有命令
+registerAllCommands(program);
+
+program.parse(process.argv);

package/index.js

@@ -0,0 +1,125 @@
+const { loadConfig } = require('./lib/config');
+const resolver = require('./lib/plugin/resolver');
+const ui = require('./lib/plugin/ui');
+const sni = require('./lib/plugin/sni-agent');
+const ruleEngine = require('./lib/plugin/rule-engine');
+const ruleActions = require('./lib/plugin/rule-actions');
+
+function extractHost(fullUrl) {
+  if (!fullUrl) return null;
+  try {
+    let u = fullUrl;
+    if (!/^https?:\/\//i.test(u)) u = `http://${u.replace(/^\/\//, '')}`;
+    const url = new URL(u);
+    return url.hostname;
+  } catch (_e) {
+    const m = /(?:https?:\/\/)?([^/:]+)/i.exec(fullUrl);
+    return m ? m[1] : null;
+  }
+}
+
+async function handleProxy(req, client, next, _options, config) {
+  const oreq = req.originalReq || {};
+  const fullUrl = oreq.fullUrl || oreq.url || req.url || '';
+  const host = extractHost(fullUrl);
+  if (!host) return next();
+
+  const path = ruleEngine.extractPath(fullUrl);
+
+  // 1. 拦截规则（高优先级）
+  if (config.interceptEnabled !== false) {
+    const rules = config.interceptRules || require('./lib/plugin/default-rules');
+    const matched = ruleEngine.matchRules(host, path, rules);
+    if (matched) {
+      const ctx = { host: host, path: path, config: config, resolver: resolver, sni: sni };
+      try {
+        await ruleActions.applyActions(req, client, next, matched, ctx);
+      } catch (_e) {
+        // 动作执行失败，放行
+        if (typeof next === 'function') return next();
+      }
+      return;
+    }
+  }
+
+  // 2. GitHub 加速：DoH 解析真实 IP，绕过 DNS 污染
+  if (!config.enabled) return next();
+  if (!ui.isTarget(host)) return next();
+
+  const ip = resolver.resolve(host);
+  if (!ip) return next();
+
+  // 可选：SNI 改写模式，直连真实 IP，改写 ClientHello SNI
+  if (config.sniRewrite?.enabled) {
+    const sniVal = config.sniRewrite.sniMap?.[host] || config.sniRewrite.defaultSni || host;
+    return sni.forward(req, { domain: host, ip, port: 443, servername: sniVal });
+  }
+
+  // 默认：whistle host:// 映射（推荐方式）
+  req.setReqRules(`${host} host://${ip}`);
+  req.passThrough();
+}
+
+// === Whistle plugin exports ===
+
+// UI server hook: management dashboard + REST API
+exports.uiServer = (server, options) => {
+  const config = loadConfig(options);
+  resolver.setConfig(config);
+
+  server.on('request', (req, client) => {
+    try {
+      handleUi(req, client, options, config);
+    } catch (_e) {
+      client.statusCode = 500;
+      client.end('Internal Server Error');
+    }
+  });
+};
+
+function isUiRequest(req) {
+  const oreq = req.originalReq || {};
+  if (oreq.isUIRequest) return true;
+  const url = req.url || '';
+  return url.startsWith('/plugin.') || url.startsWith('/api/') || url === '/' || url === '';
+}
+
+function handleUi(req, client, options, config) {
+  const url = (req.url || '/').split('?')[0];
+  if (url.startsWith('/api/')) {
+    return ui.handleApi(req, client, options, config);
+  }
+  client.statusCode = 200;
+  client.setHeader('content-type', 'text/html; charset=utf-8');
+  client.end(ui.renderDashboard(config));
+}
+
+// 使用 init hook 而不是 server hook，避免 whistle 的隧道处理干扰
+// 这是关键修复：exports.server 会导致 whistle 的 HTTPS 隧道代理规则（如 proxy://）失效
+// 而 exports.init 有相同的参数和功能，但不会干扰 HTTPS 代理
+exports.init = (server, options) => {
+  const config = loadConfig(options);
+  resolver.setConfig(config);
+
+  server.on('request', (req, client, next) => {
+    try {
+      if (isUiRequest(req)) return handleUi(req, client, options, config);
+    } catch (_e) {
+      /* fall through */
+    }
+    handleProxy(req, client, next, options, config).catch(() => {
+      if (typeof next === 'function') return next();
+    });
+  });
+
+  server.on('upgrade', (_req, _client, next) => {
+    if (typeof next === 'function') next();
+  });
+};
+
+// Expose for CLI usage
+exports.extractHost = extractHost;
+exports.config = { loadConfig, saveConfig: require('./lib/config').saveConfig };
+exports.resolver = resolver;
+exports.ruleEngine = ruleEngine;
+exports.ruleActions = ruleActions;

package/lib/cert-check.js

@@ -0,0 +1,211 @@
+/**
+ * 证书状态检查模块
+ * 检查 whistle 根证书是否存在、是否已安装到系统信任库、以及有效期。
+ *
+ * whistle 证书路径: ~/.WhistleAppData/.whistle/certs/root.crt
+ * macOS 信任检查: security find-certificate
+ * Windows 信任检查: certutil
+ * 有效期解析: 优先用 openssl（macOS 内置），回退到 node-forge
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execSync } = require('node:child_process');
+
+const HOME = os.homedir();
+const IS_MACOS = os.platform() === 'darwin';
+const IS_WINDOWS = os.platform() === 'win32';
+
+// whistle 默认证书路径（w2 start 生成的路径）
+const CERT_PATHS = [
+  path.join(HOME, '.WhistleAppData', '.whistle', 'certs', 'root.crt'),
+  path.join(HOME, '.WhistleAppData', '.whistle', 'certs', 'root.cer'),
+];
+
+/**
+ * 查找 whistle 根证书文件
+ * @returns {string|null}
+ */
+function findCertFile() {
+  for (var i = 0; i < CERT_PATHS.length; i++) {
+    if (fs.existsSync(CERT_PATHS[i])) {
+      return CERT_PATHS[i];
+    }
+  }
+  return null;
+}
+
+/**
+ * 用 openssl 解析证书有效期
+ * @param {string} certPath
+ * @returns {{notBefore: Date, notAfter: Date, subject: string}|null}
+ */
+function parseCertWithOpenssl(certPath) {
+  try {
+    var subject = execSync(`openssl x509 -in "${certPath}" -noout -subject`, {
+      encoding: 'utf-8',
+    }).trim();
+    var dates = execSync(`openssl x509 -in "${certPath}" -noout -dates`, {
+      encoding: 'utf-8',
+    }).trim();
+    var notBeforeMatch = dates.match(/notBefore=(.+)/);
+    var notAfterMatch = dates.match(/notAfter=(.+)/);
+    if (!notAfterMatch) return null;
+    return {
+      subject: subject,
+      notBefore: notBeforeMatch ? new Date(notBeforeMatch[1]) : null,
+      notAfter: new Date(notAfterMatch[1]),
+    };
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * 用 node-forge 解析证书有效期（回退方案）
+ * @param {string} certPath
+ * @returns {{notBefore: Date, notAfter: Date, subject: string}|null}
+ */
+function parseCertWithForge(certPath) {
+  try {
+    var forge = require('node-forge');
+    var pem = fs.readFileSync(certPath, 'utf-8');
+    var cert = forge.pki.certificateFromPem(pem);
+    var cn = cert.subject.attributes.find((a) => a.name === 'commonName');
+    return {
+      subject: cn ? cn.value : '',
+      notBefore: cert.validity.notBefore,
+      notAfter: cert.validity.notAfter,
+    };
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * 检查证书是否已安装到系统信任库
+ * @param {string} subject - 证书 CN（用于搜索）
+ * @returns {boolean}
+ */
+function checkTrusted(subject) {
+  if (IS_MACOS) {
+    // 检查 login keychain 和 system keychain
+    try {
+      var keyword = subject ? subject.split('.')[0] : 'whistle';
+      execSync(`security find-certificate -c "${keyword}" 2>/dev/null`, { encoding: 'utf-8' });
+      return true;
+    } catch (_e) {
+      // 在 login keychain 中未找到，检查 system keychain
+      try {
+        execSync(
+          'security find-certificate -c "whistle" /Library/Keychains/System.keychain 2>/dev/null',
+          { encoding: 'utf-8' }
+        );
+        return true;
+      } catch (_e2) {
+        return false;
+      }
+    }
+  }
+  if (IS_WINDOWS) {
+    try {
+      execSync('certutil -store Root "whistle"', { encoding: 'utf-8', windowsHide: true });
+      return true;
+    } catch (_e) {
+      return false;
+    }
+  }
+  return false;
+}
+
+// ANSI 颜色（与 bin CLI 一致）
+var c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  gray: '\x1b[90m',
+};
+
+/**
+ * 检查证书状态并输出
+ * @param {boolean} [compact] - 紧凑模式（用于 health 命令，不输出标题）
+ * @returns {Promise<void>}
+ */
+async function checkCertStatus(compact) {
+  var certPath = findCertFile();
+  if (!certPath) {
+    console.log(`${(compact ? '  ' : '') + c.red}✖${c.reset} 证书: 未找到（whistle 可能未启动过）`);
+    if (!compact) {
+      console.log(`${c.gray}    运行 easy-proxy start 启动 whistle（会自动生成证书）${c.reset}`);
+      console.log(`${c.gray}    然后运行 easy-proxy cert install 安装证书到系统信任库${c.reset}`);
+    }
+    return;
+  }
+
+  // 解析有效期
+  var info = parseCertWithOpenssl(certPath) || parseCertWithForge(certPath);
+  if (!info) {
+    console.log(`${(compact ? '  ' : '') + c.yellow}⚠${c.reset} 证书: 已存在（无法解析有效期）`);
+    console.log(`${c.gray}    路径: ${certPath}${c.reset}`);
+    return;
+  }
+
+  var now = new Date();
+  var daysLeft = Math.floor((info.notAfter.getTime() - now.getTime()) / (24 * 60 * 60 * 1000));
+  var trusted = checkTrusted(info.subject);
+  var dateStr = info.notAfter.toISOString().slice(0, 10);
+
+  // 状态判断
+  var status, color;
+  if (daysLeft <= 0) {
+    status = `已过期（超过 ${-daysLeft} 天）`;
+    color = c.red;
+  } else if (daysLeft <= 30) {
+    status = `即将过期（剩余 ${daysLeft} 天）`;
+    color = c.yellow;
+  } else {
+    status = `有效（剩余 ${daysLeft} 天）`;
+    color = c.green;
+  }
+
+  var trustedStr = trusted ? `${c.green}✓ 已信任` : `${c.yellow}⚠ 未信任${c.reset}`;
+
+  if (compact) {
+    console.log(
+      '  ' +
+        color +
+        (daysLeft <= 0 ? '✖' : daysLeft <= 30 ? '⚠' : '✓') +
+        c.reset +
+        ' 证书: ' +
+        status +
+        c.gray +
+        '，过期 ' +
+        dateStr +
+        c.reset +
+        ' — ' +
+        trustedStr
+    );
+  } else {
+    console.log(`${c.bold + c.blue}证书状态${c.reset}`);
+    console.log(c.gray + '─'.repeat(40) + c.reset);
+    console.log(`${c.blue}ℹ${c.reset} 状态:     ${color}${status}${c.reset}`);
+    console.log(`${c.blue}ℹ${c.reset} 过期时间: ${dateStr}`);
+    console.log(`${c.blue}ℹ${c.reset} 信任:     ${trustedStr}`);
+    console.log(`${c.blue}ℹ${c.reset} 路径:     ${c.gray}${certPath}${c.reset}`);
+    if (info.subject) {
+      console.log(`${c.blue}ℹ${c.reset} 颁发对象:  ${c.gray}${info.subject}${c.reset}`);
+    }
+    console.log(c.gray + '─'.repeat(40) + c.reset);
+    if (daysLeft <= 0) {
+      console.log(`${c.gray}    运行 easy-proxy cert install 重新安装证书${c.reset}`);
+    } else if (!trusted) {
+      console.log(`${c.gray}    运行 easy-proxy cert install 安装证书到系统信任库${c.reset}`);
+    }
+  }
+}
+
+module.exports = { checkCertStatus, findCertFile, parseCertWithOpenssl };