dsh-mini-remote 0.2.0 → 0.2.1

package/lib/mirror.js

@@ -38,6 +38,7 @@
  */
 import { request as httpRequest } from 'node:http'
 import { connect as netConnect } from 'node:net'
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
 import { gunzipSync, inflateSync, brotliDecompressSync } from 'node:zlib'
 
 /** 这些头是「逐跳」的，不该被转发（RFC 7230 §6.1）。 */
@@ -53,6 +54,31 @@ const HOP_BY_HOP = new Set([
  */
 const FRAME_BLOCKERS = new Set(['x-frame-options', 'content-security-policy'])
 
+/**
+ * **默认拒绝被嵌，只有持票的那一次放行**（2026-10-15）。
+ *
+ * `FRAME_BLOCKERS` 上面那条说的是「上游写死的禁止头要摘掉」；摘掉之后**由我们自己
+ * 定这一页许不许被嵌**。今天的两个用法不一样：
+ *
+ *   · **手机页那一层**（`lib/page.html` 的 `#mirrorFrame`）是**同源** iframe——
+ *     地址是相对的 `/mini/mirror/?token=…`，和手机页同一个 host:port；
+ *   · **DSH 桌面端那一层**（「远程窗口」面板）是**跨源又跨站**的 iframe——
+ *     桌面端自己的页面跑在自定义协议 `dsh-app://app/` 上（2026-10-15 实查 main.js：
+ *     `protocol.handle(SCHEME…)`、`assertMainApplication` 里那句 `dsh-app://app/`），
+ *     镜像则在 `http://127.0.0.1:<我们的端口>`。
+ *
+ * 所以默认这一条就给「只许同源」：手机页照常能嵌，别的站点一律嵌不进来。
+ * 跨源那一层要嵌，地址里必须带着**一次性票**（见下面 issueTicket/redeemTicket）——
+ * 票只有本机回环上的宿主那一半拿得到，所以「谁能嵌」由票决定，而不是由一份
+ * 源白名单决定（桌面端那一侧不是个 http 地址，白名单本来也无从写起）。
+ *
+ * 注意这两个头**不是**上游的头：上游那一份已经在 writeOut 里丢掉了。
+ */
+const FRAME_SELF_ONLY = {
+  'x-frame-options': 'SAMEORIGIN',
+  'content-security-policy': "frame-ancestors 'self'",
+}
+
 /**
  * 那条「受信任通道」的前缀。
  *
@@ -1052,6 +1078,88 @@ function injectHostHook(html, diag) {
   return inject + html
 }
 
+/**
+ * ## 窗口会话的寿命：**跟着这个宿主进程走**（2026-10-15 用户拍板）
+ *
+ * 原来写的是「12 小时」。那个数是凭空定的，而且会留下一种半死状态：面板开着超过
+ * 12 小时再刷新，服务器这边会话已经作废、浏览器里那枚 cookie 还在，用户看到的
+ * 是一条莫名其妙的 401。
+ *
+ * 现在**没有固定寿命**：进程一起来随机生成一串密钥（就是下面这个 `PROCESS_SECRET`），
+ * 每一枚窗口会话都用它**签**过，形状是 `v1.<随机串>.<签名>`。判定只有一条——
+ * **签名对不对**。换一个进程就是换一串密钥，于是**上一个进程签发的会话签名当场
+ * 对不上，一律不认**。
+ *
+ * 这样做的三个好处，正好对上用户提的三条：
+ *   · **不落盘**：密钥只活在这个进程的内存里，重启即失效，不需要扫磁盘；
+ *   · **不需要定时清理**：会话里根本没有「到期时刻」这种字段，也就没有清理任务；
+ *   · **不引入新的固定寿命**：寿命就是「这个进程活着」这一件事。
+ *
+ * ## 会话里还签着「这一扇窗是谁的」（2026-10-16 第四步）
+ *
+ * 光有签名只说明「**是本进程签的**」，**不认是哪台设备**。于是有一处撤不掉的洞：
+ * 把一台设备从名册里删掉之后，它**已经开着的那扇窗照旧能用**，一直到宿主重启为止。
+ * 所以身份要签进会话体里：`v1.<随机串>~<身份>.<签名>`。
+ *
+ * 身份是两样之一（由兑票那一下决定，见 lib/server.js 的 ticketWindowOwner）：
+ *   · **一台设备的 id**——名册里那条记录的 id（撤销就是删掉它，见 lib/devices.js）；
+ *   · **`local`**——本机那一半（桌面端面板走的就是这一条，见 lib/server.js）。
+ *
+ * **签名仍然只有进程密钥**：换一个宿主进程，旧会话的签名照样当场对不上（上面那三条
+ * 一个字都没变）。身份这一节**不是权限判据**——它只是让验完会话的人能**再回头查一次
+ * 名册**：记录还在不在，由 lib/server.js 的 windowSession 每次现查。
+ */
+const PROCESS_SECRET = randomBytes(32)
+const WINDOW_SESSION_VERSION = 'v1'
+
+/**
+ * 随机串和身份之间的分隔符。
+ *
+ * 挑 `~` 是因为 base64url 的字母表里没有它（`A-Za-z0-9-_`），所以切得干净；
+ * 也用不着转义——两侧都是我们自己生成的（`randomBytes(...).toString('base64url')`
+ * 和一个 16 字节随机数转的 hex，或者 `local`）。
+ */
+const SESSION_ID_SEP = '~'
+
+/**
+ * 签一枚窗口会话：`v1.<随机串>[~<身份>].<签名>`。
+ *
+ * @param {string} [deviceId] 这一扇窗是谁的：设备 id 或 `local`。
+ *        **给空就签一枚不带身份的会话**（老形状）；生产路径上不会出现——
+ *        lib/server.js 兑票那一下拿不到身份就干脆不兑现（见 ticketWindowOwner）。
+ */
+function mintWindowSession(deviceId) {
+  const nonce = randomBytes(32).toString('base64url')
+  const who = typeof deviceId === 'string' ? deviceId : ''
+  const body = `${WINDOW_SESSION_VERSION}.${who ? `${nonce}${SESSION_ID_SEP}${who}` : nonce}`
+  return `${body}.${createHmac('sha256', PROCESS_SECRET).update(body).digest('base64url')}`
+}
+
+/** 验一枚窗口会话：形状对，而且签名是**这个进程**签的。 */
+function windowSessionValid(value) {
+  if (typeof value !== 'string' || !value) return false
+  const parts = value.split('.')
+  if (parts.length !== 3 || parts[0] !== WINDOW_SESSION_VERSION) return false
+  const body = `${parts[0]}.${parts[1]}`
+  const expected = createHmac('sha256', PROCESS_SECRET).update(body).digest()
+  const given = Buffer.from(parts[2], 'base64url')
+  return given.length === expected.length && timingSafeEqual(given, expected)
+}
+
+/**
+ * 这枚窗口会话是**谁的**：设备 id、`local`、`''`（签出来的老形状，没带身份），
+ * 或者 `null`（形状不对/不是这个进程签的——**签名道理和 windowSessionValid 一样**）。
+ *
+ * **它本身不判权限**：签名对只说明「是本进程签的」。设备身份要拿去**回头查名册**
+ * （见 lib/server.js 的 windowSession）；记录不在了就当场拒——撤销靠的正是那一步。
+ */
+function windowSessionDevice(value) {
+  if (!windowSessionValid(value)) return null
+  const payload = value.split('.')[1]
+  const at = payload.indexOf(SESSION_ID_SEP)
+  return at < 0 ? '' : payload.slice(at + 1)
+}
+
 /**
  * 建一个镜像代理。
  *
@@ -1063,9 +1171,158 @@ function injectHostHook(html, diag) {
  *        由插件注入（见 lib/index.js 里对 connection.authenticatedUrl 的调用）——
  *        这个模块**不认识宿主**，只认识一个返回字符串的函数，好测。
  * @param {(msg:string) => void} [opts.log]
- * @returns {{ handle, reset, available, stats }}
+ * @returns {{ handle, upgrade, reset, available, stats, issueTicket, redeemTicket, windowValid, windowDevice, ticketOwner, ticketGranted, ticketTtlMs }}
  */
 export function createMirror({ upstream, tokenUrl, log }) {
+  /**
+   * 「远程窗口」的两样一次性的东西：**票**和**票换来的窗口会话**。
+   *
+   * ## 为什么要有票
+   *
+   * 桌面端的「远程窗口」面板要把这一层嵌进 iframe，而进这一层的凭据是我们的
+   * **令牌**。令牌一旦拼进 iframe 的地址，就会留在那台电脑的浏览历史里
+   * （参考插件 `dsh-remote-web-ui` 就栽在这上面）。所以改成两步：
+   *
+   *   ① 宿主那一半（本机回环上的软件）拿一张**一次性票**；
+   *   ② 浏览器带着票进一次门：票在那一刻兑现成一枚**窗口会话 cookie**（iframe 里
+   *      那些请求——静态资源、`/api/*`、WebSocket——全靠它认人），而票自己
+   *      **只授权那一次**。地址里留着的那张票随后只用来回答「这一页是我嵌出来的吗」
+   *      （取景政策靠它，别的什么都打不开，见 `ticketGranted`）。
+   *
+   * 为什么要留票在地址里：iframe 会重新加载同一条地址，而「许不许被跨源嵌」这件事
+   * 必须有个**cookie 之外**的判据——桌面端是跨站的，那枚 cookie 会被浏览器一路带着，
+   * 光靠它就等于任何站点都能把这一页嵌进自己的页面（见 lib/server.js 的取景政策）。
+   *
+   * ## 票的规矩（照设计稿：短命、一次性、用完即废）
+   *
+   *   · **短命**：30 秒。宿主拿到票到浏览器发出请求之间只差一次跳转，够用；
+   *   · **一次性**：`redeemTicket` 无论成败**先删再判**，并发来两次也只有一次能成；
+   *   · **换来的会话**：**没有固定寿命，跟着这个宿主进程走**（见上面 PROCESS_SECRET）。
+   *
+   * ## 票上还记着「这一扇窗是谁的」（2026-10-16 第五步）
+   *
+   * 跨机取票那条路上，**票是在对面那台电脑的浏览器里打开的**：那台浏览器
+   * **没有设备凭据**（凭据只活在对面那个宿主进程里，永远不进浏览器），也**不是本机回环**。
+   * 所以「兑票时看请求带了什么」这个判据在那条路上必然落空——身份只能在**发票那一刻**
+   * 定下来，跟着票一起交给兑票那一下（见 lib/server.js 的 ticketWindowOwner）。
+   *
+   * **记在服务端这张表里，不是签进票里**：票本身照旧是一串 256 位随机数，设备 id
+   * **不进对面浏览器的地址栏、不进浏览历史、也不进中间那几条链路的日志**——这条 URL
+   * 正是我们一直在防泄漏的那一处。而一次性本来就得靠服务端记住「这张票用过了」，
+   * 所以把主人寄存在这里**一个字节的状态都没多**。
+   *
+   * **窗口会话不是令牌**：它只够进镜像这一层（见 `lib/server.js` 里怎么用），
+   * 令牌始终没进过浏览器。
+   */
+  const TICKET_TTL_MS = 30_000
+  /** 两张表都不许无限长：正常情况下同时只有个位数条目。 */
+  const MAX_ENTRIES = 64
+
+  /**
+   * 还没兑现的票：`票 -> { expiresAt, owner }`。
+   *
+   * `owner` 就是**这一扇窗是谁的**（一台设备的 id，或者 `local`），由发票那一方当场
+   * 定下（见 lib/index.js 的两条取票路由）。**兑票那一下原样取回来用**：它不判权限，
+   * 名册那一关在 lib/server.js（每次放行都还要再查一次）。
+   */
+  const tickets = new Map()
+  const grants = new Set()    // 已经兑现过的票（只用于取景放行；进程一走就没了）
+
+  const randomId = () => randomBytes(32).toString('base64url')
+  const dropExpired = (map, now) => {
+    for (const [key, rec] of map) if (rec.expiresAt <= now) map.delete(key)
+  }
+
+  /**
+   * 发一张票（只可能是宿主那一半调用：本机的 `/mini-remote/window`、跨机的
+   * `/mini-remote/remote/window`，两条都在 lib/index.js）。
+   *
+   * @param {string} [owner] **这一扇窗是谁的**：本机那一半给 `local`，跨机那条给
+   *        刚验过的设备 id（见 lib/index.js 里两处的注释）。给空就发一张**无主的票**
+   *        ——它能被读到，但兑不出来（lib/server.js 定不下身份就不兑现，fail closed）。
+   */
+  function issueTicket(owner) {
+    const now = Date.now()
+    dropExpired(tickets, now)
+    if (tickets.size >= MAX_ENTRIES) tickets.delete(tickets.keys().next().value)
+    const ticket = randomId()
+    tickets.set(ticket, {
+      expiresAt: now + TICKET_TTL_MS,
+      owner: typeof owner === 'string' ? owner : '',
+    })
+    return ticket
+  }
+
+  /**
+   * 这张票是**谁的**——**只看一眼，不消费**（消费是 `redeemTicket` 那一下）。
+   *
+   * 回 `''`（无主的票）、回 `null`（这张票不在表里：没发过、已经兑现过、或者过期被清了）。
+   * **它本身不判权限**：lib/server.js 拿到之后还要按名册再查一次，本机那一半另外还要
+   * 求"这一下是这台电脑自己发的"。
+   *
+   * 为什么要留这么一口「只看不消费」：身份**定不下来**时（无主、或者那台设备刚被撤销）
+   * 票**不该被烧掉**——烧掉只让用户在网络抖一下之后白等 30 秒重新点一次，一个字节的
+   * 安全都换不来（同一条道理见 lib/index.js 那条「限速只查不记」）。
+   */
+  function ticketOwner(ticket) {
+    if (typeof ticket !== 'string' || !ticket) return null
+    const rec = tickets.get(ticket)
+    return rec ? rec.owner : null
+  }
+
+  /**
+   * 用票换窗口会话。**成不成这张票都不再能授权**（一次性）。
+   * 回 `{ session }`，票不对/过期/已经用过一律回 `null`。
+   *
+   * `deviceId` 是**这一扇窗是谁的**（设备 id 或 `local`），由调用方判——判据不在
+   * 这个模块里（它不认识名册，也不认识"回环"这件事，见 lib/server.js 的
+   * ticketWindowOwner）。**调用方照 `ticketOwner(ticket)` 读出来的那个值传进来就行。**
+   * **身份跟着会话一起被签**，所以它改不了：拿到会话的人没法把自己说成另一台设备
+   * （见上面 SESSION_ID_SEP 那一段）。
+   *
+   * 兑现过的那张票会被记进 `grants`：它**不再有任何进门的能力**，只用来回答
+   * 「这一页是我嵌出来的吗」（见 `ticketGranted`）。留着它是因为 iframe 会重新加载
+   * 同一条地址——那时靠它放行取景，靠窗口会话进门。
+   */
+  function redeemTicket(ticket, deviceId) {
+    if (typeof ticket !== 'string' || !ticket) return null
+    const rec = tickets.get(ticket)
+    // **先删再判**：并发拿同一张票来两次，第二次必然落空。
+    tickets.delete(ticket)
+    if (!rec || rec.expiresAt <= Date.now()) return null
+    if (grants.size >= MAX_ENTRIES) grants.delete(grants.values().next().value)
+    grants.add(ticket)
+    return { session: mintWindowSession(deviceId) }
+  }
+
+  /**
+   * 这张票是不是**我们发过、而且已经兑现过**的。
+   *
+   * 只用来定取景政策：**「只有带合法票的请求才放行被嵌」**（设计稿门 1）。
+   * 它本身什么都打不开——进门要的是窗口会话或者刚兑现的那一下。
+   * 这样别有用心的站点就算把 `http://127.0.0.1:<端口>/mini/mirror/` 嵌进自己的页面，
+   * 地址里没有票，取景政策就是「只许同源」，浏览器当场拒绝显示。
+   */
+  function ticketGranted(ticket) {
+    if (typeof ticket !== 'string' || !ticket) return false
+    return grants.has(ticket)
+  }
+
+  /**
+   * 这枚窗口会话还作不作数：**签名是这个进程签的**就算数（见 PROCESS_SECRET）。
+   *
+   * **它只管签名**：身份那一节要另外查名册，由 lib/server.js 的 windowSession
+   * 拿 windowDevice() 的返回值去查（撤销的当场失效就落在那里）。
+   */
+  function windowValid(session) {
+    return windowSessionValid(session)
+  }
+
+  /** 这枚窗口会话是**谁的**（设备 id / `local` / `''`），不是本进程签的就回 null。 */
+  function windowDevice(session) {
+    return windowSessionDevice(session)
+  }
+
   /** 上游地址**解析一次就记住**：它的 Host 要用来签 cookie，不能每次变。 */
   let target = null
   let targetHost = null
@@ -1197,6 +1454,14 @@ export function createMirror({ upstream, tokenUrl, log }) {
       if (HOP_BY_HOP.has(key)) continue
       // ② 我们自己那枚令牌的 cookie 不给上游；上游不认识它。
       if (key === 'cookie') continue
+      // ③ **我们自己的凭据，一个请求头都不给上游**（2026-10-16）。
+      //
+      // cookie 那条路早就断了（上面②），头这两条原来照原样转出去：手机页每一趟
+      // fetch 都带着 `X-Mini-Token`，设备身份那枚 `X-Mini-Device` 同理——
+      // 转出去就是**把口令写进上游的日志和链路**。上游压根不认识它们，
+      // 摘掉不影响任何功能（这是「凭据绝不跟着请求转发」那条规矩的前半截；
+      // 后半截在 lib/server.js 的 stripOurSecrets，管的是地址里那几个参数）。
+      if (key === 'x-mini-token' || key === 'x-mini-device') continue
       if (key === 'host') continue
       headers[key] = v
     }
@@ -1246,7 +1511,14 @@ export function createMirror({ upstream, tokenUrl, log }) {
     })
   }
 
-  function writeOut(upRes, res, reqUrl, diag) {
+  /**
+   * 把上游的响应发出去。
+   *
+   * `embed` = 「这一次是持票进来的」——由 `lib/server.js` 判定（票换来的窗口会话还在），
+   * 传到这里只做一件事：**决定这一页许不许被跨源嵌**（见 FRAME_SELF_ONLY）。
+   * 缺省是 false：正常路径（手机页那一层）一个字节都不变。
+   */
+  function writeOut(upRes, res, reqUrl, diag, embed) {
     const headers = {}
     for (const [k, v] of Object.entries(upRes.headers)) {
       const key = k.toLowerCase()
@@ -1257,6 +1529,12 @@ export function createMirror({ upstream, tokenUrl, log }) {
       headers[key] = v
     }
 
+    /**
+     * 取景政策：上游那一份（上面已丢掉）换成**我们自己的**。
+     * 不持票 = 只许同源（手机页那一层是相对地址，照常能嵌；桌面端跨源那一层要凭票）。
+     */
+    if (!embed) for (const [k, v] of Object.entries(FRAME_SELF_ONLY)) headers[k] = v
+
     // **给带内容指纹的静态资源补上长期缓存**（见 CACHEABLE 的说明）。
     // 只补「上游本来没给」的：它给了 `no-cache` 之类就尊重它，别去覆盖别人的判断。
     const path = String(reqUrl ?? '').split('?')[0]
@@ -1364,9 +1642,13 @@ export function createMirror({ upstream, tokenUrl, log }) {
    * `opts.diag` = 「这一页是诊断模式打开的」，由 `lib/server.js` 从 `?diag=1` 里读出来传进来
    * （查询串在入口那一下就被整个丢掉了，所以只能这么传，不能到这儿再自己解析）。
    * **缺省是关的**：正常路径注入的东西一个字节都不变。
+   *
+   * `opts.embed` = 「这一次是持票进来的」，同上由 `lib/server.js` 判定后传进来
+   * （票换来的窗口会话还作数就是 true）。**缺省 false**，取景政策回到「只许同源」。
    */
   async function handle(req, res, opts) {
     const diag = Boolean(opts && opts.diag)
+    const embed = Boolean(opts && opts.embed)
     try {
       await ensureCookie()
     } catch (err) {
@@ -1402,7 +1684,7 @@ export function createMirror({ upstream, tokenUrl, log }) {
       }
     }
 
-    writeOut(upRes, res, req.url, diag)
+    writeOut(upRes, res, req.url, diag, embed)
   }
 
   return {
@@ -1418,5 +1700,16 @@ export function createMirror({ upstream, tokenUrl, log }) {
     /** 上游会话可能会失效（例如 DSH 重启），提供一个显式作废的入口给测试和上层用。 */
     reset: () => { cookie = null },
     stats: () => ({ mints, lastError }),
+    // 「远程窗口」那一对：发票（只给宿主那一半）/ 用票换窗口会话 / 查窗口会话还作不作数 /
+    // 查这枚会话是哪台设备的（拿去回头查名册，见 lib/server.js）/ 查**这张票是谁的**
+    // （只看不消费，兑票那一下要先拿它定身份）/ 查这张票是不是兑现过的（取景政策用）。
+    issueTicket,
+    redeemTicket,
+    windowValid,
+    windowDevice,
+    ticketOwner,
+    ticketGranted,
+    /** 票能活多久。宿主要把这个数告诉界面半边（`expiresIn`），所以露出来。 */
+    ticketTtlMs: TICKET_TTL_MS,
   }
 }