Merge pull request #1 from markstos/add-sync-api

Add support for sync API. Updates, code test and docs

README.md

@@ -1,33 +1,56 @@
 # secure-random-string
-a node module that generates a secure random string with a given length
+
+Node.js module that generates a cryptographically secure random string with a given length
 
 ## Usage
-`require` it
 
-```
+```javascript
 var srs = require('secure-random-string');
 ```
 
+### Default behavior: Generate a random string 32 characters long.
 
-generate a random string that is 32 chars long (the default)
+```javascript
-```
+// Sync
+var result = srs();
+
+// Async
 srs(function(sr) {
 	console.log(sr);
 });
+
 ```
 
+### Options: length, urlsafe
 
-generate a random string that is 256 chars long
+Optionally, you can specify a 'length' option to specify a length.
-```
+
-srs({length: 256}, function(sr) {
+The 'urlsafe' option replaces a potential `+` character with `-` and the `/` character
+with `_`, created a valid [base64url](https://en.wikipedia.org/wiki/Base64) format string.
+
+```javascript
+// sync
+var result = srs({length: 256, urlsafe:true});
+
+// async
+srs({length: 256, urlsafe:true}, function(sr) {
 	console.log(sr);
 });
 ```
 
+## Error handling
+
+Will throw error if there is not enough accumulated entropy to generate cryptographically strong data. In other words, this without callback will not block even if all entropy sources are drained.
+
+## Author
+
+ [Simon Santoro](https://github.com/S2-)
+
+## Contributors
+
+ [Mark Stosberg](https://github.com/markstos)
+
+## License
+
+[MIT](https://github.com/aheckmann/node-ses/blob/master/LICENSE)
 
-generate a random string that is 20 chars long and is url safe (can be used as a url token)
-```
-srs({length: 20, urlsafe: true}, function(sr) {
-	console.log(sr);
-});
-```

lib/secure-random-string.js

@@ -9,18 +9,28 @@ function srs(options, cb) {
 	}
 	var length = options['length'] || 32;
 
-	crypto.randomBytes(length, function(ex, buf) {
+  // async path
-		if (ex) throw ex;
+  if (cb) {
+    crypto.randomBytes(length, function(ex, buf) {
+      if (ex) throw ex;
+      return cb(_finish(buf));
+    });
+  }
+  // sync path
+  else {
+    return _finish(crypto.randomBytes(length));
+  }
 
+  function _finish (buf) {
 		var string = buf.toString('base64');
 		if (options.urlsafe) {
 			string = string.replace(/\//g,'_').replace(/\+/g,'-');
 		}
-
+    return string.substr(0, length);
-		cb(string.substr(0, length));
+  }
-	});
 
 };
 
 
+
 module.exports = srs;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "secure-random-string",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Generates a secure random string with a given length",
   "main": "lib/secure-random-string.js",
   "scripts": {
@@ -16,6 +16,7 @@
     "string"
   ],
   "author": "Simon Santoro",
+  "contributors": ["Mark Stosberg <mark@rideamigos.com>"],
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/S2-/securerandomstring/issues"

tests.js

@@ -28,7 +28,7 @@ var test = function(name, what, ref, c) {
 
 
 
-//the actual tests
+// async tests
 srs(function(sr) {
 	test('generate a random string 32 chars long',
 		sr.length,
@@ -58,3 +58,8 @@ srs({length: 256, urlsafe: true}, function(sr) {
 });
 
 
+// sync tests
+test('generate a random string 32 chars long (sync)', srs().length, 32);
+test('generate a random string 1 chars long (sync)', srs({length:1}).length, 1);
+test('generate a random string 256 chars long (sync)', srs({length:256}).length, 256);
+test('generate a urlsafe random string 256 chars long (sync)', srs({length:256, urlsafe:true}).length, 256);