Ecosyste.ms: Packages

proxy.golang.org : github.com/superfly/macaroon

Package macaroon defines Fly.io's Macaroon token format. A Macaroon is a flexible bearer token based on the idea of "caveats". A caveat limits what a Macaroon can do. A blank Macaroon might represent an all-access credential; a caveat layered onto that Macaroon might transform it into a read-only credential; a further caveat might create a credential that can only read, and only to a particular file. The basic laws of Macaroons: An ordinary caveat is checked by looking at the request and the caveat and seeing if they match up. For instance, a Macaroon with an `Operation=read` caveat can be checked by looking to see if the request it accompanies is trying to write. Simple stuff. A "third party (3P)" caveat works differently. 3P caveats demand that some other named system validate the request. Users extract a little ticket from the 3P caveat and hands it to the third party, along with anything else the third party might want. That third party resolves the caveat by generating a "discharge Macaroon", which is a whole 'nother token, tied cryptographically to the original 3P caveat. The user then presents both the original Macaroon and the discharge Macaroon with their request. For instance: most Fly.io Macaroons require a logged-in user (usually a member of a particular organization). We express that with a 3P caveat pointing to our authentication endpoint. That endpoint checks to see who you're logged in as, and produces an appropriate discharge, which accompanies the original Macaroon and (in effect) attests to you being logged in. All the cryptography in Macaroons is symmetric; there are no public keys. We use SHA256 as our hash, and HMAC-SHA256 as our authenticator. We use ChaCha20/Poly1305 as the AEAD for third-party caveats. Our Macaroons are simple structs encoded with MessagePack. We use a binary encoding both for performance and to to encode deterministically, for cryptography. MessagePack is extraordinarily simple and you can reason about this code as if simply used JSON. A typical Fly.io request from a user will require multiple tokens; the original "root" token, which says what you're allowed to do, and tokens to validate 3P caveats (usually at least an authentication token). To represent that bundle of tokens, we define a `FlyV1` HTTP `Authorization` header scheme, which is simply a comma-separated set of Base64'd Macaroons. See the `flyio` package for more details. Create a token with New. Add caveats ("attenuating" it) with Macaroon.Add. Sign and encode the token with Macaroon.Encode. Decode a binary token with Decode. Verify the signatures on a token with Macaroon.Verify. Note that the whole token has not been checked at this point! Check the caveats (the result of Macaroon.Verify) with CaveatSet.Validate.

Registry - Source - Documentation - JSON
purl: pkg:golang/github.com/superfly/macaroon
License: Apache-2.0
Latest release: 5 months ago
First release: 9 months ago
Namespace: github.com/superfly
Stars: 1 on GitHub
Forks: 0 on GitHub
Docker dependents: 4
Docker downloads: 11,894
See more repository details: repos.ecosyste.ms
Last synced: 1 day ago

• Readme
• Versions 18
• Dependent Packages 0
• Maintainers 0