@pyrokine/mcp-ssh 3.0.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,5 +1,11 @@
1
1
  import type { SFTPWrapper } from 'ssh2';
2
+ import type { OpenSshConnection } from './openssh.js';
2
3
  import type { RemotePathStyle } from './types.js';
4
+ export type DirectoryVerificationControl = {
5
+ deadline: number;
6
+ signal: AbortSignal;
7
+ };
8
+ export declare function remainingVerificationTimeout(control: DirectoryVerificationControl): number;
3
9
  export declare const DIRECTORY_VERIFY_MAX_ENTRIES = 50000;
4
10
  export declare const DIRECTORY_VERIFY_MAX_MISMATCHES = 20;
5
11
  export declare const DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES: number;
@@ -37,9 +43,10 @@ export type DirectoryManifest = {
37
43
  skippedUnsupported: number;
38
44
  unsupportedSamples: string[];
39
45
  };
40
- export declare function matchesDirectoryExclude(relativePath: string, patterns: string[] | undefined): boolean;
41
- export declare function createLocalDirectoryManifest(rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean): Promise<DirectoryManifest>;
42
- export declare function createRemoteDirectoryManifest(sftp: SFTPWrapper, rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean, style?: RemotePathStyle): Promise<DirectoryManifest>;
46
+ export declare function matchesDirectoryExclude(relativePath: string, patterns: string[] | undefined, isDirectory?: boolean): boolean;
47
+ export declare function createLocalDirectoryManifest(rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean, control?: DirectoryVerificationControl): Promise<DirectoryManifest>;
48
+ export declare function createRemoteDirectoryManifest(sftp: SFTPWrapper, rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean, style?: RemotePathStyle, control?: DirectoryVerificationControl): Promise<DirectoryManifest>;
49
+ export declare function createOpenSshDirectoryManifest(connection: OpenSshConnection, rootPath: string, request: DirectoryVerifyRequest, timeout: number, exclude?: string[], followSymlinks?: boolean, control?: DirectoryVerificationControl): Promise<DirectoryManifest>;
43
50
  export declare function createEmptyDirectoryManifest(): DirectoryManifest;
44
51
  export declare function compareDirectoryManifests(expected: DirectoryManifest, actual: DirectoryManifest, request: DirectoryVerifyRequest, deletionBaseline?: DirectoryManifest): Record<string, unknown>;
45
52
  export {};
@@ -1,17 +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';
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
+ }
6
27
  export const DIRECTORY_VERIFY_MAX_ENTRIES = 50_000;
7
28
  export const DIRECTORY_VERIFY_MAX_MISMATCHES = 20;
8
29
  export const DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES = 256 * 1024 * 1024;
9
30
  export const DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
10
31
  export const DIRECTORY_VERIFY_MAX_FILE_BYTES = 4 * 1024 * 1024 * 1024;
11
32
  export const DIRECTORY_VERIFY_MAX_TOTAL_BYTES = 16 * 1024 * 1024 * 1024;
12
- function rootHash(entries) {
33
+ function rootHash(entries, control) {
34
+ if (control) {
35
+ remainingVerificationTimeout(control);
36
+ }
13
37
  const hash = createHash('sha256');
14
- 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
+ }
15
42
  hash.update(JSON.stringify({
16
43
  path: entry.path,
17
44
  type: entry.type,
@@ -22,26 +49,43 @@ function rootHash(entries) {
22
49
  }
23
50
  return hash.digest('hex');
24
51
  }
25
- async function hashFile(filePath, size, maxBytes) {
26
- const hash = createHash('sha256');
27
- let readBytes = 0;
28
- for await (const chunk of fs.createReadStream(filePath)) {
29
- readBytes += Buffer.byteLength(chunk);
30
- if (readBytes > maxBytes) {
31
- throw new Error('local file grew beyond directory manifest hash budget');
32
- }
33
- hash.update(chunk);
52
+ async function hashFile(filePath, size, maxBytes, control) {
53
+ if (control) {
54
+ remainingVerificationTimeout(control);
34
55
  }
35
- if (readBytes !== size) {
36
- 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();
37
78
  }
38
- return hash.digest('hex');
39
79
  }
40
- export function matchesDirectoryExclude(relativePath, patterns) {
80
+ export function matchesDirectoryExclude(relativePath, patterns, isDirectory = false) {
41
81
  const normalizedPath = relativePath.replace(/^\.\//, '').replace(/^\//, '');
42
82
  const basename = path.posix.basename(normalizedPath);
43
83
  return Boolean(patterns?.some((pattern) => {
44
- const normalizedPattern = pattern.replace(/^\//, '');
84
+ const directoryOnly = pattern.endsWith('/');
85
+ if (directoryOnly && !isDirectory) {
86
+ return false;
87
+ }
88
+ const normalizedPattern = pattern.replace(/^\//, '').replace(/\/$/, '');
45
89
  const candidate = normalizedPattern.includes('/') ? normalizedPath : basename;
46
90
  const matches = new Uint8Array(candidate.length + 1);
47
91
  matches[0] = 1;
@@ -71,11 +115,11 @@ export function matchesDirectoryExclude(relativePath, patterns) {
71
115
  return matches[candidate.length] === 1;
72
116
  }));
73
117
  }
74
- export async function createLocalDirectoryManifest(rootPath, request, exclude, followSymlinks = false) {
118
+ export async function createLocalDirectoryManifest(rootPath, request, exclude, followSymlinks = false, control) {
75
119
  const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
76
120
  const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
77
121
  const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
78
- const rootStats = await fs.promises.stat(rootPath);
122
+ const rootStats = await withDirectoryVerificationBudget(() => fs.promises.stat(rootPath), control);
79
123
  if (!rootStats.isDirectory()) {
80
124
  throw new Error(`directory verification root is not a directory: ${rootPath}`);
81
125
  }
@@ -95,29 +139,37 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
95
139
  const unsupportedSamples = [];
96
140
  let limitReason;
97
141
  const visit = async (currentPath, relativeBase) => {
98
- const realPath = await fs.promises.realpath(currentPath);
142
+ const realPath = await withDirectoryVerificationBudget(() => fs.promises.realpath(currentPath), control);
99
143
  if (activeDirectories.has(realPath)) {
100
144
  skippedSymlinks++;
101
145
  return;
102
146
  }
103
147
  activeDirectories.add(realPath);
104
148
  try {
105
- 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
+ }
106
153
  const relativePath = relativeBase ? `${relativeBase}/${name}` : name;
107
154
  if (matchesDirectoryExclude(relativePath, exclude)) {
108
155
  continue;
109
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
+ }
110
165
  if (entries.length >= maxEntries) {
111
166
  limitReason = 'entries';
112
167
  return;
113
168
  }
114
- const fullPath = path.join(currentPath, name);
115
- const linkStats = await fs.promises.lstat(fullPath);
116
169
  if (linkStats.isSymbolicLink() && !followSymlinks) {
117
170
  skippedSymlinks++;
118
171
  continue;
119
172
  }
120
- const stats = linkStats.isSymbolicLink() ? await fs.promises.stat(fullPath) : linkStats;
121
173
  if (stats.isDirectory()) {
122
174
  entries.push({
123
175
  path: relativePath,
@@ -142,7 +194,7 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
142
194
  limitReason = 'total_bytes';
143
195
  return;
144
196
  }
145
- sha256 = await hashFile(fullPath, stats.size, Math.min(maxFileBytes, maxTotalBytes - hashedBytes));
197
+ sha256 = await hashFile(fullPath, stats.size, Math.min(maxFileBytes, maxTotalBytes - hashedBytes), control);
146
198
  hashedBytes += stats.size;
147
199
  }
148
200
  entries.push({
@@ -170,7 +222,7 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
170
222
  return {
171
223
  entries,
172
224
  count: entries.length,
173
- rootSha256: rootHash(entries),
225
+ rootSha256: rootHash(entries, control),
174
226
  limited: limitReason !== undefined,
175
227
  limitReason,
176
228
  skippedSymlinks,
@@ -178,17 +230,17 @@ export async function createLocalDirectoryManifest(rootPath, request, exclude, f
178
230
  unsupportedSamples,
179
231
  };
180
232
  }
181
- 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) {
182
234
  const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
183
235
  const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
184
236
  const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
185
237
  const join = (parent, child) => remoteJoin(style, parent, child);
186
- const stat = (remotePath) => new Promise((resolve, reject) => {
238
+ const stat = (remotePath) => withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
187
239
  sftp.stat(remotePath, (error, stats) => (error ? reject(error) : resolve(stats)));
188
- });
189
- const lstat = (remotePath) => new Promise((resolve, reject) => {
240
+ }), control);
241
+ const lstat = (remotePath) => withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
190
242
  sftp.lstat(remotePath, (error, stats) => (error ? reject(error) : resolve(stats)));
191
- });
243
+ }), control);
192
244
  const root = await stat(rootPath);
193
245
  if ((root.mode & 0o170000) !== 0o040000) {
194
246
  throw new Error('remote directory verification root is not a directory');
@@ -213,20 +265,20 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
213
265
  limitReason = 'depth';
214
266
  return;
215
267
  }
216
- const resolved = await new Promise((resolve, reject) => {
268
+ const resolved = await withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
217
269
  sftp.realpath(directory, (error, result) => (error ? reject(error) : resolve(result)));
218
- });
270
+ }), control);
219
271
  if (active.has(resolved)) {
220
272
  ++skippedSymlinks;
221
273
  return;
222
274
  }
223
275
  active.add(resolved);
224
- const handle = await new Promise((resolve, reject) => {
276
+ const handle = await withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
225
277
  sftp.opendir(directory, (error, result) => (error ? reject(error) : resolve(result)));
226
- });
278
+ }), control);
227
279
  try {
228
280
  while (!limitReason) {
229
- const batch = await new Promise((resolve, reject) => {
281
+ const batch = await withDirectoryVerificationBudget(() => new Promise((resolve, reject) => {
230
282
  sftp.readdir(handle, (error, list) => {
231
283
  if (error && error.code === 1) {
232
284
  resolve(null);
@@ -238,8 +290,8 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
238
290
  resolve(list);
239
291
  }
240
292
  });
241
- });
242
- if (!batch || batch.length === 0) {
293
+ }), control);
294
+ if (!batch) {
243
295
  break;
244
296
  }
245
297
  for (const item of batch) {
@@ -251,17 +303,20 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
251
303
  if (matchesDirectoryExclude(relativePath, exclude)) {
252
304
  continue;
253
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
+ }
254
312
  if (entries.length >= maxEntries) {
255
313
  limitReason = 'entries';
256
314
  break;
257
315
  }
258
- const fullPath = join(directory, name);
259
- const link = await lstat(fullPath);
260
316
  if ((link.mode & 0o170000) === 0o120000 && !followSymlinks) {
261
317
  ++skippedSymlinks;
262
318
  continue;
263
319
  }
264
- const stats = (link.mode & 0o170000) === 0o120000 ? await stat(fullPath) : link;
265
320
  if ((stats.mode & 0o170000) === 0o040000) {
266
321
  entries.push(entry(relativePath, 'directory', stats));
267
322
  await visit(fullPath, relativePath, depth + 1);
@@ -282,17 +337,30 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
282
337
  }
283
338
  const digest = createHash('sha256');
284
339
  let actualSize = 0;
285
- for await (const chunk of sftp.createReadStream(fullPath)) {
286
- actualSize += Buffer.byteLength(chunk);
287
- if (actualSize > maxFileBytes) {
288
- limitReason = 'file_bytes';
289
- break;
290
- }
291
- if (hashedBytes + actualSize > maxTotalBytes) {
292
- limitReason = 'total_bytes';
293
- break;
294
- }
295
- 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();
296
364
  }
297
365
  if (limitReason) {
298
366
  break;
@@ -319,14 +387,162 @@ export async function createRemoteDirectoryManifest(sftp, rootPath, request, exc
319
387
  }
320
388
  finally {
321
389
  active.delete(resolved);
322
- 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
+ }
323
393
  }
324
394
  };
325
395
  await visit(rootPath, '', 0);
326
396
  return {
327
397
  entries,
328
398
  count: entries.length,
329
- rootSha256: rootHash(entries),
399
+ rootSha256: rootHash(entries, control),
400
+ limited: limitReason !== undefined,
401
+ limitReason,
402
+ skippedSymlinks,
403
+ skippedUnsupported,
404
+ unsupportedSamples,
405
+ };
406
+ }
407
+ export async function createOpenSshDirectoryManifest(connection, rootPath, request, timeout, exclude, followSymlinks = false, control) {
408
+ const deadline = Math.min(Date.now() + timeout, control?.deadline ?? Infinity);
409
+ const remaining = () => {
410
+ if (control) {
411
+ remainingVerificationTimeout(control);
412
+ }
413
+ const value = deadline - Date.now();
414
+ if (value <= 0) {
415
+ throw new Error('OpenSSH directory verification exhausted its timeout');
416
+ }
417
+ return value;
418
+ };
419
+ const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
420
+ const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
421
+ const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
422
+ const rootBytes = await connection.capture(`realpath -ze -- ${escapeShellArg(rootPath)}`, remaining(), 64 * 1024);
423
+ if (rootBytes.at(-1) !== 0) {
424
+ throw new Error('OpenSSH realpath did not return a complete path');
425
+ }
426
+ const root = new TextDecoder('utf8', { fatal: true }).decode(rootBytes.subarray(0, -1));
427
+ if (((await connection.stat(root, remaining())).mode & 0o170000) !== 0o040000) {
428
+ throw new Error('remote directory verification root is not a directory');
429
+ }
430
+ const entries = [];
431
+ const unsupportedSamples = [];
432
+ let skippedSymlinks = 0;
433
+ let skippedUnsupported = 0;
434
+ let limitReason;
435
+ let pending = Buffer.alloc(0);
436
+ const fields = [];
437
+ let metadataBytes = 0;
438
+ const metadataLimit = Math.min(128 * 1024 * 1024, Math.max(64 * 1024, maxEntries * 2048));
439
+ const limit = new Error('OpenSSH manifest resource limit reached');
440
+ const decoder = new TextDecoder('utf8', { fatal: true, ignoreBOM: true });
441
+ const consumeEntry = () => {
442
+ remaining();
443
+ const [relative, kind, sizeText, modeText, owner, fullPath] = fields;
444
+ fields.length = 0;
445
+ const parts = relative.split('/');
446
+ if (relative && (relative.startsWith('/') || parts.some((part) => !part || part === '.' || part === '..'))) {
447
+ throw new Error('OpenSSH directory verification returned an unsafe relative path');
448
+ }
449
+ if (relative &&
450
+ parts.some((_part, index) => matchesDirectoryExclude(parts.slice(0, index + 1).join('/'), exclude, index < parts.length - 1 || kind === 'd'))) {
451
+ return;
452
+ }
453
+ if (relative && parts.length > 64) {
454
+ limitReason = 'depth';
455
+ throw limit;
456
+ }
457
+ if (entries.length >= maxEntries) {
458
+ limitReason = 'entries';
459
+ throw limit;
460
+ }
461
+ if (kind === 'l') {
462
+ ++skippedSymlinks;
463
+ return;
464
+ }
465
+ if (kind !== 'f' && kind !== 'd') {
466
+ ++skippedUnsupported;
467
+ if (unsupportedSamples.length < 10) {
468
+ unsupportedSamples.push(relative);
469
+ }
470
+ return;
471
+ }
472
+ const size = Number(sizeText);
473
+ const mode = Number.parseInt(modeText, 8);
474
+ if (!Number.isSafeInteger(size) ||
475
+ size < 0 ||
476
+ !/^[0-7]{1,4}$/.test(modeText) ||
477
+ !/^\d+$/.test(owner) ||
478
+ !fullPath) {
479
+ throw new Error('OpenSSH directory verification returned invalid file metadata');
480
+ }
481
+ entries.push({
482
+ path: relative || '.',
483
+ type: kind === 'd' ? 'directory' : 'file',
484
+ size: kind === 'f' ? size : 0,
485
+ mode: formatFileMode(mode),
486
+ owner,
487
+ });
488
+ };
489
+ const format = '%P\\0%y\\0%s\\0%m\\0%U\\0%p\\0';
490
+ try {
491
+ await connection.consume('LC_ALL=C find ' +
492
+ `${followSymlinks ? '-L' : '-P'}` +
493
+ ' ' +
494
+ `${escapeShellArg(root)}` +
495
+ ' -maxdepth 65 -printf ' +
496
+ `${escapeShellArg(format)}`, (chunk) => {
497
+ metadataBytes += chunk.length;
498
+ if (metadataBytes > metadataLimit) {
499
+ limitReason = 'entries';
500
+ throw limit;
501
+ }
502
+ pending = Buffer.concat([pending, chunk]);
503
+ let end;
504
+ while ((end = pending.indexOf(0)) >= 0) {
505
+ fields.push(decoder.decode(pending.subarray(0, end)));
506
+ pending = pending.subarray(end + 1);
507
+ if (fields.length === 6) {
508
+ consumeEntry();
509
+ }
510
+ }
511
+ if (pending.length > 64 * 1024) {
512
+ throw new Error('OpenSSH manifest field exceeded its byte budget');
513
+ }
514
+ }, remaining());
515
+ if (pending.length || fields.length) {
516
+ throw new Error('OpenSSH manifest ended with incomplete metadata');
517
+ }
518
+ }
519
+ catch (error) {
520
+ if (error !== limit) {
521
+ throw error;
522
+ }
523
+ }
524
+ if (!limitReason && request.sha256) {
525
+ let hashedBytes = 0;
526
+ for (const entry of entries) {
527
+ if (entry.type !== 'file') {
528
+ continue;
529
+ }
530
+ if (entry.size > maxFileBytes) {
531
+ limitReason = 'file_bytes';
532
+ break;
533
+ }
534
+ if (hashedBytes + entry.size > maxTotalBytes) {
535
+ limitReason = 'total_bytes';
536
+ break;
537
+ }
538
+ entry.sha256 = await connection.hashFile(remoteJoin('posix', root, entry.path), 'sha256', remaining(), Math.min(maxFileBytes, maxTotalBytes - hashedBytes), entry.size);
539
+ hashedBytes += entry.size;
540
+ }
541
+ }
542
+ return {
543
+ entries,
544
+ count: entries.length,
545
+ rootSha256: rootHash(entries, control),
330
546
  limited: limitReason !== undefined,
331
547
  limitReason,
332
548
  skippedSymlinks,
@@ -365,7 +581,7 @@ export function compareDirectoryManifests(expected, actual, request, deletionBas
365
581
  return {
366
582
  kind: 'directory',
367
583
  skipped: true,
368
- reason: 'directory verification skipped symbolic links; set followSymlinks=true to verify link targets',
584
+ reason: 'directory verification skipped symbolic links and cannot verify the complete requested tree',
369
585
  expectedSkippedSymlinks: expected.skippedSymlinks,
370
586
  actualSkippedSymlinks: actual.skippedSymlinks,
371
587
  deletionBaselineSkippedSymlinks: deletionBaseline?.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;
@@ -68,7 +68,10 @@ export declare function probeLocalPath(localPath: string, followSymlinks?: boole
68
68
  matched?: boolean;
69
69
  };
70
70
  };
71
- export declare function hashRemoteFileDigest(alias: string, remotePath: string, algorithm: 'md5' | 'sha256'): Promise<string>;
71
+ export declare function hashRemoteFileDigest(alias: string, remotePath: string, algorithm: 'md5' | 'sha256', timeout?: number, limits?: {
72
+ maxBytes: number;
73
+ expectedSize: number;
74
+ }, signal?: AbortSignal): Promise<string>;
72
75
  export declare function atomicReplaceCapability(alias: string, timeout?: number): Promise<{
73
76
  atomicReplaceSupported: boolean;
74
77
  reason?: string;
@@ -81,7 +84,9 @@ export declare function removeRemoteFile(alias: string, remotePath: string, time
81
84
  export declare class UploadFileError extends Error {
82
85
  readonly remoteCreated: boolean;
83
86
  readonly details?: Record<string, unknown>;
84
- constructor(message: string, remoteCreated: boolean, options?: ErrorOptions);
87
+ constructor(message: string, remoteCreated: boolean, options?: ErrorOptions & {
88
+ details?: Record<string, unknown>;
89
+ });
85
90
  }
86
91
  /**
87
92
  * 上传文件
@@ -148,15 +153,15 @@ export declare function writeFile(alias: string, remotePath: string, content: st
148
153
  /**
149
154
  * 列出目录内容
150
155
  */
151
- 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[]>;
152
157
  /**
153
158
  * 获取文件信息
154
159
  */
155
- 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>;
156
161
  /**
157
162
  * 创建目录
158
163
  */
159
- 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>;
160
165
  /**
161
166
  * 检查远程是否安装 rsync
162
167
  */
@@ -167,12 +172,15 @@ type SyncOptions = {
167
172
  exclude?: string[];
168
173
  recursive?: boolean;
169
174
  followSymlinks?: boolean;
175
+ verifySha256?: boolean;
170
176
  preflightTimeout?: number;
171
177
  connectTimeout?: number;
172
178
  operationTimeout?: number;
173
179
  sourceIsDirectory?: boolean;
180
+ deadline?: number;
174
181
  signal?: AbortSignal;
175
182
  remotePathStyle?: 'posix' | 'win32' | 'sftp-posix';
183
+ onProgress?: (progress: TransferProgress) => void;
176
184
  };
177
185
  /**
178
186
  * 智能文件同步(根据连接能力选择 rsync 或 SFTP)
@@ -216,6 +224,7 @@ type SyncResult = {
216
224
  connectDuration?: number;
217
225
  connectStatus?: 'completed' | 'failed' | 'not_applicable';
218
226
  operationStatus?: 'completed' | 'failed' | 'unknown';
227
+ failureStage?: string;
219
228
  timedOut?: boolean;
220
229
  retryable?: boolean;
221
230
  direction?: 'upload' | 'download';
@@ -230,5 +239,10 @@ type SyncResult = {
230
239
  verification?: Record<string, unknown>;
231
240
  commandSummary?: Record<string, unknown>;
232
241
  output?: string;
242
+ outputTruncated?: boolean;
233
243
  };
244
+ export declare function hashLocalFile(filePath: string, algorithm?: 'md5' | 'sha256', timeout?: number, limits?: {
245
+ maxBytes: number;
246
+ expectedSize: number;
247
+ }): Promise<string>;
234
248
  export {};