0
# SFTP Operations
1

2
Comprehensive SFTP (SSH File Transfer Protocol) implementation supporting both client and server operations with full OpenSSH extension support for advanced file system operations.
3

4
## Capabilities
5

6
### SFTP Class
7

8
Complete SFTP client and server implementation with extensive file system operations.
9

10
```javascript { .api }
11
/**
12
 * SFTP client/server implementation
13
 * Extends EventEmitter for operation events
14
 */
15
class SFTP extends EventEmitter {
16
  maxOpenHandles: number;
17
}
18
```
19

20
### File Operations
21

22
Core file manipulation operations for reading, writing, and managing files.
23

24
```javascript { .api }
25
/**
26
 * Open a file for reading/writing
27
 * @param path - Remote file path
28
 * @param flags - Open flags (string like 'r', 'w', 'a' or numeric)
29
 * @param attrs - Optional file attributes to set
30
 * @param callback - Callback receiving file handle
31
 * @returns false if SFTP not ready, true otherwise
32
 */
33
open(path: string, flags: string | number, attrs?: Attributes, callback?: OpenCallback): boolean;
34
open(path: string, flags: string | number, callback: OpenCallback): boolean;
35

36
/**
37
 * Close a file handle
38
 * @param handle - File handle buffer to close
39
 * @param callback - Callback with operation result
40
 * @returns false if SFTP not ready, true otherwise
41
 */
42
close(handle: Buffer, callback?: StatusCallback): boolean;
43

44
/**
45
 * Read data from file handle
46
 * @param handle - File handle to read from
47
 * @param buffer - Buffer to read data into
48
 * @param offset - Offset in buffer to start writing
49
 * @param length - Number of bytes to read
50
 * @param position - Position in file to read from
51
 * @param callback - Callback with read result
52
 * @returns false if SFTP not ready, true otherwise
53
 */
54
read(
55
  handle: Buffer, 
56
  buffer: Buffer, 
57
  offset: number, 
58
  length: number, 
59
  position: number, 
60
  callback?: ReadCallback
61
): boolean;
62

63
/**
64
 * Write data to file handle
65
 * @param handle - File handle to write to
66
 * @param buffer - Buffer containing data to write
67
 * @param offset - Offset in buffer to start reading
68
 * @param length - Number of bytes to write
69
 * @param position - Position in file to write to
70
 * @param callback - Callback with write result
71
 * @returns false if SFTP not ready, true otherwise
72
 */
73
write(
74
  handle: Buffer, 
75
  buffer: Buffer, 
76
  offset: number, 
77
  length: number, 
78
  position: number, 
79
  callback?: WriteCallback
80
): boolean;
81

82
type OpenCallback = (err: Error | null, handle?: Buffer) => void;
83
type StatusCallback = (err: Error | null) => void;
84
type ReadCallback = (err: Error | null, bytesRead?: number, buffer?: Buffer, position?: number) => void;
85
type WriteCallback = (err: Error | null, bytesWritten?: number) => void;
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
// Open and read a file
92
sftp.open('/remote/path/file.txt', 'r', (err, handle) => {
93
  if (err) throw err;
94
  
95
  const buffer = Buffer.alloc(1024);
96
  sftp.read(handle, buffer, 0, 1024, 0, (err, bytesRead, buffer, position) => {
97
    if (err) throw err;
98
    console.log('Read', bytesRead, 'bytes:', buffer.slice(0, bytesRead).toString());
99
    
100
    sftp.close(handle, (err) => {
101
      if (err) throw err;
102
      console.log('File closed');
103
    });
104
  });
105
});
106

107
// Open and write to a file
108
sftp.open('/remote/path/output.txt', 'w', (err, handle) => {
109
  if (err) throw err;
110
  
111
  const data = Buffer.from('Hello, SFTP world!');
112
  sftp.write(handle, data, 0, data.length, 0, (err, bytesWritten) => {
113
    if (err) throw err;
114
    console.log('Wrote', bytesWritten, 'bytes');
115
    sftp.close(handle);
116
  });
117
});
118
```
119

120
### High-Level File Operations
121

122
Convenient methods for complete file operations without manual handle management.
123

124
```javascript { .api }
125
/**
126
 * Fast download of remote file to local filesystem
127
 * @param remotePath - Remote file path
128
 * @param localPath - Local file path
129
 * @param options - Transfer options
130
 * @param callback - Callback with transfer result
131
 * @returns false if SFTP not ready, true otherwise
132
 */
133
fastGet(remotePath: string, localPath: string, options?: TransferOptions, callback?: TransferCallback): boolean;
134
fastGet(remotePath: string, localPath: string, callback: TransferCallback): boolean;
135

136
/**
137
 * Fast upload of local file to remote filesystem
138
 * @param localPath - Local file path
139
 * @param remotePath - Remote file path  
140
 * @param options - Transfer options
141
 * @param callback - Callback with transfer result
142
 * @returns false if SFTP not ready, true otherwise
143
 */
144
fastPut(localPath: string, remotePath: string, options?: TransferOptions, callback?: TransferCallback): boolean;
145
fastPut(localPath: string, remotePath: string, callback: TransferCallback): boolean;
146

147
/**
148
 * Read entire file contents
149
 * @param path - Remote file path
150
 * @param options - Read options
151
 * @param callback - Callback receiving file data
152
 * @returns false if SFTP not ready, true otherwise
153
 */
154
readFile(path: string, options?: ReadFileOptions, callback?: ReadFileCallback): boolean;
155
readFile(path: string, callback: ReadFileCallback): boolean;
156

157
/**
158
 * Write data to file, creating or replacing it
159
 * @param path - Remote file path
160
 * @param data - Data to write
161
 * @param options - Write options
162
 * @param callback - Callback with operation result
163
 * @returns false if SFTP not ready, true otherwise
164
 */
165
writeFile(path: string, data: Buffer | string, options?: WriteFileOptions, callback?: StatusCallback): boolean;
166
writeFile(path: string, data: Buffer | string, callback: StatusCallback): boolean;
167

168
/**
169
 * Append data to existing file
170
 * @param path - Remote file path
171
 * @param data - Data to append
172
 * @param options - Append options
173
 * @param callback - Callback with operation result
174
 * @returns false if SFTP not ready, true otherwise
175
 */
176
appendFile(path: string, data: Buffer | string, options?: WriteFileOptions, callback?: StatusCallback): boolean;
177
appendFile(path: string, data: Buffer | string, callback: StatusCallback): boolean;
178

179
interface TransferOptions {
180
  concurrency?: number;
181
  chunkSize?: number;
182
  step?: (totalTransferred: number, chunk: number, total: number) => void;
183
  mode?: number;
184
}
185

186
interface ReadFileOptions {
187
  encoding?: string;
188
  flag?: string;
189
}
190

191
interface WriteFileOptions {
192
  encoding?: string;
193
  mode?: number;
194
  flag?: string;
195
}
196

197
type TransferCallback = (err: Error | null) => void;
198
type ReadFileCallback = (err: Error | null, data?: Buffer | string) => void;
199
```
200

201
### Directory Operations
202

203
Directory listing, creation, and management operations.
204

205
```javascript { .api }
206
/**
207
 * Open directory for reading
208
 * @param path - Directory path to open
209
 * @param callback - Callback receiving directory handle
210
 * @returns false if SFTP not ready, true otherwise
211
 */
212
opendir(path: string, callback?: OpenCallback): boolean;
213

214
/**
215
 * Read directory contents
216
 * @param path - Directory path to read
217
 * @param options - Read options
218
 * @param callback - Callback receiving directory listing
219
 * @returns false if SFTP not ready, true otherwise
220
 */
221
readdir(path: string, options?: ReaddirOptions, callback?: ReaddirCallback): boolean;
222
readdir(path: string, callback: ReaddirCallback): boolean;
223

224
/**
225
 * Create directory
226
 * @param path - Directory path to create
227
 * @param attrs - Optional directory attributes
228
 * @param callback - Callback with operation result
229
 * @returns false if SFTP not ready, true otherwise
230
 */
231
mkdir(path: string, attrs?: Attributes, callback?: StatusCallback): boolean;
232
mkdir(path: string, callback: StatusCallback): boolean;
233

234
/**
235
 * Remove directory
236
 * @param path - Directory path to remove
237
 * @param callback - Callback with operation result
238
 * @returns false if SFTP not ready, true otherwise
239
 */
240
rmdir(path: string, callback?: StatusCallback): boolean;
241

242
interface ReaddirOptions {
243
  encoding?: string;
244
}
245

246
type ReaddirCallback = (err: Error | null, list?: FileEntry[]) => void;
247

248
interface FileEntry {
249
  filename: string;
250
  longname: string;
251
  attrs: Stats;
252
}
253
```
254

255
### File System Operations
256

257
File and directory metadata operations and path manipulation.
258

259
```javascript { .api }
260
/**
261
 * Get file/directory attributes
262
 * @param path - File or directory path
263
 * @param callback - Callback receiving file attributes
264
 * @returns false if SFTP not ready, true otherwise
265
 */
266
stat(path: string, callback?: AttrsCallback): boolean;
267

268
/**
269
 * Get symlink attributes (don't follow link)
270
 * @param path - Symlink path
271
 * @param callback - Callback receiving link attributes
272
 * @returns false if SFTP not ready, true otherwise
273
 */
274
lstat(path: string, callback?: AttrsCallback): boolean;
275

276
/**
277
 * Get file handle attributes
278
 * @param handle - File handle
279
 * @param callback - Callback receiving file attributes
280
 * @returns false if SFTP not ready, true otherwise
281
 */
282
fstat(handle: Buffer, callback?: AttrsCallback): boolean;
283

284
/**
285
 * Set file/directory attributes
286
 * @param path - File or directory path
287
 * @param attrs - Attributes to set
288
 * @param callback - Callback with operation result
289
 * @returns false if SFTP not ready, true otherwise
290
 */
291
setstat(path: string, attrs: Attributes, callback?: StatusCallback): boolean;
292

293
/**
294
 * Set file handle attributes
295
 * @param handle - File handle
296
 * @param attrs - Attributes to set
297
 * @param callback - Callback with operation result
298
 * @returns false if SFTP not ready, true otherwise
299
 */
300
fsetstat(handle: Buffer, attrs: Attributes, callback?: StatusCallback): boolean;
301

302
/**
303
 * Test if file exists
304
 * @param path - File path to test
305
 * @param callback - Callback with existence result
306
 * @returns false if SFTP not ready, true otherwise
307
 */
308
exists(path: string, callback?: ExistsCallback): boolean;
309

310
/**
311
 * Delete file
312
 * @param path - File path to delete
313
 * @param callback - Callback with operation result
314
 * @returns false if SFTP not ready, true otherwise
315
 */
316
unlink(path: string, callback?: StatusCallback): boolean;
317

318
/**
319
 * Rename/move file or directory
320
 * @param oldPath - Current file path
321
 * @param newPath - New file path
322
 * @param callback - Callback with operation result
323
 * @returns false if SFTP not ready, true otherwise
324
 */
325
rename(oldPath: string, newPath: string, callback?: StatusCallback): boolean;
326

327
type AttrsCallback = (err: Error | null, attrs?: Stats) => void;
328
type ExistsCallback = (exists: boolean) => void;
329
```
330

331
### Link Operations
332

333
Symbolic and hard link management operations.
334

335
```javascript { .api }
336
/**
337
 * Read symbolic link target
338
 * @param path - Symbolic link path
339
 * @param callback - Callback receiving link target
340
 * @returns false if SFTP not ready, true otherwise
341
 */
342
readlink(path: string, callback?: ReadlinkCallback): boolean;
343

344
/**
345
 * Create symbolic link
346
 * @param targetPath - Target path for the link
347
 * @param linkPath - Path where link will be created
348
 * @param callback - Callback with operation result
349
 * @returns false if SFTP not ready, true otherwise
350
 */
351
symlink(targetPath: string, linkPath: string, callback?: StatusCallback): boolean;
352

353
/**
354
 * Resolve absolute path (follow all symlinks)
355
 * @param path - Path to resolve
356
 * @param callback - Callback receiving resolved path
357
 * @returns false if SFTP not ready, true otherwise
358
 */
359
realpath(path: string, callback?: ReadlinkCallback): boolean;
360

361
type ReadlinkCallback = (err: Error | null, target?: string) => void;
362
```
363

364
### Convenience Methods
365

366
Additional utility methods for common file operations.
367

368
```javascript { .api }
369
/**
370
 * Set file handle access and modification times
371
 * @param handle - File handle
372
 * @param atime - Access time
373
 * @param mtime - Modification time
374
 * @param callback - Callback with operation result
375
 * @returns false if SFTP not ready, true otherwise
376
 */
377
futimes(handle: Buffer, atime: number | Date, mtime: number | Date, callback?: StatusCallback): boolean;
378

379
/**
380
 * Set file access and modification times
381
 * @param path - File path
382
 * @param atime - Access time
383
 * @param mtime - Modification time
384
 * @param callback - Callback with operation result
385
 * @returns false if SFTP not ready, true otherwise
386
 */
387
utimes(path: string, atime: number | Date, mtime: number | Date, callback?: StatusCallback): boolean;
388

389
/**
390
 * Change file handle ownership
391
 * @param handle - File handle
392
 * @param uid - New user ID
393
 * @param gid - New group ID
394
 * @param callback - Callback with operation result
395
 * @returns false if SFTP not ready, true otherwise
396
 */
397
fchown(handle: Buffer, uid: number, gid: number, callback?: StatusCallback): boolean;
398

399
/**
400
 * Change file ownership
401
 * @param path - File path
402
 * @param uid - New user ID  
403
 * @param gid - New group ID
404
 * @param callback - Callback with operation result
405
 * @returns false if SFTP not ready, true otherwise
406
 */
407
chown(path: string, uid: number, gid: number, callback?: StatusCallback): boolean;
408

409
/**
410
 * Change file handle permissions
411
 * @param handle - File handle
412
 * @param mode - New permission mode
413
 * @param callback - Callback with operation result
414
 * @returns false if SFTP not ready, true otherwise
415
 */
416
fchmod(handle: Buffer, mode: number, callback?: StatusCallback): boolean;
417

418
/**
419
 * Change file permissions
420
 * @param path - File path
421
 * @param mode - New permission mode
422
 * @param callback - Callback with operation result
423
 * @returns false if SFTP not ready, true otherwise
424
 */
425
chmod(path: string, mode: number, callback?: StatusCallback): boolean;
426
```
427

428
### Stream Operations
429

430
Stream-based file operations for efficient data handling.
431

432
```javascript { .api }
433
/**
434
 * Create readable stream for file
435
 * @param path - Remote file path
436
 * @param options - Stream options
437
 * @returns Readable stream
438
 */
439
createReadStream(path: string, options?: ReadStreamOptions): ReadableStream;
440

441
/**
442
 * Create writable stream for file
443
 * @param path - Remote file path
444
 * @param options - Stream options
445
 * @returns Writable stream
446
 */
447
createWriteStream(path: string, options?: WriteStreamOptions): WritableStream;
448

449
interface ReadStreamOptions {
450
  flags?: string;
451
  encoding?: string;
452
  handle?: Buffer;
453
  mode?: number;
454
  autoClose?: boolean;
455
  start?: number;
456
  end?: number;
457
}
458

459
interface WriteStreamOptions {
460
  flags?: string;
461
  encoding?: string;
462
  mode?: number;
463
  autoClose?: boolean;
464
  start?: number;
465
}
466
```
467

468
**Stream Usage Examples:**
469

470
```javascript
471
// Stream file download
472
const readStream = sftp.createReadStream('/remote/largefile.dat');
473
const writeStream = fs.createWriteStream('/local/largefile.dat');
474

475
readStream.pipe(writeStream);
476

477
writeStream.on('close', () => {
478
  console.log('File downloaded via stream');
479
});
480

481
// Stream file upload  
482
const readStream = fs.createReadStream('/local/upload.dat');
483
const writeStream = sftp.createWriteStream('/remote/upload.dat');
484

485
readStream.pipe(writeStream);
486

487
writeStream.on('close', () => {
488
  console.log('File uploaded via stream');
489
});
490
```
491

492
### OpenSSH Extensions
493

494
Advanced operations specific to OpenSSH SFTP servers.
495

496
```javascript { .api }
497
/**
498
 * Atomic rename operation (OpenSSH extension)
499
 * @param oldPath - Current file path
500
 * @param newPath - New file path
501
 * @param callback - Callback with operation result
502
 * @returns false if SFTP not ready, true otherwise
503
 */
504
ext_openssh_rename(oldPath: string, newPath: string, callback?: StatusCallback): boolean;
505

506
/**
507
 * Get file system statistics (OpenSSH extension)
508
 * @param path - Path on filesystem
509
 * @param callback - Callback receiving filesystem stats
510
 * @returns false if SFTP not ready, true otherwise
511
 */
512
ext_openssh_statvfs(path: string, callback?: StatvfsCallback): boolean;
513

514
/**
515
 * Get file system statistics for handle (OpenSSH extension)
516
 * @param handle - File handle
517
 * @param callback - Callback receiving filesystem stats
518
 * @returns false if SFTP not ready, true otherwise
519
 */
520
ext_openssh_fstatvfs(handle: Buffer, callback?: StatvfsCallback): boolean;
521

522
/**
523
 * Create hard link (OpenSSH extension)
524
 * @param oldPath - Existing file path
525
 * @param newPath - New hard link path
526
 * @param callback - Callback with operation result
527
 * @returns false if SFTP not ready, true otherwise
528
 */
529
ext_openssh_hardlink(oldPath: string, newPath: string, callback?: StatusCallback): boolean;
530

531
/**
532
 * Synchronize file to disk (OpenSSH extension)
533
 * @param handle - File handle to sync
534
 * @param callback - Callback with operation result
535
 * @returns false if SFTP not ready, true otherwise
536
 */
537
ext_openssh_fsync(handle: Buffer, callback?: StatusCallback): boolean;
538

539
/**
540
 * Set symlink attributes without following link (OpenSSH extension)
541
 * @param path - Symlink path
542
 * @param attrs - Attributes to set
543
 * @param callback - Callback with operation result
544
 * @returns false if SFTP not ready, true otherwise
545
 */
546
ext_openssh_lsetstat(path: string, attrs: Attributes, callback?: StatusCallback): boolean;
547

548
/**
549
 * Expand path with wildcards (OpenSSH extension)
550
 * @param path - Path with potential wildcards
551
 * @param callback - Callback receiving expanded paths
552
 * @returns false if SFTP not ready, true otherwise
553
 */
554
ext_openssh_expandPath(path: string, callback?: ExpandPathCallback): boolean;
555

556
/**
557
 * Server-side file copy (OpenSSH extension)
558
 * @param srcHandle - Source file handle
559
 * @param srcOffset - Source file offset
560
 * @param len - Number of bytes to copy
561
 * @param dstHandle - Destination file handle
562
 * @param dstOffset - Destination file offset
563
 * @param callback - Callback with operation result
564
 * @returns false if SFTP not ready, true otherwise
565
 */
566
ext_copy_data(
567
  srcHandle: Buffer, 
568
  srcOffset: number, 
569
  len: number, 
570
  dstHandle: Buffer, 
571
  dstOffset: number, 
572
  callback?: StatusCallback
573
): boolean;
574

575
/**
576
 * Get user home directory (OpenSSH extension)
577
 * @param username - Username to get home directory for
578
 * @param callback - Callback receiving home directory path
579
 * @returns false if SFTP not ready, true otherwise
580
 */
581
ext_home_dir(username: string, callback?: ReadlinkCallback): boolean;
582

583
/**
584
 * Resolve user and group names (OpenSSH extension)
585
 * @param uids - Array of user IDs to resolve
586
 * @param gids - Array of group IDs to resolve
587
 * @param callback - Callback receiving resolved names
588
 * @returns false if SFTP not ready, true otherwise
589
 */
590
ext_users_groups(uids: number[], gids: number[], callback?: UsersGroupsCallback): boolean;
591

592
interface StatvfsInfo {
593
  bsize: number;    // File system block size
594
  frsize: number;   // Fragment size
595
  blocks: number;   // Size of fs in f_frsize units
596
  bfree: number;    // Number of free blocks
597
  bavail: number;   // Number of free blocks for unprivileged users
598
  files: number;    // Number of inodes
599
  ffree: number;    // Number of free inodes
600
  favail: number;   // Number of free inodes for unprivileged users
601
  fsid: number;     // File system ID
602
  flag: number;     // Mount flags
603
  namemax: number;  // Maximum filename length
604
}
605

606
interface UserGroupInfo {
607
  users: { [uid: number]: string };
608
  groups: { [gid: number]: string };
609
}
610

611
type StatvfsCallback = (err: Error | null, info?: StatvfsInfo) => void;
612
type ExpandPathCallback = (err: Error | null, paths?: string[]) => void;
613
type UsersGroupsCallback = (err: Error | null, info?: UserGroupInfo) => void;
614
```
615

616
### Server-Only Methods
617

618
Methods available only when SFTP is operating in server mode.
619

620
```javascript { .api }
621
/**
622
 * Send file handle response (server mode)
623
 * @param reqid - Request ID
624
 * @param handle - File handle to send
625
 * @returns false if not in server mode, true otherwise
626
 */
627
handle(reqid: number, handle: Buffer): boolean;
628

629
/**
630
 * Send status response (server mode)
631
 * @param reqid - Request ID
632
 * @param code - Status code
633
 * @param message - Optional status message
634
 * @returns false if not in server mode, true otherwise
635
 */
636
status(reqid: number, code: number, message?: string): boolean;
637

638
/**
639
 * Send data response (server mode)
640
 * @param reqid - Request ID
641
 * @param data - Data to send
642
 * @param encoding - Optional data encoding
643
 * @returns false if not in server mode, true otherwise
644
 */
645
data(reqid: number, data: Buffer | string, encoding?: string): boolean;
646

647
/**
648
 * Send name response (server mode)
649
 * @param reqid - Request ID
650
 * @param names - Array of file entries
651
 * @returns false if not in server mode, true otherwise
652
 */
653
name(reqid: number, names: FileEntry[]): boolean;
654

655
/**
656
 * Send attributes response (server mode)
657
 * @param reqid - Request ID
658
 * @param attrs - File attributes
659
 * @returns false if not in server mode, true otherwise
660
 */
661
attrs(reqid: number, attrs: Attributes): boolean;
662
```
663

664
## Type Definitions
665

666
### File Attributes and Stats
667

668
```javascript { .api }
669
interface Attributes {
670
  mode?: number;      // File permissions
671
  uid?: number;       // User ID
672
  gid?: number;       // Group ID  
673
  size?: number;      // File size in bytes
674
  atime?: number | Date;  // Access time
675
  mtime?: number | Date;  // Modification time
676
}
677

678
interface Stats extends Attributes {
679
  isFile(): boolean;
680
  isDirectory(): boolean;
681
  isBlockDevice(): boolean;
682
  isCharacterDevice(): boolean;
683
  isSymbolicLink(): boolean;
684
  isFIFO(): boolean;
685
  isSocket(): boolean;
686
}
687
```
688

689
## Constants
690

691
### Status Codes
692

693
```javascript { .api }
694
const STATUS_CODE = {
695
  OK: 0,              // No error
696
  EOF: 1,             // End of file
697
  NO_SUCH_FILE: 2,    // File or directory not found
698
  PERMISSION_DENIED: 3, // Permission denied
699
  FAILURE: 4,         // Generic failure
700
  BAD_MESSAGE: 5,     // Bad protocol message
701
  NO_CONNECTION: 6,   // No connection
702
  CONNECTION_LOST: 7, // Connection lost
703
  OP_UNSUPPORTED: 8   // Operation not supported
704
};
705
```
706

707
### Open Mode Flags
708

709
```javascript { .api }
710
const OPEN_MODE = {
711
  READ: 0x00000001,   // Read access
712
  WRITE: 0x00000002,  // Write access
713
  APPEND: 0x00000004, // Append access
714
  CREAT: 0x00000008,  // Create if doesn't exist
715
  TRUNC: 0x00000010,  // Truncate to zero length
716
  EXCL: 0x00000020    // Fail if file exists (with CREAT)
717
};
718
```
719

720
Access via:
721

722
```javascript
723
const { utils } = require('ssh2');
724
console.log(utils.sftp.STATUS_CODE.OK);        // 0
725
console.log(utils.sftp.OPEN_MODE.READ);        // 1
726
console.log(utils.sftp.flagsToString(0x3));    // "READ,WRITE"
727
console.log(utils.sftp.stringToFlags('rw'));   // 3
728
```