{"id":16320302,"url":"https://github.com/tuupola/branca-js","last_synced_at":"2025-05-07T15:22:07.067Z","repository":{"id":23063773,"uuid":"98050115","full_name":"tuupola/branca-js","owner":"tuupola","description":"Authenticated encrypted API Tokens for JavaScript. ","archived":false,"fork":false,"pushed_at":"2022-04-27T08:42:13.000Z","size":34,"stargazers_count":93,"open_issues_count":3,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-15T18:04:53.850Z","etag":null,"topics":["api","jwt","token-authentication","xchacha20-poly1305"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuupola.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-22T18:23:23.000Z","updated_at":"2024-12-16T21:29:42.000Z","dependencies_parsed_at":"2022-08-07T10:16:40.563Z","dependency_job_id":null,"html_url":"https://github.com/tuupola/branca-js","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuupola","download_url":"https://codeload.github.com/tuupola/branca-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252902796,"owners_count":21822311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","jwt","token-authentication","xchacha20-poly1305"],"created_at":"2024-10-10T22:43:54.787Z","updated_at":"2025-05-07T15:22:07.047Z","avatar_url":"https://github.com/tuupola.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"#  Branca\n\n[![Latest Version](https://img.shields.io/npm/v/branca.svg?style=flat-square)](https://www.npmjs.com/package/branca)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)\n[![Build Status](https://img.shields.io/github/workflow/status/tuupola/branca-js/Tests/master?style=flat-square)](https://github.com/tuupola/branca-js/actions)\n[![Coverage](https://img.shields.io/codecov/c/github/tuupola/branca-js.svg?style=flat-square)](https://codecov.io/github/tuupola/branca-js)\n\n## What?\n\n[Branca](https://github.com/tuupola/branca-spec) 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](http://msgpack.org/) or [Protocol Buffers](https://developers.google.com/protocol-buffers/). It is possible to use [Branca as an alternative to JWT](https://appelsiini.net/2017/branca-alternative-to-jwt/).\n\n## Install\n\nInstall the library using [Yarn](https://yarnpkg.com/en/) or [npm](https://www.npmjs.com/).\n\n``` bash\n$ yarn add branca\n$ npm install branca\n```\n\n## Secret key\n\nThe 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**.\n\nYou can pass the secret key either as an instance of `Buffer` or a hex encoded string.\n\n```javascript\nconst key = crypto.randomBytes(32);\nconst branca = require(\"branca\")(key);\n```\n\n```javascript\nconst key = \"7ed049e344f73f399ba1f7868cf9494f4b13347ecce02a8e463feb32507b73a5\";\nconst branca = require(\"branca\")(key);\n```\n\nWhile 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.\n\n```\n$ node\nWelcome to Node.js v16.2.0.\nType \".help\" for more information.\n\u003e crypto.randomBytes(32).toString(\"hex\")\n'46cad3699da5766c45e80edfbf19dd2debc311e0c9046a80e791597442b2daf0'\n```\n\n```\n$ openssl rand -hex 32\n\n29f7d3a263bd6fcfe716865cbdb00b7a317d1993b8b7a3a5bae6192fbe0ace65\n```\n\nTo 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.\n\n## Payload\n\nToken payload can be any arbitrary data such as a string containing an email\naddress.\n\n```javascript\n/* 32 byte secret key */\nconst crypto = require(\"crypto\");\nconst key = crypto.randomBytes(32);\nconst branca = require(\"branca\")(key);\n\nconst token = branca.encode(\"tuupola@appelsiini.net\");\nconsole.log(token);\n\n/*\nn8EWZ6msHPjbUPLfezL7g00RBNDvHZ37Or4aGeIWqPjUj0Sht41dasPgQgmEl3UsV4JKS4kZtEiZ6V54JYtYJRhtH8\n*/\n\nconst payload = branca.decode(token);\nconsole.log(payload.toString());\n\n/* tuupola@appelsiini.net */\n```\n\nSometimes you might prefer JSON.\n\n```javascript\n/* 32 byte secret key */\nconst crypto = require(\"crypto\");\nconst key = crypto.randomBytes(32);\nconst branca = require(\"branca\")(key);\n\nconst json = JSON.stringify({\"scope\": [\"read\", \"write\", \"delete\"]});\nconst token = branca.encode(json);\nconsole.log(token);\n\n/*\n5R9kHEyH57WbQhy0Ba3NwPYu0pFlAv45jOIsmUdvHs0HAVX3CzNw90DtXs60UwjwfYopZ1NvO11GkEQTjumMIZYuCcawnoztFsexGlHoFKGX\n*/\n\nconst payload = JSON.parse(branca.decode(token));\nconsole.log(payload);\n\n/* { scope: [ 'read', 'write', 'delete' ] } */\n```\n\nYou can keep the token size small by using a space efficient serialization method such as [MessagePack](http://msgpack.org/) or [Protocol Buffers](https://developers.google.com/protocol-buffers/).\n\n```javascript\n/* 32 byte secret key */\nconst crypto = require(\"crypto\");\nconst key = crypto.randomBytes(32);\nconst branca = require(\"branca\")(key);\nconst msgpack = require(\"msgpack5\")();\n\nconst packed = msgpack.encode({\"scope\": [\"read\", \"write\", \"delete\"]});\nconst token = branca.encode(packed);\nconsole.log(token);\n\n/*\n2EZpow8Nwk6Z9UxMel3kzFUe5boHV480zwkZDp6hNgaatnOCt4YbqgCRICKnm7IfJgxzQpT9eYdrTzyb\n*/\n\nconst binary = branca.decode(token);\nconst payload = msgpack.decode(Buffer.from(binary));\nconsole.log(payload);\n\n/* { scope: [ 'read', 'write', 'delete' ] } */\n```\n\n## Testing\n\nYou can run tests manually with the following command.\n\n``` bash\n$ node test.js\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Security\n\nIf you discover any security related issues, please email tuupola@appelsiini.net instead of using the issue tracker.\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuupola%2Fbranca-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuupola%2Fbranca-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuupola%2Fbranca-js/lists"}