http-auth-utils
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.1 • Public • Published

    http-auth-utils

    Parse, build and deal with HTTP authorization headers.

    GitHub license Build status Coverage Status NPM version Dependency Status devDependency Status Package Quality Code Climate

    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

    http-auth-utils
    http-auth-utils/mechanisms/basic
    http-auth-utils/mechanisms/bearer
    http-auth-utils/mechanisms/digest

    http-auth-utils

    http-auth-utils.mechanisms : Object

    Basic authentication mechanism.

    Kind: static property of http-auth-utils
    See: http-auth-utils/mechanisms/basic

    http-auth-utils~mechanisms : Array

    Natively supported authentication mechanisms.

    Kind: inner constant of http-auth-utils

    http-auth-utils~parseWWWAuthenticateHeader(header, [authMechanisms], [options]) ⇒ Object

    Parse HTTP WWW-Authenticate header contents.

    Kind: inner method of http-auth-utils
    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

    assert.deepEqual(
      parseWWWAuthenticateHeader('Basic realm="test"'), {
        type: 'Basic',
        data: {
          realm: 'test'
        }
      }
    );

    http-auth-utils~parseAuthorizationHeader(header, [authMechanisms], [options]) ⇒ Object

    Parse HTTP Authorization header contents.

    Kind: inner method of http-auth-utils
    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

    assert.deepEqual(
      parseAuthorizationHeader('Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='), {
        type: 'Basic',
        data: {
          hash: 'QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
        }
      }
    );

    http-auth-utils~buildWWWAuthenticateHeader(authMechanism, The) ⇒ string

    Build HTTP WWW-Authenticate header value.

    Kind: inner method of http-auth-utils
    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

    assert.deepEqual(
      buildWWWAuthenticateHeader(BASIC, {
        realm: 'test'
      }),
      'Basic realm="test"'
    );

    http-auth-utils~buildAuthorizationHeader(authMechanism, The) ⇒ string

    Build HTTP Authorization header value.

    Kind: inner method of http-auth-utils
    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

    assert.deepEqual(
      buildAuthorizationHeader(BASIC, {
        realm: 'test'
      }),
      'Basic realm="test"'
    );

    http-auth-utils/mechanisms/basic

    http-auth-utils/mechanisms/basic~BASIC : Object

    Basic authentication mechanism.

    Kind: inner constant of http-auth-utils/mechanisms/basic
    See: http://tools.ietf.org/html/rfc2617#section-2

    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

    assert.deepEqual(
      BASIC.parseWWWAuthenticateRest('realm="perlinpinpin"'), {
        realm: 'perlinpinpin'
      }
    );

    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

    assert.equal(
      BASIC.buildWWWAuthenticateRest({
        realm: 'perlinpinpin'
      }),
      'realm="perlinpinpin"'
    );

    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

    assert.deepEqual(
      BASIC.parseAuthorizationRest('QWxpIEJhYmE6b3BlbiBzZXNhbWU='), {
        hash: 'QWxpIEJhYmE6b3BlbiBzZXNhbWU=',
        username: 'Ali Baba',
        password: 'open sesame'
      }
    );

    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

    assert.equal(
      BASIC.buildAuthorizationRest({
        hash: 'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
      }),
      'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
    );

    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

    assert.equal(
      BASIC.computeHash({
        username: 'Ali Baba',
        password: 'open sesame'
      }),
      'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
    );

    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

    assert.deepEqual(
      BASIC.decodeHash('QWxpIEJhYmE6b3BlbiBzZXNhbWU='), {
        username: 'Ali Baba',
        password: 'open sesame'
      }
    );

    http-auth-utils/mechanisms/bearer

    http-auth-utils/mechanisms/bearer~BEARER : Object

    Bearer authentication mechanism.

    Kind: inner constant of http-auth-utils/mechanisms/bearer
    See: https://tools.ietf.org/html/rfc6750#section-3

    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

    assert.deepEqual(
      BEARER.parseWWWAuthenticateRest(
        'realm="testrealm@host.com", ' +
        'scope="openid profile email"'
      ), {
        realm: 'testrealm@host.com',
        scope: 'openid profile email',
      }
    );

    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

    assert.equal(
      BEARER.buildWWWAuthenticateRest({
        realm: 'testrealm@host.com',
        error: 'invalid_request',
        error_description: 'The access token expired',
      }),
      'realm="testrealm@host.com", ' +
      'error="invalid_request", ' +
      'error_description="The access token expired"'
    );

    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

    assert.deepEqual(
      BEARER.parseAuthorizationRest('mF_9.B5f-4.1JqM'), {
        hash: 'mF_9.B5f-4.1JqM',
      }
    );

    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

    assert.equal(
      BEARER.buildAuthorizationRest({
        hash: 'mF_9.B5f-4.1JqM'
      }),
      'mF_9.B5f-4.1JqM=='
    );

    http-auth-utils/mechanisms/digest

    http-auth-utils/mechanisms/digest~DIGEST : Object

    Digest authentication mechanism.

    Kind: inner constant of http-auth-utils/mechanisms/digest
    See

    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

    assert.deepEqual(
      DIGEST.parseWWWAuthenticateRest(
        'realm="testrealm@host.com", ' +
        'qop="auth, auth-int", ' +
        'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
        'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
      ), {
        realm: 'testrealm@host.com',
        qop: 'auth, auth-int',
        nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
        opaque: '5ccc069c403ebaf9f0171e9517f40e41'
      }
    );

    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 wich to build the rest.

    Example

    assert.equal(
      DIGEST.buildWWWAuthenticateRest({
        realm: 'testrealm@host.com',
        qop: 'auth, auth-int',
        nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
        opaque: '5ccc069c403ebaf9f0171e9517f40e41'
      }),
      'realm="testrealm@host.com", ' +
      'qop="auth, auth-int", ' +
      'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
      'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
    );

    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

    assert.deepEqual(
      DIGEST.parseAuthorizationRest(
        'username="Mufasa",' +
        'realm="testrealm@host.com",' +
        'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",' +
        'uri="/dir/index.html",' +
        'qop="auth",' +
        'nc="00000001",' +
        'cnonce="0a4f113b",' +
        'response="6629fae49393a05397450978507c4ef1",' +
        'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
      ), {
        username: "Mufasa",
        realm: 'testrealm@host.com',
        nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
        uri: "/dir/index.html",
        qop: 'auth',
        nc: '00000001',
        cnonce: "0a4f113b",
        response: "6629fae49393a05397450978507c4ef1",
        opaque: "5ccc069c403ebaf9f0171e9517f40e41"
      }
    );

    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 wich to build the rest.

    Example

    assert.equal(
      DIGEST.buildAuthorizationRest({
        username: "Mufasa",
        realm: 'testrealm@host.com',
        nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
        uri: "/dir/index.html",
        qop: 'auth',
        nc: '00000001',
        cnonce: "0a4f113b",
        response: "6629fae49393a05397450978507c4ef1",
        opaque: "5ccc069c403ebaf9f0171e9517f40e41"
      }),
      'username="Mufasa", ' +
      'realm="testrealm@host.com", ' +
      'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
      'uri="/dir/index.html", ' +
      'response="6629fae49393a05397450978507c4ef1", ' +
      'cnonce="0a4f113b", ' +
      'opaque="5ccc069c403ebaf9f0171e9517f40e41", ' +
      'qop="auth", ' +
      'nc="00000001"'
    );

    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

    assert.equal(
      DIGEST.computeHash({
        username: 'Mufasa',
        realm: 'testrealm@host.com',
        password: 'Circle Of Life',
        method: 'GET',
        uri: '/dir/index.html',
        nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
        nc: '00000001',
        cnonce: '0a4f113b',
        qop: 'auth',
        algorithm: 'md5'
      }),
      '6629fae49393a05397450978507c4ef1'
    );

    Authors

    License

    MIT

    Install

    npm i http-auth-utils

    DownloadsWeekly Downloads

    1,035

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    316 kB

    Total Files

    64

    Last publish

    Collaborators

    • nfroidure