@whyshu/argent 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whyshu/argent",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "description": "Argent 单 bundle（dsh web / DSH Desktop 同一插件）：ERP 连接器 + 问述代理 + 登录/续期 + MCP 网关 + 伞伞桌宠（含积分）",
   "main": "src/index.js",

package/src/config.mjs

@@ -3,6 +3,8 @@
  *
  * 单独成文件是为了让 **office 运行时** 与 **health 聚合** 共用同一份解析，
  * 避免"两处各写一遍 enabled/token 判据"（历史事故的根因形态）。
+ * 2026-11-07 增 {@link readTunnelConfig}：App 隧道（契约 §2.1）的开关/地址/machineId 也走本文件，
+ * ⛔ 不在这里读凭据（账号 JWT 由 tunnel.mjs 复用 account-token 的解析点）。
  * 纯 node 内建，无宿主 import。
  */
 import { readFileSync } from 'node:fs'
@@ -12,6 +14,8 @@ import { join } from 'node:path'
 export const REPORT_FILE = 'agent-report.json'
 export const MIN_INTERVAL_SEC = 5
 export const MAX_INTERVAL_SEC = 300
+/** App 隧道默认地址（契约 §2.1；`ARGENT_TUNNEL_URL` 可覆盖） */
+export const TUNNEL_DEFAULT_URL = 'wss://whyshu.com/api/argent/tunnel'
 
 /**
  * @param {string} dataDir
@@ -45,3 +49,41 @@ export function readConfig(dataDir) {
     return { ok: false, reason: e?.code === 'ENOENT' ? 'missing' : 'invalid', error: String(e?.message || e) }
   }
 }
+
+/** 隧道总开关：`ARGENT_TUNNEL=1` 才开（契约 §2.1；默认关）。 */
+export function isTunnelEnabled(env = process.env) {
+  return String(env.ARGENT_TUNNEL || '').trim() === '1'
+}
+
+/**
+ * App 隧道配置（契约 §2.1）——本文件是 agent-report.json 的唯一解析点，隧道也走这里。
+ *   · 开关：`ARGENT_TUNNEL=1`（默认关）
+ *   · 地址：`ARGENT_TUNNEL_URL` → {@link TUNNEL_DEFAULT_URL}
+ *   · machineId：`ARGENT_MACHINE_ID` → `agent-report.json#machineId`（缺失 ⇒ ok:false，不启动）
+ * ⛔ 不含任何凭据读取（账号 JWT 由 tunnel.mjs 复用 account-token 的解析点；此处只解析非密字段）。
+ * @returns {{enabled:false,ok:false,reason:'disabled'}|{enabled:true,ok:false,reason:string,url:string}|{enabled:true,ok:true,url:string,machineId:string,deviceName:string,serverUrl:string}}
+ */
+export function readTunnelConfig({ env = process.env, dataDir } = {}) {
+  if (!isTunnelEnabled(env)) return { enabled: false, ok: false, reason: 'disabled' }
+  const url = String(env.ARGENT_TUNNEL_URL || '').trim() || TUNNEL_DEFAULT_URL
+  try {
+    const proto = new URL(url).protocol
+    if (proto !== 'ws:' && proto !== 'wss:') return { enabled: true, ok: false, reason: 'bad-url', url }
+  } catch {
+    return { enabled: true, ok: false, reason: 'bad-url', url }
+  }
+  let report = {}
+  if (dataDir) {
+    try { report = JSON.parse(readFileSync(join(dataDir, REPORT_FILE), 'utf8')) || {} } catch { report = {} }
+  }
+  const machineId = String(env.ARGENT_MACHINE_ID || report.machineId || '').trim()
+  if (!machineId) return { enabled: true, ok: false, reason: 'no-machine-id', url }
+  return {
+    enabled: true,
+    ok: true,
+    url,
+    machineId,
+    deviceName: String(report.machineName || '').trim() || os.hostname(),
+    serverUrl: String(report.serverUrl || '').trim(),
+  }
+}

package/src/index.js

@@ -25,6 +25,7 @@ import { acquireLease, heartbeatLease, releaseLease, leaseHolder } from './lease
 import { resolveAccountToken } from './account-token.mjs'
 import { installMachineSessionReporter } from './machine-session.mjs'
 import { syncRuntimeIfNeeded } from './runtime-sync.mjs'
+import { isTunnelEnabled } from './config.mjs'
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 const PKG_VERSION = (() => {
@@ -243,5 +244,20 @@ export function apply(ctx) {
         console.error('[argent] ERP 连接器启动失败（不影响 dsh）:', e?.message || e)
       }
     }
+
+    // ⑥ App 真流式隧道（默认关：ARGENT_TUNNEL=1 才启动；Mac 出站到 relay，契约 §2）
+    //    放在内核解析之后（用最终 dataDir 读 agent-report.json#machineId）；未登录/缺 machineId 只记日志不抛。
+    if (isTunnelEnabled()) {
+      try {
+        const { startTunnel } = await import('./tunnel.mjs')
+        const tunnel = startTunnel({ dataDir, version: PKG_VERSION })
+        if (tunnel) {
+          ctx.on?.('dispose', () => { try { tunnel.stop() } catch { /* 退出清理失败不影响宿主 */ } })
+          console.log(`[argent] App 隧道已启动（${tunnel.endpoint}，machineId=${tunnel.machineId}）`)
+        }
+      } catch (e) {
+        console.error('[argent] 隧道启动失败（不影响其余功能）:', e?.message || e)
+      }
+    }
   })()
 }

package/src/tunnel.mjs

@@ -0,0 +1,848 @@
+/**
+ * App ↔ Mac 真流式隧道（Mac 侧；契约 §2/§6/§7，唯一真源：
+ * `~/Whyshu/argent-android/docs/真流式-隧道与租户门控-实施契约-2026-11-07.md`）
+ *
+ * 链路：`App ──WSS──▶ whyshu relay ──WS──▶ 本隧穿 ──WS/HTTP──▶ dsh 127.0.0.1:3080`
+ *
+ * 本文件只做三件事，**不解析业务帧**：
+ *   ① 出站 WSS 注册到 relay（Authorization: Bearer 账号 JWT + x-argent-machine-id）
+ *   ② 代持 dsh 准入 cookie（`/api/argent-state/access` → `/?token=` 换 `dsh-auth-*`，仅内存缓存）
+ *   ③ 按契约 §2.3 的帧协议透传 http / WS 两种流量（path 白名单 = `/api/` 前缀）
+ *
+ * 红线（契约 §6）：
+ *   · 隧道默认关闭（`ARGENT_TUNNEL=1` 才启动）；只允许 `/api/` 开头的路径，⛔ 不做通用反向代理；
+ *   · 账号 JWT / dsh 启动 token / dsh cookie **只在内存**，⛔ 不落盘、不打印、不写日志正文；
+ *   · 审计只记连接/断开、帧数、字节数、错误码；⛔ 不记正文。
+ *
+ * 依赖：纯 node 内建（node:http/https + 自带的 RFC 6455 客户端）。
+ * 为什么不用 `ws` 包：本插件是**已发布 npm 包**（@whyshu/argent），隧道要带自定义
+ * Authorization 头，而 Node 内置 WebSocket 不支持自定义头；为此给发布包加一个运行时依赖
+ * 不划算 ⇒ 只实现客户端必需的 RFC 6455 子集（文本帧/分片/ping-pong/close，客户端掩码）。
+ */
+import { createHash, randomBytes } from 'node:crypto'
+import http from 'node:http'
+import https from 'node:https'
+import { readFileSync } from 'node:fs'
+import { hostname } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { readTunnelConfig, TUNNEL_DEFAULT_URL } from './config.mjs'
+import { resolveAccountToken } from './account-token.mjs'
+
+// ── 常量（契约 §2.1/§2.2/§3.3）─────────────────────────────────────────────
+export const DEFAULT_TUNNEL_URL = TUNNEL_DEFAULT_URL
+export const PING_MS = 25_000
+export const PONG_TIMEOUT_MS = 45_000
+export const RECONNECT_MIN_MS = 1_000
+export const RECONNECT_MAX_MS = 30_000
+export const RECONNECT_JITTER = 0.2
+/** relay ⇄ tunnel 单帧上限（§3.3：单帧 ≤1MB） */
+export const MAX_RELAY_FRAME_BYTES = 1024 * 1024
+/** dsh ⇄ tunnel 单帧上限（会话快照可能偏大；超过 relay 上限的转出帧会被主动断开） */
+export const MAX_DSH_FRAME_BYTES = 4 * 1024 * 1024
+/** http 帧 body 上限（§3.3 同理） */
+export const MAX_HTTP_BODY_BYTES = 1024 * 1024
+/** dsh 一元响应体上限（防御性；正常 API 远小于此） */
+export const MAX_DSH_RESPONSE_BYTES = 8 * 1024 * 1024
+
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const DSH_ACCESS_PATH = '/api/argent-state/access'
+
+function readPkgVersion() {
+  try { return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version || '' } catch { return '' }
+}
+
+// ── 纯函数：帧协议（§2.3；字段名逐字对齐，⛔ 不自创）───────────────────────
+/**
+ * 契约 §2.3 的帧构造器。所有帧都是 JSON 文本帧。
+ * | 方向 | 帧 |
+ * | relay→tunnel | {t:"http", id, method, path, headers?, bodyB64?} |
+ * | tunnel→relay | {t:"http_res", id, status, headers?, bodyB64?} |
+ * | relay→tunnel | {t:"ws_open", id, path, query?} |
+ * | tunnel→relay | {t:"ws_ready", id} / {t:"ws_msg", id, data} / {t:"ws_close", id, code?, reason?} |
+ * | 双向 | {t:"ping", ts} / {t:"pong", ts} |
+ */
+export const FRAME = {
+  hello: ({ machineId, deviceName, version }) => ({ t: 'hello', machineId, deviceName, version }),
+  ping: (ts) => ({ t: 'ping', ts }),
+  pong: (ts) => ({ t: 'pong', ts }),
+  httpRes: ({ id, status, headers, bodyB64 }) => ({
+    t: 'http_res', id, status,
+    ...(headers && Object.keys(headers).length ? { headers } : {}),
+    ...(bodyB64 ? { bodyB64 } : {}),
+  }),
+  wsReady: (id) => ({ t: 'ws_ready', id }),
+  wsMsg: (id, data) => ({ t: 'ws_msg', id, data }),
+  wsClose: (id, code, reason) => ({
+    t: 'ws_close', id,
+    ...(Number.isFinite(code) ? { code } : {}),
+    ...(reason ? { reason } : {}),
+  }),
+}
+
+export const encodeFrame = (obj) => JSON.stringify(obj)
+
+/** 解析 relay 帧；形状不对一律抛（调用方只记错误码，不记正文）。 */
+export function decodeFrame(text) {
+  const v = JSON.parse(String(text))
+  if (!v || typeof v !== 'object' || Array.isArray(v) || typeof v.t !== 'string' || !v.t) throw new Error('bad-frame')
+  return v
+}
+
+/**
+ * path 白名单（契约 §2.4/§6.1）：只允许 `/api/` 前缀，且**归一化后**仍在 /api/ 下。
+ * ⛔ 拒绝绝对 URL、`//host`、越界 `..`、CRLF 注入。
+ */
+export function isAllowedPath(path) {
+  if (typeof path !== 'string' || path.length === 0 || path.length > 4096) return false
+  if (!path.startsWith('/')) return false // 相对路径会被 URL 解析成 /api/…，必须显式拒绝
+  if (/[\r\n]/.test(path)) return false
+  let u
+  try { u = new URL(path, 'http://127.0.0.1') } catch { return false }
+  if (u.origin !== 'http://127.0.0.1') return false
+  if (!u.pathname.startsWith('/api/')) return false
+  let decoded
+  try { decoded = decodeURIComponent(u.pathname) } catch { return false }
+  if (decoded.split('/').includes('..')) return false
+  return true
+}
+
+/** 指数退避 1s→30s，±20% 抖动（`random` 可注入 ⇒ 测试可确定）。 */
+export function backoffDelay(attempt, {
+  minMs = RECONNECT_MIN_MS, maxMs = RECONNECT_MAX_MS, jitter = RECONNECT_JITTER, random = Math.random,
+} = {}) {
+  const n = Math.min(30, Math.max(0, Math.floor(Number(attempt) || 0)))
+  const base = Math.min(maxMs, minMs * 2 ** n)
+  const delta = base * jitter
+  const jittered = base + (random() * 2 - 1) * delta
+  return Math.max(0, Math.round(jittered))
+}
+
+// ── 纯函数：HTTP 头过滤（代持 cookie；⛔ 不透传 relay 侧 cookie/authorization）──
+const HOP_BY_HOP = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer',
+  'transfer-encoding', 'upgrade', 'host', 'content-length', 'cookie', 'authorization',
+])
+const UNSAFE_RESPONSE_HEADERS = new Set([
+  'set-cookie', 'content-length', 'content-encoding', 'transfer-encoding', 'connection', 'keep-alive', 'upgrade',
+])
+
+/** relay 帧里的 headers 只做"去危险头"后转发；cookie 由隧道自己代持。 */
+export function filterRequestHeaders(headers) {
+  const out = {}
+  if (!headers || typeof headers !== 'object' || Array.isArray(headers)) return out
+  for (const [k, v] of Object.entries(headers)) {
+    const key = String(k).toLowerCase()
+    if (!key || HOP_BY_HOP.has(key) || key.startsWith('sec-websocket-')) continue
+    if (v === undefined || v === null) continue
+    out[key] = Array.isArray(v) ? v.map(String) : String(v)
+  }
+  return out
+}
+
+function filterResponseHeaders(headers) {
+  const out = {}
+  try {
+    for (const [k, v] of headers) {
+      const key = String(k).toLowerCase()
+      if (UNSAFE_RESPONSE_HEADERS.has(key)) continue
+      out[key] = v
+    }
+  } catch { /* 无 headers 的桩响应：返回空表 */ }
+  return out
+}
+
+function readSetCookies(res) {
+  try {
+    if (typeof res.headers?.getSetCookie === 'function') return res.headers.getSetCookie()
+    const single = res.headers?.get?.('set-cookie')
+    return single ? [single] : []
+  } catch { return [] }
+}
+
+const b64Json = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64')
+
+/** 只保留 origin+pathname，日志里永不带 query（可能含 token）。 */
+function safeEndpoint(raw) {
+  try {
+    const u = new URL(raw)
+    return `${u.origin}${u.pathname}`
+  } catch { return 'invalid-url' }
+}
+
+const err = (code, detail) => Object.assign(new Error(code), { code, detail })
+
+// ── RFC 6455 客户端（只做隧道需要的最小子集）────────────────────────────────
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+export const wsAcceptKey = (key) => createHash('sha1').update(String(key) + WS_GUID).digest('base64')
+
+/** 客户端→服务端文本帧：FIN+text，必须掩码。 */
+export function encodeClientTextFrame(text) {
+  const payload = Buffer.isBuffer(text) ? text : Buffer.from(String(text), 'utf8')
+  const len = payload.length
+  let headLen
+  if (len < 126) headLen = 2
+  else if (len < 65536) headLen = 4
+  else headLen = 10
+  const header = Buffer.alloc(headLen + 4)
+  header[0] = 0x81 // FIN + opcode=text
+  if (len < 126) header[1] = 0x80 | len
+  else if (len < 65536) { header[1] = 0x80 | 126; header.writeUInt16BE(len, 2) } else { header[1] = 0x80 | 127; header.writeUInt32BE(0, 2); header.writeUInt32BE(len, 6) }
+  const mask = randomBytes(4)
+  mask.copy(header, headLen)
+  const out = Buffer.alloc(header.length + len)
+  header.copy(out, 0)
+  for (let i = 0; i < len; i += 1) out[header.length + i] = payload[i] ^ mask[i & 3]
+  return out
+}
+
+function clientControlFrame(opcode, payload = Buffer.alloc(0)) {
+  const p = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), 'utf8')
+  const len = Math.min(p.length, 125)
+  const mask = randomBytes(4)
+  const out = Buffer.alloc(6 + len)
+  out[0] = 0x80 | (opcode & 0x0f)
+  out[1] = 0x80 | len
+  mask.copy(out, 2)
+  for (let i = 0; i < len; i += 1) out[6 + i] = p[i] ^ mask[i & 3]
+  return out
+}
+
+const closePayload = (code, reason) => {
+  const r = Buffer.from(String(reason || ''), 'utf8').subarray(0, 123)
+  const b = Buffer.alloc(2 + r.length)
+  b.writeUInt16BE(Number.isFinite(code) ? code : 1000, 0)
+  r.copy(b, 2)
+  return b
+}
+
+/**
+ * 增量帧解析器。服务端帧不掩码（掩码也接受）；文本/二进制都按 utf8 交给 onText
+ * （dsh 与 relay 的业务帧都是 JSON 文本）。超限 ⇒ onError({closeCode:1009})。
+ */
+export function createFrameParser({
+  onText, onPing, onPong, onClose, onError, maxPayload = MAX_RELAY_FRAME_BYTES,
+} = {}) {
+  let buf = Buffer.alloc(0)
+  let fragments = null
+  let failed = false
+
+  const fail = (reason, closeCode = 1002) => {
+    if (failed) return
+    failed = true
+    onError?.({ code: 'protocol-error', reason, closeCode })
+  }
+
+  const parseOne = () => {
+    if (buf.length < 2) return false
+    const b0 = buf[0]
+    const b1 = buf[1]
+    const fin = (b0 & 0x80) !== 0
+    const opcode = b0 & 0x0f
+    const masked = (b1 & 0x80) !== 0
+    let len = b1 & 0x7f
+    let offset = 2
+    if ((b0 & 0x70) !== 0) { fail('rsv'); return false }
+    if (len === 126) {
+      if (buf.length < 4) return false
+      len = buf.readUInt16BE(2)
+      offset = 4
+    } else if (len === 127) {
+      if (buf.length < 10) return false
+      const big = buf.readBigUInt64BE(2)
+      if (big > BigInt(Number.MAX_SAFE_INTEGER)) { fail('length'); return false }
+      len = Number(big)
+      offset = 10
+    }
+    if (len > maxPayload) { fail('too-large', 1009); return false }
+    const maskOffset = masked ? offset : -1
+    const payloadOffset = offset + (masked ? 4 : 0)
+    const total = payloadOffset + len
+    if (buf.length < total) return false
+    let payload = buf.subarray(payloadOffset, total)
+    if (masked) {
+      const mask = buf.subarray(maskOffset, maskOffset + 4)
+      const out = Buffer.allocUnsafe(len)
+      for (let i = 0; i < len; i += 1) out[i] = payload[i] ^ mask[i & 3]
+      payload = out
+    }
+    buf = buf.subarray(total)
+
+    if (opcode >= 0x8) {
+      if (!fin || len > 125) { fail('control'); return false }
+      if (opcode === 0x9) onPing?.(payload)
+      else if (opcode === 0xa) onPong?.(payload)
+      else if (opcode === 0x8) {
+        let code = 1005
+        let reason = ''
+        if (payload.length >= 2) { code = payload.readUInt16BE(0); reason = payload.subarray(2).toString('utf8') }
+        onClose?.({ code, reason, remote: true })
+      } else fail('opcode')
+      return true
+    }
+    if (opcode === 0x1 || opcode === 0x2) {
+      if (fragments) { fail('nested-fragment'); return false }
+      if (fin) { onText?.(payload.toString('utf8'), opcode); return true }
+      fragments = { opcode, chunks: [payload], size: len }
+      return true
+    }
+    if (opcode === 0x0) {
+      if (!fragments) { fail('stray-continuation'); return false }
+      fragments.chunks.push(payload)
+      fragments.size += len
+      if (fragments.size > maxPayload) { fail('too-large', 1009); return false }
+      if (fin) {
+        const whole = Buffer.concat(fragments.chunks)
+        fragments = null
+        onText?.(whole.toString('utf8'), opcode)
+      }
+      return true
+    }
+    fail('opcode')
+    return false
+  }
+
+  return {
+    push(chunk) {
+      if (failed || !chunk || !chunk.length) return
+      buf = buf.length ? Buffer.concat([buf, chunk]) : chunk
+      while (!failed && parseOne()) { /* 继续吃缓冲区 */ }
+    },
+    get buffered() { return buf.length },
+  }
+}
+
+/**
+ * 建一条 WS 客户端连接（带自定义请求头）。回调**异步**触发（与真实 socket 一致）。
+ * @returns {{send:(text:string)=>boolean, close:(code?:number,reason?:string)=>void, readyState:string}}
+ */
+export function connectWebSocket({
+  url, headers = {}, maxPayload = MAX_RELAY_FRAME_BYTES, handshakeTimeoutMs = 10_000,
+  onOpen, onText, onClose, onError,
+} = {}) {
+  const target = new URL(String(url))
+  if (target.protocol !== 'ws:' && target.protocol !== 'wss:') throw err('bad-ws-url')
+  const secure = target.protocol === 'wss:'
+  const key = randomBytes(16).toString('base64')
+  let socket = null
+  let closed = false
+  let closeNotified = false
+  let upgraded = false
+
+  const notifyClose = (info) => {
+    if (closeNotified) return
+    closeNotified = true
+    try { onClose?.(info) } catch { /* 回调失败不影响 socket 清理 */ }
+  }
+  const notifyError = (info) => { try { onError?.(info) } catch { /* noop */ } }
+  const sendRaw = (frameBuf) => {
+    if (closed || !socket || socket.destroyed) return false
+    try { socket.write(frameBuf); return true } catch { return false }
+  }
+  const send = (text) => sendRaw(encodeClientTextFrame(text))
+  const destroy = () => { try { socket?.destroy() } catch { /* noop */ } }
+  const close = (code = 1000, reason = '') => {
+    if (closed) return
+    sendRaw(clientControlFrame(0x8, closePayload(code, reason)))
+    closed = true
+    destroy()
+    notifyClose({ code, reason, local: true })
+  }
+
+  const parser = createFrameParser({
+    maxPayload,
+    onText: (text) => onText?.(text),
+    onPing: (payload) => sendRaw(clientControlFrame(0xa, payload)),
+    onPong: () => {},
+    onClose: (info) => {
+      sendRaw(clientControlFrame(0x8, closePayload(info.code, info.reason)))
+      closed = true
+      destroy()
+      notifyClose(info)
+    },
+    onError: (e) => {
+      notifyError(e)
+      sendRaw(clientControlFrame(0x8, closePayload(e.closeCode || 1002, '')))
+      closed = true
+      destroy()
+      notifyClose({ code: e.closeCode || 1002, reason: e.reason || 'protocol-error' })
+    },
+  })
+
+  const reqHeaders = {
+    Connection: 'Upgrade',
+    Upgrade: 'websocket',
+    'Sec-WebSocket-Version': '13',
+    'Sec-WebSocket-Key': key,
+    ...headers,
+  }
+  const path = `${target.pathname}${target.search}`
+  const req = (secure ? https : http).request({
+    host: target.hostname,
+    port: target.port || (secure ? 443 : 80),
+    path,
+    method: 'GET',
+    headers: reqHeaders,
+  })
+  const timer = setTimeout(() => req.destroy(new Error('handshake-timeout')), handshakeTimeoutMs)
+  timer.unref?.()
+
+  req.on('upgrade', (res, sock, head) => {
+    upgraded = true
+    clearTimeout(timer)
+    socket = sock
+    sock.setNoDelay?.(true)
+    sock.setTimeout?.(0)
+    if (String(res.headers['sec-websocket-accept'] || '') !== wsAcceptKey(key)) {
+      notifyError({ code: 'handshake-accept' })
+      closed = true
+      destroy()
+      notifyClose({ code: 1006, reason: 'handshake-accept' })
+      return
+    }
+    sock.on('data', (chunk) => parser.push(chunk))
+    sock.on('error', () => {
+      closed = true
+      notifyClose({ code: 1006, reason: 'socket-error' })
+    })
+    sock.on('close', () => {
+      closed = true
+      notifyClose({ code: 1006, reason: 'socket-closed' })
+    })
+    if (head && head.length) parser.push(head)
+    try { onOpen?.() } catch { /* 回调失败不影响连接 */ }
+  })
+  req.on('response', (res) => {
+    clearTimeout(timer)
+    try { res.resume?.() } catch { /* noop */ }
+    notifyError({ code: 'handshake-status', status: res.statusCode })
+    closed = true
+    notifyClose({ code: 1006, reason: 'handshake-status', status: res.statusCode })
+  })
+  req.on('error', (e) => {
+    clearTimeout(timer)
+    if (upgraded) return
+    notifyError({ code: e?.code || 'handshake-error' })
+    closed = true
+    notifyClose({ code: 1006, reason: 'handshake-error' })
+  })
+  req.end()
+
+  return {
+    send,
+    close,
+    get readyState() { return closed ? 'closed' : (socket ? 'open' : 'connecting') },
+  }
+}
+
+// ── 隧道主体 ────────────────────────────────────────────────────────────────
+const DEFAULT_DSH_BASE = 'http://127.0.0.1:3080'
+
+/** 把 `ws_open` 的 query（字符串/对象）拼到 path 上；⛔ 不放行换行/绝对 URL。 */
+export function buildWsPath(path, query) {
+  if (!isAllowedPath(path)) return null
+  if (query === undefined || query === null || query === '') return path
+  let qs
+  if (typeof query === 'string') qs = query.replace(/^[?&]+/, '')
+  else if (typeof query === 'object' && !Array.isArray(query)) qs = new URLSearchParams(query).toString()
+  else return null
+  if (/[\r\n]/.test(qs)) return null
+  if (!qs) return path
+  const joined = `${path}${path.includes('?') ? '&' : '?'}${qs}`
+  return isAllowedPath(joined) ? joined : null
+}
+
+/**
+ * 启动隧道（`ARGENT_TUNNEL=1` 且 machineId 可解析才真正启动）。
+ * @param {object} options 测试/宿主注入点：config、env、dataDir、tokenProvider、fetchImpl、
+ *   connectWs、timers、random、now、log、dshBase、version、deviceName、pingMs、pongTimeoutMs、
+ *   reconnect、autoStart
+ * @returns {null|{stop:()=>void, getStats:()=>object, machineId:string, endpoint:string}}
+ */
+export function startTunnel(options = {}) {
+  const env = options.env || process.env
+  const logFn = options.log || ((m) => console.log(`[argent] ${m}`))
+  const cfg = options.config || readTunnelConfig({ env, dataDir: options.dataDir })
+  if (!cfg || cfg.enabled === false) return null
+  if (!cfg.ok) {
+    const why = cfg.reason === 'no-machine-id'
+      ? '缺 machineId（ARGENT_MACHINE_ID 与 agent-report.json#machineId 都没有）'
+      : cfg.reason === 'bad-url' ? 'ARGENT_TUNNEL_URL 不是 ws/wss 地址' : String(cfg.reason || 'unknown')
+    logFn(`隧道未启动：${why}`)
+    return null
+  }
+
+  const timers = options.timers || { setTimeout, clearTimeout }
+  const random = options.random || Math.random
+  const now = options.now || Date.now
+  const fetchImpl = options.fetchImpl || globalThis.fetch
+  const connect = options.connectWs || connectWebSocket
+  const endpoint = options.url || cfg.url
+  const machineId = options.machineId || cfg.machineId
+  const deviceName = options.deviceName || cfg.deviceName || hostname()
+  const version = options.version || readPkgVersion()
+  const dshBase = String(options.dshBase || env.ARGENT_DSH_BASE || DEFAULT_DSH_BASE).replace(/\/+$/, '')
+  const dshWsBase = dshBase.replace(/^http:/, 'ws:').replace(/^https:/, 'wss:')
+  const pingMs = options.pingMs ?? PING_MS
+  const pongTimeoutMs = options.pongTimeoutMs ?? PONG_TIMEOUT_MS
+  const reconnect = {
+    minMs: RECONNECT_MIN_MS, maxMs: RECONNECT_MAX_MS, jitter: RECONNECT_JITTER, ...(options.reconnect || {}),
+  }
+  const tokenProvider = options.tokenProvider || (() => resolveAccountToken({ env }).token || '')
+
+  const stats = {
+    connects: 0, disconnects: 0, framesIn: 0, framesOut: 0, bytesIn: 0, bytesOut: 0,
+    errors: 0, http: 0, wsOpen: 0,
+  }
+  const dsh = { cookie: '' }
+  const streams = new Map()
+  let stopped = false
+  let attempt = 0
+  let ws = null
+  let reconnectTimer = null
+  let pingTimer = null
+  let tokenMissingLogged = false
+
+  const scheduleReconnect = () => {
+    if (stopped) return
+    const delay = backoffDelay(attempt, { ...reconnect, random })
+    attempt += 1
+    logFn(`隧道将重连（${delay}ms 后，第 ${attempt} 次）`)
+    reconnectTimer = timers.setTimeout(() => { reconnectTimer = null; void connectOnce() }, delay)
+    reconnectTimer?.unref?.()
+  }
+
+  const stopHeartbeat = () => {
+    if (pingTimer) { timers.clearTimeout(pingTimer); pingTimer = null }
+  }
+
+  const send = (obj) => {
+    if (!ws) return false
+    let text
+    try { text = encodeFrame(obj) } catch { return false }
+    const ok = ws.send(text)
+    if (ok) {
+      stats.framesOut += 1
+      stats.bytesOut += Buffer.byteLength(text, 'utf8')
+    }
+    return ok
+  }
+
+  // ── dsh 准入 cookie（仅内存；401/403 重换一次）──────────────────────────
+  const acquireCookie = async ({ refresh = false } = {}) => {
+    if (!refresh && dsh.cookie) return dsh.cookie
+    let access
+    try {
+      access = await fetchImpl(`${dshBase}${DSH_ACCESS_PATH}`, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(5000),
+      })
+    } catch { throw err('access-unreachable') }
+    let body = null
+    try { body = await access.json() } catch { body = null }
+    if (!access.ok || !body || body.ok !== true || !body.token) throw err('access-unavailable', `HTTP ${access.status}`)
+    let res
+    try {
+      res = await fetchImpl(`${dshBase}/?token=${encodeURIComponent(String(body.token))}`, {
+        redirect: 'manual',
+        signal: AbortSignal.timeout(5000),
+      })
+    } catch { throw err('cookie-unreachable') }
+    const cookies = readSetCookies(res)
+      .map((c) => String(c).split(';')[0].trim())
+      .filter((c) => c.startsWith('dsh-auth-'))
+    if (!cookies.length) throw err('cookie-missing', `HTTP ${res.status}`)
+    dsh.cookie = cookies.join('; ')
+    return dsh.cookie
+  }
+
+  const dshRequest = async ({ method, path, headers, body, retry = true }) => {
+    const build = async (cookie) => {
+      const h = filterRequestHeaders(headers)
+      h.cookie = cookie
+      const init = { method, headers: h, redirect: 'manual', signal: AbortSignal.timeout(30_000) }
+      if (body && body.length && method !== 'GET' && method !== 'HEAD') init.body = body
+      return { init, headers: h }
+    }
+    const first = await build(await acquireCookie())
+    let res = await fetchImpl(`${dshBase}${path}`, first.init)
+    if (retry && (res.status === 401 || res.status === 403)) {
+      const retried = await build(await acquireCookie({ refresh: true }))
+      res = await fetchImpl(`${dshBase}${path}`, retried.init)
+    }
+    const buf = Buffer.from(await res.arrayBuffer())
+    if (buf.length > MAX_DSH_RESPONSE_BYTES) throw err('response-too-large')
+    return { status: res.status, headers: filterResponseHeaders(res.headers), body: buf }
+  }
+
+  // ── 帧处理 ────────────────────────────────────────────────────────────────
+  const handleHttp = async (frame) => {
+    stats.http += 1
+    const id = frame.id
+    if (!isAllowedPath(frame.path)) {
+      send(FRAME.httpRes({ id, status: 403, headers: { 'content-type': 'application/json' }, bodyB64: b64Json({ ok: false, error: 'path-not-allowed' }) }))
+      return
+    }
+    let body = Buffer.alloc(0)
+    if (frame.bodyB64) {
+      try { body = Buffer.from(String(frame.bodyB64), 'base64') } catch { body = null }
+      if (!body) {
+        send(FRAME.httpRes({ id, status: 400, headers: { 'content-type': 'application/json' }, bodyB64: b64Json({ ok: false, error: 'bad-body' }) }))
+        return
+      }
+      if (body.length > MAX_HTTP_BODY_BYTES) {
+        send(FRAME.httpRes({ id, status: 413, headers: { 'content-type': 'application/json' }, bodyB64: b64Json({ ok: false, error: 'body-too-large' }) }))
+        return
+      }
+    }
+    const method = String(frame.method || 'GET').toUpperCase()
+    if (!/^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(method)) {
+      send(FRAME.httpRes({ id, status: 405, headers: { 'content-type': 'application/json' }, bodyB64: b64Json({ ok: false, error: 'method-not-allowed' }) }))
+      return
+    }
+    try {
+      const res = await dshRequest({ method, path: frame.path, headers: frame.headers, body })
+      send(FRAME.httpRes({
+        id, status: res.status, headers: res.headers,
+        bodyB64: res.body.length ? res.body.toString('base64') : undefined,
+      }))
+    } catch (e) {
+      stats.errors += 1
+      const reason = String(e?.code || 'dsh-error')
+      logFn(`隧道代理 dsh 失败：${reason}`)
+      send(FRAME.httpRes({
+        id, status: 502, headers: { 'content-type': 'application/json' },
+        bodyB64: b64Json({ ok: false, error: 'dsh-unavailable', reason }),
+      }))
+    }
+  }
+
+  const closeStream = (id, code = 1000, reason = '') => {
+    const stream = streams.get(id)
+    if (!stream) return
+    stream.closed = true
+    streams.delete(id)
+    try { stream.handle?.close(code, reason) } catch { /* noop */ }
+  }
+
+  const closeAllStreams = (code = 1001, reason = 'relay-closed') => {
+    for (const id of [...streams.keys()]) closeStream(id, code, reason)
+  }
+
+  const connectDshWs = ({ path, cookie, stream }) => new Promise((resolve, reject) => {
+    let open = false
+    let settled = false
+    let handle = null
+    const fail = (e) => { if (settled) return; settled = true; reject(e) }
+    const done = () => { if (settled) return; settled = true; open = true; resolve(handle) }
+    try {
+      handle = connect({
+        url: `${dshWsBase}${path}`,
+        headers: { cookie, host: new URL(dshBase).host },
+        maxPayload: MAX_DSH_FRAME_BYTES,
+        onOpen: () => done(),
+        onText: (text) => {
+          if (!open || stream.closed) return
+          if (Buffer.byteLength(text, 'utf8') > MAX_RELAY_FRAME_BYTES) {
+            stats.errors += 1
+            send(FRAME.wsClose(stream.id, 1009, 'message-too-large'))
+            closeStream(stream.id, 1009, 'message-too-large')
+            return
+          }
+          send(FRAME.wsMsg(stream.id, text))
+        },
+        onClose: (info) => {
+          if (!open) { fail({ code: 'closed-before-open', status: info?.status }); return }
+          if (stream.closed) return
+          stream.closed = true
+          streams.delete(stream.id)
+          send(FRAME.wsClose(stream.id, info?.code, info?.reason))
+        },
+        onError: (e) => {
+          if (!open) { fail(e); return }
+          stats.errors += 1
+          logFn(`隧道 dsh 流错误：${e?.code || 'dsh-ws-error'}`)
+        },
+      })
+    } catch (e) { fail(e) }
+  })
+
+  const openDshWs = async (path, stream) => {
+    let cookie = await acquireCookie()
+    for (let i = 0; i < 2; i += 1) {
+      try {
+        return await connectDshWs({ path, cookie, stream })
+      } catch (e) {
+        if (i === 0 && e?.code === 'handshake-status' && (e.status === 401 || e.status === 403)) {
+          cookie = await acquireCookie({ refresh: true })
+          continue
+        }
+        throw e
+      }
+    }
+    throw err('dsh-ws-unavailable')
+  }
+
+  const handleWsOpen = async (frame) => {
+    stats.wsOpen += 1
+    const id = frame.id
+    if (!isAllowedPath(frame.path)) {
+      send(FRAME.wsClose(id, 1008, 'path-not-allowed'))
+      return
+    }
+    const path = buildWsPath(frame.path, frame.query)
+    if (!path) {
+      send(FRAME.wsClose(id, 1008, 'bad-query'))
+      return
+    }
+    if (streams.has(id)) closeStream(id, 1000, 'replaced')
+    const stream = { id, handle: null, closed: false }
+    streams.set(id, stream)
+    try {
+      const handle = await openDshWs(path, stream)
+      stream.handle = handle
+      if (stream.closed) { try { handle.close(1000, 'cancelled') } catch { /* noop */ }; return }
+      send(FRAME.wsReady(id))
+    } catch (e) {
+      stats.errors += 1
+      logFn(`隧道打开 dsh 流失败：${e?.code || 'dsh-ws-error'}`)
+      const code = String(e?.code || 'dsh-ws-error').slice(0, 60)
+      if (streams.get(id) === stream) { stream.closed = true; streams.delete(id) }
+      send(FRAME.wsClose(id, 1011, code))
+    }
+  }
+
+  const handleWsMsg = (frame) => {
+    const stream = streams.get(frame.id)
+    if (!stream || stream.closed || !stream.handle) { stats.errors += 1; return }
+    const data = typeof frame.data === 'string' ? frame.data : JSON.stringify(frame.data ?? '')
+    if (!stream.handle.send(data)) stats.errors += 1
+  }
+
+  const handleWsClose = (frame) => {
+    closeStream(frame.id, Number.isFinite(frame.code) ? frame.code : 1000, String(frame.reason || ''))
+  }
+
+  const handleRelayText = (text, conn) => {
+    const size = Buffer.byteLength(String(text ?? ''), 'utf8')
+    stats.framesIn += 1
+    stats.bytesIn += size
+    if (size > MAX_RELAY_FRAME_BYTES) {
+      stats.errors += 1
+      logFn('隧道收到超大帧，断开连接')
+      try { conn.handle?.close(1009, 'frame-too-large') } catch { /* noop */ }
+      return
+    }
+    let frame
+    try { frame = decodeFrame(text) } catch { stats.errors += 1; logFn('隧道收到非法帧（已忽略）'); return }
+    switch (frame.t) {
+      case 'ping': send(FRAME.pong(frame.ts)); break
+      case 'pong': conn.lastPong = now(); break
+      case 'http': void handleHttp(frame); break
+      case 'ws_open': void handleWsOpen(frame); break
+      case 'ws_msg': handleWsMsg(frame); break
+      case 'ws_close': handleWsClose(frame); break
+      default: stats.errors += 1; logFn(`隧道收到未知帧类型（已忽略）：${String(frame.t).slice(0, 24)}`)
+    }
+  }
+
+  const startHeartbeat = (conn) => {
+    stopHeartbeat()
+    const tick = () => {
+      if (stopped || conn.closed || !conn.open) return
+      if (now() - conn.lastPong > pongTimeoutMs) {
+        stats.errors += 1
+        logFn(`隧道心跳超时（${pongTimeoutMs}ms 无 pong），重连`)
+        try { conn.handle?.close(1001, 'pong-timeout') } catch { /* noop */ }
+        return
+      }
+      send(FRAME.ping(now()))
+      pingTimer = timers.setTimeout(tick, pingMs)
+      pingTimer?.unref?.()
+    }
+    pingTimer = timers.setTimeout(tick, pingMs)
+    pingTimer?.unref?.()
+  }
+
+  const handleRelayClose = (conn, info) => {
+    conn.closed = true
+    stopHeartbeat()
+    closeAllStreams(1001, 'relay-closed')
+    if (ws === conn.handle) ws = null
+    if (conn.open) {
+      stats.disconnects += 1
+      logFn(`隧道连接已断开（code=${info?.code ?? 1006}）`)
+    }
+    if (stopped) return
+    scheduleReconnect()
+  }
+
+  const connectOnce = async () => {
+    if (stopped) return
+    let token = ''
+    try { token = await tokenProvider() } catch { token = '' }
+    if (!token) {
+      if (!tokenMissingLogged) {
+        logFn('隧道未连接：未登录问述账号（WHYSHU_API_KEY 缺失），将持续重试')
+        tokenMissingLogged = true
+      }
+      scheduleReconnect()
+      return
+    }
+    tokenMissingLogged = false
+    const conn = { handle: null, open: false, closed: false, lastPong: 0 }
+    let handle
+    try {
+      handle = connect({
+        url: endpoint,
+        headers: { Authorization: `Bearer ${token}`, 'x-argent-machine-id': machineId },
+        maxPayload: MAX_RELAY_FRAME_BYTES,
+        onOpen: () => {
+          if (stopped || conn.closed) return
+          conn.open = true
+          attempt = 0
+          stats.connects += 1
+          conn.lastPong = now()
+          logFn(`隧道已注册（machineId=${machineId}，${safeEndpoint(endpoint)}）`)
+          send(FRAME.hello({ machineId, deviceName, version }))
+          startHeartbeat(conn)
+        },
+        onText: (text) => { if (ws === conn.handle) handleRelayText(text, conn) },
+        onClose: (info) => handleRelayClose(conn, info),
+        onError: (e) => {
+          stats.errors += 1
+          logFn(`隧道连接错误：${e?.code || 'unknown'}${e?.status ? `（HTTP ${e.status}）` : ''}`)
+        },
+      })
+    } catch (e) {
+      stats.errors += 1
+      logFn(`隧道连接失败：${e?.code || 'connect-error'}`)
+      scheduleReconnect()
+      return
+    }
+    conn.handle = handle
+    ws = handle
+  }
+
+  const stop = () => {
+    if (stopped) return
+    stopped = true
+    if (reconnectTimer) { timers.clearTimeout(reconnectTimer); reconnectTimer = null }
+    stopHeartbeat()
+    closeAllStreams(1000, 'shutdown')
+    const closing = ws
+    ws = null
+    try { closing?.close(1000, 'shutdown') } catch { /* noop */ }
+    logFn('隧道已停止')
+  }
+
+  if (options.autoStart !== false) void connectOnce()
+
+  return {
+    stop,
+    getStats: () => ({ ...stats }),
+    machineId,
+    endpoint: safeEndpoint(endpoint),
+  }
+}