Skip to content

Commit 2b1e4a2

Browse files
vhidvzvhidvz
committed
📃 docs: update
1 parent 7d4c12e commit 2b1e4a2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+213
-123
lines changed

‎README.md

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,46 @@ The Attribute-Based Access-Control Library let you define five `can` access abil
2121

2222
## Quick Start Guide
2323

24-
> Read more on defining `scoped` `action` and `object` ability in this [link](https://vhidvz.github.io/blog/post-abac/).
24+
### ABAC vs RBAC?
25+
26+
| **Question** | **RBAC** | **ABAC** |
27+
| ------------------ | --------------------------------- | ------------------------------------------- |
28+
| Who can access? | :heavy_check_mark: | :heavy_check_mark: |
29+
| How can operate? | :white_check_mark: CRUD | :heavy_check_mark: With more options |
30+
| What resource? | :white_check_mark: Not Bad At All | :heavy_check_mark: More control on resource |
31+
| Where user can do? | :x: | :heavy_check_mark: Supported by IP and CIDR |
32+
| When user can do? | :x: | :heavy_check_mark: Supported by CRON |
33+
| Best structure? | Monolithic Apps | PWA, Restfull, GraphQL |
34+
| Suitable for? | Small and medium projects | Medium and large projects |
35+
36+
### What's Scope?
37+
38+
Definition as a verb is:
39+
40+
- look at carefully; scan.
41+
- assess or investigate something.
42+
43+
In this library, I have scoped `action` and `object` which means you can have more control over these attributes.
44+
45+
Assume you have a publisher website with four types of users with the following roles:
46+
47+
- `admin` super user can do anything
48+
- `manager` can do anything on articles
49+
- `guest` can read only published article
50+
- `user` the writers with limitations on time and location of article creation.
51+
52+
In microservice design patterns and restful's based on my opinion one of the best practices has focused on resource management, a single endpoint with a concentration on objects is better than having multiple endpoints or having complex business logic.
53+
54+
Now, if you want to handle all these policies in one place (e.g. `GET endpoint` read permission) how you can do this?
55+
we suppose you use the `scoped` policy or `ability` grant definition instead of having multiple endpoints or having complex business logic.
2556

2657
### installation
2758

2859
```sh
2960
npm install --save abacl
3061
```
3162

32-
### Usage
63+
### Usage and Dangling
3364

3465
Define your user policies as a json array, so you can store it in your database:
3566

@@ -122,7 +153,7 @@ const article = {
122153
Create a new access control object, then get the permission grants:
123154

124155
```ts
125-
import AccessControl, { normalize } from 'abacl';
156+
import AccessControl from 'abacl';
126157

127158
// The `strict` `AccessControlOption` control the scoped functionality
128159
// default strict value is true, you can change it on the `can` method
@@ -131,7 +162,7 @@ const ac = new AccessControl(policies, { strict: false });
131162
const permission = ac.can([user.subject], 'read', 'article');
132163

133164
// change strict mode dynamically, Example:
134-
// const strictPermission = ac.can([user.subject], 'read', 'article', undefined, { strict: true });
165+
// const strictPermission = ac.can([user.subject], 'read', 'article', { strict: true });
135166

136167
/**
137168
* it('should change strict mode dynamically', () => {
@@ -140,7 +171,7 @@ const permission = ac.can([user.subject], 'read', 'article');
140171
* expect(ac.can([Role.User], 'read', 'article:published').granted).toBeFalsy();
141172
*
142173
* // After changing strict mode
143-
* expect(ac.can([Role.User], 'read', 'article:published', undefined, { strict: false }).granted).toBeTruthy();
174+
* expect(ac.can([Role.User], 'read', 'article:published', { strict: false }).granted).toBeTruthy();
144175
* });
145176
*
146177
* */

‎docs/classes/AccessControl.html

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ <h4>Hierarchy</h4>
2929
<ul class="tsd-hierarchy">
3030
<li><span class="target">AccessControl</span></li></ul></section><aside class="tsd-sources">
3131
<ul>
32-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L12">classes/acl.class.ts:12</a></li></ul></aside>
32+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L12">classes/acl.class.ts:12</a></li></ul></aside>
3333
<section class="tsd-panel-group tsd-index-group">
3434
<section class="tsd-panel tsd-index-panel">
3535
<details class="tsd-index-content tsd-index-accordion" open><summary class="tsd-accordion-summary tsd-index-summary">
@@ -80,19 +80,19 @@ <h5><span class="tsd-kind-parameter">policies</span>: <a href="../interfaces/Pol
8080
<h5><code class="tsd-tag ts-flagOptional">Optional</code> <span class="tsd-kind-parameter">options</span>: <a href="../interfaces/ControlOptions.html" class="tsd-signature-type tsd-kind-interface">ControlOptions</a></h5></li></ul></div>
8181
<h4 class="tsd-returns-title">Returns <a href="AccessControl.html" class="tsd-signature-type tsd-kind-class">AccessControl</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources">
8282
<ul>
83-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L16">classes/acl.class.ts:16</a></li></ul></aside></li></ul></section></section>
83+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L16">classes/acl.class.ts:16</a></li></ul></aside></li></ul></section></section>
8484
<section class="tsd-panel-group tsd-member-group">
8585
<h2>Properties</h2>
8686
<section class="tsd-panel tsd-member tsd-is-protected"><a id="options" class="tsd-anchor"></a>
8787
<h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagProtected">Protected</code> <code class="tsd-tag ts-flagReadonly">Readonly</code> <span>options</span><a href="#options" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
8888
<div class="tsd-signature"><span class="tsd-kind-property">options</span><span class="tsd-signature-symbol">:</span> <a href="../interfaces/ControlOptions.html" class="tsd-signature-type tsd-kind-interface">ControlOptions</a><span class="tsd-signature-symbol"> = {}</span></div><aside class="tsd-sources">
8989
<ul>
90-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L13">classes/acl.class.ts:13</a></li></ul></aside></section>
90+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L13">classes/acl.class.ts:13</a></li></ul></aside></section>
9191
<section class="tsd-panel tsd-member tsd-is-protected"><a id="present" class="tsd-anchor"></a>
9292
<h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagProtected">Protected</code> <span>present</span><a href="#present" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
9393
<div class="tsd-signature"><span class="tsd-kind-property">present</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type ">Record</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">, </span><a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol"> = {}</span></div><aside class="tsd-sources">
9494
<ul>
95-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L14">classes/acl.class.ts:14</a></li></ul></aside></section></section>
95+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L14">classes/acl.class.ts:14</a></li></ul></aside></section></section>
9696
<section class="tsd-panel-group tsd-member-group">
9797
<h2>Accessors</h2>
9898
<section class="tsd-panel tsd-member"><a id="policies" class="tsd-anchor"></a>
@@ -102,7 +102,7 @@ <h3 class="tsd-anchor-link"><span>policies</span><a href="#policies" aria-label=
102102
<li class="tsd-description">
103103
<h4 class="tsd-returns-title">Returns <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">[]</span></h4><aside class="tsd-sources">
104104
<ul>
105-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L31">classes/acl.class.ts:31</a></li></ul></aside></li>
105+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L31">classes/acl.class.ts:31</a></li></ul></aside></li>
106106
<li class="tsd-signature" id="policies.policies-2"><span class="tsd-signature-symbol">set</span> policies<span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">policies</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">void</span></li>
107107
<li class="tsd-description">
108108
<div class="tsd-parameters">
@@ -112,7 +112,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
112112
<h5><span class="tsd-kind-parameter">policies</span>: <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">[]</span></h5></li></ul></div>
113113
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><aside class="tsd-sources">
114114
<ul>
115-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L25">classes/acl.class.ts:25</a></li></ul></aside></li></ul></section></section>
115+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L25">classes/acl.class.ts:25</a></li></ul></aside></li></ul></section></section>
116116
<section class="tsd-panel-group tsd-member-group">
117117
<h2>Methods</h2>
118118
<section class="tsd-panel tsd-member"><a id="can" class="tsd-anchor"></a>
@@ -133,7 +133,7 @@ <h5><span class="tsd-kind-parameter">object</span>: <span class="tsd-signature-t
133133
<h5><code class="tsd-tag ts-flagOptional">Optional</code> <span class="tsd-kind-parameter">options</span>: <a href="../interfaces/CanOptions.html" class="tsd-signature-type tsd-kind-interface">CanOptions</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h5></li></ul></div>
134134
<h4 class="tsd-returns-title">Returns <a href="Permission.html" class="tsd-signature-type tsd-kind-class">Permission</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources">
135135
<ul>
136-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L58">classes/acl.class.ts:58</a></li></ul></aside></li></ul></section>
136+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L58">classes/acl.class.ts:58</a></li></ul></aside></li></ul></section>
137137
<section class="tsd-panel tsd-member"><a id="delete" class="tsd-anchor"></a>
138138
<h3 class="tsd-anchor-link"><span>delete</span><a href="#delete" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
139139
<ul class="tsd-signatures">
@@ -146,7 +146,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
146146
<h5><span class="tsd-kind-parameter">policy</span>: <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h5></li></ul></div>
147147
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">boolean</span></h4><aside class="tsd-sources">
148148
<ul>
149-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L39">classes/acl.class.ts:39</a></li></ul></aside></li></ul></section>
149+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L39">classes/acl.class.ts:39</a></li></ul></aside></li></ul></section>
150150
<section class="tsd-panel tsd-member"><a id="exists" class="tsd-anchor"></a>
151151
<h3 class="tsd-anchor-link"><span>exists</span><a href="#exists" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
152152
<ul class="tsd-signatures">
@@ -159,7 +159,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
159159
<h5><span class="tsd-kind-parameter">policy</span>: <a href="../interfaces/Policy.html" class="tsd-signature-type tsd-kind-interface">Policy</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">Sub</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Act</span><span class="tsd-signature-symbol">, </span><span class="tsd-signature-type tsd-kind-type-parameter">Obj</span><span class="tsd-signature-symbol">&gt;</span></h5></li></ul></div>
160160
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">boolean</span></h4><aside class="tsd-sources">
161161
<ul>
162-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L35">classes/acl.class.ts:35</a></li></ul></aside></li></ul></section>
162+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L35">classes/acl.class.ts:35</a></li></ul></aside></li></ul></section>
163163
<section class="tsd-panel tsd-member"><a id="update" class="tsd-anchor"></a>
164164
<h3 class="tsd-anchor-link"><span>update</span><a href="#update" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
165165
<ul class="tsd-signatures">
@@ -174,7 +174,7 @@ <h5><span class="tsd-kind-parameter">policy</span>: <a href="../interfaces/Polic
174174
<h5><span class="tsd-kind-parameter">deep_copy</span>: <span class="tsd-signature-type">boolean</span><span class="tsd-signature-symbol"> = true</span></h5></li></ul></div>
175175
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4><aside class="tsd-sources">
176176
<ul>
177-
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/361d74c/src/classes/acl.class.ts#L43">classes/acl.class.ts:43</a></li></ul></aside></li></ul></section></section></div>
177+
<li>Defined in <a href="https://github.com/vhidvz/abacl/blob/7d4c12e/src/classes/acl.class.ts#L43">classes/acl.class.ts:43</a></li></ul></aside></li></ul></section></section></div>
178178
<div class="col-sidebar">
179179
<div class="page-menu">
180180
<div class="tsd-navigation settings">

0 commit comments

Comments
 (0)