@ryniaubenpm2/alias-nihil-veniam

Parse, build and deal with HTTP authorization headers.

This library provide several utilities to parse and build WWW-Authenticate and Authorization headers as described per the HTTP RFC.

It is intended to be framework agnostic and could be used either on the server and the client side. It is also pure functions only, no side effect here. The functions are synchronous since only parsing headers of small size so no need for streams or anything asynchronous.

The module is easily extensible with new mechanisms, one very common way to extend it is to create a FAKE_TOKEN mechanism for development only that allows to directly provide the userId that should be authenticated. You can find an sample implementation in the Whook's framework repository.

API

Modules

@ryniaubenpm2/alias-nihil-veniam

@ryniaubenpm2/alias-nihil-veniam/mechanisms/basic

@ryniaubenpm2/alias-nihil-veniam/mechanisms/bearer

@ryniaubenpm2/alias-nihil-veniam/mechanisms/digest

@ryniaubenpm2/alias-nihil-veniam

• @ryniaubenpm2/alias-nihil-veniam
  • static
    • .parseWWWAuthenticateHeader(header, [authMechanisms], [options]) ⇒ Object
    • .parseAuthorizationHeader(header, [authMechanisms], [options]) ⇒ Object
    • .buildWWWAuthenticateHeader(authMechanism, The) ⇒ string
    • .buildAuthorizationHeader(authMechanism, The) ⇒ string
  • inner
    • ~mechanisms : Array

@ryniaubenpm2/alias-nihil-veniam.parseWWWAuthenticateHeader(header, [authMechanisms], [options]) ⇒ Object

Parse HTTP WWW-Authenticate header contents.

Kind: static method of @ryniaubenpm2/alias-nihil-veniam
Returns: Object - Result of the contents parse.
Api: public

Param	Type	Default	Description
header	string		The WWW-Authenticate header contents
[authMechanisms]	Array	[BASIC, DIGEST, BEARER]	Allow providing custom authentication mechanisms.
[options]	Object		Parsing options
[options.strict]	boolean	true	Strictly detect the mechanism type (case sensitive)

Example

1assert.deepEqual(
2  parseWWWAuthenticateHeader('Basic realm="test"'), {
3    type: 'Basic',
4    data: {
5      realm: 'test'
6    }
7  }
8);

@ryniaubenpm2/alias-nihil-veniam.parseAuthorizationHeader(header, [authMechanisms], [options]) ⇒ Object

Parse HTTP Authorization header contents.

Kind: static method of @ryniaubenpm2/alias-nihil-veniam
Returns: Object - Result of the contents parse.
Api: public

Param	Type	Default	Description
header	string		The Authorization header contents
[authMechanisms]	Array	[BASIC, DIGEST, BEARER]	Allow custom authentication mechanisms.
[options]	Object		Parsing options
[options.strict]	boolean	true	Strictly detect the mechanism type (case sensitive)

Example

1assert.deepEqual(
2  parseAuthorizationHeader('Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='), {
3    type: 'Basic',
4    data: {
5      hash: 'QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
6    }
7  }
8);

@ryniaubenpm2/alias-nihil-veniam.buildWWWAuthenticateHeader(authMechanism, The) ⇒ string

Build HTTP WWW-Authenticate header value.

Kind: static method of @ryniaubenpm2/alias-nihil-veniam
Returns: string - The header value.
Api: public

Param	Type	Description
authMechanism	Object	The mechanism to use
The	Object	WWW-Authenticate header contents to base the value on.

Example

1assert.deepEqual(
2  buildWWWAuthenticateHeader(BASIC, {
3    realm: 'test'
4  }),
5  'Basic realm="test"'
6);

@ryniaubenpm2/alias-nihil-veniam.buildAuthorizationHeader(authMechanism, The) ⇒ string

Build HTTP Authorization header value.

Kind: static method of @ryniaubenpm2/alias-nihil-veniam
Returns: string - The header value.
Api: public

Param	Type	Description
authMechanism	Object	The mechanism to use
The	Object	Authorization header contents to base the value on.

Example

1assert.deepEqual(
2  buildAuthorizationHeader(BASIC, {
3    realm: 'test'
4  }),
5  'Basic realm="test"'
6);

@ryniaubenpm2/alias-nihil-veniam~mechanisms : Array

Natively supported authentication mechanisms.

Kind: inner constant of @ryniaubenpm2/alias-nihil-veniam

@ryniaubenpm2/alias-nihil-veniam/mechanisms/basic

• @ryniaubenpm2/alias-nihil-veniam/mechanisms/basic
  • ~BASIC : Object
    • .type : String
    • .parseWWWAuthenticateRest(rest) ⇒ Object
    • .buildWWWAuthenticateRest(data) ⇒ String
    • .parseAuthorizationRest(rest) ⇒ Object
    • .buildAuthorizationRest(content) ⇒ String
    • .computeHash(credentials) ⇒ String
    • .decodeHash(hash) ⇒ Object

@ryniaubenpm2/alias-nihil-veniam/mechanisms/basic~BASIC : Object

Basic authentication mechanism.

Kind: inner constant of @ryniaubenpm2/alias-nihil-veniam/mechanisms/basic
See: http://tools.ietf.org/html/rfc2617#section-2

• ~BASIC : Object
  • .type : String
  • .parseWWWAuthenticateRest(rest) ⇒ Object
  • .buildWWWAuthenticateRest(data) ⇒ String
  • .parseAuthorizationRest(rest) ⇒ Object
  • .buildAuthorizationRest(content) ⇒ String
  • .computeHash(credentials) ⇒ String
  • .decodeHash(hash) ⇒ Object

BASIC.type : String

The Basic auth mechanism prefix.

Kind: static property of BASIC

BASIC.parseWWWAuthenticateRest(rest) ⇒ Object

Parse the WWW Authenticate header rest.

Kind: static method of BASIC
Returns: Object - Object representing the result of the parse operation.
Api: public

Param	Type	Description
rest	String	The header rest (string after the authentication mechanism prefix).

Example

1assert.deepEqual(
2  BASIC.parseWWWAuthenticateRest('realm="perlinpinpin"'), {
3    realm: 'perlinpinpin'
4  }
5);

BASIC.buildWWWAuthenticateRest(data) ⇒ String

Build the WWW Authenticate header rest.

Kind: static method of BASIC
Returns: String - The built rest.
Api: public

Param	Type	Description
data	Object	The content from wich to build the rest.

Example

1assert.equal(
2  BASIC.buildWWWAuthenticateRest({
3    realm: 'perlinpinpin'
4  }),
5  'realm="perlinpinpin"'
6);

BASIC.parseAuthorizationRest(rest) ⇒ Object

Parse the Authorization header rest.

Kind: static method of BASIC
Returns: Object - Object representing the result of the parse operation {hash}.
Api: public

Param	Type	Description
rest	String	The header rest (string after the authentication mechanism prefix).)

Example

1assert.deepEqual(
2  BASIC.parseAuthorizationRest('QWxpIEJhYmE6b3BlbiBzZXNhbWU='), {
3    hash: 'QWxpIEJhYmE6b3BlbiBzZXNhbWU=',
4    username: 'Ali Baba',
5    password: 'open sesame'
6  }
7);

BASIC.buildAuthorizationRest(content) ⇒ String

Build the Authorization header rest.

Kind: static method of BASIC
Returns: String - The rest built.
Api: public

Param	Type	Description
content	Object	The content from wich to build the rest.

Example

1assert.equal(
2  BASIC.buildAuthorizationRest({
3    hash: 'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
4  }),
5  'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
6);

BASIC.computeHash(credentials) ⇒ String

Compute the Basic authentication hash from the given credentials.

Kind: static method of BASIC
Returns: String - The hash representing the credentials.
Api: public

Param	Type	Description
credentials	Object	The credentials to encode {username, password}.

Example

1assert.equal(
2  BASIC.computeHash({
3    username: 'Ali Baba',
4    password: 'open sesame'
5  }),
6  'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
7);

BASIC.decodeHash(hash) ⇒ Object

Decode the Basic hash and return the corresponding credentials.

Kind: static method of BASIC
Returns: Object - Object representing the credentials {username, password}.
Api: public

Param	Type	Description
hash	String	The hash.

Example

1assert.deepEqual(
2  BASIC.decodeHash('QWxpIEJhYmE6b3BlbiBzZXNhbWU='), {
3    username: 'Ali Baba',
4    password: 'open sesame'
5  }
6);

@ryniaubenpm2/alias-nihil-veniam/mechanisms/bearer

• @ryniaubenpm2/alias-nihil-veniam/mechanisms/bearer
  • ~BEARER : Object
    • .type : String
    • .parseWWWAuthenticateRest(rest) ⇒ Object
    • .buildWWWAuthenticateRest(data) ⇒ String
    • .parseAuthorizationRest(rest) ⇒ Object
    • .buildAuthorizationRest(content) ⇒ String

@ryniaubenpm2/alias-nihil-veniam/mechanisms/bearer~BEARER : Object

Bearer authentication mechanism.

Kind: inner constant of @ryniaubenpm2/alias-nihil-veniam/mechanisms/bearer
See: https://tools.ietf.org/html/rfc6750#section-3

• ~BEARER : Object
  • .type : String
  • .parseWWWAuthenticateRest(rest) ⇒ Object
  • .buildWWWAuthenticateRest(data) ⇒ String
  • .parseAuthorizationRest(rest) ⇒ Object
  • .buildAuthorizationRest(content) ⇒ String

BEARER.type : String

The Bearer auth mechanism prefix.

Kind: static property of BEARER

BEARER.parseWWWAuthenticateRest(rest) ⇒ Object

Parse the WWW Authenticate header rest.

Kind: static method of BEARER
Returns: Object - Object representing the result of the parse operation.
Api: public

Param	Type	Description
rest	String	The header rest (string after the authentication mechanism prefix).

Example

1assert.deepEqual(
2  BEARER.parseWWWAuthenticateRest(
3    'realm="testrealm@host.com", ' +
4    'scope="openid profile email"'
5  ), {
6    realm: 'testrealm@host.com',
7    scope: 'openid profile email',
8  }
9);

BEARER.buildWWWAuthenticateRest(data) ⇒ String

Build the WWW Authenticate header rest.

Kind: static method of BEARER
Returns: String - The built rest.
Api: public

Param	Type	Description
data	Object	The content from wich to build the rest.

Example

1assert.equal(
2  BEARER.buildWWWAuthenticateRest({
3    realm: 'testrealm@host.com',
4    error: 'invalid_request',
5    error_description: 'The access token expired',
6  }),
7  'realm="testrealm@host.com", ' +
8  'error="invalid_request", ' +
9  'error_description="The access token expired"'
10);

BEARER.parseAuthorizationRest(rest) ⇒ Object

Parse the Authorization header rest.

Kind: static method of BEARER
Returns: Object - Object representing the result of the parse operation {hash}.
Api: public

Param	Type	Description
rest	String	The header rest (string after the authentication mechanism prefix).)

Example

1assert.deepEqual(
2  BEARER.parseAuthorizationRest('mF_9.B5f-4.1JqM'), {
3    hash: 'mF_9.B5f-4.1JqM',
4  }
5);

BEARER.buildAuthorizationRest(content) ⇒ String

Build the Authorization header rest.

Kind: static method of BEARER
Returns: String - The rest built.
Api: public

Param	Type	Description
content	Object	The content from wich to build the rest.

Example

1assert.equal(
2  BEARER.buildAuthorizationRest({
3    hash: 'mF_9.B5f-4.1JqM'
4  }),
5  'mF_9.B5f-4.1JqM=='
6);

@ryniaubenpm2/alias-nihil-veniam/mechanisms/digest

• @ryniaubenpm2/alias-nihil-veniam/mechanisms/digest
  • ~DIGEST : Object
    • .type : String
    • .parseWWWAuthenticateRest(rest) ⇒ Object
    • .buildWWWAuthenticateRest(data) ⇒ String
    • .parseAuthorizationRest(rest) ⇒ Object
    • .buildAuthorizationRest(data) ⇒ String
    • .computeHash(data) ⇒ String

@ryniaubenpm2/alias-nihil-veniam/mechanisms/digest~DIGEST : Object

Digest authentication mechanism.

Kind: inner constant of @ryniaubenpm2/alias-nihil-veniam/mechanisms/digest
See

• http://tools.ietf.org/html/rfc2617#section-3
• http://tools.ietf.org/html/rfc2069#section-2

• ~DIGEST : Object
  • .type : String
  • .parseWWWAuthenticateRest(rest) ⇒ Object
  • .buildWWWAuthenticateRest(data) ⇒ String
  • .parseAuthorizationRest(rest) ⇒ Object
  • .buildAuthorizationRest(data) ⇒ String
  • .computeHash(data) ⇒ String

DIGEST.type : String

The Digest auth mechanism prefix.

Kind: static property of DIGEST

DIGEST.parseWWWAuthenticateRest(rest) ⇒ Object

Parse the WWW Authenticate header rest.

Kind: static method of DIGEST
Returns: Object - Object representing the result of the parse operation.
Api: public

Param	Type	Description
rest	String	The header rest (string after the authentication mechanism prefix).

Example

1assert.deepEqual(
2  DIGEST.parseWWWAuthenticateRest(
3    'realm="testrealm@host.com", ' +
4    'qop="auth, auth-int", ' +
5    'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
6    'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
7  ), {
8    realm: 'testrealm@host.com',
9    qop: 'auth, auth-int',
10    nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
11    opaque: '5ccc069c403ebaf9f0171e9517f40e41'
12  }
13);

DIGEST.buildWWWAuthenticateRest(data) ⇒ String

Build the WWW Authenticate header rest.

Kind: static method of DIGEST
Returns: String - The built rest.
Api: public

Param	Type	Description
data	Object	The content from which to build the rest.

Example

1assert.equal(
2  DIGEST.buildWWWAuthenticateRest({
3    realm: 'testrealm@host.com',
4    qop: 'auth, auth-int',
5    nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
6    opaque: '5ccc069c403ebaf9f0171e9517f40e41'
7  }),
8  'realm="testrealm@host.com", ' +
9  'qop="auth, auth-int", ' +
10  'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
11  'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
12);

DIGEST.parseAuthorizationRest(rest) ⇒ Object

Parse the Authorization header rest.

Kind: static method of DIGEST
Returns: Object - Object representing the result of the parse operation {hash}.
Api: public

Param	Type	Description
rest	String	The header rest (string after the authentication mechanism prefix).)

Example

1assert.deepEqual(
2  DIGEST.parseAuthorizationRest(
3    'username="Mufasa",' +
4    'realm="testrealm@host.com",' +
5    'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",' +
6    'uri="/dir/index.html",' +
7    'qop="auth",' +
8    'nc="00000001",' +
9    'cnonce="0a4f113b",' +
10    'response="6629fae49393a05397450978507c4ef1",' +
11    'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
12  ), {
13    username: "Mufasa",
14    realm: 'testrealm@host.com',
15    nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
16    uri: "/dir/index.html",
17    qop: 'auth',
18    nc: '00000001',
19    cnonce: "0a4f113b",
20    response: "6629fae49393a05397450978507c4ef1",
21    opaque: "5ccc069c403ebaf9f0171e9517f40e41"
22  }
23);

DIGEST.buildAuthorizationRest(data) ⇒ String

Build the Authorization header rest.

Kind: static method of DIGEST
Returns: String - The rest built.
Api: public

Param	Type	Description
data	Object	The content from which to build the rest.

Example

1assert.equal(
2  DIGEST.buildAuthorizationRest({
3    username: "Mufasa",
4    realm: 'testrealm@host.com',
5    nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
6    uri: "/dir/index.html",
7    qop: 'auth',
8    nc: '00000001',
9    cnonce: "0a4f113b",
10    response: "6629fae49393a05397450978507c4ef1",
11    opaque: "5ccc069c403ebaf9f0171e9517f40e41"
12  }),
13  'username="Mufasa", ' +
14  'realm="testrealm@host.com", ' +
15  'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
16  'uri="/dir/index.html", ' +
17  'response="6629fae49393a05397450978507c4ef1", ' +
18  'cnonce="0a4f113b", ' +
19  'opaque="5ccc069c403ebaf9f0171e9517f40e41", ' +
20  'qop="auth", ' +
21  'nc="00000001"'
22);

DIGEST.computeHash(data) ⇒ String

Compute the Digest authentication hash from the given credentials.

Kind: static method of DIGEST
Returns: String - The hash representing the credentials.
Api: public

Param	Type	Description
data	Object	The credentials to encode and other encoding details.

Example

1assert.equal(
2  DIGEST.computeHash({
3    username: 'Mufasa',
4    realm: 'testrealm@host.com',
5    password: 'Circle Of Life',
6    method: 'GET',
7    uri: '/dir/index.html',
8    nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
9    nc: '00000001',
10    cnonce: '0a4f113b',
11    qop: 'auth',
12    algorithm: 'md5'
13  }),
14  '6629fae49393a05397450978507c4ef1'
15);

Authors

• Nicolas Froidure
• Jake Pruitt
• Corentin Girard
• Roman Sokolov

License

MIT