Add auth.parse for low-level string parsing

closes #21

Author: dougwilson

HISTORY.md

@@ -1,3 +1,8 @@
+unreleased
+==========
+
+  * Add `auth.parse` for low-level string parsing
+
 1.0.4 / 2016-05-10
 ==================
 

LICENSE

@@ -2,7 +2,7 @@
 
 Copyright (c) 2013 TJ Holowaychuk
 Copyright (c) 2014 Jonathan Ong <[email protected]>
-Copyright (c) 2015 Douglas Christopher Wilson <[email protected]>
+Copyright (c) 2015-2016 Douglas Christopher Wilson <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -30,6 +30,11 @@ Get the basic auth credentials from the given request. The `Authorization`
 header is parsed and if the header is invalid, `undefined` is returned,
 otherwise an object with `name` and `pass` properties.
 
+### auth.parse(string)
+
+Parse a basic auth authorization header string. This will return an object
+with `name` and `pass` properties, or `undefined` if the string is invalid.
+
 ## Example
 
 Pass a node request or koa Context object to the module exported. If
@@ -40,7 +45,14 @@ parsing fails `undefined` is returned, otherwise an object with
 var auth = require('basic-auth');
 var user = auth(req);
 // => { name: 'something', pass: 'whatever' }
+```
 
+A header string from any other location can also be parsed with
+`auth.parse`, for example a `Proxy-Authorization` header:
+
+```js
+var auth = require('basic-auth')
+var user = auth.parse(req.getHeader('Proxy-Authorization'))
 ```
 
 ### With vanilla node.js http server

index.js

@@ -2,7 +2,7 @@
  * basic-auth
  * Copyright(c) 2013 TJ Holowaychuk
  * Copyright(c) 2014 Jonathan Ong
- * Copyright(c) 2015 Douglas Christopher Wilson
+ * Copyright(c) 2015-2016 Douglas Christopher Wilson
  * MIT Licensed
  */
 
@@ -14,6 +14,7 @@
  */
 
 module.exports = auth
+module.exports.parse = parse
 
 /**
  * RegExp for basic auth credentials
@@ -58,21 +59,7 @@ function auth (req) {
   var header = getAuthorization(req.req || req)
 
   // parse header
-  var match = CREDENTIALS_REGEXP.exec(header || '')
-
-  if (!match) {
-    return
-  }
-
-  // decode user pass
-  var userPass = USER_PASS_REGEXP.exec(decodeBase64(match[1]))
-
-  if (!userPass) {
-    return
-  }
-
-  // return credentials object
-  return new Credentials(userPass[1], userPass[2])
+  return parse(header)
 }
 
 /**
@@ -97,6 +84,37 @@ function getAuthorization (req) {
   return req.headers.authorization
 }
 
+/**
+ * Parse basic auth to object.
+ *
+ * @param {string} string
+ * @return {object}
+ * @public
+ */
+
+function parse (string) {
+  if (typeof string !== 'string') {
+    return undefined
+  }
+
+  // parse header
+  var match = CREDENTIALS_REGEXP.exec(string)
+
+  if (!match) {
+    return undefined
+  }
+
+  // decode user pass
+  var userPass = USER_PASS_REGEXP.exec(decodeBase64(match[1]))
+
+  if (!userPass) {
+    return undefined
+  }
+
+  // return credentials object
+  return new Credentials(userPass[1], userPass[2])
+}
+
 /**
  * Object to represent user credentials.
  * @private

test/basic-auth.js

@@ -117,3 +117,69 @@ describe('auth(req)', function () {
     })
   })
 })
+
+describe('auth.parse(string)', function () {
+  describe('with undefined string', function () {
+    it('should return undefined', function () {
+      assert.strictEqual(auth.parse(), undefined)
+    })
+  })
+
+  describe('with malformed string', function () {
+    it('should return undefined', function () {
+      assert.strictEqual(auth.parse('Something'), undefined)
+    })
+  })
+
+  describe('with malformed scheme', function () {
+    it('should return undefined', function () {
+      assert.strictEqual(auth.parse('basic_Zm9vOmJhcg=='), undefined)
+    })
+  })
+
+  describe('with malformed credentials', function () {
+    it('should return undefined', function () {
+      assert.strictEqual(auth.parse('basic Zm9vcgo='), undefined)
+    })
+  })
+
+  describe('with valid credentials', function () {
+    it('should return .name and .pass', function () {
+      var creds = auth.parse('basic Zm9vOmJhcg==')
+      assert.equal(creds.name, 'foo')
+      assert.equal(creds.pass, 'bar')
+    })
+  })
+
+  describe('with empty password', function () {
+    it('should return .name and .pass', function () {
+      var creds = auth.parse('basic Zm9vOg==')
+      assert.equal(creds.name, 'foo')
+      assert.equal(creds.pass, '')
+    })
+  })
+
+  describe('with empty userid', function () {
+    it('should return .name and .pass', function () {
+      var creds = auth.parse('basic OnBhc3M=')
+      assert.equal(creds.name, '')
+      assert.equal(creds.pass, 'pass')
+    })
+  })
+
+  describe('with empty userid and pass', function () {
+    it('should return .name and .pass', function () {
+      var creds = auth.parse('basic Og==')
+      assert.equal(creds.name, '')
+      assert.equal(creds.pass, '')
+    })
+  })
+
+  describe('with colon in pass', function () {
+    it('should return .name and .pass', function () {
+      var creds = auth.parse('basic Zm9vOnBhc3M6d29yZA==')
+      assert.equal(creds.name, 'foo')
+      assert.equal(creds.pass, 'pass:word')
+    })
+  })
+})