{"id":22282046,"url":"https://github.com/return/branca","last_synced_at":"2025-05-16T08:06:09.724Z","repository":{"id":33523359,"uuid":"138415862","full_name":"return/branca","owner":"return","description":"Authenticated and encrypted API tokens written in Rust. A secure JWT alternative.","archived":false,"fork":false,"pushed_at":"2025-03-18T05:28:34.000Z","size":77,"stargazers_count":62,"open_issues_count":5,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-13T20:15:51.631Z","etag":null,"topics":["aead","authenticated-encryption","branca","cryptography","jwt","rust","token-based-authentication","xchacha20-poly1305"],"latest_commit_sha":null,"homepage":"https://branca.io","language":"Rust","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/return.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-23T16:15:07.000Z","updated_at":"2025-04-07T08:25:09.000Z","dependencies_parsed_at":"2024-06-21T13:09:33.274Z","dependency_job_id":"51d7197d-b47d-47d6-9c2f-e0c3899d13ce","html_url":"https://github.com/return/branca","commit_stats":{"total_commits":90,"total_committers":7,"mean_commits":"12.857142857142858","dds":"0.33333333333333337","last_synced_commit":"282b7eca4d8da1bcb3666d3dd726dc8785f87ffe"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/return%2Fbranca","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/return%2Fbranca/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/return%2Fbranca/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/return%2Fbranca/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/return","download_url":"https://codeload.github.com/return/branca/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"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":["aead","authenticated-encryption","branca","cryptography","jwt","rust","token-based-authentication","xchacha20-poly1305"],"created_at":"2024-12-03T16:24:52.069Z","updated_at":"2025-05-16T08:06:04.714Z","avatar_url":"https://github.com/return.png","language":"Rust","readme":"# Branca - A secure alternative token format to JWT\n\n|Crate|Documentation|License|CI\n|:---:|:-----------:|:-----------:|:-----------:|\n|[![Crates.io][crates-badge]][crates-url]|[![Docs][doc-badge]][doc-url]|[![License][license-badge]][license-url]|[![CI][ci-badge]][ci-url]\n\n[crates-badge]: https://img.shields.io/crates/v/branca.svg\n[crates-url]: https://crates.io/crates/branca\n[doc-badge]: https://docs.rs/branca/badge.svg\n[doc-url]: https://docs.rs/branca\n[license-badge]: https://img.shields.io/badge/License-MIT-brightgreen.svg\n[license-url]: https://github.com/return/branca/blob/master/LICENSE\n[ci-badge]: https://github.com/return/branca/workflows/CI/badge.svg\n[ci-url]: https://github.com/return/branca/actions\n\nBranca is a secure alternative token format to JWT. This implementation is written in pure Rust and uses the XChaCha20-Poly1305 AEAD (Authenticated Encryption with Associated Data) stream cipher for generating authenticated and encrypted tamper-proof tokens. More information about the Branca token specification can be found here in [branca-spec.](https://github.com/tuupola/branca-spec/blob/master/README.md)\n\n# Security\n\n_NOTE: Branca uses Orion for its cryptographic primitives and due to Orion not receiving any formal security audit, the same security risks that Orion has also applies to this Branca implementation if one uses it in production. For a better understanding about the security risks involved, see the Orion [wiki](https://github.com/orion-rs/orion/wiki/Security)._\n\n**⚠️ Use at your own risk. ⚠️**\n\n# Requirements\n\n* Rust 1.52\n* Cargo\n\n# Installation\n\nAdd this line into your Cargo.toml under the dependencies section:\n\n```toml\n[dependencies]\nbranca = \"^0.10.0\"\ngetrandom = \"^0.2.3\"\n```\n\nThen you can import the crate into your project with these lines:\n```rust\nextern crate getrandom;\nextern crate branca;\nuse branca::{Branca, encode, decode};\n```\n\n# Example Usage\n\nThe simplest way to use this crate is to use `Branca::new()` in this example below:\n\n```rust\n    let mut key = [0u8; 32];\n    getrandom::getrandom(\u0026mut key).unwrap();\n\n    let mut token = Branca::new(\u0026key).unwrap();\n    let ciphertext = token.encode(b\"Hello World!\").unwrap();\n\n    let payload = token.decode(ciphertext.as_str(), 0).unwrap();\n    println!(\"{}\", payload); // \"Hello World!\"\n```\n\nSee more examples of setting fields in the [Branca struct](https://docs.rs/branca/) and in the [Documentation section.](https://docs.rs/branca/0.8.0/branca/struct.Branca.html)\n\n## Direct usage without Branca builder.\n### Encoding:\n```rust\nlet mut key = [0u8; 32];\ngetrandom::getrandom(\u0026mut key).unwrap();\n\nlet message = b\"Hello world!\";\nlet timestamp = 123206400;\nlet branca_token = encode(message, \u0026key, timestamp).unwrap();\n\n// branca_token = 875GH233T7.......\n```\n\n### Decoding:\n```rust\nlet ciphertext = branca_token.as_str();\nlet ttl = 0; // The ttl can be used to determine if the supplied token has expired or not.\nlet decoded = decode(ciphertext, \u0026key, ttl);\n\nif decoded.is_err() {\n    // Error\n} else {\n    let msg = decoded.unwrap(); \n    // msg = \"Hello world!\"\n}\n```\n\n## Encode/Decode arbitrary data structures with Serde.\nSince Branca is able to work with any format of data in the payload, it is possible for the payload to be anything from a JSON object, plaintext, raw bytes, protocol buffers or even a JWT.\n\nHere is an example of using Branca to encode/decode a typical JSON object with serde_json.\n\nAdd the following into your Cargo.toml file:\n```toml\n[dependencies]\nbranca = \"^0.10.0\"\nserde_json = \"^1.0\"\nserde_derive = \"1.0.97\"\n\n```\n\n```rust\n#[macro_use]\nextern crate serde_json;\n#[macro_use]\nextern crate serde_derive;\nextern crate branca;\nextern crate getrandom;\n\nuse branca::{encode, decode};\n\n#[derive(Serialize, Deserialize, Debug)]\nstruct User {\n    user: String,\n    scope: Vec\u003cString\u003e,\n}\n\nfn main(){\n\n    let message = json!({\n        \"user\" : \"someone@example.com\",\n        \"scope\":[\"read\", \"write\", \"delete\"],\n    }).to_string();\n\n    let mut key = [0u8; 32];\n    getrandom::getrandom(\u0026mut key).unwrap();\n    \n    let mut token = Branca::new(\u0026key).unwrap();\n    \n    // Encode Message\n    let branca_token = token.encode(message.as_bytes()).unwrap();\n    \n    // Decode Message\n    let payload = token.decode(branca_token.as_str(), 0).unwrap();\n\n    let json: User = serde_json::from_str(payload.as_str()).unwrap();\n\n    println!(\"{}\", branca_token);\n    println!(\"{}\", payload);\n    println!(\"{:?}\", json);\n}\n```\n\nBranca uses [Orion](https://github.com/orion-rs/orion) to generate secure random nonces when using the `encode()` and builder methods. By default, Branca does not allow setting the nonce directly since that there is a risk that it can be reused by the user which is a foot-gun.\n\nThe nonce generated **must be 24 bytes in length.** Keys **must be 32 bytes in length.**\n\n# Building\n`cargo build`\n\n# Testing\n`cargo test`\n\n# Contributing\nContributions and patches are welcome! Fork this repository, add your changes and send a PR.\n\nBefore you send a PR, make sure you run `cargo test` first to check if your changes pass the tests.\n\nIf you would like to fix a bug or add a enhancement, please do so in the issues section and provide a short description about your changes.\n\n# License\nMIT","funding_links":[],"categories":["Libraries"],"sub_categories":["Web programming"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freturn%2Fbranca","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freturn%2Fbranca","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freturn%2Fbranca/lists"}