Merge pull request #103 from eclipse-biscuit/push-yxnprpptzwxq

Cleanup and documentation

Author: divarvel

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+This repository is part of the [eclipse-biscuit](https://projects.eclipse.org/projects/technology.biscuit) project. It is licensed under `BSD-3-Clause` and requires contributors to sign the [Eclipse Contributor Agreement](https://www.eclipse.org/legal/ECA.php) (see #eclipse-contributor-agreement below).
+
+## Before contributing
+
+This is an implementation of the biscuit specification. All changes pertaining to the specification must be discussed in the [specification repo](https://github.com/eclipse-biscuit/biscuit) first.
+
+Unless you’re fixing a trivial issue, it is a good idea to start by opening an issue, in order to gather feedback about the changes you have in mind.
+
+You can also ask questions on the [implementers matrix chat](https://matrix.to/#/!suybZZpOqChdTNuIVA:matrix.org).
+
+## Code organization
+
+- `biscuit` provides core support for biscuit-auth
+- `biscuit-servant` provides support for protecting servant applications
+- `biscuit-wai` provides WAI middlewares for protecting WAI applications
+
+## Project communication
+
+The discussion space is a [matrix chat](https://matrix.to/#/!MXwhyfCFLLCfHSYJxg:matrix.org).
+Updates are also posted on [bluesky](https://bsky.app/profile/biscuitsec.org) and [mastodon](https://hachyderm.io/@biscuitauth).
+
+Security issues can be reported via [github](https://github.com/eclipse-biscuit/biscuit-haskell/security). 
+
+## Eclipse Contributor Agreement
+
+From the [ECA FAQ](https://www.eclipse.org/legal/eca/faq/):
+
+The purpose of the ECA is to provide a written record that you have agreed to provide your contributions of code and documentation under the licenses used by the Eclipse project(s) you're contributing to. It also makes it clear that you are promising that what you are contributing to Eclipse is code that you wrote, and you have the necessary rights to contribute it to our projects. And finally, it documents a commitment from you that your open source contributions will be permanently on the public record.
+
+In order to sign the ECA, you can follow these steps:
+
+- [Create an account](https://dev.eclipse.org/site_login/createaccount.php) on dev.eclipse.org
+- Open your [Account Settings tab](https://dev.eclipse.org/site_login/myaccount.php#open_tab_accountsettings), enter your GitHub ID and click Update Account
+- Read and [sign the ECA](https://dev.eclipse.org/site_login/myaccount.php#open_tab_cla)
+- Use the exact same email address for your Eclipse account and your commit author.

README.md

@@ -8,15 +8,18 @@ You will find below the main lib and its companions:
 
 * [biscuit](./biscuit/) — Main library, providing minting and signature verification of biscuit tokens, as well as a datalog engine allowing to compute the validity of a token in a given context
 * [biscuit-servant](./biscuit-servant) — Servant combinators, for a smooth integration in your API
+* [biscuit-wai](./biscuit-wai) — WAI middlewares for protecting WAI applications with biscuits
 
 ## Supported biscuit versions
 
-The core library supports [`v3` and `v4` biscuits][spec] (both open and sealed).
+The core library supports [`v3.0` to `v3.3` biscuits][spec] (both open and sealed).
+
+Only `ed25519` signatures are supported. `p256r1` signatures are not supported yet.
 
 [CI-badge]: https://img.shields.io/github/actions/workflow/status/biscuit-auth/biscuit-haskell/github-actions.yml?style=flat-square&branch=main
-[CI-url]: https://github.com/biscuit-auth/biscuit-haskell/actions
+[CI-url]: https://github.com/eclipse-biscuit/biscuit-haskell/actions
 [Hackage]: https://img.shields.io/hackage/v/biscuit-haskell?color=purple&style=flat-square
 [hackage-url]: https://hackage.haskell.org/package/biscuit-haskell
 [gcouprie]: https://github.com/geal
 [biscuit]: https://biscuitsec.org
-[spec]: https://github.com/biscuit-auth/biscuit/blob/master/SPECIFICATIONS.md
+[spec]: https://github.com/eclipse-biscuit/biscuit/blob/main/SPECIFICATIONS.md

biscuit-servant/ChangeLog.md

@@ -1,5 +1,9 @@
 # Changelog for biscuit-servant
 
+## 0.5.0.0 (not released yet)
+
+- use biscuit-haskell 0.5.0.0
+
 ## 0.4.0.0
 
 - use biscuit-haskell 0.4.0.0

biscuit-servant/README.md

@@ -6,7 +6,7 @@
 
 ## Usage
 
-```Haskell
+```haskell
 type AppM = WithAuthorizer Handler
 type API = RequireBiscuit :> ProtectedAPI
 

biscuit-wai/README.md

@@ -0,0 +1,21 @@
+<img src="https://raw.githubusercontent.com/biscuit-auth/biscuit-haskell/main/assets/logo-black-white-bg.png" align=right>
+
+# biscuit-wai [![Hackage][hackage]][hackage-url]
+
+> **WAI middlewares to enable biscuit validation in your WAI applications**
+
+## Usage
+
+```haskell
+import Network.WAI (Application)
+import Network.Wai.Middleware.Biscuit (parseBiscuit, getBiscuit)
+import Auth.Biscuit (PublicKey)
+
+app :: PublicKey -> Application
+app publicKey req respond = parseBiscuit publicKey $ do
+  let verifiedBiscuit = getBiscuit req
+   in error "TODO: authorize biscuit and return a response"
+```
+
+[Hackage]: https://img.shields.io/hackage/v/biscuit-wai?color=purple&style=flat-square
+[hackage-url]: https://hackage.haskell.org/package/biscuit-wai

biscuit/ChangeLog.md

@@ -1,5 +1,12 @@
 # Changelog for biscuit-haskell
 
+## 0.5.0.0 (not released yet)
+
+- biscuit v3.3 support
+- drop support for GHC <9.6
+- support for GHC 9.6, 9.8, 9.10, 9.12
+- dependencies update (including removal of cryptonite in favor of crypton)
+
 ## 0.4.0.0
 
 - abort authorization on evaluation error as mandated by the spec

biscuit/README.md

@@ -6,7 +6,9 @@ Main library for biscuit tokens support, providing minting and signature verific
 
 ## Supported biscuit versions
 
-The core library supports [`v2` biscuits][v2spec] (both open and sealed).
+The core library supports [`v3.0` to `v3.3` biscuits][spec] (both open and sealed).
+
+Only `ed25519` signatures are supported. `p256r1` signatures are not supported yet.
 
 ## How to use this library
 
@@ -103,7 +105,7 @@ creation = do
 [gcouprie]: https://github.com/geal
 [biscuit]: https://www.clever-cloud.com/blog/engineering/2021/04/12/introduction-to-biscuit/
 [biscuittutorial]: https://www.clever-cloud.com/blog/engineering/2021/04/15/biscuit-tutorial/
-[v2spec]: https://github.com/CleverCloud/biscuit/blob/2.0/SPECIFICATIONS.md
+[spec]: https://github.com/eclipse-biscuit/biscuit/blob/main/SPECIFICATIONS.md
 [quasiquotes]: https://wiki.haskell.org/Quasiquotation
-[biscuitexample]: https://github.com/biscuit-auth/biscuit-haskell/blob/main/biscuit/src/Auth/Biscuit/Example.hs
-[packagedoc]: https://hackage.haskell.org/package/biscuit-haskell-0.1.0.0/docs/Auth-Biscuit.html
+[biscuitexample]: https://github.com/eclipse-biscuit/biscuit-haskell/blob/main/biscuit/src/Auth/Biscuit/Example.hs
+[packagedoc]: https://hackage.haskell.org/package/biscuit-haskell-0.4.0.0/docs/Auth-Biscuit.html

biscuit/biscuit-haskell.cabal

@@ -96,7 +96,6 @@ test-suite biscuit-haskell-test
     , bytestring
     , cereal
     , containers
-    , cryptonite
     , lens
     , lens-aeson
     , megaparsec

biscuit/src/Auth/Biscuit/Proto.hs

@@ -21,13 +21,13 @@ module Auth.Biscuit.Proto
   , Block (..)
   , Scope (..)
   , ScopeType (..)
-  , FactV2 (..)
-  , RuleV2 (..)
+  , Fact (..)
+  , Rule (..)
   , CheckKind (..)
-  , CheckV2 (..)
-  , PredicateV2 (..)
-  , TermV2 (..)
-  , ExpressionV2 (..)
+  , Check (..)
+  , Predicate (..)
+  , Term (..)
+  , Expression (..)
   , TermSet (..)
   , TermArray (..)
   , TermMap (..)
@@ -103,14 +103,14 @@ data PublicKey = PublicKey
   deriving anyclass (Decode, Encode)
 
 data Block = Block {
-    symbols   :: Repeated 1 (Value Text)
-  , context   :: Optional 2 (Value Text)
-  , version   :: Optional 3 (Value Int32)
-  , facts_v2  :: Repeated 4 (Message FactV2)
-  , rules_v2  :: Repeated 5 (Message RuleV2)
-  , checks_v2 :: Repeated 6 (Message CheckV2)
-  , scope     :: Repeated 7 (Message Scope)
-  , pksTable  :: Repeated 8 (Message PublicKey)
+    symbols  :: Repeated 1 (Value Text)
+  , context  :: Optional 2 (Value Text)
+  , version  :: Optional 3 (Value Int32)
+  , facts    :: Repeated 4 (Message Fact)
+  , rules    :: Repeated 5 (Message Rule)
+  , checks   :: Repeated 6 (Message Check)
+  , scope    :: Repeated 7 (Message Scope)
+  , pksTable :: Repeated 8 (Message PublicKey)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
@@ -125,15 +125,15 @@ data Scope =
     deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
-newtype FactV2 = FactV2
-  { predicate :: Required 1 (Message PredicateV2)
+newtype Fact = Fact
+  { predicate :: Required 1 (Message Predicate)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
-data RuleV2 = RuleV2
-  { head        :: Required 1 (Message PredicateV2)
-  , body        :: Repeated 2 (Message PredicateV2)
-  , expressions :: Repeated 3 (Message ExpressionV2)
+data Rule = Rule
+  { head        :: Required 1 (Message Predicate)
+  , body        :: Repeated 2 (Message Predicate)
+  , expressions :: Repeated 3 (Message Expression)
   , scope       :: Repeated 4 (Message Scope)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
@@ -144,19 +144,19 @@ data CheckKind =
   | Reject
   deriving stock (Show, Enum, Bounded)
 
-data CheckV2 = CheckV2
-  { queries :: Repeated 1 (Message RuleV2)
+data Check = Check
+  { queries :: Repeated 1 (Message Rule)
   , kind    :: Optional 2 (Enumeration CheckKind)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
-data PredicateV2 = PredicateV2
+data Predicate = Predicate
   { name  :: Required 1 (Value Int64)
-  , terms :: Repeated 2 (Message TermV2)
+  , terms :: Repeated 2 (Message Term)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
-data TermV2 =
+data Term =
     TermVariable  (Required 1  (Value Int64))
   | TermInteger   (Required 2  (Value Int64))
   | TermString    (Required 3  (Value Int64))
@@ -176,12 +176,12 @@ data Empty = Empty {}
 
 
 newtype TermSet = TermSet
-  { set :: Repeated 1 (Message TermV2)
+  { set :: Repeated 1 (Message Term)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
 newtype TermArray = TermArray
-  { array :: Repeated 1 (Message TermV2)
+  { array :: Repeated 1 (Message Term)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
@@ -193,7 +193,7 @@ data MapKey =
 
 data MapEntry = MapEntry
   { key   ::   Required 1 (Message MapKey)
-  , value :: Required 2 (Message TermV2)
+  , value :: Required 2 (Message Term)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
@@ -202,13 +202,13 @@ newtype TermMap = TermMap
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
-newtype ExpressionV2 = ExpressionV2
+newtype Expression = Expression
   { ops :: Repeated 1 (Message Op)
   } deriving stock (Generic, Show)
     deriving anyclass (Decode, Encode)
 
 data Op =
-    OpVValue  (Required 1 (Message TermV2))
+    OpVValue  (Required 1 (Message Term))
   | OpVUnary  (Required 2 (Message OpUnary))
   | OpVBinary (Required 3 (Message OpBinary))
   | OpVClosure (Required 4 (Message OpClosure))
@@ -254,7 +254,7 @@ data BinaryKind =
   | Any
   | Get
   | BinaryFfi
-  | Try
+  | TryOr
   deriving stock (Show, Enum, Bounded)
 
 data OpBinary = OpBinary