{"id":15471842,"url":"https://github.com/thadeu/branca-ruby","last_synced_at":"2025-04-22T13:45:14.560Z","repository":{"id":37072600,"uuid":"307579983","full_name":"thadeu/branca-ruby","owner":"thadeu","description":"Branca - Authenticated and encrypted API tokens using modern crypto.","archived":false,"fork":false,"pushed_at":"2022-09-29T20:29:48.000Z","size":49,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-02-22T22:03:59.244Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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/thadeu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["thadeu"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2020-10-27T03:56:21.000Z","updated_at":"2023-04-08T07:10:39.000Z","dependencies_parsed_at":"2022-06-24T20:02:41.578Z","dependency_job_id":null,"html_url":"https://github.com/thadeu/branca-ruby","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fbranca-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fbranca-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fbranca-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fbranca-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thadeu","download_url":"https://codeload.github.com/thadeu/branca-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250251018,"owners_count":21399742,"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":[],"created_at":"2024-10-02T02:21:57.552Z","updated_at":"2025-04-22T13:45:14.294Z","avatar_url":"https://github.com/thadeu.png","language":"Ruby","funding_links":["https://github.com/sponsors/thadeu"],"categories":[],"sub_categories":[],"readme":"#  Branca Tokens for Ruby\n\nAuthenticated and encrypted API tokens using modern crypto.\n\n[![Gem Version](https://badge.fury.io/rb/branca-ruby.svg)](https://badge.fury.io/rb/branca-ruby)\n[![ci](https://github.com/thadeu/branca-ruby/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/thadeu/branca-ruby/actions/workflows/ruby.yml)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)\n\n## What?\n\n[Branca](https://github.com/thadeu/branca-ruby) 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/).\n\nIt is possible to use [Branca as an alternative to JWT](https://appelsiini.net/2017/branca-alternative-to-jwt/).\n\n## Install\n\nAdd this line to your application's Gemfile, Note that you also must have [libsodium](https://download.libsodium.org/doc/) installed.\n\n```ruby\ngem 'branca-ruby', '~\u003e 1.0.3'\n```\n\n## Configure\n\nYou must be configure `secret_key` and `ttl` using this.\n\n```ruby\nrequire 'branca'\n\nBranca.configure do |config|\n  config.secret_key = 'supersecretkeyyoushouldnotcommit'.b\n  config.ttl = 86_400 # in seconds\nend\n```\n\n## Usage\n\nThe payload of the token can be anything, like a simple string.\n\n### Encode\n\n```ruby\nBranca.encode('with string')\n\n# 1y48BiLKOcB4N8xjazwFpas3DwOovXzu6vtbiUr4bDAGLaVyFjIN5Xwz5p3qvNYsi5kWjk7ilgnS\n```\n\nor JSON stringified\n\n```ruby\nBranca.encode(JSON.generate({ permissions: [] }))\n\n# ATkzLjriA1ijbBcuZOJ1zMR0z5oVXDGDVjUWwrqJWszynAM4GLGiTwZnC6nUvtVIuavAVCMbwcsYqlYKejOI4\n```\n\nYou can also pass `secret_key` in runtime\n\n```ruby\nspecific_secret_key = SecureRandom.bytes(32)\npayload = \"sensitive data\"\ntoken = Branca.encode(payload, secret_key: specific_secret_key)\n```\n\nWill generate a token using `secret_key` in runtime instead global `secret_key`.\n\nSo, you can also pass `timestamp` to encode.\n\n```ruby\nBranca.encode('with string', Time.now.utc)\n\n# 1y48BiV0jaalTYiARPdbm52IKgGEhfwq8DlP9ulKBx8LMLFrjNKe88vIGIUxsWzybIwBhmVvIam5\n```\n\n### Decode\n\nIf you branca token isnt expired. You will receive something like this\n\n```ruby\ndecode = Branca.decode('1y48BiV0jaalTYiARPdbm52IKgGEhfwq8DlP9ulKBx8LMLFrjNKe88vIGIUxsWzybIwBhmVvIam5')\n\n# \u003cBranca::Decoder:0x00007fde4e3e6398 @message=\"with string\", @timestamp=2020-10-27 03:44:03 UTC\u003e\n\ndecode.message\n# \"with string\"\n```\n\nYou can also pass `secret_key` or `ttl` in runtime. For example:\n\n```ruby\nspecific_secret_key = SecureRandom.bytes(32)\ntmp_token = \"1y48BiV0jaalTYiARPdbm52IKgGEhfwq8DlP9ulKBx8LMLFrjNKe88vIGIUxsWzybIwBhmVvIam5\"\ntoken = Branca.decode(tmp_token, secret_key: specific_secret_key, ttl: 30)\n```\n\nWill decode token OR throw exception `DecodeError`\n\n## Exceptions\n\nToken is expired, you will receive exception `Branca::ExpiredTokenError`\n\nInvalid Version, you will receive exception `Branca::VersionError`\n\nWhen handle error, you will receive exception `Branca::DecodeError`\n\n## Contributing\n\nWe have a long list of valued contributors. Check them all at: https://github.com/thadeu/branca-ruby.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthadeu%2Fbranca-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthadeu%2Fbranca-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthadeu%2Fbranca-ruby/lists"}