dsh-remote-rea 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ccr-wer
+
+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,157 @@
-# Temporary Holding Version
+# dsh-remote-rea
 
-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.
+DSH（DeepSeek Harness）生态插件：**远程连接 + 逆向分析** —— 连上远程主机，定位/拉取目标文件，
+调用 REA（及其背后的 Ghidra / Hopper / IDA）做静态分析并回收结构化结果。
+
+**只分析、不利用**：本插件不执行目标、不注入、不改写工件、不做任何利用动作。所有远端命令都先过
+提权闸门（见「安全边界」）。
+
+## 三个工具
+
+| 工具 | 作用 | 关键入参 |
+|---|---|---|
+| `remote_hosts` | 主机库 CRUD：登记别名、认证方式、连通性 `test`、从 `~/.ssh/config` 导入 | `action` + `alias` … |
+| `remote_fetch_binary` | 预检（存在 / 大小 / 类型 / sha256）→ 拉取 → 本地复算 sha 比对 → 写 JSON 报告 | `alias`、`remotePath`（绝对路径） |
+| `remote_rea_analyze` | 拉取之后探测能力面、选 provider/operation、下发分析子命令、Evidence 落盘并出摘要 | `alias`、`remotePath`、可选 `provider` |
+
+用之前必须先在 `remote_hosts` 里有别名 —— 主机库是这两个分析工具的前置条件，本插件不读任何外部口令。
+
+`remote_rea_analyze` 不指定 `provider` 时自动路由，选路范围是
+「REA 广告面 ∩ 已用 `--help` 核对过绑定的子命令」，两者取交集，缺一个就不下发。
+
+## 支持范围
+
+| 层面 | 支持 | 不支持时的行为 |
+|---|---|---|
+| 宿主 OS | Windows / macOS / Linux | 不可能不支持（`ssh2` 是纯 JS 实现，原生加速模块可选） |
+| 宿主 Node | `>=18`（建议 20+） | 由 `package.json` 的 `engines.node` 声明；安装器告警，本插件自身不做版本检查 |
+| 远程 OS | POSIX shell（Linux / macOS） | 运行时探测 `uname -s`，命中 `MINGW*`/`MSYS*`/`CYGWIN*`/`Windows*` 直接拒：`不支持的目标平台：Windows 远端，请使用 POSIX shell 目标` |
+| 远程 Node | 22.19+ / 24.11+ / 26+（不支持 23 和 25） | 走 npx 前先探 `node --version`，不达标报一句话：`远端 <版本>；REA 要求 Node 22.19+ / 24.11+ / 26+（不支持 23 和 25）`，且**不下发任何 rea 命令** |
+| 远程工具 | GNU coreutils，或可降级的子集 | 见下面「预检的降级路径」，每条都有兜底而不是直接失败 |
+
+> 宿主 Node 的 `>=18` 是声明值，未在 18 上实测：本项目的开发/回归环境只有 Windows 侧 node 24.x
+> 与 WSL 侧 node 22.22.1。用到的语法（ESM、可选链、空值合并、`node:` 前缀内置模块）都在 18 以内。
+
+### 预检的降级路径
+
+- `stat -c %s` 拿不到大小（BSD/macOS 的 `stat` 不认 `%s`）→ 退回 `wc -c <`；两条都失败 → `sizeBytes=null`。
+- `file -b` 失败 → `fileType=null`，路由降级为「按扩展名猜类别」，note 里写明「未经格式头证实」；
+  扩展名也认不出来就报 `未知类型：file -b 没有输出、扩展名也认不出来；深度分析需指定 provider`。
+- 远端既没有全局 `rea` 也没有 `npx` → `远端无 npx，请安装 Node.js 22.19+ 或全局安装 rea`。
+- 符号链接：`file -b` 回的是 `symbolic link to …`，而 `stat -c %s` 给的是链接字符串长度、
+  `sha256sum`/SFTP 跟随目标 —— 所以链接目标的 `sizeMatches=null` + `sizeSkippedForSymlink=true`，**sha 才是权威**。
+
+## 已知限制
+
+- **Ghidra 路径已接，未实装验证。** 绑定表见 `rea-provider-router.js` 的 `GHIDRA_BINDINGS`（5 条，
+  只有 `--help` 证据、没有任何一次真机跑通），因此**不参与自动选路**，只在调用方显式
+  `provider:"ghidra"` 且 REA readiness 判它可用时才走。要实装需自备 **Ghidra 12.1.x** 解包目录并把
+  `GHIDRA_INSTALL_DIR` 指过去，外加 **JDK 21**（便携 JDK 也行，只要 PATH 上有 `java`）。
+- **`analyze-javascript-application` 不在 capabilities 广告面**（providers / capabilities / doctor 三处都没有它），
+  作为带标记的**手工例外**接入：`surface='manual-exception'`、`marker='manual-exception:not-advertised'`。
+  它的 effects 是空的 —— 也就是「读文件还是写文件系统」REA 自己没说，本项目也不替它猜。
+- **`rea-artifact-graph` 只做 inventory，`findings=0` 是结构性的**，不是「这个二进制很干净」：它的 Evidence
+  方言里没有 `semantic_graph`，摘要层的 `dialect` 计数会把 `unexplored_branches` / `next_probes` 原样透传，
+  深度要靠 Ghidra 那一条路。
+- **冷缓存预热可能 50s 到 10 分钟不等**，取决于网络。实测区间 50–83s，但同一条路出现过 120s、420s，
+  以及 2026-10-17 在 WSL 上实测的 **534s**（清缓存后用默认预算跑通整链）。`npxTimeoutMs` 因此定为 600000，
+  可按调用覆盖。
+- **`doctor` 原文不是字节稳定的**：`identity.installations.paths[0]` 会随 npx 缓存位置变化，所以本项目
+  不对 doctor 原文做逐字节断言，只按 evidence_id / 字段取用。
+- **`@latest` 可能漂移**：`npx --yes rea-agents@latest` 每次解析到的版本可能不同。遇到缓存或行为对不上，
+  可把远端命令手动锁成 `rea-agents@<版本>`。
+- **`pnpm peers check` 的 missing peer 是静态误报**：DSH profile 的 `pnpm-workspace.yaml` 设了
+  `autoInstallPeers: false`，pnpm 只看 profile 自己的 `package.json`，看不到上层
+  `profiles/node_modules/@deepseek-ai/`，于是报 `@deepseek-ai/dsh-tools` / `@deepseek-ai/cordis` 缺失。
+  实测：那两个 peer 由 DSH 运行时自带 —— `profiles/node_modules/@deepseek-ai/{cordis,dsh-tools}`
+  是指向全局 `@deepseek-ai/dsh` 内嵌依赖的符号链接（本机解析到 cordis 4.0.2、dsh-tools 0.1.5-rc.2）。
+  插件是从 tarball 解出来的**真实目录**，从它内部 `import.meta.resolve()` 向上走就能命中；
+  已装的 dsh-dolphin-security 报的是同一类误报。**只要实际版本落在 peer 范围内，这条警告可以忽略。**
+
+## 跨平台说明
+
+- 开发环境用 **WSL 做真机测试**：Windows → WSL2 的 2222 portproxy 需要管理员权限才能修，本机没修，
+  所以 Windows 侧只跑离线套件（逻辑层 + 假 engine），真机套件在 WSL 内部跑。
+- `cpu-features` 构建失败**不影响功能**：`ssh2` 把它列为可选加速模块，装不上就退回纯 JS 实现，只是性能略降。
+  （这条是 ssh2 上游行为 + 本项目 `loadSsh2`/`isSsh2Available` 的容错设计；我们没有专门实测过构建失败的安装。）
+- `REVERSE_HOME` 用**当前 OS 的路径风格**：Windows 上是 `D:\...`，POSIX 上是 `/...`，本项目不做路径翻译。
+
+## 安全边界
+
+- **只分析、不利用**：没有执行目标、注入、patch、改写工件的任何入口。
+- **提权硬闸门**：每条远端命令下发前过 `assertNoPrivilegeEscalation`，命中 `sudo` 或
+  `--break-system-packages` 直接抛错、不下发（`remote-shell-utils.js`）。探测类命令 `attempts` 固定为 1，
+  不做重放 —— 下发前无法确认幂等。
+- **`mutates_artifact` 的操作不会被选中**，机制要说准：REA 广告面里确实有带它的组
+  （`annotate_native_function`、`set_address_name(s)`、`set_bookmark` / `set_comment` / `set_inline_comment` /
+  `unset_bookmark`），但选路的必要条件是「该操作有已核对的 CLI 绑定」，而绑定表里一条写类操作都没有。
+  也就是说这是**靠白名单实现的，不是运行期按 effects 拦截**；`effects` 只如实透传进 `route.reason` 给你看。
+- **口令不进工具参数**：`authKind=password` 只接受一个环境变量名 `passwordEnv`，口令本体留在宿主进程环境里 ——
+  作为参数传会进会话记录。列表/详情回的是脱敏投影（`auth.kind`），不回显口令或私钥内容。
+
+## A 路（Ghidra 深分析）绑定表
+
+| operation | 子命令（`--help` 原文形状） | address |
+|---|---|---|
+| `analyze_function` | `rea function <path> [address] [options]` | 可选 |
+| `procedure_pseudo_code` | `rea decompile <path> [address] [options]` | 可选 |
+| `procedure_assembly` | `rea instructions <path> [address] [options]` | 可选 |
+| `xrefs` | `rea xrefs <path> [address] [options]` | 可选 |
+| `read_bytes` | `rea read-bytes <path> <address> [options]` | **必填 → 只登记不下发** |
+
+Ghidra 不可用时，错误信息用的是 REA 自己的原文（`Set GHIDRA_INSTALL_DIR to an extracted Ghidra 12.1.x
+release directory.` ＋ `install_dir / analyze_headless_path / java_command / java_home` 的诊断原值），
+本项目不自己编修法。深分析 provider 的 session 是 ephemeral（导入的 Program 与临时工程在 close 时删除），
+所以 Evidence 一解析出来就当场落盘。
+
+## 落盘位置
+
+数据根 = `$REVERSE_HOME`（回退 `$DSH_HOME`，再回退 `~/.reverse`）：
+
+- 报告：`<数据根>/reports/fetch-<alias>-<ts>.json`、`analyze-<alias>-<ts>.json`
+- 拉取的目标：`<数据根>/targets/<文件名>`
+- Evidence：按 `evidence_id` 落盘（`<数据根>/evidence/<evidence_id>.json`），路径写在报告的
+  `analysis.evidencePath`；落的是 stdout 里那一行**原始字节**，不重新格式化。
+
+工具返回体里不放远端原始 stdout，也不放全量 Evidence（真机 5.6KB ~ 75KB），只放摘要与路径。
+
+## 安装与挂载
+
+```bash
+cd <DSH home> && DSH_HOME=<DSH home> dsh plugin --profile web add dsh-remote-rea
+cd <项目根> && DSH_HOME=<DSH home> dsh --profile web --host 127.0.0.1 --no-open
+```
+
+`ssh2` / `cpu-features` 需要构建许可：pnpm 11 的门禁会拦依赖的构建脚本
+（`ERR_PNPM_IGNORED_BUILDS`，退出码 1），要在 profile 的 `pnpm-workspace.yaml` 里加上
+
+```yaml
+allowBuilds:
+  cpu-features: true
+  ssh2: true
+```
+
+装完要重启 `dsh web` 并强制刷新浏览器。桌面端（`desktop` profile）由 Electron 独占管理，
+命令行装插件会被拒（`profile "desktop" is managed exclusively by the Electron application`），
+入口是应用内的插件管理器。
+
+## 测试
+
+```bash
+node test/run-tests.mjs              # 3a 本地解析层
+node test/run-probe-tests.mjs        # 3b 远端能力面探测（--offline 只跑逻辑层）
+node test/run-deploy-tests.mjs       # 第 4 步 部署链
+node test/run-controller-tests.mjs   # 第 5 步 runFetch
+node test/run-analyze-tests.mjs      # 第 6 步 runAnalyze（--cold 额外跑破坏性冷缓存）
+node test/run-plugin-tests.mjs       # 第 7 步 插件契约 + 跨平台补丁 + A 路
+```
+
+需要真机的套件走 `--alias=<别名> --store=<主机库路径>`，别名先用 `remote_hosts` 或主机库脚本登记。
+
+## 许可与第三方声明
+
+本项目以 MIT 发布（`LICENSE`）。`remote-ssh-core.js` 派生自 dsh-web 的 `dsh-ssh`（Apache-2.0），
+`remote-shell-utils.js` 派生自 dsh-dolphin-security（MIT，同作者）—— 逐函数的来源位置、修改内容与
+许可证原文见 `THIRD_PARTY_NOTICES.md` 与 `THIRD_PARTY_LICENSES/`。
+
+技术债与已知限制的单子在同目录 `TECH_DEBT.md`。

package/THIRD_PARTY_LICENSES/dsh-dolphin-security-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dolphin 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/THIRD_PARTY_LICENSES/dsh-web-Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,92 @@
+# Third-Party Notices
+
+`dsh-remote-rea` 包含或派生自以下开源项目。依据各自许可证的要求，其原始版权声明与
+许可条款在此保留。完整许可证原文见 `THIRD_PARTY_LICENSES/` 目录。
+
+本项目自身代码以 MIT 许可证发布，完整条款见同目录 `LICENSE`（标准 MIT 模板，21 行）。
+
+---
+
+## 1. dsh-web / dsh-ssh（经 dsh-dolphin-security 中转）
+
+- **本项目文件**：`remote-ssh-core.js`
+- **上游来源**：https://github.com/zhu1090093659/dsh-web 的 `packages/dsh-ssh/src`
+  （npm 包 `@linxin666/dsh-ssh`）
+- **许可证**：Apache License 2.0
+- **版权**：Copyright (c) dsh-web contributors
+- **完整原文**：`THIRD_PARTY_LICENSES/dsh-web-Apache-2.0.txt`
+- **派生链**：`dsh-ssh`（Apache-2.0, TypeScript 多文件）
+  → `dsh-dolphin-security/dolphin-ssh-core.js`（MIT, 裁剪为单文件 ESM）
+  → `dsh-remote-rea/remote-ssh-core.js`（本文件）
+  两个上游均以宽松许可证发布，本项目的再分发满足 Apache-2.0 §4 的要求。
+- **保留的上游模块**：`engine.ts`、`engine/connection-pool.ts`、`engine/sftp.ts`、
+  `engine/cluster.ts`、`store.ts`、`protocol.ts`（类型契约以 JSDoc 形式保留）
+- **上游适配（由 dsh-dolphin-security 完成，本项目继承）**：移除 cordis、
+  `@deepseek-ai/dsh-settings`、`@deepseek-ai/dsh-tools`、`schemastery` 等宿主专属上下文，
+  移除面向 Web 界面的 `client/` 半区（含 dsh-market 遥测心跳）、`engine/pty.ts`、
+  `engine/tunnel.ts`、`routes.ts`、`loopback.ts`；运行时唯一三方依赖为 `ssh2`（MIT）。
+
+### 本项目相对 `dolphin-ssh-core.js` 的修改痕迹
+
+Apache-2.0 §4(b) 要求注明修改。本项目**只做了标识符与文案的机械改名，逻辑改动为 0 行**
+（连接池、建连参数、exec 语义、SFTP、cluster、HostStore、自检断言一律未变）：
+
+| 原标识符 | 新标识符 | 类型 | 位置 |
+|---|---|---|---|
+| `DOLPHIN_HOME` | `REVERSE_HOME` | 环境变量 | `resolveReverseHome()` 读取处 |
+| `DOLPHIN_SSH2_MODULE` | `REVERSE_SSH2_MODULE` | 环境变量 | `loadSsh2()` 覆盖项与错误提示 |
+| `resolveDolphinHome` | `resolveReverseHome` | 导出函数名 | 定义处、`storePath()` 调用处 |
+| `dolphin-ssh-hosts.json` | `remote-ssh-hosts.json` | 主机库文件名 | `storePath()`、`HostStore` 文档注释 |
+| `~/.dolphin` | `~/.reverse` | 数据根回退路径 | `resolveReverseHome()` 返回值、文档注释 |
+| `dolphin-ssh-selftest-*` | `remote-ssh-selftest-*` | 自检临时文件名 | `selfTest()` |
+| `dolphin-ssh-core.js` / `Project Dolphin` 等文案 | `remote-ssh-core.js` / 中性表述 | 注释与自检横幅 | 文件头、各节标题、`selfTest()` |
+
+未改名的中性标识符（保持原样）：`isSsh2Available`、`loadSsh2`、`expandHome`、`storePath`、
+`sshConfigPath`、`validateAlias`、`validateHostPayload`、`normalizeAgentPath`、`HostStore`、
+`createHostStore`、`DEFAULTS`、`buildConnectConfig`、`resolveAgentPath`、`connectClient`、
+`appendOutput`、`connectChain`、`acquire`、`disposeRecord`、`endRecordChain`、`sweepPool`、
+`withClient`、`execCommand`、`walkLocalDir`、`upload`、`download`、`ls`、`cluster`、
+`SshEngine`、`createSshEngine`。
+
+数据根解析优先级 `$REVERSE_HOME > $DSH_HOME > ~/.reverse` 中的 `DSH_HOME` 是 DSH 生态的
+统一数据根变量，非上游项目私有标识，原样保留。
+
+---
+
+## 2. dsh-dolphin-security（`remote-shell-utils.js`）
+
+- **本项目文件**：`remote-shell-utils.js`
+- **上游来源**：https://github.com/ccr-wer/dsh-dolphin-security
+- **许可证**：MIT
+- **版权**：Copyright (c) 2026 Dolphin Contributors
+- **完整原文**：`THIRD_PARTY_LICENSES/dsh-dolphin-security-MIT.txt`
+- **派生自（逐函数搬运，行为零改动）**：
+  `dolphin-patrol.js:69` `shellQuote`、`dolphin-patrol.js:79` `writeJsonReport`、
+  `dolphin-patrol.js:186` `assertNoPrivilegeEscalation`、`dolphin-patrol.js:211`
+  `assessDeploymentPlan`、`dolphin-core.js:220-224` `timestamp`
+  （本项目第 2 步的搬运编号为 A12–A16，指的就是上面这五个函数。）
+- **修改**：注释中性化（去掉 semgrep 专属的业务示例与理由文案）、超时常量参数化
+  （`PROBE_TIMEOUT` → `PROBE_TIMEOUT_MS`，调用方可覆盖）、`writeJsonReport` 的
+  `reportsDir` 改为参数传入且不在 import 期求值、`assessDeploymentPlan` 的策略名与
+  rationale 文案改写到本项目场景。新增导出 `defaultReportsDir`（本项目自写，非派生）。
+- 两个上游（dsh-web Apache-2.0、dsh-dolphin-security MIT）均为宽松许可证；本文件与
+  `THIRD_PARTY_LICENSES/` 满足各自的归属与原文随附要求。
+
+---
+
+## 3. ssh2
+
+- **来源**：https://github.com/mscdex/ssh2
+- **许可证**：MIT
+- **用途**：底层 SSH/SFTP 协议实现（本项目唯一的运行时三方依赖，不随源码派生）
+
+---
+
+## Apache-2.0 合规说明
+
+对于上述以 Apache License 2.0 授权的部分，本项目：
+
+- 保留原始版权、专利、商标与归属声明（见 `THIRD_PARTY_LICENSES/` 内各文件与本文件）；
+- 在 `THIRD_PARTY_LICENSES/` 中随附完整许可证原文；
+- 未使用上游商标，未以原作者名义背书；
+- 对上表所列的修改已在「修改痕迹」小节中逐条记录变更内容。

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh bundle patch：把本插件声明进 DSH 生态的组合层。
+# name 用包名（不是绝对路径）—— `dsh plugin add dsh-remote-rea` 装进 profile 后就能解析，
+# 不需要使用者把仓库 clone 到某台机器的特定目录。
+# id 必须与 index.js 的 export const name 一致：宿主按这个 id 在配置树里挂载本插件。
+- insert:
+    - id: remote-rea
+      name: dsh-remote-rea