feat: add third-party block support

Add methods to create and inspect third party blocks:
- `Biscuit::append_third_party` for creating biscuits with third party
  blocks
- `Biscuit::external_key` for retrieving external keys from blocks
- Add unit tests covering third party block functionality

Author: Naccomy

biscuit_test.py

@@ -463,3 +463,28 @@ def test(left, right):
     policy = authorizer.build_unauthenticated().authorize()
     assert policy == 0
 
+def test_append_third_party():
+    root_kp = KeyPair()
+    biscuit_builder = BiscuitBuilder("user({id})", { 'id': "1234" })
+    biscuit = biscuit_builder.build(root_kp.private_key)
+
+    third_party_kp = KeyPair()
+    third_party_block = BlockBuilder("external_fact({fact})", { 'fact': "56" })
+    biscuit_with_third_party_block = biscuit.append_third_party(third_party_kp, third_party_block)
+
+    assert repr(biscuit_with_third_party_block.block_external_key(1)) == repr(third_party_kp.public_key)
+
+def test_read_third_party_facts():
+    root_kp = KeyPair()
+    biscuit_builder = BiscuitBuilder("user({id})", { 'id': "1234" })
+    biscuit = biscuit_builder.build(root_kp.private_key)
+
+    third_party_kp = KeyPair()
+    third_party_block = BlockBuilder("external_fact({fact})", { 'fact': "56" })
+    biscuit_with_third_party_block = biscuit.append_third_party(third_party_kp, third_party_block)
+
+    authorizer  = AuthorizerBuilder("allow if true").build(biscuit_with_third_party_block)
+    rule = Rule(f"ext_fact($fact) <- external_fact($fact) trusting {third_party_kp.public_key}")
+    facts = authorizer.query(rule)
+
+    assert facts[0].terms[0] == "56"

src/lib.rs

@@ -397,6 +397,36 @@ impl PyBiscuit {
             .map(PyBiscuit)
     }
 
+    /// Create a new `Biscuit` by appending a third party attenuation block
+    ///
+    /// :param kp: keypair used to sign the block
+    /// :type kp: KeyPair
+    /// :param block: a builder for the new block
+    /// :type block: BlockBuilder
+    /// :return: the attenuated biscuit
+    /// :rtype: Biscuit
+    pub fn append_third_party(
+        &self,
+        kp: &PyKeyPair,
+        block: &PyBlockBuilder,
+    ) -> PyResult<PyBiscuit> {
+        let third_party_block = self
+            .0
+            .third_party_request()
+            .and_then(|req| {
+                req.create_block(
+                    &kp.private_key().0,
+                    block.0.clone().expect("builder already consumed"),
+                )
+            })
+            .map_err(|e| BiscuitBuildError::new_err(e.to_string()))?;
+
+        self.0
+            .append_third_party(kp.public_key().0, third_party_block)
+            .map_err(|e| BiscuitBuildError::new_err(e.to_string()))
+            .map(PyBiscuit)
+    }
+
     /// The revocation ids of the token, encoded as hexadecimal strings
     #[getter]
     pub fn revocation_ids(&self) -> Vec<String> {
@@ -407,6 +437,21 @@ impl PyBiscuit {
             .collect()
     }
 
+    /// Get the external key of a block if it exists
+    ///
+    /// :param index: the block index
+    /// :type index: int
+    /// :return: the public key if it exists
+    /// :rtype: str | None
+    pub fn block_external_key(&self, index: usize) -> PyResult<Option<PyPublicKey>> {
+        let opt_key = self
+            .0
+            .block_external_key(index)
+            .map_err(|e| BiscuitBlockError::new_err(e.to_string()))?;
+
+        Ok(opt_key.map(PyPublicKey))
+    }
+
     fn __repr__(&self) -> String {
         self.0.print()
     }