> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Управление доступом (RBAC + ABAC)

> Гибкая система ролей, разрешений и политик доступа для админ-панели Cabinet

## Обзор

Cabinet включает полноценную систему управления доступом, объединяющую два подхода:

* **RBAC** (Role-Based Access Control) — роли с набором разрешений и иерархией уровней
* **ABAC** (Attribute-Based Access Control) — политики с условиями (время, IP-адреса)

> [!WARNING]
>
> Система RBAC/ABAC работает **только в Cabinet**. В Telegram-боте доступ администраторов по-прежнему определяется через `ADMIN_IDS`.

> **Роли и разрешения**
>
> 30+ секций с индивидуальными действиями. Поддержка wildcard-паттернов.

> **Политики ABAC**
>
> Ограничение по времени суток, IP-адресам. Правило «запрет побеждает».

> **Журнал аудита**
>
> Неизменяемый лог всех действий администраторов с экспортом в CSV.

## Совместимость с legacy-доступом

Система полностью обратно совместима. Администраторы из `ADMIN_IDS` и `ADMIN_EMAILS` автоматически получают полный доступ (`*:*`) с синтетическим уровнем 1000 — выше любой RBAC-роли. RBAC-роли нужны только для дополнительных сотрудников с ограниченным доступом.

```env theme={null}
# Legacy-администраторы (обходят RBAC, получают все разрешения)
ADMIN_IDS=123456789,987654321
ADMIN_EMAILS=admin@example.com
```

## Роли

### Иерархия уровней

Каждая роль имеет уровень (level) от 0 до 999. Пользователь может управлять только ролями **ниже** своего уровня.

| Уровень | Назначение | Пример |
| - | - | - |
| 0 | Наблюдатель / аналитик | Просмотр статистики |
| 1–499 | Поддержка, модераторы | Работа с тикетами, пользователями |
| 500–998 | Менеджеры, тимлиды | Управление тарифами, рассылками |
| 999 | Суперадмин | Полный доступ (`*:*`) |
| 1000 | Legacy (ADMIN\_IDS) | Автоматически, не редактируется |

### Предустановленные шаблоны

При создании роли доступны готовые шаблоны разрешений:

| Шаблон | Разрешения |
| - | - |
| **Модератор** | Пользователи, тикеты, бан-система, трафик |
| **Маркетолог** | Рассылки, промокоды, кампании, рекламные предложения, статистика |
| **Саппорт** | Тикеты (чтение, ответ), пользователи (чтение) |

Шаблоны можно модифицировать — они задают начальный набор разрешений при создании роли.

### Системные роли

Роли с флагом `is_system=true` нельзя удалить. Последний суперадмин (level 999) защищён от удаления.

## Разрешения

### Формат

Каждое разрешение — строка в формате `секция:действие`:

```
users:read         — просмотр пользователей
users:edit         — редактирование профилей
users:*            — все действия с пользователями
*:*                — полный доступ ко всему
```

### Реестр разрешений

> **Пользователи (users)**
>
> `read` `edit` `block` `delete` `sync` `promo_group` `balance` `subscription` `send_offer` `referral`

> **Тикеты (tickets)**
>
> `read` `reply` `close` `settings`

> **Статистика (stats)**
>
> `read` `export`

> **Рассылки (broadcasts)**
>
> `read` `create` `edit` `delete` `send`

> **Тарифы (tariffs)**
>
> `read` `create` `edit` `delete`

> **Промокоды (promocodes)**
>
> `read` `create` `edit` `delete`

> **Промогруппы (promo\_groups)**
>
> `read` `create` `edit` `delete`

> **Рекламные предложения (promo\_offers)**
>
> `read` `create` `edit` `delete` `send`

> **Рекламные кампании (campaigns)**
>
> `read` `create` `edit` `delete` `stats`

> **Партнёры (partners)**
>
> `read` `approve` `revoke`

> **Выводы (withdrawals)**
>
> `read` `approve` `reject` `complete`

> **Платежи (payments)**
>
> `read`

> **Платёжные методы (payment\_methods)**
>
> `read` `edit`

> **Серверы (servers)**
>
> `read` `create` `edit` `delete` `sync`

> **RemnaWave (remnawave)**
>
> `read` `sync` `manage`

> **Трафик (traffic)**
>
> `read`

> **Настройки (settings)**
>
> `read` `edit`

> **Роли (roles)**
>
> `read` `create` `edit` `delete` `assign`

> **Журнал аудита (audit\_log)**
>
> `read` `export`

> **Прочее**
>
> `channels` · `ban_system` · `wheel` · `apps` · `email_templates` · `pinned_messages` · `updates` — у каждой секции свой набор действий

### Wildcard-сопоставление

Разрешения поддерживают glob-паттерны (fnmatch):

| Паттерн | Что разрешает |
| - | - |
| `users:read` | Только просмотр пользователей |
| `users:*` | Все действия с пользователями |
| `*:read` | Чтение во всех секциях |
| `*:*` | Полный доступ |

## Политики ABAC

Политики ABAC **дополняют** RBAC — они оцениваются после проверки разрешений роли. Политика может разрешить или **запретить** доступ с учётом условий.

### Эффекты

| Эффект | Описание |
| - | - |
| `allow` | Разрешить доступ (если RBAC уже разрешил) |
| `deny` | Запретить доступ (приоритет выше allow) |

**Правило:** если хотя бы одна политика deny совпала — доступ запрещён, независимо от разрешений роли.

### Условия

> **Временной диапазон**
>
> Ограничение по времени (UTC). Формат: `{"start": "09:00", "end": "18:00"}`

> **IP-адреса**
>
> Белый список IP: `["192.168.1.0/24", "10.0.0.1"]`. Поддерживает CIDR и отдельные адреса.

### Примеры политик

**Запретить удаление пользователей в нерабочее время:**

```json theme={null}
{
  "name": "Запрет удаления после 18:00",
  "resource": "users",
  "actions": ["delete"],
  "effect": "deny",
  "conditions": {
    "time_range": { "start": "18:00", "end": "09:00" }
  }
}
```

**Доступ к админке только из офисной сети:**

```json theme={null}
{
  "name": "Только офис",
  "resource": "*",
  "actions": ["*"],
  "effect": "deny",
  "priority": 1000,
  "conditions": {
    "ip_whitelist": ["203.0.113.0/24", "198.51.100.1"]
  }
}
```

### Приоритет

Политики оцениваются в порядке `priority` (больше = раньше). Первая совпавшая deny-политика немедленно блокирует доступ.

## Назначение ролей

### Базовое назначение

Роль назначается пользователю через админ-панель Cabinet: **Роли → Пользователи роли → Назначить**.

### Временное назначение

Роль может иметь дату истечения (`expires_at`). После этой даты роль автоматически деактивируется — удобно для подрядчиков и временных сотрудников.

### Множественные роли

Пользователь может иметь несколько ролей одновременно. Итоговые разрешения — **объединение** всех разрешений из активных ролей.

## Журнал аудита

Все действия администраторов записываются в неизменяемый журнал аудита:

| Поле | Описание |
| - | - |
| Действие | Что было сделано (create, edit, delete и т.д.) |
| Ресурс | Тип и ID объекта (user, tariff, broadcast и т.д.) |
| Статус | `success` или `denied` |
| IP-адрес | Откуда было выполнено действие |
| Детали | Тело запроса и ответа (JSON) |
| Время | Точная метка времени |

### Фильтрация

Журнал поддерживает фильтрацию по:

* Пользователю
* Действию
* Типу ресурса
* Статусу (успех / отказ)
* Диапазону дат

### Экспорт

Журнал можно экспортировать в CSV-файл. Требуется разрешение `audit_log:export`.

## Управление через UI

Админ-панель Cabinet содержит полноценный интерфейс для управления RBAC/ABAC:

**1. Роли**

Раздел **Роли** (`/admin/roles`) — список ролей с цветовыми метками, количеством пользователей. Создание и редактирование ролей с матрицей разрешений.

**2. Назначение**

Внутри каждой роли — список пользователей и кнопка назначения. Указание срока действия для временного доступа.

**3. Политики**

Раздел **Политики** (`/admin/policies`) — создание ABAC-правил с конструктором условий (время, IP). Привязка к конкретной роли или глобальная.

**4. Аудит**

Раздел **Журнал аудита** (`/admin/audit-log`) — просмотр истории всех действий с фильтрами и экспортом.

### Защита интерфейса

Каждый элемент UI защищён проверкой разрешений:

* **Маршруты** — `PermissionRoute` блокирует доступ к страницам без нужного разрешения
* **Элементы** — `PermissionGate` скрывает кнопки и секции, если нет соответствующего разрешения
* **API** — каждый endpoint проверяет разрешение через `require_permission()` и логирует результат

## API-эндпоинты

Базовый путь: `/cabinet/admin/rbac`

### Роли

| Метод | Путь | Разрешение | Описание |
| - | - | - | - |
| GET | `/roles` | `roles:read` | Список ролей |
| POST | `/roles` | `roles:create` | Создание роли |
| PUT | `/roles/{id}` | `roles:edit` | Обновление роли |
| DELETE | `/roles/{id}` | `roles:delete` | Удаление роли |

### Назначения

| Метод | Путь | Разрешение | Описание |
| - | - | - | - |
| POST | `/assignments` | `roles:assign` | Назначить роль |
| DELETE | `/assignments/{id}` | `roles:assign` | Отозвать роль |
| GET | `/roles/{id}/users` | `roles:read` | Пользователи роли |

### Политики

| Метод | Путь | Разрешение | Описание |
| - | - | - | - |
| GET | `/policies` | `roles:read` | Список политик |
| POST | `/policies` | `roles:create` | Создание политики |
| PUT | `/policies/{id}` | `roles:create` | Обновление политики |
| DELETE | `/policies/{id}` | `roles:create` | Удаление политики |

### Аудит

| Метод | Путь | Разрешение | Описание |
| - | - | - | - |
| GET | `/audit-log` | `audit_log:read` | Журнал с фильтрами |
| GET | `/audit-log/export` | `audit_log:export` | Экспорт CSV |

### Реестр

| Метод | Путь | Разрешение | Описание |
| - | - | - | - |
| GET | `/permissions` | `roles:read` | Список всех доступных разрешений |

## Безопасность

> **Иерархия ролей**
>
> Нельзя создавать, редактировать или назначать роли с уровнем ≥ своему. Последний суперадмин защищён от удаления.

> **Deny побеждает**
>
> Одна deny-политика ABAC блокирует доступ, даже если RBAC-роль разрешает.

> **IP-логирование**
>
> IP-адрес извлекается из X-Forwarded-For / X-Real-IP и сохраняется в аудит-логе.

> **JWT + Telegram**
>
> Кросс-валидация JWT-токена и X-Telegram-Init-Data предотвращает повторное использование токена.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.