How to use?First, port all
new Buffer()calls to
Then, to achieve compatibility with outdated Node.js versions (
const Buffer = require('safer-buffer').Bufferin all files where you make calls to the new Buffer API. Use
constif you need that for your Node.js version range support.
Also, see the porting Buffer guide.
Do I need it?Hopefully, not — dropping support for outdated Node.js versions should be fine nowdays, and that is the recommended path forward. You do need to port to the
See the porting guide for a better description.
Why not safe-buffer?In short: while
safe-bufferserves as a polyfill for the new API, it allows old API usage and itself contains footguns.
safe-buffercould be used safely to get the new API while still keeping support for older Node.js versions (like this module), but while analyzing ecosystem usage of the old Buffer API I found out that
safe-bufferis itself causing problems in some cases.
For example, consider the following snippet:
This is allocates and writes to console an uninitialized chunk of memory. standard linter (among others) catch that and warn people to avoid using unsafe API.
Let's now throw in
$ cat example.safe-buffer.js const Buffer = require('safe-buffer').Buffer console.log(Buffer(20)) $ standard example.safe-buffer.js $ ./node-v6.13.0-linux-x64/bin/node example.safe-buffer.js <Buffer 08 00 00 00 00 00 00 00 28 58 01 82 fe 7f 00 00 00 00 00 00>
See the problem? Adding in
safe-buffermagically removes the lint warning, but the behavior remains identiсal to what we had before, and when launched on Node.js 6.x LTS — this dumps out chunks of uninitialized memory. And this code will still emit runtime warnings on Node.js 10.x and above.
That was done by design. I first considered changing
safe-buffer, prohibiting old API usage or emitting warnings on it, but that significantly diverges from
safe-bufferdesign. After some discussion, it was decided to move my approach into a separate package, and this is that separate package.
This footgun is not imaginary — I observed top-downloaded packages doing that kind of thing, «fixing» the lint warning by blindly including
safe-bufferwithout any actual changes.
Also in some cases, even if the API was migrated to use of safe Buffer API — a random pull request can bring unsafe Buffer API usage back to the codebase by adding new calls — and that could go unnoticed even if you have a linter prohibiting that (becase of the reason stated above), and even pass CI. I also observed that being done in popular packages.
Some examples: webdriverio
(a module with 548 759 downloads/month),
(218 288 d/m, fix in [maxogden/websocket-stream#142](https://github.com/maxogden/websocket-stream/pull/142)),
(113 138 d/m, fix in [node-serialport/node-serialport#1510](https://github.com/node-serialport/node-serialport/pull/1510)),
(3 973 193 d/m, fix in [karma-runner/karma#2947](https://github.com/karma-runner/karma/pull/2947)),
And there are a lot more over the ecosystem.
(5 970 727 d/m, fix in [spdy-http2/spdy-transport#53](https://github.com/spdy-http2/spdy-transport/pull/53)).
I filed a PR at mysticatea/eslint-plugin-node#110 to partially fix that (for cases when that lint rule is used), but it is a semver-major change for linter rules and presets, so it would take significant time for that to reach actual setups. It also hasn't been released yet (2018-03-20).
safer-bufferdiscourages the usage of
.allocUnsafe(), which is often done by a mistake. It still supports it with an explicit concern barier, by placing it under
But isn't throwing bad?Not really. It's an error that could be noticed and fixed early, instead of causing havoc later like unguarded
new Buffer()calls that end up receiving user input can do.
This package affects only the files where
var Buffer = require('safer-buffer').Bufferwas done, so it is really simple to keep track of things and make sure that you don't mix old API usage with that. Also, CI should hint anything that you might have missed.
New commits, if tested, won't land new usage of unsafe Buffer API this way. Node.js 10.x also deals with that by printing a runtime depecation warning.
Would it affect third-party modules?No, unless you explicitly do an awful thing like monkey-patching or overriding the built-in
Buffer. Don't do that.
But I don't want throwing…That is also fine!
Also, it could be better in some cases when you don't comprehensive enough test coverage.
In that case — just don't override
var SaferBuffer = require('safer-buffer').Bufferinstead.
That way, everything using
Buffernatively would still work, but there would be two drawbacks:
Buffer.allocwon't be polyfilled — use
- You are still open to accidentally using the insecure deprecated API — use a linter to catch that.
Note that using a linter to catch accidential
Bufferconstructor usage in this case is strongly recommended.
Bufferis not overriden in this usecase, so linters won't get confused.
«Without footguns»?Well, it is still possible to do some things with
BufferAPI, e.g. accessing
.bufferproperty on older versions and duping things from there. You shouldn't do that in your code, probabably.
The intention is to remove the most significant footguns that affect lots of packages in the ecosystem, and to do it in the proper way.
Also, this package doesn't protect against security issues affecting some Node.js versions, so for usage in your own production code, it is still recommended to update to a Node.js version supported by upstream.