0
# Safe Buffer
1

2
Safe Buffer provides a safer replacement for the Node.js Buffer constructor by implementing secure buffer allocation methods that prevent uninitialized memory disclosure vulnerabilities. It offers drop-in compatibility with existing Buffer usage while providing explicit APIs for safe buffer creation.
3

4
## Package Information
5

6
- **Package Name**: safe-buffer
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install safe-buffer`
10

11
## Core Imports
12

13
```javascript { .api }
14
const { Buffer } = require('safe-buffer');
15
```
16

17
For TypeScript:
18

19
```typescript { .api }
20
import { Buffer } from 'safe-buffer';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { Buffer } = require('safe-buffer');
27

28
// Existing buffer code continues to work
29
new Buffer('hello', 'utf8');
30
new Buffer([1, 2, 3]);
31
new Buffer(16); // creates uninitialized buffer
32

33
// But you should use these explicit APIs for clarity and safety
34
Buffer.from('hello', 'utf8'); // convert from many types to Buffer
35
Buffer.alloc(16); // create zero-filled buffer (safe)
36
Buffer.allocUnsafe(16); // create uninitialized buffer (potentially unsafe)
37
Buffer.allocUnsafeSlow(16); // create non-pooled uninitialized buffer
38
```
39

40
## Capabilities
41

42
### Buffer Constructor
43

44
Creates Buffer instances using various input types.
45

46
```javascript { .api }
47
/**
48
 * Creates a new Buffer from string with optional encoding
49
 * @param str - String to store in buffer
50
 * @param encoding - Character encoding (default: 'utf8')
51
 */
52
new Buffer(str, encoding);
53

54
/**
55
 * Creates a new Buffer of specified size
56
 * @param size - Count of octets to allocate
57
 */
58
new Buffer(size);
59

60
/**
61
 * Creates a new Buffer from Uint8Array
62
 * @param array - Uint8Array to copy
63
 */
64
new Buffer(array);
65

66
/**
67
 * Creates a new Buffer backed by ArrayBuffer
68
 * @param arrayBuffer - ArrayBuffer to share memory with
69
 */
70
new Buffer(arrayBuffer);
71

72
/**
73
 * Creates a new Buffer from array of octets
74
 * @param array - Array of octets to store
75
 */
76
new Buffer(array);
77

78
/**
79
 * Copies an existing Buffer
80
 * @param buffer - Buffer to copy
81
 */
82
new Buffer(buffer);
83
```
84

85
### Safe Buffer Creation
86

87
Modern, explicit buffer creation methods that prevent common security vulnerabilities.
88

89
```javascript { .api }
90
/**
91
 * Creates Buffer from array of octets
92
 * @param array - Array of octets
93
 * @returns Buffer containing the array data
94
 * @throws TypeError if array is not an Array
95
 */
96
Buffer.from(array);
97

98
/**
99
 * Creates Buffer from ArrayBuffer with optional offset and length
100
 * @param arrayBuffer - ArrayBuffer to share memory with
101
 * @param byteOffset - Starting offset (default: 0)
102
 * @param length - Length to use (default: arrayBuffer.length - byteOffset)
103
 * @returns Buffer sharing memory with ArrayBuffer
104
 * @throws TypeError if arrayBuffer is not an ArrayBuffer
105
 */
106
Buffer.from(arrayBuffer, byteOffset, length);
107

108
/**
109
 * Copies existing Buffer data
110
 * @param buffer - Buffer to copy
111
 * @returns New Buffer with copied data
112
 * @throws TypeError if buffer is not a Buffer
113
 */
114
Buffer.from(buffer);
115

116
/**
117
 * Creates Buffer from string with optional encoding
118
 * @param str - String to encode
119
 * @param encoding - Character encoding (default: 'utf8')
120
 * @returns Buffer containing encoded string
121
 * @throws TypeError if str is not a string
122
 * @throws TypeError if called with a number (safe-buffer prevents this)
123
 */
124
Buffer.from(str, encoding);
125

126
/**
127
 * Allocates zero-filled Buffer of specified size
128
 * @param size - Count of octets to allocate
129
 * @param fill - Value to fill buffer with (default: 0)
130
 * @param encoding - Encoding for fill if fill is string (default: 'utf8')
131
 * @returns Zero-filled or filled Buffer
132
 * @throws TypeError if size is not a number
133
 * @throws RangeError if size exceeds maximum
134
 */
135
Buffer.alloc(size, fill, encoding);
136

137
/**
138
 * Allocates uninitialized Buffer (potentially unsafe but fast)
139
 * @param size - Count of octets to allocate
140
 * @returns Uninitialized Buffer (may contain sensitive data)
141
 * @throws TypeError if size is not a number
142
 * @throws RangeError if size exceeds maximum
143
 */
144
Buffer.allocUnsafe(size);
145

146
/**
147
 * Allocates non-pooled uninitialized Buffer
148
 * @param size - Count of octets to allocate
149
 * @returns Non-pooled uninitialized Buffer
150
 * @throws TypeError if size is not a number
151
 * @throws RangeError if size exceeds maximum
152
 */
153
Buffer.allocUnsafeSlow(size);
154
```
155

156
### Buffer Utility Methods
157

158
Static utility methods for working with Buffers.
159

160
```javascript { .api }
161
/**
162
 * Tests if object is a Buffer
163
 * @param obj - Object to test
164
 * @returns true if obj is a Buffer, false otherwise
165
 */
166
Buffer.isBuffer(obj);
167

168
/**
169
 * Tests if encoding is valid
170
 * @param encoding - String to test
171
 * @returns true if encoding is valid, false otherwise
172
 */
173
Buffer.isEncoding(encoding);
174

175
/**
176
 * Gets actual byte length of string
177
 * @param string - String to measure
178
 * @param encoding - Encoding to use (default: 'utf8')
179
 * @returns Byte length of string
180
 */
181
Buffer.byteLength(string, encoding);
182

183
/**
184
 * Concatenates array of Buffers
185
 * @param list - Array of Buffer objects to concatenate
186
 * @param totalLength - Total length when concatenated (optional, for performance)
187
 * @returns New Buffer containing concatenated data
188
 */
189
Buffer.concat(list, totalLength);
190

191
/**
192
 * Compares two Buffers
193
 * @param buf1 - First Buffer
194
 * @param buf2 - Second Buffer
195
 * @returns -1, 0, or 1 based on comparison result
196
 */
197
Buffer.compare(buf1, buf2);
198
```
199

200
### Buffer Instance Methods
201

202
Methods available on Buffer instances for reading, writing, and manipulating data.
203

204
```javascript { .api }
205
/**
206
 * Buffer length in bytes
207
 */
208
buffer.length;
209

210
/**
211
 * Writes string to buffer at offset
212
 * @param string - String to write
213
 * @param offset - Starting offset (default: 0)
214
 * @param length - Number of bytes to write (optional)
215
 * @param encoding - Character encoding (default: 'utf8')
216
 * @returns Number of bytes written
217
 */
218
buffer.write(string, offset, length, encoding);
219

220
/**
221
 * Converts buffer to string
222
 * @param encoding - Character encoding (default: 'utf8')
223
 * @param start - Starting offset (default: 0)
224
 * @param end - Ending offset (default: buffer.length)
225
 * @returns String representation of buffer
226
 */
227
buffer.toString(encoding, start, end);
228

229
/**
230
 * Converts buffer to JSON representation
231
 * @returns Object with type 'Buffer' and data array
232
 */
233
buffer.toJSON();
234

235
/**
236
 * Tests equality with another buffer
237
 * @param otherBuffer - Buffer to compare with
238
 * @returns true if buffers are equal, false otherwise
239
 */
240
buffer.equals(otherBuffer);
241

242
/**
243
 * Compares buffer with another buffer
244
 * @param otherBuffer - Buffer to compare with
245
 * @param targetStart - Start offset in target (optional)
246
 * @param targetEnd - End offset in target (optional)
247
 * @param sourceStart - Start offset in source (optional)
248
 * @param sourceEnd - End offset in source (optional)
249
 * @returns -1, 0, or 1 based on comparison result
250
 */
251
buffer.compare(otherBuffer, targetStart, targetEnd, sourceStart, sourceEnd);
252

253
/**
254
 * Copies buffer data to target buffer
255
 * @param targetBuffer - Buffer to copy data to
256
 * @param targetStart - Start offset in target (default: 0)
257
 * @param sourceStart - Start offset in source (default: 0)
258
 * @param sourceEnd - End offset in source (default: buffer.length)
259
 * @returns Number of bytes copied
260
 */
261
buffer.copy(targetBuffer, targetStart, sourceStart, sourceEnd);
262

263
/**
264
 * Creates shallow copy of buffer slice
265
 * @param start - Start offset (default: 0)
266
 * @param end - End offset (default: buffer.length)
267
 * @returns New Buffer containing slice of data
268
 */
269
buffer.slice(start, end);
270

271
/**
272
 * Fills buffer with specified value
273
 * @param value - Value to fill with (string, Buffer, or number)
274
 * @param offset - Start offset (default: 0)
275
 * @param end - End offset (default: buffer.length)
276
 * @returns Reference to buffer (for chaining)
277
 */
278
buffer.fill(value, offset, end);
279

280
/**
281
 * Finds first occurrence of value in buffer
282
 * @param value - Value to search for (string, number, or Buffer)
283
 * @param byteOffset - Starting offset for search (default: 0)
284
 * @param encoding - String encoding if value is string (default: 'utf8')
285
 * @returns Index of first occurrence, or -1 if not found
286
 */
287
buffer.indexOf(value, byteOffset, encoding);
288

289
/**
290
 * Finds last occurrence of value in buffer
291
 * @param value - Value to search for (string, number, or Buffer)
292
 * @param byteOffset - Starting offset for search (default: buffer.length - 1)
293
 * @param encoding - String encoding if value is string (default: 'utf8')
294
 * @returns Index of last occurrence, or -1 if not found
295
 */
296
buffer.lastIndexOf(value, byteOffset, encoding);
297

298
/**
299
 * Tests if buffer includes specified value
300
 * @param value - Value to search for (string, number, or Buffer)
301
 * @param byteOffset - Starting offset for search (default: 0)
302
 * @param encoding - String encoding if value is string (default: 'utf8')
303
 * @returns true if buffer includes value, false otherwise
304
 */
305
buffer.includes(value, byteOffset, encoding);
306
```
307

308
### Numeric Data Reading
309

310
Methods for reading numeric values from buffers.
311

312
```javascript { .api }
313
/**
314
 * Read unsigned 8-bit integer
315
 * @param offset - Byte offset
316
 * @param noAssert - Skip validation (deprecated, ignored)
317
 * @returns Unsigned 8-bit integer
318
 */
319
buffer.readUInt8(offset, noAssert);
320

321
/**
322
 * Read unsigned 16-bit integer, little endian
323
 * @param offset - Byte offset
324
 * @param noAssert - Skip validation (deprecated, ignored)
325
 * @returns Unsigned 16-bit integer
326
 */
327
buffer.readUInt16LE(offset, noAssert);
328

329
/**
330
 * Read unsigned 16-bit integer, big endian
331
 * @param offset - Byte offset
332
 * @param noAssert - Skip validation (deprecated, ignored)
333
 * @returns Unsigned 16-bit integer
334
 */
335
buffer.readUInt16BE(offset, noAssert);
336

337
/**
338
 * Read unsigned 32-bit integer, little endian
339
 * @param offset - Byte offset
340
 * @param noAssert - Skip validation (deprecated, ignored)
341
 * @returns Unsigned 32-bit integer
342
 */
343
buffer.readUInt32LE(offset, noAssert);
344

345
/**
346
 * Read unsigned 32-bit integer, big endian
347
 * @param offset - Byte offset
348
 * @param noAssert - Skip validation (deprecated, ignored)
349
 * @returns Unsigned 32-bit integer
350
 */
351
buffer.readUInt32BE(offset, noAssert);
352

353
/**
354
 * Read signed 8-bit integer
355
 * @param offset - Byte offset
356
 * @param noAssert - Skip validation (deprecated, ignored)
357
 * @returns Signed 8-bit integer
358
 */
359
buffer.readInt8(offset, noAssert);
360

361
/**
362
 * Read signed 16-bit integer, little endian
363
 * @param offset - Byte offset
364
 * @param noAssert - Skip validation (deprecated, ignored)
365
 * @returns Signed 16-bit integer
366
 */
367
buffer.readInt16LE(offset, noAssert);
368

369
/**
370
 * Read signed 16-bit integer, big endian
371
 * @param offset - Byte offset
372
 * @param noAssert - Skip validation (deprecated, ignored)
373
 * @returns Signed 16-bit integer
374
 */
375
buffer.readInt16BE(offset, noAssert);
376

377
/**
378
 * Read signed 32-bit integer, little endian
379
 * @param offset - Byte offset
380
 * @param noAssert - Skip validation (deprecated, ignored)
381
 * @returns Signed 32-bit integer
382
 */
383
buffer.readInt32LE(offset, noAssert);
384

385
/**
386
 * Read signed 32-bit integer, big endian
387
 * @param offset - Byte offset
388
 * @param noAssert - Skip validation (deprecated, ignored)
389
 * @returns Signed 32-bit integer
390
 */
391
buffer.readInt32BE(offset, noAssert);
392

393
/**
394
 * Read 32-bit float, little endian
395
 * @param offset - Byte offset
396
 * @param noAssert - Skip validation (deprecated, ignored)
397
 * @returns 32-bit float
398
 */
399
buffer.readFloatLE(offset, noAssert);
400

401
/**
402
 * Read 32-bit float, big endian
403
 * @param offset - Byte offset
404
 * @param noAssert - Skip validation (deprecated, ignored)
405
 * @returns 32-bit float
406
 */
407
buffer.readFloatBE(offset, noAssert);
408

409
/**
410
 * Read 64-bit double, little endian
411
 * @param offset - Byte offset
412
 * @param noAssert - Skip validation (deprecated, ignored)
413
 * @returns 64-bit double
414
 */
415
buffer.readDoubleLE(offset, noAssert);
416

417
/**
418
 * Read 64-bit double, big endian
419
 * @param offset - Byte offset
420
 * @param noAssert - Skip validation (deprecated, ignored)
421
 * @returns 64-bit double
422
 */
423
buffer.readDoubleBE(offset, noAssert);
424

425
/**
426
 * Read unsigned integer with specified byte length, little endian
427
 * @param offset - Byte offset
428
 * @param byteLength - Number of bytes to read (1-6)
429
 * @param noAssert - Skip validation (deprecated, ignored)
430
 * @returns Unsigned integer
431
 */
432
buffer.readUIntLE(offset, byteLength, noAssert);
433

434
/**
435
 * Read unsigned integer with specified byte length, big endian
436
 * @param offset - Byte offset
437
 * @param byteLength - Number of bytes to read (1-6)
438
 * @param noAssert - Skip validation (deprecated, ignored)
439
 * @returns Unsigned integer
440
 */
441
buffer.readUIntBE(offset, byteLength, noAssert);
442

443
/**
444
 * Read signed integer with specified byte length, little endian
445
 * @param offset - Byte offset
446
 * @param byteLength - Number of bytes to read (1-6)
447
 * @param noAssert - Skip validation (deprecated, ignored)
448
 * @returns Signed integer
449
 */
450
buffer.readIntLE(offset, byteLength, noAssert);
451

452
/**
453
 * Read signed integer with specified byte length, big endian
454
 * @param offset - Byte offset
455
 * @param byteLength - Number of bytes to read (1-6)
456
 * @param noAssert - Skip validation (deprecated, ignored)
457
 * @returns Signed integer
458
 */
459
buffer.readIntBE(offset, byteLength, noAssert);
460
```
461

462
### Numeric Data Writing
463

464
Methods for writing numeric values to buffers.
465

466
```javascript { .api }
467
/**
468
 * Write unsigned 8-bit integer
469
 * @param value - Value to write (0-255)
470
 * @param offset - Byte offset
471
 * @param noAssert - Skip validation (deprecated, ignored)
472
 * @returns Offset plus bytes written
473
 */
474
buffer.writeUInt8(value, offset, noAssert);
475

476
/**
477
 * Write unsigned 16-bit integer, little endian
478
 * @param value - Value to write (0-65535)
479
 * @param offset - Byte offset
480
 * @param noAssert - Skip validation (deprecated, ignored)
481
 * @returns Offset plus bytes written
482
 */
483
buffer.writeUInt16LE(value, offset, noAssert);
484

485
/**
486
 * Write unsigned 16-bit integer, big endian
487
 * @param value - Value to write (0-65535)
488
 * @param offset - Byte offset
489
 * @param noAssert - Skip validation (deprecated, ignored)
490
 * @returns Offset plus bytes written
491
 */
492
buffer.writeUInt16BE(value, offset, noAssert);
493

494
/**
495
 * Write unsigned 32-bit integer, little endian
496
 * @param value - Value to write (0-4294967295)
497
 * @param offset - Byte offset
498
 * @param noAssert - Skip validation (deprecated, ignored)
499
 * @returns Offset plus bytes written
500
 */
501
buffer.writeUInt32LE(value, offset, noAssert);
502

503
/**
504
 * Write unsigned 32-bit integer, big endian
505
 * @param value - Value to write (0-4294967295)
506
 * @param offset - Byte offset
507
 * @param noAssert - Skip validation (deprecated, ignored)
508
 * @returns Offset plus bytes written
509
 */
510
buffer.writeUInt32BE(value, offset, noAssert);
511

512
/**
513
 * Write signed 8-bit integer
514
 * @param value - Value to write (-128 to 127)
515
 * @param offset - Byte offset
516
 * @param noAssert - Skip validation (deprecated, ignored)
517
 * @returns Offset plus bytes written
518
 */
519
buffer.writeInt8(value, offset, noAssert);
520

521
/**
522
 * Write signed 16-bit integer, little endian
523
 * @param value - Value to write (-32768 to 32767)
524
 * @param offset - Byte offset
525
 * @param noAssert - Skip validation (deprecated, ignored)
526
 * @returns Offset plus bytes written
527
 */
528
buffer.writeInt16LE(value, offset, noAssert);
529

530
/**
531
 * Write signed 16-bit integer, big endian
532
 * @param value - Value to write (-32768 to 32767)
533
 * @param offset - Byte offset
534
 * @param noAssert - Skip validation (deprecated, ignored)
535
 * @returns Offset plus bytes written
536
 */
537
buffer.writeInt16BE(value, offset, noAssert);
538

539
/**
540
 * Write signed 32-bit integer, little endian
541
 * @param value - Value to write (-2147483648 to 2147483647)
542
 * @param offset - Byte offset
543
 * @param noAssert - Skip validation (deprecated, ignored)
544
 * @returns Offset plus bytes written
545
 */
546
buffer.writeInt32LE(value, offset, noAssert);
547

548
/**
549
 * Write signed 32-bit integer, big endian
550
 * @param value - Value to write (-2147483648 to 2147483647)
551
 * @param offset - Byte offset
552
 * @param noAssert - Skip validation (deprecated, ignored)
553
 * @returns Offset plus bytes written
554
 */
555
buffer.writeInt32BE(value, offset, noAssert);
556

557
/**
558
 * Write 32-bit float, little endian
559
 * @param value - Float value to write
560
 * @param offset - Byte offset
561
 * @param noAssert - Skip validation (deprecated, ignored)
562
 * @returns Offset plus bytes written
563
 */
564
buffer.writeFloatLE(value, offset, noAssert);
565

566
/**
567
 * Write 32-bit float, big endian
568
 * @param value - Float value to write
569
 * @param offset - Byte offset
570
 * @param noAssert - Skip validation (deprecated, ignored)
571
 * @returns Offset plus bytes written
572
 */
573
buffer.writeFloatBE(value, offset, noAssert);
574

575
/**
576
 * Write 64-bit double, little endian
577
 * @param value - Double value to write
578
 * @param offset - Byte offset
579
 * @param noAssert - Skip validation (deprecated, ignored)
580
 * @returns Offset plus bytes written
581
 */
582
buffer.writeDoubleLE(value, offset, noAssert);
583

584
/**
585
 * Write 64-bit double, big endian
586
 * @param value - Double value to write
587
 * @param offset - Byte offset
588
 * @param noAssert - Skip validation (deprecated, ignored)
589
 * @returns Offset plus bytes written
590
 */
591
buffer.writeDoubleBE(value, offset, noAssert);
592

593
/**
594
 * Write unsigned integer with specified byte length, little endian
595
 * @param value - Value to write
596
 * @param offset - Byte offset
597
 * @param byteLength - Number of bytes to write (1-6)
598
 * @param noAssert - Skip validation (deprecated, ignored)
599
 * @returns Offset plus bytes written
600
 */
601
buffer.writeUIntLE(value, offset, byteLength, noAssert);
602

603
/**
604
 * Write unsigned integer with specified byte length, big endian
605
 * @param value - Value to write
606
 * @param offset - Byte offset
607
 * @param byteLength - Number of bytes to write (1-6)
608
 * @param noAssert - Skip validation (deprecated, ignored)
609
 * @returns Offset plus bytes written
610
 */
611
buffer.writeUIntBE(value, offset, byteLength, noAssert);
612

613
/**
614
 * Write signed integer with specified byte length, little endian
615
 * @param value - Value to write
616
 * @param offset - Byte offset
617
 * @param byteLength - Number of bytes to write (1-6)
618
 * @param noAssert - Skip validation (deprecated, ignored)
619
 * @returns Offset plus bytes written
620
 */
621
buffer.writeIntLE(value, offset, byteLength, noAssert);
622

623
/**
624
 * Write signed integer with specified byte length, big endian
625
 * @param value - Value to write
626
 * @param offset - Byte offset
627
 * @param byteLength - Number of bytes to write (1-6)
628
 * @param noAssert - Skip validation (deprecated, ignored)
629
 * @returns Offset plus bytes written
630
 */
631
buffer.writeIntBE(value, offset, byteLength, noAssert);
632
```
633

634
### Byte Order Operations
635

636
Methods for swapping byte order in buffers.
637

638
```javascript { .api }
639
/**
640
 * Swap byte order for 16-bit values in buffer
641
 * @returns Reference to buffer (for chaining)
642
 */
643
buffer.swap16();
644

645
/**
646
 * Swap byte order for 32-bit values in buffer
647
 * @returns Reference to buffer (for chaining)
648
 */
649
buffer.swap32();
650

651
/**
652
 * Swap byte order for 64-bit values in buffer
653
 * @returns Reference to buffer (for chaining)
654
 */
655
buffer.swap64();
656
```
657

658
## Error Handling
659

660
Safe Buffer includes several important error handling behaviors:
661

662
- **TypeError**: Thrown when `Buffer.from()` is called with a number (prevents uninitialized memory allocation)
663
- **TypeError**: Thrown when allocation methods receive non-number size arguments
664
- **RangeError**: Thrown when buffer size exceeds platform limits (`require('buffer').kMaxLength`)
665

666
## Security Features
667

668
- **Memory Safety**: `Buffer.alloc()` initializes memory to zero, preventing information leakage
669
- **Explicit Unsafe Operations**: `Buffer.allocUnsafe()` and `Buffer.allocUnsafeSlow()` are clearly marked as potentially unsafe
670
- **Input Validation**: Strict type checking prevents common buffer creation vulnerabilities
671
- **Drop-in Compatibility**: Works as a secure replacement for native Buffer in older Node.js versions