feat!: impersonate users (#3042)

* feat: added contextId to user data classes * feat: contextId in H5PPlayer.play * feat: contextId in h5p-express and docs * test: added integration tests for contextId * test: contextId in rest example * feat(mongo-s3): added contextId to user data storage * refactor: permission system * refactor: permissions system * test: fix tests * test: fix more tests * test: fix more tests * refactor!: moved permissions from IUser to IPermissionSystem * refactor: permission system * refactor: fine grained permission types and REST example * refactor: prettier * refactor: more fine grained user data permission handling * feat: impersonate users and read only states * test: fixed test for new content user data interface * refactor: style improvement and docs * feat: add locales * test: fix tests * docs: extended docs * test: added test for impersonation * test: added impersonation and read only state to REST example
Lumieducation · Jul 15, 2023 · 75d7b68 · 75d7b68
1 parent 3bb30a3
commit 75d7b68
Show file tree

Hide file tree

Showing 134 changed files with 2,441 additions and 1,023 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -7,7 +7,10 @@
   * [Constructing H5PEditor](usage/h5p-editor-constructor.md)  
   * [REST Example](examples/rest/README.md)
 - Advanced usage
+  * [Authorization](advanced/authorization.md)
   * [User content state](advanced/user-content-state.md)
+  * [Multiple user states per object](advanced/context-ids.md)
+  * [Impersonating users](advanced/impersonation.md)
   * [Basic completion tracking](advanced/completion-tracking.md)
   * [Localization](advanced/localization.md)
   * [Cluster](advanced/cluster.md)
@@ -16,7 +19,6 @@
   * [Performance optimizations](advanced/performance-optimizations.md)
   * [Privacy](advanced/privacy.md)
   * [Forward proxy support](advanced/proxy.md)
-  * [Multiple content states per object](advanced/context-ids.md)
 - NPM packages
   - h5p-mongos3
     * [Mongo/S3 Content Storage](packages/h5p-mongos3/mongo-s3-content-storage.md)

diff --git a/docs/advanced/authorization.md b/docs/advanced/authorization.md
@@ -0,0 +1,17 @@
+# Authorization
+
+Many actions users perform in the H5P system need authorization. By default the
+library will allow everything to every user. You can customize who can do what,
+but passing in an implementation of `IPermissionSystem` into
+`options.permissionSystem` of the `H5PPlayer` or `H5PEditor` constructor. The
+library then calls the methods of `IPermissionSystem` whenever a user performs an
+action that requires authorization.
+
+See the documentation of `IPermissionSystem` for and the
+[`ExamplePermissionSystem`](/packages/h5p-rest-example-server/src/ExamplePermissionSystem.ts)
+for reference how to implement the permission system.
+
+Note that the `IPermissionSystem` is a generic. You can use any sub-type of
+`IUser` as the generic type. The call of the methods of `IPermissionSystem` will
+include a user of the generic type. This is the user object you've injected in
+your controllers. That means you can add any arbitrary date to it, like roles.
diff --git a/docs/advanced/impersonation.md b/docs/advanced/impersonation.md
@@ -0,0 +1,30 @@
+# Impersonating users
+
+It is possible to impersonate users when viewing a H5P object. This means that
+you can display another user's user state instead of your own. This is useful,
+if you want to implement a feature in which teachers can review the work of
+students.
+
+You do this by setting `options.asUserId` of the `H5PPlayer.render` method. Make
+sure that you [authorize users](authorization.md) as required in the permission
+system.
+
+## Read-only states
+
+In most cases in which your users impersonate another user, you'll want to
+disable saving the user state for the impersonator. You can do this by setting
+`options.readOnlyState` to true when calling `H5PPlayer.render`. This will do
+the following:
+
+-   set the save interval to the longest possible value
+-   adds the query parameter `ignorePost=yes` to the Ajax route responsible for
+    handling user states
+
+The query parameter is necessary, as the H5P core client doesn't support user
+states that are read only. We work around this by ignoring a post calls when the
+query parameter is set in h5p-express. If the query parameter is set, we simply
+return a success, so the H5P core client doesn't realize we didn't save the
+state. If you don't use this package, you must do this yourself.
+
+Obviously you also have to make sure malicious users won't change the user state
+of others, by rejecting these operations in the authorization/permission system!
diff --git a/docs/usage/h5p-editor-constructor.md b/docs/usage/h5p-editor-constructor.md
@@ -115,6 +115,16 @@ for an implementation sample using the urlGenerator.
 Allows you to customize styles and scripts of the client. Also allows passing in
 a lock implementation (needed for multi-process or clustered setups).
 
+## options.permissionSystem (optional)
+
+By passing in an implementation of `IPermissionSystem` you get fine-grained
+control over who can do what in your system. The library calls the methods of
+`IPermissionSystem` whenever a user performs an action that requires
+authorization.
+
+If you leave options.permissionSystem `undefined`, the library will allow
+everything to everyone!
+
 ## contentUserDataStorage (optional)
 
 The `contentUserDataStorage` handles saving and loading user states, so users

diff --git a/packages/h5p-examples/src/User.ts b/packages/h5p-examples/src/User.ts
@@ -7,16 +7,10 @@ export default class User implements IUser {
     constructor() {
         this.id = '1';
         this.name = 'Firstname Surname';
-        this.canInstallRecommended = true;
-        this.canUpdateAndInstallLibraries = true;
-        this.canCreateRestricted = true;
         this.type = 'local';
         this.email = '[email protected]';
     }
 
-    public canCreateRestricted: boolean;
-    public canInstallRecommended: boolean;
-    public canUpdateAndInstallLibraries: boolean;
     public email: string;
     public id: string;
     public name: string;

diff --git a/packages/h5p-examples/src/expressRoutes.ts b/packages/h5p-examples/src/expressRoutes.ts
@@ -46,6 +46,25 @@ export default function (
                         contextId:
                             typeof req.query.contextId === 'string'
                                 ? req.query.contextId
+                                : undefined,
+                        // You can impersonate other users to view their content
+                        // state by setting the query parameter asUserId.
+                        // Example:
+                        // `/h5p/play/XXXX?asUserId=YYY`
+                        asUserId:
+                            typeof req.query.asUserId === 'string'
+                                ? req.query.asUserId
+                                : undefined,
+                        // You can disabling saving of the user state, but still
+                        // display it by setting the query parameter
+                        // `readOnlyState` to `yes`. This is useful if you want
+                        // to review other users' states by setting `asUserId`
+                        // and don't want to change their state.
+                        // Example:
+                        // `/h5p/play/XXXX?readOnlyState=yes`
+                        readOnlyState:
+                            typeof req.query.readOnlyState === 'string'
+                                ? req.query.readOnlyState === 'yes'
                                 : undefined
                     }
                 );

diff --git a/packages/h5p-express/src/ContentUserDataRouter/ContentUserDataController.ts b/packages/h5p-express/src/ContentUserDataRouter/ContentUserDataController.ts
@@ -37,12 +37,18 @@ export default class ContentUserDataController {
                 ? req.query.contextId
                 : undefined;
 
+        const asUserId =
+            typeof req.query.asUserId === 'string'
+                ? req.query.asUserId
+                : undefined;
+
         const result = await this.contentUserDataManager.getContentUserData(
             contentId,
             dataType,
             subContentId,
             req.user,
-            contextId
+            contextId,
+            asUserId
         );
 
         if (!result || !result.userState) {
@@ -69,6 +75,32 @@ export default class ContentUserDataController {
             typeof req.query.contextId === 'string'
                 ? req.query.contextId
                 : undefined;
+        const asUserId =
+            typeof req.query.asUserId === 'string'
+                ? req.query.asUserId
+                : undefined;
+        const ignorePost =
+            typeof req.query.ignorePost === 'string'
+                ? req.query.ignorePost
+                : undefined;
+
+        // The ignorePost query parameter allows us to cancel requests that
+        // would fail later, when the ContentUserDataManager would deny write
+        // requests to user states. It is necessary, as the H5P JavaScript core
+        // client doesn't support displaying a state while saving is disabled.
+        // We implement this feature by setting a very long autosave frequency,
+        // rejecting write requests in the permission system and using the
+        // ignorePost query parameter.
+        if (ignorePost == 'yes') {
+            res.status(200).json(
+                new AjaxSuccessResponse(
+                    undefined,
+                    'The user state was not saved, as the query parameter ignorePost was set.'
+                )
+            );
+            return;
+        }
+
         const { user, body } = req;
 
         await this.contentUserDataManager.createOrUpdateContentUserData(
@@ -79,7 +111,8 @@ export default class ContentUserDataController {
             body.invalidate === 1 || body.invalidate === '1',
             body.preload === 1 || body.preload === '1',
             user,
-            contextId
+            contextId,
+            asUserId
         );
 
         res.status(200).json(new AjaxSuccessResponse(undefined)).end();

diff --git a/packages/h5p-express/test/ContentUserDataRouter.test.ts b/packages/h5p-express/test/ContentUserDataRouter.test.ts
@@ -102,6 +102,7 @@ describe('ContentUserData endpoint adapter', () => {
             false,
             true,
             user,
+            undefined,
             undefined
         );
         expect(res.status).toBe(200);
@@ -129,7 +130,8 @@ describe('ContentUserData endpoint adapter', () => {
             false,
             true,
             user,
-            'cid1'
+            'cid1',
+            undefined
         );
         expect(res.status).toBe(200);
     });
@@ -150,6 +152,7 @@ describe('ContentUserData endpoint adapter', () => {
             dataType,
             subContentId,
             user,
+            undefined,
             undefined
         );
         expect(res.status).toBe(200);
@@ -170,7 +173,14 @@ describe('ContentUserData endpoint adapter', () => {
 
         expect(
             mockContentUserDataManager.getContentUserData
-        ).toHaveBeenCalledWith(contentId, dataType, subContentId, user, 'cid1');
+        ).toHaveBeenCalledWith(
+            contentId,
+            dataType,
+            subContentId,
+            user,
+            'cid1',
+            undefined
+        );
         expect(res.status).toBe(200);
         expect(res.body).toEqual({
             data: mockReturnData.userState,

diff --git a/packages/h5p-express/test/User.ts b/packages/h5p-express/test/User.ts
@@ -7,16 +7,10 @@ export default class User implements IUser {
     constructor() {
         this.id = '1';
         this.name = 'Firstname Surname';
-        this.canInstallRecommended = true;
-        this.canUpdateAndInstallLibraries = true;
-        this.canCreateRestricted = true;
         this.type = 'local';
         this.email = '[email protected]';
     }
 
-    public canCreateRestricted: boolean;
-    public canInstallRecommended: boolean;
-    public canUpdateAndInstallLibraries: boolean;
     public email: string;
     public id: string;
     public name: string;

diff --git a/packages/h5p-html-exporter/test/HtmlExporter.test.ts b/packages/h5p-html-exporter/test/HtmlExporter.test.ts
@@ -13,6 +13,7 @@ import LibraryManager from '../../h5p-server/src/LibraryManager';
 import PackageImporter from '../../h5p-server/src/PackageImporter';
 import HtmlExporter from '../src/HtmlExporter';
 import { IIntegration } from '../../h5p-server/src/types';
+import { LaissezFairePermissionSystem } from '../../h5p-server';
 
 import User from './User';
 
@@ -31,17 +32,20 @@ async function importAndExportHtml(
             await fsExtra.ensureDir(libraryDir);
 
             const user = new User();
-            user.canUpdateAndInstallLibraries = true;
 
             const contentStorage = new FileContentStorage(contentDir);
-            const contentManager = new ContentManager(contentStorage);
+            const contentManager = new ContentManager(
+                contentStorage,
+                new LaissezFairePermissionSystem()
+            );
             const libraryStorage = new FileLibraryStorage(libraryDir);
             const libraryManager = new LibraryManager(libraryStorage);
             const config = new H5PConfig(null);
 
             const packageImporter = new PackageImporter(
                 libraryManager,
                 config,
+                new LaissezFairePermissionSystem(),
                 contentManager,
                 new ContentStorer(contentManager, libraryManager, undefined)
             );
@@ -222,17 +226,20 @@ describe('HtmlExporter template', () => {
         await fsExtra.ensureDir(libraryDir);
 
         const user = new User();
-        user.canUpdateAndInstallLibraries = true;
 
         const contentStorage = new FileContentStorage(contentDir);
-        const contentManager = new ContentManager(contentStorage);
+        const contentManager = new ContentManager(
+            contentStorage,
+            new LaissezFairePermissionSystem()
+        );
         const libraryStorage = new FileLibraryStorage(libraryDir);
         const libraryManager = new LibraryManager(libraryStorage);
         const config = new H5PConfig(null);
 
         const packageImporter = new PackageImporter(
             libraryManager,
             config,
+            new LaissezFairePermissionSystem(),
             contentManager,
             new ContentStorer(contentManager, libraryManager, undefined)
         );

diff --git a/packages/h5p-html-exporter/test/User.ts b/packages/h5p-html-exporter/test/User.ts
@@ -7,16 +7,10 @@ export default class User implements IUser {
     constructor() {
         this.id = '1';
         this.name = 'Firstname Surname';
-        this.canInstallRecommended = true;
-        this.canUpdateAndInstallLibraries = true;
-        this.canCreateRestricted = true;
         this.type = 'local';
         this.email = '[email protected]';
     }
 
-    public canCreateRestricted: boolean;
-    public canInstallRecommended: boolean;
-    public canUpdateAndInstallLibraries: boolean;
     public email: string;
     public id: string;
     public name: string;

diff --git a/packages/h5p-mongos3/src/MongoContentUserDataStorage.ts b/packages/h5p-mongos3/src/MongoContentUserDataStorage.ts
@@ -93,18 +93,19 @@ export default class MongoContentUserDataStorage
         contentId: ContentId,
         dataType: string,
         subContentId: string,
-        user: IUser,
+        userId: string,
         contextId?: string
     ): Promise<IContentUserData> {
         log.debug(
-            `getContentUserData: loading contentUserData for contentId ${contentId} and userId ${user.id} and contextId ${contextId}`
+            `getContentUserData: loading contentUserData for contentId ${contentId} and userId ${userId} and contextId ${contextId}`
         );
+
         return this.cleanMongoUserData(
             await this.userDataCollection.findOne<IContentUserData>({
                 contentId,
                 dataType,
                 subContentId,
-                userId: user.id,
+                userId: userId,
                 contextId
             })
         );
@@ -193,14 +194,14 @@ export default class MongoContentUserDataStorage
 
     public async getContentUserDataByContentIdAndUser(
         contentId: ContentId,
-        user: IUser,
+        userId: string,
         contextId?: string
     ): Promise<IContentUserData[]> {
         return (
             await this.userDataCollection
                 .find<IContentUserData>({
                     contentId,
-                    userId: user.id,
+                    userId,
                     contextId
                 })
                 .toArray()