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.
given:
const jwt = require('jlinc-jwt');
/*
PayloadObject must be a javascript object.
SecretString can be any string.
*/
jwt.signHmac(PayloadObject, SecretString) --> JWT
jwt.sign(PayloadObject, SecretString) --> JWT
/*
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
/*
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
/*
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
/*
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
/*
Same as above except returns the JWT payload only.
*/
jwt.verify(JWT, SecretString) --> JWT payload object
/*
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