@yufengtadian/freedom-cli 1.13.1 → 1.13.3

package/lib/security.js

@@ -1,43 +1,53 @@
 'use strict';
 
-// 安全加固模块（v1.13.0）
+// 安全加固模块
 //
 // 为 freedom build 提供两种安全模式：
 //   - basic（简单模式）：资源压缩 + 壳剥离符号建议，阻止"随手打开 resources/
 //     就能看到前端源码"的随手破解，成本低、完全向后兼容。
-//   - high（高危模式）：AES-256-CTR + HMAC-SHA256（Encrypt-then-MAC）加密资源为
-//     单一容器 resources/app.bin，运行时由壳在内存中解密（磁盘无明文）；
-//     配套 HMAC 完整性校验防篡改；密钥不落盘（由 exe 文件名派生），
-//     并强制关闭 WebView2 devtools。
+//   - high（高危模式）：AES-256-CTR + HMAC-SHA256（Encrypt-then-MAC）把前端、配置
+//     与后端源码加密为单一容器 resources/app.bin，运行时由壳在内存中解密（磁盘无明文）；
+//     配套 HMAC 完整性校验防篡改；密钥不落盘，并强制关闭 WebView2 devtools。
 //
 // 架构说明（重要）：通用壳 = 所有应用共用一份预编译 freedom-shell 二进制，
 // 因此密钥派生所需的"主密钥常量"编译在通用壳内，天然被所有应用共享；
 // high 模式的对抗目标是把攻击者从"直接读明文"抬升到"必须逆向壳二进制、
-// 提取主密钥并复现派生算法"。真正"每应用唯一密钥"需要每应用独立编译壳
-// （破坏通用壳 + 零工具链架构），不在本模式范围内。
+// 提取主密钥并复现派生算法"。客户端加密做不到不可逆，本模式不这样宣称。
 //
 // ⚠️ 跨语言同步点：本文件与 templates/go/pkg/freedom/security.go（= 仓库根 security.go）必须保持
-//    MASTER_KEY / DERIVE_SALT / PBKDF2_ITER / KEY_LEN / APP_BIN_MAGIC
+//    MASTER_KEY_CIPHER 字节表与掩码算法 out[i] ^= (i*7+0x5A)
+//    DERIVE_SALT / MAC_LABEL / PBKDF2_ITER / KEY_LEN / APP_BIN_MAGIC
+//    salt/iv/tag 长度、容器头顺序、载荷 JSON 结构（html/config/backend.d/m）
 //    以及加密算法（aes-256-ctr + hmac-sha256）完全一致。
 //    修改任一侧必须同步另一侧，否则 build 出的加密资源壳无法解密。
+//    回归锁：tests/security-frdm2.test.mjs 与 Go security_test.go 互为对方产物的夹具。
 
 const crypto = require('crypto');
-const path = require('path');
 
 const SECURITY_MODES = ['none', 'basic', 'high'];
 
 // ---- 密钥派生参数（必须与 Go security.go 同步）----
-// 固定常量主密钥：参与 PBKDF2 派生，编译进通用壳。此处为 CLI 侧同值。
-const MASTER_KEY = 'freedom-shell::kdf-master::v1::7f4e8c2a9b1d6e3f';
-const DERIVE_SALT = 'freedom:derive:v1';
-const PBKDF2_ITER = 60000;
+
+// 主密钥明文与位置相关掩码异或后的字节表：使 npm 包与壳二进制里都搜不到完整密钥明文。
+const MASTER_KEY_CIPHER = Buffer.from([
+  60, 19, 13, 10, 18, 18, 233, 166, 225, 241, 197, 203, 194, 143, 134, 168,
+  174, 183, 245, 178, 135, 158, 128, 158, 112, 51, 42, 97, 44, 31, 22, 10,
+  89, 117, 46, 125, 97, 60, 1, 90, 22, 65, 226, 179, 189, 240, 172,
+]);
+
+const DERIVE_SALT = 'freedom:derive:v2';
+const MAC_LABEL = 'freedom:mac:v2';
+const PBKDF2_ITER = 600000;
 const KEY_LEN = 32;
 
-// resources/app.bin 容器头：magic(5B 'FRDM1') + iv(16B) + tag(16B) + ciphertext
-// 算法：AES-256-CTR 加密 + HMAC-SHA256(密文) 截断 16B 认证标签。
-const APP_BIN_MAGIC = 'FRDM1';
+// resources/app.bin 容器：magic(5B 'FRDM2') + salt(16B) + iv(16B) + tag(16B) + ciphertext
+// tag = HMAC-SHA256(macKey, magic+salt+iv+密文) 截 16B（Encrypt-then-MAC，头部一并认证）。
+const APP_BIN_MAGIC = 'FRDM2';
+const CTR_SALT_LEN = 16;
 const CTR_IV_LEN = 16;
 const CTR_TAG_LEN = 16;
+const APP_BIN_HEADER_LEN = APP_BIN_MAGIC.length + CTR_SALT_LEN + CTR_IV_LEN + CTR_TAG_LEN;
+const APP_BIN_AUTH_LEN = APP_BIN_MAGIC.length + CTR_SALT_LEN + CTR_IV_LEN;
 
 // ---- 模式解析 ----
 
@@ -61,53 +71,101 @@ function resolveSecurity(cliValue, cfgValue) {
 
 // 应用标识：exe 文件名（去扩展名）。
 // CLI build 时 = 目标 exe 名去掉扩展名；壳运行时 = os.Executable() basename 去扩展名。
-// 两侧使用同一派生算法，故 exe 事后被重命名会导致 high 模式无法解密（视为防篡改特性）。
+// 两侧算法一致（Go strings.TrimSuffix 大小写敏感），故 exe 事后被重命名会导致
+// high 模式无法解密（视为防篡改特性）。
 function appIdentityFor(name) {
-  return String(name).replace(/\.(exe|app)$/i, '');
+  let s = String(name);
+  if (s.endsWith('.exe')) s = s.slice(0, -4);
+  if (s.endsWith('.app')) s = s.slice(0, -4);
+  return s;
 }
 
-// 与 Go security.go deriveKey 保持一致的 PBKDF2-HMAC-SHA256 派生。
-// 输入 salt = DERIVE_SALT + ':' + appName（避免仅按 exe 名可枚举碰撞）。
-function deriveKey(appName) {
-  const salt = Buffer.from(DERIVE_SALT + ':' + appIdentityFor(appName), 'utf8');
-  return crypto.pbkdf2Sync(MASTER_KEY, salt, PBKDF2_ITER, KEY_LEN, 'sha256');
+// masterSecret 还原主密钥（PBKDF2 的 password），与 Go masterSecret() 同式。
+function masterSecret() {
+  const out = Buffer.alloc(MASTER_KEY_CIPHER.length);
+  for (let i = 0; i < MASTER_KEY_CIPHER.length; i++) {
+    out[i] = MASTER_KEY_CIPHER[i] ^ ((i * 7 + 0x5a) & 0xff);
+  }
+  return out;
+}
+
+// 容器密钥对：加密与认证分开，避免同一密钥同时服务 AES-CTR 与 HMAC。
+// 与 Go deriveSecurityKey 一致：KEK = PBKDF2(master, DERIVE_SALT:app + 容器随机盐)，
+// macKey = HMAC-SHA256(KEK, MAC_LABEL)。
+function deriveKeys(appName, salt) {
+  const base = Buffer.concat([
+    Buffer.from(DERIVE_SALT + ':' + appIdentityFor(appName), 'utf8'),
+    salt,
+  ]);
+  const enc = crypto.pbkdf2Sync(masterSecret(), base, PBKDF2_ITER, KEY_LEN, 'sha256');
+  const mac = crypto.createHmac('sha256', enc).update(MAC_LABEL).digest();
+  return { enc, mac };
 }
 
 // ---- 加密 / 解密（high 模式）----
 
-// 载荷结构：{ html: <string>, config: <string> }（config 为 config.json 原文 JSON 字符串）。
+// 载荷结构：{ html, config, backend: { <rel>: { d: base64, m: mode } } }
+// backend 为可选的后端源码表（键 = 相对 resources 的斜杠路径），high 模式下
+// 后端源码进容器，磁盘不再留 resources/backend 明文目录。
 // 返回 app.bin 完整字节。
-// 算法：AES-256-CTR 加密 → HMAC-SHA256(密文) 截 16B 认证标签（Encrypt-then-MAC）。
-function encryptApp(name, html, configJSON) {
-  const key = deriveKey(name);
-  const payload = Buffer.from(JSON.stringify({ html, config: configJSON }), 'utf8');
+function encryptApp(name, html, configJSON, backend) {
+  const salt = crypto.randomBytes(CTR_SALT_LEN);
   const iv = crypto.randomBytes(CTR_IV_LEN);
-  const cipher = crypto.createCipheriv('aes-256-ctr', key, iv);
+  const k = deriveKeys(name, salt);
+  const payloadObj = { html, config: configJSON };
+  if (backend && Object.keys(backend).length > 0) {
+    payloadObj.backend = {};
+    for (const [rel, entry] of Object.entries(backend)) {
+      if (!isSafeRelPath(rel)) throw new Error(`后端路径非法，拒绝入容器：${rel}`);
+      const buf = Buffer.isBuffer(entry) ? entry : entry.data;
+      const mode = Buffer.isBuffer(entry) ? 0o644 : (((entry.mode ?? 0o644)) & 0o7777);
+      payloadObj.backend[rel] = { d: buf.toString('base64'), m: mode };
+    }
+  }
+  const payload = Buffer.from(JSON.stringify(payloadObj), 'utf8');
+  const cipher = crypto.createCipheriv('aes-256-ctr', k.enc, iv);
   const ct = Buffer.concat([cipher.update(payload), cipher.final()]);
-  const tag = crypto.createHmac('sha256', key).update(ct).digest().subarray(0, CTR_TAG_LEN);
-  return Buffer.concat([Buffer.from(APP_BIN_MAGIC, 'ascii'), iv, tag, ct]);
+  const header = Buffer.concat([Buffer.from(APP_BIN_MAGIC, 'ascii'), salt, iv]);
+  const tag = crypto.createHmac('sha256', k.mac)
+    .update(header).update(ct).digest().subarray(0, CTR_TAG_LEN);
+  return Buffer.concat([header, tag, ct]);
 }
 
-// 解密 app.bin（供单测验证 / 未来壳调试工具复用）。返回 { html, config }。
-function decryptApp(name, buf) {
-  const key = deriveKey(name);
+// 拆分并校验容器头；旧版 FRDM1 等不兼容版本明确拒绝（不静默降级）。
+function splitAppBin(buf) {
   const magic = Buffer.from(APP_BIN_MAGIC, 'ascii');
-  if (buf.length < magic.length + CTR_IV_LEN + CTR_TAG_LEN || !buf.subarray(0, magic.length).equals(magic)) {
-    throw new Error('app.bin 头无效：不是 FRDM1 加密容器');
+  if (buf.length < APP_BIN_HEADER_LEN) {
+    throw new Error('app.bin 长度不足容器头');
+  }
+  if (!buf.subarray(0, magic.length).equals(magic)) {
+    throw new Error(
+      `app.bin 容器版本不受支持（头为 "${buf.subarray(0, magic.length).toString('ascii')}"，要求 ${APP_BIN_MAGIC}）`);
   }
   let off = magic.length;
+  const salt = buf.subarray(off, off + CTR_SALT_LEN); off += CTR_SALT_LEN;
   const iv = buf.subarray(off, off + CTR_IV_LEN); off += CTR_IV_LEN;
   const tag = buf.subarray(off, off + CTR_TAG_LEN); off += CTR_TAG_LEN;
   const ct = buf.subarray(off);
+  return { salt, iv, tag, ct, headerLen: APP_BIN_AUTH_LEN };
+}
+
+// 判定容器内相对路径可安全落盘（与 Go isSafeRelPath 同式）。
+function isSafeRelPath(rel) {
+  if (rel === '' || rel.includes('\\') || rel.startsWith('/')) return false;
+  if (rel.length >= 2 && rel[1] === ':') return false;
+  return rel.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
 
-  // 1) 认证：HMAC-SHA256(ct) 前 16 字节与容器头 tag 恒定时间比对。
-  const expect = crypto.createHmac('sha256', key).update(ct).digest().subarray(0, CTR_TAG_LEN);
+// 解密 app.bin（供跨语言回归测试与 CLI 自检复用）。返回 { html, config, backend? }。
+function decryptApp(name, buf) {
+  const { salt, iv, tag, ct, headerLen } = splitAppBin(buf);
+  const k = deriveKeys(name, salt);
+  const expect = crypto.createHmac('sha256', k.mac)
+    .update(buf.subarray(0, headerLen)).update(ct).digest().subarray(0, CTR_TAG_LEN);
   if (!crypto.timingSafeEqual(tag, expect)) {
-    throw new Error('app.bin 认证失败（exe 被重命名或资源被篡改？）');
+    throw new Error('app.bin 认证失败（exe 被重命名、资源被篡改，或壳与 CLI 版本不匹配）');
   }
-
-  // 2) 解密：AES-256-CTR。
-  const decipher = crypto.createDecipheriv('aes-256-ctr', key, iv);
+  const decipher = crypto.createDecipheriv('aes-256-ctr', k.enc, iv);
   const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
   const obj = JSON.parse(plain.toString('utf8'));
   if (typeof obj.html !== 'string' || typeof obj.config !== 'string') {
@@ -118,17 +176,13 @@ function decryptApp(name, buf) {
 
 // ---- 完整性清单（high 模式）----
 
-// 生成 resources/.integrity：记录 app.bin 与 backend/ 各文件的 HMAC-SHA256，
-// 壳启动时校验，防止 resources 被整体替换/篡改。
-// 返回 { v, appBin, backend }。
-function buildIntegrity(appName, appBin, backendRelMap) {
-  const key = deriveKey(appName);
-  const hmac = (buf) => crypto.createHmac('sha256', key).update(buf).digest('hex');
-  const backend = {};
-  for (const [rel, buf] of Object.entries(backendRelMap || {})) {
-    backend[rel] = hmac(buf);
-  }
-  return { v: 1, appBin: hmac(appBin), backend };
+// 生成 resources/.integrity：记录 app.bin 的 HMAC-SHA256，壳启动时校验，
+// 防容器被整体替换。backend 已进容器，其完整性由容器认证标签一并保证。
+function buildIntegrity(appName, appBin) {
+  const { salt } = splitAppBin(appBin);
+  const k = deriveKeys(appName, salt);
+  const hmac = (buf) => crypto.createHmac('sha256', k.mac).update(buf).digest('hex');
+  return { v: 2, appBin: hmac(appBin) };
 }
 
 // 生成 .integrity 文件文本。
@@ -139,12 +193,17 @@ function renderIntegrity(integrity) {
 module.exports = {
   SECURITY_MODES,
   APP_BIN_MAGIC,
+  APP_BIN_HEADER_LEN,
+  CTR_SALT_LEN,
   parseSecurity,
   resolveSecurity,
   appIdentityFor,
-  deriveKey,
+  masterSecret,
+  deriveKeys,
   encryptApp,
   decryptApp,
+  splitAppBin,
+  isSafeRelPath,
   buildIntegrity,
   renderIntegrity,
 };

package/lib/shell.js

@@ -23,7 +23,9 @@ const {
   SHELL_EXE_NAME,
   localShellPath,
   nativePlatform,
+  normalizePlatform,
 } = require('./utils');
+const { applyWebkitTags } = require('./webkit');
 
 // GitHub Releases 下载源（可用环境变量覆盖）。
 // 资产命名约定：freedom-shell-<plat>（单文件二进制，不压缩）。
@@ -31,6 +33,17 @@ function releaseRepo() {
   return process.env.FREEDOM_SHELL_REPO || 'YUfeng12TA/freedom';
 }
 
+// 直连下载域与 API 域（测试可指向本地桩服务；默认走 GitHub）。
+function releaseBase() {
+  return (process.env.FREEDOM_SHELL_BASE || 'https://github.com').replace(/\/+$/, '');
+}
+function apiBase() {
+  return (process.env.FREEDOM_GITHUB_API || 'https://api.github.com').replace(/\/+$/, '');
+}
+function shellAssetName(plat) {
+  return `freedom-shell-${plat}`;
+}
+
 // 远程壳下载的默认版本：与当前包版本保持一致。
 // 通过环境变量 FREEDOM_SHELL_TAG 可强制覆盖；默认动态读取 package.json 的 version，
 // 避免与包版本漂移（历史曾硬编码 v1.1.10 导致下载到旧壳）。
@@ -46,7 +59,7 @@ function releaseTag() {
   return process.env.FREEDOM_SHELL_TAG || `v${pkgVersion()}`;
 }
 function releaseUrl(plat) {
-  return `https://github.com/${releaseRepo()}/releases/download/${releaseTag()}/freedom-shell-${plat}`;
+  return `${releaseBase()}/${releaseRepo()}/releases/download/${releaseTag()}/${shellAssetName(plat)}`;
 }
 
 // ---- 壳二进制平台格式校验 ----
@@ -193,13 +206,14 @@ function hasCurl() {
 }
 
 // 用 curl 下载到 dest；成功返回 null，失败返回错误信息
-function curlDownload(url, dest, proxy) {
+function curlDownload(url, dest, proxy, extraHeaders) {
   const args = [
     '-L', '--fail', '--silent', '--show-error',
     '--connect-timeout', '20', '--max-time', '180', '--retry', '2',
     '--output', dest,
   ];
   if (proxy) args.push('--proxy', proxy);
+  for (const h of extraHeaders || []) args.push('-H', h);
   if (process.platform === 'win32' && /^https:/i.test(url)) {
     args.push('--ssl-no-revoke'); // 规避 Windows schannel CRYPT_E_REVOCATION_OFFLINE
   }
@@ -212,18 +226,124 @@ function curlDownload(url, dest, proxy) {
   return null;
 }
 
+// 平台参数收口：win / mac / linux 等别名归一到平台 key，识别不了给可读错误。
+function requirePlatform(plat) {
+  const key = normalizePlatform(plat);
+  if (!key) {
+    throw new Error(
+      `未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}` +
+        `（也接受 win / mac / linux 别名，可带架构后缀，如 mac-arm64）`
+    );
+  }
+  return key;
+}
+
+// 单次 HTTP GET 到 Buffer：配了代理就走 curl（原生支持 socks5），否则用内置 fetch。
+// API 端点需要 Accept 头，故 headers 显式传入。
+async function httpGetBuffer(url, headers) {
+  const proxy = resolveProxy();
+  if (proxy) {
+    if (!hasCurl()) throw new Error(`已配置代理 ${proxy} 但本机无 curl`);
+    const tmp = path.join(os.tmpdir(), `freedom-dl-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const err = curlDownload(url, tmp, proxy, Object.entries(headers || {}).map(([k, v]) => `${k}: ${v}`));
+    try {
+      if (err) throw new Error(err);
+      return fs.readFileSync(tmp);
+    } finally {
+      try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
+    }
+  }
+  const res = await fetch(url, {
+    headers: Object.assign({ 'User-Agent': 'freedom-cli' }, headers),
+    redirect: 'follow',
+    signal: AbortSignal.timeout(60000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// 从 release 资产列表里挑出本平台的壳资产（需带 API url 字段）。
+function selectReleaseAsset(assets, plat) {
+  const name = shellAssetName(plat);
+  return (Array.isArray(assets) ? assets : []).find(
+    (a) => a && a.name === name && typeof a.url === 'string'
+  ) || null;
+}
+
+// 经 GitHub Release API 取壳：先按 tag 查 release 拿资产 id，再以 octet-stream 拉字节。
+// 背景（实测）：releases/download 会 302 到 S3 签名域，受限网络下响应头拿得到、
+// body 永远不结束；api.github.com 的资产端点由 GitHub 自己代理字节流，可稳定取回。
+async function downloadShellViaApi(plat) {
+  const token = process.env.FREEDOM_GITHUB_TOKEN || process.env.GITHUB_TOKEN;
+  const auth = token ? { Authorization: `Bearer ${token}` } : {};
+  const metaUrl = `${apiBase()}/repos/${releaseRepo()}/releases/tags/${releaseTag()}`;
+  let meta;
+  try {
+    meta = JSON.parse((await httpGetBuffer(metaUrl, Object.assign({ Accept: 'application/json' }, auth))).toString('utf8'));
+  } catch (e) {
+    throw new Error(`查询 release 元数据失败（${metaUrl}）：${e.message}`);
+  }
+  const asset = selectReleaseAsset(meta && meta.assets, plat);
+  if (!asset) {
+    throw new Error(`${releaseTag()} 中没有资产 ${shellAssetName(plat)}`);
+  }
+  return await httpGetBuffer(asset.url, Object.assign({ Accept: 'application/octet-stream' }, auth));
+}
+
 // 下载指定平台壳到包内 shell/<plat>/
 // 返回下载后的绝对路径；失败抛错。
+// 两条路径：直连 releases/download（有代理时经 curl）→ 失败回退 Release API 资产端点。
 async function downloadShell(plat) {
-  if (!ALL_PLATFORMS.includes(plat)) {
-    throw new Error(`未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}`);
-  }
+  plat = requirePlatform(plat);
   const url = releaseUrl(plat);
   const dest = localShellPath(plat);
   fs.mkdirSync(path.dirname(dest), { recursive: true });
 
+  let buf = null;
+  let primaryErr = null;
+  try {
+    buf = await fetchShellDirect(plat, url);
+  } catch (e) {
+    primaryErr = e;
+    process.stdout.write(
+      `[freedom] 直连下载壳 ${plat} 未完成（${String(e.message).split('\n')[0]}），回退 GitHub API 资产端点…\n`
+    );
+  }
+  if (!buf) {
+    try {
+      buf = await downloadShellViaApi(plat);
+    } catch (apiErr) {
+      throw new Error(
+        `下载壳 ${plat} 失败：直连与 Release API 两条路径都不通。\n` +
+          `  直连 ${url}：${primaryErr ? primaryErr.message : '未返回数据'}\n` +
+          `  API ${apiBase()}/repos/${releaseRepo()}：${apiErr.message}\n` +
+          `可设置代理重试（FREEDOM_SHELL_PROXY=socks5h://127.0.0.1:10808），` +
+          `或手动将壳二进制放入 ${dest}。`
+      );
+    }
+  }
+
+  // B13：下载后、落盘前校验格式/架构，防止代理劫持返回错误页或假壳被静默分发。
+  const fmt = detectShellFormat(buf);
+  const want = expectedFormat(plat);
+  if (fmt === 'unknown' || formatFamily(fmt) !== formatFamily(want)) {
+    throw new Error(
+      `下载的壳格式异常：期望 ${want}（${plat}），实际 detect=${fmt}。` +
+        `下载地址 ${url} 可能返回了错误页或非本平台假壳，请检查 GitHub Release 资产 ` +
+        `${releaseRepo()} 的 ${releaseTag()}。已放弃本次写入。`
+    );
+  }
+  fs.writeFileSync(dest, buf);
+  if (process.platform !== 'win32') {
+    fs.chmodSync(dest, 0o755);
+  }
+  return dest;
+}
+
+// 直连路径：代理在位时用 curl（原生支持 socks5/http 代理），否则用内置 fetch。
+// 返回内容 Buffer；网络失败、超时、非 2xx 一律抛错（由 downloadShell 决定回退）。
+async function fetchShellDirect(plat, url, dest) {
   const proxy = resolveProxy();
-  let buf;
   if (proxy) {
     process.stdout.write(`[freedom] 下载壳 ${plat}（经代理 ${proxy}）<- ${url}\n`);
     if (!hasCurl()) {
@@ -238,74 +358,40 @@ async function downloadShell(plat) {
       try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
       throw new Error(
         `${curlErr}\n下载地址 ${url} 不可达。` +
-          `请确认代理 ${proxy} 可用（可执行 curl --proxy ${proxy} ${url} -I 自测），` +
-          `或手动将壳二进制放入 ${localShellPath(plat)}。`
+          `请确认代理 ${proxy} 可用（可执行 curl --proxy ${proxy} ${url} -I 自测）。`
       );
     }
     try {
-      buf = fs.readFileSync(tmp);
+      return fs.readFileSync(tmp);
     } finally {
       try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
     }
-  } else {
-    process.stdout.write(`[freedom] 下载壳 ${plat} <- ${url}\n`);
-    let res;
-    try {
-      // 30s 超时：网络挂起时明确报错，避免构建进程无限阻塞
-      res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30000) });
-    } catch (e) {
-      if (e.name === 'AbortError' || e.name === 'TimeoutError') {
-        throw new Error(
-          `下载壳 ${plat} 超时（30s）。请检查网络后重试，` +
-            `或设置代理变量 FREEDOM_SHELL_PROXY=socks5h://127.0.0.1:10808 重试，` +
-            `或手动将壳二进制放入 ${localShellPath(plat)}。`
-        );
-      }
-      throw new Error(
-        `下载壳 ${plat} 失败：${e.message}。请检查网络（必要时设置 FREEDOM_SHELL_PROXY 走代理），` +
-          `或手动将壳二进制放入 ${localShellPath(plat)}。`
-      );
-    }
-    if (!res.ok) {
-      throw new Error(
-        `下载壳失败：HTTP ${res.status}。请确认 GitHub 仓库 ${releaseRepo()} 已发布 ` +
-          `${releaseTag()} 的资产 freedom-shell-${plat}，或手动将壳二进制放入 ${localShellPath(plat)}。`
-      );
-    }
-    buf = Buffer.from(await res.arrayBuffer());
   }
 
-  // B13：下载后、落盘前校验格式/架构，防止代理劫持返回错误页或假壳被静默分发。
-  const fmt = detectShellFormat(buf);
-  const want = expectedFormat(plat);
-  if (fmt === 'unknown' || formatFamily(fmt) !== formatFamily(want)) {
-    throw new Error(
-      `下载的壳格式异常：期望 ${want}（${plat}），实际 detect=${fmt}。` +
-        `下载地址 ${url} 可能返回了错误页或非本平台假壳，请检查 GitHub Release 资产 ` +
-        `${releaseRepo()} 的 ${releaseTag()}。已放弃本次写入。`
-    );
-  }
-  fs.writeFileSync(dest, buf);
-  if (process.platform !== 'win32') {
-    fs.chmodSync(dest, 0o755);
+  process.stdout.write(`[freedom] 下载壳 ${plat} <- ${url}\n`);
+  let res;
+  try {
+    // 30s 超时：网络挂起时明确报错，避免构建进程无限阻塞
+    res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30000) });
+  } catch (e) {
+    if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+      throw new Error('下载超时（30s）');
+    }
+    throw new Error(`请求失败：${e.message}`);
   }
-  return dest;
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (!buf.length) throw new Error('响应体为空');
+  return buf;
 }
 
 // 本地用 Go 编译指定平台壳（需要 Go + 该平台编译环境）。
 // Windows 产物以 GUI 子系统编译（-H windowsgui），运行时无 cmd 黑窗。
 function buildShell(plat) {
-  if (!ALL_PLATFORMS.includes(plat)) {
-    throw new Error(`未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}`);
-  }
-  const res = spawnSync('go', ['version'], { encoding: 'utf8' });
-  if (res.error || res.status !== 0) {
-    throw new Error('未检测到 Go 工具链。请先安装 Go（https://go.dev/dl/），或改用 freedom shell download。');
-  }
-  const dest = localShellPath(plat);
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-
+  plat = requirePlatform(plat);
   // 本机只能编译本机平台（webview_go 依赖系统 WebView 框架，无法交叉编译）。
+  // 这道判断刻意前置于 Go 探测：平台不匹配是与工具有关的硬事实，先报工具有关
+  // 的错误会把「装个 Go 也没用」的场景误导成装 Go 能解决。
   // 统一走 utils.nativePlatform：Intel Mac 会明确抛"已不支持"，避免两套映射语义不一（B44）。
   const native = nativePlatform();
   if (plat !== native) {
@@ -314,16 +400,37 @@ function buildShell(plat) {
         `请在目标平台执行 freedom shell build ${plat}，或用 freedom shell download ${plat} 拉取 CI 预编译产物。`
     );
   }
+  const res = spawnSync('go', ['version'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) {
+    throw new Error(
+      '未检测到 Go 工具链。执行 freedom toolchain install go 自动安装（默认只打印命令，加 --apply 才执行），' +
+        '或手动获取 https://go.dev/dl/ ，或改用 freedom shell download 拉取预编译壳。'
+    );
+  }
+  const dest = localShellPath(plat);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
 
   const buildDir = goTemplateDir();
-  const ldflags = plat.startsWith('win') ? ['-ldflags', '-H windowsgui'] : [];
-  const build = spawnSync('go', ['build', ...ldflags, '-o', dest, '.'], {
+  // 剥离符号与调试信息（-s -w）+ 抹掉构建期绝对路径（-trimpath）：
+  // 通用壳里编译进了 high 模式的密钥派生逻辑，函数名/DWARF 是给逆向者的地图。
+  const ldflags = ['-s', '-w'];
+  if (plat.startsWith('win')) ldflags.push('-H', 'windowsgui');
+  // Linux：新发行版只有 webkit2gtk-4.1，需要 -tags webkit2_41（探测与注入见 lib/webkit.js）。
+  const webkit = applyWebkitTags(process.env);
+  if (webkit.tags.length) {
+    process.stdout.write(`[freedom] 本机 WebKitGTK 仅有 4.1，构建加 -tags ${webkit.tags.join(',')}\n`);
+  }
+  const build = spawnSync('go', ['build', '-trimpath', '-ldflags', ldflags.join(' '), '-o', dest, '.'], {
     cwd: buildDir,
     encoding: 'utf8',
-    env: { ...process.env, CGO_ENABLED: '1' },
+    env: Object.assign({ CGO_ENABLED: '1' }, webkit.env),
   });
   if (build.error || build.status !== 0) {
-    throw new Error(`Go 编译失败：\n${build.stdout}\n${build.stderr}`);
+    const hint = plat.startsWith('linux') && /webkit2gtk-4\.0/.test(`${build.stdout}${build.stderr}`)
+      ? `\n提示：本机未装 webkit2gtk-4.0/4.1 开发库。Ubuntu/Debian 执行 ` +
+        `sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev（老发行版用 4.0）后重试。`
+      : '';
+    throw new Error(`Go 编译失败：\n${build.stdout}\n${build.stderr}${hint}`);
   }
   return dest;
 }