dsh-tailscale-remote 0.0.0-stage → 0.2.0

package/index.js

@@ -0,0 +1,1003 @@
+/**
+ * dsh-tailscale-remote — 把本机 DSH Web GUI 通过 Tailscale Serve 暴露到 tailnet 上，
+ * 让手机在任何网络下都能打开；DSH 退出时把这条路由撤掉。
+ *
+ * 设计要点（都是实测结论，别凭直觉改）：
+ *
+ * 1. `tailscale serve` **保留客户端的 Host 头**（实测：请求 tailnet 地址时，后端收到
+ *    的 `host` 就是 `xxx.ts.net:7259`）。而 DSH 的 `/api` fence（`isTrustedApiRequest`）
+ *    要求 Host 是回环地址或命中 `trustedHosts`，否则一律 403。所以插件必须把
+ *    `<dnsName>:<port>` 塞进 `connection.trustedHosts`，否则手机上页面能开、RPC 全 403。
+ *
+ * 2. `connection.trustedHosts` 是服务上一个**公开的可变数组**，fence 每次请求都读它，
+ *    所以运行时 push 立刻生效，不需要改 profile 的 cordis.yml。
+ *
+ * 3. 手机上要"打开网页就能连"，靠的是 `connection.authenticatedUrl(url)` 生成的一次性
+ *    令牌链接：带 `?token=` 打开会种下 30 天的 HttpOnly cookie，之后书签直接访问即可。
+ *
+ * 4. 退出清理挂在 `ctx.effect(() => () => ...)` 上：这是唯一可靠的关停挂点（没有
+ *    `app-boot/shutdown` 事件，Host 侧也没有 Electron 的 `before-quit`）。清理必须
+ *    幂等、绝不 reject（reject 的 disposer 会让 runProfile 抛 AggregateError）。
+ *
+ * @module dsh-tailscale-remote
+ */
+
+import { spawn } from 'node:child_process'
+import { createHash, createHmac, randomBytes } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** 稳定插件名。 */
+export const name = 'dsh-tailscale-remote'
+
+/** 清理阶段单条命令的超时（毫秒）。进程关停预算很紧，宁可放弃也不要拖住。 */
+const TEARDOWN_TIMEOUT_MS = 3500
+
+/** 启动阶段单条命令的超时（毫秒）。`tailscale up` 可能要等网络。 */
+const SETUP_TIMEOUT_MS = 12000
+
+/** 各平台 tailscale 可执行文件的候选路径，按顺序探测。 */
+const BINARY_CANDIDATES = {
+  win32: [
+    process.env.TAILSCALE_PATH,
+    'C:\\Program Files\\Tailscale\\tailscale.exe',
+    'C:\\Program Files (x86)\\Tailscale\\tailscale.exe',
+    'tailscale',
+  ],
+  darwin: [
+    process.env.TAILSCALE_PATH,
+    '/Applications/Tailscale.app/Contents/MacOS/Tailscale',
+    '/usr/local/bin/tailscale',
+    '/opt/homebrew/bin/tailscale',
+    '/usr/bin/tailscale',
+    'tailscale',
+  ],
+  linux: [
+    process.env.TAILSCALE_PATH,
+    '/usr/bin/tailscale',
+    '/usr/local/bin/tailscale',
+    '/usr/sbin/tailscale',
+    'tailscale',
+  ],
+}
+
+/**
+ * 各平台的 Tailscale **桌面客户端**——也就是用户手动「打开 Tailscale」的那一下。
+ *
+ * 为什么需要它：在 Windows（以及 macOS 的 App 形态）上，tailscaled 由客户端负责
+ * 初始化 backend。用户从托盘「完全退出」之后，服务还在跑、`tailscale status` 报
+ * `BackendState: NoState` + `Health: ["Tailscale is starting. Please wait."]`，
+ * 此时 **`tailscale up` 会「立刻 exit 0、不输出任何东西、也什么都不做」**（实测）。
+ * 只有把客户端拉起来，backend 才会真正连上（实测：启动后立刻变 Running + Online）。
+ */
+const GUI_CANDIDATES = {
+  win32: [
+    process.env.TAILSCALE_GUI_PATH,
+    'C:\\Program Files\\Tailscale\\tailscale-ipn.exe',
+    'C:\\Program Files (x86)\\Tailscale\\tailscale-ipn.exe',
+  ],
+  darwin: [process.env.TAILSCALE_GUI_PATH, '/Applications/Tailscale.app'],
+  linux: [process.env.TAILSCALE_GUI_PATH],
+}
+
+/** 把行内注释里提到的"配置"收敛成带默认值的普通对象（本包刻意不依赖 schemastery）。 */
+function normalizeConfig(raw) {
+  const source = raw !== null && typeof raw === 'object' ? raw : {}
+  const port = Number(source.httpsPort)
+  return {
+    enabled: source.enabled !== false,
+    httpsPort: Number.isInteger(port) && port > 0 && port <= 65535 ? port : 7259,
+    connectOnStart: source.connectOnStart !== false,
+    serveOnStart: source.serveOnStart !== false,
+    teardownOnExit: source.teardownOnExit !== false,
+    trustedHosts: source.trustedHosts !== false,
+    binaryPath: typeof source.binaryPath === 'string' && source.binaryPath !== '' ? source.binaryPath : undefined,
+    guiPath: typeof source.guiPath === 'string' && source.guiPath !== '' ? source.guiPath : undefined,
+    // 等 backend 就绪的两段预算：先等 `tailscale up`，再等桌面客户端。
+    readyTimeoutMs: Number.isFinite(source.readyTimeoutMs) && source.readyTimeoutMs >= 0 ? source.readyTimeoutMs : 8000,
+    guiReadyTimeoutMs:
+      Number.isFinite(source.guiReadyTimeoutMs) && source.guiReadyTimeoutMs >= 0 ? source.guiReadyTimeoutMs : 25000,
+    stateFile: typeof source.stateFile === 'string' && source.stateFile !== '' ? source.stateFile : undefined,
+    // 登录 cookie 的有效期（天）。DSH 默认 30 天，对「手机随时连」太短；
+    // 这里直接改 connection 上那个活的 maxAgeMilliseconds，让种下的 cookie 长期有效。
+    // 0 表示不动 DSH 的默认值。
+    cookieMaxAgeDays:
+      Number.isFinite(source.cookieMaxAgeDays) && source.cookieMaxAgeDays >= 0 ? source.cookieMaxAgeDays : 3650,
+    // 是否注册一个「稳定登录入口」路由（/remote/<持久密钥>），让手机不用去翻令牌。
+    loginRoute: source.loginRoute !== false,
+  }
+}
+
+/**
+ * 跑一条命令，收集 stdout/stderr，超时就杀掉。
+ * 永不 reject —— 调用方永远拿到一个结果对象。
+ */
+function run(file, args, timeoutMs) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(file, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (error) {
+      resolve({ ok: false, code: -1, stdout: '', stderr: String(error?.message ?? error) })
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(result)
+    }
+    // 刻意不用 AbortSignal.timeout()：它的定时器是 unref 的，关停阶段可能永远不触发。
+    const timer = setTimeout(() => {
+      try {
+        child.kill()
+      } catch {
+        /* 进程可能已经没了 */
+      }
+      finish({ ok: false, code: -1, stdout, stderr: `${stderr}\n[超时 ${String(timeoutMs)}ms]`.trim() })
+    }, timeoutMs)
+    child.stdout?.setEncoding('utf8')
+    child.stderr?.setEncoding('utf8')
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk
+    })
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk
+    })
+    child.on('error', (error) => finish({ ok: false, code: -1, stdout, stderr: String(error?.message ?? error) }))
+    child.on('close', (code) => finish({ ok: code === 0, code: code ?? -1, stdout, stderr }))
+  })
+}
+
+/** 探测可用的 tailscale 可执行文件；找不到返回 undefined。 */
+async function resolveBinary(ctx, configured) {
+  const candidates = [...(BINARY_CANDIDATES[process.platform] ?? ['tailscale'])]
+  if (configured !== undefined) candidates.unshift(configured)
+  for (const candidate of candidates) {
+    if (candidate === undefined || candidate === '') continue
+    // 带路径分隔符的候选先做存在性检查，省一次进程启动。
+    if (/[\\/]/.test(candidate) && !existsSync(candidate)) continue
+    const result = await run(candidate, ['version'], 5000)
+    if (result.ok) return candidate
+  }
+  return undefined
+}
+
+/** 解析 `tailscale status --json`；失败返回 undefined。 */
+async function readStatus(binary) {
+  const result = await run(binary, ['status', '--json'], 6000)
+  if (!result.ok) return undefined
+  try {
+    return JSON.parse(result.stdout)
+  } catch {
+    return undefined
+  }
+}
+
+/** 解析 `tailscale serve status --json`；失败返回 undefined（视为"无配置"）。 */
+async function readServeStatus(binary) {
+  const result = await run(binary, ['serve', 'status', '--json'], 6000)
+  if (result.ok && result.stdout.trim() !== '') {
+    try {
+      return JSON.parse(result.stdout)
+    } catch {
+      return undefined
+    }
+  }
+  // 没有 serve 配置时该命令可能以非零码退出，这里统一当作空配置。
+  return undefined
+}
+
+/** `Self.DNSName` 带结尾点，去掉它才是可用的主机名。 */
+function dnsNameOf(status) {
+  const raw = status?.Self?.DNSName
+  if (typeof raw !== 'string' || raw === '') return undefined
+  return raw.replace(/\.$/, '').toLowerCase()
+}
+
+/** 探测桌面客户端路径；找不到返回 undefined。 */
+function resolveGui(configured) {
+  const candidates = [...(GUI_CANDIDATES[process.platform] ?? [])]
+  if (typeof configured === 'string' && configured !== '') candidates.unshift(configured)
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string' || candidate === '') continue
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * 启动桌面客户端。**刻意 detached + unref**：它是常驻托盘程序，不能因为 DSH
+ * 退出就被带走（也不能让 DSH 因为它的 stdio 一直挂着不退出）。
+ * @returns 是否成功发起启动（不代表 backend 已就绪）。
+ */
+function launchGui(target) {
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(target, [], { detached: true, stdio: 'ignore', windowsHide: false })
+      child.on('error', () => resolve(false))
+      child.unref()
+      // 只要没有立刻报错就当作已发起；backend 是否起来由 waitForRunning 判定。
+      setTimeout(() => resolve(true), 300)
+    } catch {
+      resolve(false)
+    }
+  })
+}
+
+/** backend 是否已经 Running。 */
+async function isRunning(deps, binary) {
+  const status = await deps.readStatus(binary)
+  return status?.BackendState === 'Running'
+}
+
+/** 轮询等待 backend 变 Running；超时返回 false（绝不抛）。 */
+async function waitForRunning(deps, binary, timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    if (await isRunning(deps, binary)) return true
+    if (Date.now() >= deadline) return false
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+  }
+}
+
+/**
+ * 确保 tailscale backend 真的在 Running —— **光看 `tailscale up` 的退出码是不够的**。
+ *
+ * 顺序：已经 Running 就直接成功 → `tailscale up` → 还不 Running 就拉起桌面客户端。
+ * 每一步都用 `readStatus` 验证，而不是相信命令的退出码。
+ * @returns true 表示 backend 确实 Running（此时才值得去配 Serve 路由）。
+ */
+async function ensureRunning(binary, config, deps, logger, undo) {
+  if (await isRunning(deps, binary)) {
+    logger.info('tailscale-remote: tailscale 本来就在运行，退出时不会把它断开')
+    return true
+  }
+  if (!config.connectOnStart) {
+    logger.warn('tailscale-remote: tailscale 未连接，且 connectOnStart=false，跳过')
+    return false
+  }
+
+  logger.info('tailscale-remote: tailscale 未连接，执行 tailscale up')
+  const up = await deps.run(binary, ['up'], SETUP_TIMEOUT_MS)
+  if (!up.ok) {
+    logger.warn(`tailscale-remote: tailscale up 失败: ${(up.stderr || up.stdout).trim().slice(0, 300)}`)
+  }
+  if (await waitForRunning(deps, binary, config.readyTimeoutMs)) {
+    undo.startedTailscale = true
+    return true
+  }
+
+  // Windows/macOS：`tailscale up` 在客户端被完全退出后会「exit 0 但什么都不做」，
+  // 必须把桌面客户端拉起来才会真正初始化 backend。
+  const gui = deps.resolveGui(config.guiPath)
+  if (gui === undefined) {
+    logger.warn(
+      'tailscale-remote: tailscale up 没有生效（backend 仍不是 Running）。' +
+        '请手动打开 Tailscale 客户端登录/连接，或设置 config.guiPath 指向它',
+    )
+    return false
+  }
+  logger.info(`tailscale-remote: tailscale up 未生效，改为启动桌面客户端 ${gui}`)
+  const launched = await deps.launchGui(gui)
+  if (!launched) {
+    logger.warn(`tailscale-remote: 启动 ${gui} 失败`)
+    return false
+  }
+  if (await waitForRunning(deps, binary, config.guiReadyTimeoutMs)) {
+    logger.info('tailscale-remote: tailscale 已由桌面客户端拉起')
+    undo.startedTailscale = true
+    return true
+  }
+  logger.warn('tailscale-remote: 等不到 tailscale 进入 Running；请检查客户端是否需要登录')
+  return false
+}
+
+/**
+ * 判定 7259 端口上现有的 serve 路由与我们的目标是什么关系。
+ * 只有"空着"或"本来就是指向我们的回环代理"才动手；其余一律视为冲突，不覆盖。
+ */
+function classifyServe(status, port, target) {
+  const web = status?.Web
+  const tcp = status?.TCP
+  const authority = Object.keys(web ?? {}).find((key) => {
+    try {
+      return Number(new URL(`https://${key}`).port) === port
+    } catch {
+      return false
+    }
+  })
+  if (authority === undefined) {
+    const claimed = tcp !== undefined && Object.prototype.hasOwnProperty.call(tcp, String(port))
+    if (claimed) return { kind: 'conflict', reason: `TCP ${String(port)} 已被其它 Tailscale Serve 配置占用` }
+    return { kind: 'absent' }
+  }
+  const handlers = web?.[authority]?.Handlers
+  if (handlers === null || typeof handlers !== 'object') {
+    return { kind: 'conflict', reason: `${authority} 的 Serve 处理程序无法识别` }
+  }
+  const paths = Object.keys(handlers)
+  if (paths.length !== 1 || paths[0] !== '/') {
+    return { kind: 'conflict', reason: `${authority} 上还有其它路径处理程序（${paths.join(', ')}）` }
+  }
+  const proxy = handlers['/']?.Proxy
+  if (typeof proxy !== 'string') return { kind: 'conflict', reason: `${authority} 的根处理程序不是反向代理` }
+  // tailscale 写回的形态可能带尾斜杠；归一化后比较，否则会把自己的路由误判成陈旧路由，
+  // 进而把它记成"本次新建"，退出时撤掉一条其实不是自己建的路由。
+  const normalized = proxy.replace(/\/+$/, '')
+  if (normalized === target) return { kind: 'exact', authority }
+  // 指向另一个回环地址 = 上一次 DSH 换端口后留下的陈旧路由，可以接管。
+  if (/^https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?$/i.test(normalized)) {
+    return { kind: 'stale', authority, previousProxy: proxy }
+  }
+  return { kind: 'conflict', reason: `${authority} 已代理到 ${proxy}` }
+}
+
+/**
+ * 解析 DSH home，与 `@deepseek-ai/dsh-home-paths` 的 `resolveDshHome` 同一套优先级：
+ * 显式配置 > `$DSH_HOME`（空/纯空白视为未设） > `~/.dsh`。
+ *
+ * 注意：**Host 进程的环境里通常没有 `DSH_HOME`**（那个变量是 shell 调用时才注入的），
+ * 所以只读 `process.env.DSH_HOME` 会让状态文件永远写不出来。这里必须回落到 `~/.dsh`。
+ */
+function resolveDshHome(configured) {
+  const fromConfig = typeof configured === 'string' && configured.trim() !== '' ? configured : undefined
+  if (fromConfig !== undefined) return fromConfig
+  const fromEnv = process.env.DSH_HOME
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return fromEnv
+  return join(homedir(), '.dsh')
+}
+
+/** 把当前远程地址写一份到磁盘，方便用户随时取用；失败只记日志。 */
+async function persistState(ctx, state) {
+  const home = resolveDshHome(process.env.DSH_HOME)
+  const path = state.stateFile ?? join(home, 'tailscale-remote.json')
+  try {
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+  } catch (error) {
+    ctx.logger.warn(`tailscale-remote: 写入 ${path} 失败：${String(error?.message ?? error)}`)
+  }
+}
+
+/** 读回上一次的状态文件；不存在或坏了都返回 undefined（绝不抛）。 */
+async function loadState(scope, config) {
+  const home = resolveDshHome(process.env.DSH_HOME)
+  const path = config.stateFile ?? join(home, 'tailscale-remote.json')
+  try {
+    const raw = await readFile(path, 'utf8')
+    const parsed = JSON.parse(raw)
+    return parsed !== null && typeof parsed === 'object' ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 取得（或首次生成）**跨重启稳定**的登录密钥。
+ *
+ * 为什么要它：DSH 的登录令牌是**进程级**的（`PROCESS_LAUNCH_TOKENS` 以 root ctx 为键），
+ * 每次重启 DSH 都会换，用户根本没法记、也没法存成书签。这里自己生成一个持久随机密钥，
+ * 存进状态文件，让「手机上的登录链接」永远不变。
+ */
+async function ensureLoginSecret(scope, config, deps) {
+  const previous = await deps.loadState(scope, config)
+  const existing = previous?.loginSecret
+  if (typeof existing === 'string' && /^[A-Za-z0-9_-]{22,}$/.test(existing)) return existing
+  return randomBytes(24).toString('base64url')
+}
+
+/** DSH 的浏览器会话 cookie 前缀（与 client-connection 的 `COOKIE_PREFIX` 一致）。 */
+const COOKIE_PREFIX = 'dsh-auth-'
+
+/** base64url 编码（与 DSH 内部实现逐字一致：+→-、/→_、去掉尾部 =）。 */
+function base64url(buffer) {
+  return buffer.toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '')
+}
+
+/**
+ * 直接**铸造** DSH 的浏览器会话 cookie。
+ *
+ * 为什么要自己铸：DSH 正常流程是「带 `?token=` 访问 → 303 + Set-Cookie → 跳回 `/`」。
+ * 这条链在手机浏览器上很脆（跨站跳转 + `SameSite=Strict`：从别的 App 点进来时，
+ * 后续请求可能不带 cookie，于是又看到那句未授权提示）。自己铸就只要一跳：
+ * `/remote/<密钥>` → 302 到 `/` **同时把 cookie 种下去**，而且可以用 `SameSite=Lax`。
+ *
+ * 格式必须和 `client-connection` 完全一致，否则 `isAuthenticated` 验不过：
+ *   cookie 名 = `dsh-auth-` + base64url(sha256(authority))
+ *   值       = `v1.` + base64url(JSON) + `.` + base64url(HMAC-SHA256(secret, base64url(JSON)))
+ *   JSON     = { version: 1, authority, issuedAt, expiresAt }
+ * @returns 铸好的 cookie；拿不到签名密钥时返回 undefined（调用方回落到令牌跳转）。
+ */
+function mintSessionCookie(connection, authority, maxAgeMilliseconds) {
+  const secret = connection?.browserAuth?.secret
+  if (!Buffer.isBuffer(secret) || secret.length === 0) return undefined
+  const issuedAt = Date.now()
+  const expiresAt = issuedAt + maxAgeMilliseconds
+  if (!Number.isSafeInteger(expiresAt)) return undefined
+  const body = base64url(Buffer.from(JSON.stringify({ version: 1, authority, issuedAt, expiresAt }), 'utf8'))
+  const signature = base64url(createHmac('sha256', secret).update(body).digest())
+  return {
+    name: COOKIE_PREFIX + base64url(createHash('sha256').update(authority).digest()),
+    value: `v1.${body}.${signature}`,
+    maxAgeSeconds: Math.floor(maxAgeMilliseconds / 1000),
+    expiresAt,
+  }
+}
+
+/** 把铸好的 cookie 序列化成 `Set-Cookie` 头值。`SameSite=Lax` 是刻意的（见上）。 */
+function sessionCookieHeader(minted) {
+  return `${minted.name}=${minted.value}; Max-Age=${String(minted.maxAgeSeconds)}; Path=/; Expires=${new Date(minted.expiresAt).toUTCString()}; HttpOnly; SameSite=Lax`
+}
+
+/**
+ * 设置页那一行读的两个管理端点。
+ *
+ * 注册在 `connection.fetch` 上而**不是** `webServer.register`：`/api` 那条前缀路由
+ * 上挂着 DSH 自己的 Host/Origin fence 与浏览器 cookie 鉴权（`connection.admit`），
+ * 注册到 `connection.fetch` 等于白拿这套策略。反过来，用 `webServer.register` 建一条
+ * exact 的 `/api/...` 会**抢先命中** `match()` 的 exact 表，把整条 `/api` 前缀路由遮掉。
+ */
+const STATE_PATH = '/api/dsh-tailscale-remote/state'
+const ROTATE_PATH = '/api/dsh-tailscale-remote/rotate'
+
+/**
+ * 组装管理端点要返回的状态。
+ *
+ * 刻意**不抛**：「还在启动」「起不来」都是设置页要看的正常答案，不是错误响应。
+ * @param config - 归一化后的配置。
+ * @param runtime - 本次运行的活状态（见 `apply`）。
+ */
+function statePayload(config, runtime) {
+  const state = runtime.state
+  return {
+    ok: true,
+    enabled: config.enabled,
+    phase: runtime.phase,
+    error: runtime.error ?? null,
+    // 只有「已就绪」才谈得上换密钥：换密钥要写回状态文件并重建登录路由。
+    canRotate: config.enabled && config.loginRoute && runtime.phase === 'ready',
+    plainUrl: state?.plainUrl ?? null,
+    loginUrl: state?.loginUrl ?? null,
+    authority: state?.authority ?? null,
+    dnsName: state?.dnsName ?? null,
+    httpsPort: state?.httpsPort ?? config.httpsPort,
+    cookieMaxAgeDays: state?.cookieMaxAgeDays ?? config.cookieMaxAgeDays,
+    updatedAt: state?.updatedAt ?? null,
+  }
+}
+
+/**
+ * 注册（或换成）登录入口路由。
+ *
+ * 换密钥时**必须先撤掉旧的**：路由表按 `(kind, path)` 去重，路径变了不会报冲突，
+ * 于是旧链接会继续可用 —— 那会让「换完之后旧链接立刻失效」变成谎话。
+ * @param runtime - 活状态；`webScope` 缺席时什么都不做。
+ * @param connection - `connection` 服务（取签名密钥用）。
+ * @param config - 归一化后的配置。
+ * @param authority - `<dnsName>:<httpsPort>`。
+ * @param secret - 要用的密钥。
+ * @returns 新路径；装不上时返回 undefined。
+ */
+function installLoginRoute(runtime, connection, config, authority, secret) {
+  const webScope = runtime.webScope
+  if (webScope === undefined) return undefined
+  const webServer = webScope.get('webServer')
+  if (webServer === undefined) return undefined
+
+  runtime.login?.dispose?.()
+  runtime.login = undefined
+
+  const path = `/remote/${secret}`
+  const dispose = webScope.effect(
+    () =>
+      webServer.register({
+        kind: 'exact',
+        path,
+        handler: (req, res) => {
+          if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.writeHead(405)
+            res.end()
+            return
+          }
+          // 首选：自己铸 cookie，一跳到位（见 mintSessionCookie 的说明）。
+          const minted = mintSessionCookie(connection, authority, config.cookieMaxAgeDays * 86400000)
+          if (minted !== undefined) {
+            res.writeHead(302, {
+              location: `https://${authority}/`,
+              'set-cookie': sessionCookieHeader(minted),
+              'cache-control': 'no-store',
+              'referrer-policy': 'no-referrer',
+            })
+            res.end()
+            return
+          }
+          // 回落：拿不到签名密钥时走 DSH 自己的令牌链。
+          res.writeHead(302, {
+            location: runtime.handoffUrl ?? `https://${authority}/`,
+            'cache-control': 'no-store',
+            'referrer-policy': 'no-referrer',
+          })
+          res.end()
+        },
+      }),
+    'tailscale-remote: login route',
+  )
+
+  runtime.login = { secret, path, dispose }
+  return path
+}
+
+/**
+ * 换一个新密钥：装上新路由 → 写回状态文件 → 更新活状态。
+ *
+ * 已经登录过的手机**不受影响**：DSH 的会话 cookie 由 `browserAuth.secret` 签名，
+ * 和这个登录密钥无关，换密钥只让「拿旧链接重新登录」失效。
+ * @param scope - 带 `connection` 的上下文。
+ * @param config - 归一化后的配置。
+ * @param runtime - 活状态。
+ * @param deps - 依赖注入（测试替换用）。
+ * @returns `{ loginUrl, loginPath, updatedAt }`。
+ * @throws 未就绪 / 登录入口已关闭 / webServer 不可用时。
+ */
+async function rotateLoginSecret(scope, config, runtime, deps = REAL_DEPS) {
+  if (!config.loginRoute) throw new Error('登录入口已关闭（loginRoute=false），没有可更换的密钥')
+  const state = runtime.state
+  if (state === undefined) throw new Error('远程访问还没就绪，稍后再试')
+
+  const connection = scope.get('connection', false)
+  const secret = randomBytes(24).toString('base64url')
+  const loginPath = installLoginRoute(runtime, connection, config, state.authority, secret)
+  if (loginPath === undefined) throw new Error('webServer 不可用，换不了密钥')
+
+  const loginUrl = `https://${state.authority}${loginPath}`
+  let handoffUrl = state.plainUrl
+  try {
+    handoffUrl = connection?.authenticatedUrl?.(state.plainUrl) ?? state.plainUrl
+  } catch {
+    handoffUrl = state.plainUrl
+  }
+
+  const next = {
+    ...state,
+    url: handoffUrl,
+    loginUrl,
+    loginPath,
+    loginSecret: secret,
+    updatedAt: new Date().toISOString(),
+  }
+  await deps.persistState(scope, next)
+  runtime.state = next
+  runtime.handoffUrl = handoffUrl
+  if (runtime.undo !== undefined) runtime.undo.loginPath = loginPath
+  return { loginUrl, loginPath, updatedAt: next.updatedAt }
+}
+
+/**
+ * 注册管理端点。
+ *
+ * 即便 `enabled=false` 也注册：设置页那一行要能回答「为什么没起来」，
+ * 而不是只能看到一个 404。
+ * @param scope - 带 `connection` 的上下文。
+ * @param config - 归一化后的配置。
+ * @param runtime - 活状态。
+ */
+function registerAdminRoutes(scope, config, runtime) {
+  const connection = scope.get('connection', false)
+  const routes = connection?.fetch
+  if (routes === undefined) return
+
+  const json = (payload, status = 200) =>
+    new Response(JSON.stringify(payload), {
+      status,
+      headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+    })
+
+  // 每条路由都显式挂在自己的 effect 上。
+  //
+  // `connection.fetch.register` 内部**确实**会用「读服务的那个 ctx」调 `owner.effect`，
+  // 但那个 ctx 来自 cordis 的服务代理在调用点绑定 —— 与其依赖这条链路，不如自己
+  // 明确声明生命周期：`scope.effect(() => routes.register(...))` 拿返回的 disposer
+  // 作为清理函数，插件卸载时路由一定跟着走，不多不少。
+  scope.effect(
+    () =>
+      routes.register({
+        path: STATE_PATH,
+        methods: ['GET'],
+        requestBody: 'buffered',
+        fetch: () => Promise.resolve(json(statePayload(config, runtime))),
+      }),
+    'tailscale-remote: state route',
+  )
+
+  scope.effect(
+    () =>
+      routes.register({
+        path: ROTATE_PATH,
+        methods: ['POST'],
+        requestBody: 'buffered',
+        fetch: async () => {
+          try {
+            return json({ ok: true, ...(await rotateLoginSecret(scope, config, runtime)) })
+          } catch (error) {
+            return json({ ok: false, error: String(error?.message ?? error) }, 409)
+          }
+        },
+      }),
+    'tailscale-remote: rotate route',
+  )
+}
+
+/**
+ * 本次运行的活状态。
+ *
+ * 设置页那一行要能回答「现在到哪一步了」，而 `setup` 的返回值只够写日志；
+ * 这里把阶段、错误、状态快照和已装的登录路由都挂在一个对象上，`apply` 建一次、
+ * `setup` 往里写、管理端点读。
+ * @param undo - 本次运行的回滚清单（换密钥时要更新它的 loginPath）。
+ */
+function freshRuntime(undo) {
+  return {
+    phase: 'starting',
+    error: undefined,
+    /** 最近一次写盘的状态快照（见 `setup` 末尾）。 */
+    state: undefined,
+    /** 登录入口落地的那个 webServer 作用域；换密钥时复用它。 */
+    webScope: undefined,
+    /** 当前登录路由 `{ secret, path, dispose }`；换密钥时先撤掉它。 */
+    login: undefined,
+    /** 回落跳转用的带令牌地址。 */
+    handoffUrl: undefined,
+    undo,
+  }
+}
+
+/**
+ * 插件入口。
+ * @param {import('@deepseek-ai/cordis').Context} ctx - 插件上下文。
+ * @param {unknown} rawConfig - 该行声明的 config。
+ */
+export function apply(ctx, rawConfig) {
+  const config = normalizeConfig(rawConfig)
+
+  // connection 是可选依赖：服务晚到也会触发，永不出现则保持静默。
+  // 服务只从 scope 参数上取（inject 新建的 fiber 的 store 里才有它）。
+  ctx.inject(['connection'], (scope) => {
+    if (scope.get('connection') === undefined) return
+
+    /** 本次运行真正做过的副作用，退出时按这个清单回滚。 */
+    const undo = {
+      /** 我们 push 进 trustedHosts 的那一项。 */
+      trustedHost: undefined,
+      /** 7259 路由是不是我们建的（本来就在就留着，不动）。 */
+      createdRoute: false,
+      /** tailscale 是不是我们拉起来的（本来 Running 就不 down）。 */
+      startedTailscale: false,
+      /** 启动阶段探测到的可执行文件，退出时直接复用——关停预算里再探一次就超时了。 */
+      binary: undefined,
+      /** 注册的登录入口路径（fiber 拆除时路由会跟着注销，这里只作记录）。 */
+      loginPath: undefined,
+      disposed: false,
+    }
+    const runtime = freshRuntime(undo)
+
+    // 管理端点**即便 enabled=false 也注册**：设置页那一行要能回答「为什么没起来」，
+    // 而不是只能看到一个 404。客户端半边是独立声明的，禁用时照样会加载并渲染这一行。
+    if (!config.enabled) {
+      runtime.phase = 'disabled'
+      ctx.logger.info('tailscale-remote: enabled=false，只提供设置页状态，不动作')
+      registerAdminRoutes(scope, config, runtime)
+      return
+    }
+
+    registerAdminRoutes(scope, config, runtime)
+
+    // 退出清理挂在这里：这是唯一可靠的关停挂点，且 disposer 绝不能 reject。
+    scope.effect(() => async () => {
+      if (undo.disposed) return
+      undo.disposed = true
+      if (!config.teardownOnExit) return
+      // 关停预算很紧：全部吞掉异常，绝不让 disposer reject（会变成 AggregateError）。
+      await Promise.allSettled([teardown(scope, config, undo)])
+    }, 'tailscale-remote: teardown')
+
+    // 启动流程异步跑，不阻塞 Loader 装配。
+    setup(scope, config, undo, REAL_DEPS, runtime).catch((error) => {
+      runtime.phase = 'error'
+      runtime.error = String(error?.message ?? error)
+      scope.logger.warn(`tailscale-remote: 启动失败：${runtime.error}`)
+    })
+  })
+}
+
+/** 真实依赖；测试通过 `deps` 参数替换它们，生产路径永远用这一份。 */
+const REAL_DEPS = {
+  run,
+  resolveBinary,
+  readStatus,
+  readServeStatus,
+  waitForPort,
+  persistState,
+  loadState,
+  ensureLoginSecret,
+  announce,
+  launchGui,
+  resolveGui,
+}
+
+/** 启动：拉起 tailscale → 建 serve 路由 → 信任该 authority → 打印手机可用的链接。 */
+async function setup(scope, config, undo, deps = REAL_DEPS, runtime = freshRuntime(undo)) {
+  const logger = scope.logger
+  runtime.undo = undo
+  runtime.phase = 'starting'
+  runtime.error = undefined
+  const binary = await deps.resolveBinary(scope, config.binaryPath)
+  if (binary === undefined) {
+    runtime.phase = 'unavailable'
+    runtime.error = '找不到 tailscale 可执行文件'
+    logger.warn('tailscale-remote: 找不到 tailscale 可执行文件；请安装 Tailscale 或用 config.binaryPath 指定路径')
+    return
+  }
+  // 记下来给退出阶段复用：关停时只有几秒预算，不能再跑一轮 `tailscale version` 探测。
+  undo.binary = binary
+
+  let status = await deps.readStatus(binary)
+  const wasRunning = status?.BackendState === 'Running'
+
+  // 关键：必须验证 backend 真的 Running，不能只信 `tailscale up` 的退出码
+  // （Windows 上客户端被完全退出时，up 会 exit 0 但什么都不做）。
+  const running = await ensureRunning(binary, config, deps, logger, undo)
+  if (!running) {
+    runtime.phase = 'unavailable'
+    runtime.error = 'tailscale 没在运行'
+    return
+  }
+  if (!wasRunning) status = await deps.readStatus(binary)
+
+  const dnsName = dnsNameOf(status)
+  if (dnsName === undefined) {
+    runtime.phase = 'unavailable'
+    runtime.error = '读不到 tailnet DNS 名称'
+    logger.warn('tailscale-remote: 读不到 tailnet DNS 名称，跳过 Serve 配置')
+    return
+  }
+
+  // DSH 自己的 Web 端口从服务上读，绝不写死。
+  const port = await deps.waitForPort(scope)
+  if (port === undefined) {
+    runtime.phase = 'unavailable'
+    runtime.error = '等不到 DSH Web 端口'
+    logger.warn('tailscale-remote: 等不到 DSH Web 端口，跳过 Serve 配置')
+    return
+  }
+
+  const target = `http://127.0.0.1:${String(port)}`
+  const authority = `${dnsName}:${String(config.httpsPort)}`
+
+  if (config.serveOnStart) {
+    const serveStatus = await deps.readServeStatus(binary)
+    const state = classifyServe(serveStatus, config.httpsPort, target)
+    if (state.kind === 'conflict') {
+      runtime.phase = 'error'
+      runtime.error = `${String(config.httpsPort)} 端口上有冲突的 Serve 配置（${state.reason}）`
+      logger.warn(`tailscale-remote: ${String(config.httpsPort)} 端口上有冲突的 Serve 配置（${state.reason}），不覆盖`)
+      return
+    }
+    if (state.kind === 'exact') {
+      // 已经有一条精确指向本实例 DSH 端口的路由。它只可能是上一次运行留下的
+      // （正常退出会撤掉，所以这种情况基本等于「上次 DSH 是崩溃/强杀结束的」）。
+      // 既然目标就是我们自己，就把它**认领下来**，退出时一并撤掉 —— 否则用户的
+      // 「关 DSH 就关掉」在崩溃恢复后会永远失效，路由会一直留在那儿。
+      logger.info(`tailscale-remote: ${authority} 已在代理 ${target}，接管它（退出时会撤掉）`)
+      undo.createdRoute = true
+    } else {
+      if (state.kind === 'stale') {
+        logger.info(`tailscale-remote: 接管陈旧路由 ${state.authority}（原代理 ${state.previousProxy}）`)
+      }
+      const serve = await deps.run(binary, ['serve', '--bg', `--https=${String(config.httpsPort)}`, target], SETUP_TIMEOUT_MS)
+      if (!serve.ok) {
+        const detail = (serve.stderr || serve.stdout).trim().slice(0, 300)
+        runtime.phase = 'error'
+        runtime.error = detail === '' ? '配置 Serve 失败' : detail
+        logger.warn(
+          `tailscale-remote: 配置 Serve 失败: ${detail}；` +
+            '若提示 HTTPS 证书，请先在 Tailscale 管理台为该 tailnet 启用 HTTPS 证书',
+        )
+        return
+      }
+      undo.createdRoute = true
+    }
+  }
+
+  // 关键一步：让 DSH 的 /api fence 接受这个 authority，否则手机上前端能开、RPC 全 403。
+  if (config.trustedHosts) {
+    const trusted = connectionTrustedHosts(scope)
+    if (trusted === undefined) {
+      logger.warn('tailscale-remote: 读不到 connection.trustedHosts，远程 RPC 会被 403 拒绝')
+    } else if (!trusted.includes(authority)) {
+      trusted.push(authority)
+      undo.trustedHost = authority
+      logger.info(`tailscale-remote: 已把 ${authority} 加入 /api 信任列表`)
+    }
+  }
+
+  const plainUrl = `https://${authority}/`
+  const connection = scope.get('connection')
+
+  // 把登录 cookie 的有效期拉长。DSH 默认 30 天，对「手机随时连」太短。
+  // `connection.browserAuth.maxAgeMilliseconds` 是**活的**字段：authorizeIndex 种 cookie 时
+  // 用它算 expiresAt / Max-Age，isAuthenticated 校验时也用它，所以在这里改立刻就生效。
+  if (config.cookieMaxAgeDays > 0) {
+    const maxAgeMilliseconds = config.cookieMaxAgeDays * 86400000
+    const auth = connection?.browserAuth
+    if (auth !== undefined && Number.isSafeInteger(Date.now() + maxAgeMilliseconds)) {
+      auth.maxAgeMilliseconds = maxAgeMilliseconds
+      logger.info(`tailscale-remote: 登录 cookie 有效期设为 ${String(config.cookieMaxAgeDays)} 天`)
+    } else {
+      logger.warn('tailscale-remote: 读不到 connection.browserAuth，cookie 有效期沿用 DSH 默认值')
+    }
+  }
+
+  let handoffUrl = plainUrl
+  try {
+    // authenticatedUrl 会把本进程的启动令牌加到链接上；首次打开会种下 cookie。
+    handoffUrl = connection?.authenticatedUrl?.(plainUrl) ?? plainUrl
+  } catch {
+    handoffUrl = plainUrl
+  }
+  runtime.handoffUrl = handoffUrl
+
+  // 稳定的登录入口：/remote/<持久密钥> → 302 到带令牌的地址。
+  // 令牌每次都变、用户没法存书签；这条路径的密钥写在状态文件里，**跨重启不变**，
+  // 所以手机上存一次就够了。密钥同时充当访问门槛（不知道密钥的人拿不到会话）。
+  let loginUrl = plainUrl
+  let loginPath
+  if (config.loginRoute) {
+    const secret = await deps.ensureLoginSecret(scope, config, deps)
+    // 路径在这里**同步**算出来：`scope.inject` 的服务晚到时回调是异步的，
+    // 若等回调再算，webServer 迟到就会让状态文件里丢掉 loginUrl。
+    loginPath = `/remote/${secret}`
+    loginUrl = `https://${authority}${loginPath}`
+    undo.loginPath = loginPath
+    // 登录入口的跳转目标就是上面这个带令牌的地址；注册在 DSH 自己的 webserver 上
+    // （所以不需要第二个端口、也不需要额外的 tailscale serve 路由）。
+    // 嵌套 inject：webServer 缺席时只丢登录入口，tailscale / 信任项照常工作。
+    scope.inject(['webServer'], (webScope) => {
+      runtime.webScope = webScope
+      installLoginRoute(runtime, connection, config, authority, secret)
+    })
+  }
+
+  const loginSecret = loginPath === undefined ? undefined : loginPath.slice('/remote/'.length)
+  const snapshot = {
+    url: handoffUrl,
+    loginUrl,
+    loginPath,
+    loginSecret,
+    plainUrl,
+    authority,
+    dnsName,
+    httpsPort: config.httpsPort,
+    target,
+    cookieMaxAgeDays: config.cookieMaxAgeDays,
+    updatedAt: new Date().toISOString(),
+    stateFile: config.stateFile,
+  }
+  await deps.persistState(scope, snapshot)
+  runtime.state = snapshot
+  runtime.phase = 'ready'
+  runtime.error = undefined
+
+  logger.info(`tailscale-remote: 手机可用地址 ${plainUrl}`)
+  if (loginUrl !== plainUrl) {
+    logger.info(`tailscale-remote: 手机登录入口（存一次书签即可，跨重启不变）${loginUrl}`)
+  }
+  logger.info(`tailscale-remote: 一次性令牌链接（每次重启都会变）${handoffUrl}`)
+  // 也打到 stdout：桌面版的日志面板里能直接看到。
+  deps.announce?.(plainUrl, loginUrl, handoffUrl)
+}
+
+/** 默认的 announce：写 stdout，桌面版日志面板可见。 */
+function announce(plainUrl, loginUrl, handoffUrl) {
+  console.log(`dsh tailscale-remote: ${plainUrl}`)
+  if (loginUrl !== plainUrl) console.log(`dsh tailscale-remote (手机登录入口): ${loginUrl}`)
+  console.log(`dsh tailscale-remote (一次性令牌): ${handoffUrl}`)
+}
+
+/**
+ * 等 `webServer.port` 就绪。
+ * WebServer 在构造函数里就 provide 了服务，但端口要等 `[Service.init]` 的异步 listen
+ * 完成才赋值；插件激活时机与它没有顺序保证，所以这里轮询而不是一次性读。
+ */
+async function waitForPort(scope, timeoutMs = 8000) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    const port = scope.get('webServer')?.port
+    if (Number.isInteger(port) && port > 0) return port
+    if (Date.now() >= deadline) return undefined
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+}
+
+/** 从 connection 服务上取那个可变的 trustedHosts 数组。 */
+function connectionTrustedHosts(scope, strict = true) {
+  const connection = scope.get('connection', strict)
+  const trusted = connection?.trustedHosts
+  return Array.isArray(trusted) ? trusted : undefined
+}
+
+/** 退出：按 undo 清单回滚。幂等、并发安全、绝不抛。 */
+async function teardown(scope, config, undo, deps = REAL_DEPS) {
+  const logger = scope.logger
+  try {
+    if (undo.trustedHost !== undefined) {
+      // strict=false：关停时 connection 的 fiber 可能已经不再 active，但仍要清掉那一项。
+      const trusted = connectionTrustedHosts(scope, false)
+      if (trusted !== undefined) {
+        const at = trusted.indexOf(undo.trustedHost)
+        if (at !== -1) trusted.splice(at, 1)
+      }
+      undo.trustedHost = undefined
+    }
+  } catch {
+    /* 上下文可能已经在拆除中 */
+  }
+
+  if (!undo.createdRoute && !undo.startedTailscale) return
+
+  const binary = undo.binary ?? (await deps.resolveBinary(scope, config.binaryPath))
+  if (binary === undefined) return
+
+  // 两条清理各自独立：Serve 路由没建起来不代表 tailscale 不是我们拉起的。
+  if (undo.createdRoute) {
+    undo.createdRoute = false
+    const off = await deps.run(binary, ['serve', `--https=${String(config.httpsPort)}`, 'off'], TEARDOWN_TIMEOUT_MS)
+    if (off.ok) logger.info(`tailscale-remote: 已撤销 ${String(config.httpsPort)} 端口上的 Serve 路由`)
+    else logger.warn(`tailscale-remote: 撤销 Serve 路由失败: ${(off.stderr || off.stdout).trim().slice(0, 200)}`)
+  }
+
+  if (undo.startedTailscale) {
+    undo.startedTailscale = false
+    const down = await deps.run(binary, ['down'], TEARDOWN_TIMEOUT_MS)
+    if (down.ok) logger.info('tailscale-remote: 已断开 tailscale（本次由 DSH 拉起）')
+    else logger.warn(`tailscale-remote: tailscale down 失败: ${(down.stderr || down.stdout).trim().slice(0, 200)}`)
+  }
+}
+
+/**
+ * 纯函数与底层 runner 的测试入口。
+ * 生产路径不读这个对象；它只为单元测试而存在（决定"要不要覆盖已有 Serve 配置"的
+ * `classifyServe` 是这里风险最高的一段逻辑，必须有牙齿地测）。
+ */
+export const internals = {
+  normalizeConfig,
+  classifyServe,
+  dnsNameOf,
+  resolveDshHome,
+  resolveGui,
+  run,
+  resolveBinary,
+  readServeStatus,
+  readStatus,
+  waitForPort,
+  waitForRunning,
+  ensureRunning,
+  ensureLoginSecret,
+  mintSessionCookie,
+  sessionCookieHeader,
+  statePayload,
+  installLoginRoute,
+  rotateLoginSecret,
+  registerAdminRoutes,
+  freshRuntime,
+  setup,
+  teardown,
+  REAL_DEPS,
+  STATE_PATH,
+  ROTATE_PATH,
+}