Datalog v3.3 support, rebased on the CI stabilization fixes (alternative to #178)

.gitignore

@@ -2,3 +2,4 @@ build
 .gobincache
 /go.work
 /go.work.sum
+.buf-plugins/

Makefile

@@ -1,6 +1,6 @@
 IMAGE ?= biscuit-go-test
 
-.PHONY: all build test test-local verify lint apidiff clean
+.PHONY: all build test test-local verify lint apidiff generate clean
 
 all: verify lint test
 
@@ -27,5 +27,9 @@ lint:
 apidiff:
 	./script/apidiff.sh -r main
 
+# Regenerates pb/ from the biscuit spec protobuf schema with buf.
+generate:
+	./script/generate.sh
+
 clean:
 	rm -rf build

README.md

@@ -9,6 +9,23 @@ biscuit-go is an implementation of [Biscuit](https://github.com/eclipse-biscuit/
 - [biscuit specification](https://github.com/eclipse-biscuit/biscuit)
 - [biscuit-rust](https://github.com/eclipse-biscuit/biscuit-rust) for some more technical details.
 
+## Specification compatibility
+
+This library currently accepts datalog `v3.0` to `v3.3` blocks (block versions `3` to `6`, see
+`MaxSchemaVersion`). Of datalog `v3.3`, `reject if`, the heterogeneous `==` and `!=`, `null`,
+the lazy `&&` and `||`, the `.all()` / `.any()` closures, arrays, maps, `.type()`,
+`extern::` function calls (registered with `WithExternFuncs`) and `.try_or()` are supported.
+
+The [specification sample suite](./samples) runs in CI: samples using block versions above
+`MaxSchemaVersion` are verified to be rejected and otherwise skipped, so they become active as
+support for each version lands.
+
+Tokens may be signed with Ed25519 or ECDSA on P-256 (`secp256r1`). `Biscuit.AuthorizerFrom`
+takes a `RootKeyProvider` (`RootKey`, `RootKeysByID`, or your own function) for either key type;
+`Biscuit.Authorizer` and `Biscuit.AuthorizerFor` still work with Ed25519 keys and are marked
+deprecated. The `datalog.World` methods take the origin of each fact and the origins each rule
+trusts, as in biscuit-rust.
+
 ## Usage
 
 #### Create a biscuit
@@ -56,7 +73,7 @@ if err != nil {
 // Attenuate the biscuit by appending a new block to it
 blockBuilder := b.CreateBlock()
 block, err := parser.FromStringBlockWithParams(`
-		check if resource($file), operation($permission), [{read}].contains($permission);`,
+		check if resource($file), operation($permission), {{read}}.contains($permission);`,
 	map[string]biscuit.Term{"read": biscuit.String("read")})
 if err != nil {
 	panic(fmt.Errorf("failed to parse block: %v", err))
@@ -75,6 +92,40 @@ if err != nil {
 // attenuatedToken is a []byte, representing an attenuated token
 ```
 
+#### Append a third-party block
+
+A third party signs a block for a token without seeing the token. Facts of that block are only
+visible to rules that trust the third party's key.
+
+```go
+// Token holder: build the request for the third party.
+request, err := b.ThirdPartyRequest()
+if err != nil {
+    panic(err)
+}
+requestBytes, _ := request.Serialize()
+
+// Third party: sign a block for that request with its own key.
+request, _ = biscuit.UnmarshalThirdPartyBlockRequest(requestBytes)
+blockBuilder := biscuit.NewThirdPartyBlockBuilder()
+blockBuilder.AddFact(biscuit.Fact{Predicate: biscuit.Predicate{Name: "group", IDs: []biscuit.Term{biscuit.String("admin")}}})
+contents, err := request.CreateBlock(thirdPartyPrivateKey, blockBuilder)
+if err != nil {
+    panic(err)
+}
+contentsBytes, _ := contents.Serialize()
+
+// Token holder: append the signed block.
+contents, _ = biscuit.UnmarshalThirdPartyBlockContents(contentsBytes)
+b, err = b.AppendThirdPartyBlock(nil, thirdPartyPublicKey, contents)
+if err != nil {
+    panic(err)
+}
+
+// A check trusting the third party's key sees group("admin"):
+//   check if group("admin") trusting ed25519/<hex of thirdPartyPublicKey>
+```
+
 #### Verify a biscuit
 
 ```go
@@ -83,7 +134,7 @@ if err != nil {
     panic(fmt.Errorf("failed to deserialize token: %v", err))
 }
 
-authorizer, err := b.Authorizer(publicRoot)
+authorizer, err := b.AuthorizerFrom(biscuit.RootKey(publicRoot))
 if err != nil {
     panic(fmt.Errorf("failed to verify token and create authorizer: %v", err))
 }