@pyrokine/mcp-ssh 2.4.0 → 2.4.2

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,14 +2,16 @@
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';
9
9
  import { StringDecoder } from 'string_decoder';
10
10
  import { matchesDirectoryExclude } from './directory-verification.js';
11
11
  import { sessionManager } from './session-manager.js';
12
+ import { SftpOperationTimeoutError, withSftpOperationTimeout } from './sftp-timeout.js';
12
13
  import { escapeShellArg, expandTilde } from './tools/utils.js';
14
+ import { ensureUtf8Boundary, isUtf8ContinuationByte, utf8SafeEnd } from './utf8.js';
13
15
  // 文件类型 mode 常量
14
16
  const S_IFMT = 0o170000; // 文件类型位掩码
15
17
  const S_IFDIR = 0o40000;
@@ -19,6 +21,8 @@ const S_IFLNK = 0o120000;
19
21
  const RSYNC_CACHE_TTL_MS = 5 * 60_000;
20
22
  const LOCAL_PROCESS_OUTPUT_LIMIT = 200_000;
21
23
  const rsyncCache = new Map();
24
+ const rsyncAliasGenerations = new Map();
25
+ let rsyncGlobalGeneration = 0;
22
26
  function appendLimitedOutput(current, chunk) {
23
27
  if (current.length >= LOCAL_PROCESS_OUTPUT_LIMIT) {
24
28
  return current;
@@ -68,13 +72,30 @@ function runLocalProcess(command, args, timeout) {
68
72
  });
69
73
  });
70
74
  }
75
+ function getRsyncGeneration(alias) {
76
+ return {
77
+ global: rsyncGlobalGeneration,
78
+ alias: rsyncAliasGenerations.get(alias) ?? 0,
79
+ };
80
+ }
81
+ function isCurrentRsyncGeneration(alias, generation) {
82
+ const current = getRsyncGeneration(alias);
83
+ return current.global === generation.global && current.alias === generation.alias;
84
+ }
85
+ function assertCurrentRsyncGeneration(alias, generation) {
86
+ if (!isCurrentRsyncGeneration(alias, generation)) {
87
+ throw new Error(`SSH session '${alias}' changed during rsync setup; retry the sync on the current session`);
88
+ }
89
+ }
71
90
  /** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
72
91
  export function clearRsyncCache(alias) {
73
92
  if (alias === undefined) {
74
93
  rsyncCache.clear();
94
+ ++rsyncGlobalGeneration;
75
95
  }
76
96
  else {
77
97
  rsyncCache.delete(alias);
98
+ rsyncAliasGenerations.set(alias, (rsyncAliasGenerations.get(alias) ?? 0) + 1);
78
99
  }
79
100
  }
80
101
  function positiveIntegerEnv(name, defaultValue) {
@@ -87,14 +108,6 @@ const SFTP_SYNC_MAX_FILES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_FILES', 10_000)
87
108
  const SFTP_SYNC_MAX_DIRECTORIES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DIRECTORIES', 2_000);
88
109
  const SFTP_SYNC_MAX_DEPTH = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DEPTH', 64);
89
110
  const SFTP_SYNC_MAX_BYTES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_BYTES', 10 * 1024 * 1024 * 1024);
90
- class SftpOperationTimeoutError extends Error {
91
- timeout;
92
- constructor(timeout) {
93
- super(`SFTP operation timed out after ${timeout}ms; remote transfer state is unknown`);
94
- this.timeout = timeout;
95
- this.name = 'SftpOperationTimeoutError';
96
- }
97
- }
98
111
  function abortError(signal) {
99
112
  return signal.reason instanceof Error ? signal.reason : new Error('SFTP operation aborted');
100
113
  }
@@ -160,24 +173,35 @@ async function runWithConcurrency(items, limit, worker) {
160
173
  function quoteRsyncSshArg(value) {
161
174
  return escapeShellArg(String(value));
162
175
  }
163
- function getAllowListStatus(localPath) {
176
+ function configuredAllowDirectories() {
164
177
  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) {
178
+ const configuredPaths = allowEnv?.split(path.delimiter).filter((item) => item.trim().length > 0) ?? [];
179
+ return {
180
+ configured: configuredPaths.length > 0,
181
+ directories: configuredPaths.flatMap((directory) => {
182
+ try {
183
+ return [fs.realpathSync(directory)];
184
+ }
185
+ catch {
186
+ return [];
187
+ }
188
+ }),
189
+ };
190
+ }
191
+ function isPathInsideDirectory(directory, targetPath) {
192
+ const relative = path.relative(directory, targetPath);
193
+ return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
194
+ }
195
+ function getAllowListStatus(localPath) {
196
+ const allowList = configuredAllowDirectories();
197
+ if (!allowList.configured) {
167
198
  return { configured: false };
168
199
  }
169
200
  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 };
201
+ return {
202
+ configured: true,
203
+ matched: allowList.directories.some((directory) => isPathInsideDirectory(directory, resolvedLocal)),
204
+ };
181
205
  }
182
206
  function validateLocalPathAgainstAllowList(localPath) {
183
207
  const allowList = getAllowListStatus(localPath);
@@ -185,6 +209,9 @@ function validateLocalPathAgainstAllowList(localPath) {
185
209
  throw new Error('localPath 不在 SSH_MCP_FILE_OPS_ALLOW_DIRS 允许目录内');
186
210
  }
187
211
  }
212
+ export function validateLocalPathPolicy(localPath) {
213
+ validateLocalPathAgainstAllowList(expandTilde(localPath));
214
+ }
188
215
  function resolvePathOrAncestor(p) {
189
216
  const absolute = path.isAbsolute(p) ? p : path.resolve(p);
190
217
  try {
@@ -205,6 +232,39 @@ function resolvePathOrAncestor(p) {
205
232
  return absolute;
206
233
  }
207
234
  }
235
+ function validateLocalUploadSource(localPath, followSymlinks, symlinkError) {
236
+ const expandedPath = expandTilde(localPath);
237
+ validateLocalPathAgainstAllowList(expandedPath);
238
+ if (!fs.existsSync(expandedPath)) {
239
+ throw new Error(`Local source does not exist: ${expandedPath}`);
240
+ }
241
+ const linkStats = fs.lstatSync(expandedPath);
242
+ if (linkStats.isSymbolicLink() && !followSymlinks) {
243
+ throw new Error(symlinkError);
244
+ }
245
+ if (followSymlinks && getAllowListStatus(expandedPath).configured) {
246
+ throw new Error('followSymlinks=true cannot be combined with SSH_MCP_FILE_OPS_ALLOW_DIRS because ' +
247
+ 'symlink targets can change during transfer');
248
+ }
249
+ return {
250
+ expandedPath,
251
+ linkStats,
252
+ stats: linkStats.isSymbolicLink() ? fs.statSync(expandedPath) : linkStats,
253
+ };
254
+ }
255
+ export function validateUploadFileSource(localPath) {
256
+ const source = validateLocalUploadSource(localPath, false, 'Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)');
257
+ if (source.stats.isDirectory()) {
258
+ throw new Error('UPLOAD_PATH_IS_DIRECTORY: localPath is a directory, use ssh_sync for directory upload');
259
+ }
260
+ if (!source.stats.isFile()) {
261
+ throw new Error('UPLOAD_PATH_IS_NOT_FILE: localPath is not a regular file');
262
+ }
263
+ return source;
264
+ }
265
+ export function validateSyncUploadSource(localPath, followSymlinks = false) {
266
+ return validateLocalUploadSource(localPath, followSymlinks, 'Refusing to sync a top-level symlink; set followSymlinks=true to traverse its target');
267
+ }
208
268
  export function probeLocalPath(localPath, followSymlinks = false) {
209
269
  const expanded = expandTilde(localPath);
210
270
  const resolvedPath = resolvePathOrAncestor(expanded);
@@ -231,8 +291,17 @@ export function probeLocalPath(localPath, followSymlinks = false) {
231
291
  /**
232
292
  * sftp.stat 的 Promise 包装
233
293
  */
234
- function sftpStat(sftp, remotePath) {
235
- return new Promise((resolve, reject) => {
294
+ async function getSftpWithinDeadline(alias, timeout) {
295
+ const request = sessionManager.getSftp(alias);
296
+ return withSftpOperationTimeout(request, timeout, () => {
297
+ void request.then((sftp) => sftp.end(), () => undefined);
298
+ });
299
+ }
300
+ function withSftpDeadline(sftp, operation, timeout) {
301
+ return withSftpOperationTimeout(operation, timeout, () => sftp.end());
302
+ }
303
+ function sftpStat(sftp, remotePath, timeout) {
304
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
236
305
  sftp.stat(remotePath, (err, stats) => {
237
306
  if (err) {
238
307
  reject(err);
@@ -241,7 +310,7 @@ function sftpStat(sftp, remotePath) {
241
310
  resolve(stats);
242
311
  }
243
312
  });
244
- });
313
+ }), timeout);
245
314
  }
246
315
  function isSftpMissingError(error) {
247
316
  if (!error || typeof error !== 'object') {
@@ -254,6 +323,9 @@ function isSftpMissingError(error) {
254
323
  const message = error instanceof Error ? error.message : String(error);
255
324
  return /no such file|not found/i.test(message);
256
325
  }
326
+ function isLocalMissingError(error) {
327
+ return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
328
+ }
257
329
  async function sftpExists(sftp, remotePath) {
258
330
  try {
259
331
  await sftpStat(sftp, remotePath);
@@ -267,7 +339,7 @@ async function sftpExists(sftp, remotePath) {
267
339
  }
268
340
  }
269
341
  async function remoteExists(alias, remotePath) {
270
- const sftp = await sessionManager.getSftp(alias);
342
+ const sftp = await getSftpWithinDeadline(alias);
271
343
  try {
272
344
  return await sftpExists(sftp, remotePath);
273
345
  }
@@ -275,6 +347,76 @@ async function remoteExists(alias, remotePath) {
275
347
  sftp.end();
276
348
  }
277
349
  }
350
+ export async function hashRemoteFileDigest(alias, remotePath, algorithm) {
351
+ const sftp = await getSftpWithinDeadline(alias);
352
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
353
+ const hash = createHash(algorithm);
354
+ const stream = sftp.createReadStream(remotePath);
355
+ let settled = false;
356
+ const finish = (error) => {
357
+ if (settled) {
358
+ return;
359
+ }
360
+ settled = true;
361
+ sftp.end();
362
+ if (error) {
363
+ reject(error);
364
+ }
365
+ else {
366
+ resolve(hash.digest('hex'));
367
+ }
368
+ };
369
+ stream.on('data', (chunk) => hash.update(chunk));
370
+ stream.once('error', finish);
371
+ stream.once('end', () => finish());
372
+ }));
373
+ }
374
+ export class RemoteRenameNotStartedError extends Error {
375
+ constructor(message) {
376
+ super(message);
377
+ this.name = 'RemoteRenameNotStartedError';
378
+ }
379
+ }
380
+ export async function renameRemoteFile(alias, sourcePath, targetPath, replaceExisting = false, timeout) {
381
+ const sftp = await getSftpWithinDeadline(alias, timeout);
382
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
383
+ const callback = (error) => {
384
+ sftp.end();
385
+ if (error) {
386
+ reject(error);
387
+ }
388
+ else {
389
+ resolve();
390
+ }
391
+ };
392
+ try {
393
+ if (replaceExisting) {
394
+ sftp.ext_openssh_rename(sourcePath, targetPath, callback);
395
+ }
396
+ else {
397
+ sftp.rename(sourcePath, targetPath, callback);
398
+ }
399
+ }
400
+ catch (error) {
401
+ sftp.end();
402
+ reject(new RemoteRenameNotStartedError(`SFTP rename request was not sent: ${error instanceof Error ? error.message : String(error)}`));
403
+ }
404
+ }), timeout);
405
+ }
406
+ export async function removeRemoteFile(alias, remotePath) {
407
+ const sftp = await getSftpWithinDeadline(alias);
408
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
409
+ sftp.unlink(remotePath, (error) => {
410
+ sftp.end();
411
+ if (error && !isSftpMissingError(error)) {
412
+ reject(error);
413
+ }
414
+ else {
415
+ resolve();
416
+ }
417
+ });
418
+ }));
419
+ }
278
420
  /**
279
421
  * 带进度追踪的流传输
280
422
  */
@@ -329,14 +471,19 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
329
471
  readStream.on('error', (err) => cleanup(err));
330
472
  writeStream.on('error', (err) => cleanup(err));
331
473
  writeStream.on('close', () => {
332
- if (!settled) {
333
- settled = true;
334
- detachAbort();
335
- if (closeSftp) {
336
- sftp.end();
337
- }
338
- resolve({ success: true, size: totalSize });
474
+ if (settled) {
475
+ return;
339
476
  }
477
+ if (transferred !== totalSize) {
478
+ cleanup(new Error(`Transfer size mismatch: expected ${totalSize} bytes, received ${transferred}`));
479
+ return;
480
+ }
481
+ settled = true;
482
+ detachAbort();
483
+ if (closeSftp) {
484
+ sftp.end();
485
+ }
486
+ resolve({ success: true, size: totalSize });
340
487
  });
341
488
  if (signal?.aborted) {
342
489
  cleanup(abortError(signal));
@@ -346,54 +493,107 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
346
493
  readStream.pipe(writeStream);
347
494
  });
348
495
  }
496
+ export class UploadFileError extends Error {
497
+ remoteCreated;
498
+ details;
499
+ constructor(message, remoteCreated, options) {
500
+ super(message, options);
501
+ this.remoteCreated = remoteCreated;
502
+ this.name = 'UploadFileError';
503
+ const cause = options?.cause;
504
+ if (cause && typeof cause === 'object' && 'details' in cause) {
505
+ this.details = cause.details;
506
+ }
507
+ }
508
+ }
349
509
  /**
350
510
  * 上传文件
351
511
  */
352
- export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal) {
512
+ export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal, followSymlinks = false, exclusive = false, timeout) {
353
513
  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()) {
514
+ const source = followSymlinks
515
+ ? validateLocalUploadSource(localPath, true, 'Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)')
516
+ : validateUploadFileSource(localPath);
517
+ localPath = source.expandedPath;
518
+ const stats = source.stats;
519
+ if (stats.isDirectory()) {
366
520
  throw new Error('UPLOAD_PATH_IS_DIRECTORY: localPath is a directory, use ssh_sync for directory upload');
367
521
  }
368
- if (!lstats.isFile()) {
522
+ if (!stats.isFile()) {
369
523
  throw new Error('UPLOAD_PATH_IS_NOT_FILE: localPath is not a regular file');
370
524
  }
371
- 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') };
525
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
526
+ const totalSize = stats.size;
527
+ const safeCreateMode = (createMode ?? stats.mode) & 0o777;
528
+ const writeStream = sftp.createWriteStream(remotePath, { mode: safeCreateMode, flags: exclusive ? 'wx' : 'w' });
529
+ let remoteCreated = false;
530
+ writeStream.once('open', () => {
531
+ remoteCreated = true;
532
+ });
533
+ try {
534
+ const result = await withSftpDeadline(sftp, pipeWithProgress(fs.createReadStream(localPath), writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), timeout);
535
+ return { ...result, createMode: safeCreateMode.toString(8).padStart(4, '0') };
536
+ }
537
+ catch (error) {
538
+ throw new UploadFileError(error instanceof Error ? error.message : String(error), remoteCreated, {
539
+ cause: error,
540
+ });
541
+ }
542
+ }
543
+ async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, closeSftpOnFailure, timeout) {
544
+ let readStream;
545
+ try {
546
+ const totalSize = (await sftpStat(sftp, remotePath, timeout)).size;
547
+ if (!fs.existsSync(localDir)) {
548
+ fs.mkdirSync(localDir, { recursive: true });
549
+ }
550
+ readStream = sftp.createReadStream(remotePath);
551
+ return {
552
+ totalSize,
553
+ readStream,
554
+ writeStream: fs.createWriteStream(temporaryPath, { flags: 'wx' }),
555
+ };
556
+ }
557
+ catch (error) {
558
+ try {
559
+ ;
560
+ readStream?.destroy?.();
561
+ }
562
+ catch {
563
+ /* ignore cleanup errors while preserving the transfer setup error */
564
+ }
565
+ if (closeSftpOnFailure) {
566
+ sftp.end();
567
+ }
568
+ throw error;
569
+ }
376
570
  }
377
571
  /**
378
572
  * 下载文件
379
573
  */
380
- export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp, signal) {
574
+ export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp, signal, timeout) {
381
575
  throwIfAborted(signal);
382
576
  localPath = expandTilde(localPath);
383
577
  validateLocalPathAgainstAllowList(localPath);
384
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
578
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
579
+ const localDir = path.dirname(localPath);
580
+ const temporaryPath = path.join(localDir, `.${path.basename(localPath)}.mcp-tmp-${process.pid}-${randomBytes(8).toString('hex')}`);
385
581
  try {
386
- const totalSize = (await sftpStat(sftp, remotePath)).size;
387
- // 确保本地目录存在
388
- const localDir = path.dirname(localPath);
389
- if (!fs.existsSync(localDir)) {
390
- fs.mkdirSync(localDir, { recursive: true });
391
- }
392
- return await pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress, !sharedSftp, signal);
582
+ const { totalSize, readStream, writeStream } = await prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, !sharedSftp, timeout);
583
+ const result = await withSftpDeadline(sftp, pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), timeout);
584
+ await fs.promises.rename(temporaryPath, localPath);
585
+ return { ...result, atomic: true };
393
586
  }
394
587
  catch (error) {
395
- if (!sharedSftp) {
396
- sftp.end();
588
+ try {
589
+ await fs.promises.unlink(temporaryPath);
590
+ }
591
+ catch (cleanupError) {
592
+ if (!isLocalMissingError(cleanupError)) {
593
+ throw new AggregateError([error, cleanupError], 'Download failed and temporary file cleanup failed', {
594
+ cause: cleanupError,
595
+ });
596
+ }
397
597
  }
398
598
  throw error;
399
599
  }
@@ -468,24 +668,26 @@ export function buildLineRangeAwkProgram(start, end) {
468
668
  `NR > ${end} { if (full_body) { byte_limit = 1 } saw_after = 1; exit }`,
469
669
  'END {',
470
670
  ' if (full_body && final_terminated) { byte_limit = 1 }',
471
- ' printf "__MCP_LINE_META__%d:%d:%d:%d:%d\\n", actual_start, actual_end, written, byte_limit, saw_after > "/dev/stderr"',
671
+ ' printf "__MCP_LINE_META__%d:%d:%d:%d:%d\\n",' +
672
+ ' actual_start, actual_end, written, byte_limit, saw_after > "/dev/stderr"',
472
673
  '}',
473
674
  ].join('\n');
474
675
  }
475
- async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange) {
676
+ async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange, timeout) {
476
677
  const { start, end } = parseLineRange(lineRange);
477
678
  const awkProgram = buildLineRangeAwkProgram(start, end);
478
679
  const escapedPath = escapeShellArg(remotePath);
479
680
  const command = [
480
681
  `last_byte=$(tail -c 1 -- ${escapedPath} 2>/dev/null | od -An -tu1 | tr -d ' ')`,
481
682
  'if [ "$last_byte" = "10" ]; then terminated=1; else terminated=0; fi',
482
- `LC_ALL=C awk -v max=${maxBytes} -v final_terminated="$terminated" ${escapeShellArg(awkProgram)} ${escapedPath} | base64 | tr -d '\\n'`,
683
+ `LC_ALL=C awk -v max=${maxBytes} -v final_terminated="$terminated" ` +
684
+ `${escapeShellArg(awkProgram)} ${escapedPath} | base64 | tr -d '\\n'`,
483
685
  'status=${PIPESTATUS[0]}',
484
686
  'printf "__MCP_LINE_END__%s\\n" "$terminated" >&2',
485
687
  'exit "$status"',
486
688
  ].join('; ');
487
689
  const result = await sessionManager.exec(alias, `bash -c ${escapeShellArg(command)}`, {
488
- timeout: 30000,
690
+ timeout: timeout ?? 30000,
489
691
  useLoginUser: true,
490
692
  maxOutputSize: Math.ceil(maxBytes / 3) * 4 + 4096,
491
693
  });
@@ -540,10 +742,10 @@ async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange)
540
742
  export async function readFile(alias, remotePath, options) {
541
743
  const readOptions = normalizeReadFileOptions(options);
542
744
  validateReadFileOptions(readOptions);
543
- const sftp = await sessionManager.getSftp(alias);
745
+ const sftp = await getSftpWithinDeadline(alias, readOptions.timeout);
544
746
  let actualSize;
545
747
  try {
546
- actualSize = (await sftpStat(sftp, remotePath)).size;
748
+ actualSize = (await sftpStat(sftp, remotePath, readOptions.timeout)).size;
547
749
  }
548
750
  catch (error) {
549
751
  sftp.end();
@@ -551,16 +753,16 @@ export async function readFile(alias, remotePath, options) {
551
753
  }
552
754
  if (readOptions.lineRange) {
553
755
  sftp.end();
554
- return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange);
756
+ return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange, readOptions.timeout);
555
757
  }
556
758
  if (actualSize === 0) {
557
759
  sftp.end();
558
760
  return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full');
559
761
  }
560
- const readOffset = readOptions.tail
762
+ const requestedOffset = readOptions.tail
561
763
  ? Math.max(0, actualSize - readOptions.maxBytes)
562
764
  : Math.min(readOptions.offset ?? 0, actualSize);
563
- const readSize = Math.min(actualSize - readOffset, readOptions.maxBytes);
765
+ const readSize = Math.min(actualSize - requestedOffset, readOptions.maxBytes);
564
766
  const sampleKind = readOptions.tail
565
767
  ? 'tail'
566
768
  : readOptions.offset !== undefined
@@ -570,46 +772,74 @@ export async function readFile(alias, remotePath, options) {
570
772
  : 'head';
571
773
  if (readSize === 0) {
572
774
  sftp.end();
573
- return emptyReadResult(actualSize, sampleKind, readOffset);
775
+ return emptyReadResult(actualSize, sampleKind, requestedOffset);
574
776
  }
575
- return new Promise((resolve, reject) => {
777
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
576
778
  const chunks = [];
779
+ let settled = false;
780
+ const finish = (error) => {
781
+ if (settled) {
782
+ return;
783
+ }
784
+ settled = true;
785
+ sftp.end();
786
+ if (error) {
787
+ reject(error);
788
+ return;
789
+ }
790
+ try {
791
+ const buffer = Buffer.concat(chunks);
792
+ let contentStart = 0;
793
+ if (readOptions.tail) {
794
+ while (contentStart < buffer.length && isUtf8ContinuationByte(buffer[contentStart])) {
795
+ ++contentStart;
796
+ }
797
+ }
798
+ else {
799
+ ensureUtf8Boundary(buffer, 0, 'offset');
800
+ }
801
+ const contentEnd = utf8SafeEnd(buffer, contentStart, buffer.length, remotePath, requestedOffset + buffer.length < actualSize);
802
+ const contentBuffer = buffer.subarray(contentStart, contentEnd);
803
+ const actualReadOffset = requestedOffset + contentStart;
804
+ const nextOffset = requestedOffset + contentEnd;
805
+ const remainingBytes = Math.max(0, actualSize - nextOffset);
806
+ resolve({
807
+ content: contentBuffer.toString('utf-8'),
808
+ size: actualSize,
809
+ total_size: actualSize,
810
+ read_offset: actualReadOffset,
811
+ requested_offset: requestedOffset,
812
+ read_bytes: contentBuffer.length,
813
+ read_end: nextOffset,
814
+ next_offset: nextOffset,
815
+ remaining_bytes: remainingBytes,
816
+ sample_kind: sampleKind,
817
+ truncated: actualReadOffset > 0 || remainingBytes > 0,
818
+ });
819
+ }
820
+ catch (processingError) {
821
+ reject(processingError);
822
+ }
823
+ };
577
824
  const readStream = sftp.createReadStream(remotePath, {
578
- start: readOffset,
579
- end: readOffset + readSize - 1,
825
+ start: requestedOffset,
826
+ end: requestedOffset + readSize - 1,
580
827
  });
581
828
  readStream.on('data', (chunk) => {
582
829
  chunks.push(chunk);
583
830
  });
584
- readStream.on('end', () => {
585
- sftp.end();
586
- const buffer = Buffer.concat(chunks);
587
- const remainingBytes = Math.max(0, actualSize - readOffset - buffer.length);
588
- resolve({
589
- content: buffer.toString('utf-8'),
590
- size: actualSize,
591
- total_size: actualSize,
592
- read_offset: readOffset,
593
- read_bytes: buffer.length,
594
- remaining_bytes: remainingBytes,
595
- sample_kind: sampleKind,
596
- truncated: readOffset > 0 || remainingBytes > 0,
597
- });
598
- });
599
- readStream.on('error', (err) => {
600
- sftp.end();
601
- reject(err);
602
- });
603
- });
831
+ readStream.once('end', () => finish());
832
+ readStream.once('error', (error) => finish(error));
833
+ }), readOptions.timeout);
604
834
  }
605
835
  /**
606
836
  * 写入远程文件
607
837
  */
608
- export async function writeFile(alias, remotePath, content, append = false) {
609
- const sftp = await sessionManager.getSftp(alias);
838
+ export async function writeFile(alias, remotePath, content, append = false, timeout) {
839
+ const sftp = await getSftpWithinDeadline(alias, timeout);
610
840
  const flags = append ? 'a' : 'w';
611
841
  const contentBuffer = Buffer.from(content, 'utf-8');
612
- return new Promise((resolve, reject) => {
842
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
613
843
  const writeStream = sftp.createWriteStream(remotePath, { flags });
614
844
  writeStream.on('close', () => {
615
845
  sftp.end();
@@ -621,15 +851,25 @@ export async function writeFile(alias, remotePath, content, append = false) {
621
851
  });
622
852
  writeStream.write(contentBuffer);
623
853
  writeStream.end();
624
- });
854
+ }), timeout);
855
+ }
856
+ function validateSftpEntryName(filename) {
857
+ if (filename.length === 0 ||
858
+ filename === '.' ||
859
+ filename === '..' ||
860
+ filename.includes('\0') ||
861
+ filename.includes('/') ||
862
+ filename.includes('\\')) {
863
+ throw new Error('SFTP directory listing returned an unsafe entry name');
864
+ }
625
865
  }
626
866
  /**
627
867
  * 列出目录内容
628
868
  */
629
- export async function listDir(alias, remotePath, showHidden = false, sharedSftp) {
630
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
869
+ export async function listDir(alias, remotePath, showHidden = false, sharedSftp, timeout) {
870
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
631
871
  const closeWhenDone = !sharedSftp;
632
- return new Promise((resolve, reject) => {
872
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
633
873
  sftp.readdir(remotePath, (err, list) => {
634
874
  if (err) {
635
875
  if (closeWhenDone) {
@@ -638,6 +878,18 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp)
638
878
  reject(err);
639
879
  return;
640
880
  }
881
+ try {
882
+ for (const item of list) {
883
+ validateSftpEntryName(item.filename);
884
+ }
885
+ }
886
+ catch (error) {
887
+ if (closeWhenDone) {
888
+ sftp.end();
889
+ }
890
+ reject(error);
891
+ return;
892
+ }
641
893
  const files = list
642
894
  .filter((item) => showHidden || !item.filename.startsWith('.'))
643
895
  .map((item) => ({
@@ -665,14 +917,14 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp)
665
917
  }
666
918
  resolve(files);
667
919
  });
668
- });
920
+ }), timeout);
669
921
  }
670
922
  /**
671
923
  * 获取文件信息
672
924
  */
673
- export async function getFileInfo(alias, remotePath) {
674
- const sftp = await sessionManager.getSftp(alias);
675
- return new Promise((resolve, reject) => {
925
+ export async function getFileInfo(alias, remotePath, timeout) {
926
+ const sftp = await getSftpWithinDeadline(alias, timeout);
927
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
676
928
  sftp.stat(remotePath, (err, stats) => {
677
929
  sftp.end();
678
930
  if (err) {
@@ -693,38 +945,87 @@ export async function getFileInfo(alias, remotePath) {
693
945
  atime: new Date(stats.atime * 1000),
694
946
  });
695
947
  });
696
- });
948
+ }), timeout);
949
+ }
950
+ function sftpMkdir(sftp, remotePath, timeout) {
951
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
952
+ sftp.mkdir(remotePath, (error) => {
953
+ if (error) {
954
+ reject(error);
955
+ }
956
+ else {
957
+ resolve();
958
+ }
959
+ });
960
+ }), timeout);
961
+ }
962
+ async function ensureSftpDirectory(sftp, remotePath, timeout) {
963
+ const normalizedPath = path.posix.normalize(remotePath);
964
+ if (normalizedPath === '/' || normalizedPath === '.') {
965
+ return;
966
+ }
967
+ let existingMode;
968
+ try {
969
+ existingMode = (await sftpStat(sftp, normalizedPath, timeout)).mode;
970
+ }
971
+ catch (error) {
972
+ if (!isSftpMissingError(error)) {
973
+ throw error;
974
+ }
975
+ }
976
+ if (existingMode !== undefined) {
977
+ if ((existingMode & S_IFMT) !== S_IFDIR) {
978
+ throw new Error(`Remote path exists and is not a directory: ${normalizedPath}`);
979
+ }
980
+ return;
981
+ }
982
+ const parent = path.posix.dirname(normalizedPath);
983
+ if (parent !== normalizedPath) {
984
+ await ensureSftpDirectory(sftp, parent, timeout);
985
+ }
986
+ try {
987
+ await sftpMkdir(sftp, normalizedPath, timeout);
988
+ }
989
+ catch (error) {
990
+ try {
991
+ const stats = await sftpStat(sftp, normalizedPath, timeout);
992
+ if ((stats.mode & S_IFMT) === S_IFDIR) {
993
+ return;
994
+ }
995
+ }
996
+ catch {
997
+ // 保留原 mkdir 错误
998
+ }
999
+ throw error;
1000
+ }
697
1001
  }
698
1002
  /**
699
1003
  * 创建目录
700
1004
  */
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}`);
708
- }
709
- return true;
710
- }
711
- const sftp = await sessionManager.getSftp(alias);
712
- return new Promise((resolve, reject) => {
713
- sftp.mkdir(remotePath, (err) => {
714
- sftp.end();
715
- if (err) {
716
- reject(err);
1005
+ export async function mkdir(alias, remotePath, recursive = false, sharedSftp, timeout) {
1006
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
1007
+ return withSftpDeadline(sftp, (async () => {
1008
+ try {
1009
+ if (recursive) {
1010
+ await ensureSftpDirectory(sftp, remotePath, timeout);
717
1011
  }
718
1012
  else {
719
- resolve(true);
1013
+ await sftpMkdir(sftp, remotePath, timeout);
720
1014
  }
721
- });
722
- });
1015
+ return true;
1016
+ }
1017
+ finally {
1018
+ if (!sharedSftp) {
1019
+ sftp.end();
1020
+ }
1021
+ }
1022
+ })(), timeout);
723
1023
  }
724
1024
  /**
725
1025
  * 检查远程是否安装 rsync
726
1026
  */
727
1027
  export async function checkRsync(alias, timeout = 10_000) {
1028
+ const generation = getRsyncGeneration(alias);
728
1029
  const cached = rsyncCache.get(alias);
729
1030
  if (cached !== undefined && cached.expiresAt > Date.now()) {
730
1031
  return cached.value;
@@ -737,6 +1038,15 @@ export async function checkRsync(alias, timeout = 10_000) {
737
1038
  maxOutputSize: 4096,
738
1039
  });
739
1040
  const duration = Date.now() - startedAt;
1041
+ if (!isCurrentRsyncGeneration(alias, generation)) {
1042
+ return {
1043
+ available: false,
1044
+ status: 'error',
1045
+ duration,
1046
+ retryable: true,
1047
+ error: `SSH session '${alias}' changed during rsync probe`,
1048
+ };
1049
+ }
740
1050
  if (result.success && result.exitCode === 0 && result.stdout.trim().length > 0) {
741
1051
  const probe = {
742
1052
  available: true,
@@ -817,18 +1127,11 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
817
1127
  if (remotePath === '~' || remotePath.startsWith('~/')) {
818
1128
  throw new Error('remotePath must be absolute or relative to the SSH working directory; ~ is not supported');
819
1129
  }
820
- const capabilityStartedAt = Date.now();
821
- const capability = sessionManager.getExternalTransferCapability(alias);
822
1130
  let sourceIsDirectory;
823
1131
  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();
1132
+ const source = validateSyncUploadSource(localPath, options.followSymlinks === true);
1133
+ localPath = source.expandedPath;
1134
+ sourceIsDirectory = source.stats.isDirectory();
832
1135
  }
833
1136
  else {
834
1137
  sourceIsDirectory = (await getFileInfo(alias, remotePath)).isDirectory;
@@ -836,6 +1139,9 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
836
1139
  if (sourceIsDirectory && options.recursive === false) {
837
1140
  throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
838
1141
  }
1142
+ const capabilityStartedAt = Date.now();
1143
+ const rsyncGeneration = getRsyncGeneration(alias);
1144
+ const capability = sessionManager.getExternalTransferCapability(alias);
839
1145
  const preflightTimeout = options.preflightTimeout ?? 10_000;
840
1146
  const rsyncProbe = capability.rsyncEligible
841
1147
  ? await checkRsync(alias, preflightTimeout)
@@ -846,6 +1152,7 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
846
1152
  retryable: false,
847
1153
  reason: capability.decisionReason,
848
1154
  };
1155
+ assertCurrentRsyncGeneration(alias, rsyncGeneration);
849
1156
  const resolvedOptions = { ...options, sourceIsDirectory };
850
1157
  const capabilityDuration = Date.now() - capabilityStartedAt;
851
1158
  const selectedTransport = capability.rsyncEligible && rsyncProbe?.available ? 'rsync' : 'sftp';
@@ -860,7 +1167,7 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
860
1167
  : 'remote_rsync_probe_failed';
861
1168
  const operationStartedAt = Date.now();
862
1169
  const result = selectedTransport === 'rsync'
863
- ? await syncWithRsync(alias, localPath, remotePath, direction, resolvedOptions, capability)
1170
+ ? await syncWithRsync(alias, localPath, remotePath, direction, resolvedOptions, capability, rsyncGeneration)
864
1171
  : await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, resolvedOptions);
865
1172
  const operationDuration = Date.now() - operationStartedAt;
866
1173
  const operationStatus = result.operationStatus ?? (result.success ? 'completed' : 'failed');
@@ -892,9 +1199,11 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
892
1199
  * 使用 rsync 同步文件
893
1200
  * 通过本地执行 rsync 连接到远程(需要密钥认证或 ssh-agent)
894
1201
  */
895
- async function syncWithRsync(alias, localPath, remotePath, direction, options, capability) {
1202
+ async function syncWithRsync(alias, localPath, remotePath, direction, options, capability, generation) {
1203
+ assertCurrentRsyncGeneration(alias, generation);
896
1204
  const checkCommand = os.platform() === 'win32' ? 'where' : 'which';
897
1205
  const checkResult = await runLocalProcess(checkCommand, ['rsync'], options.preflightTimeout ?? 10_000);
1206
+ assertCurrentRsyncGeneration(alias, generation);
898
1207
  if (checkResult.status !== 0) {
899
1208
  const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
900
1209
  return {
@@ -956,9 +1265,11 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
956
1265
  sshOptions.push('-i', capability.keyPath);
957
1266
  }
958
1267
  const destination = `${capability.username}@${capability.host}`;
1268
+ assertCurrentRsyncGeneration(alias, generation);
959
1269
  const connectStartedAt = Date.now();
960
1270
  const connectResult = await runLocalProcess('ssh', [...sshOptions, destination, 'true'], connectTimeout);
961
1271
  const connectDuration = Date.now() - connectStartedAt;
1272
+ assertCurrentRsyncGeneration(alias, generation);
962
1273
  if (connectResult.error || connectResult.status !== 0) {
963
1274
  const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
964
1275
  const fallbackReason = connectResult.timedOut ? 'rsync_connect_timeout' : 'rsync_connect_failed';
@@ -987,8 +1298,21 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
987
1298
  ? [...args, '-e', sshCmd, '--', rsyncLocalPath, remoteSpec]
988
1299
  : [...args, '-e', sshCmd, '--', remoteSpec, localPath];
989
1300
  try {
1301
+ assertCurrentRsyncGeneration(alias, generation);
990
1302
  const operationTimeout = options.operationTimeout ?? 600_000;
991
1303
  const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout);
1304
+ if (!isCurrentRsyncGeneration(alias, generation)) {
1305
+ return {
1306
+ success: false,
1307
+ method: 'rsync',
1308
+ connectDuration,
1309
+ connectStatus: 'completed',
1310
+ operationStatus: 'unknown',
1311
+ retryable: true,
1312
+ fallbackReason: 'ssh_session_changed',
1313
+ output: `SSH session '${alias}' changed during rsync; remote transfer state is unknown`,
1314
+ };
1315
+ }
992
1316
  if (result.error || result.status !== 0) {
993
1317
  const stderr = result.stderr.trim();
994
1318
  const reason = result.timedOut
@@ -1042,6 +1366,9 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1042
1366
  };
1043
1367
  }
1044
1368
  catch (e) {
1369
+ if (!isCurrentRsyncGeneration(alias, generation)) {
1370
+ throw e;
1371
+ }
1045
1372
  // rsync 启动异常发生在传输进程建立前,可安全改用 SFTP
1046
1373
  const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1047
1374
  const warning = `rsync 异常: ${e instanceof Error ? e.message : String(e)} | 已 fallback 到 SFTP(性能可能较差)`;
@@ -1168,31 +1495,17 @@ function hashLocalFile(filePath) {
1168
1495
  });
1169
1496
  }
1170
1497
  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
- };
1498
+ try {
1499
+ const digest = await hashRemoteFileDigest(alias, remotePath, 'sha256');
1500
+ return { status: 'available', digest, retryable: false };
1184
1501
  }
1185
- const digest = result.stdout.trim().split(/\s+/)[0];
1186
- if (!/^[a-fA-F0-9]{64}$/.test(digest)) {
1502
+ catch (error) {
1187
1503
  return {
1188
1504
  status: 'error',
1189
- exitCode: result.exitCode,
1190
- failureKind: result.failureKind,
1191
- retryable: false,
1192
- error: 'remote SHA-256 command returned an invalid digest',
1505
+ retryable: true,
1506
+ error: error instanceof Error ? error.message : String(error),
1193
1507
  };
1194
1508
  }
1195
- return { status: 'available', digest, retryable: false };
1196
1509
  }
1197
1510
  async function buildSingleFileVerification(alias, localPath, remotePath, direction) {
1198
1511
  try {
@@ -1209,8 +1522,6 @@ async function buildSingleFileVerification(alias, localPath, remotePath, directi
1209
1522
  failureStage: remoteHash.status === 'error' ? 'remote_hash' : undefined,
1210
1523
  retryable: remoteHash.retryable,
1211
1524
  error: remoteHash.error,
1212
- exitCode: remoteHash.exitCode,
1213
- failureKind: remoteHash.failureKind,
1214
1525
  hashAlgorithm: 'sha256',
1215
1526
  hashMatch: remoteHash.digest ? localSha256 === remoteHash.digest : undefined,
1216
1527
  local: {
@@ -1346,7 +1657,13 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1346
1657
  };
1347
1658
  }
1348
1659
  if (stats.isDirectory() && options.recursive === false) {
1349
- throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1660
+ return {
1661
+ success: false,
1662
+ method: 'sftp',
1663
+ operationStatus: 'failed',
1664
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1665
+ output: 'recursive=false does not support directories; use a file source or enable recursion',
1666
+ };
1350
1667
  }
1351
1668
  if (stats.isDirectory()) {
1352
1669
  const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal);
@@ -1354,7 +1671,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1354
1671
  }
1355
1672
  const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath);
1356
1673
  const existed = await remoteExists(alias, targetRemotePath);
1357
- const { size } = await uploadFile(alias, localPath, targetRemotePath, undefined, undefined, undefined, options.signal);
1674
+ const { size } = await uploadFile(alias, localPath, targetRemotePath, undefined, undefined, undefined, options.signal, options.followSymlinks === true);
1358
1675
  return {
1359
1676
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
1360
1677
  verification: await buildSingleFileVerification(alias, localPath, targetRemotePath, 'upload'),
@@ -1363,7 +1680,13 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1363
1680
  // download
1364
1681
  const info = await getFileInfo(alias, remotePath);
1365
1682
  if (info.isDirectory && options.recursive === false) {
1366
- throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1683
+ return {
1684
+ success: false,
1685
+ method: 'sftp',
1686
+ operationStatus: 'failed',
1687
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1688
+ output: 'recursive=false is not supported for directory sources; use a file source or enable recursion',
1689
+ };
1367
1690
  }
1368
1691
  if (info.isDirectory) {
1369
1692
  const result = await downloadDirectory(alias, remotePath, localPath, options.exclude, undefined, {
@@ -1410,7 +1733,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1410
1733
  const accumulator = new DirectoryTransferAccumulator();
1411
1734
  recordSftpDirectory(traversal, depth, localPath);
1412
1735
  const ownSftp = !sharedSftp;
1413
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
1736
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
1414
1737
  const activeDirectories = (traversal.activeDirectories ??= new Set());
1415
1738
  const realPath = fs.realpathSync(localPath);
1416
1739
  if (activeDirectories.has(realPath)) {
@@ -1422,7 +1745,8 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1422
1745
  }
1423
1746
  activeDirectories.add(realPath);
1424
1747
  try {
1425
- await mkdir(alias, remotePath, true);
1748
+ validateLocalPathAgainstAllowList(localPath);
1749
+ await mkdir(alias, remotePath, true, sftp);
1426
1750
  throwIfAborted(signal);
1427
1751
  const items = fs.readdirSync(localPath);
1428
1752
  // 先分类:目录串行(递归会自己并发文件);文件并发上传,避免单 SSH session 上 channel 过多
@@ -1457,7 +1781,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1457
1781
  const itemRemotePath = path.posix.join(remotePath, name);
1458
1782
  const existed = await sftpExists(sftp, itemRemotePath);
1459
1783
  try {
1460
- await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal);
1784
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal, followSymlinks);
1461
1785
  accumulator.addFile(stats.size, existed);
1462
1786
  }
1463
1787
  catch (error) {
@@ -1489,7 +1813,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1489
1813
  const accumulator = new DirectoryTransferAccumulator();
1490
1814
  recordSftpDirectory(traversal, depth, remotePath);
1491
1815
  const ownSftp = !sharedSftp;
1492
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
1816
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
1493
1817
  try {
1494
1818
  if (!fs.existsSync(localPath)) {
1495
1819
  fs.mkdirSync(localPath, { recursive: true });