Ролі та права доступу

DocPlatform використовує контроль доступу на основі ролей (RBAC) на базі вбудованого авторизаційного рушія, що працює в процесі. Перевірка прав доступу виконується менш ніж за 0,1 мс без зовнішнього сервісу.

Ієрархія ролей

DocPlatform визначає 5 ролей у строгій ієрархії. Вищі ролі успадковують усі права нижчих ролей.

Super Admin         ← Повний доступ до платформи (усі робочі простори)
    │
Admin               ← Управління налаштуваннями робочого простору, учасниками, git, темою
    │
Editor              ← Створення та редагування сторінок (налаштовується для кожного workspace)
    │
Commenter           ← Перегляд сторінок, залишення коментарів
    │
Viewer              ← Лише перегляд сторінок

Platform Owner — внутрішня роль для операторів самостійно розгорнутих екземплярів, призначена для обслуговування платформи (міграції бази даних, управління ліцензіями, конфігурація системи). Вона не відображається в інтерфейсі чи API і не входить до публічної ієрархії ролей.

Матриця прав доступу

Налаштовувані права редактора

Можливості Editor можна налаштувати для кожного робочого простору. Admin та Super Admin конфігурують їх в налаштуваннях робочого простору:

API:

curl -X PATCH http://localhost:3000/api/v1/workspaces/:id \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "editor_can_create_pages": true,
    "editor_can_delete_pages": false
  }'

Конфігураційний файл:

# .docplatform/config.yaml (для робочого простору)
permissions:
  editor_can_create_pages: true
  editor_can_delete_pages: false

Коли дозвіл вимкнено, редактори бачать дію неактивною в інтерфейсі та отримують 403 Forbidden від API.

Призначення ролей

Перший користувач (Super Admin)

Перший зареєстрований користувач на новому екземплярі DocPlatform автоматично отримує роль Super Admin. Це відбувається лише один раз — наступні реєстрації не отримують ролі в робочому просторі, доки їх не запросять.

Super Admin є власником org та створювачем акаунту. Він має повний контроль над кожним робочим простором, білінгом, git-підключеннями та запрошенням зовнішніх користувачів.

Запрошення зовнішніх користувачів

Лише Super Admin може запрошувати зовнішніх користувачів до організації:

Веб-інтерфейс: Org Settings → Members → Invite External User

API:

curl -X POST http://localhost:3000/api/v1/org/invitations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "default_role": "editor"
  }'

Запрошений користувач приєднується до org і може бути призначений до робочих просторів будь-яким Admin або Super Admin.

Призначення учасників до робочих просторів

Admin призначає існуючих учасників org до свого робочого простору. Admin не може запрошувати зовнішніх користувачів — це може робити лише Super Admin.

Веб-інтерфейс: Workspace Settings → Members → Add Member → оберіть з учасників org → оберіть роль

API:

curl -X POST http://localhost:3000/api/v1/workspaces/:id/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "01HY5K3M7Q8P",
    "role": "editor"
  }'

Роль за замовчуванням

Встановіть роль за замовчуванням для нових учасників, доданих до робочого простору без конкретної ролі:

# .docplatform/config.yaml
permissions:
  default_role: viewer

Доступні значення: viewer, commenter, editor, admin

Контроль доступу на рівні сторінок

Перевизначте права доступу на рівні робочого простору для окремих сторінок за допомогою frontmatter. Правила доступу frontmatter обмежують в межах ролі користувача — вони ніколи не надають прав понад роль.

Синтаксис контролю доступу

Використовуйте правила доступу на основі ролей та користувачів для контролю доступу до сторінки:

---
title: Internal Security Policy
access:
  roles: ["security-team", "engineering-leads"]
  users: ["@01HY5K3M7Q8P"]
---

Правила:

• Ідентифікатори користувачів позначаються префіксом @
• Super Admin та Admin завжди мають доступ незалежно від правил frontmatter
• Frontmatter може лише обмежувати — сторінка не може надати доступ понад роль користувача в робочому просторі

Що означає обмежений доступ

Коли сторінка має правила access:

• Користувачі без необхідної ролі не можуть переглядати сторінку
• Сторінка не з’являється в результатах пошуку для неавторизованих користувачів
• Прямий доступ за URL повертає 403 Forbidden

Доступ до опублікованої документації

Для опублікованого документаційного сайту (/p/{slug}/...) контроль доступу працює інакше:

• Усі опубліковані сторінки є публічними за замовчуванням — вхід не потрібен
• Щоб вимагати вхід для всього опублікованого сайту, встановіть PUBLISH_REQUIRE_AUTH=true — це застосовується до всіх сторінок у всіх робочих просторах
• Контроль доступу на рівні окремих сторінок в опублікованій документації заплановано для майбутнього релізу

У v0.5 поле frontmatter access зберігається та доступне для майбутнього використання, але не застосовується на опублікованих маршрутах. Використовуйте PUBLISH_REQUIRE_AUTH для обмеження доступу на рівні всього сайту.

Внутрішні рівні ролей

Для довідки, кожна роль відповідає числовому рівню. Вищі рівні успадковують усі права нижчих рівнів:

Внутрішній код використовує workspace_admin для Admin та super_admin для Super Admin. Це деталі реалізації — публічні назви: Admin та Super Admin.

Дії мають мінімальні рівні: read вимагає рівень 10+, write вимагає 30+, delete вимагає 30+ (та editor_can_delete_pages увімкнено для Editor), admin вимагає 40+. Рівень ролі користувача порівнюється з мінімальним рівнем дії.

Як оцінюються права доступу

API Request
    │
    ▼
Auth Middleware
(extract JWT, identify user)
    │
    ▼
Permission Middleware
(custom RBAC check: user + role + resource + action)
    │
    ├── Allowed → proceed to handler
    │
    └── Denied → 403 Forbidden

5-крокова послідовність оцінки

1. Чи є користувач Platform Owner? → ДОЗВОЛИТИ (глобальний обхід)
2. Чи є користувач Org Super Admin для організації цього workspace? → ДОЗВОЛИТИ (обхід на рівні організації)
3. Знайти роль користувача у workspace → якщо не учасник, ВІДМОВИТИ
4. Чи досягає рівень ролі мінімуму для дії? → порівняти role_level >= action_min_level, плюс прапорці прав редактора
5. Чи має сторінка правила доступу у frontmatter? → перевірити access.roles/access.users, ОБМЕЖИТИ в межах ролі

Frontmatter ОБМЕЖУЄ в межах ролі, ніколи не НАДАЄ понад неї. Некоректний frontmatter за замовчуванням використовує строгий режим — сторінка обмежена лише для Admin.

Продуктивність

Кешування прав доступу

Політики custom RBAC завантажуються з SQLite у пам’ять при запуску сервера. Зміни ролей або frontmatter декларацій доступу запускають інвалідацію кешу:

1. Admin змінює роль користувача → версія кешу прав інкрементується
2. Editor оновлює frontmatter сторінки з новими правилами access → кеш інвалідується для цієї сторінки
3. Наступна перевірка прав завантажує свіжу політику з SQLite

Кеш версіонований, а не часовий — вікна застарілих прав немає.

Плани та ліміти місць

Підрахунок місць

Ролі Super Admin, Admin та Editor враховуються у ліміті max_editors плану. Ролі Commenter та Viewer необмежені на всіх планах і ніколи не враховуються.

Коли ліміт місць досягнуто, нових учасників org все ще можна запрошувати — але їм можна призначити лише ролі Commenter або Viewer, доки місце не звільниться.

Community Edition

Community Edition безкоштовний та self-hosted, ліцензійний ключ не потрібен:

Cloud плани

Потрібно більше? Зв’яжіться з відділом продажів для Enterprise планів з користувацькими лімітами, SSO та SLA.

Типові шаблони

Публічна документація з обмеженими внутрішніми сторінками

# Більшість сторінок: без правил доступу (відкриті для всіх учасників)

# Внутрішні сторінки: обмежені
---
title: Incident Response Playbook
access:
  roles: ["sre-team", "admin"]
---

Редактор створює, адміністратор публікує

1. Встановіть publishing.default_published: false в конфігурації робочого простору
2. Editors створюють та редагують сторінки (неопубліковані за замовчуванням)
3. Admins переглядають та перемикають published: true

Робочі простори для окремих команд

Створіть окремі робочі простори для кожної команди з незалежними списками учасників:

• Робочий простір eng-docs → інженерна команда
• Робочий простір product-docs → продуктова команда
• Робочий простір internal-wiki → усі

Super Admin має доступ до всіх робочих просторів для міжкомандної видимості. Admin управляє учасниками в межах призначених робочих просторів.

Обмеження можливостей Editor

Для робочих просторів, де Editors мають лише змінювати існуючий контент:

# .docplatform/config.yaml
permissions:
  editor_can_create_pages: false
  editor_can_delete_pages: false

Editors можуть редагувати існуючі сторінки, але не можуть створювати нові або видаляти будь-які.

Усунення несправностей

«403 Forbidden» на сторінці, до якої я маю мати доступ

1. Перевірте свою роль: Profile → Workspace Membership
2. Перевірте frontmatter сторінки: чи включає access.roles вашу роль?
3. Попросіть Admin робочого простору перевірити призначення вашої ролі
4. Якщо ви Editor, перевірте чи дія вимагає увімкнення editor_can_create_pages або editor_can_delete_pages

Зміни прав не набувають чинності

Зміни прав мають бути миттєвими (інвалідація кешу синхронна). Якщо це не так:

1. Вийдіть та увійдіть знову (оновіть JWT токени)
2. Перевірте логи сервера на предмет помилок інвалідації кешу
3. Запустіть docplatform doctor для перевірки стану системи прав

Перший користувач не є Super Admin

Це трапляється, якщо перший користувач реєструється, коли база даних уже містить записи користувачів (наприклад, від попереднього встановлення). Для виправлення:

1. Зупиніть сервер
2. Видаліть базу даних: rm {DATA_DIR}/data.db
3. Запустіть сервер та зареєструйтесь знову

Це скидає всі дані. Використовуйте лише на свіжих інсталяціях.

«Ліміт місць досягнуто» при запрошенні учасника

Ліміт max_editors плану досягнуто. Варіанти:

1. Понизити існуючого Admin або Editor до Commenter або Viewer, щоб звільнити місце
2. Запросити нового користувача як Commenter або Viewer (необмежені)
3. Оновити план для отримання більшої кількості місць