branca
Authenticated and encrypted API tokens using modern crypto
Last updated 2 years ago by tuupola .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install branca 
SYNC missed versions from official npm registry.

Branca

Latest Version Software License Build Status Coverage

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

Usage

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

const key = "supersecretkeyyoushouldnotcommit";
const branca = require("branca")(key);

const token = branca.encode("tuupola@appelsiini.net");
console.log(token);

/*
TYfc6x7g8HiQf9HMkPwXC33UKwESCiBHrnVbb6AjDTaRR5oDxt3bK8kyiEyyc8HDqfnukQlMHT
*/

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

/* tuupola@appelsiini.net */

Sometimes you might prefer JSON.

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

/*
3Gq57osRXk7UsZsqzLuLOoHYj2VgrGvhkETjZ4J1ftW7zhALYFUol2jDyxYtmrqJfi5DbKx7BqIptfeaoN2yadmJxSIx
*/

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.

const key = "supersecretkeyyoushouldnotcommit";
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 tuupola@appelsiini.net instead of using the issue tracker.

License

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

Current Tags

  • 0.3.0                                ...           latest (2 years ago)

3 Versions

  • 0.3.0                                ...           2 years ago
  • 0.2.0                                ...           4 years ago
  • 0.1.0                                ...           4 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 1
Last Day 0
Last Week 0
Last Month 5
Dependencies (3)
Dev Dependencies (2)

Copyright 2014 - 2017 © taobao.org |