Guardian

Generic framework for roles and permissions to be used in our projects

Limitations and Notes

• Supported Database: Implementation with MariaDb
• Context (ctx): Allows to have multiple database pools (See next section)

Setup with MariaDB backend (MultiPools)

  let open Guardian_backend.Pools in
  let module MariaConfig = struct
    include DefaultConfig

    let database =
      MultiPools
        [ "pool-one", "mariadb://root@database:3306/dev"
        ; "pool-two", "mariadb://root@database:3306/test"
        ]
    ;;
  end
  in
  let module MariaDb = Guardian_backend.MariaDb.Make (Roles) (Make (MariaConfig))
  let%lwt () = Lwt_list.iter (fun pool -> MariaDb.migrate ~ctx:["pool", pool] ()) ["pool-one"; "pool-two"]
  (** NOTE: To integrate migrations into your applications migration state see
      e.g. function 'MariaDB.find_migrations *)

Usage

The test directory shows an example implementation of how guardian can be used.

• role.ml: Definition of actors and targets
• role.mli: Signature of the defined actors and targets
• guard.ml: Create the guardian service
• article.ml: Definition of the article target
• hacker.ml: Definition of the hacker actor
• user.ml: Definition of the user actor and target
• main.ml: implementation of all test cases

Example usage:

  module Guard = Guardian.Make (Role.Actor) (Role.Target)

  let thomas = "Thomas", Guard.Uuid.Actor.create ()
  let mike = "Mike", Guard.Uuid.Actor.create ()

  let thomas_article = Article.make "Foo" "Bar" thomas
  let mike_article = Article.make "Hello" "World" mike

  let example_rule = `Actor (snd mike), `Update, `Target thomas_article.uuid

  let initialize_authorizables_and_rules ?ctx =
    (* Note: As a user can be an actor and a target, both need to be initialized *)
    let* (_: [> `User ] MariaDb.actor) = User.to_authorizable ?ctx thomas in
    let* (_: [> `User ] MariaDb.actor) = User.to_authorizable ?ctx mike in
    let* (_: [> `User ] MariaDb.target) = UserTarget.to_authorizable ?ctx thomas in
    let* (_: [> `User ] MariaDb.target) = UserTarget.to_authorizable ?ctx mike in
    let* (_: [> `Article ] MariaDb.target) = Article.to_authorizable ?ctx thomas_article in
    let* (_: [> `Article ] MariaDb.target) = Article.to_authorizable ?ctx mike_article in
    let* () = MariaDb.Rule.save ?ctx example_role in
    Lwt.return_unit

  (* let mike Update the title of thomas article -> returns a (Article.t, string) Lwt_result.t  *)
  let update_title = Article.update_title ?ctx mike thomas_article "Updated Title"

Development

This project runs in a DevContainer. All credentials are passed via a local .env file — no host SSH keys required.

1. Follow the general DevContainer instructions in the Engineering Wiki.
2. Copy the env template and fill in the values: cp .devcontainer/.env.example .devcontainer/.env
3. Click the >< icon in the bottom-left corner of VS Code and select Reopen in Container.

NOTE: When the setup is fully installed, select View -> Command Palette... and run the command OCaml: Restart Language Server

Database View

There is an Adminer container added to the development package. To be able to use it, follow these few steps:

1. Uncomment its line in the .devcontainer/devcontainer.json under runServices
2. Use Remote-Containers: Rebuild Container that it will also create and startup the Adminer container
3. Open your web browser and open localhost:8080
4. Use the development credentials defined for the development database in your .env file (default: user: root, password: <empty/none>, host: database, database: development )

Commands

Most used commands can be found in the following list. For the full list of commands, checkout the Makefile.

• make build - to build the project
• make build-watch - to build and watch the project
• make test - to run all tests. This requires a running MariaDB instance.

🚀 Release new version

1. Update CHANGELOG.md and document changes made. Ensure the version to be releases has a header matching the version, follow previous releases.
2. Run econ-version --[patch|minor|major]
3. Push changes and git tag
4. create opam release (opam publish)