Merge policy and access request support

README.md

@@ -30,6 +30,8 @@ You can then execute the following flows:
 - `yarn script:collection`: `POST`, `GET` and `DELETE` some text to/from `/alice/public/resource.txt` to test the correct creation and deletion of resource registrations on the UMA server.
                             An AssetCollection policy is used to create `/alice/public/`.
                             More information on the collection implementation can be found in [documentation/collections.md](documentation/collections.md).
+- `yarn script:uma-odrl-policy`: Tests all policy management APIs.
+- `yarn script:uma-odrl-end2end`: Tests the access request management APIs
 
 `yarn script:flow` runs all flows in sequence.
 
@@ -39,6 +41,9 @@ the above scripts are the best way to learn about how everything works.
 A more extensive getting started guide can be found
 in [documentation/getting-started.md](documentation/getting-started.md).
 
+More information on policy management can be found in
+[documentation/policy-management](documentation/policy-management.md).
+
 ## Demonstration
 
 Instead of running `yarn start`, you can run `yarn start:demo` to start the server with an alternative configuration.

documentation/access-request-management.md

@@ -0,0 +1,134 @@
+# Access Request Management
+
+This document describes the *access request administration endpoint*.
+It contains the methods to describe how to create, read, update and delete access requests.
+Example cURL-requests are provided for ease of use.
+
+The general flow of access requests and grants looks like this:
+
+![Access requests and grants flow](./figures/access_grants_requests_fsm.png)
+
+The document makes use of these parties and identifiers:
+
+- **Resource Owner**: `https://pod.example.com/profile/card#me`
+- **Authorization Server**: `http://localhost:4000`
+- **Resource Server**: `http://localhost:3000/resources`
+- **Requesting Party**: `https://example.pod.knows.idlab.ugent.be/profile/card#me`
+
+The examples provided below make use of `text/turtle` and `application/sparql-update` messages.
+The access request used in the examples below looks like this:
+
+```turtle
+@prefix sotw: <https://w3id.org/force/sotw#> .
+@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
+@prefix ex: <http://example.org/> .
+
+ex:request a sotw:EvaluationRequest ;
+      sotw:requestedTarget <http://localhost:3000/resources/resource.txt> ;
+      sotw:requestedAction odrl:read ;
+      sotw:requestingParty <https://example.pod.knows.idlab.ugent.be/profile/card#me> ;
+      ex:requestStatus ex:requested .
+```
+
+## Supported endpoints
+
+The current implementation supports the following requests to the `uma/requests` and `/uma/requests/:id` endpoints
+
+- [**GET**](#reading-access-requests)
+- [**POST**](#creating-access-requests)
+- [**PATCH**](#managing-access-requests)
+- [**DELETE**](#deleting-access-requests)
+
+## Creating access requests
+
+Create an access request/multiple access requests by sending a **POST** request to `uma/requests`.
+Apart from its `Authorization` header, the `Content-Type` header must be set to the RDF serialization format in which the body is written.
+The accepted formats are those accepted by the [N3 Parser](https://github.com/rdfjs/N3.js/?tab=readme-ov-file#parsing), represented by the following content types:
+
+- `text/turtle`
+- `application/trig`
+- `application/n-triples`
+- `application/n-quads`
+- `text/n3`
+
+The body is expected to represent a valid ODRL access request.
+No sanitization is currently applied.
+Upon success, the server responds with **status code 201**.
+Bad requests, possibly due to improper access request definition, will respond with **status code 400** (to be implemented) <!-- TODO: implement -->
+When the access requested has been validated (to be implemented), but the storage fails, the response will have **status code 500**.
+
+### Example POST request
+
+This example creates an access request `ex:request` for the RP `https://example.pod.knows.idlab.ugent.be/profile/card#me`:
+
+```shell-session
+curl --location 'http://localhost:4000/uma/requests' \
+--header 'Authorization: https://example.pod.knows.idlab.ugent.be/profile/card#me' \
+--header 'Content-Type: text/turtle' \
+--data-raw '
+@prefix sotw: <https://w3id.org/force/sotw#> .
+@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix ex: <http://example.org/> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ex:request a sotw:EvaluationRequest ;
+      sotw:requestedTarget <http://localhost:3000/resources/resource.txt> ;
+      sotw:requestedAction odrl:write ;
+      sotw:requestingParty <https://example.pod.knows.idlab.ugent.be/profile/card#me> ;
+      ex:requestStatus ex:requested .'
+```
+
+## Reading access requests
+
+To read policies, a single endpoint is currently implemented.
+This endpoint currently returns the list of access requests where the WebID provided in the `Authorization` header is marked as the requesting party.
+An example request to this endpoint is:
+
+```shell-session
+curl -X GET --location 'http://localhost:4000/uma/requests' \
+--header 'Authorization: https://example.pod.knows.idlab.ugent.be/profile/card#me'
+```
+
+## Managing access requests
+
+The RO can accept or deny the access requests, which is done by updating the status triple.
+
+Updating policies can be done through a **PATCH** request.
+The body must hold the content type `application/json`.
+The example below shows how to update the access request's status from `requested` to `accepted`:
+
+```shell-session
+curl -X PATCH --location 'http://localhost:4000/uma/requests/http%3A%2F%2Fexample.org%2Frequest' \
+--header 'Authorization: https://pod.example.com/profile/card#me' \
+--header 'Content-Type: application/json' \
+--data-raw '{ "status": "accepted" }' # can be changed to `denied` too.
+```
+
+Once an access request's status has been changed from `requested` to `accepted`, the backend will automatically create a new policy including the correct rules to allow the RP access to the resource.
+After this, the RP will be able to use the resource following the UMA protocol.
+
+## Deleting access requests
+
+Currently, access requests cannot be deleted. The reason being that it from a governance decision a decision need to be made who is allowed to delete it.
+
+Is it the requesting party? Or is it the resource owner?
+From the start. It makes more sense for the RP. However, if the RO made a decision, it does not make sense that the RP can remove this.
+
+
+## Important Notes
+
+### Undefined behavior for **PATCH/DELETE** request
+
+Upon the first **PATCH** request which changes an access request's status from `requested` to `accepted` a new policy and permission are created.
+When a new **PATCH** request would change the status to denied, nothing is currently done with the policy.
+Even when the access request would be deleted, the backend currently doesn't do anything to the policy.
+This is undefined behavior and should be treated as such.
+This works in both directions: if the policy is changed in some way, nothing is changed to the access request either.
+
+## Future work
+
+### Discrepancies between [earlier descriptions](https://github.com/bramcomyn/loama/blob/feat/odrl/documentation/access_grants_vs_dsnp.md) and this implementation
+
+This file counts as authorative resource for the access request management.
+Other documentation should point to this file as the latest and correct documentation.