feat: usage control policies package (#3)

Signed-off-by: Wouter Termont <wouter.termont@ugent.be>

Author: woutslabbinck

.yarnrc.yml

@@ -27,4 +27,4 @@ nodeLinker: "node-modules"
 #       "@types/node": ^18
 #   winston@*:
 #     dependencies:
-#       "@types/node": ^18
+#       "@types/node": ^18

README.md

@@ -10,12 +10,14 @@ This repository contains SolidLab research artefacts on use of UMA in the Solid
 
 - [`@solidlab/uma-css`](packages/css): UMA modules for the [Community Solid Server](https://github.com/CommunitySolidServer/CommunitySolidServer/). 
 
+- [`@solidlab/ucp`](packages/ucp): Usage Control Policy decision/enforcement component.
 
 ## Getting started
 
 In order to run this project you need to perform the following steps. 
 
-1. Ensure that you are using Node.js 18.18 or higher with Yarn 4.0 or higher.
+1. Ensure that you are using Node.js 18.18 or higher, e.g. by running `nvm use`.
+1. Enable Node.js Corepack with `corepack enable`.
 1. Run `yarn install` in the project root (this will automatically call `yarn build:all`).
 1. Run `yarn start:all`.
 
@@ -24,15 +26,31 @@ 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`, with redirection to the UMA server;
-- `yarn script:registration`: `POST`, `GET` and `DELETE` some text `/alice/public/resource.txt` without redirection to the UMA server, to test the correct creation and deletion of resource registrations on the UNA 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.
 
 ## Implemented features
 
 The packages in this project currently only support a fixed UMA AS per CSS RS, and contain only the trivial [AllAuthorizer](packages/uma/src/models/AllAuthorizer.ts) that allows all access. More useful features are coming soon ...
 
+### 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.
+
 
 ## Next steps
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidlab/user-managed-access",
   "version": "0.1.0",
-  "description": "UMA artefacts for use in the Solid ecosystem.",
+  "description": "SolidLab access & usage control artefacts for use in the Solid ecosystem.",
   "keywords": [
     "css",
     "solid",
@@ -10,20 +10,26 @@
     "uma",
     "user managed access",
     "access control",
+    "usage control",
     "authorization",
     "policies",
     "grants"
   ],
   "author": {
     "name": "Wouter Termont",
     "email": "wouter.termont@ugent.be",
-    "url": "https://wouter.termont.online"
+    "url": "https://wouter.termont.online/"
   },
   "license": "MIT",
   "repository": "github:SolidLabResearch/user-managed-access",
   "homepage": "https://github.com/SolidLabResearch/user-managed-access/README.md",
   "bugs": "https://github.com/SolidLabResearch/user-managed-access/issues",
   "contributors": [
+    {
+      "name": "Ruben Dedecker",
+      "email": "ruben.dedecker@ugent.be",
+      "url": "https://pod.rubendedecker.be/profile/card#me"
+    },
     {
       "name": "Wout Slabbink",
       "email": "wout.slabbink@ugent.be",
@@ -32,11 +38,11 @@
     {
       "name": "Wouter Termont",
       "email": "wouter.termont@ugent.be",
-      "url": "https://wouter.termont.online"
+      "url": "https://wouter.termont.online/"
     }
   ],
   "private": true,
-  "packageManager": "yarn@4.0.2",
+  "packageManager": "yarn@4.1.0",
   "engines": {
     "node": ">=18.18",
     "yarn": ">=4.0"
@@ -53,11 +59,14 @@
     "script:public": "yarn exec ts-node ./scripts/test-public.ts",
     "script:private": "yarn exec ts-node ./scripts/test-private.ts",
     "script:registration": "yarn exec ts-node ./scripts/test-registration.ts",
-    "script:flow": "yarn run script:public && yarn run script:private && yarn run script:registration"
+    "script:ucp-enforcement": "yarn exec ts-node ./scripts/test-ucp-enforcement.ts",
+    "script:uma-ucp": "yarn exec ts-node ./scripts/test-uma-ucp.ts",
+    "script:flow": "yarn run script:public && yarn run script:private && yarn run script:uma-ucp && yarn run script:registration && yarn run script:ucp-enforcement"
   },
   "devDependencies": {
     "@commitlint/cli": "^16.1.0",
     "@commitlint/config-conventional": "^16.0.0",
+    "@solidlab/ucp": "workspace:^",
     "@types/jest": "^29.5.6",
     "@types/node": "^20.9.4",
     "@typescript-eslint/eslint-plugin": "^5.12.1",
@@ -67,6 +76,7 @@
     "eslint": "^8.10.0",
     "jest": "^29.7.0",
     "lerna": "^4.0.0",
+    "koreografeye": "^0.4.8",
     "shx": "^0.3.3",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.9.1",

packages/css/package.json

@@ -17,7 +17,7 @@
   "author": {
     "name": "Wouter Termont",
     "email": "wouter.termont@ugent.be",
-    "url": "https://wouter.termont.online"
+    "url": "https://wouter.termont.online/"
   },
   "license": "MIT",
   "repository": "github:SolidLabResearch/user-managed-access",
@@ -32,7 +32,7 @@
     {
       "name": "Wouter Termont",
       "email": "wouter.termont@ugent.be",
-      "url": "https://wouter.termont.online"
+      "url": "https://wouter.termont.online/"
     }
   ],
   "private": true,

packages/css/src/authorization/UmaPermissionReader.ts

@@ -41,7 +41,7 @@ export class UmaPermissionReader extends PermissionReader {
           return [scope, false];
         }
 
-        return [scope, true];
+        return [scope.replace('urn:example:css:modes:', ''), true];
       }));
 
       result.set({ path: resource_id }, permissionSet);

packages/css/src/uma/ResourceRegistrar.ts

@@ -1,5 +1,5 @@
 import type { ResourceIdentifier, MonitoringStore, KeyValueStorage } from '@solid/community-server';
-import { AS, getLoggerFor, StaticHandler } from '@solid/community-server';
+import { AccessMode, AS, getLoggerFor, StaticHandler } from '@solid/community-server';
 import { OwnerUtil } from '../util/OwnerUtil';
 import { fetchUmaConfig } from './util/UmaConfigFetcher.js';
 import { ResourceDescription } from '@solidlab/uma';
@@ -34,7 +34,15 @@ export class ResourceRegistrar extends StaticHandler {
 
     const { resource_registration_endpoint: endpoint } = await fetchUmaConfig(issuer);
 
-    const description: ResourceDescription = { resource_scopes: [ 'CRUD' ] };
+    const description: ResourceDescription = {
+      resource_scopes: [
+        'urn:example:css:modes:read',
+        'urn:example:css:modes:append',
+        'urn:example:css:modes:create',
+        'urn:example:css:modes:delete',
+        'urn:example:css:modes:write',
+      ]
+    };
 
     this.logger.info(`Creating resource registration for <${resource.path}> at <${endpoint}>`);
 

packages/css/src/uma/util/PermissionTicketFetcher.ts

@@ -19,7 +19,7 @@ export async function fetchPermissionTicket(
   for (const [ target, modes ] of permissions.entrySets()) {
     body.push({
       resource_id: target.path,
-      resource_scopes: Array.from(modes)
+      resource_scopes: Array.from(modes).map(mode => `urn:example:css:modes:${mode}`)
     });
   }
 

packages/ucp/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@solidlab/ucp",
+  "version": "0.1.0",
+  "description": "A Usage Control Policy decision/enforcement component.",
+  "keywords": [
+    "access control",
+    "usage control",
+    "authorization",
+    "policies",
+    "grants"
+  ],
+  "author": {
+    "name": "Wout Slabbinck",
+    "email": "wout.slabbinck@ugent.be",
+    "url": "https://woutslabbinck.com"
+  },
+  "license": "MIT",
+  "repository": "github:SolidLabResearch/user-managed-access",
+  "homepage": "https://github.com/SolidLabResearch/user-managed-access/README.md",
+  "bugs": "https://github.com/SolidLabResearch/user-managed-access/issues",
+  "contributors": [
+    {
+      "name": "Wout Slabbink",
+      "email": "wout.slabbink@ugent.be",
+      "url": "https://pod.woutslabbinck.com/profile/card#me"
+    },
+    {
+      "name": "Wouter Termont",
+      "email": "wouter.termont@ugent.be",
+      "url": "https://wouter.termont.online/"
+    }
+  ],
+  "private": true,
+  "packageManager": "yarn@4.0.2",
+  "engines": {
+    "node": ">=18.18",
+    "yarn": ">=4.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "config"
+  ],
+  "scripts": {
+    "build": "yarn build:ts",
+    "build:ts": "yarn run -T tsc"
+  },
+  "dependencies": {
+    "@types/n3": "^1.16.3",
+    "koreografeye": "^0.4.8",
+    "n3": "^1.17.1"
+  },
+  "devDependencies": {
+    "@solid/community-server": "7.0.3",
+    "@types/node": "^20.11.16",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.3"
+  }
+}