ahmad-module 1.0.0

package/safer-buffer/Readme.md

@@ -0,0 +1,156 @@
+# safer-buffer [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![javascript style guide][standard-image]][standard-url] [![Security Responsible Disclosure][secuirty-image]][secuirty-url]
+
+[travis-image]: https://travis-ci.org/ChALkeR/safer-buffer.svg?branch=master
+[travis-url]: https://travis-ci.org/ChALkeR/safer-buffer
+[npm-image]: https://img.shields.io/npm/v/safer-buffer.svg
+[npm-url]: https://npmjs.org/package/safer-buffer
+[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
+[standard-url]: https://standardjs.com
+[secuirty-image]: https://img.shields.io/badge/Security-Responsible%20Disclosure-green.svg
+[secuirty-url]: https://github.com/nodejs/security-wg/blob/master/processes/responsible_disclosure_template.md
+
+Modern Buffer API polyfill without footguns, working on Node.js from 0.8 to current.
+
+## How to use?
+
+First, port all `Buffer()` and `new Buffer()` calls to `Buffer.alloc()` and `Buffer.from()` API.
+
+Then, to achieve compatibility with outdated Node.js versions (`<4.5.0` and 5.x `<5.9.0`), use
+`const Buffer = require('safer-buffer').Buffer` in all files where you make calls to the new
+Buffer API. _Use `var` instead of `const` if you need that for your Node.js version range support._
+
+Also, see the
+[porting Buffer](https://github.com/ChALkeR/safer-buffer/blob/master/Porting-Buffer.md) 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 `Buffer.alloc()` and `Buffer.from()`
+though.
+
+See the [porting guide](https://github.com/ChALkeR/safer-buffer/blob/master/Porting-Buffer.md)
+for a better description.
+
+## Why not [safe-buffer](https://npmjs.com/safe-buffer)?
+
+_In short: while `safe-buffer` serves as a polyfill for the new API, it allows old API usage and
+itself contains footguns._
+
+`safe-buffer` could 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-buffer` is itself causing problems in some cases.
+
+For example, consider the following snippet:
+
+```console
+$ cat example.unsafe.js
+console.log(Buffer(20))
+$ ./node-v6.13.0-linux-x64/bin/node example.unsafe.js
+<Buffer 0a 00 00 00 00 00 00 00 28 13 de 02 00 00 00 00 05 00 00 00>
+$ standard example.unsafe.js
+standard: Use JavaScript Standard Style (https://standardjs.com)
+  /home/chalker/repo/safer-buffer/example.unsafe.js:2:13: 'Buffer()' was deprecated since v6. Use 'Buffer.alloc()' or 'Buffer.from()' (use 'https://www.npmjs.com/package/safe-buffer' for '<4.5.0') instead.
+```
+
+This is allocates and writes to console an uninitialized chunk of memory.
+[standard](https://www.npmjs.com/package/standard) linter (among others) catch that and warn people
+to avoid using unsafe API.
+
+Let's now throw in `safe-buffer`!
+
+```console
+$ 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-buffer` _magically 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-buffer` design. 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-buffer` without 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](https://github.com/webdriverio/webdriverio/commit/05cbd3167c12e4930f09ef7cf93b127ba4effae4#diff-124380949022817b90b622871837d56cR31)
+   (a module with 548 759 downloads/month),
+ * [websocket-stream](https://github.com/maxogden/websocket-stream/commit/c9312bd24d08271687d76da0fe3c83493871cf61)
+   (218 288 d/m, fix in [maxogden/websocket-stream#142](https://github.com/maxogden/websocket-stream/pull/142)),
+ * [node-serialport](https://github.com/node-serialport/node-serialport/commit/e8d9d2b16c664224920ce1c895199b1ce2def48c)
+   (113 138 d/m, fix in [node-serialport/node-serialport#1510](https://github.com/node-serialport/node-serialport/pull/1510)),
+ * [karma](https://github.com/karma-runner/karma/commit/3d94b8cf18c695104ca195334dc75ff054c74eec)
+   (3 973 193 d/m, fix in [karma-runner/karma#2947](https://github.com/karma-runner/karma/pull/2947)),
+ * [spdy-transport](https://github.com/spdy-http2/spdy-transport/commit/5375ac33f4a62a4f65bcfc2827447d42a5dbe8b1)
+   (5 970 727 d/m, fix in [spdy-http2/spdy-transport#53](https://github.com/spdy-http2/spdy-transport/pull/53)).
+ * And there are a lot more over the ecosystem.
+
+I filed a PR at
+[mysticatea/eslint-plugin-node#110](https://github.com/mysticatea/eslint-plugin-node/pull/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)._
+
+Also, `safer-buffer` discourages the usage of `.allocUnsafe()`, which is often done by a mistake.
+It still supports it with an explicit concern barier, by placing it under
+`require('safer-buffer/dangereous')`.
+
+## 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').Buffer` was 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 `Buffer` and use
+`var SaferBuffer = require('safer-buffer').Buffer` instead.
+
+That way, everything using `Buffer` natively would still work, but there would be two drawbacks:
+
+* `Buffer.from`/`Buffer.alloc` won't be polyfilled — use `SaferBuffer.from` and
+  `SaferBuffer.alloc` instead.
+* 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 `Buffer` constructor usage in this case is strongly
+recommended. `Buffer` is not overriden in this usecase, so linters won't get confused.
+
+## «Without footguns»?
+
+Well, it is still possible to do _some_ things with `Buffer` API, e.g. accessing `.buffer` property
+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](https://github.com/nodejs/release#release-schedule).

package/safer-buffer/dangerous.js

@@ -0,0 +1,58 @@
+/* eslint-disable node/no-deprecated-api */
+
+'use strict'
+
+var buffer = require('buffer')
+var Buffer = buffer.Buffer
+var safer = require('./safer.js')
+var Safer = safer.Buffer
+
+var dangerous = {}
+
+var key
+
+for (key in safer) {
+  if (!safer.hasOwnProperty(key)) continue
+  dangerous[key] = safer[key]
+}
+
+var Dangereous = dangerous.Buffer = {}
+
+// Copy Safer API
+for (key in Safer) {
+  if (!Safer.hasOwnProperty(key)) continue
+  Dangereous[key] = Safer[key]
+}
+
+// Copy those missing unsafe methods, if they are present
+for (key in Buffer) {
+  if (!Buffer.hasOwnProperty(key)) continue
+  if (Dangereous.hasOwnProperty(key)) continue
+  Dangereous[key] = Buffer[key]
+}
+
+if (!Dangereous.allocUnsafe) {
+  Dangereous.allocUnsafe = function (size) {
+    if (typeof size !== 'number') {
+      throw new TypeError('The "size" argument must be of type number. Received type ' + typeof size)
+    }
+    if (size < 0 || size >= 2 * (1 << 30)) {
+      throw new RangeError('The value "' + size + '" is invalid for option "size"')
+    }
+    return Buffer(size)
+  }
+}
+
+if (!Dangereous.allocUnsafeSlow) {
+  Dangereous.allocUnsafeSlow = function (size) {
+    if (typeof size !== 'number') {
+      throw new TypeError('The "size" argument must be of type number. Received type ' + typeof size)
+    }
+    if (size < 0 || size >= 2 * (1 << 30)) {
+      throw new RangeError('The value "' + size + '" is invalid for option "size"')
+    }
+    return buffer.SlowBuffer(size)
+  }
+}
+
+module.exports = dangerous

package/safer-buffer/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "safer-buffer",
+  "version": "2.1.2",
+  "description": "Modern Buffer API polyfill without footguns",
+  "main": "safer.js",
+  "scripts": {
+    "browserify-test": "browserify --external tape tests.js > browserify-tests.js && tape browserify-tests.js",
+    "test": "standard && tape tests.js"
+  },
+  "author": {
+    "name": "Nikita Skovoroda",
+    "email": "chalkerx@gmail.com",
+    "url": "https://github.com/ChALkeR"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChALkeR/safer-buffer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChALkeR/safer-buffer/issues"
+  },
+  "devDependencies": {
+    "standard": "^11.0.1",
+    "tape": "^4.9.0"
+  },
+  "files": [
+    "Porting-Buffer.md",
+    "Readme.md",
+    "tests.js",
+    "dangerous.js",
+    "safer.js"
+  ]
+}

package/safer-buffer/safer.js

@@ -0,0 +1,77 @@
+/* eslint-disable node/no-deprecated-api */
+
+'use strict'
+
+var buffer = require('buffer')
+var Buffer = buffer.Buffer
+
+var safer = {}
+
+var key
+
+for (key in buffer) {
+  if (!buffer.hasOwnProperty(key)) continue
+  if (key === 'SlowBuffer' || key === 'Buffer') continue
+  safer[key] = buffer[key]
+}
+
+var Safer = safer.Buffer = {}
+for (key in Buffer) {
+  if (!Buffer.hasOwnProperty(key)) continue
+  if (key === 'allocUnsafe' || key === 'allocUnsafeSlow') continue
+  Safer[key] = Buffer[key]
+}
+
+safer.Buffer.prototype = Buffer.prototype
+
+if (!Safer.from || Safer.from === Uint8Array.from) {
+  Safer.from = function (value, encodingOrOffset, length) {
+    if (typeof value === 'number') {
+      throw new TypeError('The "value" argument must not be of type number. Received type ' + typeof value)
+    }
+    if (value && typeof value.length === 'undefined') {
+      throw new TypeError('The first argument must be one of type string, Buffer, ArrayBuffer, Array, or Array-like Object. Received type ' + typeof value)
+    }
+    return Buffer(value, encodingOrOffset, length)
+  }
+}
+
+if (!Safer.alloc) {
+  Safer.alloc = function (size, fill, encoding) {
+    if (typeof size !== 'number') {
+      throw new TypeError('The "size" argument must be of type number. Received type ' + typeof size)
+    }
+    if (size < 0 || size >= 2 * (1 << 30)) {
+      throw new RangeError('The value "' + size + '" is invalid for option "size"')
+    }
+    var buf = Buffer(size)
+    if (!fill || fill.length === 0) {
+      buf.fill(0)
+    } else if (typeof encoding === 'string') {
+      buf.fill(fill, encoding)
+    } else {
+      buf.fill(fill)
+    }
+    return buf
+  }
+}
+
+if (!safer.kStringMaxLength) {
+  try {
+    safer.kStringMaxLength = process.binding('buffer').kStringMaxLength
+  } catch (e) {
+    // we can't determine kStringMaxLength in environments where process.binding
+    // is unsupported, so let's not set it
+  }
+}
+
+if (!safer.constants) {
+  safer.constants = {
+    MAX_LENGTH: safer.kMaxLength
+  }
+  if (safer.kStringMaxLength) {
+    safer.constants.MAX_STRING_LENGTH = safer.kStringMaxLength
+  }
+}
+
+module.exports = safer