README.md

Web JWT

Small JWT library using the Web Crypto API.

Installation

npm install @borderless/web-jwt --save

Usage

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.
• The JWT alg header is ignored and the crypto key algorithm is used instead. This avoids attacks using the alg header.

TypeScript

This project is written using TypeScript and publishes the definitions directly to NPM.

License

MIT