@pyrokine/mcp-ssh 3.1.0 → 3.2.0

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.
@@ -1,18 +1,44 @@
1
1
  import { createHash } from 'crypto';
2
2
  import * as fs from 'fs';
3
3
  import * as path from 'path';
4
- import { remoteJoin } from './remote-platform.js';
5
4
  import { formatFileMode } from './file-mode.js';
5
+ import { remoteJoin } from './remote-platform.js';
6
+ import { withSftpOperationTimeout } from './sftp-timeout.js';
6
7
  import { escapeShellArg } from './tools/utils.js';
8
+ export function remainingVerificationTimeout(control) {
9
+ if (control.signal.aborted) {
10
+ throw control.signal.reason;
11
+ }
12
+ const remaining = control.deadline - Date.now();
13
+ if (remaining <= 0) {
14
+ throw new Error('directory verification exhausted the sync operation timeout');
15
+ }
16
+ return remaining;
17
+ }
18
+ async function withDirectoryVerificationBudget(action, control, cancel) {
19
+ if (!control) {
20
+ return action();
21
+ }
22
+ const timeout = remainingVerificationTimeout(control);
23
+ const result = await withSftpOperationTimeout(action(), timeout, () => cancel?.(), control.signal);
24
+ remainingVerificationTimeout(control);
25
+ return result;
26
+ }
7
27
  export const DIRECTORY_VERIFY_MAX_ENTRIES = 50_000;
8
28
  export const DIRECTORY_VERIFY_MAX_MISMATCHES = 20;
9
29
  export const DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES = 256 * 1024 * 1024;
10
30
  export const DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
11
31
  export const DIRECTORY_VERIFY_MAX_FILE_BYTES = 4 * 1024 * 1024 * 1024;
12
32
  export const DIRECTORY_VERIFY_MAX_TOTAL_BYTES = 16 * 1024 * 1024 * 1024;
13
- function rootHash(entries) {
33
+ function rootHash(entries, control) {
34
+ if (control) {
35
+ remainingVerificationTimeout(control);
36
+ }
14
37
  const hash = createHash('sha256');
15
- for (const entry of [...entries].sort((a, b) => a.path.localeCompare(b.path))) {
38
+ for (const entry of [...entries].sort((a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path)))) {
39
+ if (control) {
40
+ remainingVerificationTimeout(control);
41
+ }
16
42
  hash.update(JSON.stringify({
17
43
  path: entry.path,
18
44
  type: entry.type,
@@ -23,26 +49,43 @@ function rootHash(entries) {
23
49
  }
24
50
  return hash.digest('hex');
25
51
  }
26
- async function hashFile(filePath, size, maxBytes) {
27
- const hash = createHash('sha256');
28
- let readBytes = 0;
29
- for await (const chunk of fs.createReadStream(filePath)) {
30
- readBytes += Buffer.byteLength(chunk);
31
- if (readBytes > maxBytes) {
32
- throw new Error('local file grew beyond directory manifest hash budget');
33
- }
34
- hash.update(chunk);
52
+ async function hashFile(filePath, size, maxBytes, control) {
53
+ if (control) {
54
+ remainingVerificationTimeout(control);
35
55
  }
36
- if (readBytes !== size) {
37
- throw new Error('local file changed during manifest hashing');
56
+ const stream = fs.createReadStream(filePath);
57
+ try {
58
+ return await withDirectoryVerificationBudget(async () => {
59
+ const hash = createHash('sha256');
60
+ let readBytes = 0;
61
+ for await (const chunk of stream) {
62
+ readBytes += Buffer.byteLength(chunk);
63
+ if (readBytes > maxBytes) {
64
+ throw new Error('local file grew beyond directory manifest hash budget');
65
+ }
66
+ hash.update(chunk);
67
+ }
68
+ if (readBytes !== size) {
69
+ throw new Error('local file changed during manifest hashing');
70
+ }
71
+ return hash.digest('hex');
72
+ }, control, () => {
73
+ stream.destroy();
74
+ });
75
+ }
76
+ finally {
77
+ stream.destroy();
38
78
  }
39
- return hash.digest('hex');
40
79
  }
41
- export function matchesDirectoryExclude(relativePath, patterns) {
80
+ export function matchesDirectoryExclude(relativePath, patterns, isDirectory = false) {
42
81
  const normalizedPath = relativePath.replace(/^\.\//, '').replace(/^\//, '');
43
82
  const basename = path.posix.basename(normalizedPath);
44
83
  return Boolean(patterns?.some((pattern) => {
45
- const normalizedPattern = pattern.replace(/^\//, '');
84
+ const directoryOnly = pattern.endsWith('/');
85
+ if (directoryOnly && !isDirectory) {
86
+ return false;
87
+ }
88
+ const normalizedPattern = pattern.replace(/^\//, '').replace(/\/$/, '');
46
89
  const candidate = normalizedPattern.includes('/') ? normalizedPath : basename;
47
90
  const matches = new Uint8Array(candidate.length + 1);
48
91
  matches[0] = 1;
@@ -72,11 +115,11 @@ export function matchesDirectoryExclude(relativePath, patterns) {
72
115
  return matches[candidate.length] === 1;
73
116
  }));
74
117
  }
75
- export async function createLocalDirectoryManifest(rootPath, request, exclude, followSymlinks = false) {
118
+ export async function createLocalDirectoryManifest(rootPath, request, exclude, followSymlinks = false, control) {
76
119
  const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
77
120
  const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
78
121
  const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
79
- const rootStats = await fs.promises.stat(rootPath);
122
+ const rootStats = await withDirectoryVerificationBudget(() => fs.promises.stat(rootPath), control);
80
123
  if (!rootStats.isDirectory()) {
81
124
  throw new Error(`directory verification root is not a directory: ${rootPath}`);
82
125
  }
@@ -96,29 +139,37 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
96
139
  const unsupportedSamples = [];
97
140
  let limitReason;
98
141
  const visit = async (currentPath, relativeBase) => {
99
- const realPath = await fs.promises.realpath(currentPath);
142
+ const realPath = await withDirectoryVerificationBudget(() => fs.promises.realpath(currentPath), control);
100
143
  if (activeDirectories.has(realPath)) {
101
144
  skippedSymlinks++;
102
145
  return;
103
146
  }
104
147
  activeDirectories.add(realPath);
105
148
  try {
106
- for (const name of await fs.promises.readdir(currentPath)) {
149
+ for (const name of await withDirectoryVerificationBudget(() => fs.promises.readdir(currentPath), control)) {
150
+ if (control) {
151
+ remainingVerificationTimeout(control);
152
+ }
107
153
  const relativePath = relativeBase ? `${relativeBase}/${name}` : name;
108
154
  if (matchesDirectoryExclude(relativePath, exclude)) {
109
155
  continue;
110
156
  }
157
+ const fullPath = path.join(currentPath, name);
158
+ const linkStats = await withDirectoryVerificationBudget(() => fs.promises.lstat(fullPath), control);
159
+ const stats = linkStats.isSymbolicLink() && followSymlinks
160
+ ? await withDirectoryVerificationBudget(() => fs.promises.stat(fullPath), control)
161
+ : linkStats;
162
+ if (matchesDirectoryExclude(relativePath, exclude, stats.isDirectory())) {
163
+ continue;
164
+ }
111
165
  if (entries.length >= maxEntries) {
112
166
  limitReason = 'entries';
113
167
  return;
114
168
  }
115
- const fullPath = path.join(currentPath, name);
116
- const linkStats = await fs.promises.lstat(fullPath);
117
169
  if (linkStats.isSymbolicLink() && !followSymlinks) {
118
170
  skippedSymlinks++;
119
171
  continue;
120
172
  }
121
- const stats = linkStats.isSymbolicLink() ? await fs.promises.stat(fullPath) : linkStats;
122
173
  if (stats.isDirectory()) {
123
174
  entries.push({
124
175
  path: relativePath,
@@ -143,7 +194,7 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
143
194
  limitReason = 'total_bytes';
144
195
  return;
145
196
  }
146
- sha256 = await hashFile(fullPath, stats.size, Math.min(maxFileBytes, maxTotalBytes - hashedBytes));
197
+ sha256 = await hashFile(fullPath, stats.size, Math.min(maxFileBytes, maxTotalBytes - hashedBytes), control);
147
198
  hashedBytes += stats.size;
148
199
  }
149
200
  entries.push({
@@ -171,7 +222,7 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
171
222
  return {
172
223
  entries,
173
224
  count: entries.length,
174
- rootSha256: rootHash(entries),
225
+ rootSha256: rootHash(entries, control),
175
226
  limited: limitReason !== undefined,
176
227
  limitReason,
177
228
  skippedSymlinks,
@@ -179,17 +230,17 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
179
230
  unsupportedSamples,
180
231
  };
181
232
  }
182
- export async function createRemoteDirectoryManifest(sftp, rootPath, request, exclude, followSymlinks = false, style = 'posix') {
233
+ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exclude, followSymlinks = false, style = 'posix', control) {
183
234
  const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
184
235
  const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
185
236
  const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
186
237
  const join = (parent, child) => remoteJoin(style, parent, child);
187
- const stat = (remotePath) => new Promise((resolve, reject) => {
238
+ const stat = (remotePath) => withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
188
239
  sftp.stat(remotePath, (error, stats) => (error ? reject(error) : resolve(stats)));
189
- });
190
- const lstat = (remotePath) => new Promise((resolve, reject) => {
240
+ }), control);
241
+ const lstat = (remotePath) => withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
191
242
  sftp.lstat(remotePath, (error, stats) => (error ? reject(error) : resolve(stats)));
192
- });
243
+ }), control);
193
244
  const root = await stat(rootPath);
194
245
  if ((root.mode & 0o170000) !== 0o040000) {
195
246
  throw new Error('remote directory verification root is not a directory');
@@ -214,20 +265,20 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
214
265
  limitReason = 'depth';
215
266
  return;
216
267
  }
217
- const resolved = await new Promise((resolve, reject) => {
268
+ const resolved = await withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
218
269
  sftp.realpath(directory, (error, result) => (error ? reject(error) : resolve(result)));
219
- });
270
+ }), control);
220
271
  if (active.has(resolved)) {
221
272
  ++skippedSymlinks;
222
273
  return;
223
274
  }
224
275
  active.add(resolved);
225
- const handle = await new Promise((resolve, reject) => {
276
+ const handle = await withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
226
277
  sftp.opendir(directory, (error, result) => (error ? reject(error) : resolve(result)));
227
- });
278
+ }), control);
228
279
  try {
229
280
  while (!limitReason) {
230
- const batch = await new Promise((resolve, reject) => {
281
+ const batch = await withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
231
282
  sftp.readdir(handle, (error, list) => {
232
283
  if (error && error.code === 1) {
233
284
  resolve(null);
@@ -239,7 +290,7 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
239
290
  resolve(list);
240
291
  }
241
292
  });
242
- });
293
+ }), control);
243
294
  if (!batch) {
244
295
  break;
245
296
  }
@@ -252,17 +303,20 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
252
303
  if (matchesDirectoryExclude(relativePath, exclude)) {
253
304
  continue;
254
305
  }
306
+ const fullPath = join(directory, name);
307
+ const link = await lstat(fullPath);
308
+ const stats = (link.mode & 0o170000) === 0o120000 && followSymlinks ? await stat(fullPath) : link;
309
+ if (matchesDirectoryExclude(relativePath, exclude, (stats.mode & 0o170000) === 0o040000)) {
310
+ continue;
311
+ }
255
312
  if (entries.length >= maxEntries) {
256
313
  limitReason = 'entries';
257
314
  break;
258
315
  }
259
- const fullPath = join(directory, name);
260
- const link = await lstat(fullPath);
261
316
  if ((link.mode & 0o170000) === 0o120000 && !followSymlinks) {
262
317
  ++skippedSymlinks;
263
318
  continue;
264
319
  }
265
- const stats = (link.mode & 0o170000) === 0o120000 ? await stat(fullPath) : link;
266
320
  if ((stats.mode & 0o170000) === 0o040000) {
267
321
  entries.push(entry(relativePath, 'directory', stats));
268
322
  await visit(fullPath, relativePath, depth + 1);
@@ -283,17 +337,30 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
283
337
  }
284
338
  const digest = createHash('sha256');
285
339
  let actualSize = 0;
286
- for await (const chunk of sftp.createReadStream(fullPath)) {
287
- actualSize += Buffer.byteLength(chunk);
288
- if (actualSize > maxFileBytes) {
289
- limitReason = 'file_bytes';
290
- break;
291
- }
292
- if (hashedBytes + actualSize > maxTotalBytes) {
293
- limitReason = 'total_bytes';
294
- break;
295
- }
296
- digest.update(chunk);
340
+ if (control) {
341
+ remainingVerificationTimeout(control);
342
+ }
343
+ const stream = sftp.createReadStream(fullPath);
344
+ try {
345
+ await withDirectoryVerificationBudget(async () => {
346
+ for await (const chunk of stream) {
347
+ actualSize += Buffer.byteLength(chunk);
348
+ if (actualSize > maxFileBytes) {
349
+ limitReason = 'file_bytes';
350
+ break;
351
+ }
352
+ if (hashedBytes + actualSize > maxTotalBytes) {
353
+ limitReason = 'total_bytes';
354
+ break;
355
+ }
356
+ digest.update(chunk);
357
+ }
358
+ }, control, () => {
359
+ stream.destroy();
360
+ });
361
+ }
362
+ finally {
363
+ stream.destroy();
297
364
  }
298
365
  if (limitReason) {
299
366
  break;
@@ -320,14 +387,16 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
320
387
  }
321
388
  finally {
322
389
  active.delete(resolved);
323
- await new Promise((resolve, reject) => sftp.close(handle, (error) => (error ? reject(error) : resolve())));
390
+ if (!control?.signal.aborted) {
391
+ await withDirectoryVerificationBudget(() => new Promise((resolve, reject) => sftp.close(handle, (error) => (error ? reject(error) : resolve()))), control);
392
+ }
324
393
  }
325
394
  };
326
395
  await visit(rootPath, '', 0);
327
396
  return {
328
397
  entries,
329
398
  count: entries.length,
330
- rootSha256: rootHash(entries),
399
+ rootSha256: rootHash(entries, control),
331
400
  limited: limitReason !== undefined,
332
401
  limitReason,
333
402
  skippedSymlinks,
@@ -335,20 +404,25 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
335
404
  unsupportedSamples,
336
405
  };
337
406
  }
338
- export async function createOpenSshDirectoryManifest(connection, rootPath, request, timeout, exclude, followSymlinks = false) {
339
- const deadline = Date.now() + timeout;
407
+ export async function createOpenSshDirectoryManifest(connection, rootPath, request, timeout, exclude, followSymlinks = false, control) {
408
+ const deadline = Math.min(Date.now() + timeout, control?.deadline ?? Infinity);
340
409
  const remaining = () => {
410
+ if (control) {
411
+ remainingVerificationTimeout(control);
412
+ }
341
413
  const value = deadline - Date.now();
342
- if (value <= 0)
414
+ if (value <= 0) {
343
415
  throw new Error('OpenSSH directory verification exhausted its timeout');
416
+ }
344
417
  return value;
345
418
  };
346
419
  const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
347
420
  const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
348
421
  const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
349
422
  const rootBytes = await connection.capture(`realpath -ze -- ${escapeShellArg(rootPath)}`, remaining(), 64 * 1024);
350
- if (rootBytes.at(-1) !== 0)
423
+ if (rootBytes.at(-1) !== 0) {
351
424
  throw new Error('OpenSSH realpath did not return a complete path');
425
+ }
352
426
  const root = new TextDecoder('utf8', { fatal: true }).decode(rootBytes.subarray(0, -1));
353
427
  if (((await connection.stat(root, remaining())).mode & 0o170000) !== 0o040000) {
354
428
  throw new Error('remote directory verification root is not a directory');
@@ -365,6 +439,7 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
365
439
  const limit = new Error('OpenSSH manifest resource limit reached');
366
440
  const decoder = new TextDecoder('utf8', { fatal: true, ignoreBOM: true });
367
441
  const consumeEntry = () => {
442
+ remaining();
368
443
  const [relative, kind, sizeText, modeText, owner, fullPath] = fields;
369
444
  fields.length = 0;
370
445
  const parts = relative.split('/');
@@ -372,8 +447,9 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
372
447
  throw new Error('OpenSSH directory verification returned an unsafe relative path');
373
448
  }
374
449
  if (relative &&
375
- parts.some((_part, index) => matchesDirectoryExclude(parts.slice(0, index + 1).join('/'), exclude)))
450
+ parts.some((_part, index) => matchesDirectoryExclude(parts.slice(0, index + 1).join('/'), exclude, index < parts.length - 1 || kind === 'd'))) {
376
451
  return;
452
+ }
377
453
  if (relative && parts.length > 64) {
378
454
  limitReason = 'depth';
379
455
  throw limit;
@@ -388,8 +464,9 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
388
464
  }
389
465
  if (kind !== 'f' && kind !== 'd') {
390
466
  ++skippedUnsupported;
391
- if (unsupportedSamples.length < 10)
467
+ if (unsupportedSamples.length < 10) {
392
468
  unsupportedSamples.push(relative);
469
+ }
393
470
  return;
394
471
  }
395
472
  const size = Number(sizeText);
@@ -411,7 +488,12 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
411
488
  };
412
489
  const format = '%P\\0%y\\0%s\\0%m\\0%U\\0%p\\0';
413
490
  try {
414
- await connection.consume(`LC_ALL=C find ${followSymlinks ? '-L' : '-P'} ${escapeShellArg(root)} -maxdepth 65 -printf ${escapeShellArg(format)}`, (chunk) => {
491
+ await connection.consume('LC_ALL=C find ' +
492
+ `${followSymlinks ? '-L' : '-P'}` +
493
+ ' ' +
494
+ `${escapeShellArg(root)}` +
495
+ ' -maxdepth 65 -printf ' +
496
+ `${escapeShellArg(format)}`, (chunk) => {
415
497
  metadataBytes += chunk.length;
416
498
  if (metadataBytes > metadataLimit) {
417
499
  limitReason = 'entries';
@@ -422,24 +504,29 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
422
504
  while ((end = pending.indexOf(0)) >= 0) {
423
505
  fields.push(decoder.decode(pending.subarray(0, end)));
424
506
  pending = pending.subarray(end + 1);
425
- if (fields.length === 6)
507
+ if (fields.length === 6) {
426
508
  consumeEntry();
509
+ }
427
510
  }
428
- if (pending.length > 64 * 1024)
511
+ if (pending.length > 64 * 1024) {
429
512
  throw new Error('OpenSSH manifest field exceeded its byte budget');
513
+ }
430
514
  }, remaining());
431
- if (pending.length || fields.length)
515
+ if (pending.length || fields.length) {
432
516
  throw new Error('OpenSSH manifest ended with incomplete metadata');
517
+ }
433
518
  }
434
519
  catch (error) {
435
- if (error !== limit)
520
+ if (error !== limit) {
436
521
  throw error;
522
+ }
437
523
  }
438
524
  if (!limitReason && request.sha256) {
439
525
  let hashedBytes = 0;
440
526
  for (const entry of entries) {
441
- if (entry.type !== 'file')
527
+ if (entry.type !== 'file') {
442
528
  continue;
529
+ }
443
530
  if (entry.size > maxFileBytes) {
444
531
  limitReason = 'file_bytes';
445
532
  break;
@@ -455,7 +542,7 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
455
542
  return {
456
543
  entries,
457
544
  count: entries.length,
458
- rootSha256: rootHash(entries),
545
+ rootSha256: rootHash(entries, control),
459
546
  limited: limitReason !== undefined,
460
547
  limitReason,
461
548
  skippedSymlinks,
package/dist/file-mode.js CHANGED
@@ -37,35 +37,47 @@ export function parseExpectedFileMode(value) {
37
37
  if (/^[0-7]{3,4}$/.test(trimmed)) {
38
38
  return Number.parseInt(trimmed, 8) & FILE_MODE_MASK;
39
39
  }
40
- const match = /^(?:[-dl?])?([r-][w-][xSs-][r-][w-][xSs-][r-][w-][xTt-])$/.exec(trimmed);
40
+ const match = /^[-dl?]?(?<permissions>[r-][w-][xSs-][r-][w-][xSs-][r-][w-][xTt-])$/.exec(trimmed);
41
41
  if (!match) {
42
42
  return undefined;
43
43
  }
44
44
  const bits = match[1];
45
45
  let mode = 0;
46
- if (bits[0] === 'r')
46
+ if (bits[0] === 'r') {
47
47
  mode |= 0o400;
48
- if (bits[1] === 'w')
48
+ }
49
+ if (bits[1] === 'w') {
49
50
  mode |= 0o200;
50
- if (bits[2] === 'x' || bits[2] === 's')
51
+ }
52
+ if (bits[2] === 'x' || bits[2] === 's') {
51
53
  mode |= 0o100;
52
- if (bits[2] === 's' || bits[2] === 'S')
54
+ }
55
+ if (bits[2] === 's' || bits[2] === 'S') {
53
56
  mode |= 0o4000;
54
- if (bits[3] === 'r')
57
+ }
58
+ if (bits[3] === 'r') {
55
59
  mode |= 0o040;
56
- if (bits[4] === 'w')
60
+ }
61
+ if (bits[4] === 'w') {
57
62
  mode |= 0o020;
58
- if (bits[5] === 'x' || bits[5] === 's')
63
+ }
64
+ if (bits[5] === 'x' || bits[5] === 's') {
59
65
  mode |= 0o010;
60
- if (bits[5] === 's' || bits[5] === 'S')
66
+ }
67
+ if (bits[5] === 's' || bits[5] === 'S') {
61
68
  mode |= 0o2000;
62
- if (bits[6] === 'r')
69
+ }
70
+ if (bits[6] === 'r') {
63
71
  mode |= 0o004;
64
- if (bits[7] === 'w')
72
+ }
73
+ if (bits[7] === 'w') {
65
74
  mode |= 0o002;
66
- if (bits[8] === 'x' || bits[8] === 't')
75
+ }
76
+ if (bits[8] === 'x' || bits[8] === 't') {
67
77
  mode |= 0o001;
68
- if (bits[8] === 't' || bits[8] === 'T')
78
+ }
79
+ if (bits[8] === 't' || bits[8] === 'T') {
69
80
  mode |= 0o1000;
81
+ }
70
82
  return mode;
71
83
  }
@@ -9,7 +9,7 @@ type RsyncProbeResult = {
9
9
  status: 'available' | 'unavailable' | 'timeout' | 'error' | 'skipped';
10
10
  duration: number;
11
11
  retryable: boolean;
12
- exitCode?: number;
12
+ exitCode?: number | null;
13
13
  failureKind?: string;
14
14
  error?: string;
15
15
  reason?: string;
@@ -71,7 +71,7 @@ export declare function probeLocalPath(localPath: string, followSymlinks?: boole
71
71
  export declare function hashRemoteFileDigest(alias: string, remotePath: string, algorithm: 'md5' | 'sha256', timeout?: number, limits?: {
72
72
  maxBytes: number;
73
73
  expectedSize: number;
74
- }): Promise<string>;
74
+ }, signal?: AbortSignal): Promise<string>;
75
75
  export declare function atomicReplaceCapability(alias: string, timeout?: number): Promise<{
76
76
  atomicReplaceSupported: boolean;
77
77
  reason?: string;
@@ -84,7 +84,9 @@ export declare function removeRemoteFile(alias: string, remotePath: string, time
84
84
  export declare class UploadFileError extends Error {
85
85
  readonly remoteCreated: boolean;
86
86
  readonly details?: Record<string, unknown>;
87
- constructor(message: string, remoteCreated: boolean, options?: ErrorOptions);
87
+ constructor(message: string, remoteCreated: boolean, options?: ErrorOptions & {
88
+ details?: Record<string, unknown>;
89
+ });
88
90
  }
89
91
  /**
90
92
  * 上传文件
@@ -151,15 +153,15 @@ export declare function writeFile(alias: string, remotePath: string, content: st
151
153
  /**
152
154
  * 列出目录内容
153
155
  */
154
- export declare function listDir(alias: string, remotePath: string, showHidden?: boolean, sharedSftp?: SFTPWrapper, timeout?: number, style?: 'posix' | 'win32' | 'sftp-posix'): Promise<FileInfo[]>;
156
+ export declare function listDir(alias: string, remotePath: string, showHidden?: boolean, sharedSftp?: SFTPWrapper, timeout?: number, style?: 'posix' | 'win32' | 'sftp-posix', signal?: AbortSignal): Promise<FileInfo[]>;
155
157
  /**
156
158
  * 获取文件信息
157
159
  */
158
- export declare function getFileInfo(alias: string, remotePath: string, timeout?: number, style?: 'posix' | 'win32' | 'sftp-posix'): Promise<FileInfo>;
160
+ export declare function getFileInfo(alias: string, remotePath: string, timeout?: number, style?: 'posix' | 'win32' | 'sftp-posix', signal?: AbortSignal): Promise<FileInfo>;
159
161
  /**
160
162
  * 创建目录
161
163
  */
162
- export declare function mkdir(alias: string, remotePath: string, recursive?: boolean, sharedSftp?: SFTPWrapper, timeout?: number, style?: 'posix' | 'win32' | 'sftp-posix'): Promise<boolean>;
164
+ export declare function mkdir(alias: string, remotePath: string, recursive?: boolean, sharedSftp?: SFTPWrapper, timeout?: number, style?: 'posix' | 'win32' | 'sftp-posix', signal?: AbortSignal): Promise<boolean>;
163
165
  /**
164
166
  * 检查远程是否安装 rsync
165
167
  */
@@ -170,12 +172,15 @@ type SyncOptions = {
170
172
  exclude?: string[];
171
173
  recursive?: boolean;
172
174
  followSymlinks?: boolean;
175
+ verifySha256?: boolean;
173
176
  preflightTimeout?: number;
174
177
  connectTimeout?: number;
175
178
  operationTimeout?: number;
176
179
  sourceIsDirectory?: boolean;
180
+ deadline?: number;
177
181
  signal?: AbortSignal;
178
182
  remotePathStyle?: 'posix' | 'win32' | 'sftp-posix';
183
+ onProgress?: (progress: TransferProgress) => void;
179
184
  };
180
185
  /**
181
186
  * 智能文件同步(根据连接能力选择 rsync 或 SFTP)
@@ -219,6 +224,7 @@ type SyncResult = {
219
224
  connectDuration?: number;
220
225
  connectStatus?: 'completed' | 'failed' | 'not_applicable';
221
226
  operationStatus?: 'completed' | 'failed' | 'unknown';
227
+ failureStage?: string;
222
228
  timedOut?: boolean;
223
229
  retryable?: boolean;
224
230
  direction?: 'upload' | 'download';
@@ -233,6 +239,7 @@ type SyncResult = {
233
239
  verification?: Record<string, unknown>;
234
240
  commandSummary?: Record<string, unknown>;
235
241
  output?: string;
242
+ outputTruncated?: boolean;
236
243
  };
237
244
  export declare function hashLocalFile(filePath: string, algorithm?: 'md5' | 'sha256', timeout?: number, limits?: {
238
245
  maxBytes: number;