npm package: @funkybob/jwt
Description: Native JWT validation without deps
Author: Curtis Maloney
Latest version: 2.0.4

Native JWT validation
=====================

Using nothing but what modern browsers provide, this package can decode and
validate JWT, even those signed using RS256.

Supported Algorithms
--------------------

 - HS256
 - HS384
 - HS512
 - RS256
 - RS384
 - RS512

Verified Claims
---------------

 - aud
 - iss
 - exp
 - nbf

Note: RS algorithms only support keys in JWK format, currently.

Usage
-----

    import {decode, verify} from "@funkybob/jwt"

    let jwt = decode(token);
    let valid;
    try {
        valid = await verify(jwt, options)
    } catch(err) {
        valid = false;
    };

Loading Keys
------------

If you are using the RS family of signing algorithms, you will need to provide
a map of kid to JWK objects (see https://tools.ietf.org/html/rfc7517).

If your issuer provides their JWK at well known URI ("/.well-known/jwks.json")
you can use the "fetchKeys" function to retrieve them once. This returns a
Promise:

    options.keys = await fetchKeys('hostname.myissuer.com')

or

    fetchKeys('hostname').then(keys => options.keys = keys);

Remember to not try to validate a token before this promise is resolved.

Errors
------

"Unsupported algorithm"

The 'alg' specified in the Header does not match that specified in options, or
is not supported by this library.

"Unknown key"

The 'kid' specified in the Header could not be found in the list of known keys.
If options.hostname was specified, the list of keys retrieved did not contain
the matching kid.

"Invalid signature"

The signing algorithm returned a negative result.

"Unrecognised issuer"

The 'iss' field in the Message did not match that specified in options.

"Invalid audience"

The 'aud' specified in options was not found in the 'aud' list in the Message.

"Token has expired"

The tokens 'exp' claim is in the past.

"Token not yet valid"

The tokens 'nbf' claim is in the future.


Modules
=======

verify
--------

# decode(token)

Decodes a JWT string into an Object:

 - header : the JSON decoded content of the header part of the token.
 - claims : the JSON decoded content of the claims part of the token.
 - signature : the signature from the token
 - parts : the token split by '.'
 - token : the original token string

# async isValid(jwt, {alg, iss, aud, secret, keys})

 - alg: signature algorithm
 - aud: audience (Optional)
 - iss: issuer (Optional)
 - secret: secret for HS* algorithms
 - keys: map of {kid: jwt} for RS* algorithms

Check if a jwt is valid.

 - verifies header.typ is 'JWT'
 - verifies the algorithm matches what we accept.
 - verifies the signature matches
 - if an "iss" is specified, verify it matches.
 - if an "aud" is specified, verify it matches.
 - if the token claims an "exp", ensure it's after now.
 - if the token claims a "nbf", ensure it's before now.

keys
----

# fetchKeys (hostname)

Fetches keys from `https://${hostname}/.well-known/jwks.json`, then assembles them into
an Object by Key ID (kid).

crypto
------

# function importKey (alg, key)

Imports the key matter as appropriate for the specified algorithm.

util
----

# function b64d (v)

base64url decode 'v'

# function b64e (v)

base64url encode 'v'

# function str2bytes (v)

Converts 'v' from a String to a Uint8Array.

# function bytes2str (v)

Converts 'v' from a Uint8Array to a String