docs: Give more general information in README

Author: joachimvh

README.md

@@ -1,34 +1,69 @@
-# Pacsoi POC 
+# SolidLab's User Managed Access
 
-This repository contains a demonstrator for the [SolidLab project](https://solidlab.be/) on managing trust-flows in decentralized data storage systems such as Solid.
+This repository contains SolidLab research artefacts on use of UMA in the Solid ecosystem.
 
 
-## Cloning the repository
+## Packages
 
-To run the demonstrator, you will have to clone the repository.
-```
-git clone -b project/pacsoi-poc1 git@github.com:SolidLabResearch/user-managed-access.git
+- [`@solidlab/uma`](packages/uma): Experimental and opinionated implementation of [UMA Grants](https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html) and [UMA Federation](https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-federated-authz-2.0.html).
 
-cd user-managed-access/
-```
+- [`@solidlab/uma-css`](packages/css): UMA modules for the [Community Solid Server](https://github.com/CommunitySolidServer/CommunitySolidServer/).
 
-## Getting started
-
-### Setting up the Authorization Server 
+- [`@solidlab/ucp`](packages/ucp): Usage Control Policy decision/enforcement component.
 
-Before starting, make sure you are on the correct branch (pacsoi-poc1).
-See the above command to clone only the relevant branch for the demonstrator.
+## Getting started
 
-In order to run the demonstrator you need to perform the following steps. 
+In order to run this project you need to perform the following steps.
 
 1. Ensure that you are using Node.js 20 or higher, e.g. by running `nvm use`. (see [.nvmrc](./.nvmrc))
 2. Enable Node.js Corepack with `corepack enable`.
-3. Run `yarn install` in the project root to install the requirements.
-4. Run `yarn build` in the project root to build.
-5. Run `yarn run start:demo` in the project root to start all services.
+3. Run `yarn install` in the project root (this will automatically call `yarn build`).
+4. Run `yarn start`.
+
+This will boot up a UMA server and compatible Community Solid Server instance.
+
+You can then execute the following flows:
+
+- `yarn script:public`: `GET` the public `/alice/profile/card` without redirection to the UMA server;
+- `yarn script:private`: `PUT` some text to the private `/alice/private/resource.txt`, protected by a simple WebID check;
+- `yarn script:uma-ucp`: `PUT` some text to the private `/alice/other/resource.txt`, protected by a UCP enforcer checking WebIDs according to policies in `packages/uma/config/rules/policy/`.
+- `yarn script:registration`: `POST`, `GET` and `DELETE` some text to/from `/alice/public/resource.txt` to test the correct creation and deletion of resource registrations on the UNA server.
+- `yarn script:ucp-enforcement`: Run the UCP enforcer in a script (`scripts/test-ucp-enforcement.ts`). This does not need the servers to be started.
+
+`yarn script:flow` runs all flows in sequence.
+
+As we are still in the progress of documenting everything,
+the above scripts are the best way to learn about how everything works.
+
+## Demonstration
+
+Instead of running `yarn start`, you can run `yarn start:demo` to start the server with an alternative configuration.
+With this configuration you can run the `script:demo`,
+which runs with experimental contracts.
+
+## Implemented features
+
+The packages in this project currently only support a fixed UMA AS per CSS RS.
+Authorization can be done with a simple, unverified, WebID embedded in the ticket
+using the [WebIdAuthorizer](packages/uma/src/policies/authorizers/WebIdAuthorizer.ts)
+or the [PolicyBasedAuthorizer](packages/uma/src/policies/authorizers/PolicyBasedAuthorizer.ts)
+which supports simple ODRL policies.
+
+### Usage control policy enforcement
+
+Used for creating a modular engine that calculates which access modes are granted based on:
+
+- Usage Control Rules
+- Interpretation of those rules
+- The request of the Requested Party together with all its claims
+
+For more information, you can check out its [own repository](https://github.com/woutslabbinck/ucp-enforcement) which has three engines that use [ODRL rules](https://www.w3.org/TR/odrl-model/).
+
+A test script is provided for a CRUD ODRL engine: `yarn script:ucp-enforcement`.
+In the [script](./scripts/test-ucp-enforcement.ts) a read Usage Control Rule (in ODRL) is present together with N3 interpretation rules.
+Then a read request is performed using the engine, which results in a list of grants. This list is then printed to the console.
 
 
-### Docker
+## Next steps
 
-The docker is not working atm. 
-I am trying to get it working, but there seem to be some problems with the internal networking.
+More advanced ODRL evaluation can be found in the `feat/ODRL-evaluator` branch.