@via-profit/ability 2.0.0-rc.8 → 2.1.0

package/README.md

@@ -3,109 +3,92 @@
 > Набор сервисов, частично реализующих
 > принцип [Attribute Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control)
 
-Данный сервис позволяет создать правила или политики, а затем применить их по отношению к каким-либо данным для того
-чтобы проверить наличие доступа к этим данным.
-
-# Draft
+Этот сервис позволяет создавать правила и политики, применять их к данным и проверять доступ на их основе.
 
 ## Содержание
 
-1. [Описание и общие принципы](#overview)
-
-   1.1 [Состав пакета](#structure)
-
-   1.2 [Общие принципы](#principles)
-
-2. [Правила](#rules)
-
-   2.1 [Синтаксис правил](#rule-syntax)
-
-   2.2 [Примеры](#rule-recipes)
+## Оглавление
+- [Обзор](#overview)
+    - [Состав пакета](#structure)
+    - [Основные принципы](#principles)
+- [Правила](#rules)
+    - [Создание правила](#rule-creation)
+    - [Проверка правила](#rule-check)
+- [Группы правил](#rule-sets)
+    - [Создание группы правил](#ruleset-creation)
+    - [Проверка группы правил](#ruleset-check)
+- [Политики](#policies)
+    - [Создание политики](#policy-creattion)
+    - [Проверка политики](#policy-check)
+- [Управление политиками](#policy-management)
 
-   2.3 [Класс AbilityRule](#ability-rule-class)
 
-3. [Политики](#policies)
+---
 
-   3.1 [Синтаксис правил](#policy-syntax)
-
-   3.2 [Примеры](#policy-recipes)
-
-   3.3 [Класс AbilityPolicy](#ability-policy-class)
-
-4. [Создание политики из конфига](#policy-config)
-
-## Описание и общие принципы <a name="overview"></a>
+## Обзор <a name="overview"></a>
 
 ### Состав пакета <a name="structure"></a>
 
-- `AbilityPolicy` - класс политики
-- `AbilityRuleSet` - класс группы правил
-- `AbilityRule` - класс правила
-- `AbilityParser` - парсер конфигурационных правил из/в JSON
-- `AbilityResolver` - класс управления политиками
-- `AbilityMatch` - Класс констант для определния соответствия правил (`PENDING` `MATCH` `MISMATCH`)
-- `AbilityPolicyEffect` - Класс констант для определния эффекта политик (`DENY` `PERMIT`)
-- `AbilityCompare` - Класс констант для определния способа сравнения правил и групп (`OR` `AND`)
-- `AbilityCondition` - Класс констант для определния метода вычисления правил (`EQUAL` `NOT_EQUAL` `MORE_THAN`
-  `LESS_THAN` `LESS_OR_EQUAL` `MORE_OR_EQUAL` `IN` `NOT_IN`)
-- `AbilityError` - Класс инстанса ошибки
-- `AbilityCode` - Базовый клас констанкт
+- **`AbilityRule`** — класс отдельного правила
+- **`AbilityRuleSet`** — класс группы правил
+- **`AbilityPolicy`** — класс политики
+- **`AbilityResolver`** — управление политиками
+- **`AbilityMatch`** — константы состояния правил (`pending`, `match`, `mismatch`)
+- **`AbilityCompare`** — способы сравнения (`or`, `and`)
+- **`AbilityCondition`** — методы вычисления (`equal`, `not_equal`, `more_than`, `less_than`, `in`, `not_in` и др.)
+- **`AbilityPolicyEffect`** — эффекты политики (`deny`, `permit`)
+- **`AbilityParser`** — парсер конфигурационных правил (JSON)
+- **`AbilityError`** — инстанс ошибок
+
+### Основные принципы <a name="principles"></a>
 
-### Общие принципы <a name="principles"></a>
+Работа сервиса основана на формировании **правил**, объединении их в **политики** и проверке доступа с их помощью.
 
-Принцип работы основан на формировании правил, объединения их в политики и запуске этих политик.
+Пример: необходимо **запретить доступ** пользователям, связанным с отделом менеджеров, **за исключением администраторов**.
 
-Предположим, что необходимо запретить доступ пользователям из отдела менеджеров и причастным к ним, за исключением
-администраторов. Пользователи относятся к отделу менеджеров, если их отдел называется `managers`. Причастные
-пользователи являются те пользователи, среди ролей которых имеется роль `manager`. Администраторы - пользователи имеющие
-соответствующую роль (`administrator`).
+- Менеджеры — если их отдел `managers` или есть роль `manager`
+- Администраторы — пользователи с ролью `administrator`
 
-Для решения поставленной задачи нам понадобится объединить несколько правил в группы согласно изображению ниже:
+Структура политики:
 
 ![ability-01.drawio.png](assets/ability-01.drawio.png)
 
-JSON представление такой политики будет иметь следующий вид:
+JSON-конфигурация:
 
 ```json
 {
-  "name": "Запретить доступ пользователям из отдела менеджеров и причастным к ним за исключением администраторов",
-  "compareMethod": 1,
+  "name": "Запрет доступа для менеджеров (исключение: администраторы)",
+  "compareMethod": "and",
   "action": "order.update",
-  "effect": 0,
+  "effect": "deny",
   "ruleSet": [
     {
       "name": "Менеджеры",
-      "compareMethod": 0,
+      "compareMethod": "or",
       "rules": [
         {
-          "name": "Пользователь состоит в отделе managers",
-          "matches": [
-            "user.department",
-            "=",
-            "managers"
-          ]
+          "name": "Отдел managers",
+          "subject": "user.department",
+          "resource": "managers",
+          "condition": "in"
         },
         {
-          "name": "Пользователь имеет роль manager",
-          "matches": [
-            "user.roles",
-            "in",
-            "manager"
-          ]
+          "name": "Роль manager",
+          "subject": "user.roles",
+          "resource": "manager",
+          "condition": "in"
         }
       ]
     },
     {
       "name": "Не администраторы",
-      "compareMethod": 1,
+      "compareMethod": "and",
       "rules": [
         {
-          "name": "Пользователь не является администратором",
-          "matches": [
-            "user.roles",
-            "not in",
-            "administrator"
-          ]
+          "name": "Нет роли administrator",
+          "subject": "user.roles",
+          "resource": "administrator",
+          "condition": "not in"
         }
       ]
     }
@@ -113,154 +96,343 @@ JSON представление такой политики будет имет
 }
 ```
 
-Теперь для того чтобы применить (проверить политику) необходимо её восстановить из JSON (метод `parse`) и запустить
-проверку (метод `check`):
+Применение политики:
 
 ```ts
-const jsonConfig = { ... }
-
-const result = AbilityPolicy.parse(jsonConfig).check({
+const jsonConfig = { ... };
+AbilityPolicy.parse(jsonConfig).check({
   user: {
     department: 'managers',
-    roles: ['manager', 'couch']
+    roles: ['manager', 'coach'],
   }
 });
-````
+```
+
+---
 
 ## Правила <a name="rules"></a>
 
-Правила позволяют создавать условия, которые в последствии будут сгруппированы в группу правил, а те, в свою очередь, в
-политику.
+**Правила** выполняют условие проверки и возвращают результат. **Основная цель** - выполнить сравнение переданных
+значений субъекта и ресурса, а затем вернуть результат такого сравнения.
+
+### Создание правила <a name="rule-creation"></a>
 
-Класс `AbilityRule`
+Создать правило можно двумя способами: создание через конструктор класса и парсинг JSON-конфига правила.
 
-Правило определяется необязательных названием и обязательным массивом `matches`, который и несёт самую важную роль в
-данном модуле.
+При создании необходимо указать следующие параметры:
 
-_Пример простого правила:_
+- **id** - `string` Уникальный идентификатор.
+- **name** - `string` Название правила.
+- **condition** - `AbilityCondition` Определяет условия сравнения переданных данных
+- **subject** - `string` Dot notation путь в проверяемом субъекте, например: `user.name`.
+- **resource** - `string | number | boolean | (string | number)[]` Dot notation путь в проверяемом ресурсе, например:
+  `user.name` или значение, которое может быть строкой, числом, булеан значением или массивом строк или чисел.
+
+_Создание правила через конструктор класса:_
 
 ```ts
 import { AbilityRule, AbilityCondition } from '@via-profit/ability';
 
 const rule = new AbilityRule({
-  name: 'Simple rule',
-  matches: [
-    'user.department', // dot notation путь до проверяемого поля
-    AbilityCondition.EQUAL, // определяет метод сравнения "="
-    'managers' // искомое значение
-  ],
+  id: '<rule-id>',
+  name: 'Пользователь из отдела managers',
+  subject: 'user.department',
+  resource: 'managers',
+  condition: AbilityCondition.equal
 });
 
 ```
 
-Правило выше будет выполнено в случае, если среди проверямых данных будет ключ `user`, содержащий ключ `department`,
-значение которого будет равно (`=`) `managers`
+_Создание правила через парсинг JSON-конфигурации:_
 
-Адрес поля `user.department`, представляет собой запись в
-формате [dot notation](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics#dot_notation), что
-указывает, что для сравнения данных будет использоваться поле department ресурса `user`.
-Для сравнения двух отделов будет использоваться оператор сравнения `=`.
+```ts
+import { AbilityRule } from '@via-profit/ability';
+
+const rule = AbilityRule.parse({
+  "id": "<rule-id>",
+  "name": "Пользователь из отдела managers",
+  "subject": "user.department",
+  "resource": "managers",
+  "condition": "="
+});
 
-Теперь, для того чтобы проверить правило, необходимо выполнить метод `check` передав необходимые ресурсы:
+```
 
-```ts
-import { AbilityRule, AbilityCondition } from '@via-profit/ability';
+### Проверка правила <a name="rule-check"></a>
 
-const rule = new AbilityRule({
-  name: 'Simple rule',
-  matches: [
-    'user.department', // dot notation путь до проверяемого поля
-    AbilityCondition.EQUAL, // определяет метод сравнения "="
-    'managers' // искомое значение
-  ],
+Для проверки правила следует вызвать метод `check` класса `AbilityRule` передав объект проверяемого ресурса. Этот метод
+вернёт экземпляр класса
+`AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение правила и переданных значений.
+
+```ts
+import { AbilityRule } from '@via-profit/ability';
+
+const rule = AbilityRule.parse({
+  "id": "<rule-id>",
+  "name": "Пользователь из отдела managers",
+  "subject": "user.department",
+  "resource": "managers",
+  "condition": "="
 });
 
-const result = rule.check({
+const match = rule.check({
   user: {
     department: 'managers',
-  }
+  },
 });
 
+const is = match.isEqual(AbilityMatch.match); // true
+
 ```
 
-### Синтаксис правил <a name="rule-syntax"></a>
+---
+
+## Группы правил <a name="rule-sets"></a>
+
+**Группы правил** необходимы для объединения нескольких правил в группу. **Основная цель** - выполнить проверку каждого
+правила в группе и вернуть лишь один результат.
+
+Создавая группу следует указывать метод сравнения (`compareMethod`), который необходим для вычисления значения всей
+группы при проверке правил.
+
+При создании необходимо указать следующие параметры:
+
+- **id** - `string` Уникальный идентификатор.
+- **name** - `string` Название группы.
+- **compareMethod** - `AbilityCompare` Способ сравнения правил в группе (`or` или `and`).
+
+_Влияние **compareMethod** на результат вычисления группы:_
+
+- **`or`** - Результат всей группы примет значение `match`, если хотя бы одно из правил вернуло `match`.
+- **`and`** - Результат всей группы примет значение `match`, если все правила вернули `match`.
+
+### Создание группы правил <a name="ruleset-creation"></a>
 
-Для описания правил используется массив следующего типа:
+Создать группу правил можно двумя способами: создание через конструктор класса и парсинг JSON-конфига группы.
+
+_Создание группы через конструктор класса_:
 
 ```ts
-type AbilityRuleMatches = [
-  string, // dot notation путь до поля в субъекте или энвайронменте
-    '=' | '<>' | '>' | '<' | '<=' | '>=' | 'in', // оператор сравнения
-    string | number | boolean, // dot notation путь до поля в ресурсе или энвайронменте или просто значение
-];
+import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
+
+const ruleSet = new AbilityRuleSet({
+  id: '<set-id>',
+  name: 'Название группы',
+  compareMethod: AbilityCompare.and,
+});
+
+// Добавление правил в группу
+ruleSet.addRules([
+  new AbilityRule(...),
+  new AbilityRule(...),
+]);
+
 ```
 
-### Операторы сравнения <a name="rule-operators"></a>
+_Создание группы через парсинг JSON-конфига группы_:
+
+```ts
+import { AbilityRuleSet } from '@via-profit/ability';
+
+const ruleSet = AbilityRuleSet.parse({
+  'id': '<set-id>',
+  'name': 'Название группы',
+  'compareMethod': 'and',
+  'rules': [
+    {
+      'id': '<rule-id>',
+      'name': 'Пользователь из отдела managers',
+      'subject': 'user.department',
+      'resource': 'managers',
+      'condition': '=',
+    },
+  ],
+});
 
-- `AbilityCondition.EQUAL` (`=`) Прямое сравнение
-- `AbilityCondition.NOT_EQUAL` (`<>`) Не равно
-- `AbilityCondition.MORE_THAN` (`>`) Больше
-- `AbilityCondition.LESS_THAN` (`<`) Меньше
-- `AbilityCondition.LESS_OR_EQUAL` (`<=`) Меньше или равно
-- `AbilityCondition.MORE_OR_EQUAL` (`>=`) Больше или равно
-- `AbilityCondition.IN` (`in` Вхождение в массив. Позволяет проверять вхождение значения в массив
-- `AbilityCondition.NOT_IN` (`not in` Нет вхождения в массив. Позволяет проверять отсутствие значения в массив
+```
 
-### Примеры правил <a name="rule-recipes"></a>
+### Проверка группы правил <a name="ruleset-check"></a>
 
-<details>
-<summary>Пользователь старше 21 года</summary>
+Для проверки группы правил следует вызвать метод `check` класса `AbilityRuleSet` передав объект проверяемого ресурса.
+Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
+для группы и переданных значений.
 
 ```ts
-const user = {
-  age: 18,
-};
+import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
 
-const isPermit = new AbilityRule('User age', ['subject.age', '>=', 21]).isPermit(user); // true
+const ruleSet = new AbilityRuleSet({
+  id: '<set-id>',
+  name: 'Название группы',
+  compareMethod: AbilityCompare.and,
+}).addRules([
+  new AbilityRule(...),
+  new AbilityRule(...),
+]);
+
+const match = rule.check({ ... });
+
+const is = match.isEqual(AbilityMatch.match);
 ```
 
-</details>
+___
+
+## Политики <a name="policies"></a>
+
+**Политики** включают в себя группы правил. Основная цель - выполнить проверку всех вложенных групп, сравнить результат
+выполнения групп и вернуть один единственный результат.
+
+### Создание политики <a name="policy-creattion"></a>
+
+Создать политику можно двумя способами: создание через конструктор класса и парсинг JSON-конфига политики.
+
+При создании политики необходимо указать следующие параметры:
+
+- **id** - `string` Уникальный идентификатор.
+- **name** - `string` Название политики.
+- **action** - `string` Ключ политики, в формате Dot notation, определяющий схожесть политик. В названии может
+  применяться символ звездочки (`*`). Политики с одинаковым экшеном обрабатываются вместе как группа политик. Экшен
+  `users.account` не считается похожим с экшеном `users.account.login`, но в это же время `users.account.*` равен экшену
+  `users.account.login` (из-за использования звездочки).
+- **compareMethod** - `AbilityCompare` Метод сравнения групп правил, входящих в политику (`or` или `and`)
+- **effect** - `AbilityPolicyEffect` Определяет итоговый результат всех вычислений (`permit` или `deny`). В слчае
+  использования класса `AbilityResolver` (метод `enforce`) последний выкинет исключение `AbilityError`, если политика
+  вернёт `deny`. Текст сообщения `AbilityError` будет соответствовать названию сработавшей политики. В остальных случаях
+  ничего не произойдет.
+- **ruleSet** - `AbilityRuleSet[]` Массив групп (см. [Группы правил](#rule-sets))
 
-<details>
-<summary>Пользователь имеет роль администратора</summary>
+**Замечание** - Политика может быть запрещающей (`effect` = `deny`) и разрешающей (`effect` = `permit`). Если вам
+необходимо ограничить какой-либо доступ, например, пользователю с недостаточными правами, то следует создавать политику
+с эффектом `deny`.
+
+_Создание политики через конструктор класса_:
 
 ```ts
-const user = {
-  roles: ['administrator', 'manager'],
-};
+import { AbilityPolicy, AbilityCondition } from '@via-profit/ability';
+
+const policy = new AbilityPolicy({
+  id: '<policy-id>',
+  name: 'Пример политики',
+  effect: 'deny',
+  action: 'users.update',
+  compareMethod: 'and',
+  ruleSet: [
+    new AbilityRule({
+      id: '<rule-id>',
+      name: 'Пользователь является владельцем заказа',
+      subject: 'user.id',
+      resource: 'order.owner',
+      condition: AbilityCondition.equal
+    })
+  ]
+});
 
-const isPermit = new AbilityRule('has role', ['subject.roles', 'in', 'administrator']).isPermit(
-  user,
-); // true
 ```
 
-</details>
+_Создание политики через парсинг JSON-конфига_:
 
-<details>
-  <summary>Пользователь является владельцем заказа</summary>
+```ts
+import { AbilityPolicy } from '@via-profit/ability';
+
+const policy = AbilityPolicy.parse({
+  "id": "bb758c1b-1015-4894-ba25-d23156e063cf",
+  "name": "Status hui",
+  "action": "order.status",
+  "effect": "deny",
+  "compareMethod": "and",
+  "ruleSet": [
+    {
+      "id": "9cc009e5-0aa9-453a-a668-cb3f418ced92",
+      "name": "Не администратор",
+      "compareMethod": "and",
+      "rules": [
+        {
+          "id": "4093cd50-e54f-4062-8053-2d3b5966fad3",
+          "name": "Нет роли администраторв",
+          "subject": "account.roles",
+          "resource": "administrator",
+          "condition": "<>"
+        }
+      ]
+    }
+  ]
+});
+
+```
+
+### Проверка политики <a name="policy-check"></a>
+
+Для проверки политики правил следует вызвать метод `check` класса `AbilityPolicy` передав объект проверяемого ресурса.
+Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
+для группы и переданных значений.
 
 ```ts
-const user = {
-  id: '1',
-};
+import { AbilityPolicy } from '@via-profit/ability';
 
-const order = {
-  owner: '1',
-};
+const policy = AbilityPolicy.parse({ ... });
+
+const match = policy.check({ ... });
 
-const isPermit = new AbilityRule('owner', ['subject.id', '=', 'resource.owner']).isPermit(
-  user,
-  order,
-); // true
+const is = match.isEqual(AbilityMatch.match);
 ```
 
-</details>
+___
 
-## Политики <a name="policies"></a>
+## Управление политиками <a name="policy-management"></a>
+
+Для управления политиками реализован специальный класс `AbilityResolver`.
+
+В случае, если вам необходимо запустить лишь разовую проверку данных, то данный раздел можно опустить.
 
-Политики позволяют группировать правила или создавать вложенные друг в друга политики.
+**AbilityResolver** необходим для возможности запуска проверки разных политик в разный период времени.
 
+Политики содержат название экшена (поле `action`) определяемого разработчиком. Запуск метода `enforce` или `resolve`
+отберет из всех переданных политик только те, которые попадают под указанный экшен.
+
+```ts
+import { AbilityPolicy, AbilityPolicyConfig, AbilityResolver } from './AbilityPolicy';
+
+const config: AbilityPolicyConfig[] = [...]; // массив различных политик (JSON)
+const policies: AbilityPolicy<Resources>[] = config.map(cfg => AbilityPolicy.parse(cfg)); // массив уже созданных политик
+
+// Проверка политик  с экшеном `order.create`
+// Варинат 1. Будет выброшено исключение AbilityError
+// c название политики, которая вернула deny,
+// либо ничего не произойдет, если ни одна из политик
+// не вернет deny
+new AbilityResolver(policies).enforce('order.create', {
+  user: { department: 'managers' },
+});
+
+// Вариант 2.
+const isDeny = new AbilityResolver(policies)
+  .resolve('order.create', {
+    user: { department: 'managers' },
+  })
+  .isDeny();
+
+if (isDeny) {
+  throw new AbilityError('Permission denied');
+}
+
+
+// Типы ресурсов, где каждый ключ будет являться название экшена
+type Resources = {
+  ['order.status']: { // <-- название экшена
+    readonly account: { // <-- данные ресурса
+      readonly roles: readonly string[];
+    };
+  };
+  ['order.create']: {
+    readonly user: {
+      readonly department: string;
+    };
+  };
+  ...
+};
+
+```
 
-## Создание политики из конфига <a name="policy-config"></a>
+_Пояснение примера выше. В данном примере создается массив всех политик, а затем запускается проверка политик подходящих
+по указанному экшену, а самое главное, что при помощи типа `Resources`, который необходимо формировать
+вручную, **TypeScript** подскажет какие именно данные следует передать вторым аргументом (ресурс)._
 
-Политику и правила можно создавать не только по средствам классов, но и при помощи конфигураций.