@ntdgy/dsh-remote-bridge-plugin 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-remote-bridge contributors
+
+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

@@ -0,0 +1,105 @@
+# @ntdgy/dsh-remote-bridge-plugin
+
+DSH 插件半边 —— 跑在**私网 DSH 进程内**，主动出站连接公网网关。
+
+配合 [`@ntdgy/dsh-remote-relay`](https://www.npmjs.com/package/@ntdgy/dsh-remote-relay) 使用：
+浏览器 → 公网网关 → 这条出站长连接 → 你的私网 DSH。
+
+**私网 DSH 不监听任何公网端口，也没有隧道。**
+
+---
+
+## 安装
+
+```bash
+dsh plugin --profile web add @ntdgy/dsh-remote-bridge-plugin
+```
+
+> ⚠️ **0.1.0 是坏的**（缺 peerDependencies，装上 import 会直接失败），已标记 deprecated。
+> 正常情况下会解析到 0.1.1。若被 pnpm 的 `minimumReleaseAge` 挡住装到了旧的，
+> 请显式指定版本：
+>
+> ```bash
+> dsh plugin --profile web add @ntdgy/dsh-remote-bridge-plugin@0.1.1
+> ```
+
+---
+
+## 配置
+
+在 profile 目录的 `cordis.patch.yml` 里插入：
+
+```yaml
+- insert:
+    - id: remote-bridge
+      name: '@ntdgy/dsh-remote-bridge-plugin'
+      config:
+        relayUrl: wss://你的域名/agent
+        instanceId: my-dsh
+        instanceKey: '与网关侧 DSH_REMOTE_INSTANCE_KEYS 里完全一致的那串'
+```
+
+| 配置项 | 必填 | 说明 |
+|---|---|---|
+| `relayUrl` | ✅ | 网关地址，**结尾是 `/agent`**，生产环境必须 `wss://` |
+| `instanceId` | ✅ | 本实例标识，必须与网关的 `DSH_PROXY_INSTANCE` 一致 |
+| `instanceKey` | ✅ | 与网关共享的 HMAC 密钥，必须与 `DSH_REMOTE_INSTANCE_KEYS` 里的一致 |
+| `reconnectBaseMs` | — | 重连初始退避，默认 3000 |
+| `reconnectMaxMs` | — | 重连退避上限，默认 60000 |
+
+### 关于 `ws://`
+
+用 `ws://` 时插件仍会连接，但每次启动会打一条醒目告警：
+
+> relayUrl uses ws:// (plaintext): the HMAC handshake can be bypassed by a man-in-the-middle.
+
+原因：明文链路上，中间人可以替换 nonce 与签名，那样"认证通过"只是假象。
+本机联调或前面有 TLS 终结时可以用，公网直连不行。
+
+---
+
+## DSH 启动必须带 `--trusted-host`
+
+```bash
+dsh web --host 127.0.0.1 --port 3080 --trusted-host 你的域名
+```
+
+**漏了这条的症状很坑**：首页 200、页面骨架能渲染，但**所有 `/api/*` 返回 403**。
+不是启动报错，是运行时静默拒绝 —— 不写在这里，每个新用户都要重新踩一遍。
+
+---
+
+## 它做什么
+
+| 职责 | 说明 |
+|---|---|
+| 出站注册 | HMAC 挑战应答自证身份，不发送任何凭据 |
+| 窄 RPC 服务端 | 只响应白名单 method（`session.list` / `history` / `prompt` / `follow`），未知一律拒绝 |
+| 路径上报 | 把 DSH 实际注册的 HTTP 前缀报给网关，网关据此放行转发 |
+| 会话代持上报 | 上报已认证的 launch URL，让网关代持 DSH 会话（用户不必手输 `?token=`） |
+| 状态面板 | 在 DSH 侧边栏显示连接状态与断线原因 |
+
+**不做**的事：不转发任意 TCP、不建隧道、不读 DSH 的凭据文件。
+
+---
+
+## 依赖说明
+
+`peerDependencies` 里的四项由 **DSH 宿主提供**，本包不打包：
+
+- `@deepseek-ai/cordis` —— 插件基类与服务容器
+- `@deepseek-ai/dsh` —— 宿主，范围 `^0.2.1-rc.2`
+- `@deepseek-ai/schemastery` —— 配置 schema
+- `react` —— 客户端面板
+
+装上后 `pnpm peers check` 会报这四项 missing。**这是预期行为** ——
+它们由宿主在运行时提供，profile 里本来就不该有。判断标准是插件能不能加载，
+而不是这条警告在不在。
+
+---
+
+## 状态
+
+早期版本（0.1.x）。协议无版本协商字段，**请与网关保持同版本**。
+
+完整部署步骤见主仓库 README。许可证见 LICENSE。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ntdgy/dsh-remote-bridge-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "DSH host-side plugin: outbound registration and narrow RPC server",
   "type": "module",
   "main": "./lib/index.js",
@@ -46,16 +46,18 @@
   },
   "dependencies": {
     "@ntdgy/dsh-remote-proto": "^0.1.0",
-    "@deepseek-ai/schemastery": "^3.18.5",
     "ws": "^8.18.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/schemastery": "^3.18.5",
     "@types/node": "^22.19.0",
     "@types/ws": "^8.5.13"
   },
   "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
     "@deepseek-ai/dsh": "^0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.5",
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {
@@ -66,5 +68,18 @@
   "engines": {
     "node": ">=20.11.0",
     "dsh": "^0.2.1-rc.2"
-  }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://cnb.cool/ntdgy.top/dsh-remote.git",
+    "directory": "packages/bridge-plugin"
+  },
+  "keywords": [
+    "dsh",
+    "remote",
+    "gateway",
+    "websocket",
+    "tunnel-free"
+  ]
 }