Safer Node.js Buffer API Polyfill

Common errors

• DeprecationWarning: new Buffer() is deprecated

  cause Using the `new Buffer()` constructor directly or indirectly via `safe-buffer` in Node.js v10.0.0 or higher.
  fix Replace all instances of `new Buffer(...)` with `Buffer.alloc(...)` for zero-filled buffers, `Buffer.allocUnsafe(...)` for uninitialized buffers, or `Buffer.from(...)` for creating buffers from existing data.

• TypeError: Class constructor Buffer cannot be invoked without 'new'

  cause Attempting to call `Buffer()` as a function (e.g., `Buffer(10)`) in Node.js versions where `Buffer` is strictly a class constructor.
  fix If creating a new buffer, use `new Buffer(...)` (deprecated in modern Node.js) or preferably `Buffer.alloc(...)`, `Buffer.allocUnsafe(...)`, or `Buffer.from(...)`.

• Potential sensitive data disclosure due to uninitialized buffer memory.

  cause Using `Buffer.allocUnsafe(size)` without immediately and fully overwriting its contents, or relying on `new Buffer(size)` / `Buffer(size)` in Node.js < v8.0.0.
  fix For all new allocations, use `Buffer.alloc(size)` which guarantees zero-filled memory. If `Buffer.allocUnsafe(size)` is used for performance, ensure the entire allocated memory segment is explicitly written to before any part of the buffer is exposed or returned.

Warnings

• breaking The `new Buffer(size)` constructor (and `Buffer(size)` as a function call) created uninitialized memory in Node.js versions prior to 8.0.0. This could lead to disclosure of sensitive data if the buffer was not entirely overwritten before being exposed. `safe-buffer` provides `Buffer.alloc()` for safe, zero-filled buffers and `Buffer.allocUnsafe()` for performance-critical scenarios where uninitialized memory is acceptable, emphasizing the need for developers to explicitly choose safe allocation.
  Fix: Always use `Buffer.alloc(size)` for new buffer allocations unless `Buffer.allocUnsafe(size)` is explicitly required for performance and you are certain the buffer's contents will be fully overwritten immediately.
• deprecated The `new Buffer()` constructor is officially deprecated in Node.js since v10.0.0 and has been completely removed in v12.0.0. While `safe-buffer` allows its use for backward compatibility, relying on it will lead to runtime deprecation warnings in Node.js v10/v11 and errors in v12+.
  Fix: Migrate all uses of `new Buffer()` or `Buffer()` (as a function) to `Buffer.alloc()`, `Buffer.allocUnsafe()`, or `Buffer.from()` based on the desired allocation and initialization behavior.
• gotcha Using `safe-buffer` in Node.js versions 6.0.0 and above is largely redundant, as these versions natively include `Buffer.from()`, `Buffer.alloc()`, and `Buffer.allocUnsafe()` methods. While `safe-buffer` gracefully defers to the native implementation when available, it adds an unnecessary dependency and a layer of indirection to your project.
  Fix: For new projects targeting Node.js 6.0.0+, avoid `safe-buffer` and use the native `Buffer` APIs directly. For existing projects, consider removing `safe-buffer` if dropping support for Node.js versions below 6.0.0.
• gotcha A critical 'footgun' exists where `safe-buffer` still permits `Buffer(size)` (calling `Buffer` as a function without `new`) which, in Node.js versions prior to 8.0.0, allocates uninitialized memory. Moreover, it can silence linting tools that would otherwise warn about the deprecated `Buffer()` call, giving a false sense of security.
  Fix: Strictly avoid `new Buffer(size)` and `Buffer(size)` in all code, even when using `safe-buffer`. Always explicitly use `Buffer.alloc(size)` for safe zero-filled buffers or `Buffer.allocUnsafe(size)` when raw uninitialized memory is intentionally handled.

Install

• npm install safe-buffer npm
• yarn add safe-buffer yarn
• pnpm add safe-buffer pnpm

Imports

• Buffer

  import { Buffer } from 'safe-buffer';

  Imports the named Buffer class for ESM environments.
• Buffer
  wrong:

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

  correct:

  const Buffer = require('safe-buffer').Buffer;

  CommonJS pattern to access the Buffer class exported as a property. While destructuring `const { Buffer } = require('safe-buffer');` technically works, the explicit property access `require('safe-buffer').Buffer` is shown in the README and often preferred for clarity.
• Buffer
  wrong:

  import SafeBuffer from 'safe-buffer';

  correct:

  import { Buffer } from 'safe-buffer';

  The module does not provide a default export that represents the Buffer class directly; Buffer is a named export.

Quickstart

Demonstrates `safe-buffer`'s core functionality, including safe and unsafe buffer allocation methods (`Buffer.alloc`, `Buffer.allocUnsafe`), and creating buffers from strings or arrays using `Buffer.from`, contrasting them with the deprecated `new Buffer()`.

const Buffer = require('safe-buffer').Buffer;

console.log("Using safe-buffer for Buffer operations:\n");

// The old, potentially unsafe way: new Buffer(size) or Buffer(size)
// While safe-buffer provides compatibility, this can create uninitialized buffers
// in older Node.js versions and is deprecated.
console.log('Old (deprecated) uninitialized buffer via new Buffer(10):');
try {
  const oldBuffer = new Buffer(10);
  console.log(oldBuffer); // Might show garbage data in older Node.js
} catch (e) {
  console.log('  Caught error for new Buffer(10):', e.message);
}

// Modern, safe way: zero-filled buffer (recommended for new allocations)
console.log('\nSafe zero-filled buffer via Buffer.alloc(10):');
const safeBuffer = Buffer.alloc(10);
console.log(safeBuffer);

// Modern way: uninitialized buffer (faster, use if you immediately overwrite contents)
// Be cautious: this memory may contain sensitive data if not fully overwritten.
console.log('\nPotentially unsafe uninitialized buffer via Buffer.allocUnsafe(10):');
const unsafeAllocBuffer = Buffer.allocUnsafe(10);
console.log(unsafeAllocBuffer); // Contents are unpredictable

// Creating a buffer from a string
console.log('\nBuffer from string via Buffer.from("Hello, safe-buffer!"):');
const stringBuffer = Buffer.from('Hello, safe-buffer!', 'utf8');
console.log(stringBuffer.toString('utf8'));

// Creating a buffer from an array of octets
console.log('\nBuffer from array via Buffer.from([0x68, 0x65, 0x6C, 0x6C, 0x6F]):');
const arrayBuffer = Buffer.from([0x68, 0x65, 0x6C, 0x6C, 0x6F]);
console.log(arrayBuffer.toString('utf8'));

// Copying an existing buffer
console.log('\nCopying an existing buffer:');
const originalBuf = Buffer.from('original');
const copiedBuf = Buffer.from(originalBuf); // Creates a new buffer with copied data
originalBuf[0] = 0x58; // Modify the original buffer
console.log('  Original after change:', originalBuf.toString());
console.log('  Copied buffer (should remain "original"):', copiedBuf.toString());