fix(loopback4-authorization): CasbinResourceModifierFn definition and readme update (#15)

* fix(loopback4-authorization): CasbinResourceModifierFn definition and readme update

SFO-154 SFO-160

* docs(loopback4-authorization): adding inline comments

SFO-154

* feat(loopback4-authorization): changes to load model from string or via code
SFO-160

* docs(loopback4-authorization): update readme for model initilization methods
SFO-160

* docs(loopback4-authorization): model-policy formats documentation
SFO-160

Author: vineet-suri

README.md

@@ -23,7 +23,6 @@ It provides three ways of integration
 
 [Extension enhancement using CASBIN authorisation](#Extension-enhancement-using-CASBIN-authorisation)
 
-
 Refer to the usage section below for details on integration
 
 ## Install
@@ -119,6 +118,7 @@ export class User extends Entity implements UserPermissionsOverride<string> {
   }
 }
 ```
+
 - For method #3, we also provide a simple provider function [_AuthorizationBindings.USER_PERMISSIONS_](<[./src/providers/user-permissions.provider.ts](https://github.com/sourcefuse/loopback4-authorization/blob/master/src/providers/user-permissions.provider.ts)>) to evaluate the user permissions based on its role permissions and user-level overrides. Just inject it
 
 ```ts
@@ -271,7 +271,8 @@ export const enum PermissionKey {
 
 # Extension enhancement using CASBIN authorisation
 
-As a further enhancement to these methods, we are using [casbin library!](https://casbin.org/docs/en/overview) to define permissions at level of entity or resource associated with an API call. Casbin authorisation implementation can be performed in two ways:
+As a further enhancement to these methods, we are using [casbin library](https://casbin.org/docs/en/overview) to define permissions at level of entity or resource associated with an API call. Casbin authorisation implementation can be performed in two ways:
+
 1. **Using default casbin policy document** - Define policy document in default casbin format in the app, and configure authorise decorator to use those policies.
 2. **Defining custom logic to form dynamic policies** - Implement dynamic permissions based on app logic in casbin-enforcer-config provider. Authorisation extension will dynamically create casbin policy using this business logic to give the authorisation decisions.
 
@@ -295,6 +296,7 @@ this.bind(AuthorizationBindings.CASBIN_RESOURCE_MODIFIER_FN).toProvider(
   CasbinResValModifierProvider,
 );
 ```
+
 - Implement the **Casbin Resource value modifier provider**. Customise the resource value based on business logic using route arguments parameter in the provider.
 
 ```ts
@@ -303,22 +305,32 @@ import {HttpErrors} from '@loopback/rest';
 import {
   AuthorizationBindings,
   AuthorizationMetadata,
-  CasbinResourceModifierFn
+  CasbinResourceModifierFn,
 } from 'loopback4-authorization';
 
 export class CasbinResValModifierProvider
   implements Provider<CasbinResourceModifierFn> {
   constructor(
     @inject.getter(AuthorizationBindings.METADATA)
     private readonly getCasbinMetadata: Getter<AuthorizationMetadata>,
+    @inject(AuthorizationBindings.PATHS_TO_ALLOW_ALWAYS)
+    private readonly allowAlwaysPath: string[],
   ) {}
 
   value(): CasbinResourceModifierFn {
-    return (pathParams: string[]) => this.action(pathParams);
+    return (pathParams: string[], req: Request) => this.action(pathParams, req);
   }
 
-  async action(pathParams: string[]): Promise<string> {
+  async action(pathParams: string[], req: Request): Promise<string> {
     const metadata: AuthorizationMetadata = await this.getCasbinMetadata();
+
+    if (
+      !metadata &&
+      !!this.allowAlwaysPath.find(path => req.path.indexOf(path) === 0)
+    ) {
+      return '';
+    }
+
     if (!metadata) {
       throw new HttpErrors.InternalServerError(`Metadata object not found`);
     }
@@ -330,40 +342,77 @@ export class CasbinResValModifierProvider
     return `${res}`;
   }
 }
-
 ```
-- Implement the **casbin enforcer config provider** . Provide the casbin model path. In case 1 of using [default casbin format policy!](https://casbin.org/docs/en/how-it-works), provide the casbin policy path. In other case of creating dynamic policy, provide the array of Resource-Permission objects for a given user, based on business logic.
+
+- Implement the **casbin enforcer config provider** . Provide the casbin model path. Model definition can be initialized from [.CONF file, from code, or from a string](https://casbin.org/docs/en/model-storage).
+  In the case of policy creation being handled by extension (isCasbinPolicy parameter is false), provide the array of Resource-Permission objects for a given user, based on business logic.
+  In other case, provide the policy from file or as CSV string or from [casbin Adapters](https://casbin.org/docs/en/adapters).
+  **NOTE**: In the second case, if model is initialized from .CONF file, then any of the above formats can be used for policy. But if model is being initialised from code or string, then policy should be provided as [casbin adapter](https://casbin.org/docs/en/adapters) only.
 
 ```ts
 import {Provider} from '@loopback/context';
-import {CasbinConfig, CasbinEnforcerConfigGetterFn, IAuthUserWithPermissions} from 'loopback4-authorization';
+import {
+  CasbinConfig,
+  CasbinEnforcerConfigGetterFn,
+  IAuthUserWithPermissions,
+} from 'loopback4-authorization';
 import * as path from 'path';
 
 export class CasbinEnforcerConfigProvider
   implements Provider<CasbinEnforcerConfigGetterFn> {
   constructor() {}
 
   value(): CasbinEnforcerConfigGetterFn {
-    return (authUser: IAuthUserWithPermissions, resource: string, isCasbinPolicy?: boolean) =>
-      this.action(authUser, resource, isCasbinPolicy);
+    return (
+      authUser: IAuthUserWithPermissions,
+      resource: string,
+      isCasbinPolicy?: boolean,
+    ) => this.action(authUser, resource, isCasbinPolicy);
   }
 
-  async action(authUser: IAuthUserWithPermissions, resource: string, isCasbinPolicy?: boolean): Promise<CasbinConfig> {
-    const model = path.resolve(
-      __dirname,
-      './../../fixtures/casbin/model.conf',
-    );
+  async action(
+    authUser: IAuthUserWithPermissions,
+    resource: string,
+    isCasbinPolicy?: boolean,
+  ): Promise<CasbinConfig> {
+    const model = path.resolve(__dirname, './../../fixtures/casbin/model.conf'); // Model initialization from file path
+    /**
+     * import * as casbin from 'casbin';
+     *
+     * To initialize model from code, use
+     *      let m = new casbin.Model();
+     *      m.addDef('r', 'r', 'sub, obj, act'); and so on...
+     *
+     * To initialize model from string, use
+     *      const text = `
+     *      [request_definition]
+     *     r = sub, obj, act
+     *
+     *      [policy_definition]
+     *      p = sub, obj, act
+     *
+     *      [policy_effect]
+     *      e = some(where (p.eft == allow))
+     *
+     *      [matchers]
+     *      m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
+     *       `;
+     *      const model = casbin.newModelFromString(text);
+     */
 
     // Write business logic to find out the allowed resource-permission sets for this user. Below is a dummy value.
     //const allowedRes = [{resource: 'session', permission: "CreateMeetingSession"}];
 
-    const policy = path.resolve(__dirname, './../../fixtures/casbin/policy.csv');
+    const policy = path.resolve(
+      __dirname,
+      './../../fixtures/casbin/policy.csv',
+    );
 
     const result: CasbinConfig = {
       model,
       //allowedRes,
-      policy
-    }
+      policy,
+    };
     return result;
   }
 }
@@ -418,10 +467,10 @@ export class MySequence implements SequenceHandler {
     protected authenticateRequest: AuthenticateFn<AuthUser>,
     @inject(AuthenticationBindings.CLIENT_AUTH_ACTION)
     protected authenticateRequestClient: AuthenticateFn<AuthClient>,
-    @inject(AuthorizationBindings.AUTHORIZE_ACTION)
-    protected checkAuthorisation: AuthorizeFn,
-    @inject(AuthorizationBindings.USER_PERMISSIONS)
-    private readonly getUserPermissions: UserPermissionsFn<string>,
+    @inject(AuthorizationBindings.CASBIN_AUTHORIZE_ACTION)
+    protected checkAuthorisation: CasbinAuthorizeFn,
+    @inject(AuthorizationBindings.CASBIN_RESOURCE_MODIFIER_FN)
+    protected casbinResModifierFn: CasbinResourceModifierFn,
   ) {}
 
   async handle(context: RequestContext) {

src/providers/casbin-authorization-action.provider.ts

@@ -54,24 +54,28 @@ export class CasbinAuthorizationProvider
         );
       }
 
-      const subject = this.getUserName(`${user.id}`);
+      if (!user.id) {
+        throw new HttpErrors.Unauthorized(`User not found.`);
+      }
 
-      // const object = resource;
+      const subject = this.getUserName(`${user.id}`);
 
       let desiredPermissions;
 
+      //Fetch permissions to check from decorator metadata
       if (metadata.permissions && metadata.permissions.length > 0) {
         desiredPermissions = metadata.permissions;
       } else {
         throw new HttpErrors.Unauthorized(
           `Permissions are missing in the decorator.`,
         );
       }
-      // Fetch casbin config by invoking casbin-config-getter-provider
 
+      // Fetch casbin config by invoking casbin-config-getter-provider
       const casbinConfig = await this.getCasbinEnforcerConfig(
         user,
         metadata.resource,
+        metadata.isCasbinPolicy,
       );
 
       let enforcer: casbin.Enforcer;
@@ -92,17 +96,20 @@ export class CasbinAuthorizationProvider
         const baseDir = path.join(__dirname, '../../src/policy.csv');
         await fsPromises.writeFile(baseDir, policy);
 
-        enforcer = await casbin.newEnforcer(casbinConfig.model, baseDir);
+        const policyAdapter = new casbin.FileAdapter(baseDir);
+
+        enforcer = await casbin.newEnforcer(casbinConfig.model, policyAdapter);
       } else {
         return false;
       }
 
+      // Use casbin enforce method to get authorization decision
       for (const permission of desiredPermissions) {
         const decision = await enforcer.enforce(subject, resource, permission);
         authDecision = authDecision || decision;
       }
     } catch (err) {
-      throw new HttpErrors.Unauthorized(err);
+      throw new HttpErrors.Unauthorized(err.message);
     }
 
     return authDecision;
@@ -115,6 +122,7 @@ export class CasbinAuthorizationProvider
     return `u${id}`;
   }
 
+  // Create casbin policy for user based on ResourcePermission data provided by extension client
   createCasbinPolicy(
     resPermObj: ResourcePermissionObject[],
     subject: string,

src/types.ts

@@ -1,4 +1,5 @@
 import {Request} from '@loopback/express';
+import {FileAdapter, Model} from 'casbin';
 import PostgresAdapter from 'casbin-pg-adapter';
 
 /**
@@ -106,15 +107,15 @@ export interface CasbinEnforcerConfigGetterFn {
  * for integration with casbin, as per business logic
  */
 export interface CasbinResourceModifierFn {
-  (pathParams: string[]): Promise<string>;
+  (pathParams: string[], req: Request): Promise<string>;
 }
 
 /**
  * Casbin config object
  */
 export interface CasbinConfig {
-  model: string;
-  policy?: string | PostgresAdapter;
+  model: string | Model;
+  policy?: string | PostgresAdapter | FileAdapter;
   allowedRes?: ResourcePermissionObject[];
 }