{"id":28122629,"url":"https://github.com/eclipse-biscuit/biscuit-go","last_synced_at":"2025-06-17T04:37:58.251Z","repository":{"id":37038190,"uuid":"230325508","full_name":"eclipse-biscuit/biscuit-go","owner":"eclipse-biscuit","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-08T15:30:34.000Z","size":614,"stargazers_count":81,"open_issues_count":22,"forks_count":23,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-14T07:52:30.819Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-biscuit.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":"2019-12-26T20:40:23.000Z","updated_at":"2025-05-06T17:14:16.000Z","dependencies_parsed_at":"2024-06-18T22:49:30.242Z","dependency_job_id":"01fe80f2-2bbb-412b-b5d0-b8d1128969d7","html_url":"https://github.com/eclipse-biscuit/biscuit-go","commit_stats":{"total_commits":180,"total_committers":14,"mean_commits":"12.857142857142858","dds":0.6055555555555556,"last_synced_commit":"61386fc9e1be296472c2cc63f42a87f9b227ae51"},"previous_names":["flynn/biscuit-go","eclipse-biscuit/biscuit-go","biscuit-auth/biscuit-go"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-biscuit%2Fbiscuit-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-biscuit%2Fbiscuit-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-biscuit%2Fbiscuit-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-biscuit%2Fbiscuit-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-biscuit","download_url":"https://codeload.github.com/eclipse-biscuit/biscuit-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101543,"owners_count":22014909,"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":"2025-05-14T08:14:11.345Z","updated_at":"2025-06-17T04:37:58.232Z","avatar_url":"https://github.com/eclipse-biscuit.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# biscuit-go\n\nbiscuit-go is an implementation of [Biscuit](https://github.com/biscuit-auth/biscuit) in Go. It aims to be fully compatible with other existing implementations, so that tokens issued by, for example, the Rust version, could be validated by this library and vice versa.\n\n## Documentation and specifications\n\n- [biscuit website](https://www.biscuitsec.org) for documentation and examples\n- [biscuit specification](https://github.com/biscuit-auth/biscuit)\n- [biscuit-rust](https://github.com/biscuit-auth/biscuit-rust) for some more technical details.\n\n## Usage\n\n#### Create a biscuit\n```go\nrng := rand.Reader\npublicRoot, privateRoot, _ := ed25519.GenerateKey(rng)\n\nauthority, err := parser.FromStringBlockWithParams(`\n\tright(\"/a/file1.txt\", {read});\n\tright(\"/a/file1.txt\", {write});\n\tright(\"/a/file2.txt\", {read});\n\tright(\"/a/file3.txt\", {write});\n`, map[string]biscuit.Term{\"read\": biscuit.String(\"read\"), \"write\": biscuit.String(\"write\")})\n\nif err != nil {\n\tpanic(fmt.Errorf(\"failed to parse authority block: %v\", err))\n}\n\nbuilder := biscuit.NewBuilder(privateRoot)\nbuilder.AddBlock(authority)\n\nb, err := builder.Build()\nif err != nil {\n\tpanic(fmt.Errorf(\"failed to build biscuit: %v\", err))\n}\n\ntoken, err := b.Serialize()\nif err != nil {\n\tpanic(fmt.Errorf(\"failed to serialize biscuit: %v\", err))\n}\n\n// token is now a []byte, ready to be shared\n// The biscuit spec mandates the use of URL-safe base64 encoding for textual representation:\nfmt.Println(base64.URLEncoding.EncodeToString(token))\n```\n\n#### Attenuate a biscuit\n\n```go\nb, err = biscuit.Unmarshal(token)\nif err != nil {\n    panic(fmt.Errorf(\"failed to deserialize biscuit: %v\", err))\n}\n\n// Attenuate the biscuit by appending a new block to it\nblockBuilder := b.CreateBlock()\nblock, err := parser.FromStringBlockWithParams(`\n\t\tcheck if resource($file), operation($permission), [{read}].contains($permission);`,\n\tmap[string]biscuit.Term{\"read\": biscuit.String(\"read\")})\nif err != nil {\n\tpanic(fmt.Errorf(\"failed to parse block: %v\", err))\n}\nblockBuilder.AddBlock(block)\n\nattenuatedBiscuit, err := b.Append(rng, blockBuilder.Build())\nif err != nil {\n    panic(fmt.Errorf(\"failed to append: %v\", err))\n}\nattenuatedToken, err := b.Serialize()\nif err != nil {\n    panic(fmt.Errorf(\"failed to serialize biscuit: %v\", err))\n}\n\n// attenuatedToken is a []byte, representing an attenuated token\n```\n\n#### Verify a biscuit\n\n```go\nb, err := biscuit.Unmarshal(token)\nif err != nil {\n    panic(fmt.Errorf(\"failed to deserialize token: %v\", err))\n}\n\nauthorizer, err := b.Authorizer(publicRoot)\nif err != nil {\n    panic(fmt.Errorf(\"failed to verify token and create authorizer: %v\", err))\n}\n\nauthorizerContents, err := parser.FromStringAuthorizerWithParams(`\n\tresource({res});\n\toperation({op});\n\tallow if right({res}, {op});\n\t`, map[string]biscuit.Term{\"res\": biscuit.String(\"/a/file1.txt\"), \"op\": biscuit.String(\"read\")})\nif err != nil {\n\tpanic(fmt.Errorf(\"failed to parse authorizer: %v\", err))\n}\nauthorizer.AddAuthorizer(authorizerContents)\n\nif err := authorizer.Authorize(); err != nil {\n    fmt.Printf(\"failed authorizing token: %v\\n\", err)\n} else {\n    fmt.Println(\"success authorizing token\")\n}\n```\n\n### Using biscuit-go grammar\n\nbiscuit-go provides a datalog parser, allowing to input datalog elements as plain strings, along with support for parameter substitution. \n\nSee [GRAMMAR reference](./parser/GRAMMAR.md) for the complete syntax.\n\nThe parsers supports parsing whole blocks (containing several facts, rules and checks), whole authorizers (containing several facts, rules, checks and policies), as well as individual facts, rules, checks and policies. Parsing and adding elements individually is especially useful when doing so from inside a loop. \n\nThe `parser` module provides convenient helpers for parsing a string into datalog elements (`FromStringFact`, `FromStringRule`, `FromStringCheck`, `FromStringPolicy`, `FromStringBlock`, `FromStringAuthorizer`, for static datalog snippets, and their counterparts allowing parameter substitution: `FromStringFactWithParams`, `FromStringRuleWithParams`, `FromStringCheckWithParams`, `FromStringPolicyWithParams`, `FromStringBlockWithParams`, `FromStringAuthorizerWithParams`).\n\n#### Panic on parsing errors\n\nIn most cases, `FromString*` functions will let you handle errors. If you do not wish to handle errors and instead crash on errors (for instance in one-off scripts), it can be done by first creating a parser instance, and using the `panic`-y functions:\n\n```go\np := parser.New()\nb := biscuit.NewBuilder(privateRoot)\n\nb.AddBlock(p.Must().Block(`\n\tright(\"/a/file1.txt\", {read});\n\tright(\"/a/file1.txt\", {write});\n\tright(\"/a/file2.txt\", {read});\n\tright(\"/a/file3.txt\", {write});\n`, map[string]biscuit.Term{\"read\": biscuit.String(\"read\"), \"write\": biscuit.String(\"write\")}))\n\nb.AddFact(p.Must().Fact(`resource({res})`, map[string]biscuit.Term{\"res\": biscuit.String(\"/a/file1.txt\")}))\nb.AddRule(p.Must().Rule(`\n    can_read($file) \n        \u003c- resource($file)\n        $file.starts_with(\"/a/\")\n`, nil))\n```\n\nDo note that these helpers take two arguments: a datalog snippet and a parameters map. If the datalog snippet does not contain parameters, `nil` can be passed as the second argument.\n\n## Examples\n\n- [example_test.go](./example_test.go) for a simple use case\n- [experiments folder](./experiments) for more advanced or specific use cases examples.\n\n## License\n\nLicensed under [Apache License, Version 2.0](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-biscuit%2Fbiscuit-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-biscuit%2Fbiscuit-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-biscuit%2Fbiscuit-go/lists"}