@pyrokine/mcp-ssh 2.4.0 → 2.4.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/README.md +60 -20
- package/README_zh.md +20 -16
- package/dist/file-ops.d.ts +22 -2
- package/dist/file-ops.js +347 -99
- package/dist/forward-manager.d.ts +17 -1
- package/dist/forward-manager.js +391 -89
- package/dist/operation-manager.d.ts +13 -1
- package/dist/operation-manager.js +188 -45
- package/dist/session-manager.d.ts +26 -1
- package/dist/session-manager.js +246 -49
- package/dist/tools/connection.js +10 -9
- package/dist/tools/file.d.ts +1 -0
- package/dist/tools/file.js +219 -137
- package/dist/tools/forward.js +6 -4
- package/dist/tools/operation.js +11 -3
- package/dist/types.d.ts +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -110,6 +110,8 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
110
110
|
|
|
111
111
|
`ssh_list_sessions()` returns only `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`. Use `detail=true` for connection details or `fields=[...]` to select fields. Neither mode returns `keyPath`.
|
|
112
112
|
|
|
113
|
+
`ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before the replacement connection is published. Automatic reconnect timers are bound to the session and client that scheduled them, so an old timer cannot disconnect a newer session with the same alias. A delayed `close` from the old client cannot leave stale resources attached to the alias. If a target connection is cancelled while a jump-host `forwardOut` is pending, a channel returned by the delayed callback is destroyed before the connection attempt fails.
|
|
114
|
+
|
|
113
115
|
### Command Execution
|
|
114
116
|
|
|
115
117
|
| Tool | Description |
|
|
@@ -252,9 +254,11 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
|
|
|
252
254
|
```
|
|
253
255
|
|
|
254
256
|
`ssh_connect` returns `identity`, `loginUser`, `runAs`, `reused`, `defaultEnvKeys`, `envKeys`, and `reusableSessions`
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
257
|
+
from the session that was actually published. Concurrent calls reuse an alias only when the complete session configuration
|
|
258
|
+
matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout settings. A conflicting
|
|
259
|
+
pending or active connection is rejected even when its `user@host:port` identity is unchanged. Missing templates include
|
|
260
|
+
available template names when they can be loaded. Missing `configHost` returns SSH config candidates and suggests
|
|
261
|
+
`ssh_config_list`.
|
|
258
262
|
|
|
259
263
|
### Jump Host (Bastion)
|
|
260
264
|
|
|
@@ -300,18 +304,20 @@ tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` bl
|
|
|
300
304
|
Use tracked operations when a command must continue beyond one synchronous tool call:
|
|
301
305
|
|
|
302
306
|
```
|
|
303
|
-
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
|
|
307
|
+
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576, startTimeoutMs=30000)
|
|
304
308
|
ssh_operation_status(operationId="op_xxx")
|
|
305
309
|
ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
|
|
306
310
|
ssh_operation_cancel(operationId="op_xxx")
|
|
307
311
|
```
|
|
308
312
|
|
|
309
|
-
The start call returns an unpredictable `operationId`. The server keeps bounded stdout and stderr buffers, records the
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
313
|
+
The start call returns an unpredictable `operationId`. The server creates the record before requesting the SSH channel, keeps bounded stdout and stderr buffers, records the remote PID after verifying a per-operation marker, and expires terminal records after `retentionMs`. `startTimeoutMs` bounds channel setup, defaults to 30 seconds, and accepts up to 10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks another pending start on that alias until the original channel request settles or the alias is disconnected. `maxOutputBytes` defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours. `ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and PID are verified. Stderr written by a shell profile before the marker is retained as operation output, including an unterminated preamble immediately followed by the marker. A line that uses the operation marker prefix with the wrong token or invalid process metadata ends the
|
|
314
|
+
record as `failed`, closes its channel, and starts the configured retention period. Delayed exec, sudo, SFTP, PTY-start,
|
|
315
|
+
and operation-start callbacks from a disconnected or replaced SSH session are rejected and their channels are destroyed.
|
|
316
|
+
A sudo callback that arrives after timeout is also closed before any password is written. Operation listeners are installed
|
|
317
|
+
inside the SSH exec callback before it returns, so a short command that emits its marker and closes immediately still enters
|
|
318
|
+
a terminal state with `finishedAt` and `expiresAt` set. If the SSH session disconnects while a tracked command is active,
|
|
319
|
+
its status becomes `unknown`; the server does not claim that the remote process stopped. `ssh_exec` keeps its existing
|
|
320
|
+
synchronous timeout behavior.
|
|
315
321
|
|
|
316
322
|
### Interactive Commands (PTY mode)
|
|
317
323
|
|
|
@@ -383,12 +389,29 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
|
|
|
383
389
|
```
|
|
384
390
|
|
|
385
391
|
`ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
|
|
386
|
-
verification checks. `atomic=true`
|
|
387
|
-
|
|
388
|
-
|
|
392
|
+
verification checks. `atomic=true` writes an unpredictable same-directory temporary path with exclusive SFTP creation,
|
|
393
|
+
returns `diagnostics.tempRemotePath`, verifies the temporary file, and renames it only after every requested check passes.
|
|
394
|
+
Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies the path that
|
|
395
|
+
was probed, and atomic verification also returns `verifiedTempRemotePath`. `verification.actual.remotePath` continues to
|
|
396
|
+
describe the file that was actually verified, even after that temporary path has been renamed. Interpret the final state
|
|
397
|
+
with `targetReplaced` and `targetReplacementStatus`. An existing target is replaced with the OpenSSH
|
|
398
|
+
`posix-rename@openssh.com` extension; a new target uses standard SFTP
|
|
399
|
+
rename. If the client cannot send the rename request, the response reports `operationStatus="failed"`,
|
|
400
|
+
`targetReplaced=false`, and `targetReplacementStatus="not_replaced"`. An error returned after the request was sent cannot
|
|
401
|
+
prove whether the server committed it, so the response reports `operationStatus="unknown"`, `targetReplaced=null`, and
|
|
402
|
+
`targetReplacementStatus="unknown"`; inspect the target before retrying. Temporary-file cleanup is attempted in both
|
|
403
|
+
cases. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit transfer checks. Parent and
|
|
404
|
+
target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The standard
|
|
405
|
+
upload path works on SFTP-only servers and does not require GNU `stat`, `md5sum`, `sha256sum`, `mkdir`, `mv`, or `rm`
|
|
406
|
+
commands. Explicit directory manifest verification still runs remote shell commands.
|
|
407
|
+
|
|
408
|
+
`ssh_download` writes to a same-directory temporary file and renames it over the requested local path after the SFTP
|
|
409
|
+
stream closes and the transferred byte count matches the size reported by SFTP `stat`. A failed, truncated, or aborted
|
|
410
|
+
download removes the temporary file and leaves an existing local target unchanged. SFTP directory listings reject empty
|
|
411
|
+
names, `.` and `..`, NUL bytes, and path separators before constructing child paths.
|
|
412
|
+
|
|
389
413
|
Command execution results include `emptyOutputFailure=true` when the remote command exits non-zero without
|
|
390
|
-
stdout/stderr,
|
|
391
|
-
with the effective user, cwd, and a suggested follow-up read command when available.
|
|
414
|
+
stdout/stderr, with the effective user, cwd, and a suggested follow-up read command when available.
|
|
392
415
|
`ssh_read_file` defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`,
|
|
393
416
|
`read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
|
|
394
417
|
from a head, tail, byte range, or line range sample.
|
|
@@ -456,8 +479,8 @@ reporting a partial match.
|
|
|
456
479
|
If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
|
|
457
480
|
`transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
|
|
458
481
|
`failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size,
|
|
459
|
-
mode or permissions, mtime, owner/group, and SHA-256 comparison
|
|
460
|
-
|
|
482
|
+
mode or permissions, mtime, owner/group, and a streamed SFTP SHA-256 comparison. `verifyOwner` and `verifyMode` apply
|
|
483
|
+
to upload single-file sync; use `verify.owner` and `verify.mode` for directory manifests.
|
|
461
484
|
|
|
462
485
|
Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
|
|
463
486
|
jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
|
|
@@ -529,6 +552,9 @@ ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>",
|
|
|
529
552
|
// Remote forward: expose local dev server (3000) to remote port 8080
|
|
530
553
|
ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
|
|
531
554
|
|
|
555
|
+
// Ask the SSH server to allocate a remote port; use remotePort from the result
|
|
556
|
+
ssh_forward_remote(alias="server", remotePort=0, localHost="127.0.0.1", localPort=3000)
|
|
557
|
+
|
|
532
558
|
// List all forwards
|
|
533
559
|
ssh_forward_list()
|
|
534
560
|
|
|
@@ -542,7 +568,14 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
|
542
568
|
A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
|
|
543
569
|
`listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. Timeout or callback failure
|
|
544
570
|
keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful local close, the port
|
|
545
|
-
can be rebound immediately.
|
|
571
|
+
can be rebound immediately. `remotePort=0` returns the actual allocated port and uses that port for incoming connection
|
|
572
|
+
routing and `unforwardIn`.
|
|
573
|
+
|
|
574
|
+
Forward creation is tracked before `listen` or `forwardIn` completes. Disconnect cancels pending creation, closes a local
|
|
575
|
+
listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A forward stops
|
|
576
|
+
accepting new local or remote connections as soon as close begins. Delayed `forwardOut`, close, and unforward callbacks
|
|
577
|
+
check the same lifecycle record before changing state, so a closed forward cannot reappear in `ssh_forward_list`. Each local
|
|
578
|
+
connection tracks both the local socket and the SSH `forwardOut` channel. Closing or failing either side destroys the other, and force close returns only after both sides are destroyed and `activeConnections` reaches zero. Pending `forwardOut` requests are limited to 32 per alias, and a close waits for every callback. If the SSH server never answers a channel-open request, close times out, keeps the forward retryable, and rejects another local forward on the same alias so pending ssh2 channels cannot accumulate. Disconnect the alias to release a channel request that never completes.
|
|
546
579
|
|
|
547
580
|
## Configuration Options
|
|
548
581
|
|
|
@@ -579,6 +612,11 @@ Connection failures return `failureStage`, `retryable`, and a bounded suggestion
|
|
|
579
612
|
| `useLoginUser` | boolean | false | Skip session-level runAs |
|
|
580
613
|
| `loadProfile` | boolean | true | Load target user's shell profile for runAs |
|
|
581
614
|
|
|
615
|
+
When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with `&&`, then runs the
|
|
616
|
+
entire requested command as one escaped `eval` argument in the active login shell. A failed directory change or export
|
|
617
|
+
prevents every part of the requested command from running, including text after `;`, newlines, or `||`, while Bash/Zsh
|
|
618
|
+
syntax keeps the same interpreter semantics as a direct SSH command.
|
|
619
|
+
|
|
582
620
|
## Security
|
|
583
621
|
|
|
584
622
|
### Path Whitelist for Key/Config Files
|
|
@@ -607,8 +645,10 @@ directories (recommended for shared environments), set `SSH_MCP_FILE_OPS_ALLOW_D
|
|
|
607
645
|
export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
608
646
|
```
|
|
609
647
|
|
|
610
|
-
When set, any local path outside the whitelist is rejected
|
|
611
|
-
|
|
648
|
+
When set, any local path outside the whitelist is rejected and symlinks are resolved via `realpath`.
|
|
649
|
+
`ssh_sync(direction="upload", followSymlinks=true)` is rejected before transport selection while the whitelist is active.
|
|
650
|
+
A symlink can change between validation and transfer, and rsync cannot bind the validated target to the later `-L` read.
|
|
651
|
+
Keep `followSymlinks=false`, or copy regular files into an allowed directory before syncing.
|
|
612
652
|
|
|
613
653
|
### File Size Limits
|
|
614
654
|
|
package/README_zh.md
CHANGED
|
@@ -110,6 +110,8 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
110
110
|
|
|
111
111
|
`ssh_list_sessions()` 默认只返回 `alias`、规范化 `identity`、`runAs`、`connected` 和 `lastUsedAt`,使用 `detail=true` 获取连接详情,或通过 `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
|
|
112
112
|
|
|
113
|
+
`ssh_reconnect` 会在发布替代连接前,使绑定旧 client 的 operation、PTY、forward 和传输能力缓存失效;自动重连 timer 绑定发起调度的 session 和 client,不会断开同一 alias 下后来发布的新会话;旧 client 延迟到达的 `close` 不会让过期资源继续挂在同一 alias 下;通过 jump host 建立目标连接时,如果取消发生在 `forwardOut` pending 阶段,延迟 callback 返回的 channel 会先销毁再结束连接请求
|
|
114
|
+
|
|
113
115
|
### 命令执行
|
|
114
116
|
|
|
115
117
|
| 工具 | 描述 |
|
|
@@ -250,9 +252,7 @@ ssh_exec(alias="app-dev", command="whoami && echo $APP_ENV")
|
|
|
250
252
|
ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
|
|
251
253
|
```
|
|
252
254
|
|
|
253
|
-
`ssh_connect`
|
|
254
|
-
下已连接 alias 的 `reusableSessions`,同一个 alias 连接到不同 identity 会被拒绝,并返回现有 identity 和请求
|
|
255
|
-
identity,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
|
|
255
|
+
`ssh_connect` 返回实际发布会话的 `identity`、`loginUser`、`runAs`、`reused`、`defaultEnvKeys`、`envKeys`,以及同一 `user@host:port` identity 下已连接 alias 的 `reusableSessions`,并发调用只有在完整会话配置一致时才复用同一 alias,包括 endpoint、认证、`runAs`、环境变量、jump host、keepalive 和 timeout;pending 或 active 连接的配置冲突时会被拒绝,即使 `user@host:port` identity 相同,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
|
|
256
256
|
|
|
257
257
|
### 跳板机
|
|
258
258
|
|
|
@@ -296,13 +296,13 @@ destructive、process-control、service-control、credential-bearing、未限制
|
|
|
296
296
|
需要命令跨越一次同步工具调用继续执行时,使用 operation 工具组:
|
|
297
297
|
|
|
298
298
|
```
|
|
299
|
-
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
|
|
299
|
+
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576, startTimeoutMs=30000)
|
|
300
300
|
ssh_operation_status(operationId="op_xxx")
|
|
301
301
|
ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
|
|
302
302
|
ssh_operation_cancel(operationId="op_xxx")
|
|
303
303
|
```
|
|
304
304
|
|
|
305
|
-
start 返回不可预测的 `operationId
|
|
305
|
+
start 返回不可预测的 `operationId`,服务端在请求 SSH channel 前创建记录,保存有硬上限的 stdout 和 stderr,并在校验每个任务独立的 marker 后记录远端 PID;`startTimeoutMs` 限制 channel 建立等待,默认 30 秒、最大 10 分钟,超时错误的 details 返回 `operationId`,对应记录进入可查询的 `unknown` 终态,在旧 channel request 返回或 alias 断开前拒绝同 alias 的另一次 pending start;`maxOutputBytes` 默认 1 MiB、最大 8 MiB,`retentionMs` 默认 1 小时、最大 24 小时,`ssh_operation_read.maxBytes` 默认 64 KiB、最大 1 MiB,marker 和 PID 未完成校验时拒绝取消,shell profile 在 marker 前写入的 stderr 会保留为任务输出,包括未换行 preamble 后紧接 marker 的情况;使用 operation marker 前缀但 token 不匹配、长度超限或进程元数据无效时,记录进入 `failed` 终态、关闭 channel 并开始 retention 计时;断开或替换 SSH session 后才返回的 exec、sudo、SFTP、PTY start 和 operation start callback 都会被拒绝并销毁 channel,sudo callback 在 timeout 后返回时也会先关闭,不会写入密码;operation listener 会在 SSH exec callback 返回前安装,极短命令即使立即输出 marker 并关闭,也会进入终态并设置 `finishedAt` 和 `expiresAt`;SSH 会话在 tracked command 运行期间断开后状态变为 `unknown`,不会声称远端进程已经停止,`ssh_exec` 保持原有同步 timeout 行为
|
|
306
306
|
|
|
307
307
|
### 交互式命令(PTY 模式)
|
|
308
308
|
|
|
@@ -373,12 +373,11 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, max
|
|
|
373
373
|
ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
|
|
374
374
|
```
|
|
375
375
|
|
|
376
|
-
`ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true`
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes
|
|
381
|
-
`remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
|
|
376
|
+
`ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 使用不可预测的同目录临时路径和 SFTP 独占创建,返回 `diagnostics.tempRemotePath`,先对临时文件完成全部请求的校验,再 rename 到目标路径;响应使用 `finalRemotePath` 表示最终目标,`verifiedRemotePath` 表示实际执行校验的路径,atomic 校验还会返回 `verifiedTempRemotePath`,`verification.actual.remotePath` 始终描述真正被校验的文件,即使该临时路径随后已被 rename,最终状态需要结合 `targetReplaced` 和 `targetReplacementStatus` 判断;已有目标通过 OpenSSH `posix-rename@openssh.com` 扩展替换,新目标使用标准 SFTP rename;客户端无法发出 rename 请求时返回 `operationStatus="failed"`、`targetReplaced=false` 和 `targetReplacementStatus="not_replaced"`,请求发出后的错误无法证明服务端是否已提交,返回 `operationStatus="unknown"`、`targetReplaced=null` 和 `targetReplacementStatus="unknown"`,重试前应先检查目标内容;两种失败都会尝试清理临时文件;`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输校验,父目录和目标探测、递归建目录、文件哈希、rename、临时文件清理都使用 SFTP,普通上传不依赖 GNU `stat`、`md5sum`、`sha256sum`、`mkdir`、`mv` 或 `rm`,可用于禁用 exec 的 SFTP-only 服务和 BSD 系统,显式目录 manifest 校验仍会执行远端 shell 命令
|
|
377
|
+
|
|
378
|
+
`ssh_download` 先写入目标同目录的临时文件,SFTP 流关闭且传输字节数与 SFTP `stat` 报告的大小一致后再 rename 到本地目标;下载失败、提前截断或取消时会删除临时文件,已有本地目标保持原内容,SFTP 目录列表在构造子路径前会拒绝空名称、`.`、`..`、NUL 和路径分隔符
|
|
379
|
+
|
|
380
|
+
命令执行结果在远端命令非零退出且没有 stdout/stderr 时返回 `emptyOutputFailure=true`,同时给出 effective user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过 16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes`、`remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
|
|
382
381
|
|
|
383
382
|
### 使用 rsync 或 SFTP 同步目录
|
|
384
383
|
|
|
@@ -431,7 +430,7 @@ ssh_sync(..., delete=true, verify={deletions: true})
|
|
|
431
430
|
|
|
432
431
|
目录校验会生成有界的本地和远端 manifest,可比较条目数、SHA-256 root manifest、owner、mode、旧文件和删除结果,`verify.deletions=true` 必须同时设置 `delete=true`,工具会在传输前记录目标目录,只检查这些删除候选是否消失,`staleFiles` 则独立检查目标端全部额外条目,响应只返回摘要和最多 20 个 mismatch 样本,不返回完整 manifest,默认上限为 10000 个条目、单文件 256 MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileBytes` 和 `verify.maxTotalBytes` 提高到最多 50000 个条目、单文件 4 GiB、总哈希字节 16 GiB,遇到被跳过的 symlink 或不支持的文件系统条目时,校验会明确返回 `skipped`,不会报告部分匹配成功
|
|
433
432
|
|
|
434
|
-
请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess` 仍单独表示传输是否完成,`verificationStatus`、`verificationSuccess` 和 `failedChecks` 描述校验结果,SFTP 单文件同步还会返回本地和远端的 size、mode 或 permissions、mtime、owner/group
|
|
433
|
+
请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess` 仍单独表示传输是否完成,`verificationStatus`、`verificationSuccess` 和 `failedChecks` 描述校验结果,SFTP 单文件同步还会返回本地和远端的 size、mode 或 permissions、mtime、owner/group,以及通过 SFTP 流读取计算的 SHA-256 对比,upload 单文件使用 `verifyOwner` 和 `verifyMode`,目录逐项校验使用 `verify.owner` 和 `verify.mode`
|
|
435
434
|
|
|
436
435
|
只有直连且存在已校验 key path 或可用 SSH agent 时才选择 rsync,password、inline key 和 jump host 会使用 SFTP,因为独立 OpenSSH 进程无法安全继承对应路由或认证材料,`preflightTimeout`、`connectTimeout` 和 `operationTimeout` 分别限制能力预检、rsync SSH 建连和完整传输,默认值为 10 秒、30 秒和 10 分钟,不具备 rsync 条件的 session 会返回 `rsyncProbe.status="skipped"` 和路由判定原因,不再省略 probe,rsync 模式设置 `StrictHostKeyChecking=accept-new`,SFTP 不支持 `delete=true`,此类请求会明确失败,不会报告已经删除,如需严格的主机密钥验证与管理,请使用 SFTP 模式
|
|
437
436
|
|
|
@@ -495,6 +494,9 @@ ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>",
|
|
|
495
494
|
// 远程转发:将本地开发服务器 (3000) 暴露到远程端口 8080
|
|
496
495
|
ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
|
|
497
496
|
|
|
497
|
+
// 由 SSH 服务器动态分配远程端口,使用返回结果中的 remotePort
|
|
498
|
+
ssh_forward_remote(alias="server", remotePort=0, localHost="127.0.0.1", localPort=3000)
|
|
499
|
+
|
|
498
500
|
// 列出所有转发
|
|
499
501
|
ssh_forward_list()
|
|
500
502
|
|
|
@@ -505,9 +507,9 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="graceful", timeoutMs=5000)
|
|
|
505
507
|
ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
506
508
|
```
|
|
507
509
|
|
|
508
|
-
关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased
|
|
509
|
-
|
|
510
|
-
`ssh_forward_list
|
|
510
|
+
关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、`remoteUnforwarded`、`activeConnections`、`closeMode` 和 `retryable`,超时或 callback 失败时 forward 仍保留在 `ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind,`remotePort=0` 会返回实际分配端口,后续连接路由和 `unforwardIn` 都使用该端口
|
|
511
|
+
|
|
512
|
+
forward 在 `listen` 或 `forwardIn` 完成前就进入生命周期管理,disconnect 会取消 pending creation;延迟返回的本地 listener 会被关闭,延迟分配的远端 listener 会被移除;close 开始后立即拒绝新的本地或远端连接,`forwardOut`、close 和 unforward 的延迟 callback 修改状态前会检查同一生命周期记录,已关闭的 forward 不会重新出现在 `ssh_forward_list`;每条本地转发连接同时跟踪本地 socket 和 SSH `forwardOut` channel,任一端关闭或失败都会销毁另一端,force close 只在两端都销毁且 `activeConnections` 归零后返回;每个 alias 最多允许 32 个 pending `forwardOut` 请求,close 会等待全部 callback;如果 SSH 服务端始终不回应 channel-open,请求会超时并保留可重试的 forward,同时拒绝同 alias 新建 local forward,避免 ssh2 pending channel 继续累积,此时断开 alias 才能释放始终不返回的底层请求
|
|
511
513
|
|
|
512
514
|
## 配置选项
|
|
513
515
|
|
|
@@ -544,6 +546,8 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
|
544
546
|
| `useLoginUser` | boolean | false | 跳过连接级 runAs |
|
|
545
547
|
| `loadProfile` | boolean | true | runAs 时加载目标用户 shell 配置 |
|
|
546
548
|
|
|
549
|
+
传入 `cwd` 或 `env` 时,生成的 shell 命令会用 `&&` 连接 `cd` 和每个通过校验的 `export`,再把完整用户命令作为当前登录 shell 的一个转义后 `eval` 参数执行;目录切换或环境变量注入失败后,用户命令的任何部分都不会执行,包括 `;`、换行或 `||` 后的内容,同时 Bash/Zsh 专有语法保持与直接 SSH 命令相同的解释器语义
|
|
550
|
+
|
|
547
551
|
## 安全
|
|
548
552
|
|
|
549
553
|
### 私钥/配置文件路径白名单
|
|
@@ -570,7 +574,7 @@ export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
|
|
|
570
574
|
export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
571
575
|
```
|
|
572
576
|
|
|
573
|
-
设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath`
|
|
577
|
+
设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath` 解析;白名单生效时,`ssh_sync(direction="upload", followSymlinks=true)` 会在选择 transport 前被拒绝,symlink 可在校验和传输之间改变目标,rsync 也无法把预检目标绑定到后续 `-L` 读取;应保持 `followSymlinks=false`,或先把普通文件复制到允许目录再同步
|
|
574
578
|
|
|
575
579
|
### 文件大小上限
|
|
576
580
|
|
package/dist/file-ops.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* SSH File Operations - 文件操作
|
|
3
3
|
*/
|
|
4
|
+
import * as fs from 'fs';
|
|
4
5
|
import { SFTPWrapper } from 'ssh2';
|
|
5
6
|
import { FileInfo, TransferProgress } from './types.js';
|
|
6
7
|
type RsyncProbeResult = {
|
|
@@ -15,6 +16,14 @@ type RsyncProbeResult = {
|
|
|
15
16
|
};
|
|
16
17
|
/** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
|
|
17
18
|
export declare function clearRsyncCache(alias?: string): void;
|
|
19
|
+
export declare function validateLocalPathPolicy(localPath: string): void;
|
|
20
|
+
type ValidatedLocalUploadSource = {
|
|
21
|
+
expandedPath: string;
|
|
22
|
+
linkStats: fs.Stats;
|
|
23
|
+
stats: fs.Stats;
|
|
24
|
+
};
|
|
25
|
+
export declare function validateUploadFileSource(localPath: string): ValidatedLocalUploadSource;
|
|
26
|
+
export declare function validateSyncUploadSource(localPath: string, followSymlinks?: boolean, _exclude?: string[]): ValidatedLocalUploadSource;
|
|
18
27
|
export declare function probeLocalPath(localPath: string, followSymlinks?: boolean): {
|
|
19
28
|
exists: boolean;
|
|
20
29
|
inputPath: string;
|
|
@@ -46,10 +55,20 @@ export declare function probeLocalPath(localPath: string, followSymlinks?: boole
|
|
|
46
55
|
matched?: boolean;
|
|
47
56
|
};
|
|
48
57
|
};
|
|
58
|
+
export declare function hashRemoteFileDigest(alias: string, remotePath: string, algorithm: 'md5' | 'sha256'): Promise<string>;
|
|
59
|
+
export declare class RemoteRenameNotStartedError extends Error {
|
|
60
|
+
constructor(message: string);
|
|
61
|
+
}
|
|
62
|
+
export declare function renameRemoteFile(alias: string, sourcePath: string, targetPath: string, replaceExisting?: boolean): Promise<void>;
|
|
63
|
+
export declare function removeRemoteFile(alias: string, remotePath: string): Promise<void>;
|
|
64
|
+
export declare class UploadFileError extends Error {
|
|
65
|
+
readonly remoteCreated: boolean;
|
|
66
|
+
constructor(message: string, remoteCreated: boolean, options?: ErrorOptions);
|
|
67
|
+
}
|
|
49
68
|
/**
|
|
50
69
|
* 上传文件
|
|
51
70
|
*/
|
|
52
|
-
export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal): Promise<{
|
|
71
|
+
export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal, followSymlinks?: boolean, exclusive?: boolean): Promise<{
|
|
53
72
|
success: boolean;
|
|
54
73
|
size: number;
|
|
55
74
|
createMode: string;
|
|
@@ -60,6 +79,7 @@ export declare function uploadFile(alias: string, localPath: string, remotePath:
|
|
|
60
79
|
export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal): Promise<{
|
|
61
80
|
success: boolean;
|
|
62
81
|
size: number;
|
|
82
|
+
atomic: true;
|
|
63
83
|
}>;
|
|
64
84
|
export declare const DEFAULT_READ_FILE_MAX_BYTES: number;
|
|
65
85
|
export declare const HARD_READ_FILE_MAX_BYTES: number;
|
|
@@ -108,7 +128,7 @@ export declare function getFileInfo(alias: string, remotePath: string): Promise<
|
|
|
108
128
|
/**
|
|
109
129
|
* 创建目录
|
|
110
130
|
*/
|
|
111
|
-
export declare function mkdir(alias: string, remotePath: string, recursive?: boolean): Promise<boolean>;
|
|
131
|
+
export declare function mkdir(alias: string, remotePath: string, recursive?: boolean, sharedSftp?: SFTPWrapper): Promise<boolean>;
|
|
112
132
|
/**
|
|
113
133
|
* 检查远程是否安装 rsync
|
|
114
134
|
*/
|