@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/dist/file-ops.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * SSH File Operations - 文件操作
3
3
  */
4
4
  import { spawn } from 'child_process';
5
- import { createHash } from 'crypto';
5
+ import { createHash, randomBytes } from 'crypto';
6
6
  import * as fs from 'fs';
7
7
  import * as os from 'os';
8
8
  import * as path from 'path';
@@ -19,6 +19,8 @@ const S_IFLNK = 0o120000;
19
19
  const RSYNC_CACHE_TTL_MS = 5 * 60_000;
20
20
  const LOCAL_PROCESS_OUTPUT_LIMIT = 200_000;
21
21
  const rsyncCache = new Map();
22
+ const rsyncAliasGenerations = new Map();
23
+ let rsyncGlobalGeneration = 0;
22
24
  function appendLimitedOutput(current, chunk) {
23
25
  if (current.length >= LOCAL_PROCESS_OUTPUT_LIMIT) {
24
26
  return current;
@@ -68,13 +70,30 @@ function runLocalProcess(command, args, timeout) {
68
70
  });
69
71
  });
70
72
  }
73
+ function getRsyncGeneration(alias) {
74
+ return {
75
+ global: rsyncGlobalGeneration,
76
+ alias: rsyncAliasGenerations.get(alias) ?? 0,
77
+ };
78
+ }
79
+ function isCurrentRsyncGeneration(alias, generation) {
80
+ const current = getRsyncGeneration(alias);
81
+ return current.global === generation.global && current.alias === generation.alias;
82
+ }
83
+ function assertCurrentRsyncGeneration(alias, generation) {
84
+ if (!isCurrentRsyncGeneration(alias, generation)) {
85
+ throw new Error(`SSH session '${alias}' changed during rsync setup; retry the sync on the current session`);
86
+ }
87
+ }
71
88
  /** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
72
89
  export function clearRsyncCache(alias) {
73
90
  if (alias === undefined) {
74
91
  rsyncCache.clear();
92
+ ++rsyncGlobalGeneration;
75
93
  }
76
94
  else {
77
95
  rsyncCache.delete(alias);
96
+ rsyncAliasGenerations.set(alias, (rsyncAliasGenerations.get(alias) ?? 0) + 1);
78
97
  }
79
98
  }
80
99
  function positiveIntegerEnv(name, defaultValue) {
@@ -160,24 +179,35 @@ async function runWithConcurrency(items, limit, worker) {
160
179
  function quoteRsyncSshArg(value) {
161
180
  return escapeShellArg(String(value));
162
181
  }
163
- function getAllowListStatus(localPath) {
182
+ function configuredAllowDirectories() {
164
183
  const allowEnv = process.env.SSH_MCP_FILE_OPS_ALLOW_DIRS;
165
- const allowDirs = allowEnv?.split(path.delimiter).filter((item) => item.trim().length > 0) ?? [];
166
- if (allowDirs.length === 0) {
184
+ const configuredPaths = allowEnv?.split(path.delimiter).filter((item) => item.trim().length > 0) ?? [];
185
+ return {
186
+ configured: configuredPaths.length > 0,
187
+ directories: configuredPaths.flatMap((directory) => {
188
+ try {
189
+ return [fs.realpathSync(directory)];
190
+ }
191
+ catch {
192
+ return [];
193
+ }
194
+ }),
195
+ };
196
+ }
197
+ function isPathInsideDirectory(directory, targetPath) {
198
+ const relative = path.relative(directory, targetPath);
199
+ return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
200
+ }
201
+ function getAllowListStatus(localPath) {
202
+ const allowList = configuredAllowDirectories();
203
+ if (!allowList.configured) {
167
204
  return { configured: false };
168
205
  }
169
206
  const resolvedLocal = resolvePathOrAncestor(localPath);
170
- const matched = allowDirs.some((dir) => {
171
- try {
172
- const resolvedDir = fs.realpathSync(dir);
173
- const rel = path.relative(resolvedDir, resolvedLocal);
174
- return !rel.startsWith('..') && !path.isAbsolute(rel);
175
- }
176
- catch {
177
- return false;
178
- }
179
- });
180
- return { configured: true, matched };
207
+ return {
208
+ configured: true,
209
+ matched: allowList.directories.some((directory) => isPathInsideDirectory(directory, resolvedLocal)),
210
+ };
181
211
  }
182
212
  function validateLocalPathAgainstAllowList(localPath) {
183
213
  const allowList = getAllowListStatus(localPath);
@@ -185,6 +215,9 @@ function validateLocalPathAgainstAllowList(localPath) {
185
215
  throw new Error('localPath 不在 SSH_MCP_FILE_OPS_ALLOW_DIRS 允许目录内');
186
216
  }
187
217
  }
218
+ export function validateLocalPathPolicy(localPath) {
219
+ validateLocalPathAgainstAllowList(expandTilde(localPath));
220
+ }
188
221
  function resolvePathOrAncestor(p) {
189
222
  const absolute = path.isAbsolute(p) ? p : path.resolve(p);
190
223
  try {
@@ -205,6 +238,38 @@ function resolvePathOrAncestor(p) {
205
238
  return absolute;
206
239
  }
207
240
  }
241
+ function validateLocalUploadSource(localPath, followSymlinks, symlinkError) {
242
+ const expandedPath = expandTilde(localPath);
243
+ validateLocalPathAgainstAllowList(expandedPath);
244
+ if (!fs.existsSync(expandedPath)) {
245
+ throw new Error(`Local source does not exist: ${expandedPath}`);
246
+ }
247
+ const linkStats = fs.lstatSync(expandedPath);
248
+ if (linkStats.isSymbolicLink() && !followSymlinks) {
249
+ throw new Error(symlinkError);
250
+ }
251
+ if (followSymlinks && getAllowListStatus(expandedPath).configured) {
252
+ throw new Error('followSymlinks=true cannot be combined with SSH_MCP_FILE_OPS_ALLOW_DIRS because symlink targets can change during transfer');
253
+ }
254
+ return {
255
+ expandedPath,
256
+ linkStats,
257
+ stats: linkStats.isSymbolicLink() ? fs.statSync(expandedPath) : linkStats,
258
+ };
259
+ }
260
+ export function validateUploadFileSource(localPath) {
261
+ const source = validateLocalUploadSource(localPath, false, 'Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)');
262
+ if (source.stats.isDirectory()) {
263
+ throw new Error('UPLOAD_PATH_IS_DIRECTORY: localPath is a directory, use ssh_sync for directory upload');
264
+ }
265
+ if (!source.stats.isFile()) {
266
+ throw new Error('UPLOAD_PATH_IS_NOT_FILE: localPath is not a regular file');
267
+ }
268
+ return source;
269
+ }
270
+ export function validateSyncUploadSource(localPath, followSymlinks = false, _exclude) {
271
+ return validateLocalUploadSource(localPath, followSymlinks, 'Refusing to sync a top-level symlink; set followSymlinks=true to traverse its target');
272
+ }
208
273
  export function probeLocalPath(localPath, followSymlinks = false) {
209
274
  const expanded = expandTilde(localPath);
210
275
  const resolvedPath = resolvePathOrAncestor(expanded);
@@ -254,6 +319,9 @@ function isSftpMissingError(error) {
254
319
  const message = error instanceof Error ? error.message : String(error);
255
320
  return /no such file|not found/i.test(message);
256
321
  }
322
+ function isLocalMissingError(error) {
323
+ return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
324
+ }
257
325
  async function sftpExists(sftp, remotePath) {
258
326
  try {
259
327
  await sftpStat(sftp, remotePath);
@@ -275,6 +343,76 @@ async function remoteExists(alias, remotePath) {
275
343
  sftp.end();
276
344
  }
277
345
  }
346
+ export async function hashRemoteFileDigest(alias, remotePath, algorithm) {
347
+ const sftp = await sessionManager.getSftp(alias);
348
+ return new Promise((resolve, reject) => {
349
+ const hash = createHash(algorithm);
350
+ const stream = sftp.createReadStream(remotePath);
351
+ let settled = false;
352
+ const finish = (error) => {
353
+ if (settled) {
354
+ return;
355
+ }
356
+ settled = true;
357
+ sftp.end();
358
+ if (error) {
359
+ reject(error);
360
+ }
361
+ else {
362
+ resolve(hash.digest('hex'));
363
+ }
364
+ };
365
+ stream.on('data', (chunk) => hash.update(chunk));
366
+ stream.once('error', finish);
367
+ stream.once('end', () => finish());
368
+ });
369
+ }
370
+ export class RemoteRenameNotStartedError extends Error {
371
+ constructor(message) {
372
+ super(message);
373
+ this.name = 'RemoteRenameNotStartedError';
374
+ }
375
+ }
376
+ export async function renameRemoteFile(alias, sourcePath, targetPath, replaceExisting = false) {
377
+ const sftp = await sessionManager.getSftp(alias);
378
+ return new Promise((resolve, reject) => {
379
+ const callback = (error) => {
380
+ sftp.end();
381
+ if (error) {
382
+ reject(error);
383
+ }
384
+ else {
385
+ resolve();
386
+ }
387
+ };
388
+ try {
389
+ if (replaceExisting) {
390
+ sftp.ext_openssh_rename(sourcePath, targetPath, callback);
391
+ }
392
+ else {
393
+ sftp.rename(sourcePath, targetPath, callback);
394
+ }
395
+ }
396
+ catch (error) {
397
+ sftp.end();
398
+ reject(new RemoteRenameNotStartedError(`SFTP rename request was not sent: ${error instanceof Error ? error.message : String(error)}`));
399
+ }
400
+ });
401
+ }
402
+ export async function removeRemoteFile(alias, remotePath) {
403
+ const sftp = await sessionManager.getSftp(alias);
404
+ return new Promise((resolve, reject) => {
405
+ sftp.unlink(remotePath, (error) => {
406
+ sftp.end();
407
+ if (error && !isSftpMissingError(error)) {
408
+ reject(error);
409
+ }
410
+ else {
411
+ resolve();
412
+ }
413
+ });
414
+ });
415
+ }
278
416
  /**
279
417
  * 带进度追踪的流传输
280
418
  */
@@ -329,14 +467,19 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
329
467
  readStream.on('error', (err) => cleanup(err));
330
468
  writeStream.on('error', (err) => cleanup(err));
331
469
  writeStream.on('close', () => {
332
- if (!settled) {
333
- settled = true;
334
- detachAbort();
335
- if (closeSftp) {
336
- sftp.end();
337
- }
338
- resolve({ success: true, size: totalSize });
470
+ if (settled) {
471
+ return;
472
+ }
473
+ if (transferred !== totalSize) {
474
+ cleanup(new Error(`Transfer size mismatch: expected ${totalSize} bytes, received ${transferred}`));
475
+ return;
476
+ }
477
+ settled = true;
478
+ detachAbort();
479
+ if (closeSftp) {
480
+ sftp.end();
339
481
  }
482
+ resolve({ success: true, size: totalSize });
340
483
  });
341
484
  if (signal?.aborted) {
342
485
  cleanup(abortError(signal));
@@ -346,33 +489,47 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
346
489
  readStream.pipe(writeStream);
347
490
  });
348
491
  }
492
+ export class UploadFileError extends Error {
493
+ remoteCreated;
494
+ constructor(message, remoteCreated, options) {
495
+ super(message, options);
496
+ this.remoteCreated = remoteCreated;
497
+ this.name = 'UploadFileError';
498
+ }
499
+ }
349
500
  /**
350
501
  * 上传文件
351
502
  */
352
- export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal) {
503
+ export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal, followSymlinks = false, exclusive = false) {
353
504
  throwIfAborted(signal);
354
- localPath = expandTilde(localPath);
355
- validateLocalPathAgainstAllowList(localPath);
356
- if (!fs.existsSync(localPath)) {
357
- throw new Error('Local file not found');
358
- }
359
- // 用 lstat 拒绝顶层 symlink,与 ssh_sync 顶层 followSymlinks=false 行为一致;
360
- // 单文件接口不引入 followSymlinks 选项,需走 symlink 请用 ssh_sync
361
- const lstats = fs.lstatSync(localPath);
362
- if (lstats.isSymbolicLink()) {
363
- throw new Error('Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)');
364
- }
365
- if (lstats.isDirectory()) {
505
+ const source = followSymlinks
506
+ ? validateLocalUploadSource(localPath, true, 'Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)')
507
+ : validateUploadFileSource(localPath);
508
+ localPath = source.expandedPath;
509
+ const stats = source.stats;
510
+ if (stats.isDirectory()) {
366
511
  throw new Error('UPLOAD_PATH_IS_DIRECTORY: localPath is a directory, use ssh_sync for directory upload');
367
512
  }
368
- if (!lstats.isFile()) {
513
+ if (!stats.isFile()) {
369
514
  throw new Error('UPLOAD_PATH_IS_NOT_FILE: localPath is not a regular file');
370
515
  }
371
516
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
372
- const totalSize = lstats.size;
373
- const safeCreateMode = (createMode ?? lstats.mode) & 0o777;
374
- const result = await pipeWithProgress(fs.createReadStream(localPath), sftp.createWriteStream(remotePath, { mode: safeCreateMode }), sftp, totalSize, onProgress, !sharedSftp, signal);
375
- return { ...result, createMode: safeCreateMode.toString(8).padStart(4, '0') };
517
+ const totalSize = stats.size;
518
+ const safeCreateMode = (createMode ?? stats.mode) & 0o777;
519
+ const writeStream = sftp.createWriteStream(remotePath, { mode: safeCreateMode, flags: exclusive ? 'wx' : 'w' });
520
+ let remoteCreated = false;
521
+ writeStream.once('open', () => {
522
+ remoteCreated = true;
523
+ });
524
+ try {
525
+ const result = await pipeWithProgress(fs.createReadStream(localPath), writeStream, sftp, totalSize, onProgress, !sharedSftp, signal);
526
+ return { ...result, createMode: safeCreateMode.toString(8).padStart(4, '0') };
527
+ }
528
+ catch (error) {
529
+ throw new UploadFileError(error instanceof Error ? error.message : String(error), remoteCreated, {
530
+ cause: error,
531
+ });
532
+ }
376
533
  }
377
534
  /**
378
535
  * 下载文件
@@ -382,19 +539,33 @@ export async function downloadFile(alias, remotePath, localPath, onProgress, sha
382
539
  localPath = expandTilde(localPath);
383
540
  validateLocalPathAgainstAllowList(localPath);
384
541
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
542
+ const localDir = path.dirname(localPath);
543
+ const temporaryPath = path.join(localDir, `.${path.basename(localPath)}.mcp-tmp-${process.pid}-${randomBytes(8).toString('hex')}`);
544
+ let transferStarted = false;
385
545
  try {
386
546
  const totalSize = (await sftpStat(sftp, remotePath)).size;
387
- // 确保本地目录存在
388
- const localDir = path.dirname(localPath);
389
547
  if (!fs.existsSync(localDir)) {
390
548
  fs.mkdirSync(localDir, { recursive: true });
391
549
  }
392
- return await pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress, !sharedSftp, signal);
550
+ transferStarted = true;
551
+ const result = await pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(temporaryPath, { flags: 'wx' }), sftp, totalSize, onProgress, !sharedSftp, signal);
552
+ await fs.promises.rename(temporaryPath, localPath);
553
+ return { ...result, atomic: true };
393
554
  }
394
555
  catch (error) {
395
- if (!sharedSftp) {
556
+ if (!sharedSftp && !transferStarted) {
396
557
  sftp.end();
397
558
  }
559
+ try {
560
+ await fs.promises.unlink(temporaryPath);
561
+ }
562
+ catch (cleanupError) {
563
+ if (!isLocalMissingError(cleanupError)) {
564
+ throw new AggregateError([error, cleanupError], 'Download failed and temporary file cleanup failed', {
565
+ cause: cleanupError,
566
+ });
567
+ }
568
+ }
398
569
  throw error;
399
570
  }
400
571
  }
@@ -623,6 +794,16 @@ export async function writeFile(alias, remotePath, content, append = false) {
623
794
  writeStream.end();
624
795
  });
625
796
  }
797
+ function validateSftpEntryName(filename) {
798
+ if (filename.length === 0 ||
799
+ filename === '.' ||
800
+ filename === '..' ||
801
+ filename.includes('\0') ||
802
+ filename.includes('/') ||
803
+ filename.includes('\\')) {
804
+ throw new Error('SFTP directory listing returned an unsafe entry name');
805
+ }
806
+ }
626
807
  /**
627
808
  * 列出目录内容
628
809
  */
@@ -638,6 +819,18 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp)
638
819
  reject(err);
639
820
  return;
640
821
  }
822
+ try {
823
+ for (const item of list) {
824
+ validateSftpEntryName(item.filename);
825
+ }
826
+ }
827
+ catch (error) {
828
+ if (closeWhenDone) {
829
+ sftp.end();
830
+ }
831
+ reject(error);
832
+ return;
833
+ }
641
834
  const files = list
642
835
  .filter((item) => showHidden || !item.filename.startsWith('.'))
643
836
  .map((item) => ({
@@ -695,36 +888,80 @@ export async function getFileInfo(alias, remotePath) {
695
888
  });
696
889
  });
697
890
  }
891
+ function sftpMkdir(sftp, remotePath) {
892
+ return new Promise((resolve, reject) => {
893
+ sftp.mkdir(remotePath, (error) => {
894
+ if (error) {
895
+ reject(error);
896
+ }
897
+ else {
898
+ resolve();
899
+ }
900
+ });
901
+ });
902
+ }
903
+ async function ensureSftpDirectory(sftp, remotePath) {
904
+ const normalizedPath = path.posix.normalize(remotePath);
905
+ if (normalizedPath === '/' || normalizedPath === '.') {
906
+ return;
907
+ }
908
+ try {
909
+ const stats = await sftpStat(sftp, normalizedPath);
910
+ if ((stats.mode & S_IFMT) !== S_IFDIR) {
911
+ throw new Error(`Remote path exists and is not a directory: ${normalizedPath}`);
912
+ }
913
+ return;
914
+ }
915
+ catch (error) {
916
+ if (!isSftpMissingError(error)) {
917
+ throw error;
918
+ }
919
+ }
920
+ const parent = path.posix.dirname(normalizedPath);
921
+ if (parent !== normalizedPath) {
922
+ await ensureSftpDirectory(sftp, parent);
923
+ }
924
+ try {
925
+ await sftpMkdir(sftp, normalizedPath);
926
+ }
927
+ catch (error) {
928
+ try {
929
+ const stats = await sftpStat(sftp, normalizedPath);
930
+ if ((stats.mode & S_IFMT) === S_IFDIR) {
931
+ return;
932
+ }
933
+ }
934
+ catch {
935
+ // 保留原 mkdir 错误
936
+ }
937
+ throw error;
938
+ }
939
+ }
698
940
  /**
699
941
  * 创建目录
700
942
  */
701
- export async function mkdir(alias, remotePath, recursive = false) {
702
- if (recursive) {
703
- // 通过 exec 实现递归创建
704
- const result = await sessionManager.exec(alias, `mkdir -p ${escapeShellArg(remotePath)}`);
705
- if (!result.success || result.exitCode !== 0) {
706
- const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`;
707
- throw new Error(`Remote mkdir failed for ${remotePath}: ${detail}`);
943
+ export async function mkdir(alias, remotePath, recursive = false, sharedSftp) {
944
+ const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
945
+ try {
946
+ if (recursive) {
947
+ await ensureSftpDirectory(sftp, remotePath);
948
+ }
949
+ else {
950
+ await sftpMkdir(sftp, remotePath);
708
951
  }
709
952
  return true;
710
953
  }
711
- const sftp = await sessionManager.getSftp(alias);
712
- return new Promise((resolve, reject) => {
713
- sftp.mkdir(remotePath, (err) => {
954
+ finally {
955
+ if (!sharedSftp) {
714
956
  sftp.end();
715
- if (err) {
716
- reject(err);
717
- }
718
- else {
719
- resolve(true);
720
- }
721
- });
722
- });
957
+ }
958
+ }
723
959
  }
724
960
  /**
725
961
  * 检查远程是否安装 rsync
726
962
  */
727
963
  export async function checkRsync(alias, timeout = 10_000) {
964
+ const generation = getRsyncGeneration(alias);
728
965
  const cached = rsyncCache.get(alias);
729
966
  if (cached !== undefined && cached.expiresAt > Date.now()) {
730
967
  return cached.value;
@@ -737,6 +974,15 @@ export async function checkRsync(alias, timeout = 10_000) {
737
974
  maxOutputSize: 4096,
738
975
  });
739
976
  const duration = Date.now() - startedAt;
977
+ if (!isCurrentRsyncGeneration(alias, generation)) {
978
+ return {
979
+ available: false,
980
+ status: 'error',
981
+ duration,
982
+ retryable: true,
983
+ error: `SSH session '${alias}' changed during rsync probe`,
984
+ };
985
+ }
740
986
  if (result.success && result.exitCode === 0 && result.stdout.trim().length > 0) {
741
987
  const probe = {
742
988
  available: true,
@@ -817,18 +1063,11 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
817
1063
  if (remotePath === '~' || remotePath.startsWith('~/')) {
818
1064
  throw new Error('remotePath must be absolute or relative to the SSH working directory; ~ is not supported');
819
1065
  }
820
- const capabilityStartedAt = Date.now();
821
- const capability = sessionManager.getExternalTransferCapability(alias);
822
1066
  let sourceIsDirectory;
823
1067
  if (direction === 'upload') {
824
- if (!fs.existsSync(localPath)) {
825
- throw new Error(`Local source does not exist: ${localPath}`);
826
- }
827
- const linkStats = fs.lstatSync(localPath);
828
- if (linkStats.isSymbolicLink() && !options.followSymlinks) {
829
- throw new Error('Refusing to sync a top-level symlink; set followSymlinks=true to traverse its target');
830
- }
831
- sourceIsDirectory = (options.followSymlinks ? fs.statSync(localPath) : linkStats).isDirectory();
1068
+ const source = validateSyncUploadSource(localPath, options.followSymlinks === true, options.exclude);
1069
+ localPath = source.expandedPath;
1070
+ sourceIsDirectory = source.stats.isDirectory();
832
1071
  }
833
1072
  else {
834
1073
  sourceIsDirectory = (await getFileInfo(alias, remotePath)).isDirectory;
@@ -836,6 +1075,9 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
836
1075
  if (sourceIsDirectory && options.recursive === false) {
837
1076
  throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
838
1077
  }
1078
+ const capabilityStartedAt = Date.now();
1079
+ const rsyncGeneration = getRsyncGeneration(alias);
1080
+ const capability = sessionManager.getExternalTransferCapability(alias);
839
1081
  const preflightTimeout = options.preflightTimeout ?? 10_000;
840
1082
  const rsyncProbe = capability.rsyncEligible
841
1083
  ? await checkRsync(alias, preflightTimeout)
@@ -846,6 +1088,7 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
846
1088
  retryable: false,
847
1089
  reason: capability.decisionReason,
848
1090
  };
1091
+ assertCurrentRsyncGeneration(alias, rsyncGeneration);
849
1092
  const resolvedOptions = { ...options, sourceIsDirectory };
850
1093
  const capabilityDuration = Date.now() - capabilityStartedAt;
851
1094
  const selectedTransport = capability.rsyncEligible && rsyncProbe?.available ? 'rsync' : 'sftp';
@@ -860,7 +1103,7 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
860
1103
  : 'remote_rsync_probe_failed';
861
1104
  const operationStartedAt = Date.now();
862
1105
  const result = selectedTransport === 'rsync'
863
- ? await syncWithRsync(alias, localPath, remotePath, direction, resolvedOptions, capability)
1106
+ ? await syncWithRsync(alias, localPath, remotePath, direction, resolvedOptions, capability, rsyncGeneration)
864
1107
  : await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, resolvedOptions);
865
1108
  const operationDuration = Date.now() - operationStartedAt;
866
1109
  const operationStatus = result.operationStatus ?? (result.success ? 'completed' : 'failed');
@@ -892,9 +1135,11 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
892
1135
  * 使用 rsync 同步文件
893
1136
  * 通过本地执行 rsync 连接到远程(需要密钥认证或 ssh-agent)
894
1137
  */
895
- async function syncWithRsync(alias, localPath, remotePath, direction, options, capability) {
1138
+ async function syncWithRsync(alias, localPath, remotePath, direction, options, capability, generation) {
1139
+ assertCurrentRsyncGeneration(alias, generation);
896
1140
  const checkCommand = os.platform() === 'win32' ? 'where' : 'which';
897
1141
  const checkResult = await runLocalProcess(checkCommand, ['rsync'], options.preflightTimeout ?? 10_000);
1142
+ assertCurrentRsyncGeneration(alias, generation);
898
1143
  if (checkResult.status !== 0) {
899
1144
  const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
900
1145
  return {
@@ -956,9 +1201,11 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
956
1201
  sshOptions.push('-i', capability.keyPath);
957
1202
  }
958
1203
  const destination = `${capability.username}@${capability.host}`;
1204
+ assertCurrentRsyncGeneration(alias, generation);
959
1205
  const connectStartedAt = Date.now();
960
1206
  const connectResult = await runLocalProcess('ssh', [...sshOptions, destination, 'true'], connectTimeout);
961
1207
  const connectDuration = Date.now() - connectStartedAt;
1208
+ assertCurrentRsyncGeneration(alias, generation);
962
1209
  if (connectResult.error || connectResult.status !== 0) {
963
1210
  const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
964
1211
  const fallbackReason = connectResult.timedOut ? 'rsync_connect_timeout' : 'rsync_connect_failed';
@@ -987,8 +1234,21 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
987
1234
  ? [...args, '-e', sshCmd, '--', rsyncLocalPath, remoteSpec]
988
1235
  : [...args, '-e', sshCmd, '--', remoteSpec, localPath];
989
1236
  try {
1237
+ assertCurrentRsyncGeneration(alias, generation);
990
1238
  const operationTimeout = options.operationTimeout ?? 600_000;
991
1239
  const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout);
1240
+ if (!isCurrentRsyncGeneration(alias, generation)) {
1241
+ return {
1242
+ success: false,
1243
+ method: 'rsync',
1244
+ connectDuration,
1245
+ connectStatus: 'completed',
1246
+ operationStatus: 'unknown',
1247
+ retryable: true,
1248
+ fallbackReason: 'ssh_session_changed',
1249
+ output: `SSH session '${alias}' changed during rsync; remote transfer state is unknown`,
1250
+ };
1251
+ }
992
1252
  if (result.error || result.status !== 0) {
993
1253
  const stderr = result.stderr.trim();
994
1254
  const reason = result.timedOut
@@ -1042,6 +1302,9 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1042
1302
  };
1043
1303
  }
1044
1304
  catch (e) {
1305
+ if (!isCurrentRsyncGeneration(alias, generation)) {
1306
+ throw e;
1307
+ }
1045
1308
  // rsync 启动异常发生在传输进程建立前,可安全改用 SFTP
1046
1309
  const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1047
1310
  const warning = `rsync 异常: ${e instanceof Error ? e.message : String(e)} | 已 fallback 到 SFTP(性能可能较差)`;
@@ -1168,31 +1431,17 @@ function hashLocalFile(filePath) {
1168
1431
  });
1169
1432
  }
1170
1433
  async function hashRemoteFile(alias, remotePath) {
1171
- const result = await sessionManager.exec(alias, `sha256sum ${escapeShellArg(remotePath)} | awk '{print $1}'`, {
1172
- timeout: 30000,
1173
- useLoginUser: true,
1174
- maxOutputSize: 4096,
1175
- });
1176
- if (!result.success) {
1177
- return {
1178
- status: 'error',
1179
- exitCode: result.exitCode,
1180
- failureKind: result.failureKind,
1181
- retryable: result.failureKind !== 'remote_command',
1182
- error: result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`,
1183
- };
1434
+ try {
1435
+ const digest = await hashRemoteFileDigest(alias, remotePath, 'sha256');
1436
+ return { status: 'available', digest, retryable: false };
1184
1437
  }
1185
- const digest = result.stdout.trim().split(/\s+/)[0];
1186
- if (!/^[a-fA-F0-9]{64}$/.test(digest)) {
1438
+ catch (error) {
1187
1439
  return {
1188
1440
  status: 'error',
1189
- exitCode: result.exitCode,
1190
- failureKind: result.failureKind,
1191
- retryable: false,
1192
- error: 'remote SHA-256 command returned an invalid digest',
1441
+ retryable: true,
1442
+ error: error instanceof Error ? error.message : String(error),
1193
1443
  };
1194
1444
  }
1195
- return { status: 'available', digest, retryable: false };
1196
1445
  }
1197
1446
  async function buildSingleFileVerification(alias, localPath, remotePath, direction) {
1198
1447
  try {
@@ -1209,8 +1458,6 @@ async function buildSingleFileVerification(alias, localPath, remotePath, directi
1209
1458
  failureStage: remoteHash.status === 'error' ? 'remote_hash' : undefined,
1210
1459
  retryable: remoteHash.retryable,
1211
1460
  error: remoteHash.error,
1212
- exitCode: remoteHash.exitCode,
1213
- failureKind: remoteHash.failureKind,
1214
1461
  hashAlgorithm: 'sha256',
1215
1462
  hashMatch: remoteHash.digest ? localSha256 === remoteHash.digest : undefined,
1216
1463
  local: {
@@ -1354,7 +1601,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1354
1601
  }
1355
1602
  const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath);
1356
1603
  const existed = await remoteExists(alias, targetRemotePath);
1357
- const { size } = await uploadFile(alias, localPath, targetRemotePath, undefined, undefined, undefined, options.signal);
1604
+ const { size } = await uploadFile(alias, localPath, targetRemotePath, undefined, undefined, undefined, options.signal, options.followSymlinks === true);
1358
1605
  return {
1359
1606
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
1360
1607
  verification: await buildSingleFileVerification(alias, localPath, targetRemotePath, 'upload'),
@@ -1422,7 +1669,8 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1422
1669
  }
1423
1670
  activeDirectories.add(realPath);
1424
1671
  try {
1425
- await mkdir(alias, remotePath, true);
1672
+ validateLocalPathAgainstAllowList(localPath);
1673
+ await mkdir(alias, remotePath, true, sftp);
1426
1674
  throwIfAborted(signal);
1427
1675
  const items = fs.readdirSync(localPath);
1428
1676
  // 先分类:目录串行(递归会自己并发文件);文件并发上传,避免单 SSH session 上 channel 过多
@@ -1457,7 +1705,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1457
1705
  const itemRemotePath = path.posix.join(remotePath, name);
1458
1706
  const existed = await sftpExists(sftp, itemRemotePath);
1459
1707
  try {
1460
- await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal);
1708
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal, followSymlinks);
1461
1709
  accumulator.addFile(stats.size, existed);
1462
1710
  }
1463
1711
  catch (error) {