dsh-remote-panel 0.3.0 → 0.3.1

package/README.md

@@ -64,6 +64,22 @@ Caddy 的 `pki/authorities/local/root.crt`）。
 - Android：设置 → 安全 → 加密与凭据 → 安装证书 → CA 证书。
 - iOS：下载后到 设置 → 通用 → 关于本机 → 证书信任设置 里打开信任。
 
+## 安全模型：令牌只在门禁之后
+
+手机端有两道门：Caddy 的口令门禁（`dsh_gate` Cookie）+ DSH 自己的会话令牌。两者的取用顺序是：
+
+```
+扫码/点链接 → /pair?k=口令（种门禁 Cookie） → /remote-panel/login（要 Cookie，Caddy 直接发）
+            → /?token=…（换取 DSH 会话）
+```
+
+- 二维码里**只有口令**，没有令牌；
+- 带令牌的跳转页 `login.html` 放在门禁**之后**，没有 Cookie 拿不到（实测 401）；
+- 免鉴权的 `/remote-panel/app/*` 只放静态资源（manifest / 图标 / 根证书 / APK），不含任何凭据；
+- 旧版 APK 的入口 `go.html` 已改成「请更新」提示页，不会再泄露令牌。
+
+APK 里内置了门禁口令（启动即过 `/pair`），所以**换口令后需要重新构建壳**。
+
 ## 手机 App（WebView 壳）
 
 PWA「安装应用」在国行 Android 上装不成：WebAPK 打包依赖 Google Play 服务，且打包服务器要能从公网

package/deploy/templates/Caddyfile.tmpl

@@ -25,7 +25,7 @@
 		handle /pair {
 			header Set-Cookie "dsh_gate=@@ACCESS_KEY@@; Max-Age=31536000; Path=/; HttpOnly; SameSite=Lax"
 			header Content-Type "text/html; charset=utf-8"
-			respond `<!doctype html><meta charset="utf-8"><title>正在连接…</title><script>const t=new URLSearchParams(location.search).get("token");location.replace(t?"/?token="+encodeURIComponent(t):"/")</script>` 200
+			respond `<!doctype html><meta charset="utf-8"><title>正在连接…</title><script>const t=new URLSearchParams(location.search).get("token");location.replace(t?"/?token="+encodeURIComponent(t):"/remote-panel/login")</script>` 200
 		}
 
 		# 诊断用：不经过任何认证
@@ -62,6 +62,12 @@
 		# Caddy 默认没有 cookie 匹配器，用 Header 通配匹配替代
 		@paired header Cookie "*dsh_gate=@@ACCESS_KEY@@*"
 		handle @paired {
+			# 带令牌的跳转页：必须过了门禁才能拿
+			handle /remote-panel/login* {
+				root * @@APP_DIR@@
+				rewrite * /login.html
+				file_server
+			}
 			# 关键：不重写 Host/Origin。DSH 通过 --trusted-host 接受这个 authority，
 			# Cookie 因此天然同源，不需要任何注入或伪造。
 			reverse_proxy 127.0.0.1:@@UPSTREAM_PORT@@

package/lib/client.js

@@ -545,11 +545,14 @@ window.__ModuleLoader__.load({
 			const [probe, setProbe] = useState(null)
 			const [rejects, setRejects] = useState([])
 			const [busy, setBusy] = useState(false)
+			const [shell, setShell] = useState(null)
 
 			const refresh = useCallback(async () => {
 				setBusy(true)
 				try {
-					setProbe((await callApi('/probe')).probe)
+					const [probed, status] = await Promise.all([callApi('/probe'), callApi('/status')])
+					setProbe(probed.probe)
+					setShell(status.shell ?? null)
 					setRejects((await callApi('/rejects')).entries)
 				} catch {
 					/* 状态探测失败时保留上一帧 */
@@ -572,6 +575,8 @@ window.__ModuleLoader__.load({
 				// 内部 CA 的叶子证书只有 12 小时，续签失败时探活照样握手成功（rejectUnauthorized:false），
 				// 所以单独看它：剩余不足 2 小时或 SAN 不匹配都算红灯
 				[certHours === null ? '证书' : `证书 ${certHours}h`, cert === undefined ? undefined : { ok: cert.ok === true }],
+				// 手机外壳依赖 DSH 的 hash 类名：DSH 升级后这里会红，提示需要更新插件
+				['外壳适配', shell === null ? undefined : { ok: shell.ok === true }],
 			]
 
 			return jsxs(Card, {
@@ -591,6 +596,12 @@ window.__ModuleLoader__.load({
 							}),
 						],
 					}),
+					shell !== null && shell.ok !== true
+						? jsx('p', {
+								style: { ...styles.hint, color: '#f2b8b5' },
+								children: `外壳挂点缺失：${(shell.missing ?? []).join(', ') || '未知'} —— DSH 升级后需要更新插件，否则手机样式会错位`,
+							})
+						: null,
 					cert !== undefined && cert.ok !== true
 						? jsx('p', {
 								style: { ...styles.hint, color: '#f2b8b5' },
@@ -1068,7 +1079,7 @@ window.__ModuleLoader__.load({
     inset: 0 auto 0 0;
     height: auto !important;
     z-index: 900;
-    padding-bottom: env(safe-area-inset-bottom, 0px);
+    padding-bottom: max(env(safe-area-inset-bottom, 0px), var(--dsh-safe-bottom, 0px));
     border-radius: 0 16px 16px 0 !important;
     box-shadow: 0 0 28px rgba(0, 0, 0, .32) !important;
   }
@@ -1076,7 +1087,10 @@ window.__ModuleLoader__.load({
   body { overscroll-behavior: none; }
 
   /* 顶部安全区：默认取 env()；WebView 里由壳把真实切角高度写进 --dsh-safe-top */
-  :root { --dsh-safe-top: env(safe-area-inset-top, 0px); }
+  :root {
+    --dsh-safe-top: env(safe-area-inset-top, 0px);
+    --dsh-safe-bottom: env(safe-area-inset-bottom, 0px);
+  }
 
   /* 顶栏：52px；刘海屏/独立窗口把状态栏让出来 */
   .wSkVaW_header {
@@ -1156,11 +1170,16 @@ window.__ModuleLoader__.load({
   .pXSMma_previewBadge { display: none !important; }
   /* 原生把「问候语 + 输入条」一起居中；手机按原型拆开：
      问候语留在屏幕中间（原生居中），输入条钉到底部 */
+  /* 会话里的输入条座位：底部要让开手势条（WebView 里 env() 常为 0，由壳注入） */
+  .wSkVaW_composerSeat {
+    padding-bottom: max(env(safe-area-inset-bottom, 0px), var(--dsh-safe-bottom, 0px)) !important;
+  }
+
   .wSkVaW_composerHero .uV2eYG_root {
     position: fixed;
     left: 0;
     right: 0;
-    bottom: max(18px, env(safe-area-inset-bottom, 0px));
+    bottom: max(18px, max(env(safe-area-inset-bottom, 0px), var(--dsh-safe-bottom, 0px)));
     z-index: 55;
   }
 
@@ -1436,7 +1455,7 @@ window.__ModuleLoader__.load({
     overflow-y: auto;
     -webkit-overflow-scrolling: touch;
     overscroll-behavior: contain;
-    padding-bottom: env(safe-area-inset-bottom, 0px) !important;
+    padding-bottom: max(env(safe-area-inset-bottom, 0px), var(--dsh-safe-bottom, 0px)) !important;
   }
 
   /* 长会话滚动：只在窄屏做滚动容器层面的优化，桌面保持原样 */
@@ -1678,6 +1697,32 @@ window.__ModuleLoader__.load({
 			}
 		}
 
+		/**
+		 * 外壳挂点自检：DSH 升级后这些 hash 类名可能全变，样式就整体失配。
+		 * 启动后检查一遍 DOM，把结果报给宿主，面板里能直接看到「外壳适配」这盏灯。
+		 */
+		function installShellContractReport() {
+			if (typeof document === 'undefined' || typeof window === 'undefined') return () => {}
+			// 只查「任何页面都该存在」的挂点；抽屉里的 hHd-Xa_ 只在打开时才有，不参与判定
+			const markers = ['wSkVaW_', 'uV2eYG_', 'pXSMma_', 'pI_x6G_']
+			let timer = window.setTimeout(async () => {
+				try {
+					const missing = markers.filter((marker) => document.querySelector(`[class*="${marker}"]`) === null)
+					if (missing.length > 0) {
+						console.warn('[remote-panel] 外壳挂点缺失，手机样式可能失配：', missing.join(', '))
+					}
+					await callApi('/shell', {
+						method: 'POST',
+						headers: { 'content-type': 'application/json' },
+						body: JSON.stringify({ missing }),
+					})
+				} catch {
+					/* 上报失败不影响使用 */
+				}
+			}, 1500)
+			return () => window.clearTimeout(timer)
+		}
+
 		/**
 		 * 本机反馈：任务跑完 / 等你确认时，如果页面在后台，闪一下标题 + 震动。
 		 * 不依赖推送服务（v1 不做推送），也不需要服务端配合。
@@ -2225,6 +2270,7 @@ window.__ModuleLoader__.load({
 			const cleanupNet = installConnectivity()
 			const cleanupFocus = installComposerFocusGuard()
 			const cleanupFps = installFpsMeter()
+			const cleanupContract = installShellContractReport()
 			if (typeof ctx.effect === 'function') ctx.effect(() => cleanupClear, 'remote-panel: workspace clear')
 			if (typeof ctx.effect === 'function') ctx.effect(() => cleanupBack, 'remote-panel: back gesture')
 			if (typeof ctx.effect === 'function') ctx.effect(() => cleanupAttention, 'remote-panel: attention')
@@ -2232,6 +2278,7 @@ window.__ModuleLoader__.load({
 			if (typeof ctx.effect === 'function') ctx.effect(() => cleanupNet, 'remote-panel: connectivity')
 			if (typeof ctx.effect === 'function') ctx.effect(() => cleanupFocus, 'remote-panel: composer focus guard')
 			if (typeof ctx.effect === 'function') ctx.effect(() => cleanupFps, 'remote-panel: fps meter')
+			if (typeof ctx.effect === 'function') ctx.effect(() => cleanupContract, 'remote-panel: shell contract report')
 			if (typeof ctx.effect === 'function') ctx.effect(() => cleanup, 'remote-panel: mobile shell css')
 
 			ctx.slots.inject('shell.overlay', () =>

package/lib/contract.js

@@ -0,0 +1,73 @@
+/**
+ * 外壳契约检查：确认 DSH 前端还在用我们依赖的那套 hash 类名。
+ *
+ * 手机外壳的样式全靠 DSH 构建产物里的私有类名（`wSkVaW_header` 这种），
+ * 它们随每次构建变化。DSH 一升级，样式可能整体失配——所以在宿主侧做一次
+ * 「挂点还在不在」的体检，失配时面板显红，而不是等用户发现界面错位。
+ *
+ * 只读：拉一次 index.html 和它引用的 CSS，做纯字符串匹配。
+ */
+
+import { request } from 'node:http'
+
+/** 外壳依赖的类名前缀（对应 lib/client.js 里的选择器）。 */
+export const SHELL_MARKERS = ['wSkVaW_', 'hHd-Xa_', 'uV2eYG_', 'pXSMma_', 'pI_x6G_']
+
+/**
+ * @param {{ port: number, token: string, host?: string, timeoutMs?: number }} options
+ * @returns {Promise<{ ok: boolean, missing: string[], asset?: string, reason?: string, checkedAt: number }>}
+ */
+export async function checkShellContract({ port, token, host = '127.0.0.1', timeoutMs = 4000 }) {
+	const checkedAt = Date.now()
+	const base = `http://${host}:${port}`
+	// DSH 的令牌是「先 303 种 Cookie，再访问首页」两步走，这里手工跟一次
+	const login = await requestText(`${base}/?token=${encodeURIComponent(token)}`, { timeoutMs })
+	const cookie = login.cookie
+	if (cookie === undefined) return { ok: false, missing: [...SHELL_MARKERS], reason: 'login-failed', checkedAt }
+	const html = await requestText(`${base}/`, { timeoutMs, cookie })
+	if (html.body === undefined) return { ok: false, missing: [...SHELL_MARKERS], reason: 'index-unreachable', checkedAt }
+	// 页面通常引多个 CSS（vendor + 业务），挂点类名在业务那个里，所以全取回来一起看
+	const assets = [...html.body.matchAll(/href="\.?\/?(assets\/[^"']+\.css)"/g)].map((m) => m[1])
+	if (assets.length === 0) return { ok: false, missing: [...SHELL_MARKERS], reason: 'no-css-asset', checkedAt }
+	let css = ''
+	let matched
+	for (const asset of assets) {
+		const body = await requestText(`${base}/${asset}`, { timeoutMs, cookie })
+		if (body.body === undefined) continue
+		css += body.body
+		if (matched === undefined && SHELL_MARKERS.some((marker) => body.body.includes(marker))) matched = asset
+	}
+	if (css === '') return { ok: false, missing: [...SHELL_MARKERS], reason: 'css-unreachable', checkedAt }
+	const missing = SHELL_MARKERS.filter((marker) => !css.includes(marker))
+	return { ok: missing.length === 0, missing, asset: matched ?? assets[0], assets, checkedAt }
+}
+
+/**
+ * 简单 GET：返回 { body, cookie }，超时/失败给 undefined。
+ * 体检不该把状态接口带崩，所以这里不抛异常。
+ */
+function requestText(url, { timeoutMs, cookie } = {}) {
+	return new Promise((resolve) => {
+		const headers = cookie === undefined ? {} : { cookie }
+		const req = request(url, { method: 'GET', headers, timeout: timeoutMs }, (res) => {
+			const jar = (res.headers['set-cookie'] ?? []).map((entry) => entry.split(';')[0]).join('; ')
+			if ((res.statusCode ?? 500) >= 400) {
+				res.resume()
+				resolve({ cookie: jar === '' ? undefined : jar })
+				return
+			}
+			let body = ''
+			res.setEncoding('utf8')
+			res.on('data', (chunk) => {
+				body += chunk
+			})
+			res.on('end', () => resolve({ body, cookie: jar === '' ? undefined : jar }))
+		})
+		req.on('timeout', () => {
+			req.destroy()
+			resolve({})
+		})
+		req.on('error', () => resolve({}))
+		req.end()
+	})
+}

package/lib/index.js

@@ -110,6 +110,7 @@ export function syncAppAssets(dir = join(homedir(), '.dsh', 'remote-panel-app'))
 			/* 缺某个尺寸不算致命 */
 		}
 	}
+	writeLandingPage(dir)
 	const ca = localCaPath()
 	if (ca !== undefined) {
 		try {
@@ -131,23 +132,52 @@ export function syncAppAssets(dir = join(homedir(), '.dsh', 'remote-panel-app'))
  * @param {string|undefined} token 当前进程的 DSH 令牌
  * @param {string|undefined} accessKey 门禁口令
  */
-export function writeGoPage(dir, token, accessKey) {
-	const target =
-		token === undefined || !accessKey
-			? '/'
-			: `/pair?k=${encodeURIComponent(accessKey)}&token=${encodeURIComponent(token)}`
+/**
+ * 写 `/remote-panel/login` 背后的跳转页（由 Caddy 放在门禁之后发送）。
+ *
+ * 之前这个页面放在免鉴权的 `/remote-panel/app/go.html` 里，等于把当前进程的令牌
+ * 暴露给网内任何人——口令门禁被绕过。现在令牌只在通过门禁之后才能拿到：
+ *
+ *   扫码 / 点链接 → /pair?k=口令（种 Cookie） → /remote-panel/login（要 Cookie） → /?token=
+ *
+ * @param {string} dir 资源目录
+ * @param {string|undefined} token 当前进程的 DSH 令牌
+ * @returns {string} 跳转目标
+ */
+export function writeLoginPage(dir, token) {
+	const target = token === undefined ? '/' : `/?token=${encodeURIComponent(token)}`
 	const html =
 		'<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
 		`<title>DSH</title><meta http-equiv="refresh" content="0;url=${target}">` +
 		'<style>html,body{height:100%;margin:0;background:#000;color:#888;font:14px system-ui;display:flex;align-items:center;justify-content:center}</style>' +
 		'<p>正在进入 DSH…</p>' +
-		// ?fps=1 时把开关记进 sessionStorage，跳转后由客户端插件读取（用于真机性能排查）
+		// ?fps=1 时把开关记进 sessionStorage，跳转后由客户端插件读取（真机性能排查用）
 		'<script>try{if(/[?&]fps=1/.test(location.search))sessionStorage.setItem("dsh-fps","1")}catch(e){}' +
 		`location.replace(${JSON.stringify(target)})</script>`
-	writeFileSync(join(dir, 'go.html'), html)
+	writeFileSync(join(dir, 'login.html'), html)
 	return target
 }
 
+/**
+ * 旧版手机壳的入口页：不再带任何凭据，只提示升级。
+ *
+ * v0.2.x 的 APK 启动地址是这里；那些版本会把令牌写在本页里（安全缺陷），
+ * 所以直接停用，让页面告诉用户装新版壳。
+ */
+export function writeLandingPage(dir) {
+	const html =
+		'<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
+		'<title>DSH</title>' +
+		'<style>html,body{height:100%;margin:0;background:#000;color:#ddd;font:14px system-ui;display:flex;align-items:center;justify-content:center;padding:24px;text-align:center}</style>' +
+		'<div><p style="font-size:16px;font-weight:600;margin:0 0 8px">手机壳需要更新</p>' +
+		'<p style="color:#888;margin:0">旧版入口已停用（安全升级）。<br>请在浏览器打开面板重新下载 DSH 壳。</p></div>'
+	try {
+		writeFileSync(join(dir, 'go.html'), html)
+	} catch {
+		/* 目录不可写就算了 */
+	}
+}
+
 /**
  * 注入 index 的 head 行：主题色 + iOS 独立窗口 + 桌面图标 + 我们自己的 manifest。
  *
@@ -339,7 +369,7 @@ routes.set('GET /pair', async ({ req }) => {
 	const scheme = requestScheme(req) === 'https' || detectTls() ? 'https' : 'http'
 	try {
 		const dir = join(homedir(), '.dsh', 'remote-panel-app')
-		if (existsSync(dir)) writeGoPage(dir, token, state.accessKey)
+		if (existsSync(dir)) writeLoginPage(dir, token)
 	} catch {
 		/* 目录还没建好就算了 */
 	}
@@ -455,6 +485,17 @@ routes.set('GET /probe', async ({ probe: runProbe = probe }) => {
 	return { ok: true, state, probe: await runProbe(state, { tls: detectTls() }) }
 })
 
+/** 客户端上报的外壳挂点自检结果（内存里保留最近一次）。 */
+let lastShellReport = null
+
+routes.set('POST /shell', async ({ req }) => {
+	const body = await readJson(req)
+	const missing = Array.isArray(body?.missing) ? body.missing.filter((item) => typeof item === 'string') : null
+	if (missing === null) throw new BadRequest('missing 必须是字符串数组')
+	lastShellReport = { ok: missing.length === 0, missing, checkedAt: Date.now() }
+	return { ok: true, ...lastShellReport }
+})
+
 routes.set('GET /status', ({ query }) => {
 	const tlsEnabled = detectTls()
 	return {
@@ -467,6 +508,8 @@ routes.set('GET /status', ({ query }) => {
 		scheme: tlsEnabled ? 'https' : 'http',
 		// 轻量证书信息：只读最近一次 /probe 的缓存，不在 status 里做网络探测
 		tls: tlsStatus(tlsEnabled, lastCertSnapshot()),
+		// 手机外壳的挂点自检：客户端启动后上报一次，用来说明「DSH 升级后样式还对不对得上」
+		shell: lastShellReport,
 		echo: query.get('echo') ?? null,
 	}
 })
@@ -525,7 +568,7 @@ export function apply(ctx) {
 				const state = readState()
 				const ports = [Number(state?.port) || 8710, Number(state?.upstream) || 3080]
 				const tokens = await findTokens({ ports })
-				writeGoPage(appDir, tokens.at(-1), state?.accessKey)
+				writeLoginPage(appDir, tokens.at(-1))
 			} catch (error) {
 				console.warn('[remote-panel] write go.html failed', error)
 			}

package/lib/pair.js

@@ -98,13 +98,13 @@ export function pairingUrls({ ip, port, accessKey, token, scheme = 'http' }) {
 	return {
 		gate,
 		token: tokenUrl,
-		// 一张二维码走完两步：先种门禁 Cookie，再由 Caddy 转发到令牌地址
+		// 登录入口：受门禁保护，Caddy 直接发一份带当前令牌的跳转页。
+		// 二维码只带门禁口令，口令换来的 Cookie 才能打开它——令牌不落在二维码/链接里。
+		login: `${base}/remote-panel/login`,
+		// 一张二维码走完两步：先种门禁 Cookie，再由 Caddy 转发到登录入口
 		// 走专用路径：Caddy 会回一个同源页面，由它发起跳转——
 		// 跨站导航不会携带 SameSite=Strict 的 DSH Cookie，非要同源页面自己发起才行
-		combo:
-			accessKey !== undefined && token !== undefined
-				? `${base}/pair?k=${accessKey}&token=${token}`
-				: undefined,
+		combo: accessKey !== undefined ? `${base}/pair?k=${accessKey}` : undefined,
 	}
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-panel",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "DSH 远程访问控制面：部署向导、状态面板与一键配对（EasyTier + Caddy），数据面保持进程外。",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,7 +33,8 @@
     "dsh": ">=0.2.1-rc.3"
   },
   "scripts": {
-    "test": "node --test \"test/*.test.js\""
+    "test": "node --test \"test/*.test.js\"",
+    "e2e": "node test/e2e/shell.mjs"
   },
   "dependencies": {
     "qrcode": "^1.5.4"