refactor: iterate over access request endpoint API

Ensure timestamp is generated within the server;
Ensure DELETE on access requests can not be executed (who owns an access request?);
iterate over documentation;
Remove duplicated function;
fix tests accordingly

Author: woutslabbinck

documentation/access-request-management.md

@@ -10,7 +10,7 @@ The general flow of access requests and grants looks like this:
 
 The document makes use of these parties and identifiers:
 
-- **Resource Owner**: `https://pod.harrypodder.org/profile/card#me`
+- **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`
@@ -21,10 +21,7 @@ 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 dcterms: <http://purl.org/dc/terms/> .
-@prefix dct: <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> ;
@@ -70,19 +67,16 @@ curl --location 'http://localhost:4000/uma/requests' \
 --header 'Content-Type: text/turtle' \
 --data-raw '
 @prefix sotw: <https://w3id.org/force/sotw#> .
-@prefix odrl: <https://www.w3.org/ns/odrl/2/> .
-@prefix dcterms: <https://purl.org/dc/terms/> .
-@prefix dct: <https://purl.org/dc/terms/> .
-@prefix ex: <https://example.org/> .
-@prefix xsd: <https://www.w3.org/2001/XMLSchema#> .
+@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 ;
-      dcterms:issued "2025-08-21T11:24:34.999Z"^^xsd:datetime ;
       sotw:requestedTarget <http://localhost:3000/resources/resource.txt> ;
-      sotw:requestedAction odrl:read ;
+      sotw:requestedAction odrl:write ;
       sotw:requestingParty <https://example.pod.knows.idlab.ugent.be/profile/card#me> ;
-      ex:requestStatus ex:requested .
-'
+      ex:requestStatus ex:requested .'
 ```
 
 ## Reading access requests
@@ -105,8 +99,8 @@ 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/rquests/:id' \
---header 'Authorization: https://example.pod.knows.idlab.ugent.be/profile/card#me' \
+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.
 ```
@@ -116,13 +110,11 @@ After this, the RP will be able to use the resource following the UMA protocol.
 
 ## Deleting access requests
 
-By making a simple **DELETE** request on the `/uma/requests/:id` endpoint, an access request can be deleted.
-The id should be sufficiently encoded in the URL.
+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.
 
-```shell-session
-curl -X DELETE --location 'http://localhost:4000/uma/requests/:id' \
---header 'Authorization: https://example.pod.knows.idlab.ugent.be/profile/card#me' \
-```
 
 ## Important Notes
 

packages/uma/config/routes/accessrequests.json

@@ -33,7 +33,8 @@
                 "OPTIONS",
                 "PATCH",
                 "GET",
-                "DELETE"
+                "DELETE", 
+                "PUT"
             ],
             "handler": { "@id": "urn:uma:default:AccessRequestHandler" },
             "path": "/uma/requests/{id}"

packages/uma/src/controller/AccessRequestController.ts

@@ -25,4 +25,20 @@ export class AccessRequestController extends BaseController {
             patchAccessRequest,
         );
     }
+
+    /**
+     * Deletes are not allowed on access requests.
+     * 
+     * @param entityID ID pointing to the policy or access request
+     * @param clientID ID of the resource owner (RO) or requesting party (RP) making the deletion
+     * @returns a status code: 403
+     */
+    public async deleteEntity(entityID: string, clientID: string): Promise<{ status: number }> {
+        return { status: 403 }; 
+    }
+
+    public async putEntity(data: string, entityID: string, clientID: string): Promise<{ status: number }> {
+        return { status: 403 }; 
+    }
+
 }

packages/uma/src/controller/BaseController.ts

@@ -78,19 +78,19 @@ export abstract class BaseController {
      *          - 201 if creation was successful
      *          - 409 if a conflict occurred (duplicate subject)
      */
-    public async addEntity(data: string, clientID: string): Promise<{ status: number }> {
+    public async addEntity(data: string, clientID: string): Promise<{ status: number, message:string }> {
         const store = await parseStringAsN3Store(data);
 
         try {
             const sanitizedStore = await this.sanitizePost(store, clientID);
             if (noAlreadyDefinedSubjects(await this.store.getStore(), sanitizedStore))
                 this.store.addRule(sanitizedStore);
-            else return { status: 409 }; // conflict
-        } catch (e) {
-            return { status: parseInt(e.message, 10) }; // the message of this error will contain the reason this query failed
+            else return { status: 409, message: ''  }; // conflict
+        } catch (e) {          
+            return { status: e.statusCode || 500, message: e.message }; // the message of this error will contain the reason this query failed
         }
 
-        return { status: 201 }; // success
+        return { status: 201, message: ''  }; // success
     }
 
     /**
@@ -147,10 +147,9 @@ export abstract class BaseController {
     }
 
     /**
-     * Apply a PUT to a single policy or access request identified by `entityID`µ.
+     * Apply a PUT to a single policy or access request identified by `entityID`.
      * 
      * Currently, this is only implemented for policies.
-     * The {@link BaseHandler} should never call this function for access requests routes, as it isn't configured in the componentsjs file.
      * 
      * @param data RDF data in Turtle/N3 format representing a policy or acccess request
      * @param entityID ID pointing to the policy or access request

packages/uma/src/routes/BaseHandler.ts

@@ -170,12 +170,13 @@ export abstract class BaseHandler extends HttpHandler {
      * @returns a response with status code 201 if successful, 409 if conflict occurred, or error otherwise
      * @throws BadRequestHttpError if request body is missing
      */
-    private async handlePost(request: HttpHandlerRequest<string>, clientID: string): Promise<HttpHandlerResponse<void>> {
+    private async handlePost(request: HttpHandlerRequest<string>, clientID: string): Promise<HttpHandlerResponse<string>> {
         if (!request.body) throw new BadRequestHttpError();
-        const { status } = await this.controller.addEntity(request.body.toString(), clientID);
+        const { status, message } = await this.controller.addEntity(request.body.toString(), clientID);
 
         return {
-            status: status
+            status: status,
+            body: message
         };
     }
 }

packages/uma/src/util/routeSpecific/delete.ts

@@ -103,5 +103,7 @@ const buildAccessRequestDeletionQuery = (requestID: string, requestingPartyOrRes
  * @param requestingPartyOrResourceOwner ID of the requesting party or resource owner
  * @returns a promise resolving when deletion is completed
  */
-export const deleteAccessRequest = (store: Store, requestID: string, requestingPartyOrResourceOwner: string) =>
-    executeDelete(store, buildAccessRequestDeletionQuery(requestID, requestingPartyOrResourceOwner));
+export const deleteAccessRequest = async (store: Store, requestID: string, requestingPartyOrResourceOwner: string): Promise<void> => {
+    await executeDelete(store, buildAccessRequestDeletionQuery(requestID, requestingPartyOrResourceOwner));
+
+}

packages/uma/src/util/routeSpecific/post.ts

@@ -1,6 +1,7 @@
-import { Store } from "n3";
+import { Store, DataFactory } from "n3";
 import {queryEngine} from './index';
-
+import { BadRequestHttpError, ForbiddenHttpError, RDF, XSD } from "@solid/community-server";
+const {literal, namedNode} = DataFactory
 /**
  * Run a query against the store and extract exactly one matching subgraph.
  *
@@ -90,7 +91,7 @@ const buildPolicyCreationQuery = (resourceOwner: string) => `
  */
 export const postPolicy = async (store: Store, resourceOwner: string): Promise<Store> => {
     const isOwner = store.countQuads(null, 'http://www.w3.org/ns/odrl/2/assigner', resourceOwner, null) !== 0;
-    if (!isOwner) throw new Error('403');
+    if (!isOwner) throw new ForbiddenHttpError();
 
     const result = await executePost(store, buildPolicyCreationQuery(resourceOwner), ["p", "r"]);
 
@@ -132,20 +133,15 @@ const buildAccessRequestCreationQuery = (requestingParty: string) => `
  * @param requestingParty identifier of the client
  * @returns the validated request as a store
  */
-export const postAccessRequest = (store: Store, requestingParty: string) =>
-    executePost(store, buildAccessRequestCreationQuery(requestingParty), ["r"]);
+export const postAccessRequest = async (store: Store, requestingParty: string): Promise<Store>  =>{
+    const hasTime = store.countQuads(null, "http://purl.org/dc/terms/issued", null, null) !== 0;
+    if (hasTime) throw new BadRequestHttpError("Time is managed by the server");
 
-/**
- * Check whether all subjects in the new store
- * are absent from the existing store.
- *
- * This is used to ensure no pre-existing entities
- * are being redefined.
- *
- * @param store the original store
- * @param newStore the store containing new data
- * @returns true if no subjects are already defined, false otherwise
- */
-export const noAlreadyDefinedSubjects = (store: Store, newStore: Store): boolean =>
-    newStore.getSubjects(null, null, null)
-        .every((subject) => store.countQuads(subject, null, null, null) === 0);
+    const requestIds = store.getSubjects(RDF.type, "https://w3id.org/force/sotw#EvaluationRequest", null);
+    if (requestIds.length !==1) {
+        throw new BadRequestHttpError("Expected one acces request.");
+    }
+
+    store.addQuad(requestIds[0], namedNode("http://purl.org/dc/terms/issued"), literal(new Date().toISOString(), XSD.terms.dateTime))
+    return await executePost(store, buildAccessRequestCreationQuery(requestingParty), ["r"]);
+}

packages/uma/src/util/routeSpecific/sanitizeUtil.ts

@@ -1,10 +1,19 @@
 import { Store } from "n3";
 
-// check if there are no subjects in newStore that are already in Store
+/**
+ * Check whether all subjects in the new store
+ * are absent from the existing store.
+ *
+ * This is used to ensure no pre-existing entities
+ * are being redefined.
+ *
+ * @param store the original store
+ * @param newStore the store containing new data
+ * @returns true if no subjects are already defined, false otherwise
+ */
 export const noAlreadyDefinedSubjects = (store: Store, newStore: Store): boolean =>
     newStore.getSubjects(null, null, null)
         .every((subject) => store.countQuads(subject, null, null, null) === 0);
-
 export class ConflictError extends Error {
     constructor() { super(`Resource already exists`); }
 }