dsh-tailscale-remote 0.1.0 → 0.3.0

package/README.md

@@ -1,16 +1,19 @@
 # dsh-tailscale-remote
 
 打开 DSH 就把本机 Web GUI 通过 **Tailscale Serve** 暴露到你的 tailnet 上，手机在任何网络下
-打开一个网址就能用；DSH 退出时把这条路由撤掉。
+打开一个网址就能用；DSH 退出时把这条路由撤掉。手机链接直接显示在
+**「设置 → 通用 → 手机连接」**里，点一下就能复制。
 
 > 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）用的插件。
 > 只需要「随时随地用手机连上自己电脑上的 DSH」这一件事，不引入任何第三方中转。
 
 ## 先看这个：手机怎么进
 
-DSH 的 Web GUI 要求一次**登录令牌**，没令牌只显示一句
-`dsh web authentication required; ...`。DSH Desktop 又**从不打印**那行链接，令牌还每次重启都换 ——
-所以插件给你一条**存一次就永久用**的入口：
+**最省事的办法：DSH 里打开「设置 → 通用」，往下找到「手机连接」那一行，里面就有链接，
+点一下「复制」，发到手机上打开一次即可。** 那一行还能随时「更换密钥」——万一链接泄露，
+换了之后旧链接和所有旧登录一起失效。
+
+不想开 DSH 界面时，读状态文件也一样（字段是 `loginUrl`）：
 
 ```sh
 # 装好并重启 DSH 后，执行（Windows 用 PowerShell 见下）
@@ -32,7 +35,11 @@ Windows PowerShell 读法：
 Get-Content "$env:USERPROFILE\.dsh\tailscale-remote.json"
 ```
 
-就这么两步：**读 `loginUrl` → 手机打开一次并存书签**。下面都是细节。
+就这么两步：**拿到 `loginUrl` → 手机打开一次并存书签**。下面都是细节。
+
+> DSH 的 Web GUI 要求一次**登录令牌**，没令牌只显示一句
+> `dsh web authentication required; ...`。DSH Desktop 又**从不打印**那行链接，令牌还每次重启都换 ——
+> 所以插件给你一条**存一次就永久用**的入口。
 
 ## 安装
 
@@ -83,9 +90,28 @@ dsh web authentication required; reopen the URL printed by dsh web.
 ```
 
 麻烦的地方在于：**DSH Desktop 从不打印这行链接**（它走 IPC，不走 `dsh web`），而令牌又是
-**进程级**的、每次重启都换。所以本插件做了两件事，让你**只需要拿一次链接**：
+**进程级**的、每次重启都换。所以本插件给你三个拿链接的地方，任选其一。
+
+### ① 设置页里的「手机连接」行（推荐）
+
+**设置 → 通用**，滚到下面有「手机连接」这一行：
 
-### ① 稳定登录入口（推荐，存一次书签就够）
+- 里面是**手机登录链接**，一个只读输入框 + 「复制」按钮，点一下就能发到手机上。
+- 旁边有「更换密钥」：点一下会先让你确认，确认后**旧密钥与所有旧登录一起失效**。
+  - **换的到底是什么**：登录链接（`/remote/<密钥>`）只负责**换取**一张会话 cookie。
+    密钥泄露后，如果对方已经用它登录过，他手里那张 cookie 是另一把签名密钥签的、
+    有效期 10 年 —— 只换登录密钥完全不影响它。所以这里的「更换密钥」会**同时**换掉
+    登录密钥**和**会话签名密钥，让泄露的密钥真正失效。
+  - **代价**：所有设备（包括你自己的手机）都会被登出，需要用新链接重新登录一次。
+    **点按钮的这台设备会被自动补发一张新 cookie、不掉线**，所以在电脑上操作最顺手。
+  - 想只换链接、不踢设备？设 `revokeSessionsOnRotate: false`（此时泄露的旧 cookie
+    仍然有效，只适合「我确定没人用过那条链接」的情况）。
+- 还没就绪时会直接告诉你卡在哪一步（比如「Tailscale 没在运行」），而不是给你一个空框。
+
+> 这一行只在你**打开设置页**时才请求一次状态（外加窗口重新获得焦点时刷新一次），
+> 不轮询、不挂定时器。它注册在 DSH 自己的 `/api` 上，所以**只有已登录的浏览器**能读。
+
+### ② 稳定登录入口（存一次书签就够）
 
 插件会在 DSH 自己的 webserver 上注册一条路由：
 
@@ -100,7 +126,7 @@ https://<你的机器>.<tailnet>.ts.net:7259/remote/<持久密钥>
 > 密钥本身就是访问门槛：不知道它的人拿不到会话（和 DSH 自己的令牌同一级别）。
 > 不需要的话可以设 `loginRoute: false` 关掉。
 
-### ② 状态文件（永远可以查到）
+### ③ 状态文件（永远可以查到）
 
 任何一次启动后，下面这个文件里都有**当前**可用的链接：
 
@@ -147,7 +173,8 @@ cookie 种下后，直接访问干净地址 `https://<机器>.<tailnet>.ts.net:7
 | `serveOnStart` | `true` | 是否建立 Serve 路由。 |
 | `teardownOnExit` | `true` | 退出时是否回滚。 |
 | `trustedHosts` | `true` | 是否把该 authority 加进 `/api` 信任列表。 |
-| `loginRoute` | `true` | 是否注册 `/remote/<持久密钥>` 这个稳定登录入口。 |
+| `loginRoute` | `true` | 是否注册 `/remote/<持久密钥>` 这个稳定登录入口（设置页那一行的「更换密钥」也依赖它）。 |
+| `revokeSessionsOnRotate` | `true` | 换密钥时是否**同时吊销所有已登录的会话**。默认开：密钥泄露时对方可能已用旧密钥换到一张 10 年 cookie，只换登录密钥拦不住他。关掉则只换链接、所有设备继续登录。 |
 | `cookieMaxAgeDays` | `3650` | 登录 cookie 有效期（天）。`0` = 不插手 DSH 的 30 天默认值。 |
 | `binaryPath` | 自动探测 | `tailscale` CLI 可执行文件路径。 |
 | `guiPath` | 自动探测 | Tailscale **桌面客户端**路径（Windows 默认 `tailscale-ipn.exe`）。 |
@@ -179,12 +206,83 @@ DSH 把 cookie 有效期上限写死在 `connection` 的 `cookieMaxAgeDays` 里
 如果连客户端都拉不起来（例如需要交互式登录），插件会留下明确提示让你手动打开 Tailscale，
 并且**不会**谎报成功去配一条连不上的路由。
 
+## 发布（维护者）
+
+包名 `dsh-tailscale-remote` 已发布到 npm。`package.json` 里写了 `publishConfig`
+（`access: public` + `registry: https://registry.npmjs.org/`），所以**直接 `npm publish`
+不带任何参数**就会发到正确的地方——即使本机 `~/.npmrc` 指向的是镜像站。
+
+后续版本**自动发布**：推送到 `main` 时 `.github/workflows/publish.yml` 会先跑测试再
+`npm publish`——但**只有 `package.json` 里的 `version` 是 registry 上还没有的版本时才发**。
+所以发版流程就是两步：
+
+1. 改 `package.json` 的 `version`。
+2. 推送到 `main`。
+
+这次运行要么发出这个版本，要么报告「该版本已在线上」并以成功结束。
+**没改版本号的推送是 no-op，不是失败**——所以每个要发出去的改动都必须自己带一次版本号
+变更；只改文档的提交同样会触发工作流，同样 no-op。
+
+认证用 npm **Trusted Publishing（OIDC）**：GitHub 给这个 job 签一个短时 token，npm 拿它换
+一个只对这一个包有效的发布 token。**仓库里没有任何 `NPM_TOKEN` secret。** 工作流刻意
+**不用** `actions/setup-node` 的 `registry-url` 输入——它会往 `~/.npmrc` 写
+`//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`，而该变量没定义时这个占位符会
+原样留下、被 npm 当作 token 发出去。registry 交给 `publishConfig` 就够了。
+
+<details>
+<summary>一次性配置：绑定 Trusted Publisher</summary>
+
+Trusted Publisher **只能绑到 registry 上已存在的包**，所以**首次发布是手工做的**
+（在检出目录里跑了一次 `npm publish`），从第二个版本起才轮到工作流接管。在 npmjs.com 上：
+包 → Settings → Trusted Publisher → GitHub Actions，填
+
+| 字段 | 值 |
+|---|---|
+| Repository | `Ckarefulon/dsh-tailscale-remote` |
+| Workflow filename | `publish.yml` |
+| Environment | *留空* |
+
+文件名必须**逐字一致**——npm 把授权绑在它上面，写错会表现为发布报 `ENEEDAUTH`。
+
+</details>
+
 ## 安全边界
 
 这条路由**只对你的 tailnet 可见**（Tailscale Serve 的默认范围，不是 Funnel），也就是说
 只有登录到你这个 tailnet 的设备能连上。DSH 自己的浏览器鉴权（30 天签名 cookie）仍然
 生效，两层是叠加的。
 
+设置页那一行背后的两个端点注册在 DSH 自己的 `/api` 前缀路由上
+（`connection.fetch`），因此**直接白拿 DSH 的 Host/Origin fence 与浏览器 cookie 鉴权**：
+未登录的请求在到达插件之前就被 401 挡掉了。它们也刻意**不用**
+`webServer.register({ kind: 'exact', path: '/api/...' })` —— `webserver` 的 `match()`
+先查 exact 表，那样会**抢先命中**并遮掉整条 `/api` 路由，把 fence 和鉴权一起绕过去。
+
+| 端点 | 作用 |
+| --- | --- |
+| `GET /api/dsh-tailscale-remote/state` | 当前阶段、手机链接、能否换密钥、换密钥会不会踢设备。不缓存。 |
+| `POST /api/dsh-tailscale-remote/rotate` | 换一把新登录密钥，并（默认）吊销所有已登录的会话；给发起方补发一张新 cookie。 |
+
+### 「更换密钥」到底吊销了什么
+
+DSH 的浏览器鉴权有两把独立的密钥，别把它们混为一谈：
+
+| | 作用 | 换了它会怎样 |
+| --- | --- | --- |
+| **登录密钥**（本插件的 `/remote/<密钥>`） | 换取会话 cookie 的入口 | 旧链接立刻 404 |
+| **会话签名密钥**（`connection.browserAuth.secret`，存在 credentials 的 `client-connection/browser-session` 记录里） | 给会话 cookie 签名 | 所有已发出的 cookie 立刻验不过 |
+
+**只换登录密钥是不够的**：泄露的链接如果已经被用过，对方手里那张 cookie 由第二把密钥
+签名、有效期 10 年，换第一把对它毫无影响。所以默认两把一起换（`revokeSessionsOnRotate`）。
+
+实现上两处都要改，缺一不可：credentials 记录（**持久**，否则 DSH 一重启就把旧密钥读回来、
+旧 cookie 复活）和活着的 `browserAuth.secret`（**立即生效**，它按引用逐字比较签名）。
+写入后会**回读确认**：写错记录键或被只读来源遮蔽时 `modifyRecord` 会「成功返回但记录没变」，
+不校验的话就是「报成功、实则没换」。
+
+想彻底踢掉已登录设备也可以直接去改 DSH 自己的凭据 —— 那等于把第二把密钥换掉，效果一样，
+但会一并影响其它依赖它的东西；用本插件这一行更精确，而且会顺手把新链接给你。
+
 插件**不会覆盖** 7259 上已有的、指向别处的 Serve 配置：检测到冲突就只记日志、不动手。
 唯一会接管的情况是发现一条指向**另一个回环端口**的陈旧路由（通常是上次 DSH 换了端口
 留下的）。

package/client/client.js

@@ -0,0 +1,465 @@
+// dsh-tailscale-remote 的浏览器半边：在「设置 → 通用」里加一行「手机连接」，
+// 显示手机可用的登录链接，并允许更换密钥。
+//
+// 手写，没有构建步骤：元素一律用 React.createElement 构造，样式全部内联，
+// 颜色走 DSH 主题变量（真名前缀是 --dsw-alias-，深浅色自动跟随）并各带一个
+// 浅色兜底值，变量缺失时界面仍然可读。
+//
+// 数据来自同源的两个 /api 路由（host 侧 index.js 注册在 connection.fetch 上，
+// 因此白拿 DSH 自己的 Host/Origin fence 与 cookie 鉴权）：
+//   GET  /api/dsh-tailscale-remote/state   → { ok, phase, error, plainUrl, loginUrl, ... }
+//   POST /api/dsh-tailscale-remote/rotate  → { ok, loginUrl } | { ok:false, error }
+// 注意失败时状态码不是 200 但响应体仍是 JSON，所以先解析 body 再看 body.ok，
+// 不拿状态码覆盖原文。
+//
+// 这一行**不轮询、不挂后台定时器**：只在挂载时取一次，另有窗口重新获得焦点时
+// 刷新一次。设置页关掉就什么都不剩。
+
+window.__ModuleLoader__.load({
+	id: 'dsh-tailscale-remote',
+	factory: (require) => {
+		// loader 只传 require、不传 module，所以每个 bundle 自带这一对，
+		// 和宿主自己的 bundle 写法一致。
+		const module = { exports: {} }
+		const exports = module.exports
+		Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+		const React = require('react')
+		const h = React.createElement
+		const useState = React.useState
+		const useEffect = React.useEffect
+		const useCallback = React.useCallback
+		const useRef = React.useRef
+
+		/** 这一行的插槽 id；同时是设置页里这一行的定位键。 */
+		const ROW_ID = 'dsh-tailscale-remote'
+
+		const STATE_PATH = '/api/dsh-tailscale-remote/state'
+		const ROTATE_PATH = '/api/dsh-tailscale-remote/rotate'
+
+		/**
+		 * 行内字典。
+		 *
+		 * 宿主有 locale 服务时优先用它（见 pickLanguage），这里这份是兜底：
+		 * 拿不到 locale 服务时（浏览器 harness、精简组合）界面仍然是中文/英文，
+		 * 而不是一堆字面量 key。
+		 */
+		const ZH = {
+			title: '手机连接',
+			description: '开 DSH 时把网页发布到你的 Tailscale 网络（tailnet），手机在任何网络下打开下面的链接就能连上；关掉 DSH 会自动撤掉这条路由。',
+			loading: '正在读取…',
+			urlLabel: '手机登录链接',
+			plainLabel: '直连地址',
+			copy: '复制',
+			copied: '已复制',
+			copyFailed: '复制失败，请手动选中输入框里的内容复制',
+			rotate: '更换密钥',
+			rotateConfirm: '确认更换',
+			rotateCancel: '取消',
+			rotateWarningRevoke: '换完之后旧链接立刻失效，所有已登录的设备都会退出（包括你的手机），需要用新链接重新登录一次。这台设备会被自动保留登录状态。',
+			rotateWarningLinkOnly: '换完之后旧链接立刻失效，需要把新链接重新存一次书签。已经登录过的设备不受影响。',
+			rotateDoneRevoke: '已更换。旧密钥与所有旧登录都已失效，请把新链接重新存一次书签。',
+			rotateDoneLinkOnly: '已更换。请重新保存下面的链接。',
+			rotateFailed: '更换失败',
+			noLogin: '登录入口已关闭（loginRoute=false），下面的直连地址需要先在本机用一次性令牌登录。',
+			keepBookmark: '存一次书签即可，跨重启不变。',
+			cookieHint: (days) => `登录状态有效期 ${days} 天。`,
+			retry: '重试',
+			phaseStarting: '还在启动中（拉起 Tailscale / 建立 Serve 路由）。',
+			phaseUnavailable: 'Tailscale 没在运行，远程访问暂时不可用。',
+			phaseError: '远程访问没能建起来。',
+		}
+
+		const EN = {
+			title: 'Phone access',
+			description: 'While DSH runs, its Web GUI is published to your Tailscale network (tailnet), so a phone anywhere can open the link below. Quitting DSH removes the route.',
+			loading: 'Loading…',
+			urlLabel: 'Phone login link',
+			plainLabel: 'Direct address',
+			copy: 'Copy',
+			copied: 'Copied',
+			copyFailed: 'Copy failed — select the field and copy manually',
+			rotate: 'Change key',
+			rotateConfirm: 'Confirm change',
+			rotateCancel: 'Cancel',
+			rotateWarningRevoke: 'The old link stops working immediately and every signed-in device is signed out, including your phone — sign in again with the new link. This device stays signed in.',
+			rotateWarningLinkOnly: 'The old link stops working immediately; bookmark the new one. Devices already signed in are unaffected.',
+			rotateDoneRevoke: 'Changed. The old key and every old session are now invalid; save the new link again.',
+			rotateDoneLinkOnly: 'Changed. Save the link below again.',
+			rotateFailed: 'Change failed',
+			noLogin: 'The login entry is off (loginRoute=false); the direct address needs a one-time token login from this machine first.',
+			keepBookmark: 'Bookmark it once — it survives restarts.',
+			cookieHint: (days) => `Sign-in stays valid for ${days} days.`,
+			retry: 'Retry',
+			phaseStarting: 'Still starting up (bringing up Tailscale / the Serve route).',
+			phaseUnavailable: 'Tailscale is not running, so remote access is unavailable.',
+			phaseError: 'Remote access could not be established.',
+		}
+
+		/**
+		 * 当前该说中文还是英文。
+		 *
+		 * 只读 `ctx.get('locale')`（可选服务，**不写进 inject**：写进去会在
+		 * locale 缺席时把整个包 park 掉）。拿不到就退回浏览器语言。
+		 * @param ctx - 客户端根上下文。
+		 * @returns 'zh' 或 'en'。
+		 */
+		function pickLanguage(ctx) {
+			let active
+			try {
+				active = ctx.get('locale')?.getSnapshot?.().active
+			} catch {
+				active = undefined
+			}
+			if (typeof active === 'string' && active !== '') {
+				return active.toLowerCase().startsWith('zh') ? 'zh' : 'en'
+			}
+			const nav = typeof navigator === 'undefined' ? '' : navigator.language
+			return String(nav).toLowerCase().startsWith('zh') ? 'zh' : 'en'
+		}
+
+		/** 行内样式。token 名照抄宿主，括号里是浅色兜底。 */
+		const styles = {
+			row: {
+				display: 'flex',
+				flexDirection: 'column',
+				gap: '10px',
+				padding: '16px 0',
+				borderBottom: '.5px solid var(--dsw-alias-border-l2,#e5e7eb)',
+			},
+			head: { display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: '24px' },
+			title: { fontSize: 14, lineHeight: '20px', color: 'var(--dsw-alias-label-primary,#111827)' },
+			description: {
+				marginTop: 4,
+				fontSize: 12,
+				lineHeight: '18px',
+				color: 'var(--dsw-alias-label-secondary,#6b7280)',
+			},
+			actions: { display: 'flex', alignItems: 'center', gap: 8, flex: 'none' },
+			field: { display: 'flex', alignItems: 'center', gap: 8 },
+			label: {
+				fontSize: 12,
+				lineHeight: '18px',
+				color: 'var(--dsw-alias-label-secondary,#6b7280)',
+				flex: 'none',
+			},
+			input: {
+				flex: '1 1 auto',
+				minWidth: 0,
+				font: 'inherit',
+				fontSize: 12,
+				lineHeight: '18px',
+				padding: '5px 8px',
+				borderRadius: 'var(--dsw-radius-sm,8px)',
+				border: '1px solid var(--dsw-alias-border-l2,#e5e7eb)',
+				background: 'var(--dsw-alias-bg-base,#fff)',
+				color: 'var(--dsw-alias-label-primary,#111827)',
+			},
+			button: {
+				font: 'inherit',
+				fontSize: 12,
+				lineHeight: '18px',
+				padding: '5px 10px',
+				borderRadius: 'var(--dsw-radius-sm,8px)',
+				border: '1px solid var(--dsw-alias-border-l2,#e5e7eb)',
+				background: 'transparent',
+				color: 'var(--dsw-alias-label-primary,#111827)',
+				cursor: 'pointer',
+				whiteSpace: 'nowrap',
+				flex: 'none',
+			},
+			buttonPrimary: {
+				borderColor: 'transparent',
+				background: 'var(--dsw-alias-state-warn-primary,#b45309)',
+				color: '#fff',
+			},
+			hint: { fontSize: 12, lineHeight: '18px', color: 'var(--dsw-alias-label-secondary,#6b7280)' },
+			warn: { fontSize: 12, lineHeight: '18px', color: 'var(--dsw-alias-state-warn-primary,#b45309)' },
+			error: { fontSize: 12, lineHeight: '18px', color: 'var(--dsw-alias-state-error-primary,#dc2626)' },
+			ok: { fontSize: 12, lineHeight: '18px', color: 'var(--dsw-alias-state-success-primary,#16a34a)' },
+		}
+
+		/**
+		 * 读一个 JSON 端点。
+		 *
+		 * 失败时状态码不是 200，但 body 仍是 JSON 且带着真正的原因，所以这里
+		 * 先解析、再看 `ok`，不拿状态码覆盖原文（照抄 dsh-mini-remote 的经验）。
+		 * @param path - 同源路径。
+		 * @param options - fetch 选项。
+		 * @returns `{ ok: true, data }` 或 `{ ok: false, error }`。
+		 */
+		async function readJson(path, options) {
+			let response
+			try {
+				response = await fetch(path, { credentials: 'same-origin', cache: 'no-store', ...options })
+			} catch (error) {
+				return { ok: false, error: String((error && error.message) || error) }
+			}
+			let body
+			try {
+				body = await response.json()
+			} catch {
+				return { ok: false, error: `HTTP ${response.status}` }
+			}
+			if (body === null || typeof body !== 'object') return { ok: false, error: `HTTP ${response.status}` }
+			if (body.ok !== true) {
+				return { ok: false, error: typeof body.error === 'string' ? body.error : `HTTP ${response.status}` }
+			}
+			return { ok: true, data: body }
+		}
+
+		/** 把文案里的阶段/错误翻成人话；认不出来就把原文附在后面。 */
+		function describePhase(t, state) {
+			if (state === null) return t.loading
+			if (state.phase === 'starting') return t.phaseStarting
+			if (state.phase === 'unavailable') return t.phaseUnavailable
+			if (state.phase === 'error') return t.phaseError
+			return undefined
+		}
+
+		/**
+		 * 「设置 → 通用」里的这一行。
+		 *
+		 * 只在挂载时取一次状态；另有 window focus 时刷新一次（桌面 App 里
+		 * 用户切走再切回来很常见，这时 Tailscale 可能刚好起来了）。
+		 * @param props - 注入面给的 `ctx`（见 apply 里的 `inject`）。
+		 */
+		function RemoteRow(props) {
+			const ctx = props.ctx
+			// 语言变化时强制重渲染；字典本身是行内常量，不需要订阅字典。
+			const [, setTick] = useState(0)
+			const [state, setState] = useState(null)
+			const [error, setError] = useState(null)
+			const [busy, setBusy] = useState(false)
+			const [copied, setCopied] = useState(false)
+			const [confirming, setConfirming] = useState(false)
+			const [notice, setNotice] = useState(null)
+			const inputRef = useRef(null)
+
+			const t = pickLanguage(ctx) === 'zh' ? ZH : EN
+
+			const load = useCallback(async () => {
+				const result = await readJson(STATE_PATH)
+				if (result.ok) {
+					setState(result.data)
+					setError(null)
+				} else {
+					setError(result.error)
+				}
+			}, [])
+
+			useEffect(() => {
+				void load()
+			}, [load])
+
+			useEffect(() => {
+				const locale = (() => {
+					try {
+						return ctx.get('locale')
+					} catch {
+						return undefined
+					}
+				})()
+				if (locale === undefined || typeof locale.subscribe !== 'function') return undefined
+				return locale.subscribe(() => setTick((n) => n + 1))
+			}, [ctx])
+
+			useEffect(() => {
+				const onFocus = () => {
+					void load()
+				}
+				window.addEventListener('focus', onFocus)
+				return () => window.removeEventListener('focus', onFocus)
+			}, [load])
+
+			const url = state === null ? null : state.loginUrl || state.plainUrl
+			const usesLoginUrl = state !== null && state.loginUrl !== null && state.loginUrl !== undefined
+
+			const copy = useCallback(async () => {
+				if (url === null || url === undefined) return
+				let done = false
+				try {
+					if (typeof navigator !== 'undefined' && navigator.clipboard !== undefined) {
+						await navigator.clipboard.writeText(url)
+						done = true
+					}
+				} catch {
+					done = false
+				}
+				if (!done) {
+					// 非安全上下文里 clipboard 不可用（tailnet 的 https 和 localhost 都算安全，
+					// 但用户可能从 http 的局域网地址进来）。退回选中输入框内容，让人手动复制。
+					try {
+						inputRef.current?.select?.()
+						done = document.execCommand('copy')
+					} catch {
+						done = false
+					}
+				}
+				setNotice(done ? null : t.copyFailed)
+				setCopied(done)
+				if (done) setTimeout(() => setCopied(false), 1600)
+			}, [url, t])
+
+			const rotate = useCallback(async () => {
+				setBusy(true)
+				setNotice(null)
+				const result = await readJson(ROTATE_PATH, { method: 'POST' })
+				setBusy(false)
+				setConfirming(false)
+				if (!result.ok) {
+					setNotice(`${t.rotateFailed}：${result.error}`)
+					return
+				}
+				setState((previous) => ({ ...(previous ?? {}), ...result.data }))
+				setNotice(result.data.revokesSessions === false ? t.rotateDoneLinkOnly : t.rotateDoneRevoke)
+			}, [t])
+
+			const canRotate = state !== null && state.canRotate === true && !busy
+			// 文案必须跟着实际行为走：吊销会话时警告要说清「所有设备都会退出」，
+			// 否则用户以为只是换个链接，结果手机被踢下线、还不知道为什么。
+			const revokes = state !== null && state.revokesSessions === true
+			const warningText = revokes ? t.rotateWarningRevoke : t.rotateWarningLinkOnly
+
+			// 首帧：还没拿到状态，也没出错。这时不要摆一个空输入框配一个会误导的标签，
+			// 直接说「正在读取」。
+			if (state === null && error === null) {
+				return h(
+					'div',
+					{ style: styles.row, 'data-dsh-tailscale-remote-row': '' },
+					h('div', { style: styles.title }, t.title),
+					h('div', { style: styles.description }, t.description),
+					h('div', { style: styles.hint }, t.loading),
+				)
+			}
+
+			const hint = describePhase(t, state)
+
+			return h(
+				'div',
+				{ style: styles.row, 'data-dsh-tailscale-remote-row': '' },
+				h(
+					'div',
+					{ style: styles.head },
+					h(
+						'div',
+						null,
+						h('div', { style: styles.title }, t.title),
+						h('div', { style: styles.description }, t.description),
+					),
+					h(
+						'div',
+						{ style: styles.actions },
+						confirming
+							? [
+									h(
+										'button',
+										{
+											key: 'go',
+											type: 'button',
+											style: { ...styles.button, ...styles.buttonPrimary },
+											disabled: busy,
+											onClick: () => void rotate(),
+										},
+										t.rotateConfirm,
+									),
+									h(
+										'button',
+										{ key: 'no', type: 'button', style: styles.button, disabled: busy, onClick: () => setConfirming(false) },
+										t.rotateCancel,
+									),
+								]
+							: h(
+									'button',
+									{
+										type: 'button',
+										style: styles.button,
+										disabled: !canRotate,
+										onClick: () => {
+											setNotice(null)
+											setConfirming(true)
+										},
+									},
+									t.rotate,
+								),
+					),
+				),
+				h(
+					'div',
+					{ style: styles.field },
+					h('span', { style: styles.label }, usesLoginUrl ? t.urlLabel : t.plainLabel),
+					h('input', {
+						ref: inputRef,
+						readOnly: true,
+						spellCheck: false,
+						value: url ?? '',
+						'aria-label': usesLoginUrl ? t.urlLabel : t.plainLabel,
+						style: styles.input,
+						onFocus: (event) => {
+							try {
+								event.target.select()
+							} catch {
+								/* 选中失败无所谓 */
+							}
+						},
+					}),
+					h(
+						'button',
+						{ type: 'button', style: styles.button, disabled: url === null || url === undefined, onClick: () => void copy() },
+						copied ? t.copied : t.copy,
+					),
+				),
+				confirming ? h('div', { style: styles.warn }, warningText) : null,
+				notice === null ? null : h('div', { style: styles.warn }, notice),
+				error !== null
+					? h(
+							'div',
+							{ style: styles.error, role: 'alert' },
+							`${error} `,
+							h(
+								'button',
+								{ type: 'button', style: styles.button, onClick: () => void load() },
+								t.retry,
+							),
+						)
+					: null,
+				state === null || state.phase === 'ready'
+					? h(
+							'div',
+							{ style: styles.hint },
+							usesLoginUrl ? `${t.keepBookmark}${t.cookieHint(state?.cookieMaxAgeDays ?? 0)}` : t.noLogin,
+						)
+					: h('div', { style: styles.hint }, hint),
+			)
+		}
+
+		/**
+		 * 注册这一行。
+		 *
+		 * `slots.inject` 而不是 `slots.register` 直调：`settings.general.item` 由
+		 * ui-settings-general 声明，它和本包的激活顺序没有保证。
+		 * @param ctx - 客户端根上下文。
+		 */
+		function apply(ctx) {
+			ctx.slots.inject('settings.general.item', () =>
+				ctx.slots.register(
+					{
+						name: 'settings.general.item',
+						id: ROW_ID,
+						// 排在 performance-usage(30) 之后、current-version(100) 之前。
+						order: 95,
+						// 组件从注入面上拿 ctx（插槽的 standard props 里没有 ctx）。
+						inject: () => ({ ctx }),
+					},
+					RemoteRow,
+				),
+			)
+		}
+
+		exports.name = 'dsh-tailscale-remote'
+		// 只要 slots；locale 走 ctx.get 可选读取（写进 inject 会在它缺席时 park 掉整包）。
+		exports.inject = ['slots']
+		exports.apply = apply
+		return module.exports
+	},
+})

package/index.js

@@ -107,6 +107,12 @@ function normalizeConfig(raw) {
       Number.isFinite(source.cookieMaxAgeDays) && source.cookieMaxAgeDays >= 0 ? source.cookieMaxAgeDays : 3650,
     // 是否注册一个「稳定登录入口」路由（/remote/<持久密钥>），让手机不用去翻令牌。
     loginRoute: source.loginRoute !== false,
+    // 换密钥时是否**同时吊销所有已登录的会话**。
+    //
+    // 默认 true，因为换密钥的动机通常就是「密钥泄露了」：只换登录密钥的话，
+    // 已经用泄露密钥登录过的人手里那张 10 年 cookie 依然有效。代价是所有设备
+    // （含自己的手机）都要重新登录一次；点按钮的那台会被补发 cookie、不掉线。
+    revokeSessionsOnRotate: source.revokeSessionsOnRotate !== false,
   }
 }
 
@@ -435,6 +441,340 @@ 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'
+
+/**
+ * DSH 浏览器会话 cookie 的签名密钥在 credentials 里的记录键。
+ *
+ * 值是 `credentialKey('client-connection', 'browser-session')` —— 那个 helper 只是
+ * `brandString(`${scope}/${id}`)`（`@deepseek-ai/dsh-credentials` 的 types），所以
+ * 运行时就是这条普通字符串。**必须逐字一致**：写错键会静默写到另一条记录上，
+ * 于是重启后旧密钥照旧生效、旧 cookie 继续能用 —— 换了个寂寞而且毫无提示。
+ */
+const AUTH_RECORD_KEY = 'client-connection/browser-session'
+/** 会话密钥长度（字节），与 client-connection 的 `SECRET_BYTES` 一致，否则它拒绝加载。 */
+const SESSION_SECRET_BYTES = 32
+/** 记录格式版本，与 `STORED_SECRET_VERSION` 一致。 */
+const STORED_SECRET_VERSION = 1
+
+/** 从请求头取规范化的 authority（cookie 名与签名受众都用它）。 */
+function hostAuthority(headers) {
+  const host = headers?.get?.('host')
+  if (typeof host !== 'string' || host === '') return undefined
+  try {
+    return new URL(`http://${host}`).host
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 换掉 DSH 浏览器会话 cookie 的签名密钥，从而**立刻吊销所有已登录的会话**。
+ *
+ * 为什么换密钥必须连这一步一起做：登录链接（`/remote/<密钥>`）只负责**换取**一张
+ * 会话 cookie。密钥泄露后，如果对方已经用它登录过，他手里那张 cookie 是用
+ * `browserAuth.secret` 签名的、**有效期 10 年**，换登录密钥完全不影响它。
+ * 要让泄露的密钥真正失效，签名密钥也得换。
+ *
+ * 两处都要改，缺一不可：
+ *  1. credentials 记录（**持久**）—— 否则 DSH 一重启就把旧密钥读回来，旧 cookie 复活。
+ *  2. 活着的 `browserAuth.secret`（**立即生效**）—— 它按引用比较签名，改了就当场失效。
+ * @param scope - 带 `connection` / `credentials` 的上下文。
+ * @returns 新的密钥字节。
+ * @throws 服务缺席、或写入没有真正落到那条记录上时（绝不假装成功）。
+ */
+async function rotateSessionSecret(scope) {
+  const credentials = scope.get('credentials', false)
+  if (credentials === undefined || typeof credentials.modifyRecord !== 'function') {
+    throw new Error('读不到 credentials 服务，无法吊销已登录的会话')
+  }
+  const connection = scope.get('connection', false)
+  if (connection?.browserAuth === undefined) {
+    throw new Error('读不到 connection.browserAuth，无法吊销已登录的会话')
+  }
+
+  const secret = randomBytes(SESSION_SECRET_BYTES).toString('base64url')
+  const written = await credentials.modifyRecord(AUTH_RECORD_KEY, () =>
+    Promise.resolve({
+      kind: 'grant',
+      payload: { version: STORED_SECRET_VERSION, secret },
+    }),
+  )
+
+  // 回读确认。写错键、或被只读来源遮蔽时，`modifyRecord` 会**成功返回**但记录没变，
+  // 于是这里不校验的话就是「报成功、实则没换」——重启后旧 cookie 复活。
+  if (written?.payload?.secret !== secret) {
+    throw new Error('会话密钥没有写入成功（credentials 记录未更新）')
+  }
+
+  connection.browserAuth.secret = Buffer.from(secret, 'base64url')
+  return connection.browserAuth.secret
+}
+
+/**
+ * 组装管理端点要返回的状态。
+ *
+ * 刻意**不抛**：「还在启动」「起不来」都是设置页要看的正常答案，不是错误响应。
+ * @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',
+    // 换密钥会不会把所有设备踢下线（客户端据此决定警告文案的强度）。
+    revokesSessions: config.enabled && config.loginRoute && config.revokeSessionsOnRotate,
+    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
+}
+
+/**
+ * 换一个新密钥：换登录密钥 → 吊销所有会话 → 装上新路由 → 写回状态文件 → 更新活状态。
+ *
+ * 吊销会话是**有意的**：登录密钥泄露后，对方可能已经用它换到一张 10 年有效的会话
+ * cookie；只换登录密钥的话他照样在里面。代价是**所有设备都要重新登录一次**，
+ * 包括你自己的手机 —— 这正是「密钥泄露」时该有的行为。
+ *
+ * 例外：**发起这次更换的那个浏览器会被补发一张新 cookie**，所以它自己不会掉线。
+ * 也就是说「在你电脑上点更换」= 电脑留着、其它设备全部踢掉。
+ * @param scope - 带 `connection` 的上下文。
+ * @param config - 归一化后的配置。
+ * @param runtime - 活状态。
+ * @param deps - 依赖注入（测试替换用）。
+ * @param requestingAuthority - 发起请求的那个 authority（用它给当前浏览器补发 cookie）。
+ * @returns `{ loginUrl, loginPath, updatedAt, revokesSessions, stayedSignedIn }`。
+ * @throws 未就绪 / 登录入口已关闭 / webServer 或 credentials 不可用时。
+ */
+async function rotateLoginSecret(scope, config, runtime, deps = REAL_DEPS, requestingAuthority) {
+  if (!config.loginRoute) throw new Error('登录入口已关闭（loginRoute=false），没有可更换的密钥')
+  const state = runtime.state
+  if (state === undefined) throw new Error('远程访问还没就绪，稍后再试')
+
+  const connection = scope.get('connection', false)
+
+  // 先吊销会话，再装新路由：反过来的话，若吊销失败就已经把新密钥写出去了，
+  // 用户会以为换成功了，而泄露的那张 cookie 还活着。
+  if (config.revokeSessionsOnRotate) await rotateSessionSecret(scope)
+
+  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
+
+  // 给**发起请求的那个 authority** 补一张新 cookie，让点按钮的这台设备不掉线。
+  // 只能补这一个：cookie 按 authority 命名并签名，给别的 authority 种的 cookie
+  // 浏览器会直接忽略。
+  let stayedSignedIn = false
+  if (config.revokeSessionsOnRotate && typeof requestingAuthority === 'string' && requestingAuthority !== '') {
+    const minted = mintSessionCookie(connection, requestingAuthority, config.cookieMaxAgeDays * 86400000)
+    if (minted !== undefined) stayedSignedIn = true
+    return {
+      loginUrl,
+      loginPath,
+      updatedAt: next.updatedAt,
+      revokesSessions: true,
+      stayedSignedIn,
+      cookie: minted === undefined ? null : sessionCookieHeader(minted),
+    }
+  }
+
+  return { loginUrl, loginPath, updatedAt: next.updatedAt, revokesSessions: config.revokeSessionsOnRotate, stayedSignedIn }
+}
+
+/**
+ * 注册管理端点。
+ *
+ * 即便 `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, extraHeaders) =>
+    new Response(JSON.stringify(payload), {
+      status,
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        ...(extraHeaders ?? {}),
+      },
+    })
+
+  // 每条路由都显式挂在自己的 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 (request) => {
+          try {
+            const result = await rotateLoginSecret(
+              scope,
+              config,
+              runtime,
+              REAL_DEPS,
+              hostAuthority(request?.headers),
+            )
+            // 补发的 cookie 必须由 HTTP 响应带走；放在 body 里没用。
+            const cookie = typeof result.cookie === 'string' ? { 'set-cookie': result.cookie } : undefined
+            const { cookie: _omitted, ...payload } = result
+            return json({ ok: true, ...payload }, 200, cookie)
+          } 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 - 插件上下文。
@@ -442,10 +782,6 @@ function sessionCookieHeader(minted) {
  */
 export function apply(ctx, rawConfig) {
   const config = normalizeConfig(rawConfig)
-  if (!config.enabled) {
-    ctx.logger.info('tailscale-remote: enabled=false，插件不动作')
-    return
-  }
 
   // connection 是可选依赖：服务晚到也会触发，永不出现则保持静默。
   // 服务只从 scope 参数上取（inject 新建的 fiber 的 store 里才有它）。
@@ -466,6 +802,18 @@ export function apply(ctx, rawConfig) {
       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 () => {
@@ -477,8 +825,10 @@ export function apply(ctx, rawConfig) {
     }, 'tailscale-remote: teardown')
 
     // 启动流程异步跑，不阻塞 Loader 装配。
-    setup(scope, config, undo).catch((error) => {
-      scope.logger.warn(`tailscale-remote: 启动失败：${String(error?.message ?? error)}`)
+    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}`)
     })
   })
 }
@@ -499,10 +849,15 @@ const REAL_DEPS = {
 }
 
 /** 启动：拉起 tailscale → 建 serve 路由 → 信任该 authority → 打印手机可用的链接。 */
-async function setup(scope, config, undo, deps = REAL_DEPS) {
+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
   }
@@ -515,11 +870,17 @@ async function setup(scope, config, undo, deps = REAL_DEPS) {
   // 关键：必须验证 backend 真的 Running，不能只信 `tailscale up` 的退出码
   // （Windows 上客户端被完全退出时，up 会 exit 0 但什么都不做）。
   const running = await ensureRunning(binary, config, deps, logger, undo)
-  if (!running) return
+  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
   }
@@ -527,6 +888,8 @@ async function setup(scope, config, undo, deps = REAL_DEPS) {
   // 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
   }
@@ -538,6 +901,8 @@ async function setup(scope, config, undo, deps = REAL_DEPS) {
     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
     }
@@ -554,8 +919,11 @@ async function setup(scope, config, undo, deps = REAL_DEPS) {
       }
       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 失败: ${(serve.stderr || serve.stdout).trim().slice(0, 300)}；` +
+          `tailscale-remote: 配置 Serve 失败: ${detail}；` +
             '若提示 HTTPS 证书，请先在 Tailscale 管理台为该 tailnet 启用 HTTPS 证书',
         )
         return
@@ -593,6 +961,15 @@ async function setup(scope, config, undo, deps = REAL_DEPS) {
     }
   }
 
+  let handoffUrl = plainUrl
+  try {
+    // authenticatedUrl 会把本进程的启动令牌加到链接上；首次打开会种下 cookie。
+    handoffUrl = connection?.authenticatedUrl?.(plainUrl) ?? plainUrl
+  } catch {
+    handoffUrl = plainUrl
+  }
+  runtime.handoffUrl = handoffUrl
+
   // 稳定的登录入口：/remote/<持久密钥> → 302 到带令牌的地址。
   // 令牌每次都变、用户没法存书签；这条路径的密钥写在状态文件里，**跨重启不变**，
   // 所以手机上存一次就够了。密钥同时充当访问门槛（不知道密钥的人拿不到会话）。
@@ -600,66 +977,22 @@ async function setup(scope, config, undo, deps = REAL_DEPS) {
   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
-  }
-
-  let handoffUrl = plainUrl
-  try {
-    // authenticatedUrl 会把本进程的启动令牌加到链接上；首次打开会种下 cookie。
-    handoffUrl = connection?.authenticatedUrl?.(plainUrl) ?? plainUrl
-  } catch {
-    handoffUrl = plainUrl
-  }
-
-  // 登录入口的跳转目标就是上面这个带令牌的地址；注册在 DSH 自己的 webserver 上
-  // （所以不需要第二个端口、也不需要额外的 tailscale serve 路由）。
-  if (loginPath !== undefined) {
-    const registerLoginRoute = (webScope) => {
-      const webServer = webScope.get('webServer')
-      if (webServer === undefined) return
-      webScope.effect(
-        () =>
-          webServer.register({
-            kind: 'exact',
-            path: loginPath,
-            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: handoffUrl,
-                'cache-control': 'no-store',
-                'referrer-policy': 'no-referrer',
-              })
-              res.end()
-            },
-          }),
-        'tailscale-remote: login route',
-      )
-    }
+    // 登录入口的跳转目标就是上面这个带令牌的地址；注册在 DSH 自己的 webserver 上
+    // （所以不需要第二个端口、也不需要额外的 tailscale serve 路由）。
     // 嵌套 inject：webServer 缺席时只丢登录入口，tailscale / 信任项照常工作。
-    scope.inject(['webServer'], (webScope) => registerLoginRoute(webScope))
+    scope.inject(['webServer'], (webScope) => {
+      runtime.webScope = webScope
+      installLoginRoute(runtime, connection, config, authority, secret)
+    })
   }
 
   const loginSecret = loginPath === undefined ? undefined : loginPath.slice('/remote/'.length)
-  await deps.persistState(scope, {
+  const snapshot = {
     url: handoffUrl,
     loginUrl,
     loginPath,
@@ -672,7 +1005,11 @@ async function setup(scope, config, undo, deps = REAL_DEPS) {
     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) {
@@ -771,7 +1108,17 @@ export const internals = {
   ensureLoginSecret,
   mintSessionCookie,
   sessionCookieHeader,
+  statePayload,
+  installLoginRoute,
+  rotateLoginSecret,
+  rotateSessionSecret,
+  hostAuthority,
+  registerAdminRoutes,
+  freshRuntime,
   setup,
   teardown,
   REAL_DEPS,
+  STATE_PATH,
+  ROTATE_PATH,
+  AUTH_RECORD_KEY,
 }

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Tailscale remote access",
-    "description": "Publishes the DSH Web GUI on your tailnet whenever DSH runs, so a phone anywhere can connect, and removes the route on exit. Your login link lives in the loginUrl field of ~/.dsh/tailscale-remote.json (https://<machine>.<tailnet>.ts.net:7259/remote/<key>); bookmark it once on the phone — it survives restarts."
+    "description": "Publishes the DSH Web GUI on your tailnet whenever DSH runs, so a phone anywhere can connect, and removes the route on exit. The phone link is in Settings -> General -> Phone access; copy it with one click, and if it ever leaks, rotate the key there so the old link and every old session stop working."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Tailscale 远程访问",
-    "description": "开 DSH 就把 Web GUI 发布到你的 tailnet，手机随处可连；关 DSH 自动撤掉路由。登录链接在 ~/.dsh/tailscale-remote.json 的 loginUrl 字段（形如 https://<机器>.<tailnet>.ts.net:7259/remote/<密钥>），手机上存一次书签即可，跨重启不变。"
+    "description": "开 DSH 就把 Web GUI 发布到你的 tailnet，手机随处可连；关 DSH 自动撤掉路由。手机链接就在「设置 → 通用 → 手机连接」那一行里，点一下即可复制；链接泄露时可在那里更换密钥，旧链接与所有旧登录会一起失效。"
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-tailscale-remote",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "Publishes the DSH Web GUI on your tailnet whenever DSH runs, so a phone anywhere can connect, and removes the route on exit. The login link lives in the loginUrl field of ~/.dsh/tailscale-remote.json (https://<machine>.<tailnet>.ts.net:7259/remote/<key>); bookmark it once — it survives restarts.",
+  "description": "Publishes the DSH Web GUI on your tailnet whenever DSH runs, so a phone anywhere can connect, and removes the route on exit. The phone link lives in Settings -> General -> Phone access with one-click copy and key rotation: rotating revokes the old link and every session signed with it. The same link is in the loginUrl field of ~/.dsh/tailscale-remote.json.",
   "license": "MIT",
   "author": "Ckarefulon",
   "publishConfig": {
@@ -31,23 +31,31 @@
   ],
   "exports": {
     ".": "./index.js",
+    "./client": "./client/client.js",
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json"
   },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings-general"
+      ]
     }
   },
   "files": [
     "index.js",
+    "client/client.js",
     "cordis.patch.yml",
     "README.md",
     "LICENSE",
     "locale/*.json"
   ],
   "scripts": {
-    "test": "node --test test/classify.test.mjs test/teardown.test.mjs"
+    "test": "node --test test/classify.test.mjs test/teardown.test.mjs test/routes.test.mjs test/client.test.mjs"
   },
   "engines": {
     "node": ">=20"