introduce Roles bridge (#653)

src/definition/accessors/IRead.ts

@@ -5,6 +5,7 @@ import { IMessageRead } from './IMessageRead';
 import { INotifier } from './INotifier';
 import { IOAuthAppsReader } from './IOAuthAppsReader';
 import { IPersistenceRead } from './IPersistenceRead';
+import { IRoleRead } from './IRoleRead';
 import { IRoomRead } from './IRoomRead';
 import { IThreadRead } from './IThreadRead';
 import { IUploadRead } from './IUploadRead';
@@ -46,4 +47,6 @@ export interface IRead {
     getVideoConferenceReader(): IVideoConferenceRead;
 
     getOAuthAppsReader(): IOAuthAppsReader;
+
+    getRoleReader(): IRoleRead;
 }

src/definition/accessors/IRoleRead.ts

@@ -0,0 +1,27 @@
+import { IRole } from '../roles';
+
+/**
+ * Interface for reading roles.
+ */
+export interface IRoleRead {
+    /**
+     * Retrieves a role by its id or name.
+     * @param idOrName The id or name of the role to retrieve.
+     * @param appId The id of the app.
+     * @returns The role, if found.
+     * @returns null if no role is found.
+     * @throws If there is an error while retrieving the role.
+     */
+    getOneByIdOrName(idOrName: IRole['id'] | IRole['name'], appId: string): Promise<IRole | null>;
+
+    /**
+     * Retrieves all custom roles.
+     * @param appId The id of the app.
+     * @returns All custom roles.
+     * @throws If there is an error while retrieving the roles.
+     * @throws If the app does not have the necessary permissions.
+     * @see IRole.protected
+     * @see AppPermissions.role.read
+     */
+    getCustomRoles(appId: string): Promise<Array<IRole>>;
+}

src/definition/accessors/index.ts

@@ -29,6 +29,7 @@ export * from './INotifier';
 export * from './IPersistence';
 export * from './IPersistenceRead';
 export * from './IRead';
+export * from './IRoleRead';
 export * from './IRoomBuilder';
 export * from './IRoomExtender';
 export * from './IRoomRead';

src/definition/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocket.chat/apps-ts-definition",
-  "version": "1.40.0-alpha",
+  "version": "1.41.0-alpha",
   "description": "Contains the TypeScript definitions for the Rocket.Chat Applications.",
   "main": "index.js",
   "typings": "index",

src/definition/roles/IRole.ts

@@ -0,0 +1,8 @@
+export interface IRole {
+    description: string;
+    mandatory2fa?: boolean;
+    name: string;
+    protected: boolean;
+    scope: 'Users' | 'Subscriptions';
+    id: string;
+}

src/definition/roles/index.ts

@@ -0,0 +1,5 @@
+/**
+ * This module exports the IRole interface for defining roles in Rocket.Chat Apps.
+ * @module definition/roles
+ */
+export * from './IRole';

src/server/accessors/Reader.ts

@@ -12,6 +12,7 @@ import {
     IVideoConferenceRead,
 } from '../../definition/accessors';
 import { IOAuthAppsReader } from '../../definition/accessors/IOAuthAppsReader';
+import { IRoleRead } from '../../definition/accessors/IRoleRead';
 import { IThreadRead } from '../../definition/accessors/IThreadRead';
 
 export class Reader implements IRead {
@@ -29,6 +30,7 @@ export class Reader implements IRead {
 
         private oauthApps: IOAuthAppsReader,
         private thread: IThreadRead,
+        private role: IRoleRead,
     ) {}
     public getEnvironmentReader(): IEnvironmentRead {
         return this.env;
@@ -77,4 +79,8 @@ export class Reader implements IRead {
     public getOAuthAppsReader(): IOAuthAppsReader {
         return this.oauthApps;
     }
+
+    public getRoleReader(): IRoleRead {
+        return this.role;
+    }
 }

src/server/accessors/RoleRead.ts

@@ -0,0 +1,15 @@
+import { IRoleRead } from '../../definition/accessors/IRoleRead';
+import { IRole } from '../../definition/roles';
+import { RoleBridge } from '../bridges';
+
+export class RoleRead implements IRoleRead {
+    constructor(private roleBridge: RoleBridge, private appId: string) {}
+
+    public getOneByIdOrName(idOrName: IRole['id'] | IRole['name']): Promise<IRole | null> {
+        return this.roleBridge.doGetOneByIdOrName(idOrName, this.appId);
+    }
+
+    public getCustomRoles(): Promise<Array<IRole>> {
+        return this.roleBridge.doGetCustomRoles(this.appId);
+    }
+}

src/server/accessors/index.ts

@@ -23,6 +23,7 @@ import { OAuthAppsReader } from './OAuthAppsReader';
 import { Persistence } from './Persistence';
 import { PersistenceRead } from './PersistenceRead';
 import { Reader } from './Reader';
+import { RoleRead } from './RoleRead';
 import { RoomBuilder } from './RoomBuilder';
 import { RoomExtender } from './RoomExtender';
 import { RoomRead } from './RoomRead';
@@ -68,6 +69,7 @@ export {
     Persistence,
     PersistenceRead,
     Reader,
+    RoleRead,
     RoomBuilder,
     RoomExtender,
     RoomRead,

src/server/bridges/AppBridges.ts

@@ -13,6 +13,7 @@ import { MessageBridge } from './MessageBridge';
 import { ModerationBridge } from './ModerationBridge';
 import { OAuthAppsBridge } from './OAuthAppsBridge';
 import { PersistenceBridge } from './PersistenceBridge';
+import { RoleBridge } from './RoleBridge';
 import { RoomBridge } from './RoomBridge';
 import { SchedulerBridge } from './SchedulerBridge';
 import { ServerSettingBridge } from './ServerSettingBridge';
@@ -42,7 +43,8 @@ export type Bridge =
     | SchedulerBridge
     | VideoConferenceBridge
     | OAuthAppsBridge
-    | ModerationBridge;
+    | ModerationBridge
+    | RoleBridge;
 
 export abstract class AppBridges {
     public abstract getCommandBridge(): CommandBridge;
@@ -69,4 +71,6 @@ export abstract class AppBridges {
     public abstract getModerationBridge(): ModerationBridge;
 
     public abstract getThreadBridge(): ThreadBridge;
+
+    public abstract getRoleBridge(): RoleBridge;
 }

src/server/bridges/RoleBridge.ts

@@ -0,0 +1,37 @@
+import { IRole } from '../../definition/roles';
+import { PermissionDeniedError } from '../errors/PermissionDeniedError';
+import { AppPermissionManager } from '../managers/AppPermissionManager';
+import { AppPermissions } from '../permissions/AppPermissions';
+import { BaseBridge } from './BaseBridge';
+
+export abstract class RoleBridge extends BaseBridge {
+    public async doGetOneByIdOrName(idOrName: IRole['id'] | IRole['name'], appId: string): Promise<IRole | null> {
+        if (this.hasReadPermission(appId)) {
+            return this.getOneByIdOrName(idOrName, appId);
+        }
+    }
+
+    public async doGetCustomRoles(appId: string): Promise<Array<IRole>> {
+        if (this.hasReadPermission(appId)) {
+            return this.getCustomRoles(appId);
+        }
+    }
+
+    protected abstract getOneByIdOrName(idOrName: IRole['id'] | IRole['name'], appId: string): Promise<IRole | null>;
+    protected abstract getCustomRoles(appId: string): Promise<Array<IRole>>;
+
+    private hasReadPermission(appId: string): boolean {
+        if (AppPermissionManager.hasPermission(appId, AppPermissions.role.read)) {
+            return true;
+        }
+
+        AppPermissionManager.notifyAboutError(
+            new PermissionDeniedError({
+                appId,
+                missingPermissions: [AppPermissions.role.read],
+            }),
+        );
+
+        return false;
+    }
+}

src/server/bridges/index.ts

@@ -13,6 +13,7 @@ import { LivechatBridge } from './LivechatBridge';
 import { MessageBridge } from './MessageBridge';
 import { ModerationBridge } from './ModerationBridge';
 import { PersistenceBridge } from './PersistenceBridge';
+import { RoleBridge } from './RoleBridge';
 import { RoomBridge } from './RoomBridge';
 import { SchedulerBridge } from './SchedulerBridge';
 import { ServerSettingBridge } from './ServerSettingBridge';
@@ -45,4 +46,5 @@ export {
     VideoConferenceBridge,
     IInternalFederationBridge,
     ModerationBridge,
+    RoleBridge,
 };

src/server/managers/AppAccessorManager.ts

@@ -27,6 +27,7 @@ import {
     Persistence,
     PersistenceRead,
     Reader,
+    RoleRead,
     RoomRead,
     SchedulerExtend,
     SchedulerModify,
@@ -177,7 +178,9 @@ export class AppAccessorManager {
 
             const thread = new ThreadRead(this.bridges.getThreadBridge(), appId);
 
-            this.readers.set(appId, new Reader(env, msg, persist, room, user, noti, livechat, upload, cloud, videoConf, oauthApps, thread));
+            const role = new RoleRead(this.bridges.getRoleBridge(), appId);
+
+            this.readers.set(appId, new Reader(env, msg, persist, room, user, noti, livechat, upload, cloud, videoConf, oauthApps, thread, role));
         }
 
         return this.readers.get(appId);

src/server/permissions/AppPermissions.ts

@@ -37,10 +37,18 @@ export const AppPermissions = {
         read: { name: 'room.read' },
         write: { name: 'room.write' },
     },
+    'role': {
+        read: { name: 'role.read' },
+        write: { name: 'role.write' },
+    },
     'message': {
         read: { name: 'message.read' },
         write: { name: 'message.write' },
     },
+    'moderation': {
+        read: { name: 'moderation.read' },
+        write: { name: 'moderation.write' },
+    },
     'threads': {
         read: { name: 'threads.read' },
     },
@@ -99,10 +107,6 @@ export const AppPermissions = {
         read: { name: 'oauth-app.read' },
         write: { name: 'oauth-app.write' },
     },
-    'moderation': {
-        read: { name: 'moderation.read' },
-        write: { name: 'moderation.write' },
-    },
 };
 
 export const defaultPermissions: Array<IPermission> = [
@@ -138,4 +142,6 @@ export const defaultPermissions: Array<IPermission> = [
     AppPermissions.apis.default,
     AppPermissions.moderation.read,
     AppPermissions.moderation.write,
+    AppPermissions.role.read,
+    AppPermissions.role.write,
 ];

tests/server/accessors/Reader.spec.ts

@@ -6,6 +6,7 @@ import {
     IMessageRead,
     INotifier,
     IPersistenceRead,
+    IRoleRead,
     IRoomRead,
     IUploadRead,
     IUserRead,
@@ -29,6 +30,7 @@ export class ReaderAccessorTestFixture {
     private oauthApps: IOAuthAppsReader;
 
     private thread: IThreadRead;
+    private role: IRoleRead;
 
     @SetupFixture
     public setupFixture() {
@@ -44,6 +46,7 @@ export class ReaderAccessorTestFixture {
         this.videoConf = {} as IVideoConferenceRead;
         this.oauthApps = {} as IOAuthAppsReader;
         this.thread = {} as IThreadRead;
+        this.role = {} as IRoleRead;
     }
 
     @Test()
@@ -63,6 +66,7 @@ export class ReaderAccessorTestFixture {
                     this.videoConf,
                     this.oauthApps,
                     this.thread,
+                    this.role,
                 ),
         ).not.toThrow();
 
@@ -79,6 +83,7 @@ export class ReaderAccessorTestFixture {
             this.videoConf,
             this.oauthApps,
             this.thread,
+            this.role,
         );
 
         Expect(rd.getEnvironmentReader()).toBeDefined();
@@ -90,5 +95,6 @@ export class ReaderAccessorTestFixture {
         Expect(rd.getLivechatReader()).toBeDefined();
         Expect(rd.getUploadReader()).toBeDefined();
         Expect(rd.getVideoConferenceReader()).toBeDefined();
+        Expect(rd.getRoleReader()).toBeDefined();
     }
 }

tests/test-data/bridges/appBridges.ts

@@ -10,6 +10,7 @@ import {
     MessageBridge,
     ModerationBridge,
     PersistenceBridge,
+    RoleBridge,
     RoomBridge,
     SchedulerBridge,
     ServerSettingBridge,
@@ -36,6 +37,7 @@ import { TestsMessageBridge } from './messageBridge';
 import { TestsModerationBridge } from './moderationBridge';
 import { TestOAuthAppsBridge } from './OAuthAppsBridge';
 import { TestsPersisBridge } from './persisBridge';
+import { TestsRoleBridge } from './roleBridge';
 import { TestsRoomBridge } from './roomBridge';
 import { TestSchedulerBridge } from './schedulerBridge';
 import { TestsServerSettingBridge } from './serverSettingBridge';
@@ -55,6 +57,7 @@ export class TestsAppBridges extends AppBridges {
     private readonly msgBridge: TestsMessageBridge;
     private readonly moderationBridge: TestsModerationBridge;
     private readonly persisBridge: TestsPersisBridge;
+    private readonly roleBridge: TestsRoleBridge;
     private readonly roomBridge: TestsRoomBridge;
     private readonly internalBridge: TestsInternalBridge;
     private readonly userBridge: TestsUserBridge;
@@ -81,6 +84,7 @@ export class TestsAppBridges extends AppBridges {
         this.msgBridge = new TestsMessageBridge();
         this.moderationBridge = new TestsModerationBridge();
         this.persisBridge = new TestsPersisBridge();
+        this.roleBridge = new TestsRoleBridge();
         this.roomBridge = new TestsRoomBridge();
         this.internalBridge = new TestsInternalBridge();
         this.userBridge = new TestsUserBridge();
@@ -143,6 +147,9 @@ export class TestsAppBridges extends AppBridges {
     public getThreadBridge(): ThreadBridge {
         return this.threadBridge;
     }
+    public getRoleBridge(): RoleBridge {
+        return this.roleBridge;
+    }
 
     public getRoomBridge(): RoomBridge {
         return this.roomBridge;

tests/test-data/bridges/roleBridge.ts

@@ -0,0 +1,12 @@
+import { IRole } from '../../../src/definition/roles';
+import { RoleBridge } from '../../../src/server/bridges';
+
+export class TestsRoleBridge extends RoleBridge {
+    public getOneByIdOrName(idOrName: IRole['id'] | IRole['name'], appId: string): Promise<IRole | null> {
+        throw new Error('Method not implemented.');
+    }
+
+    public getCustomRoles(appId: string): Promise<Array<IRole>> {
+        throw new Error('Method not implemented.');
+    }
+}