@diwala/guardian

Guardian

This package is based on RBAC functionality which is used to check permission according to plan and authentication of users for both server side it works as middleware and at client side it works like a hook

Folder structure

This is the folder structure we set up for you:

/src
  /authentictor             # Authentication for API side
    index.ts                  # User authentication middleware with jwt
  /core                     # Check permission
    error.ts                  # Error class to throw the error
    index.ts                  # Validate permission and throw error
  /express-guardian         # Middleware for API side
    index.ts                  # Initialization of Middleware
  /guardian-client          # React Hook for Clien side
    index.ts                  # Initialization of hook
  /permissions
    /plans                  # Defined all the permission for plans
    subscription-plans.ts  # Return subscription plan
    user-roles.ts          # Return user roles
/test                      # Test cases
  core.test.ts               # Test cases for all the plans
index,ts                   # Initialization of guardian package
types.ts                   # Defined all enums and interface
.gitignore
package.json
README.md
tsconfig.json

Available Scripts

In the project directory, you can run:

yarn start

This builds to /dist and runs the project in watch mode so any edits you save inside src causes a rebuild to /dist.

yarn test

This will run the unit test cases for all the plans in test/core.test.ts

yarn build

This will create the builds to /dist.

Configuration

Code quality is set up for you with prettier, husky, and lint-staged. Adjust the respective fields in package.json accordingly.

TypeScript

tsconfig.json is set up to interpret dom and esnext types. Adjust according to your needs.

Glossary

• Resource - Contains all the name of resources ( In which we are apply permissions) which is used to define permissions according to the plans based on the Action.

• Action - Contain the list of action. Basically, the action is based on CRUD.

• SubcriptionPlan - Contain the list of plans.

You, can find all the above names in types.ts

Plans Permission Architecture

We have define all the plans and permission based on its action and resource. plan In the plan we only define the resource and action which is true. Different case for plan permission :

• Case 1 - Resource type(DigitalSignature) which has only create and read permission [Resource.DigitalSignature]: { [ActionsCRUD.Create]: {}, [ActionsCRUD.Read]: {} }
• Case 2 - Resource type(Signers) which has only create and update permission with a limit to add & update is 1 [Resource.Signers]: { [ActionsCRUD.Create]: { limit: 1 }, [ActionsCRUD.Update]: { limit: 1 }, }
• Case 3 - Resource type(CredentialTemplate) which has only read and update permission with a permission of classic [Resource.CredentialTemplate]: { [ActionsCRUD.Read]: { templates: TemplatesList }, [ActionsCRUD.Update]: { templates: TemplatesList }, } Note: In TemplatesList you defined the template which have permission

How to use guardian

Finally, we can now ready to understand that how the guardian module will work :

API side (express-guardian)

Plan permission

• Import the expressGuardian from @diwala/guardian package
• Initailize the guardian in middleware and according to role and plan get the instance of guardian and add it in express req object. req['guardian'] = expressGuardian(role, plan); As you can check in the file: authenticator
• For using the guardian just you need to pass the Resource and action i.e.(CRUD) in the guardian which you have added in the request object.If the user have the permission it will return true else it will throw an error. guardian.can(Resource.DigitalSignature).create(); Example : controller.ts

Client Side (Hook guardian-client)

• Import the GuardianClient hook from @diwala/guardian package
• Add the guardian hook in whole react app route. <GuardianClient.Provider>...</GuardianClient.Provider> As you can check in the file: app.js
• Initialize the guardian hook according to the role and plan
  • Get the initializeGuardian from the GuardianClient container const { initializeGuardian } = GuardianClient.useContainer();
  • Then, initializeGuardian with the plan & role initializeGuardian({ plan: currentEntity.subscriptionPlan, role }); Example: auth.js
• For using the guardian hook just you need to pass the Resource and action i.e.(CRUD) if the user have the permission it will return true else it will throw an error. guardian.can(Resource.DigitalSignature).read(); Example : account-signature-data

Authenticator (API side for jwt token with its permissions)

Authenticator is used to

• Check the permission of user according to role
• Used to set the JWT token Usage
• Import the jwtAuthenticator and guardPermissions hook from @diwala/guardian package
• Add the jwtAuthenticator as a middleware with the Secret key it will set the token if authenticated else will return null. jwtAuthenticator(config.SECRET)
• Add the guardPermissions as a middleware with the permissions it will set the token if authenticated else will return null. guardPermissions(permissions) As you can check in the file: app.js

How guardian core works

Guardian core is depends on 2 things action and resource.And it will check the permission if the permission succeed then it will return true else it will throw an error.

How resource works

We have the can method which returns the action on the basis of resources guardian.can(Resource.DigitalSignature)

How action works

We have the method `checkPermission` which validates the permissions
`guardian.can(Resource.DigitalSignature).read();`

Link : core

How express-guardian works

• We have the method expressGuardian which returns the instance of the guardian package according to user role and plan Link : express-guardian

How guardian-client works

• We have the hook method guardianHook for client. In method, we have a method for initializeGuardian which intialize the guardian according to user role and plan with the guardian-core and it set the guardian state. Link : guardian-client