@via-profit/ability 2.1.0 → 3.1.0

package/README.md

@@ -2,437 +2,1176 @@
 
 > Набор сервисов, частично реализующих
 > принцип [Attribute Based Access Control](https://en.wikipedia.org/wiki/Attribute-based_access_control)
+> Пакет позволяет описывать правила, объединять их в группы, формировать политики и применять их к данным для определения разрешений.
 
-Этот сервис позволяет создавать правила и политики, применять их к данным и проверять доступ на их основе.
+## Для чего
+
+Пакет задуман как **лёгкая и предельно простая альтернатива** тяжёлым системам управления доступом.  
+Без сложных конфигураций, без зависимостей — только минимальный набор инструментов, который позволяет описывать правила и политики в максимально простом DSL.
 
 ## Содержание
 
-## Оглавление
-- [Обзор](#overview)
-    - [Состав пакета](#structure)
-    - [Основные принципы](#principles)
-- [Правила](#rules)
-    - [Создание правила](#rule-creation)
-    - [Проверка правила](#rule-check)
-- [Группы правил](#rule-sets)
-    - [Создание группы правил](#ruleset-creation)
-    - [Проверка группы правил](#ruleset-check)
-- [Политики](#policies)
-    - [Создание политики](#policy-creattion)
-    - [Проверка политики](#policy-check)
-- [Управление политиками](#policy-management)
+- [Быстрый старт](#быстрый-старт)
+- [Основные положения](#основные-положения)
+- [DSL](#dsl)
+- [Объединение политик](#объединение-политик)
+- [Environment политик](#environment-политик)
+- [Генератор типов для TypeScript](#генератор-типов-для-typescript)
+- [Отладка политик](#отладка-политик)
+- [Решение проблем](#решение-проблем)
+- [Рекомендации по проектированию](#рекомендации-по-проектированию)
+- [Примеры](#примеры)
+- [Производительность](#производительность)
+- [Api-Reference](./docs/ru/api.md)
 
 
----
+## Быстрый старт
 
-## Обзор <a name="overview"></a>
-
-### Состав пакета <a name="structure"></a>
-
-- **`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>
-
-Работа сервиса основана на формировании **правил**, объединении их в **политики** и проверке доступа с их помощью.
-
-Пример: необходимо **запретить доступ** пользователям, связанным с отделом менеджеров, **за исключением администраторов**.
-
-- Менеджеры — если их отдел `managers` или есть роль `manager`
-- Администраторы — пользователи с ролью `administrator`
-
-Структура политики:
-
-![ability-01.drawio.png](assets/ability-01.drawio.png)
-
-JSON-конфигурация:
-
-```json
-{
-  "name": "Запрет доступа для менеджеров (исключение: администраторы)",
-  "compareMethod": "and",
-  "action": "order.update",
-  "effect": "deny",
-  "ruleSet": [
-    {
-      "name": "Менеджеры",
-      "compareMethod": "or",
-      "rules": [
-        {
-          "name": "Отдел managers",
-          "subject": "user.department",
-          "resource": "managers",
-          "condition": "in"
-        },
-        {
-          "name": "Роль manager",
-          "subject": "user.roles",
-          "resource": "manager",
-          "condition": "in"
-        }
-      ]
-    },
-    {
-      "name": "Не администраторы",
-      "compareMethod": "and",
-      "rules": [
-        {
-          "name": "Нет роли administrator",
-          "subject": "user.roles",
-          "resource": "administrator",
-          "condition": "not in"
-        }
-      ]
-    }
-  ]
-}
+Установить пакет, написать DSL, вызвать парсер, запустить резолвер.
+
+### Установка
+
+```bash
+npm install @via-profit/ability
+```
+
+```bash
+yarn add @via-profit/ability
 ```
 
-Применение политики:
+```bash
+pnpm add @via-profit/ability
+```
+
+
+### Пример: запретить доступ к `passwordHash` всем, кроме владельца
+
+Допустим, у нас есть пользовательские данные:
 
 ```ts
-const jsonConfig = { ... };
-AbilityPolicy.parse(jsonConfig).check({
-  user: {
-    department: 'managers',
-    roles: ['manager', 'coach'],
-  }
-});
+const user = {
+  id: '1',
+  login: 'user-001',
+  passwordHash: '...',
+};
+```
+
+Нужно запретить чтение `passwordHash` всем, кроме самого пользователя.
+
+#### DSL‑политика
+
+На языке политик это выглядит так:
+
 ```
+deny permission.user.passwordHash if any:
+  viewer.id is not equals owner.id
+```
+
+**Пояснение:**
+
+- `deny` — эффект политики (запретить доступ)
+- `permission.user.passwordHash` — ключ разрешения.
+- `if any:` — начало блока условий
+- `viewer.id is not equals owner.id` — правило: если идентификатор запрашивающего не равен идентификатору владельца
+
+
+Если `viewer.id` не равен `owner.id`, правило считается выполненным, и политика возвращает `deny` — доступ запрещён. Если же идентификаторы совпадают (т.е. пользователь запрашивает свои собственные данные), правило не срабатывает, и доступ разрешается.
+
+_Замечание: Ключ разрешения формируется по принципу: `permission.` + ваш кастомный ключ в формате **dot notation**, например, ключ `foo.bar.baz` в DSL будет иметь вид `permission.foo.bar.baz`_
+
+#### Проверка в коде
+
+```ts
+import { AbilityDSLParser, AbilityResolver } from '@via-profit/ability';
+
+const dsl = `
+deny permission.user.passwordHash if any:
+  viewer.id is not equals owner.id
+`;
+
+const policies = new AbilityDSLParser(dsl).parse(); // получение политик
+const resolver = new AbilityResolver(policies); // создание резолвера
+
+resolver.enforce('user.passwordHash', {
+  viewer: { id: '1' },
+  owner: { id: '2' },
+}); // выбросит ошибку — доступ запрещён
+```
+В `enforce` передаётся ключ без префикса `permission.` — он автоматически удаляется парсером.
+
+## Основные положения
+
+Тезисно перечислим основные положения, которые необходимо знать перед тем как начать пользоваться пакетом:
+
+1. Резолвер (`AbilityResolver`) настроен по принципу `Default Deny`. Это значит, что если ни одна политика не сработала, то результат будет `deny` ([подробнее здесь](#решение-проблем)). Чтобы избежать неожиданного `deny`, убедитесь, что существует хотя бы одна `permit`‑политика, которая может совпасть. Только после этого добавляйте `deny`‑политики.
+2. Политики применяются последовательно. Если несколько политик совпали, результат определяется последней совпавшей политикой.
+3. Правила выполняются последовательно.
+4. В группе правил (`RuleSet`) с оператором сравнения `all` дальнейшее выполнение правил прекращается как только первое же правило вернёт `mismatch`.
+5. Для составления политик используйте [DSL](#dsl) — это проще и удобнее
+6. Для хранения политик на сервере используйте JSON. Политики возможно экспортировать в JSON и импортировать из JSON
+7. Чаще всего следует опираться на утверждение если разрешение не выдано явно → доступ запрещён.
+8. Используйте встроенный кэш только в случаях, если ваши политики неимоверно сложны и содержат большое количество правил
 
 ---
 
-## Правила <a name="rules"></a>
+## DSL
+
+> DSL - Domain-Specific Language
+
+Ability DSL — это декларативный язык для описания политик доступа.  
+Он позволяет определять правила в человекочитаемой форме, используя простые конструкции: *политики*, *группы*, *правила* и *аннотации*.
+
+### Структура политики
+
+Политика состоит из:
+
+```
+<effect> <permission> if <all|any>:
+  <group>...
+```
+
+Где:
+
+- **effect** — `permit` или `deny`
+- **permission** — строка вида `permission.foo.bar`, где суффикс `permission.` обязателен.
+- **if all:** — все группы должны быть истинны
+- **if any:** — хотя бы одна группа должна быть истинна
+
+Политика может содержать одну или несколько групп правил.
+
+Пример:
 
-**Правила** выполняют условие проверки и возвращают результат. **Основная цель** - выполнить сравнение переданных
-значений субъекта и ресурса, а затем вернуть результат такого сравнения.
+```dsl
+permit permission.order.update if any:
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
 
-### Создание правила <a name="rule-creation"></a>
+  any of:
+    user.roles contains 'developer'
+    user.login is equals 'dev'
+```
+
+> Префикс `permission.` обязателен в DSL, но автоматически удаляется парсером. Внутри системы разрешение хранится как `order.update`.
+
+Пример политики выше гласит - разрешение `permission.order.update` будет разрешено при выполнении одного из двух условий:
+1. user.roles содержит 'admin' **и** user.token не null
+2. user.roles содержит 'developer' **или** user.login равен 'dev'
+
+### Ключ разрешения (permission key)
 
-Создать правило можно двумя способами: создание через конструктор класса и парсинг JSON-конфига правила.
+Ключ разрешения записываются в `dot notation` виде, но поддерживают возможность использования wildcard шаблонов при
+помощи символа `*`. Это позволяет группировать ключи, а так же переопределять политики с похожими ключами.
 
-При создании необходимо указать следующие параметры:
+Если под ключ подходит несколько политик, **выполняются все**. Итог определяется **последней совпавшей политикой**:
 
-- **id** - `string` Уникальный идентификатор.
-- **name** - `string` Название правила.
-- **condition** - `AbilityCondition` Определяет условия сравнения переданных данных
-- **subject** - `string` Dot notation путь в проверяемом субъекте, например: `user.name`.
-- **resource** - `string | number | boolean | (string | number)[]` Dot notation путь в проверяемом ресурсе, например:
-  `user.name` или значение, которое может быть строкой, числом, булеан значением или массивом строк или чисел.
 
-_Создание правила через конструктор класса:_
+**Пример использования шаблонов**
 
+| Политика (permission) | ключ                   | Совпадает |
+|-------------------|------------------------|-----------|
+| `order.*`         | `order.create`         | да |
+| `order.*`         | `order.update`         | да |
+| `order.*`         | `user.create`          | нет |
+| `*.create`        | `order.create`         | да |
+| `*.create`        | `user.create`          | да |
+| `*.create`        | `order.update`         | нет |
+| `user.profile.*`  | `user.profile.update`  | да |
+| `user.profile.*`  | `user.settings.update` | нет |
+
+**Пример политики с wildcard**
 ```ts
-import { AbilityRule, AbilityCondition } from '@via-profit/ability';
-
-const rule = new AbilityRule({
-  id: '<rule-id>',
-  name: 'Пользователь из отдела managers',
-  subject: 'user.department',
-  resource: 'managers',
-  condition: AbilityCondition.equal
-});
+import { AbilityDSLParser, AbilityResolver } from '@via-profit/ability';
+
+// DSL не полный и показан только ради примера
+const dsl = `
+permit permission.order.*
+deny permission.order.update
+`;
+
+const policies = new AbilityDSLParser(dsl).parse();
+const resolver = new AbilityResolver(policies);
+
+await resolver.enforce('order.update', resource); // выбросит AbilityError
+
+```
+
+**Пояснение**
+
+В DSL порядок политик имеет значение:
+последняя совпавшая политика выигрывает.
+
+Поэтому:
+
+1. `permit` `permission.order.*` разрешает всё, что начинается с `order.`
+2. `deny` `permission.order.update` перекрывает это разрешение.
+
+Итог выполнения:
+
+```
+order.update → deny
+order.create → permit
+order.delete → permit
+order.view   → permit
+```
+
+
+### Комментарии
+
+Строки, начинающиеся с символа `#` считаются комментариями и не влияют на результат работы правил и политик.
+
+---
+
+### Аннотации
+
+В настоящий момент поддерживается только одна аннотация ’name’, которая будет использована в качестве имени для политики, либо группы правил, либо правила.
+
+Аннотации задаются через комментарии:
+
+```
+# @name <имя>
+```
+
+Аннотации применяются к **следующей сущности**:
+
+- политике
+- группе
+- правилу
+
+Пример:
+
+```dsl
+# @name can order update
+permit permission.order.update if any:
+  # @name authorized admin
+  all of:
+    # @name contains role admin
+    user.roles contains 'admin'
+```
+
+---
+
+### Группы правил
+
+Группа определяет, как объединяются правила внутри неё:
+
+```
+all of:
+  <rule>
+  <rule>
+
+any of:
+  <rule>
+  <rule>
+```
+
+- `all of:` — логическое AND
+- `any of:` — логическое OR
+
+`all of` - значит, что группа считается выполненной, если все правила внутри группы сработали.
+
+`any of` - значит, что группа считается выполненной, если хотя бы одно правило внутри группы сработало.
+
+Каждая группа внутри политики будет вычисляться независимо от других групп. Итоговая оценка результата будет определена путем сравнения результата вычисления всех групп в политике.
+
+
+Группы могут иметь аннотации:
 
+```dsl
+# @name developer group
+any of:
+  user.roles contains 'developer'
 ```
 
-_Создание правила через парсинг JSON-конфигурации:_
+---
+
+### Правила
+
+Правило — это атомарное условие внутри политики. Оно определяет, при каких данных политика будет считаться совпавшей. С помощью правил задаются условия по которым определяется эффективность политики (`permit` или `deny`)
+
+Правило имеет форму:
+
+```
+<subject> <operator> <value?> — значение указывается не для всех операторов (например, is null не требует значения).
+```
+
+#### Subject (субъект)
+
+Идентификатор в dot‑нотации:
+
+```
+user.roles
+env.time.hour
+order.total
+```
+
+#### Operators (операторы)
+
+_Синонимы — это альтернативные формы записи, которые также поддерживаются парсером._
+
+**Базовые операторы сравнения**
+
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **is equals** | `=`, `==`, `equals` | `age is equals 18` | Строгое равенство | number, string, boolean |
+| **is not equals** | `!=`, `<>`, `not equals` | `role is not equals 'admin'` | Строгое неравенство | number, string, boolean |
+| **greater than** | `>`, `gt` | `age greater than 18` | Больше | number, date |
+| **greater than or equal** | `>=`, `gte` | `age greater than or equal 18` | Больше или равно | number, date |
+| **less than** | `<`, `lt` | `age less than 18` | Меньше | number, date |
+| **less than or equal** | `<=`, `lte` | `age less than or equal 18` | Меньше или равно | number, date |
+
+
+**Null‑операторы**
+
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **is null** | `== null`, `= null` | `middleName is null` | Значение отсутствует | any |
+| **is not null** | `!= null` | `middleName is not null` | Значение присутствует | any |
+
+**Операторы для списков (массивов)**
+
+| Оператор DSL | Синонимы                  | Пример | Описание | Типы |
+|--------------|---------------------------|--------|----------|------|
+| **in [...]** | -                         | `role in ['admin', 'manager']` | Значение входит в список | number, string |
+| **not in [...]** | -                         | `role not in ['banned']` | Значение не входит | number, string |
+| **contains** | `includes`, `has`         | `tags contains 'vip'` | Массив содержит элемент | array |
+| **not contains** | `not includes`, `not has` | `tags not contains 'vip'` | Массив не содержит элемент | array |
+
+
+**Строковые операторы**
+
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **starts with** | `begins with` | `email starts with 'admin@'` | Строка начинается с | string |
+| **not starts with** | — | `email not starts with 'test'` | Строка не начинается с | string |
+| **ends with** | — | `email ends with '.ru'` | Строка заканчивается на | string |
+| **not ends with** | — | `email not ends with '.com'` | Строка не заканчивается на | string |
+| **includes** | `contains substring` | `name includes 'lex'` | Строка содержит подстроку | string |
+| **not includes** | — | `name not includes 'test'` | Строка не содержит подстроку | string |
+
+**Булевые операторы**
+
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **is true** | `= true` | `isActive is true` | Значение истинно | boolean |
+| **is false** | `= false` | `isActive is false` | Значение ложно | boolean |
+
+**Операторы длины**
+
+| Оператор DSL | Синонимы | Пример | Описание | Типы |
+|--------------|----------|--------|----------|------|
+| **length equals** | `len =` | `tags length equals 3` | Длина равна | array, string |
+| **length greater than** | `len >` | `tags length greater than 2` | Длина больше | array, string |
+| **length less than** | `len <` | `tags length less than 5` | Длина меньше | array, string |
+
+#### Value (значение)
+
+Поддерживаются:
+
+- строки `'text'`
+- числа `42`
+- булевы `true` / `false`
+- `null`
+- массивы `[1, 2, 3]` / `['foo', false, null, 1, 2, '999']`
+
+Примеры:
+
+```dsl
+# возраст пользователя больше 18
+user.age greater than 18
+
+# массив ролей содержит роль 'admin'
+user.roles contains 'admin'
+
+# тэг заказа либо 'vip', либо 'priority'
+order.tag in ['vip', 'priority']
+
+# токен пользователя не null
+user.token is not null
+
+# логин пользователя длиннее 12 символов
+user.login length greater than 12
+```
+
+
+
+---
+
+### Неявная группа (implicit group)
+
+Если правила идут без `all of:` или `any of:`, они объединяются оператором политики:
+
+```dsl
+permit permission.order.update if all:
+  user.roles contains 'admin'
+  user.token is not null
+```
+
+Эквивалентно:
+
+```dsl
+permit permission.order.update if all:
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
+```
+
+Неявная группа всегда соответствует оператору политики (`if all` или `if any`).
+
+---
+
+### Полный пример
+
+```dsl
+# @name разрешено обновление заказа
+permit permission.order.update if any:
+
+  # @name если это администратор
+  all of:
+    user.roles contains 'admin'
+    user.token is not null
+
+  # @name если это разработчик
+  any of:
+    user.roles contains 'developer'
+    user.login is equals 'dev'
+```
+
+
+
+## Объединение политик
+
+В реальном проекте следует использовать несколько политик сразу
+
+TODO: использование нескольких политик
+
+## Environment политик
+
+**Environment** — это объект, содержащий данные окружения, которые не принадлежат ни пользователю, ни ресурсу.
+Содержимое объекта определяется разработчиком и может быть любым объектом состоящим из примитивов.
+
+- время запроса,
+- IP‑адрес,
+- параметры устройства,
+- заголовки запроса,
+- контекст сессии,
+- любые другие внешние условия.
+
+**Примеры:**
 
 ```ts
-import { AbilityRule } from '@via-profit/ability';
-
-const rule = AbilityRule.parse({
-  "id": "<rule-id>",
-  "name": "Пользователь из отдела managers",
-  "subject": "user.department",
-  "resource": "managers",
-  "condition": "="
-});
+type Environment = {
+  time: {
+    hour: number;
+  };
+  ip: string;
+  geo: {
+    country: string;
+  };
+};
+```
 
+Environment передаётся в `resolve()` и `enforce()` как третий аргумент:
+
+```ts
+await resolver.resolve('order.update', resource, environment);
+await resolver.enforce('order.update', resource, environment);
 ```
 
-### Проверка правила <a name="rule-check"></a>
+### Использование environment в правилах
+
+В политике можно ссылаться на environment через путь `env.*`.
 
-Для проверки правила следует вызвать метод `check` класса `AbilityRule` передав объект проверяемого ресурса. Этот метод
-вернёт экземпляр класса
-`AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение правила и переданных значений.
+Пример политики, которая запрещает обновление заказов ночью (22:00–06:00).:
+
+```dsl
+# @name Deny updates at night
+deny permission.order.update if all:
+  env.time.hour less than 6 
+  env.time.hour greater or equal than 22
+```
+
+**Извлечение значений из environment**
+
+Если в правиле указан путь:
+
+- `env.*` → значение берётся из environment
+- `user.*`, `order.*`, `profile.*` → из resource
+- литерал (`18`, `"admin"`, `true`) → используется как есть
+
+Пример:
 
 ```ts
-import { AbilityRule } from '@via-profit/ability';
-
-const rule = AbilityRule.parse({
-  "id": "<rule-id>",
-  "name": "Пользователь из отдела managers",
-  "subject": "user.department",
-  "resource": "managers",
-  "condition": "="
-});
+subject: "env.geo.country"
+resource: "user.country"
+condition: "equal"
+```
 
-const match = rule.check({
-  user: {
-    department: 'managers',
-  },
-});
+### Environment в TypeScript
 
-const is = match.isEqual(AbilityMatch.match); // true
+Тип Environment задаётся на уровне `AbilityResolver`:
 
+```ts
+const resolver = new AbilityResolver<Resources, Environment>(policies);
 ```
 
----
+Это позволяет:
 
-## Группы правил <a name="rule-sets"></a>
+- получать автодополнение в IDE,
+- проверять корректность путей `env.*`,
+- избегать ошибок при передаче environment.
 
-**Группы правил** необходимы для объединения нескольких правил в группу. **Основная цель** - выполнить проверку каждого
-правила в группе и вернуть лишь один результат.
+> Если правило использует `env.*`, но environment не передан, то значение `env.*` будет `undefined`, и сравнение будет выполнено так, как если бы environment не было вовсе
 
-Создавая группу следует указывать метод сравнения (`compareMethod`), который необходим для вычисления значения всей
-группы при проверке правил.
 
-При создании необходимо указать следующие параметры:
 
-- **id** - `string` Уникальный идентификатор.
-- **name** - `string` Название группы.
-- **compareMethod** - `AbilityCompare` Способ сравнения правил в группе (`or` или `and`).
+## Генератор типов для TypeScript
 
-_Влияние **compareMethod** на результат вычисления группы:_
+`AbilityParser.generateTypeDefs()` генерирует типы для TypeScript на основе политик, что позволяет не беспокоиться о расхождении между типами и данными в политиках.
 
-- **`or`** - Результат всей группы примет значение `match`, если хотя бы одно из правил вернуло `match`.
-- **`and`** - Результат всей группы примет значение `match`, если все правила вернули `match`.
+**Пример использования**
 
-### Создание группы правил <a name="ruleset-creation"></a>
+Сначала необходимо подготовить массив политик. Политики можно хранить в DSL или в JSON и парсить их в массив готовых политик. В данном примере, для наглядности, политики хранятся в DSL.
 
-Создать группу правил можно двумя способами: создание через конструктор класса и парсинг JSON-конфига группы.
+```ts
+// scripts/policies.ts
+
+import { AbilityDSLParser } from './AbilityDSLParser';
+
+const dsl = `
+# @name Update order
+permit permission.order.update if all:
 
-_Создание группы через конструктор класса_:
+  # @name Owner check
+  all of:
+    # @name User is owner
+    user.id = order.ownerId
+`;
+
+const policies = new AbilityDSLParser(dsl).parse();
+
+export default policies;
+```
 
 ```ts
-import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
+// scripts/generate-types.ts
+import { writeFileSync } from 'node:fs';
+import { AbilityParser } from '@via-profit/ability';
+import policies from './policies.json';
 
-const ruleSet = new AbilityRuleSet({
-  id: '<set-id>',
-  name: 'Название группы',
-  compareMethod: AbilityCompare.and,
-});
+const typedefs = AbilityParser.generateTypeDefs(policies);
+
+writeFileSync('./src/ability/types.generated.ts', typedefs, 'utf8');
+```
 
-// Добавление правил в группу
-ruleSet.addRules([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+**Сгенерированный файл (пример)**
 
+```ts
+// src/ability/types.generated.ts
+
+// Automatically generated by via-profit/ability
+// Do not edit manually
+export type Resources = {
+  'order.update': {
+    readonly user: {
+      readonly id: string;
+    };
+    readonly order: {
+      readonly ownerId: string;
+    };
+  };
+};
 ```
 
-_Создание группы через парсинг 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': '=',
-    },
-  ],
-});
+import { AbilityResolver, AbilityPolicy } from '@via-profit/ability';
+import type { Resources } from './ability/types.generated';
+
+const resolver = new AbilityResolver<Resources>(
+  AbilityPolicy.parseAll(policies),
+);
 
+await resolver.enforce('order.update', {
+  user: { id: 'u1' },
+  order: { ownerId: 'u1' },
+});
 ```
 
-### Проверка группы правил <a name="ruleset-check"></a>
+## Отладка политик
 
-Для проверки группы правил следует вызвать метод `check` класса `AbilityRuleSet` передав объект проверяемого ресурса.
-Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
-для группы и переданных значений.
+### Объяснения
+
+Для упрощения отладки политик применяется специальный класс `AbilityResult`, который уже включён в итоговый результат вычислений. `AbilityResult` инкапсулирует итог применения всех подходящих политик к ключу разрешений и ресурсу.
+
+`AbilityResult` содержит:
+
+- список проверенных политик,
+- методы для определения итогового эффекта,
+- методы для получения объяснений в текстовом представлении.
+
+Пример:
 
 ```ts
-import { AbilityRuleSet, AbilityCompare } from '@via-profit/ability';
+const result = await resolver.resolve('order.update', resource);
 
-const ruleSet = new AbilityRuleSet({
-  id: '<set-id>',
-  name: 'Название группы',
-  compareMethod: AbilityCompare.and,
-}).addRules([
-  new AbilityRule(...),
-  new AbilityRule(...),
-]);
+if (result.isDenied()) {
+  console.log('Access denied');
+}
 
-const match = rule.check({ ... });
+const explanations = result.explain(); // AbilityExplain
 
-const is = match.isEqual(AbilityMatch.match);
+// console.log(explanations.toString());
 ```
 
-___
+### AbilityExplain
 
-## Политики <a name="policies"></a>
+`AbilityExplain` и связанные классы (`AbilityExplainPolicy`, `AbilityExplainRuleSet`, `AbilityExplainRule`) позволяют получить человекочитаемое объяснение:
 
-**Политики** включают в себя группы правил. Основная цель - выполнить проверку всех вложенных групп, сравнить результат
-выполнения групп и вернуть один единственный результат.
+- какая политика сработала,
+- какие группы правил совпали,
+- какие правила не прошли,
+- какой эффект был применён.
 
-### Создание политики <a name="policy-creattion"></a>
+Пример использования:
 
-Создать политику можно двумя способами: создание через конструктор класса и парсинг JSON-конфига политики.
+```ts
+const result = await resolver.resolve('order.update', resource);
+const explanations = result.explain();
 
-При создании политики необходимо указать следующие параметры:
+console.log(explanations.toString());
+```
+
+Пример вывода:
+
+```
+✓ policy «Запрет обновления заказа для менеджеров» is match
+  ✓ ruleSet «Менеджеры» is match
+    ✓ rule «Отдел managers» is match
+    ✗ rule «Роль manager» is mismatch
+  ✓ ruleSet «Не администраторы» is match
+    ✓ rule «Нет роли administrator» is match
+```
+
+### Формат вывода
 
-- **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))
+В настоящий момент поддерживается только один формат вывода - текстовый.
 
-**Замечание** - Политика может быть запрещающей (`effect` = `deny`) и разрешающей (`effect` = `permit`). Если вам
-необходимо ограничить какой-либо доступ, например, пользователю с недостаточными правами, то следует создавать политику
-с эффектом `deny`.
+Вывод строится по принципу: <policy | ruleSet | rule > <название> <is match | is mismatch>
 
-_Создание политики через конструктор класса_:
+
+## Решение проблем
+
+### Модель принятия решений (Default Deny)
+
+> Почему политика `deny` не превращается в `permit`, если её условия не выполнены?
+
+Рассмотрим политику, которая **запрещает** доступ пользователю с возрастом 16 лет:
 
 ```ts
-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 dsl = `
+deny permission.test if all:
+  user.age is equals 16
+`;
+
+const policies = new AbilityDSLParser(dsl).parse();
+const resolver = new AbilityResolver(policies);
+
+const result = await resolver.resolve('test', {
+  user: { age: 16 },
 });
 
+console.log(result.isDenied());  // true  ✔
+console.log(result.isAllowed()); // false ✔
 ```
 
-_Создание политики через парсинг JSON-конфига_:
+В этом случае всё очевидно:  
+условие выполнено → политика совпала → эффект `deny` → доступ запрещён.
+
+**Что происходит, если условия `не выполнены`?**
 
 ```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": "<>"
+const result = await resolver.resolve('test', {
+  user: { age: 12 },
+});
+
+console.log(result.isDenied());  // true  ✔
+console.log(result.isAllowed()); // false ✔
+```
+
+На первый взгляд может показаться, что если условие не выполнено, то политика должна «разрешить» доступ.  
+Но это **не так**.
+
+**Модель принятия решений: `Default Deny`**
+
+`AbilityResolver` использует классическую модель безопасности:
+
+> **Если нет ни одной совпавшей permit‑политики → доступ запрещён.**
+
+**Что происходит в данном примере:**
+
+1. Политика `deny` существует, но её условие **не выполнено**  
+   → политика получает статус `mismatch`.
+
+2. Политика `deny` **не применяется**, потому что условия не совпали.
+
+3. Политики `permit` **нет**.
+
+4. Раз нет ни одной разрешающей политики → итоговое решение:  
+   **deny (по умолчанию)**.
+
+
+**Итог**
+
+- `deny` с совпавшими условиями → **deny**
+- `deny` с несовпавшими условиями → **deny (default deny)**
+- `permit` с совпавшими условиями → **allow**
+- `permit` с несовпавшими условиями → **deny (default deny)**
+
+**Заключение**
+
+**Доступ разрешается только при наличии явного permit.**
+
+## Рекомендации по проектированию
+
+### Именование ключей доступа
+
+- Используйте иерархические ключи: `permission.order.create`, `permission.order.update.status`, `permission.user.profile.update`.
+- Группируйте по доменам: `permission.user.*`, `permission.order.*`, `permission.product.*`.
+- Не смешивайте разные домены в одном ключе.
+
+### Структура данных
+
+- Явно описывайте `Resources` в TypeScript.
+- Не передавайте «лишние» поля — это усложняет понимание.
+- Старайтесь, чтобы структура данных для одного `permission` была стабильной.
+
+### Проектирование политик
+
+- Общие правила — через wildcard (`permission.order.*`).
+- Специфичные ограничения — через точные действия (`permission.order.update`).
+- Для запретов используйте `effect: deny`.
+- Для разрешений — `effect: permit`.
+
+### Типичные ошибки
+
+- Ожидание, что отсутствие совпавших политик означает deny.
+- Смешивание бизнес-логики и политик доступа.
+- Слишком крупные политики с десятками правил — лучше разбивать.
+
+### Пример использования на фронтенде (React)
+
+**Хук для проверки политик**
+
+```tsx
+// hooks/use-ability.ts
+import { useEffect, useState } from 'react';
+import { AbilityResolver } from '@via-profit/ability';
+import { Resources } from './generated-types';
+
+export function useAbility<Permission extends keyof Resources>(
+  resolver: AbilityResolver<Resources>,
+  permission: Permission,
+  resource: Resources[Permission],
+) {
+  const [allowed, setAllowed] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function check() {
+      try {
+        const result = await resolver.resolve(permission, resource);
+        if (!cancelled) {
+          setAllowed(result.isAllowed());
+        }
+      } catch {
+        if (!cancelled) {
+          setAllowed(false);
         }
-      ]
+      }
     }
-  ]
-});
 
+    check();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [resolver, permission, resource]);
+
+  return allowed;
+}
 ```
 
-### Проверка политики <a name="policy-check"></a>
+**Использование в компоненте**
 
-Для проверки политики правил следует вызвать метод `check` класса `AbilityPolicy` передав объект проверяемого ресурса.
-Этот метод вернёт экземпляр класса `AbilityMatch`, при помощи методов которого можно определить имеется ли совпадение
-для группы и переданных значений.
+```tsx
+function OrderUpdateButton({ order, user }) {
+  const allowed = useAbility(resolver, 'order.update', {
+    user,
+    order,
+  });
 
-```ts
-import { AbilityPolicy } from '@via-profit/ability';
+  if (allowed === null) {
+    return null; // или бейдж загрузки
+  }
+
+  if (!allowed) {
+    return null;
+  }
+
+  return <button>Update order</button>;
+}
+```
+
+
+## Примеры
+
+
+### Пример сложной многоступенчатой политики
+
+Ниже - многоступенчатый набор политик, на примере использования в кинотеатре (выдуманный пример).
+
+**Пример демонстрирует:**
+ - работу с ролями (admin, seller, manager, VIP, banned),
+ - временн́ые ограничения (`env.time.hour`),
+ - wildcard‑права (`permission.*`),
+ - ограничения по количеству билетов,
+ - запрет на продажу уже проданных билетов,
+ - комбинацию `permit`/`deny`‑политик,
+ - приоритет политик и модель Default Deny.
+
+
+**Краткое описание правил**
+- **Администратор**  
+  Имеет wildcard‑права (`permission.*`) и может выполнять любые действия.  
+  Может редактировать стоимость билетов.
+
+- **Продавец**  
+  Может продавать билеты только в рабочие часы (09:00–23:00).  
+  Не может продавать билеты, если:
+   - кинотеатр закрыт,
+   - билет уже продан.
+
+- **Менеджер**  
+  Имеет те же права, что и продавец.
+
+- **Покупатели**
+   - Пользователь старше 21 года может покупать билеты.
+   - VIP‑пользователь может покупать билеты в любое время.
+   - Заблокированный пользователь (`status = banned`) не может покупать билеты.
+   - Любой пользователь не может купить более 6 билетов.
+
+
+**Общая диаграмма политик**
+
+```mermaid
+flowchart LR
+
+%% ==== ROLES ====
+
+   subgraph Roles[Роли]
+      A[Администратор]
+      B[Продавец]
+      C[Менеджер]
+   end
+
+   subgraph Buyers[Покупатели]
+      U1[Пользователь > 21]
+      U2[VIP пользователь]
+      U3[Заблокированный пользователь]
+   end
+
+%% ==== ADMIN ====
+
+   A --> A1[Wildcard: permission.*]
+   A --> A2[Редактировать цену билетов]
+
+   A1 --> FINAL[Итоговое решение]
+   A2 --> FINAL
+
+%% ==== SELLER ====
+
+   B --> B1[Продавать билеты]
+
+   B1 -->|09:00–23:00| B2[Разрешено]
+   B1 -->|Вне времени| D2[Запрещено]
+   B1 -->|ticket.status = sold| D3[Запрещено]
+
+   B2 --> FINAL
+   D2 --> FINAL
+   D3 --> FINAL
+
+%% ==== MANAGER ====
+
+   C --> C1[Продавать билеты как продавец]
+   C1 --> FINAL
+
+%% ==== BUYERS ====
 
-const policy = AbilityPolicy.parse({ ... });
+   U1 --> U1A[Покупать билеты]
+   U1A -->|ticketsCount < 6| U1OK[Разрешено]
+   U1A -->|ticketsCount ≥ 6| U1DENY[Запрещено]
 
-const match = policy.check({ ... });
+   U2 --> U2A[Покупать билеты в любое время]
+   U2A -->|ticketsCount < 6| U2OK[Разрешено]
+   U2A -->|ticketsCount ≥ 6| U2DENY[Запрещено]
+
+   U3 --> U3A[Запрещено покупать билеты]
+
+   U1OK --> FINAL
+   U1DENY --> FINAL
+   U2OK --> FINAL
+   U2DENY --> FINAL
+   U3A --> FINAL
+
+%% ==== DENY RULES ====
+
+   D1[Запрещено покупать билеты, если user.status = banned] --> FINAL
 
-const is = match.isEqual(AbilityMatch.match);
 ```
 
-___
+**DSL политик**
+
+```dsl
+############################################################
+# @name Admin can edit ticket price
+permit permission.ticket.price.edit if all:
+  user.role is equals 'admin'
+
+
+############################################################
+# @name Seller can sell tickets during working hours
+permit permission.ticket.sell if all:
+  user.role is equals 'seller'
+  all of:
+    env.time.hour greater than or equal 9
+    env.time.hour less than or equal 23
+
+
+############################################################
+# @name Users older than 21 can buy tickets
+permit permission.ticket.buy if all:
+  user.age greater than 21
+
+
+############################################################
+# @name VIP users can buy tickets anytime
+permit permission.ticket.buy if all:
+  user.isVIP is true
+
+
+############################################################
+# @name Deny buying tickets if user is banned
+deny permission.ticket.buy if all:
+  user.status is equals 'banned'
 
-## Управление политиками <a name="policy-management"></a>
 
-Для управления политиками реализован специальный класс `AbilityResolver`.
+############################################################
+# @name Deny selling tickets if cinema is closed
+deny permission.ticket.sell if all:
+  any of:
+    env.time.hour less than 9
+    env.time.hour greater than 23
 
-В случае, если вам необходимо запустить лишь разовую проверку данных, то данный раздел можно опустить.
 
-**AbilityResolver** необходим для возможности запуска проверки разных политик в разный период времени.
+############################################################
+# @name Manager can do everything seller can
+permit permission.ticket.sell if all:
+  user.role is equals 'manager'
 
-Политики содержат название экшена (поле `action`) определяемого разработчиком. Запуск метода `enforce` или `resolve`
-отберет из всех переданных политик только те, которые попадают под указанный экшен.
+
+############################################################
+# @name Admin wildcard permissions
+permit permission.* if all:
+  user.role is equals 'admin'
+
+
+############################################################
+# @name Limit tickets per user (max 6)
+deny permission.ticket.buy if all:
+  user.ticketsCount greater than or equal 6
+
+
+############################################################
+# @name Cannot sell already sold tickets
+deny permission.ticket.sell if all:
+  ticket.status is equals 'sold'
+
+```
+
+
+Ниже показано, как использовать приведённые выше политики в Node.js + TypeScript.
+
+**Подготовка политик**
 
 ```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' },
+import { AbilityDSLParser } from '@via-profit/ability';
+import cinemaDSL from './policies/cinema.dsl';
+
+export const policies = new AbilityDSLParser(cinemaDSL).parse();
+```
+
+**Создание резолвера**
+
+```ts
+import { AbilityResolver } from '@via-profit/ability';
+import { policies } from './policies';
+
+const resolver = new AbilityResolver(policies);
+```
+
+**Проверка разрешений (enforce)**
+
+Пример: покупка билета.
+
+Метод enforce выбрасывает исключение `AbilityError`, если доступ запрещён.
+
+```ts
+await resolver.enforce('ticket.buy', {
+  user: { age: 25, ticketsCount: 1 },
+  env: { time: { hour: 18 } },
 });
 
-// Вариант 2.
-const isDeny = new AbilityResolver(policies)
-  .resolve('order.create', {
-    user: { department: 'managers' },
-  })
-  .isDeny();
+```
+Если разрешено — код продолжит выполнение.
+Если запрещено — будет выброшено исключение `AbilityError`.
+
 
-if (isDeny) {
-  throw new AbilityError('Permission denied');
+
+**Проверка разрешений без исключений (resolve)**
+
+`resolve` возвращает объект результата:
+
+```ts
+const result = await resolver.resolve('ticket.buy', {
+  user: { age: 25, ticketsCount: 1 },
+  env: { time: { hour: 18 } },
+});
+
+if (result.isAllowed()) {
+  console.log('Покупка разрешена');
+} else {
+  console.log('Покупка запрещена');
 }
 
+```
 
-// Типы ресурсов, где каждый ключ будет являться название экшена
-type Resources = {
-  ['order.status']: { // <-- название экшена
-    readonly account: { // <-- данные ресурса
-      readonly roles: readonly string[];
-    };
-  };
-  ['order.create']: {
-    readonly user: {
-      readonly department: string;
-    };
-  };
-  ...
+**Продавец может продавать только в рабочие часы***
+
+```ts
+await resolver.enforce('ticket.sell', {
+  user: { role: 'seller' },
+  env: { time: { hour: 15 } },
+  ticket: { status: 'available' },
+});
+
+```
+
+**Подготовка данных для резолвера**
+
+В примерах выше в резолвер передаются простые константные объекты:
+
+```ts
+resolver.enforce('ticket.buy', {
+  user: { age: 25 },
+  env: { time: { hour: 18 } },
+});
+```
+
+Это сделано для наглядности. В реальном приложении данные для резолвера должны формироваться динамически — из тех источников, которые доступны вашему серверу.
+
+**Пользователь** (`user`) обычно берётся из:
+
+
+- JWT‑токена
+- сессии
+- базы данных
+- middleware авторизации
+
+Пример:
+
+```ts
+const user = await db.users.findById(session.userId);
+```
+
+**Окружение (Environment)** (`env`)
+
+Это любые внешние параметры, которые могут влиять на доступ:
+
+- текущее время сервера
+- часовой пояс
+- IP‑адрес
+- заголовки запроса
+- конфигурация системы
+
+Пример:
+
+```ts
+const env = {
+  time: {
+    hour: new Date().getHours(),
+  },
+  ip: req.ip,
 };
+```
+
+**Ресурс** (например, `ticket`)
+
+Если действие связано с конкретным объектом — его тоже нужно загрузить:
+
+```ts
+const ticket = await db.tickets.findById(req.params.ticketId);
+```
+
+**Контекст**
+
+Контекст — это объект, который вы передаёте в `resolve` или `enforce`.  
+Он содержит **все данные**, которые могут понадобиться политикам:
+
+- `user` — данные о текущем пользователе
+- `env` — данные окружения (время, IP, география, настройки системы)
+- `resource` или `ticket` — данные о сущности, над которой выполняется действие
+- любые другие объекты, которые вы используете в DSL
+
+**Важно понимать:**
+
+> Контекст формируется под конкретное действие и конкретные политики. Его не нужно хранить заранее — вы собираете его динамически перед вызовом резолвера.
+
+
+## Производительность
+
+В тестах задействовались политики на 10 условий, вложенные поля, environment.
+
+**Tinybench** ([https://github.com/tinylibs/tinybench](https://github.com/tinylibs/tinybench))
+
+| # | Task name                              | Latency avg (ns)      | Latency med (ns)      | Throughput avg (ops/s) | Throughput med (ops/s) | Samples |
+|---|-----------------------------------------|------------------------|------------------------|--------------------------|--------------------------|---------|
+| 0 | resolve() — no cache (heavy rules)      | 646317 ± 0.32%         | 632319 ± 8446.0        | 1555 ± 0.21%             | 1581 ± 21                | 3095    |
+| 1 | resolve() — cold cache (heavy rules)    | 636363 ± 0.38%         | 623092 ± 7885.0        | 1581 ± 0.21%             | 1605 ± 20                | 3143    |
+| 2 | resolve() — warm cache (heavy rules)    | 631328 ± 0.26%         | 621152 ± 6562.5        | 1590 ± 0.17%             | 1610 ± 17                | 3168    |
 
 ```
+Latency (ns)
+650k | ███████████████████████████████████████ resolve() — no cache
+640k | █████████████████████████████████████ resolve() — cold cache
+630k | ████████████████████████████████████ resolve() — warm cache
+      --------------------------------------------------------------
+        no cache            cold cache            warm cache
+```
+
+```
+Throughput (ops/s)
+1600 | ███████████████████████████████████████ resolve() — warm cache
+1590 | ██████████████████████████████████████ resolve() — cold cache
+1580 | █████████████████████████████████████ resolve() — no cache
+      --------------------------------------------------------------
+        no cache            cold cache            warm cache
+
+```
+
 
-_Пояснение примера выше. В данном примере создается массив всех политик, а затем запускается проверка политик подходящих
-по указанному экшену, а самое главное, что при помощи типа `Resources`, который необходимо формировать
-вручную, **TypeScript** подскажет какие именно данные следует передать вторым аргументом (ресурс)._
+## Лицензия
 
+Этот проект лицензирован под лицензией MIT. Подробности в файле [LICENSE](LICENSE).