Enforce bytes type

dingosky · dingosky · commit f3088c3dd249 · 2017-07-19T21:21:01.000-07:00
Must be either Uint8Array or Buffer
diff --git a/README.md b/README.md
@@ -198,24 +198,24 @@ We'll start with using 32 characters. What 32 characters, you ask? Well, the [Ch
 
 We're using the same __bits__ calculation since we haven't changed the number of IDs or the accepted risk of probabilistic uniqueness. But this time we use 32 characters and our resulting ID only requires 10 characters (and can carry 50 bits of entropy).
 
-Now let's suppose we need to ensure the names of a handful of items are unique.  Let's say 30 items. And let's decide we can live with a 1 in 100,000 probability of collision (we're just futzing with some code ideas). Using hex characters:
+Now let's suppose we need to ensure the names of a handful of items are unique.  Let's say 30 items. And let's decide we can live with a 1 in 100,000 probability of collision (we're just futzing with some coding ideas). Using hex characters:
 
   ```js
   bits = entropy.bits(30, 100000)
-  string = entropy.randomString(bits, entropy.charSet16)
+  string = entropy.randomString(bits, entropy.charSet16, false)
   ```
 
   > String: dbf40a6
 
 Using 4 characters:
 
   ```js
-  string = entropy.randomString(bits, entropy.charSet4)
+  string = entropy.randomString(bits, entropy.charSet4, false)
   ```
 
   > String: CGCCGTAGGATAT
 
-Okay, we probably wouldn't use 4 characters (and what's up with those characters?), but you get the idea.
+Okay, we probably wouldn't use 4 characters (and what's up with those characters?), but you get the idea. The [Efficiency](#Efficiency) explains the 3rd argument of `false`.
 
 Suppose we have a more extreme need. We want less than a 1 in a trillion chance that 10 billion base 32 strings repeat. Let's see, our risk (trillion) is 10 to the 12th and our total (10 billion) is 10 to the 10th, so:
 
@@ -363,7 +363,7 @@ Compare that to the `entropy-string` scheme. For the example above, slicing off
 
 But there is an even bigger issue with the above code from a security perspective. `Math.random` *is not a crytographically strong random number generator*. **_Do not_** use `Math.random` to create secure IDs! This highlights an important point. Strings are only capable of carrying information (entropy); it's the random bytes that actually provide the entropy itself. `entropy-string` automatically generates the necessary number of bytes needed to create a random string using the `crypto` library.
 
-However, if you don't need cryptographically strong random strings, you can request `entropy-string` use `Math.random` rather than the `crypto` library to generate randomness:
+However, if you don't need cryptographically strong random strings, you can request `entropy-string` use `Math.random` rather than the `crypto` library by passing in a 3rd argument of `false`:
 
   ```js
   const entropy = require('entropy-string')
@@ -372,32 +372,32 @@ However, if you don't need cryptographically strong random strings, you can requ
   
   > PQ9dmqJ7g6
   
-When using `Math.random`, the `entropy-string` scheme uses 48 of the 52(ish) bits of randomness from each call to `Math.random`. That's more efficient than the above code snippet but less so than using `crypto` bytes.
+When using `Math.random`, the `entropy-string` scheme uses 48 of the 52(ish) bits of randomness from each call to `Math.random`. That's more efficient than the above code snippet but less so than using bytes from `crypto`.
 
 Fortunately you don't need to really understand how the bytes are efficiently sliced and diced to get the string. But you may want to provide your own [Custom Bytes](#CustomBytes) to create a string, which is the next topic.
 
 [TOC](#TOC)
 
 ## <a name="CustomBytes"></a>Custom Bytes
 
-As described in [Efficiency](#Efficiency), `entropy-string` automatically generates random bytes using the `crypto` library. But you may have a need to provide your own bytes, say for deterministic testing or to use a specialized byte genterator. The `entropy.randomStringWithBytes` function allows passing in your own bytes to create a string.
+As described in [Efficiency](#Efficiency), `entropy-string` automatically generates random bytes using the `crypto` library. But you may have a need to provide your own bytes, say for deterministic testing or to use a specialized byte generator. The `entropy.randomString` function allows passing in your own bytes to create a string.
 
 Suppose we want a string capable of 30 bits of entropy using 32 characters. We pass in 4 bytes (to cover the 30 bits):
 
   ```js
   const entropy = require('entropy-string')
 
-  let bytes: RandomString.Bytes = [250, 200, 150, 100]
-  let string = entropy.randomStringWithBytes(30, entropy.charSet32, bytes)
+  let bytes: RandomString.Bytes = new Uint8Array[250, 200, 150, 100]
+  let string = entropy.randomString(30, entropy.charSet32, bytes)
   ```
 
   > string: Th7fjL
  
-The __bytes__ provided can come from any source. However, the number of bytes must be sufficient to generate the string as described in the [Efficiency](#Efficiency) section.  `entropy.randomStringWithBytes` throws an `Error` if the string cannot be formed from the passed bytes.
+The __bytes__ provided can come from any source. However, the number of bytes must be sufficient to generate the string as described in the [Efficiency](#Efficiency) section.  `entropy.randomString` throws an `Error` if the string cannot be formed from the passed bytes.
 
   ```js
   try {
-    string = entropy.randomStringWithBytes(32, entropy.charSet32, bytes)
+    string = entropy.randomString(32, entropy.charSet32, bytes)
   }
   catch(error) {
     console.log(error.message)
diff --git a/dist/lib/entropy.js b/dist/lib/entropy.js
@@ -75,9 +75,13 @@ var bitsWithPowers = function bitsWithPowers(tPower, rPower) {
 };
 
 var randomString = function randomString(entropy, charSet) {
-  var crypto = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
+  var opt = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
 
-  var bytes = crypto ? _cryptoBytes(entropy, charSet) : _randomBytes(entropy, charSet);
+  if (!(opt === null || opt instanceof Uint8Array || typeof opt == 'boolean')) {
+    throw new Error('Optional 3rd argument must be either an Uint8Array or a boolean');
+  }
+
+  var bytes = opt instanceof Uint8Array ? opt : opt === false ? _randomBytes(entropy, charSet) : _cryptoBytes(entropy, charSet);
   return randomStringWithBytes(entropy, charSet, bytes);
 };
 
diff --git a/lib/entropy.js b/lib/entropy.js
@@ -52,8 +52,12 @@ const bitsWithPowers = (tPower, rPower) => {
   return N
 }
 
-const randomString = (entropy, charSet, opt) => {
-  let bytes = (opt instanceof Array) ? opt :
+const randomString = (entropy, charSet, opt = null) => {
+  if ( !( (opt === null) || (opt instanceof Uint8Array) || (typeof opt == 'boolean') ) ) {
+    throw new Error('Optional 3rd argument must be either an Uint8Array or a boolean')
+  }
+  
+  let bytes = (opt instanceof Uint8Array) ? opt :
       (opt === false) ? _randomBytes(entropy, charSet) : _cryptoBytes(entropy, charSet)
   return randomStringWithBytes(entropy, charSet, bytes)
 }
diff --git a/test/entropy.js b/test/entropy.js
@@ -453,7 +453,7 @@ test('Custom 64 chars', t => {
   let charSet = entropy.charSet64
   try {
     charSet.use('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ9876543210_-')
-    let bytes = [0x9d, 0x99, 0x4e, 0xa5, 0xd2, 0x3f, 0x8c, 0x86, 0x80]
+    let bytes = new Uint8Array([0x9d, 0x99, 0x4e, 0xa5, 0xd2, 0x3f, 0x8c, 0x86, 0x80])
     let string = entropy.randomString(72, charSet, bytes)
                                                
     t.is(string, 'NzLoPDi-JiAa')
@@ -471,7 +471,8 @@ test('Custom 32 chars', t => {
   let charSet = entropy.charSet32
   try {
     charSet.use('2346789BDFGHJMNPQRTbdfghjlmnpqrt')
-    let string = entropy.randomString(55, charSet, [0xd2, 0xe3, 0xe9, 0xda, 0x19, 0x97, 0x52])
+    let bytes = new Uint8Array([0xd2, 0xe3, 0xe9, 0xda, 0x19, 0x97, 0x52])
+    let string = entropy.randomString(55, charSet, bytes)
     t.is(string, 'mHRrbgQlTqF')
   }
   catch(error) {
@@ -487,7 +488,7 @@ test('Custom 16 chars', t => {
   let charSet = entropy.charSet16
   try {
     charSet.use('0123456789ABCDEF')
-    let string = entropy.randomString(20, charSet, [0xc7, 0xc9, 0x00])
+    let string = entropy.randomString(20, charSet, new Uint8Array([0xc7, 0xc9, 0x00]))
     t.is(string, 'C7C90')
   }
   catch(error) {
@@ -503,7 +504,7 @@ test('Custom 8 chars', t => {
   let charSet = entropy.charSet8
   try {
     charSet.use('abcdefgh')
-    let string = entropy.randomString(30, charSet, [0xc7, 0xc9, 0x07, 0xc9])
+    let string = entropy.randomString(30, charSet, new Uint8Array([0xc7, 0xc9, 0x07, 0xc9]))
     t.is(string, 'gbheeeahgc')
   }
   catch(error) {
@@ -519,7 +520,7 @@ test('Custom 4 chars', t => {
   let charSet = entropy.charSet4
   try {
     charSet.use('atcg')
-    let string = entropy.randomString(16, charSet, [0x20, 0xf1])
+    let string = entropy.randomString(16, charSet, new Uint8Array([0x20, 0xf1]))
     t.is(string, 'acaaggat')
   }
   catch(error) {
@@ -535,7 +536,7 @@ test('Custom 2 chars', t => {
   let charSet = entropy.charSet2
   try {
     charSet.use('HT')
-    let string = entropy.randomString(16, charSet, [0xe3, 0xe9])
+    let string = entropy.randomString(16, charSet, new Uint8Array([0xe3, 0xe9]))
     t.is(string, 'TTTHHHTTTTTHTHHT')
   }
   catch(error) {
@@ -575,7 +576,7 @@ test('No crypto', t => {
 
 const entropyString = (bits, charSet, arr) => {
   let bytes = Buffer.from(arr)
-  return entropy.randomStringWithBytes(bits, charSet, bytes)
+  return entropy.randomString(bits, charSet, bytes)
 }
 
 const entropyStringLength = (bits, charSet) => {

Original file line number	Diff line number	Diff line change
`@@ -52,8 +52,12 @@ const bitsWithPowers = (tPower, rPower) => {`
`52`	`52`	`return N`
`53`	`53`	`}`
`54`	`54`
`55`		`-const randomString = (entropy, charSet, opt) => {`
`56`		`- let bytes = (opt instanceof Array) ? opt :`
	`55`	`+const randomString = (entropy, charSet, opt = null) => {`
	`56`	`+ if ( !( (opt === null) \|\| (opt instanceof Uint8Array) \|\| (typeof opt == 'boolean') ) ) {`
	`57`	`+ throw new Error('Optional 3rd argument must be either an Uint8Array or a boolean')`
	`58`	`+ }`
	`59`	`+`
	`60`	`+ let bytes = (opt instanceof Uint8Array) ? opt :`
`57`	`61`	`(opt === false) ? _randomBytes(entropy, charSet) : _cryptoBytes(entropy, charSet)`
`58`	`62`	`return randomStringWithBytes(entropy, charSet, bytes)`
`59`	`63`	`}`