JWT - JWKS Verification Library

This is a TypeScript library for verifying JSON Web Tokens (JWTs) using JSON Web Key (JWK) sets URL endpoints in the browser.

Note

This library uses the Web Crypto Subtle API to verify JWTs. Cryptography is a complex subject, and it is easy to make mistakes. This is a personal project, and should be used with caution or in controlled environments. I am not a cryptography expert, and I cannot guarantee the security of this library. Please use at your own risk.

Installation

You can install the library using npm or yarn:

npm install jwt-quick

or

yarn add jwt-quick

Usage

To use the library, you can import the verifyTokenByJWKS function and pass in the URL of the JWK set and the JWT to verify:

import { jwt, Token } from "jwt-quick"

const jwksUrl = new URL('https://example.com/.well-known/jwks.json');
const token: Token = {
    header: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
    payload: 'eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ',
    signature: 'SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
};

const isValid = await jwt.verifyTokenByJWKS(jwksUrl, token);
console.log(isValid); // true or false

If you already have a JWK, you can use the verifyTokenByJWK function instead:

import { jwt, Token } from "jwt-quick"

const token: Token = {
    header: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
    payload: 'eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ',
    signature: 'SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
};

const jwk = /* ... */;

const isValid = await jwt.verifyTokenByJWK(token, jwk);
console.log(isValid); // true or false

API

verifyTokenByJWKS(jwksUrl: URL, token: Token): Promise<boolean>

Verifies a JWT using a JWK set at the specified URL.

• jwksUrl: The URL of the JWK set to use for verification.
• token: The JWT to verify.

Returns a Promise that resolves to true if the JWT is valid, or false otherwise.

verifyTokenByJWK(token: Token, jwk: JWK): Promise<boolean>

Verifies a JWT using a single JWK.

• token: The JWT to verify.
• jwk: The JWK to use for verification.

Returns a Promise that resolves to true if the JWT is valid, or false otherwise.

Supported Algorithms

This library currently supports the following algorithms for verifying JSON Web Tokens (JWTs):

• HMAC using SHA-256 (HS256)
• RSASSA-PKCS1-v1_5 using SHA-256 (RS256)
• ECDSA using SHA-256 (ES256)
• ECDSA using SHA-384 (ES384)
• ECDSA using SHA-512 (ES512)

These algorithms are based on the JSON Web Algorithms (JWA) specification. The library currently only supports the Required, Recommended, and Recommended+ algorithms from the specification.

To use the library with a different algorithm, you will need to modify the algDict and hashDict objects in the helper.ts file to include the new algorithm and its corresponding hash algorithm. You will also need to modify the verifyTokenByJWK and verifyTokenByJWKS functions to support the new algorithm.

Support

If you appreciate this library, please consider buying me a coffee. Feel free to create an issue if you have any questions or suggestions. Actively looking for security experts to review the code!

License

This library is licensed under the MIT License.