@holoyan/adonisjs-permissions 0.1.0 → 0.5.2

package/README.md

@@ -1,8 +1,8 @@
 # Role permissions system for AdonisJS V6+
 
-## Under development!
+## Beta version
 
-[![test](https://github.com/holoyan/adonisjs-permissions/actions/workflows/test.yml/badge.svg)](https://github.com/holoyan/adonisjs-permissions/actions/workflows/test.yml)
+[//]: # ([![test](https://github.com/holoyan/adonisjs-permissions/actions/workflows/test.yml/badge.svg)](https://github.com/holoyan/adonisjs-permissions/actions/workflows/test.yml))
 [![license](https://poser.pugx.org/silber/bouncer/license.svg)](https://github.com/holoyan/adonisjs-permissions/blob/master/LICENSE.md)
 
 ## Table of Contents
@@ -12,6 +12,10 @@
 - [Introduction](#introduction)
 - [Installation](#installation)
 - [Configuration](#configuration)
+- [Mixins](#mixins)
+- [Support](#support)
+  - [Database support](#database-support)
+  - [UUID support](#uuid-support)
 - [Basic Usage](#basic-usage)
   - [Creating roles and permissions](#creating-roles-and-permissions)
   - [Assigning permissions to the roles (Globally)](#assigning-permissions-to-the-roles-globally)
@@ -30,8 +34,9 @@
   - [Forbidding permissions on a resource](#forbidding-permissions-on-a-resource)
   - [Checking for forbidden permissions](#checking-for-forbidden-permissions)
   - [Unforbidding the permissions](#unforbidding-the-permissions)
-  - [Global v resource permissions (Important!)](#global-v-resource-permissions-important)
+  - [Global vs resource permissions (Important!)](#global-vs-resource-permissions-important)
   - [containsPermission v hasPermission](#containspermission-v-haspermission)
+- [Test](#test)
 - [License](#license)
 </p></details>
 
@@ -56,16 +61,108 @@ await Acl.permission('edit').attachToModel(user);
 // You can also grant a permission only to a specific model
 const post = await Post.first()
 await Acl.model(user).allow('delete', post);
+// or 
+await user.allow('delete', post)
 ```
 
-To be able to use full power of Acl you should have clear understanding how it is structured and works, that's why documentation will be divided into two parts - [Basic usage](#basic-usage) and [Advanced usage](#advanced-usage) .
+To be able to use full power of Acl you should have clear understanding how it is structured and works, that's why documentation will be divided into two parts - [Basic usage](#basic-usage) and [Advanced usage](#digging-deeper) .
 For most of the applications [Basic usage](#basic-usage) will be enough
 
 ## Installation
-    npm install ...
+    
+    npm i @holoyan/adonisjs-permissions
+
+
+Next publish config files
+
+    node ace configure @holoyan/adonisjs-permissions
+this will create permissions.ts file in `configs` and migration file in the `database/migrations` directory
+
+Next run migration
+    
+    node ace migration:run
+
 
 ## Configuration
 
+All models which will interact with `Acl` MUST use `@MorphMap('ALIAS_FOR_CLASS')` decorator and implement `AclModelInterface` contract
+
+Example. 
+
+```typescript
+
+import { BaseModel, column } from '@adonisjs/lucid/orm'
+import { MorphMap } from '@holoyan/adonisjs-permissions'
+import { AclModelInterface } from '@holoyan/adonisjs-permissions/types'
+
+@MorphMap('users')
+export default class User extends BaseModel implements AclModelInterface {
+  getModelId(): number {
+    return this.id
+  }
+  
+  // other code goes here
+}
+
+@MorphMap('admins')
+export default class Admin extends BaseModel implements AclModelInterface {
+  getModelId(): number {
+    return this.id
+  }
+  // other code goes here
+}
+
+@MorphMap('posts')
+export default class Post extends BaseModel implements AclModelInterface {
+  getModelId(): number {
+    return this.id
+  }
+
+  // other code goes here
+}
+
+```
+
+
+## Mixins
+
+If you want to be able to call these methods on a `User` model then consider using `hasPermissions` mixin
+
+```typescript
+
+import { BaseModel, column } from '@adonisjs/lucid/orm'
+import { MorphMap } from '@holoyan/adonisjs-permissions'
+import { AclModelInterface } from '@holoyan/adonisjs-permissions/types'
+
+// import mixin
+import { hasPermissions } from '@holoyan/adonisjs-permissions'
+import { compose } from '@adonisjs/core/helpers'
+
+@MorphMap('users')
+export default class User extends compose(BaseModel, hasPermissions()) implements AclModelInterface {
+  getModelId(): number {
+    return this.id
+  }
+  // other code goes here
+}
+
+// then all methods are available on the user
+
+const user = await User.first()
+const roles = await user.roles() // and so on
+
+
+```
+
+## Support
+
+### Database Support
+
+Currently supported databases: `postgres`, `mysql`, `mssql`
+
+### UUID support
+No uuid support *yet*
+
 ## Basic Usage
 
 On this section we will explore basic role permission methods
@@ -200,7 +297,7 @@ const roles = await Acl.model(user).permissions()
 const models = await Acl.permission(permission).models()
 
 ```
-this will return array of `ModelPermission` which will contain `modelType,modelId` attributes, where `modelType` is *alias* which you had specified in [morphMap decorator](#morph-map-decorator), `modelId` is the value of column, you've specified in [getModelId]() method.
+this will return array of `ModelPermission` which will contain `modelType,modelId` attributes, where `modelType` is *alias* which you had specified in [morphMap decorator](#configuration), `modelId` is the value of column, you've specified in [getModelId](#configuration) method.
 
 Most of the cases you will have only one model (User), it's better to use `modelsFor()` to get  concrete models
 
@@ -242,7 +339,7 @@ you can pass array of roles
 ```typescript
 
 // returns true only if user has all roles
-await Acl.model(user).hasAllRoles(['admin', 'manager']) 
+await Acl.model(user).hasAllRoles('admin', 'manager') 
 
 ```
 
@@ -250,7 +347,7 @@ to check if user has any of roles, will return true if user has at least one rol
 
 ```typescript
 
-await Acl.model(user).hasAnyRole(['admin', 'manager']) 
+await Acl.model(user).hasAnyRole('admin', 'manager') 
 
 ```
 
@@ -550,89 +647,87 @@ await Acl.role(role).containsPermission('delete') // true
 
 ```
 
-### Global v resource permissions (Important!)
+### Global vs resource permissions (Important!)
 
-> Important! Action performed globally will affect on resource models
+> Important! Action performed globally will affect on a resource models
 
 It is very important to understood difference between global and resource permissions and their scope.
 Look at this way, if there is no `entity` model then action will be performed **globally**, otherwise **on resource**
 
-```typescript
-// global actions
-import {Acl} from "@holoyan/adonisjs-permissions";
-
-// Give a user the permission to edit
-await Acl.model(user).allow('edit');
-
-Acl.model(user).assignDirectPermission('uploadFile')
-
-await Acl.model(user).forbid('delete')
-
-await Acl.model(user).hasPermission('create')
-await Acl.model(user).unforbid('delete')
-// ... and so on
-
 ```
 
-```typescript
-// On resource actions
 
-await Acl.role(admin).assign('edit', product1)
-await Acl.model(user).hasPermission('edit', product1)
-await Acl.model(user).assignDirectPermission('edit', Post)
+|--------------Global--------------|
+|                                  |
+|    |------Class level------|     |
+|    |                       |     |
+|    |   |--Model level--|   |     |
+|    |   |               |   |     |
+|    |   |               |   |     |
+|    |   |               |   |     |
+|    |   |---------------|   |     |
+|    |                       |     |
+|    |-----------------------|     |
+|                                  |
+|----------------------------------|
 
 ```
 
-As you can see if `entity` (product1, Post and so on) is specified then it's a *on resource* action
 
-Now let's see few examples
 
 ```typescript
 import {Acl} from "@holoyan/adonisjs-permissions";
+import Post from "#models/post";
 
-// Global action
-await Acl.model(user).allow('edit');
 
-const product1 = Product.first();
+// Global level
+await Acl.model(admin).allow('create');
+await Acl.model(admin).allow('edit');
+await Acl.model(admin).allow('view');
 
-await Acl.model(user).hasPermission('edit') // true
-await Acl.model(user).hasPermission('edit', product1) // true becouse 'edit' permission assigned globaly
-await Acl.model(user).hasPermission('edit', ImageModel) // true becouse 'edit' permission assigned globaly
+// class level
+await Acl.model(manager).allow('create', Post)
 
-```
+// model level
+const myPost = await Post.find(id)
+await Acl.model(client).allow('view', myPost)
 
-Now if do same but assign on Resource, result will be different
-
-```typescript
+// checking
+// admin
+await Acl.model(admin).hasPermission('create') // true
+await Acl.model(admin).hasPermission('create', Post) // true
+await Acl.model(admin).hasPermission('create', myPost) // true
 
-const product1 = Product.first();
+// manager
+await Acl.model(manager).hasPermission('create') // false
+await Acl.model(manager).hasPermission('create', Post) // true
+await Acl.model(manager).hasPermission('create', myPost) // true
+await Acl.model(manager).hasPermission('create', myOtherPost) // true
 
-await Acl.model(user).allow('edit', product1);
-
-await Acl.model(user).hasPermission('edit', product1) // true becouse 'edit' permission assigned to this specific model instance
-
-await Acl.model(user).hasPermission('edit') // false
-await Acl.model(user).hasPermission('edit', Product) // false becouse 'edit' permission assigned to the specific model instance
+// client
+await Acl.model(client).hasPermission('create') // false
+await Acl.model(client).hasPermission('create', Post) // false
+await Acl.model(client).hasPermission('create', myPost) // true
+await Acl.model(client).hasPermission('create', myOtherPost) // false
+// ... and so on
 
 ```
 
-let's see one more example
+Same is true when using `forbidden` action
 
 ```typescript
 
-await Acl.model(user).allow('edit', Product); // assing to Product model, for all Product instances it will be true
+// class level
+await Acl.model(manager).allow('edit', Post) // allow to edit all posts
 
-const product1 = Product.first();
-await Acl.model(user).hasPermission('edit', product1) // true
-const product2 = Product.find(someId);
-await Acl.model(user).hasPermission('edit', product2) // true
-await Acl.model(user).hasPermission('edit', Product) // true
+await Acl.model(manager).forbid('edit', myPost) // forbid editing on a specific post
 
-await Acl.model(user).hasPermission('edit') // false , becouse it's not global, it's only on Product resrouce
 
-```
+await Acl.model(client).hasPermission('edit', Post) // true
+await Acl.model(client).hasPermission('edit', myPost) // false
+await Acl.model(client).hasPermission('edit', myOtherPost) // true
 
-Anytime you can use `containsPermission()` method to check if user has it
+```
 
 ### containsPermission v hasPermission
 
@@ -656,6 +751,12 @@ await Acl.model(user).containsPermission('read') // true
 
 ```
 
+## Test
+
+    npm run test
+
+
 ## License
 
+
 MIT

package/build/index.d.ts

@@ -1,8 +1,14 @@
+import modelRole from './src/models/model_role.js';
+import modelPermission from './src/models/model_permission.js';
+import permission from './src/models/permission.js';
+import role from './src/models/role.js';
+export declare const ModelRole: typeof modelRole;
+export declare const ModelPermission: typeof modelPermission;
+export declare const Permission: typeof permission;
+export declare const Role: typeof role;
 export { configure } from './configure.js';
 export { stubsRoot } from './stubs/main.js';
 export { Acl } from './src/acl.js';
-export * from './src/models/role.js';
-export * from './src/models/permission.js';
-export * from './src/models/model_permission.js';
-export * from './src/models/model_role.js';
 export { MorphMap, getClassPath } from './src/decorators.js';
+export * as morphMapModel from './src/morph_map.js';
+export { hasPermissions } from './src/mixins/has_permissions.js';

package/build/index.js

@@ -6,12 +6,17 @@
 | Export values from the package entrypoint as you see fit.
 |
 */
+import modelRole from './src/models/model_role.js';
+import modelPermission from './src/models/model_permission.js';
+import permission from './src/models/permission.js';
+import role from './src/models/role.js';
+export const ModelRole = modelRole;
+export const ModelPermission = modelPermission;
+export const Permission = permission;
+export const Role = role;
 export { configure } from './configure.js';
 export { stubsRoot } from './stubs/main.js';
 export { Acl } from './src/acl.js';
-export * from './src/models/role.js';
-export * from './src/models/permission.js';
-export * from './src/models/model_permission.js';
-export * from './src/models/model_role.js';
-// export * as HasPermissions from './src/mixins/has_permissions.js'
 export { MorphMap, getClassPath } from './src/decorators.js';
+export * as morphMapModel from './src/morph_map.js';
+export { hasPermissions } from './src/mixins/has_permissions.js';

package/build/providers/role_permission_provider.d.ts

@@ -1,12 +1,15 @@
 import { ApplicationService } from '@adonisjs/core/types';
+import ModelManager from '../src/model_manager.js';
 import MorphMap from '../src/morph_map.js';
 declare module '@adonisjs/core/types' {
     interface ContainerBindings {
         morphMap: MorphMap;
+        modelManager: ModelManager;
     }
 }
 export default class RolePermissionProvider {
     protected app: ApplicationService;
     constructor(app: ApplicationService);
     register(): void;
+    boot(): Promise<void>;
 }

package/build/providers/role_permission_provider.js

@@ -1,3 +1,9 @@
+import Permission from '../src/models/permission.js';
+import Role from '../src/models/role.js';
+import ModelPermission from '../src/models/model_permission.js';
+import ModelRole from '../src/models/model_role.js';
+import ModelManager from '../src/model_manager.js';
+import { Acl } from '../src/acl.js';
 import MorphMap from '../src/morph_map.js';
 export default class RolePermissionProvider {
     app;
@@ -8,5 +14,20 @@ export default class RolePermissionProvider {
         this.app.container.singleton('morphMap', async () => {
             return new MorphMap();
         });
+        this.app.container.singleton('modelManager', async () => {
+            return new ModelManager();
+        });
+    }
+    async boot() {
+        const modelManager = await this.app.container.make('modelManager');
+        modelManager.setModel('permission', Permission);
+        modelManager.setModel('role', Role);
+        modelManager.setModel('modelPermission', ModelPermission);
+        modelManager.setModel('modelRole', ModelRole);
+        Acl.setModelManager(modelManager);
+        const map = await this.app.container.make('morphMap');
+        map.set('permissions', Permission);
+        map.set('roles', Role);
+        Acl.setMorphMap(map);
     }
 }

package/build/src/acl.d.ts

@@ -1,11 +1,16 @@
 import { RoleHasModelPermissions } from './services/roles/role_has_model_permissions.js';
 import { ModelHasRolePermissions } from './services/model_has_role_permissions.js';
-import { AclModel } from './types.js';
-import Role from './models/role.js';
-import Permission from './models/permission.js';
+import { AclModel, MorphInterface, PermissionInterface, RoleInterface } from './types.js';
 import PermissionHasModelRoles from './services/permissions/permission_has_model_roles.js';
+import ModelManager from './model_manager.js';
+import EmptyPermission from './services/permissions/empty_permission.js';
+import EmptyRoles from './services/roles/empty_roles.js';
 export declare class Acl {
+    private static modelManager;
+    private static map;
+    static setModelManager(manager: ModelManager): void;
+    static setMorphMap(map: MorphInterface): void;
     static model(model: AclModel): ModelHasRolePermissions;
-    static role(role: Role | null): typeof Role | RoleHasModelPermissions;
-    static permission(permisison: Permission | null): typeof Permission | PermissionHasModelRoles;
+    static role(role?: RoleInterface): RoleHasModelPermissions | EmptyRoles;
+    static permission(permission?: PermissionInterface): PermissionHasModelRoles | EmptyPermission;
 }

package/build/src/acl.js

@@ -2,28 +2,36 @@ import { RoleHasModelPermissions } from './services/roles/role_has_model_permiss
 import { ModelHasRolePermissions } from './services/model_has_role_permissions.js';
 import PermissionsService from './services/permissions/permissions_service.js';
 import RolesService from './services/roles/roles_service.js';
-import Role from './models/role.js';
-import Permission from './models/permission.js';
 import PermissionHasModelRoles from './services/permissions/permission_has_model_roles.js';
 import ModelService from './services/model_service.js';
+import EmptyPermission from './services/permissions/empty_permission.js';
+import EmptyRoles from './services/roles/empty_roles.js';
 export class Acl {
+    static modelManager;
+    static map;
+    static setModelManager(manager) {
+        this.modelManager = manager;
+    }
+    static setMorphMap(map) {
+        this.map = map;
+    }
     static model(model) {
-        return new ModelHasRolePermissions(model, new RolesService(), new PermissionsService());
+        return new ModelHasRolePermissions(model, new RolesService(this.modelManager.getModel('role'), this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map), new PermissionsService(this.modelManager.getModel('permission'), this.modelManager.getModel('role'), this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map), this.map);
     }
     static role(role) {
         if (role) {
-            return new RoleHasModelPermissions(role, new PermissionsService(), new ModelService());
+            return new RoleHasModelPermissions(role, new PermissionsService(this.modelManager.getModel('permission'), this.modelManager.getModel('role'), this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map), new ModelService(this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map), this.map);
         }
         else {
-            return Role;
+            return new EmptyRoles(this.modelManager.getModel('role'));
         }
     }
-    static permission(permisison) {
-        if (permisison) {
-            return new PermissionHasModelRoles(permisison, new RolesService(), new PermissionsService(), new ModelService());
+    static permission(permission) {
+        if (permission) {
+            return new PermissionHasModelRoles(permission, new RolesService(this.modelManager.getModel('role'), this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map), new PermissionsService(this.modelManager.getModel('permission'), this.modelManager.getModel('role'), this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map), new ModelService(this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map), this.modelManager.getModel('modelPermission'), this.modelManager.getModel('modelRole'), this.map);
         }
         else {
-            return Permission;
+            return new EmptyPermission(this.modelManager.getModel('permission'));
         }
     }
 }

package/build/src/decorators.js

@@ -7,6 +7,7 @@ export function MorphMap(param) {
             return param;
         };
         target.prototype.__morphMapName = service();
+        target.prototype.__morphMapName = param;
     };
 }
 export function getClassPath(clazz) {