Example API

[Geal]

The logic language we're exploring in #11 can already be useful, but it might be better to have an easy to use API that covers most use cases, and then allows people with more specific needs to use the low level tools. (the example is a bit rust-y but I'm also thinking of other languages).

Basic API:

// generate a root key pair
create_key() -> KeyPair
// generate root token
create_token(root_key: KeyPair, authority: [Facts], caveats: [Caveats]) -> Token
// derive a new token
derive_token(key: &KeyPair, caveats: &[Caveats]) -> Token
// verify
verify_token(root_public_key: &PublicKey, token: &Token, ambient: [Facts], query: Query) -> bool

Generating authority facts?

Generating a caveat?

generating a query?

[Geal]

I tried some ideas around an API to make the blocks and the verifier here: https://github.com/CleverCloud/biscuit/blob/824db991d4b6919ebf0fce6d5c520c9ee7deaf4c/code/biscuit-poc/src/lib.rs#L418-L529

It looks like a good idea to have some default ways to represent rights and some constraints. Those will not bloat the resulting tokens, since their symbols will be part of the default symbol table.
Which common patterns should be supported right away? Right now I added things like expiration dates and revocation ids. I'm not sure they should be part of the specification, but they should be recommended in most implementations, at least.

[Geal]

I added more information about the API in https://github.com/CleverCloud/biscuit/blob/master/DESIGN.md#implementation
And some ideas about a higher level API in https://github.com/CleverCloud/biscuit/blob/master/DESIGN.md#caveat-creation-api
That high level API is quite nice to use in tests, so if we find some common patterns it should be nice to have them baked in.

[clementd-fretlink]

I like the add fact / add rule interface. I'm a bit more reserved about the resource / right / prefix thingy. While they map quite neatly to rest resources, I wonder how it would feel for higher-level concerns.

I guess the best thing would be to compile a list of use cases and see how the proposed APIs would fit.

[Geal]

do you have some interesting caveats to share from your macaroons, so I can see if they fit with this model?

[clementd-fretlink]

I'm gathering a few use cases.

[Geal]

the API has now evolved a lot in the Rust and Java implementations, and the specification will be updated to follow that feedback