1.0 release

[Geal]

Biscuit has been in development for 2 years now and is now used in production. Most of the initial roadmap is done (we still need to commission an audit).

So it will soon be time for a stable release and more public communication. Before that, I'd prefer that we clean things up a bit, there are design decisions that were left alone because fixing them would be breaking changes, but a 1.0 release would be the right time to take care of them (here I consider a breaking change anything that would invalidate how currently existing tokens would be validated).

This will be a meta issue for the work needed towards the major release:

• vocabulary issues:
  • Consider renaming larger #23 Consider renaming larger
  • Consider renaming In/NotInt #24 Consider renaming In/NotIn
  • nitpicking: renaming atom #52 renaming atom (not a breaking change, this would mainly change the API in libraries)
• Text syntax changes #54 text syntax changes (changes to the parser and printer)
• renaming In to Contains, removing NotIn #63 renaming In to Contains, removing NotIn
• Protobuf schema simplification #55 Protobuf schema simplification
• handling different format versions #59 adding a version field to the Protobuf format
• adding a revocation id in the common keys? #1 revocation identifiers
• new data types. There might be more of them we could add. I'd also like to consider whether constraints could be folded in the expression type (by making boolean expressions)
  • New atom type: Set #51 new atom type: set
  • supporting expressions #38 new atom type: expression
  • new type: boolean #61 new type: boolean
  • "deny" caveats vs "success caveats" #62 "deny" caveats vs "success caveats"
• Datalog evaluation:
  • specifying the regular expression features #50 specifying the regular expression features
  • allowing variables in constraints #47 allowing variables in constraints (need to decide if we allow it or not)
  • explicit run time limits for the datalog engine #53 explicit run time limits for the datalog engine
  • Using the symbol table for strings too #58 Using the symbol table for strings too
  • Datalog restrictions in blocks #56 Datalog restrictions in blocks

I'll make a branch of this repo with updated test samples once I've started that work on the Rust library.

see anything else we would need?
cc @divarvel @daeMOn63 @titanous @Keruspe @KannarFr @BlackYoup @meh

[Geal]

I'm starting the work in the 1.0 branch: https://github.com/CleverCloud/biscuit/tree/1.0
The samples directory will contain the samples generated at version 0 of the format in a v0/* subdirectory, while tokens generated with the new format and features will be in the v1/ folder, so we can test that new implementations also accept older tokens. I'll try to make one commit per feature to make it easier to update the implementations gradually.

[Geal]

The first example of handling multiple versions is done with #23:
Rust: biscuit-auth/biscuit-rust@01f1ba0
Java: CleverCloud/biscuit-java@2fc7c41
spec: 456549d

• new tokens generated with a schema at version 1 cannot be deserialized with the 0.9 release of the Rust library.
• new tokens generated with a schema at version 1 can be deserialized by the 1.0 branch of the Rust library
• old tokens generated with a schema at version 0 can be deserialized by the 1.0 branch, and it will convert it to its renamed types

This is a small change for now, renaming fields does not modify the structure significantly (the generated tokens are the same byte for byte)

[Geal]

Next, changing the protobuf format to use oneof (#55):
Rust: biscuit-auth/biscuit-rust@7a84336
Java: CleverCloud/biscuit-java@56b51b0
spec: 0ec07df

this changes the token's format, but not internal structures in the library, so there's no change to the feature set

[Geal]

Adding support for boolean type (#61):
spec: 0954e32
Rust: biscuit-auth/biscuit-rust@78a7657
Java: CleverCloud/biscuit-java@4675131

[Geal]

Adding support for the set type (#51):
spec: f5169d2
Rust: biscuit-auth/biscuit-rust@bb47508
Java: CleverCloud/biscuit-java@ae0d47b

[meh]

Any chance of getting . as allowed character for names in the language? At the moment I'm using the functional API for building caveats and rules but it gets very hairy very quickly.

[Geal]

@meh possible, but I'll have to check if it will be compatible with expressions. I'm planning more operations like string.len() etc

[meh]

Yeah that's why I didn't just go for it, I know it's a valuable symbol for extending the language.

For me it doesn't have to be a dot either, I just want an additional separator to _ so I can namespace things a bit, : would also work.

[Geal]

Expressions(#38 using the design outlined in #47 (comment)):
spec: ec99146
Rust: biscuit-auth/biscuit-rust@cd9495a
Java: CleverCloud/biscuit-java@b052be6

[Geal]

#62: Renaming "caveat" to "check", introduce "allow" and "deny" policies
#60: new syntax

spec: fea8c33
Rust: biscuit-auth/biscuit-rust@b4e2b06 and biscuit-auth/biscuit-rust@34107fc
Java: CleverCloud/biscuit-java@691cd95 and CleverCloud/biscuit-java@3f9cd09

[Geal]

With those changes, most of the work for 1.0 is done. now it needs a bit of polishing, like taking care of those issues:
biscuit-auth/biscuit-rust#29 Expressions: prevent panics & overflows
biscuit-auth/biscuit-rust#30 Expression: Negate: drop int support
biscuit-auth/biscuit-rust#31 Expressions: group feature

and making sure the specification is clear enough on the 1.0 changes

[Geal]

adding #63 to the list, since I'm changing the syntax for those operations

[Geal]

#63: renaming In to Contains, removing NotIn
Rust: biscuit-auth/biscuit-rust@6b3f901
Java: CleverCloud/biscuit-java@1ef7cac
spec: 01ea43f

[Geal]

now would be a good time to think of other operations that could be supported. Right now I'm thinking of adding .len() for strings, sets and byte arrays

[Geal]

I added revocation identifiers for #1:
spec: bf3f7b2
Rust version: biscuit-auth/biscuit-rust@451690c
CleverCloud/biscuit-java@7cf654c

[Geal]

more operations added to expressions:
spec 1c09f36
Rust: biscuit-auth/biscuit-rust@ada0c95

[Geal]

the 1.0 release is done 🥳