branca

Branca

What?

Branca is a secure easy to use token format which makes it hard to shoot yourself in the foot. It uses IETF XChaCha20-Poly1305 AEAD symmetric encryption to create encrypted and tamperproof tokens. Payload itself is an arbitrary sequence of bytes. You can use for example a JSON object, plain text string or even binary data serialized by MessagePack or Protocol Buffers. It is possible to use Branca as an alternative to JWT.

Install

Install the library using Yarn or npm.

$ yarn add branca
$ npm install branca

Secret key

The token is encrypted using a 32 byte secret key. As the name implies this key should be kept a secret. Do not commit it to version control nor make it publicly available.

You can pass the secret key either as an instance of Buffer or a hex encoded string.

const key = crypto.randomBytes(32);
const branca = require("branca")(key);

const key = "7ed049e344f73f399ba1f7868cf9494f4b13347ecce02a8e463feb32507b73a5";
const branca = require("branca")(key);

While technically possible, you should not use human readable strings as the secret key. Instead always generate the key using cryptographically secure random bytes. You can do this, for example, from commandline with Node.js itself or openssl.

$ node
Welcome to Node.js v16.2.0.
Type ".help" for more information.
> crypto.randomBytes(32).toString("hex")
'46cad3699da5766c45e80edfbf19dd2debc311e0c9046a80e791597442b2daf0'

$ openssl rand -hex 32

29f7d3a263bd6fcfe716865cbdb00b7a317d1993b8b7a3a5bae6192fbe0ace65

To keep things simple, rest of the examples generate the secret key on the fly. In real life the application would load the secret key from external key store. External here meaning outside of the application code. How to store and load secret keys in beyond the scope of this library.

Payload

Token payload can be any arbitrary data such as a string containing an email address.

/* 32 byte secret key */
const crypto = require("crypto");
const key = crypto.randomBytes(32);
const branca = require("branca")(key);

const token = branca.encode("[e-mail]");
console.log(token);

/*
n8EWZ6msHPjbUPLfezL7g00RBNDvHZ37Or4aGeIWqPjUj0Sht41dasPgQgmEl3UsV4JKS4kZtEiZ6V54JYtYJRhtH8
*/

const payload = branca.decode(token);
console.log(payload.toString());

/* [e-mail] */

Sometimes you might prefer JSON.

/* 32 byte secret key */
const crypto = require("crypto");
const key = crypto.randomBytes(32);
const branca = require("branca")(key);

const json = JSON.stringify({"scope": ["read", "write", "delete"]});
const token = branca.encode(json);
console.log(token);

/*
5R9kHEyH57WbQhy0Ba3NwPYu0pFlAv45jOIsmUdvHs0HAVX3CzNw90DtXs60UwjwfYopZ1NvO11GkEQTjumMIZYuCcawnoztFsexGlHoFKGX
*/

const payload = JSON.parse(branca.decode(token));
console.log(payload);

/* { scope: [ 'read', 'write', 'delete' ] } */

You can keep the token size small by using a space efficient serialization method such as MessagePack or Protocol Buffers.

/* 32 byte secret key */
const crypto = require("crypto");
const key = crypto.randomBytes(32);
const branca = require("branca")(key);
const msgpack = require("msgpack5")();

const packed = msgpack.encode({"scope": ["read", "write", "delete"]});
const token = branca.encode(packed);
console.log(token);

/*
2EZpow8Nwk6Z9UxMel3kzFUe5boHV480zwkZDp6hNgaatnOCt4YbqgCRICKnm7IfJgxzQpT9eYdrTzyb
*/

const binary = branca.decode(token);
const payload = msgpack.decode(Buffer.from(binary));
console.log(payload);

/* { scope: [ 'read', 'write', 'delete' ] } */

Testing

You can run tests manually with the following command.

$ node test.js

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

Changelog

0.5.0 - 2022-04-27

Changed

• Replaced Travis with GitHub actions (#20).
• Upgraded base-x and tape (#22).