or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-safe-buffer

Safer Node.js Buffer API with secure buffer allocation methods to prevent uninitialized memory disclosure vulnerabilities

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/safe-buffer@5.2.x

To install, run

npx @tessl/cli install tessl/npm-safe-buffer@5.2.0

Safe Buffer

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.

Package Information

Package Name: safe-buffer
Package Type: npm
Language: JavaScript (with TypeScript definitions)
Installation: npm install safe-buffer

Core Imports

const { Buffer } = require('safe-buffer');

For TypeScript:

import { Buffer } from 'safe-buffer';

Basic Usage

const { Buffer } = require('safe-buffer');

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

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

Capabilities

Buffer Constructor

Creates Buffer instances using various input types.

/**
 * Creates a new Buffer from string with optional encoding
 * @param str - String to store in buffer
 * @param encoding - Character encoding (default: 'utf8')
 */
new Buffer(str, encoding);

/**
 * Creates a new Buffer of specified size
 * @param size - Count of octets to allocate
 */
new Buffer(size);

/**
 * Creates a new Buffer from Uint8Array
 * @param array - Uint8Array to copy
 */
new Buffer(array);

/**
 * Creates a new Buffer backed by ArrayBuffer
 * @param arrayBuffer - ArrayBuffer to share memory with
 */
new Buffer(arrayBuffer);

/**
 * Creates a new Buffer from array of octets
 * @param array - Array of octets to store
 */
new Buffer(array);

/**
 * Copies an existing Buffer
 * @param buffer - Buffer to copy
 */
new Buffer(buffer);

Safe Buffer Creation

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

/**
 * Creates Buffer from array of octets
 * @param array - Array of octets
 * @returns Buffer containing the array data
 * @throws TypeError if array is not an Array
 */
Buffer.from(array);

/**
 * Creates Buffer from ArrayBuffer with optional offset and length
 * @param arrayBuffer - ArrayBuffer to share memory with
 * @param byteOffset - Starting offset (default: 0)
 * @param length - Length to use (default: arrayBuffer.length - byteOffset)
 * @returns Buffer sharing memory with ArrayBuffer
 * @throws TypeError if arrayBuffer is not an ArrayBuffer
 */
Buffer.from(arrayBuffer, byteOffset, length);

/**
 * Copies existing Buffer data
 * @param buffer - Buffer to copy
 * @returns New Buffer with copied data
 * @throws TypeError if buffer is not a Buffer
 */
Buffer.from(buffer);

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

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

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

/**
 * Allocates non-pooled uninitialized Buffer
 * @param size - Count of octets to allocate
 * @returns Non-pooled uninitialized Buffer
 * @throws TypeError if size is not a number
 * @throws RangeError if size exceeds maximum
 */
Buffer.allocUnsafeSlow(size);

Buffer Utility Methods

Static utility methods for working with Buffers.

/**
 * Tests if object is a Buffer
 * @param obj - Object to test
 * @returns true if obj is a Buffer, false otherwise
 */
Buffer.isBuffer(obj);

/**
 * Tests if encoding is valid
 * @param encoding - String to test
 * @returns true if encoding is valid, false otherwise
 */
Buffer.isEncoding(encoding);

/**
 * Gets actual byte length of string
 * @param string - String to measure
 * @param encoding - Encoding to use (default: 'utf8')
 * @returns Byte length of string
 */
Buffer.byteLength(string, encoding);

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

/**
 * Compares two Buffers
 * @param buf1 - First Buffer
 * @param buf2 - Second Buffer
 * @returns -1, 0, or 1 based on comparison result
 */
Buffer.compare(buf1, buf2);

Buffer Instance Methods

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

/**
 * Buffer length in bytes
 */
buffer.length;

/**
 * Writes string to buffer at offset
 * @param string - String to write
 * @param offset - Starting offset (default: 0)
 * @param length - Number of bytes to write (optional)
 * @param encoding - Character encoding (default: 'utf8')
 * @returns Number of bytes written
 */
buffer.write(string, offset, length, encoding);

/**
 * Converts buffer to string
 * @param encoding - Character encoding (default: 'utf8')
 * @param start - Starting offset (default: 0)
 * @param end - Ending offset (default: buffer.length)
 * @returns String representation of buffer
 */
buffer.toString(encoding, start, end);

/**
 * Converts buffer to JSON representation
 * @returns Object with type 'Buffer' and data array
 */
buffer.toJSON();

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

/**
 * Compares buffer with another buffer
 * @param otherBuffer - Buffer to compare with
 * @param targetStart - Start offset in target (optional)
 * @param targetEnd - End offset in target (optional)
 * @param sourceStart - Start offset in source (optional)
 * @param sourceEnd - End offset in source (optional)
 * @returns -1, 0, or 1 based on comparison result
 */
buffer.compare(otherBuffer, targetStart, targetEnd, sourceStart, sourceEnd);

/**
 * Copies buffer data to target buffer
 * @param targetBuffer - Buffer to copy data to
 * @param targetStart - Start offset in target (default: 0)
 * @param sourceStart - Start offset in source (default: 0)
 * @param sourceEnd - End offset in source (default: buffer.length)
 * @returns Number of bytes copied
 */
buffer.copy(targetBuffer, targetStart, sourceStart, sourceEnd);

/**
 * Creates shallow copy of buffer slice
 * @param start - Start offset (default: 0)
 * @param end - End offset (default: buffer.length)
 * @returns New Buffer containing slice of data
 */
buffer.slice(start, end);

/**
 * Fills buffer with specified value
 * @param value - Value to fill with (string, Buffer, or number)
 * @param offset - Start offset (default: 0)
 * @param end - End offset (default: buffer.length)
 * @returns Reference to buffer (for chaining)
 */
buffer.fill(value, offset, end);

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

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

/**
 * Tests if buffer includes specified value
 * @param value - Value to search for (string, number, or Buffer)
 * @param byteOffset - Starting offset for search (default: 0)
 * @param encoding - String encoding if value is string (default: 'utf8')
 * @returns true if buffer includes value, false otherwise
 */
buffer.includes(value, byteOffset, encoding);

Numeric Data Reading

Methods for reading numeric values from buffers.

/**
 * Read unsigned 8-bit integer
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Unsigned 8-bit integer
 */
buffer.readUInt8(offset, noAssert);

/**
 * Read unsigned 16-bit integer, little endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Unsigned 16-bit integer
 */
buffer.readUInt16LE(offset, noAssert);

/**
 * Read unsigned 16-bit integer, big endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Unsigned 16-bit integer
 */
buffer.readUInt16BE(offset, noAssert);

/**
 * Read unsigned 32-bit integer, little endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Unsigned 32-bit integer
 */
buffer.readUInt32LE(offset, noAssert);

/**
 * Read unsigned 32-bit integer, big endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Unsigned 32-bit integer
 */
buffer.readUInt32BE(offset, noAssert);

/**
 * Read signed 8-bit integer
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Signed 8-bit integer
 */
buffer.readInt8(offset, noAssert);

/**
 * Read signed 16-bit integer, little endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Signed 16-bit integer
 */
buffer.readInt16LE(offset, noAssert);

/**
 * Read signed 16-bit integer, big endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Signed 16-bit integer
 */
buffer.readInt16BE(offset, noAssert);

/**
 * Read signed 32-bit integer, little endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Signed 32-bit integer
 */
buffer.readInt32LE(offset, noAssert);

/**
 * Read signed 32-bit integer, big endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Signed 32-bit integer
 */
buffer.readInt32BE(offset, noAssert);

/**
 * Read 32-bit float, little endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns 32-bit float
 */
buffer.readFloatLE(offset, noAssert);

/**
 * Read 32-bit float, big endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns 32-bit float
 */
buffer.readFloatBE(offset, noAssert);

/**
 * Read 64-bit double, little endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns 64-bit double
 */
buffer.readDoubleLE(offset, noAssert);

/**
 * Read 64-bit double, big endian
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns 64-bit double
 */
buffer.readDoubleBE(offset, noAssert);

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

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

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

/**
 * Read signed integer with specified byte length, big endian
 * @param offset - Byte offset
 * @param byteLength - Number of bytes to read (1-6)
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Signed integer
 */
buffer.readIntBE(offset, byteLength, noAssert);

Numeric Data Writing

Methods for writing numeric values to buffers.

/**
 * Write unsigned 8-bit integer
 * @param value - Value to write (0-255)
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Offset plus bytes written
 */
buffer.writeUInt8(value, offset, noAssert);

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

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

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

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

/**
 * Write signed 8-bit integer
 * @param value - Value to write (-128 to 127)
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Offset plus bytes written
 */
buffer.writeInt8(value, offset, noAssert);

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

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

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

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

/**
 * Write 32-bit float, little endian
 * @param value - Float value to write
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Offset plus bytes written
 */
buffer.writeFloatLE(value, offset, noAssert);

/**
 * Write 32-bit float, big endian
 * @param value - Float value to write
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Offset plus bytes written
 */
buffer.writeFloatBE(value, offset, noAssert);

/**
 * Write 64-bit double, little endian
 * @param value - Double value to write
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Offset plus bytes written
 */
buffer.writeDoubleLE(value, offset, noAssert);

/**
 * Write 64-bit double, big endian
 * @param value - Double value to write
 * @param offset - Byte offset
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Offset plus bytes written
 */
buffer.writeDoubleBE(value, offset, noAssert);

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

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

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

/**
 * Write signed integer with specified byte length, big endian
 * @param value - Value to write
 * @param offset - Byte offset
 * @param byteLength - Number of bytes to write (1-6)
 * @param noAssert - Skip validation (deprecated, ignored)
 * @returns Offset plus bytes written
 */
buffer.writeIntBE(value, offset, byteLength, noAssert);

Byte Order Operations

Methods for swapping byte order in buffers.

/**
 * Swap byte order for 16-bit values in buffer
 * @returns Reference to buffer (for chaining)
 */
buffer.swap16();

/**
 * Swap byte order for 32-bit values in buffer
 * @returns Reference to buffer (for chaining)
 */
buffer.swap32();

/**
 * Swap byte order for 64-bit values in buffer
 * @returns Reference to buffer (for chaining)
 */
buffer.swap64();

Error Handling

Safe Buffer includes several important error handling behaviors:

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

Security Features

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