Go package for working with Macaroons and the superfly/macaroon package in an SFO Museum context.
Documentation is incomplete. For the time being please consult the tests and in particular caveats/caveats_test.go to get started.
If you don't know what "macaroons" are then you should start by reading the following documents:
- Macaroons Escalated Quickly
- Integral Principles of the Structural Dynamics of Macaroons
- Third Party Discharge Protocol
This package exposes tools and code to test using the parts of the superfly/macaroon package that aren't (don't seem to be) specific to the Fly.io service. It is being released as-is in the spirit of generousity and because it might be helpful or interesting to others. Suggestions, bug-fixes and (gentle) cluebats are welcome.
Importantly, the superfly/macaroon package comes with the following warning:
We don't think you should use any of this code; it's shrink-wrapped around some peculiar details of our production network, and the data model is Fly-specific. But if it's an interesting read, that's great too.
So, buyer beware. I have gotten basic custom (non-Fly.io) caveat creation and testing both locally and with third-party discharges working so that bodes well for the idea of common code not bound to any one service but it's early days.
$> ./bin/new-macaroon -h
Generate a new Macaroon token and emit it as a base64-encoded string.
Usage:
./bin/new-macaroon [options]
-duration string
A valid ISO8061 duration time used to set the time-to-live for the Macaroon token. (default "PT10M")
-location string
The 'location' string to associate with the Macaroon token. (default "sfomuseum.org")
-signing-key-uri string
A valid sfomuseum/runtimevar URI that contains the signing key for the Macaroon token.
-urlescape
A boolean flag to URL escape the final base64-encoded Macaroon token.
For example:
$> ./bin/new-macaroon -signing-key-uri file:https:///usr/local/sfomuseum/go-macaroon/fixtures/signing.key
lJPAxBDUE507S463PTwmomfDUVIlwq1zZm9tdXNldW0ub3JnkgSSzmXFQLPOZcVDC8Qgp8rB2CYGZ0o6El7wOQtnfcgMB80FvT3Vv2If5Pj6hss=
It is important to note that this produces a Macaroon token with nothing more than a "time-to-live" caveat and it is up to you to update it with additional caveats as necessary.
See also:
Append a "ensure account" caveat to discharge with a third-party to a Macaroon token and emit it as a base64-encoded string.
$> ./bin/tp-ensure-account -h
Append a "ensure account" caveat to discharge with a third-party to a Macaroon token and emit it as a base64-encoded string.
Usage:
./bin/tp-ensure-account [options]
-account-id int
The account ID to assign to the third-party caveat.
-encryption-key-uri string
A valid sfomuseum/runtimevar URI that contains the shared encryption key for the third-party caveat.
-location string
The 'location' string to associate with the Macaroon token. (default "")
-macaroon string
A base64-encoded string containing the Macaroon token to update. If the value is '-' then data will be read from STDIN.
-urlescape
A boolean flag to URL unescape the base64-encoded Macaroon token being updated.
-urlunescape
A boolean flag to URL escape the final base64-encoded Macaroon token.
For example (reading data from STDIN):
$> ./bin/new-macaroon \
-signing-key-uri file:https:///usr/local/sfomuseum/go-macaroon/fixtures/signing.key \
-duration PT30S \
| \
./bin/tp-ensure-account -encryption-key-uri file:https:///usr/local/sfomuseum/go-macaroon/fixtures/3p-encryption.key \
-location example.com \
-macaroon -
lJPAxBA2ZfumuM+3ye8ksRwEfMqKwq1zZm9tdXNldW0ub3JnlASSzmXFQwfOZcVDJQuTq2V4YW1wbGUuY29txDxfN+zomqLyS1MH2w5OkYRKPFnz7d6UwLBbbYiOLdd9qIhlnzz+B9HuuzIYQcqjlEjDpFo+2kzNTALYxrzETp0uDb6u3XHQ5nx4xDM8I6zNOr9skiIUpLWlGQWc32rL56ILzSBSfIUvVkngOEuyG/bY58s2KQltpggV4IsGNwE4IhyjWB+zns8fW8C09MQghGB+25sWgzazuqI0sLNAd4in5pUves6nT179GjL1HY0=
See also
Generate a random base64-encoded Macaroon signing key.
$> ./bin/signing-key -h
Generate a random base64-encoded Macaroon signing key.
Usage:
./bin/signing-key
For example:
$> ./bin/signing-key
SLDGG+DU9wAXQz5l1bYmymEhyRpEyK1f4wrXs58N4iw=
Generate a random base64-encoded Macaroon encyption key.
$> ./bin/encryption-key -h
Generate a random base64-encoded Macaroon encyption key.
Usage:
./bin/encryption-key
For example:
$> ./bin/encryption-key
hMonc06ho508zB+Hn3N70jg7kkKvJu3IrDZxJxcgSrQ=