dsh-scp-ops 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,70 @@
1
+ # Changelog
2
+
3
+ ## 0.2.1 — 2026-11-17
4
+
5
+ - **Fixed**: ssh2 resolution no longer assumes the bundle's installed directory
6
+ name. `loadSsh2()` now tries three anchors in order — the module's own ESM
7
+ resolution chain, this file's real location via `import.meta.url` (survives
8
+ symlinked, renamed or relocated installs), and `DSH_PROFILE_DIR` anchored at
9
+ `package.json` — instead of the old hard-coded
10
+ `node_modules/dsh-scp-ops/index.js` fallback path.
11
+ - **Changed**: package prepared for its first npm publication (`private`
12
+ flag removed); profile-installed bundles remain unaffected.
13
+
14
+ ## 0.2.0 — 2026-11-12
15
+
16
+ Security & robustness release after a 7-perspective adversarial code review
17
+ (security, protocol correctness, host contract, tool/agent experience,
18
+ performance, cross-device compatibility, plus a dedicated attacker with live
19
+ reproduction).
20
+
21
+ - **Fixed**: recursive-download path escape — dot segments (`..`) in wire entry
22
+ names are refused and every write is containment-checked against the resolved
23
+ destination root
24
+ - **Fixed**: profile rows now LOCK their endpoint — inline `host`/`port`/`username`
25
+ overrides that conflict with a matched profile are rejected (credential
26
+ forwarding guard); unknown-profile errors no longer enumerate profile names
27
+ - **Fixed**: private key material is never echoed in errors (redacted summary;
28
+ PuTTY PPK detection with a re-export hint)
29
+ - **Added**: inbound wire buffer cap (64 MiB) and protocol line cap (8 KiB) with
30
+ hard failure — a desyncing or runaway remote can no longer balloon host memory
31
+ - **Added**: per-file (4 GiB) and per-call (64 GiB) declared-size limits
32
+ - **Changed**: streaming transfers in both directions (constant memory) with
33
+ byte-count verification
34
+ - **Added**: per-host transfer serialization (`config.max_concurrent_per_host`,
35
+ default 1) — prevents interleaved writes to the same destination and plays
36
+ nicely with single-session embedded devices
37
+ - **Fixed**: `preserve` (-p) interoperates with OpenSSH — four-field T frames
38
+ are now sent and parsed (mtime microseconds included)
39
+ - **Added**: `literal` parameter for exact-name downloads containing glob
40
+ characters (`*`, `?`, `[`)
41
+ - **Changed**: glob batches continue past per-file remote errors and report
42
+ `truncated` plus sanitized `warnings` instead of aborting silently
43
+ - **Added**: legacy device hooks — `algorithms` override and `try_keyboard`
44
+ with password auto-answer (keyboard-interactive)
45
+ - **Added**: downloaded-name neutralization on Windows (NTFS ADS colons,
46
+ reserved device names, trailing dots/spaces)
47
+ - **Added**: `local_path` must be absolute (relative paths resolved against the
48
+ harness process cwd were silently misplaced); results now include
49
+ `local_path_resolved`
50
+ - **Fixed**: remote-originated text is control-character sanitized and
51
+ delimited (`[remote]`) before reaching error messages; declared as data,
52
+ not instructions
53
+ - **Changed**: non-atomic failure semantics are documented (already-transferred
54
+ files remain; counts reported)
55
+ - **Docs**: bilingual README with an honest security model (including the
56
+ missing host-key verification gap), destination-semantics reference, and
57
+ legacy-device algorithm notes
58
+
59
+ ## 0.1.1 — 2026-11-11
60
+
61
+ - Bilingual release README; packaging metadata alignment
62
+
63
+ ## 0.1.0 — 2026-11-11
64
+
65
+ - Initial release: `scp_upload` / `scp_download` — exact single file, recursive
66
+ directory, and remote glob batch modes
67
+ - Legacy SCP wire protocol (`scp -t` / `scp -f`) over ssh2 exec — works without
68
+ a remote SFTP subsystem
69
+ - Password / private-key auth, named profiles, `recursive`, `preserve`,
70
+ `timeout_ms`
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ciskonc
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,143 @@
1
- # Temporary Holding Version
1
+ # dsh-scp-ops
2
2
 
3
- 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.
3
+ <div align="center">
4
+
5
+ [![Version](https://img.shields.io/badge/version-0.2.1-blue?style=flat-square)](https://github.com/ciskonc/dsh-scp-ops/releases)
6
+ [![License](https://img.shields.io/badge/license-MIT-orange?style=flat-square)](LICENSE)
7
+ [![Platform](https://img.shields.io/badge/platform-DeepSeek%20Harness-green?style=flat-square)](https://github.com/ciskonc/dsh-scp-ops)
8
+
9
+ [中文](README.md) · [English](README_EN.md) · [更新日志](CHANGELOG.md)
10
+
11
+ </div>
12
+
13
+ ## 概要
14
+
15
+ DeepSeek Harness 的 SCP 上传/下载插件。在 ssh2 exec 通道上实现 SCP 协议(`scp -t` / `scp -f`),远端有 `scp` 可执行文件即可,不需要 SFTP 子系统。`dsh-ssh-ops` 的伴生插件,补足 SCP 传输能力。
16
+
17
+ ## 功能
18
+
19
+ | 功能 | 说明 |
20
+ |------|------|
21
+ | 三种传输形态 | 单文件精确路径 / 递归目录树 / 远端通配符批量(`/logs/*.log`),`literal: true` 按字面名下载 |
22
+ | 免 SFTP | 直接在 ssh2 exec 通道实现 SCP 线协议,远端有 `scp` 可执行文件即可 |
23
+ | preserve 时间戳 | `-p` 双向保留 mtime/atime(T 帧四字段,兼容 OpenSSH) |
24
+ | 老设备认证 | profile 级 `algorithms`(SHA1 KEX/CBC)与 `try_keyboard`(keyboard-interactive 自动应答) |
25
+ | profile 锁端点 | 命中 profile 后内联 host/port/username 覆盖被拒绝,防止存档凭据被转发 |
26
+ | 流式传输 | 双向常量内存 + 字节数校验,单文件上限 4 GiB |
27
+ | 同主机串行 | 排队执行(`max_concurrent_per_host`,默认 1),根绝同路径交错写 |
28
+ | 路径与名字防护 | 下载写入包含性校验;拒 `.`/`..` 条目;Windows 剥 ADS 冒号/保留名/尾点 |
29
+
30
+ ## 安装
31
+
32
+ #### 方式一:GitHub 仓库
33
+
34
+ ```text
35
+ plugin_manager install_bundle → github:ciskonc/dsh-scp-ops
36
+ ```
37
+
38
+ #### 方式二:npm(发布后可用)
39
+
40
+ ```bash
41
+ npm install -g dsh-scp-ops
42
+ dsh plugin --profile web add dsh-scp-ops
43
+ ```
44
+
45
+ 依赖:`ssh2`。同 profile 已装 `dsh-ssh-ops` 时自动满足;否则在插件目录执行 `npm install ssh2`。
46
+
47
+ ## 配置
48
+
49
+ 命名 profile 保存在 patch 层,升级不丢:
50
+
51
+ ```yaml
52
+ - id: scp-ops
53
+ name: 'dsh-scp-ops'
54
+ config:
55
+ profiles:
56
+ - name: onu-stick-4
57
+ host: 192.168.1.100
58
+ username: root
59
+ password: '...'
60
+ # 老设备(仅 SHA1 KEX / CBC 或 keyboard-interactive 认证):
61
+ # algorithms: { kex: ["diffie-hellman-group14-sha1"], cipher: ["aes128-cbc"] }
62
+ # try_keyboard: true
63
+ ```
64
+
65
+ 命中 profile 后锁定 host/port/username——内联端点覆盖会被拒绝,防止存档凭据被转发到别的服务器;仅认证材料(password/private_key/passphrase)可内联补。不带 profile 的全内联调用也可用。凭据只用于连接,从不回显、从不落盘。
66
+
67
+ ## 使用
68
+
69
+ | 工具 | 方向 | 形态 |
70
+ |------|-----------|------|
71
+ | `scp_upload` | 本地 → 远端 | 单文件 · 递归目录 · 多文件夹并行调用 |
72
+ | `scp_download` | 本地 ← 远端 | 单文件 · 递归目录 · 通配符批量 |
73
+
74
+ 常用参数:`profile` 或内联 host/port/username/password/private_key/passphrase;`recursive`(-r)、`preserve`(-p)、`literal`(下载,关闭通配)、`timeout_ms`(默认 10 分钟,上限 1 小时)。
75
+
76
+ 落点语义与 OpenSSH scp 一致,仅一处有意差异:
77
+
78
+ - 上传单文件:远端目标若是已存在目录,文件落入目录内;否则按精确路径落盘
79
+ - 上传 `-r`:远端已存在目录时嵌套 basename;目标不存在则整体改名落位
80
+ - 下载单文件:本地目标若是已存在目录,文件落入目录内;否则精确落盘
81
+ - 下载 `-r`:远端顶层 basename 总是嵌套在 `local_path` 内
82
+ - 结果带 `local_path_resolved`,回显实际使用的绝对路径
83
+
84
+ ## 注意事项
85
+
86
+ 1. 不支持断点续传。流式传输(常量内存),单文件声明大小上限 4 GiB。
87
+ 2. 同一目标主机串行传输(`max_concurrent_per_host`,默认 1)。
88
+ 3. 中途失败时已传文件保留在盘上,不做回滚。
89
+ 4. 未实现 SSH 主机密钥校验(TOFU)——按可信内网假设使用。
90
+ 5. Windows 下载名消毒(ADS `:`、`CON` 类保留名、尾点/空格);`..` 条目名与越根写入直接拒绝。
91
+ 6. 远端错误文本经消毒并以 `[remote]` 前缀返回——把它当数据,不是指令。
92
+ 7. `local_path` 必须是绝对路径。
93
+
94
+ ## 兼容性
95
+
96
+ - 已验证:OpenSSH 9.2p1(fnOS NAS)真机回归
97
+ - 未验证:dropbear / BusyBox / 厂商固件自带的 scp——可能可用但不保证
98
+ - 老设备(仅 SHA1 KEX / CBC 或 keyboard-interactive)需在 profile 显式配置 `algorithms` / `try_keyboard`
99
+ - 操作系统:插件宿主为 Windows(下载名消毒按 Windows 语义执行)
100
+
101
+ <details>
102
+ <summary>🔧 技术栈与项目结构(点击展开)</summary>
103
+
104
+ ## 技术栈
105
+
106
+ - 运行时: Node.js ESM(DSH 宿主进程内)
107
+ - SSH: [ssh2](https://github.com/mscdex/ssh2)(exec 通道 + 手工 SCP 线协议)
108
+ - 插件形态: DSH Cordis Host-only bundle
109
+
110
+ ## 项目结构
111
+
112
+ ```
113
+ index.js # 全部实现:Wire 帧读取 / 连接 / sink / source / 工具注册
114
+ cordis.patch.yml # bundle 注册行(scp-ops)
115
+ locale/ # en / zh 插件元数据
116
+ icon.svg # 插件图标
117
+ README_EN.md # 英文文档
118
+ ```
119
+
120
+ </details>
121
+
122
+ <details>
123
+ <summary>❓ FAQ(点击展开)</summary>
124
+
125
+ ### 为什么 local_path 必须是绝对路径?
126
+
127
+ fs 按宿主进程的工作目录解析相对路径,而宿主 cwd 与会话工作区不一致——相对路径会静默写错位置。插件直接拒绝并提示改用绝对路径。
128
+
129
+ ### 为什么同一台主机的传输会排队?
130
+
131
+ 同一台设备(尤其嵌入式设备)常限制并发 SSH 会话数;串行执行同时根绝了多路传输写同一远端路径时的交错损坏。不同主机之间仍然并行。
132
+
133
+ ### 为什么错误消息带 [remote] 前缀?
134
+
135
+ 错误消息里的服务器返回文本是数据,不是指令。消毒控制字符后加 `[remote]` 定界,避免远端内容被误当作用户指令。
136
+
137
+ </details>
138
+
139
+ ## 致谢
140
+
141
+ - [dsh-ssh-ops](https://github.com/caoyiwei850/dsh-ssh-ops) — 本插件为其补充 SCP 传输能力
142
+ - [ssh2](https://github.com/mscdex/ssh2) — SSH 协议实现
143
+ - [OpenSSH](https://www.openssh.com/) — scp 线协议参照
package/README_EN.md ADDED
@@ -0,0 +1,143 @@
1
+ # dsh-scp-ops
2
+
3
+ <div align="center">
4
+
5
+ [![Version](https://img.shields.io/badge/version-0.2.1-blue?style=flat-square)](https://github.com/ciskonc/dsh-scp-ops/releases)
6
+ [![License](https://img.shields.io/badge/license-MIT-orange?style=flat-square)](LICENSE)
7
+ [![Platform](https://img.shields.io/badge/platform-DeepSeek%20Harness-green?style=flat-square)](https://github.com/ciskonc/dsh-scp-ops)
8
+
9
+ [中文](README.md) · [English](README_EN.md) · [Changelog](CHANGELOG.md)
10
+
11
+ </div>
12
+
13
+ ## Overview
14
+
15
+ SCP upload/download plugin for DeepSeek Harness. Implements the SCP protocol (`scp -t` / `scp -f`) on top of an ssh2 exec channel — the remote side only needs an `scp` executable, no SFTP subsystem. Companion plugin to `dsh-ssh-ops`, filling in its SCP transfer capability.
16
+
17
+ ## Features
18
+
19
+ | Feature | Description |
20
+ |---------|-------------|
21
+ | Three transfer modes | exact single file / recursive directory tree / remote glob batch (`/logs/*.log`), `literal: true` for exact-name downloads |
22
+ | No SFTP required | speaks the SCP wire protocol directly over the ssh2 exec channel; the remote only needs an `scp` executable |
23
+ | preserve timestamps | `-p` keeps mtime/atime in both directions (four-field T frames, OpenSSH compatible) |
24
+ | Legacy device auth | profile-level `algorithms` (SHA1 KEX/CBC) and `try_keyboard` (keyboard-interactive auto-answer) |
25
+ | Profile endpoint locking | inline host/port/username overrides conflicting with a matched profile are rejected |
26
+ | Streaming transfers | constant memory in both directions + byte-count verification, 4 GiB per-file cap |
27
+ | Per-host serialization | transfers queue up per target host (`max_concurrent_per_host`, default 1) — no interleaved writes |
28
+ | Path & name protection | download writes containment-checked; `.`/`..` entries refused; Windows strips ADS colons / reserved names / trailing dots |
29
+
30
+ ## Install
31
+
32
+ #### Option 1: GitHub repository
33
+
34
+ ```text
35
+ plugin_manager install_bundle → github:ciskonc/dsh-scp-ops
36
+ ```
37
+
38
+ #### Option 2: npm (once published)
39
+
40
+ ```bash
41
+ npm install -g dsh-scp-ops
42
+ dsh plugin --profile web add dsh-scp-ops
43
+ ```
44
+
45
+ Dependency: `ssh2`. Automatically satisfied when `dsh-ssh-ops` is installed in the same profile; otherwise run `npm install ssh2` inside the plugin directory.
46
+
47
+ ## Configuration
48
+
49
+ Named profiles live in the patch layer and survive upgrades:
50
+
51
+ ```yaml
52
+ - id: scp-ops
53
+ name: 'dsh-scp-ops'
54
+ config:
55
+ profiles:
56
+ - name: onu-stick-4
57
+ host: 192.168.1.100
58
+ username: root
59
+ password: '...'
60
+ # legacy devices (SHA1 KEX / CBC or keyboard-interactive only):
61
+ # algorithms: { kex: ["diffie-hellman-group14-sha1"], cipher: ["aes128-cbc"] }
62
+ # try_keyboard: true
63
+ ```
64
+
65
+ A matched profile locks host/port/username — inline endpoint overrides are rejected, so stored credentials cannot be forwarded to another server. Only auth material (password/private_key/passphrase) may be supplied inline. Fully inline calls without a profile also work. Credentials are used only to connect; they are never echoed back or written to disk.
66
+
67
+ ## Usage
68
+
69
+ | Tool | Direction | Modes |
70
+ |------|-----------|-------|
71
+ | `scp_upload` | local → remote | single file · recursive directory · multiple folders via parallel calls |
72
+ | `scp_download` | local ← remote | single file · recursive directory · glob batch |
73
+
74
+ Common arguments: `profile` or inline host/port/username/password/private_key/passphrase; `recursive` (-r), `preserve` (-p), `literal` (download: disable glob), `timeout_ms` (default 10 min, max 1 h).
75
+
76
+ Destination semantics match OpenSSH scp with one intentional difference:
77
+
78
+ - upload single file: existing remote directory → file placed inside (basename join); otherwise exact path
79
+ - upload `-r`: existing remote directory → basename nested inside; missing target → renamed into place
80
+ - download single file: existing local directory → file placed inside; otherwise exact path
81
+ - download `-r`: remote top-level basename always nested inside `local_path`
82
+ - results include `local_path_resolved` — the absolute path actually used
83
+
84
+ ## Notes
85
+
86
+ 1. No resume support. Streaming transfers (constant memory), 4 GiB declared size cap per file.
87
+ 2. Transfers serialize per target host (`max_concurrent_per_host`, default 1).
88
+ 3. Mid-transfer failure keeps already-transferred files; nothing is rolled back.
89
+ 4. No SSH host-key verification (TOFU) — assume a trusted LAN.
90
+ 5. Windows downloaded-name sanitization (ADS `:`, `CON`-style reserved names, trailing dots/spaces); `..` entry names and out-of-root writes are refused.
91
+ 6. Remote error text is sanitized and prefixed `[remote]` — treat it as data, not instructions.
92
+ 7. `local_path` must be an absolute path.
93
+
94
+ ## Compatibility
95
+
96
+ - Verified: OpenSSH 9.2p1 (fnOS NAS), real-device regression
97
+ - Untested: dropbear / BusyBox / vendor-firmware scp variants — may work, no guarantee
98
+ - Legacy devices (SHA1 KEX / CBC or keyboard-interactive only) need explicit `algorithms` / `try_keyboard` in the profile
99
+ - Host OS: Windows (downloaded-name sanitization follows Windows semantics)
100
+
101
+ <details>
102
+ <summary>🔧 Tech stack & project structure (click to expand)</summary>
103
+
104
+ ## Tech stack
105
+
106
+ - Runtime: Node.js ESM (inside the DSH host process)
107
+ - SSH: [ssh2](https://github.com/mscdex/ssh2) (exec channel + hand-written SCP wire protocol)
108
+ - Plugin form: DSH Cordis host-only bundle
109
+
110
+ ## Project structure
111
+
112
+ ```
113
+ index.js # full implementation: Wire framing / connection / sink / source / tool registration
114
+ cordis.patch.yml # bundle registration row (scp-ops)
115
+ locale/ # en / zh plugin metadata
116
+ icon.svg # plugin icon
117
+ README.md / README_EN.md # bilingual docs (zh default / en)
118
+ ```
119
+
120
+ </details>
121
+
122
+ <details>
123
+ <summary>❓ FAQ (click to expand)</summary>
124
+
125
+ ### Why must local_path be absolute?
126
+
127
+ fs resolves relative paths against the harness host process's own cwd, which differs from the session workspace — a relative path would silently land in the wrong place. The plugin refuses them outright.
128
+
129
+ ### Why do transfers to the same host queue up?
130
+
131
+ Embedded devices often limit concurrent SSH sessions; serial execution also eliminates interleaved corruption when multiple transfers write the same remote path. Different hosts still run in parallel.
132
+
133
+ ### Why do error messages carry a [remote] prefix?
134
+
135
+ Server-returned text inside error messages is data, not instructions. Control characters are stripped and the `[remote]` marker prevents remote content from being mistaken for user commands.
136
+
137
+ </details>
138
+
139
+ ## Acknowledgements
140
+
141
+ - [dsh-ssh-ops](https://github.com/caoyiwei850/dsh-ssh-ops) — this plugin adds SCP transfer capability on top of it
142
+ - [ssh2](https://github.com/mscdex/ssh2) — SSH protocol implementation
143
+ - [OpenSSH](https://www.openssh.com/) — scp wire protocol reference
@@ -0,0 +1,7 @@
1
+ # dsh-scp-ops bundle patch: registers the SCP transfer plugin entry.
2
+ # Auth profiles are configured here; they survive harness upgrades because the
3
+ # user patch layer is authoritative.
4
+ - insert:
5
+ - id: scp-ops
6
+ name: 'dsh-scp-ops'
7
+ config: {}
package/icon.svg ADDED
@@ -0,0 +1,5 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
2
+ <rect x="4" y="4" width="56" height="56" rx="13" fill="#0f766e"/>
3
+ <path d="M22 45V21m0 0l-8 8m8-8l8 8" stroke="#ffffff" stroke-width="4.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
4
+ <path d="M42 19v24m0 0l-8-8m8 8l8-8" stroke="#99f6e4" stroke-width="4.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
5
+ </svg>