@curity/jwt-validation/README.md

Curity JWT Validation library

# JWT Validation

Simple JWT validation library without any external dependencies.

**NOTE**: if you plan to use the library in an environment without the browser you will need to use at least node version 15.0.0.

## Add to project
Add to your project using npm 

```
npm install @curity/jwt-validation
```

or yarn

```
yarn add @curity/jwt-validation
```

## How to use in your project

Initialize the JWT Validator.  

```
import JWTValidator from "@curity/jwt-validation";
// OR using require 
// const JWTValidator = require("@curity/jwt-validation");

const allowed_jwt_algorithms= ['RS256', 'ES384'];

const jwt_sig_public_key= {   // allowed formats are jwk | jwks_uri | pem | issuer | metadata_url | raw
    format: 'issuer',   // in case of issuer, the issuer value will be taken from jwt payload
    value: null
};

const jwtValidator = new JWTValidator(
            issuer,
            audience,  // audience is the client_id
            allowed_jwt_algorithms,
            jwt_sig_public_key,
        );

```
      
      
Verify JWT using jwtValidator instance that you initialized as described above.  

```
const options= {
   accessToken     : accessTokenValue,     // optional, pass it if you want to validate at_hash
   state           : stateValue,           // optional, pass it if you want to validate s_hash
   nonce           : nonceValue,           // optional, pass it if you want to validate nonce
   ignoreExpiration: true,                 // optional, default false
   ignoreNotBefore : true,                 // optional, default false
   clockTolerance  : 0,                    // optional, default 0 seconds
   subject         : 'test',               // optional, if provided, then jwt.sub should match it
   jti             : 'jti-value',          // optional, if provided, then jwt.jti should match it
   code            : 'authorize-code'      // optional, pass it if you want to validate c_hash
};

jwtValidator.verifyJWT(jwtString, options)
        .then((payload) => {
           // validation is successful, payload is parsed json payload of jwt.
           // do the stuff here to save or use jwt.
        }).catch(err => {
            // validation failed, err.message contain the reason for failure
        })

```

### Allowed public key formats 
    
* **jwk**   
   A jwk can directly be passed as an object (and not a string), when format specified is `jwk`.    
      
* **jwks_uri**     
   A list of jwks can be retrieved from a specified `jwks_uri`.
   
* **pem**    
   A pem key string can be provided using public key format `pem`. 
   
* **issuer**   
   If the format specified is `issuer`, then jwt issuer is used to retrieve metadata which in turn, is resolved to retrieve jwk from corresponding jwks_uri. 
     
* **metadata_url**    
   If the format specified is `metadata_url`, then jwk is retrieved from corresponding jwks_uri of resolved metadata.
    
* **raw**    
   You can also provide the raw public key using format `raw` e.g: HMAC secret.   
  
### Supported Algorithms

Following is the list of supported algorithms.

```
HS256: {name: 'HMAC', hash: 'SHA-256'},
HS384: {name: 'HMAC', hash: 'SHA-384'},
HS512: {name: 'HMAC', hash: 'SHA-512'},
RS256: {name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256'},
RS384: {name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-384'},
RS512: {name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-512'},
ES256: {name: 'ECDSA', namedCurve: "P-256", hash: 'SHA-256'},
ES384: {name: 'ECDSA', namedCurve: "P-384", hash: 'SHA-384'},
ES512: {name: 'ECDSA', namedCurve: "P-521", hash: 'SHA-512'},
PS256: {name: 'RSA-PSS', saltLength: 256 / 8, hash: 'SHA-256'},
PS384: {name: 'RSA-PSS', saltLength: 384 / 8, hash: 'SHA-384'},
PS512: {name: 'RSA-PSS', saltLength: 512 / 8, hash: 'SHA-512'}
```