Small JWT library using the Web Crypto API
npm install @borderless/web-jwt[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Build status][build-image]][build-url]
[![Test coverage][coverage-image]][coverage-url]
[![Bundle size][bundle-image]][bundle-url]
> Small JWT library using the Web Crypto API.
``sh`
npm install @borderless/web-jwt --save
`js
import {
encodeJwt,
decodeJwt,
verifyJwt,
NOOP_JWT,
NONE_KEY,
} from "@borderless/web-jwt";
// Create a web crypto key.
const key = crypto.subtle.importKey(
"jwk",
{
kty: "oct",
k: "4Vulge0qgl6janNxYmrYk-sao2wR5tpyKkh_sTLY2CQ",
alg: "HS256",
},
{ name: "HMAC", hash: "SHA-256" },
false,
["sign", "verify"]
);
// Create a JWT and sign using the key.
await encodeJwt(
{
alg: "HS256",
},
{
test: true,
},
key
); //=> "eyJhbGciOiJIUzI1NiJ9.eyJ0ZXN0Ijp0cnVlfQ.pQM0RvgTKjtAC1XmMnCK4vhgGycbg0vVLn0rsiE8BGc"
// Decode the JWT.
const jwt = await decodeJwt(
"eyJhbGciOiJIUzI1NiJ9.eyJ0ZXN0Ijp0cnVlfQ.pQM0RvgTKjtAC1XmMnCK4vhgGycbg0vVLn0rsiE8BGc"
); //=> { header, payload, ... }
// Verify the decoded JWT _before_ trusting!
const valid = await verifyJwt(jwt); //=> true
`
Notes:
- decodeJwt will return a NOOP_JWT when decoding an invalid JWT. No errors are thrown on invalid data.alg: none
- is only supported by using the NONE_KEY symbol exported by the package.alg
- The JWT header is ignored and the crypto key algorithm is used instead. This avoids attacks using the alg` header.
This project is written using TypeScript and publishes the definitions directly to NPM.
MIT
[npm-image]: https://img.shields.io/npm/v/@borderless/web-jwt
[npm-url]: https://npmjs.org/package/@borderless/web-jwt
[downloads-image]: https://img.shields.io/npm/dm/@borderless/web-jwt
[downloads-url]: https://npmjs.org/package/@borderless/web-jwt
[build-image]: https://img.shields.io/github/actions/workflow/status/borderless/web-jwt/ci.yml?branch=main
[build-url]: https://github.com/borderless/web-jwt/actions/workflows/ci.yml?query=branch%3Amain
[coverage-image]: https://img.shields.io/codecov/c/gh/borderless/web-jwt
[coverage-url]: https://codecov.io/gh/borderless/web-jwt
[bundle-image]: https://img.shields.io/bundlephobia/minzip/@borderless/web-jwt.svg
[bundle-url]: https://bundlephobia.com/result?p=@borderless/web-jwt