# cascade-permissions
> ### Description
Latest version **1.2.1** (published 2018-11-06) · MIT license · 0 weekly downloads
## Install
```sh
npm install cascade-permissions
pnpm add cascade-permissions
yarn add cascade-permissions
bun add cascade-permissions
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.2.1 |
| Published | 2018-11-06 |
| First published | 2018-08-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | 8.11.3 |
| Dependencies | 2 |
| Unpacked size | 220 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Bryan Chu |
| Maintainers | chulander |
## Links
- npm: https://www.npmjs.com/package/cascade-permissions
- Homepage: https://github.com/Argo-DigitalVentures/cascade-permissions/
- npm.io page: https://npm.io/package/cascade-permissions
## Dependencies (2)
- [cross-env](https://npm.io/package/cross-env.md) ^5.2.0
- [pluralize](https://npm.io/package/pluralize.md) ^7.0.0
## Recent versions
- 1.2.1 (latest) — 2018-11-06
- 0.2.10 (support_ie) — 2018-08-22
- 1.2.0 — 2018-09-13
- 1.1.1 — 2018-09-12
- 1.1.0 — 2018-09-12
- 1.0.0 — 2018-08-23
- 0.2.9 — 2018-08-22
- 0.2.8 — 2018-08-22
- 0.2.7 — 2018-08-21
- 0.2.6 — 2018-08-21
- 0.2.5 — 2018-08-21
- 0.2.4 — 2018-08-21
- 0.2.3 — 2018-08-21
- 0.2.2 — 2018-08-20
- 0.2.1 — 2018-08-19
- … 3 more at https://npm.io/package/cascade-permissions/versions
## README
# Cascade-Permissions
### Description
This package addresses the burden of managing multiple types of users with different, or at times, overlapping permissions.
Background
#### Scaling
While working on an MVP application with role-based users that were:
1. restricted from viewing a particular type of data
2. restricted from viewing a property / properties on an authorized data.
We ran into issues scaling to other business-units as the legacy code base used conditionals which I named "multiple conditional hell"
##### Multiple-Conditional-Hell Example
###### Assume this object represents the relevant data
```javascript
const dataFromStore = {
username: 'someName',
message: 'some message',
chat_room: 'some chat room topic',
creation_date: '2018-08-09',
modified_data: '2018-08-10',
};
```
##### 1. Started with an innucous conditional authorizing the "power_user" role users
```javascript
// Using an ES6-Promise
return getUser(id).then(user => {
if (user.role === 'power_user') {
return dataFromStore;
} else {
return Promise.reject(user);
}
});
```
##### 2. As the application grew, the use-cases expanded
```javascript
return getUser(id).then(user => {
if (user.role === 'power_user' || user.seniority === 'senior') {
return dataFromStore;
} else {
return Promise.reject(user);
}
});
```
##### 3. Expanded some more
```javascript
return getUser(id).then(user => {
if (user.role === 'power_user' || user.seniority === 'senior' || (user.role === 'basic_user' && user.associations.includes('permitted_data'))) {
return dataFromStore;
} else {
return Promise.reject(user);
}
});
```
##### 4. When we moved out of the MVP phase, we encountered the problem that an authorized user required a subset of the permissions.
```javascript
return getUser(id).then(user => {
if (user.role === 'power_user' || user.seniority === 'senior' || (user.role === 'basic_user' && user.associations.includes('permitted_data'))) {
if (user.role === 'basic_user' && user.associations.includes('permitted_data')) {
// have to remove data the user is not authorized to see.
delete dataFromStore.creation_date;
}
return dataFromStore;
} else {
return Promise.reject(user);
}
});
```
How It Works
Using the Javascript's native **prototype-chain** and an "**exclusion**" list approach, role-based permissions become inheritable and therefore, may be cascaded across different groups / subgroups.
Package Features
1. **Inheritable permissions**
- rules changes in the parent is dynamically reflected in the child.
2. **Restrictinng data access**
Using ES6-proxies (sorry IE users) and the user's runtime permissions:
- accessing a restricted property will return undefined
- setting a restricted property will result in an authorization error
Package Limitations
- Still a Proof-of-concept,
- Limited to shallow objects (1 layer deep)
### **Installation**
install package from npm with node 8+ or transpile the package
```sh
npm i cascade-permissions
```
Roles definition
```javascript
// assume there are just three roles, "Admin", "Basic", "Moderator"
// the "values" can be any thing in this POC.
export default function Admin() {
return {
authorized_date: '2018-01-30',
id: 10,
last_active_date: '2018-08-10',
username: 'admin.doe',
};
}
export default function Basic() {
return {
id: 7,
last_active_date: '2018-08-01',
signup_date: '2018-07-25',
username: 'basic.doe',
};
}
export default function Moderator() {
return {
authorized_date: '2018-07-23',
id: 6,
last_active_date: '2018-08-16',
signup_date: '2018-03-20',
username: 'moderator.doe',
};
}
```
Types definition
##### Define Types (of data)
```javascript
// assume there are just three types, "Account", "Message", "Transaction"
// the values "true" can be any thing in this POC.
// account.js
export default function Account() {
return {
first_name: true,
id: true,
last_name: true,
last_active_date: true,
signup_date: true,
username: true,
};
}
// message.js
export default function Message() {
return {
account_id: true,
date: true,
forum: true,
id: true,
message: true,
modified_date: true,
receiver_username: true,
};
}
// transaction.js
export default function Transaction() {
return {
account_id: true,
date: true,
id: true,
invoice_amount: true,
product: true,
purchase_amount: true,
purchase_method: true,
repeated_purchase: true,
tax_amount: true,
};
}
```
### Step 2: Create Domain Rules
Create the rules-specific to a domain (ie. rules for the "Roles")
1. Create domain dictionary (unique keys)
For example, the "roles" dictionary contains the unqiue keys of the keys that define "admin", "basic", and "moderator";
2. Create "exclusion list" domain representation
Invert the definition of an "admin" role to the keys that **do not** represent an "admin" role based of the dictionary (hence "exclusion-list").
#### Exclusion-list formula is [uniqueKeys] - [typeDefinitionKeys] = typeExclusionKeys
3. Create inheritable domain-rules
Create an domain dictionary with its specific types defined by the exclusion list.
```javascript
const Roles = {
authorized_date: true,
id: true,
last_active_date: true,
signup_date: true,
username: true,
[Symbol('admin')]: [
/* adminExclusionList */
],
[Symbol('basic')]: [
/* basicExclusionList */
],
[Symbol('moderator')]: [
/* moderatorExclusionList */
],
};
```
#### Create Domain Rules: Implementation Options
Option 1: Easy way
Provide the definitions as an object to the **CreateDomain** and call the **createRules** helper method
Roles-domain rules
```javascript
import { helper } from 'cascade-permissions';
const { CreateDomain } = helper;
// application-defined types
import admin from './admin';
import basic from './basic';
import moderator from './moderator';
const allRoles = CreateDomain({
admin,
basic,
moderator,
});
const Roles = AllRoles.createRules('roles');
```
Types-domain rules
```javascript
import { helper } from 'cascade-permissions';
const { CreateDomain } = helper;
// application-defined types
import account from './account';
import message from './message';
import transaction from './transaction';
const allTypes = CreateDomain({
account,
**message**,
transaction,
});
const Types = AllTypes.createRules('types');
```
Option 2: Hard / "understand-how-it-works" way
##### A. Create a dictionary / unique list of keys for a domain
###### this is a naive method that works only for shallow objects.
Roles dictionary
```javascript
// using the roles already created above
import account from '../someDirectory/account';
import message from '../someDirectory/message';
import transaction from '../someDirectory/transaction';
const allTypes = Object.assign({}, account(), message(), transaction());
```
Types dictionary
```javascript
// using the roles already created above
import admin from '../someDirectory/admin';
import basic from '../someDirectory/basic';
import moderator from '../someDirectory/moderator';
const allRoles = Object.assign({}, admin(), basic(), moderataor());
```
##### B. Define each type based on an "exclusion list" of keys.
###### The exclusion list formula is **[uniqueKeys] - [typeDefinitionKeys] = typeExclusionKeys**
Example: admin role
###### For example, to define an admin data object
```javascript
const adminObj = {
first_name: 'someFirstName',
last_name: 'someLastName',
username: 'someUsername',
};
const messageObj = {
message: 'some text written here',
username: 'someUserName',
createdDate: '2018-01-01',
modifiedDate: '2018-01-03',
};
const allRolesKeys = ['createdDate', 'first_name', 'last_name', 'message', 'modifiedDate', 'username'];
const adminExclusionKeys = allRolesKeys.filter(item => !Object.keys(adminObj).includes(item)); // ['createdDate', 'message', 'modifiedDate'];
```
##### C. Create domain-rules object via "BaseFactory"
Roles-domain rules
```javascript
import { appSymbols, BaseFactory } from 'cascade-permissions';
const { _defineType } = appSymbols;
const allRolesDictionary = {
// list of unique key + arbitrary values
};
const adminExclusionKeys = [// uniqueKeys that do not represent an admin]
const basicExclusionKeys = [// uniqueKeys that do not represent an basic]
const moderatorExclusionKeys = [// uniqueKeys that do not represent an moderator]
// this return an object that includes a _defineType method;
const Roles = BaseFactory('roles', {}, allRolesDictionary);
Roles[_defineType]('admin', {
restrictedKeys: adminExclusionKeys,
restrictedTypes: ['basic','moderator']
})
Roles[_defineType]('basic', {
restrictedKeys: basicExclusionKeys,
restrictedTypes: ['admin','moderator']
})
Roles[_defineType]('moderator', {
restrictedKeys: moderatorExclusionKeys,
restrictedTypes: ['admin','basic']
})
```
Types-domain rules
```javascript
import { appSymbols, BaseFactory } from 'cascade-permissions';
const { _defineType } = appSymbols;
const allTypesDictionary = {
// list of unique key + arbitrary values
};
const accountExclusionKeys = [// uniqueKeys that do not represent an account]
const messageExclusionKeys = [// uniqueKeys that do not represent an message]
const transactionExclusionKeys = [// uniqueKeys that do not represent an transaction]
// this return an object that includes a _defineType method;
const Types = BaseFactory('types', {}, allTypesDictionary);
Types[_defineType]('account', {
restrictedKeys: accountExclusionKeys,
restrictedTypes: ['message','transaction']
})
Types[_defineType]('message', {
restrictedKeys: messageExclusionKeys,
restrictedTypes: ['account','transaction']
})
Types[_defineType]('transaction', {
restrictedKeys: transactionExclusionKeys,
restrictedTypes: ['account','message']
})
```
### Step 3: Inherit Domain Rules
The fun part begins. How do you inherit these rules for your application?
##### Example assumes application has 2 groups of users "internal" and "external".
```javascript
import { appSymbols, BaseFactory, helper } from 'cascade-permissions';
// assume allRoles is defined as we did earlier
const Roles = allRoles().createRules('rules');
// assume allTypes is defined as we did earlier
const Types = allTypes().createRules('types');
// create a Groups object
const Groups = BaseFactory(
'groups',
{},
{
[Symbol('roles')]: Roles,
[Symbol('types')]: Types,
}
);
```
#### Scenarios
1. Inherting all the rules
##### Situation: "internal" users have zero restrictions
```javascript
Groups[_inherit]('internal', {
restrictedTypes: ['external'],
});
```
The interal user will have all "roles" and all "types"
2. Inherting a subset of the rules
##### Situation: "external" users are restricted from "admin" role and "transaction" type
```javascript
Groups[_inherit]('internal', {
restrictedTypes: ['internal', 'admin', 'transaction'],
});
```
The external user will have all "roles" except the "admin" role, and all "types" except the "transaction" types.
3. Inherting a subset of the rules + global domain key restrictions
#### Situation: "external" users are restricted from "admin" role and "transaction" type. In addition, the "id" property is not authorized any domains.
```javascript
Groups[_inherit]('internal', {
restrictedKeys: ['id'],
restrictedTypes: ['internal', 'admin', 'transaction'],
});
```
The external user will have all "roles" except the "admin" role, and all "types" except the "transaction" types. In addition, any domain types with an "id" property is not visible to the user.
4. Inherting a subset of the rules + domain specific restrictions
#### Situation: "external" users are restricted from "admin" role and "transaction" type. In addition, the "account" type ['first_name', 'last_name'] and "basic" role ['last_active_date'] are not authorized.
```javascript
Groups[_inherit]('internal', {
restrictedKeys: {
account: ['first_name', 'last_name'],
basic: ['last_active_date'],
},
restrictedTypes: ['internal', 'admin', 'transaction'],
});
```
The external user will have all "roles" except the "admin" role, and all "types" except the "transaction" types. In addition, the "basic" role's "last_active_date" and the "account" type's "first_name" & "last_name" are not visible.
5. Name Conficts (domains sharing same name)
#### Situation: Scenario of above step + there is a name conflict. In both the **roles** and **types** domain, there is a "**workspace**" domain type and external user is authorized only for the "types" domain.
```javascript
Groups[_inherit]('internal', {
restrictedKeys: {
account: ['first_name', 'last_name'],
basic: ['last_active_date'],
},
restrictedTypes: ['internal', { [Symbol('types')]: ['transaction'] }, { [Symbol('roles')]: ['admin', 'workspace'] }],
});
```
The external user will have all "roles" except the "admin" and "workspace" role, and all "types" except the "transaction" types. In addition, the "basic" role's "last_active_date" and the "account" type's "first_name" & "last_name" are not visible.