@jlinc/jwt v1.0.3

JLINC JSON WebToken

The JLINC protocol uses JSON WebTokens of type JWS as a compact standards-based way to transmit SISAs and SISA Events between servers.

The standard NPM jsonwebtoken package supports 13 algorithms, only one of which (HS256) is used by JLINC, and does not support EdDSA/Ed25519 which we do need. It has many options and support for standard claims which we also don't need.

This package supports HS256 and EdDSA/Ed25519 algorithms only and tries to be a simple as possible to enable comprehensive security audit. It has only two dependencies, sodium and urlsafe-base64.

There are 3 compatibility methods, decode, sign and verify, to provide drop-in replacement for the default usage in the existing jsonwebtoken package.

Expected Usage

given:

const jwt = require('jlinc-jwt');

Sign with HMAC/SHA256

/*
PayloadObject must be a javascript object.
SecretString can be any string.
*/

jwt.signHmac(PayloadObject, SecretString) --> JWT

Compatibility sign with HMAC/SHA256

jwt.sign(PayloadObject, SecretString) --> JWT

Sign with EdDSA/Ed25519

/* 
PayloadObject must be a javascript object.
PublicKey and SecretKey are an Ed25519 keypair as created for example by sodium.crypto_sign_keypair().

The optional DIDKeyUrl argument, if present, is placed in the JWT header under jwk.kid,
i.e. a JSON-WebKey key-ID (https://www.rfc-editor.org/rfc/rfc7515#section-4.1.4).

If used, it must be either a JLINC DID or a JLINC DID url of the form {DID}#signing
*/

jwt.signEdDsa(PayloadObject, PublicKey, SecretKey[, DIDkeyUrl]) --> JWT

Read a JWT

/*
Presented with a valid JWT, returns an object with the following keys --

signed: the first two sections of the JWT
signature: the last section of the JWT
header: the decoded header object
payload: the decoded payload

*/

jwt.read(JWT) --> JWT information object

Decode a JWT

/*
Presented with a valid JWT, returns the payload object only.
Included for compatibility with the jsonwebtoken package, except that it throws
an error if the JWT is unreadable rather than returning null.
*/

jwt.decode(JWT) --> JWT payload object

Verify a HMAC/SHA256 signed JWT

/*
Presented with a valid HMAC/SHA256 signed JWT and the secret it was signed with,
returns an object as in Read above.
*/

jwt.verifyHmac(JWT, SecretString) --> JWT information object

Compatibility verify a HMAC/SHA256 signed JWT

/*
Same as above except returns the JWT payload only.
*/

jwt.verify(JWT, SecretString) --> JWT payload object

Verify an EdDSA/Ed25519 signed JWT

/*
JWTs created with this package's signEdDsa() method will contain the public key that
validates the signature in the JWT's header under the jwk.x key.
See https://tools.ietf.org/html/rfc8037#section-2.

If the public key is not available that way, perhaps because the JWT was created by a different
application, then it must be supplied by the optional second argument. If the public key
is present in both places, the supplied argument will be used.

On success returns an object as in Read above.
*/

jwt.verifyEdDsa(JWT[, PublicKey]) --> JWT information object