dsh-remote-hub 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liaoguogang-hub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# DSH Remote — Android 远程控制器
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/liaoguogang-hub/dsh-remote-public)
+
+手机原生 App，直接控制电脑上的 **DeepSeek Harness (DSH)**。不是 WebView 套壳：
+Kotlin/Compose 直连 DSH 自带的 HTTP API + WebSocket 网关。
+
+这是**公共版**，与作者自用版的唯一差别：
+
+| | 自用版 | 本仓库（公共版） |
+|---|---|---|
+| 连接方式 | 局域网 / 自建中继 / 自定义 | 局域网 / **ngrok 隧道** / 自定义 |
+| 内置服务器地址 | 有 | **无** |
+| 内置登录凭证 | 有（30 天 cookie） | **无** |
+| 包名 | `com.dsh.remote` | `com.dsh.remote.ngrok`（可与自用版共存） |
+| 应用名 / APK | `DSH` / `DSH-Remote-v*.apk` | `DSH Remote` / `DSH Remote-v*.apk` |
+
+功能与 UI 与自用版 4.12.2 完全一致。
+
+## 下载手机端 App
+
+**DSH Remote v4.17.1** · Android 8.0 (API 26) 及以上 · 2.6 MB
+
+[⬇️ 下载 APK](https://github.com/liaoguogang-hub/dsh-remote-public/releases/download/v4.17.1/DSH-Remote-v4.17.1.apk) ·
+[全部版本](https://github.com/liaoguogang-hub/dsh-remote-public/releases)
+
+安装后应用名「DSH Remote」，包名 `com.dsh.remote.ngrok`（可与作者的 `DSH` 自用版共存）。
+手机端不通过 npm 分发——npm 包 `dsh-remote-hub` 是电脑侧的 DSH 插件，两者配合使用：
+
+```
+电脑：dsh plugin --profile desktop add dsh-remote-hub   → 起桥接 / 开隧道 / 签 Cookie
+手机：装上面这个 APK → 填电脑给出的地址与 Cookie → 连接
+```
+
+## 功能
+
+| 能力 | 状态 |
+|---|---|
+| 三种连接方式（局域网 / ngrok / 自定义），地址与凭证首次填写后本地保存 | ✅ |
+| 会话列表：搜索、排序（最近更新 / 手动）、归档筛选（隐藏 / 全部 / 仅归档） | ✅ |
+| 会话列表默认显示最近 10 条，「展开其余 N 个会话」每次 +5 | ✅ |
+| 长按会话：重命名 / 归档会话（或取消归档） | ✅ |
+| 发消息、逐字流式回复、随时中断 | ✅ |
+| 历史分页（「加载更早的消息」）与本地缓存（先显示上次内容再同步） | ✅ |
+| 模型选择（分组目录 + 切换） | ✅ |
+| 权限模式 | ⚠️ 只能读取当前值（DSH 未开放远程切换权限的接口） |
+| 自定义地址历史（点选填入 / 删除） | ✅ |
+
+## 三步连上（推荐：一键脚本）
+
+1. **电脑上双击 `connect.cmd`**（和 App 一起发布的文件）。
+   它会自动做四件事：起桥接 → 签发 30 天 Cookie → 尽量开公网隧道 → 打印结果。
+2. 等黑窗口打印出这两行：
+   - `DSH 地址: http://192.168.x.x:6300`（同一 WiFi，最快）
+   - `Cookie: dsh-auth-…`（已自动复制到剪贴板）
+   如果网络允许，还会多给一行公网地址 `https://xxx.trycloudflare.com`（人在外面时用）。
+3. **App 里选「自定义」档** → 把地址粘进「DSH 地址」框 → Cookie 粘进「Cookie」框 → 点连接。
+
+> 电脑端那个黑窗口要保持开着；关掉 = 断开手机。下次用重新双击一次，抄新的地址和 Cookie 即可。
+> 结果同时会写到同目录的 `connect-info.txt`。
+
+### 公网隧道说明
+
+脚本按这个顺序尝试，**局域网地址永远可用**，公网则尽力而为：
+
+| 情况 | 结果 |
+|---|---|
+| 装了 `ngrok` 且在 PATH 里 | 用 ngrok 开隧道 |
+| 有 `cloudflared`（脚本会自动找/下载）且 `api.trycloudflare.com` 可达 | 免费 trycloudflare 地址，免注册 |
+| 两者都不行（常见于受限网络） | 只给局域网地址，并提示需要自备内网穿透（cpolar / natapp / 花生壳 / 自建 frp） |
+
+### 用 ngrok 拿一个永久固定域名（可选，需注册）
+
+cloudflared 的免费 quick tunnel **每次重启地址都会变**；想要固定域名就用 ngrok 免费账号。
+
+
+![ngrok 注册要点：左栏三处](docs/ngrok-dashboard-annotated.png)
+
+上图红框就是全部要点：① Share Localhost ② Your Authtoken ③ Domains。
+
+**注册（约 2 分钟）**
+
+1. 打开 <https://dashboard.ngrok.com/get-started/setup>，在首页选 **Share Localhost**
+   （「Put your local app on a public URL」——它明确写着 *stable, auth-protected URL*）；
+2. 跟着 **Get started** 走完，进 dashboard 后取两样东西：
+   - **Authtoken**：左侧 `Getting Started` → `Your Authtoken`
+     <https://dashboard.ngrok.com/get-started/your-authtoken>
+   - **免费固定域名**：左侧 `Universal Gateway` → `Domains`，免费账号自带一个
+     `xxxx-yyyy.ngrok-free.app` <https://dashboard.ngrok.com/domains>
+3. 下载 ngrok 单文件（同样免安装、不需要管理员权限），放进 `tools\ngrok.exe`，或装到 PATH。
+
+**配置（只需一次）**
+
+```powershell
+tools\ngrok.exe config add-authtoken <你的 Authtoken>
+```
+
+然后双击 `connect.cmd`：它会自己发现 ngrok、问你一次固定域名（记在
+`%LOCALAPPDATA%\dsh-remote\ngrok-domain.txt`），之后每次都复用同一个地址。
+
+> - **Host 必须改写**：脚本用 `--host-header=127.0.0.1:1815`，否则 DSH 的信任栅栏会 403，
+>   而且 cookie 的 authority 对不上。
+> - **不要加 ngrok 的 Basic Auth**：App 是用 DSH 的签名 cookie 认证的，Basic Auth 会让每个
+>   API 调用先被 ngrok 拦下（401），App 连不上。安全性由 30 天签名的 cookie 保证。
+> - **免费额度**：约 40 连接/分钟、1 GB/月。App 是长连接 + 流式输出，日常够用；
+>   偶发断连多半是额度或连接数超限，可换付费或 cloudflared。
+
+### 自己下载 cloudflared（可选，单文件免安装、不需要管理员权限）
+
+脚本会优先在 `connect.cmd` 同目录、`tools\`、`%LOCALAPPDATA%\dsh-remote\` 等位置找
+`cloudflared.exe`；找不到才下载。想自己放一份，按下面来：
+
+```powershell
+# 1) 镜像优先：国内直连 GitHub 下 52 MB 基本必超时
+$url = "https://ghfast.top/https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe"
+# 官方直连（网络允许时）：
+# $url = "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe"
+
+$dest = "tools\cloudflared.exe"
+New-Item -ItemType Directory -Force -Path (Split-Path $dest) | Out-Null
+Invoke-WebRequest -Uri $url -OutFile $dest -TimeoutSec 300 -UseBasicParsing
+
+# 2) 一定要验签：镜像可能给错文件，但签名伪造不了
+Get-AuthenticodeSignature $dest | Format-List Status, SignerCertificate
+```
+
+合格标准：`Status = Valid`，`Subject` 里含 `Cloudflare, Inc.`。
+参考值（2026.10.5 版）：`55,343,328` 字节，
+SHA256 `DB4E4C413612A0916F3E1679D3CAAF376F94911952D163028FB726FB2E0516A9`。
+
+> 脚本自己下载时也会做同样的验签（`Get-AuthenticodeSignature` + 主体含 Cloudflare），
+> 校验不过就丢弃并换下一个源 —— **不要用哈希对比代替验签**，镜像可以把哈希一起改掉。
+
+### 手工方式（想自己控制时）
+
+```bash
+node lan-proxy.mjs 6300 127.0.0.1:1815     # 桥接：把 Host 改写成 DSH 认可的 127.0.0.1:1815
+ngrok http 6300 --host-header=127.0.0.1:1815   # 或 cloudflared tunnel --url http://127.0.0.1:6300
+node mint.mjs "127.0.0.1:1815" 30              # 签发 30 天 Cookie
+```
+
+```text
+浏览器打开 DSH 页面 → F12 → Application → Cookies → 复制会话 cookie
+  （cookie 只对签发时的 authority 有效，所以桥接必须改写 Host 到同一个值）
+```
+
+## 安全说明
+
+- **本仓库不包含任何地址、Token 或 Cookie**：`DshDefaults.kt` 里全是空字符串，首次连接在 App 里填。
+- **Cookie 由你自己的电脑签发**：脚本用 `~/.dsh/.credentials.yaml` 里的密钥签一个 30 天有效的凭据，
+  只在你自己机器和手机之间流动，不要提交到任何仓库。
+- **局域网默认是明文 HTTP**：`lan-proxy.mjs` 监听 `0.0.0.0:6300`，同一 WiFi 内 Anyone 能访问它，
+  所以请只在可信网络里用局域网模式；要跨网请用 ngrok / cloudflared 这类带 TLS 的隧道。
+- **App 允许明文与用户证书**（`network_security_config.xml`）：DSH 通常跑在明文 HTTP 上，
+  自签 CA 的中转也要能信任；代价是它不会阻止你连明文地址，所以地址来源要自己把关。
+- **别把 ngrok 的 Basic Auth 和 DSH 的 Cookie 混用**：App 只带 DSH 的 Cookie，
+  Basic Auth 会让每个请求先被隧道 401 拦掉。
+
+## 构建
+
+```bash
+./gradlew assembleRelease      # 产物：dist/DSH Remote-v<version>.apk
+```
+
+需要 JDK 17 与 Android SDK（`local.properties` 指向本机 SDK）。
+
+## 版本
+
+当前 `4.12.2`（versionCode 58），与自用版 4.12.2 功能一致。
+
+## 作为 DSH 插件安装（推荐）
+
+本仓库根目录同时是一个 **DSH plugin**（Node 侧），装进 DSH 后由宿主负责起桥接、开隧道、签 Cookie，
+并把地址与 Cookie 写进 `~/.dsh/dsh-remote/`，手机 App 直接抄。
+
+```bash
+# 从 NPM 安装（推荐，会出现在 DSH 内的「插件中心」）
+# https://www.npmjs.com/package/dsh-remote-hub
+dsh plugin --profile desktop add dsh-remote-hub
+dsh plugin --profile web add dsh-remote-hub      # web profile 同样可用
+
+# 或直接从本仓库源码安装（不经过 NPM）
+dsh plugin --profile web add github:liaoguogang-hub/dsh-remote-public
+```
+
+装完重启 `dsh web`（或桌面端），插件会自动：
+
+1. 起桥接：`0.0.0.0:6300`，把 Host 改写成 `127.0.0.1:1815`（Cookie 因此不会因端口变化失效）；
+2. 自动发现 DSH 宿主端口（宿主每次重启都换端口，插件每次失败会重新扫一遍）；
+3. 开隧道：**有 ngrok 就用 ngrok**（固定域名），否则自动下载并验签 cloudflared 开免注册 quick tunnel；
+4. 签发 30 天 Cookie，写到 `~/.dsh/dsh-remote/status.json` 与 `connect.txt`。
+
+查看结果：
+
+```bash
+dsh-remote qr         # 打开配对页（二维码），手机扫一下就自动填好
+dsh-remote status     # 局域网地址、公网地址、Cookie、上游端口
+dsh-remote connect    # 直接打印要抄进手机的两行
+dsh-remote doctor     # 逐项自检：凭据、ngrok、cloudflared、宿主端口
+dsh-remote start      # 不开 DSH 也能单独前台跑（Ctrl+C 退出）
+```
+
+插件配置（profile 行里覆盖即可）：
+
+| 键 | 默认 | 作用 |
+|---|---|---|
+| `enabled` | `true` | 关掉插件但不卸载 |
+| `port` | `6300` | 桥接监听端口（手机连这个） |
+| `authority` | `127.0.0.1:1815` | 桥接呈现的 Host，Cookie 绑定它 |
+| `tunnel` | `auto` | `auto` / `off` / `ngrok` / `cloudflared` |
+| `upstreamPort` | `0` | 固定 DSH 宿主端口，`0` 表示自动发现 |
+
+> 公网隧道受网络影响：`api.trycloudflare.com` 不可达时插件会跳过公网、只给局域网地址，
+> 并在 `status.json` 里写明原因，不会假装成功。
+
+### 扫码配对（一次性配对码）
+
+不想手抄 Cookie 就用二维码：
+
+```bash
+dsh-remote qr
+```
+
+浏览器会打开 `http://127.0.0.1:6300/_dsh-remote/pair`，显示一个二维码。手机 DSH Remote 里点
+「扫码配对」，扫完自动填入地址并换取登录凭据，直接连上。
+
+安全设计：
+- 二维码里**不含 Cookie**，只含一个 **10 分钟有效的一次性配对码**（`{"v":1,"u":"<地址>","c":"<配对码>","e":<过期时间>}`）；
+- 兑换成功即作废，截图/偷拍泄漏的是一个立刻失效的码，而不是 30 天访问权；
+- 配对码只存在内存里，插件重启即全部失效（失效安全）。
+
+端点（都在桥接上，不经 DSH）：
+
+| 方法 | 路径 | 作用 |
+|---|---|---|
+| GET | `/_dsh-remote/pair` | 配对页（二维码 HTML） |
+| GET | `/_dsh-remote/pair.svg` | 只要二维码 SVG |
+| POST | `/_dsh-remote/pair/redeem` | `{code}` → `{url, cookie}`；用过即失效 |

package/bin/dsh-remote.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * dsh-remote CLI — inspect or drive the bridge/tunnel without the DSH UI.
+ *
+ *   dsh-remote status      show LAN URL, public URL, cookie and upstream port
+ *   dsh-remote connect     print the two lines to paste into the phone
+ *   dsh-remote cookie      print only the cookie
+ *   dsh-remote start       run the supervisor in the foreground (Ctrl+C stops it)
+ *   dsh-remote stop        ask a foreground `start` to stop (best effort, via status file)
+ *   dsh-remote doctor      check every prerequisite in one pass
+ *   dsh-remote qr          open the pairing page (QR) in the default browser
+ *
+ * @module bin/dsh-remote
+ */
+
+import fs from 'node:fs'
+import { execFile } from 'node:child_process'
+import os from 'node:os'
+import path from 'node:path'
+
+import { credentialsPath, mintCookie, readSigningSecret } from '../lib/cookie.js'
+import { listeningPorts, probePort } from '../lib/discover.js'
+import { findCloudflared, findNgrok } from '../lib/tunnel.js'
+import { CONNECT_FILE, STATUS_FILE, readStatus, start } from '../lib/supervisor.js'
+
+const args = process.argv.slice(2)
+const command = args[0] || 'status'
+
+function fmtTime(ms) {
+  if (!ms) return '?'
+  const d = new Date(ms)
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}
+
+function printStatus() {
+  const status = readStatus()
+  if (!status) {
+    console.log('还没有运行记录。先运行： dsh-remote start')
+    return
+  }
+  const remaining = status.cookieExpiresAt ? Math.round((status.cookieExpiresAt - Date.now()) / 86400000) : null
+  console.log('')
+  console.log('  DSH Remote 状态')
+  console.log('  ' + '-'.repeat(52))
+  console.log(`  局域网地址   ${status.lan?.url ?? '(未检测到局域网 IP)'}`)
+  console.log(`  公网地址     ${status.public?.url ?? `无（${status.public?.note ?? '未开启'}）`}`)
+  console.log(`  桥接端口     ${status.bridgePort}`)
+  console.log(`  DSH 上游     ${status.upstreamPort ? '127.0.0.1:' + status.upstreamPort : '未找到'}`)
+  console.log(`  更新时间     ${new Date(status.updatedAt).toLocaleString()}`)
+  if (status.bridgePort) console.log(`  扫码配对     dsh-remote qr   （或 http://127.0.0.1:${status.bridgePort}/_dsh-remote/pair）`)
+  if (status.cookie) {
+    console.log(`  Cookie 到期  ${fmtTime(status.cookieExpiresAt)}${remaining !== null ? `（还剩 ${remaining} 天）` : ''}`)
+    console.log('')
+    console.log('  把下面两样填进手机 App：')
+    console.log(`    地址   ${status.public?.url ?? status.lan?.url ?? ''}`)
+    console.log(`    Cookie ${status.cookie}`)
+  } else if (status.error) {
+    console.log(`  错误   ${status.error}`)
+  }
+  console.log('  ' + '-'.repeat(52))
+  console.log('')
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  return new Promise((resolve) => {
+    execFile(cmd, args, { windowsHide: true }, () => resolve())
+  })
+}
+
+async function qrCommand() {
+  const status = readStatus()
+  const port = status?.bridgePort ?? Number(process.env.DSH_REMOTE_PORT || 6300)
+  const page = `http://127.0.0.1:${port}/_dsh-remote/pair`
+  console.log('')
+  console.log('  配对页：', page)
+  console.log('  用手机 DSH Remote 的「扫码配对」扫屏幕上的二维码（10 分钟内有效，只能用一次）')
+  console.log('')
+  if (process.argv.includes('--no-open')) {
+    console.log('  （--no-open：未自动打开浏览器）')
+    return
+  }
+  await openBrowser(page)
+}
+
+async function doctor() {
+  console.log('')
+  console.log('  dsh-remote 自检')
+  console.log('  ' + '-'.repeat(52))
+  const cred = credentialsPath()
+  let secret = null
+  try {
+    secret = readSigningSecret(cred)
+    console.log(`  ✔ 凭据文件        ${cred}`)
+  } catch (err) {
+    console.log(`  ✘ 凭据文件        ${err.message}`)
+  }
+  const ngrok = findNgrok()
+  console.log(`  ${ngrok ? '✔' : '·'} ngrok          ${ngrok ?? '未安装（可选，有则优先用固定域名）'}`)
+  const cf = findCloudflared()
+  console.log(`  ${cf ? '✔' : '·'} cloudflared    ${cf ?? '未安装（首次运行会自动下载并验签）'}`)
+  if (secret) {
+    try {
+      const { cookie } = mintCookie('127.0.0.1:1815', { secret, days: 30 })
+      const bridgePort = Number(process.env.DSH_REMOTE_PORT || 6300)
+      const ports = (await listeningPorts()).filter((p) => p !== bridgePort)
+      let found = null
+      for (const p of ports) {
+        // eslint-disable-next-line no-await-in-loop
+        if (await probePort(p, { authority: '127.0.0.1:1815', cookie })) {
+          found = p
+          break
+        }
+      }
+      console.log(`  ${found ? '✔' : '✘'} DSH 宿主端口    ${found ? '127.0.0.1:' + found : '未找到（DSH 开着吗？）'}`)
+    } catch (err) {
+      console.log(`  ✘ 探测失败        ${err.message}`)
+    }
+  }
+  console.log('  ' + '-'.repeat(52))
+  console.log('')
+}
+
+async function main() {
+  switch (command) {
+    case 'status':
+      printStatus()
+      break
+    case 'connect':
+      if (fs.existsSync(CONNECT_FILE)) console.log(fs.readFileSync(CONNECT_FILE, 'utf8'))
+      else printStatus()
+      break
+    case 'cookie': {
+      const status = readStatus()
+      if (status?.cookie) console.log(status.cookie)
+      else {
+        const { cookie } = mintCookie('127.0.0.1:1815')
+        console.log(cookie)
+      }
+      break
+    }
+    case 'doctor':
+      await doctor()
+      break
+    case 'qr':
+    case 'pair':
+      await qrCommand()
+      break
+    case 'start': {
+      const handle = await start({ log: (m) => console.log(m) })
+      process.on('SIGINT', async () => {
+        await handle.close()
+        process.exit(0)
+      })
+      break
+    }
+    case 'stop':
+      console.log('前台运行的 dsh-remote 用 Ctrl+C 停止；插件模式下请在 profile 设置里关闭该插件。')
+      break
+    default:
+      console.log(`未知命令：${command}`)
+      console.log('可用：status | connect | cookie | qr | doctor | start | stop')
+      process.exitCode = 1
+  }
+}
+
+main().catch((err) => {
+  console.error(err?.stack ?? String(err))
+  process.exitCode = 1
+})

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# Bundle patch layer for the dsh-remote plugin.
+#
+# One insert row mounts the Host half only: the plugin runs inside the DSH host process, starts
+# the Host-rewriting bridge and the tunnel from there, and writes the resulting URL + cookie to
+# ~/.dsh/dsh-remote/. There is no browser half — the phone talks to the bridge, not to the web UI.
+#
+# Every key below is overridable from a saved profile row:
+#   enabled        false disables the whole plugin without uninstalling it
+#   port           local bridge port the phone connects to on the LAN
+#   authority      Host header the bridge presents; the signed cookie is bound to it
+#   tunnel         "auto" (ngrok if found, else cloudflared), "off", "ngrok" or "cloudflared"
+#   upstreamPort   pin the DSH host port; 0 means discover it automatically
+- insert:
+    - id: dsh-remote
+      name: 'dsh-remote-hub'
+      config:
+        enabled: true
+        port: 6300
+        authority: '127.0.0.1:1815'
+        tunnel: 'auto'
+        upstreamPort: 0

package/lib/bridge.js

@@ -0,0 +1,213 @@
+/**
+ * Host-rewriting reverse proxy between the phone and the DSH host.
+ *
+ * Two invariants:
+ *
+ *  1. The cookie's audience is whatever Host DSH receives, so this proxy always presents a fixed
+ *     authority (`127.0.0.1:1815` by default). One signed cookie therefore keeps working across
+ *     host restarts and across every transport.
+ *  2. The upstream port moves, so forwarding never pins it: a failed request or a 5xx triggers a
+ *     re-resolve before the error reaches the phone (up to one retry).
+ *
+ * It also trims `/api/session/list`, which is the single heaviest payload the app pulls (every
+ * Session with its full projection set). The phone only renders title / permissions /
+ * modelSelection, so projecting it here cuts the wire body by roughly 8x.
+ *
+ * @module lib/bridge
+ */
+
+import http from 'node:http'
+import net from 'node:net'
+import zlib from 'node:zlib'
+
+import { handlePairing } from './pairing-routes.js'
+
+const LIST_PATH = '/api/session/list'
+
+function rewriteHeaders(headers, authority) {
+  const next = { ...headers }
+  delete next.origin
+  delete next.referer
+  next.host = authority
+  return next
+}
+
+/** Keep only the fields the Android app reads, from a `session/list` response body. */
+function trimSessionList(body) {
+  const doc = JSON.parse(body.toString('utf8'))
+  const items = doc?.result?.value?.items
+  if (!Array.isArray(items)) return null
+  doc.result.value.items = items.map((row) => {
+    const v = row?.projections?.values ?? row?.projections ?? {}
+    return {
+      sessionId: row.sessionId,
+      updatedAt: row.updatedAt,
+      running: row.running,
+      blank: row.blank,
+      origin: row.origin,
+      cwd: row.cwd,
+      projections: {
+        values: {
+          title: v.title,
+          permissions: v.permissions,
+          modelSelection: v.modelSelection,
+        },
+      },
+    }
+  })
+  return Buffer.from(JSON.stringify(doc), 'utf8')
+}
+
+/**
+ * Start the bridge.
+ *
+ * @param {object} options
+ * @param {number} options.listenPort
+ * @param {string} options.authority
+ * @param {{resolve: (force?: boolean) => Promise<number>, invalidate: () => void}} options.upstream
+ * @param {(msg: string) => void} [options.log]
+ * @returns {Promise<{close: () => Promise<void>, port: number}>}
+ */
+export function startBridge({ listenPort, authority, upstream, pairing = null, log = () => {} }) {
+  const forward = (req, res, attempt = 0) =>
+    new Promise((resolve) => {
+      upstream.resolve(attempt > 0).then((port) => {
+        if (!port) {
+          res.writeHead(502)
+          res.end('dsh-remote: no upstream found (is the DSH host running?)')
+          return resolve()
+        }
+        const headers = rewriteHeaders(req.headers, authority)
+        // DSH gzips on its own when it sees Accept-Encoding; the list needs plain JSON so it can
+        // be trimmed and re-compressed here.
+        const isList = req.url === LIST_PATH
+        if (isList) delete headers['accept-encoding']
+
+        const up = http.request({ host: '127.0.0.1', port, path: req.url, method: req.method, headers }, (r) => {
+          if (r.statusCode >= 500 && attempt === 0) {
+            r.resume()
+            upstream.invalidate()
+            return forward(req, res, attempt + 1).then(resolve)
+          }
+          const contentType = String(r.headers['content-type'] || '')
+          const clientWantsGzip = /gzip/i.test(String(req.headers['accept-encoding'] || ''))
+          const canRewrite = isList && r.statusCode === 200 && !r.headers['content-encoding']
+          if (!canRewrite || !/json/i.test(contentType)) {
+            res.writeHead(r.statusCode, { ...r.headers, 'x-dsh-remote-bridge': '1' })
+            r.pipe(res)
+            r.on('end', resolve)
+            return
+          }
+          const chunks = []
+          r.on('data', (c) => chunks.push(c))
+          r.on('end', () => {
+            const headersOut = { ...r.headers }
+            let body = Buffer.concat(chunks)
+            try {
+              const trimmed = trimSessionList(body)
+              if (trimmed) {
+                body = trimmed
+                delete headersOut['content-length']
+              }
+            } catch {
+              /* unexpected shape: pass the original body through */
+            }
+            headersOut['x-dsh-remote-bridge'] = '1'
+            if (clientWantsGzip && body.length >= 2048) {
+              const gz = zlib.gzipSync(body, { level: 6 })
+              headersOut['content-encoding'] = 'gzip'
+              headersOut['content-length'] = String(gz.length)
+              delete headersOut['transfer-encoding']
+              res.writeHead(r.statusCode, headersOut)
+              res.end(gz)
+            } else {
+              res.writeHead(r.statusCode, headersOut)
+              res.end(body)
+            }
+            resolve()
+          })
+          r.on('error', () => {
+            try {
+              res.destroy()
+            } catch {}
+            resolve()
+          })
+        })
+        up.on('error', () => {
+          if (attempt === 0) {
+            upstream.invalidate()
+            return forward(req, res, attempt + 1).then(resolve)
+          }
+          try {
+            res.writeHead(502)
+            res.end('dsh-remote: upstream unavailable')
+          } catch {}
+          resolve()
+        })
+        req.pipe(up)
+      })
+    })
+
+  const server = http.createServer((req, res) => {
+    // Pairing is served by the bridge itself: it must work before the phone has any credential,
+    // and it must NOT be proxied to DSH.
+    if (pairing && String(req.url || '').startsWith('/_dsh-remote/pair')) {
+      handlePairing({ req, res, current: pairing.current, store: pairing.store }).catch(() => {
+        try {
+          res.writeHead(500)
+          res.end('dsh-remote: pairing error')
+        } catch {}
+      })
+      return
+    }
+    forward(req, res).catch(() => {
+      try {
+        res.writeHead(502)
+        res.end('dsh-remote: internal error')
+      } catch {}
+    })
+  })
+
+  // WebSocket upgrades (session/follow) need the same Host rewrite, done by hand: a raw socket
+  // tunnel cannot reuse `http.request`.
+  server.on('upgrade', (req, socket, head) => {
+    upstream.resolve().then((port) => {
+      if (!port) {
+        socket.destroy()
+        return
+      }
+      const up = net.connect(port, '127.0.0.1', () => {
+        const headers = rewriteHeaders({ ...req.headers, connection: 'Upgrade', upgrade: req.headers.upgrade }, authority)
+        const lines = [
+          `GET ${req.url} HTTP/1.1`,
+          ...Object.entries(headers).map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : v}`),
+          '',
+          '',
+        ]
+        up.write(lines.join('\r\n'))
+        if (head?.length) up.write(head)
+        up.pipe(socket)
+        socket.pipe(up)
+      })
+      up.on('error', () => socket.destroy())
+      socket.on('error', () => up.destroy())
+    })
+  })
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(listenPort, '0.0.0.0', () => {
+      server.removeListener('error', reject)
+      log(`bridge listening on 0.0.0.0:${listenPort} (Host: ${authority})`)
+      resolve({
+        port: listenPort,
+        close: () =>
+          new Promise((done) => {
+            server.close(() => done())
+            // `close` waits for keep-alive sockets; drop them so shutdown is prompt.
+            server.closeAllConnections?.()
+          }),
+      })
+    })
+  })
+}