{"id":16320324,"url":"https://github.com/tuupola/branca-php","last_synced_at":"2025-08-01T18:08:02.625Z","repository":{"id":22936971,"uuid":"97711882","full_name":"tuupola/branca-php","owner":"tuupola","description":"Authenticated and encrypted API tokens using modern crypto","archived":false,"fork":false,"pushed_at":"2022-05-08T14:42:38.000Z","size":73,"stargazers_count":53,"open_issues_count":2,"forks_count":6,"subscribers_count":5,"default_branch":"2.x","last_synced_at":"2025-02-27T10:36:01.115Z","etag":null,"topics":["api","jwt","token-authentication","xchacha20-poly1305"],"latest_commit_sha":null,"homepage":"","language":"PHP","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":"CONTRIBUTING.md","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-19T12:07:54.000Z","updated_at":"2025-01-27T11:32:27.000Z","dependencies_parsed_at":"2022-08-08T16:15:14.362Z","dependency_job_id":null,"html_url":"https://github.com/tuupola/branca-php","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fbranca-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuupola","download_url":"https://codeload.github.com/tuupola/branca-php/tar.gz/refs/heads/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243818195,"owners_count":20352629,"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:44:00.184Z","updated_at":"2025-03-16T14:30:58.726Z","avatar_url":"https://github.com/tuupola.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"#  Branca Tokens for PHP\n\nAuthenticated and encrypted API tokens using modern crypto.\n\n[![Latest Version](https://img.shields.io/packagist/v/tuupola/branca.svg?style=flat-square)](https://packagist.org/packages/tuupola/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-php/Tests/2.x?style=flat-square)](https://github.com/tuupola/branca-php/actions)\n[![Coverage](https://img.shields.io/codecov/c/github/tuupola/branca-php.svg?style=flat-square)](https://codecov.io/github/tuupola/branca-php)\n\n\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/).\n\nIt is possible to use [Branca as an alternative to JWT](https://appelsiini.net/2017/branca-alternative-to-jwt/). There is also an [authentication middleware](https://github.com/tuupola/branca-middleware) for frameworks which support PSR-7 doublepass or PSR-15 standards.\n\n## Install\n\nInstall the library using [Composer](https://getcomposer.org/).\n\n\n``` bash\n$ composer require tuupola/branca\n```\n\nThis branch requires PHP 7.2 or up. The older 1.x branch supports also PHP 5.6, 7.0 and 7.1.\n\n``` bash\n$ composer require \"tuupola/branca:^1.0\"\n```\n\n## Usage\n\nToken payload can be any arbitrary data such as string containing an email\naddress. You also must provide a 32 byte secret key. The key is used for encrypting the payload.\n\n```php\nuse Branca\\Branca;\n\n$key = random_bytes(32);\n$branca = new Branca($key);\n\n$payload = \"tuupola@appelsiini.net\";\n$token = $branca-\u003eencode($payload);\n/* hGgg0dPSseaUPZqGloWlDGb2i8hb6iamFBIQaatgYDRhEuaXyByaX0nzmyQk1WYAuSBEMWpB20Z1dENLFItwf1 */\n\n$decoded = $branca-\u003edecode($token);\n/* tuupola@appelsiini.net */\n```\n\nSometimes you might prefer JSON.\n\n```php\nuse Branca\\Branca;\n\n$key = random_bytes(32);\n$branca = new Branca($key);\n\n$payload = json_encode([\"scope\" =\u003e [\"read\", \"write\", \"delete\"]]);\n$token = $branca-\u003eencode($payload);\n\n/*\n5R7p5pC1gU5kfVuBUzhl43Ndh4HLT9fxAHrhN1zNRivTuehY8zYYzrVZ8C6d6VcNLfCk3EUgBwwW6kIk0wm32O34OFIYz5LnOIezwcV2Xsfc\n*/\n\n$decoded = $branca-\u003edecode($token);\n$array = json_decode($decoded, true);\n\n/*\nArray\n(\n    [scope] =\u003e Array\n        (\n            [0] =\u003e read\n            [1] =\u003e write\n            [2] =\u003e delete\n        )\n\n)\n*/\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```php\nuse Branca\\Branca;\nuse MessagePack\\MessagePack;\nuse MessagePack\\Packer;\nuse MessagePack\\BufferUnpacker;\n\n$key = random_bytes(32);\n$branca = new Branca($key);\n\n$payload = (new Packer)-\u003epack([\"scope\" =\u003e [\"read\", \"write\", \"delete\"]]);\n$token = $branca-\u003eencode($payload);\n\n/*\n3iJt0CjqTRh3FGuAf0DHEmhULFIbPVInjguWIkmyCm7RMps5BMJZKa1KwZMN0z58IpPeCxdjoTdkurn9pl0YNrxAQfg3deP0\n*/\n\n$decoded = $branca-\u003edecode($token);\n$unpacked = (new BufferUnpacker($decoded))-\u003eunpack();\nprint_r($unpacked);\n\n/*\nArray\n(\n    [scope] =\u003e Array\n        (\n            [0] =\u003e read\n            [1] =\u003e write\n            [2] =\u003e delete\n        )\n\n)\n*/\n```\n\n## Timestamp\n\nBranca token includes a timestamp when it was created. When decoding you can optionally pass a `ttl` parameter. Value is passed in seconds. Below example throws en exception if token is older than 60 minutes.\n\n```php\nuse Branca\\Branca;\n\n$key = hex2bin(\"73757065727365637265746b6579796f7573686f756c646e6f74636f6d6d6974\");\n$branca = new Branca($key);\n\n$token = \"1jJDJOEeG2FutA8g7NAOHK4Mh5RIE8jtbXd63uYbrFDSR06dtQl9o2gZYhBa36nZHXVfiGFz\";\n\nprint $branca-\u003etimestamp($token); /* 123206400 */\n\ntry {\n    $decoded = $branca-\u003edecode($token, 3600);\n} catch (RuntimeException $exception) {\n    print $exception-\u003egetMessage(); /* Token is expired */\n}\n```\n\n## Testing\n\nYou can run tests either manually or automatically on every code change. Automatic tests require [entr](http://entrproject.org/) to work.\n\n``` bash\n$ make test\n```\n``` bash\n$ brew install entr\n$ make watch\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-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuupola%2Fbranca-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuupola%2Fbranca-php/lists"}