#Контроль дозволів ACL

ACL (Access Control List) використовується для контролю дозволів на операції з ресурсами. Ви можете надавати дозволи ролям або обходити обмеження ролей і безпосередньо встановлювати дозволи. Система ACL пропонує гнучкий механізм керування дозволами, підтримуючи фрагменти дозволів, проміжне ПЗ, умовні перевірки та інші методи.

#Реєстрація фрагментів дозволів (Snippet)

Фрагменти дозволів (Snippet) дозволяють реєструвати часто використовувані комбінації дозволів як багаторазові одиниці дозволів. Після прив'язки ролі до фрагмента вона отримує відповідний набір дозволів. Це зменшує дублювання конфігурації та підвищує ефективність керування дозволами.

acl.registerSnippet({
  name: 'ui.customRequests', // Префікс ui.* вказує на дозволи, які можна конфігурувати в інтерфейсі
  actions: ['customRequests:*'], // Відповідні операції з ресурсами, підтримує символи-замінники
});

#Дозволи, що обходять обмеження ролей (allow)

acl.allow() використовується для дозволу певних операцій в обхід обмежень ролей. Це підходить для публічних API, сценаріїв, що вимагають динамічної оцінки дозволів, або випадків, коли перевірка дозволів має базуватися на контексті запиту.

// Публічний доступ, вхід не потрібен
acl.allow('app', 'getLang', 'public');

// Доступно авторизованим користувачам
acl.allow('app', 'getInfo', 'loggedIn');

// На основі користувацької умови
acl.allow('orders', ['create', 'update'], (ctx) => {
  return ctx.auth.user?.isAdmin ?? false;
});

Опис параметра condition:

• 'public' : Будь-який користувач (включно з неавторизованими) може отримати доступ без будь-якої автентифікації.
• 'loggedIn' : Доступно лише авторизованим користувачам, вимагає дійсної ідентифікації користувача.
• (ctx) => Promise<boolean> або (ctx) => boolean : Користувацька функція, яка динамічно визначає, чи дозволено доступ, на основі контексту запиту; може реалізовувати складну логіку дозволів.

#Реєстрація проміжного ПЗ для дозволів (use)

acl.use() використовується для реєстрації користувацького проміжного ПЗ для дозволів, що дозволяє вставляти власну логіку в процес перевірки дозволів. Зазвичай використовується разом з ctx.permission для визначення користувацьких правил дозволів. Підходить для сценаріїв, що вимагають реалізації нетрадиційного контролю дозволів, наприклад, публічні форми, що потребують перевірки користувацького пароля, динамічні перевірки дозволів на основі параметрів запиту тощо.

Типові сценарії використання:

• Сценарії публічних форм: без користувача та ролі, але з необхідністю обмежити дозволи за допомогою користувацького пароля.
• Контроль дозволів на основі параметрів запиту, IP-адрес та інших умов.
• Користувацькі правила дозволів, що обходять або змінюють стандартний процес перевірки дозволів.

Керування дозволами через ctx.permission:

acl.use(async (ctx, next) => {
  const { resourceName, actionName } = ctx.action;
  
  // Приклад: Публічна форма потребує перевірки пароля, щоб пропустити перевірку дозволів
  if (resourceName === 'publicForms' && actionName === 'submit') {
    const password = ctx.request.body?.password;
    if (password === 'your-secret-password') {
      // Перевірка пройдена, пропустити перевірку дозволів
      ctx.permission = {
        skip: true,
      };
    } else {
      ctx.throw(403, 'Invalid password');
    }
  }
  
  // Виконати перевірку дозволів (продовжити процес ACL)
  await next();
});

Опис властивостей ctx.permission:

• skip: true : Пропускає подальші перевірки дозволів ACL і безпосередньо дозволяє доступ.
• Може динамічно встановлюватися в проміжному ПЗ на основі користувацької логіки для досягнення гнучкого контролю дозволів.

#Додавання фіксованих обмежень даних для певних операцій (addFixedParams)

addFixedParams може додавати фіксовані обмеження діапазону даних (фільтр) до операцій з певними ресурсами. Ці обмеження застосовуються безпосередньо, обходячи обмеження ролей, і зазвичай використовуються для захисту критично важливих системних даних.

acl.addFixedParams('roles', 'destroy', () => {
  return {
    filter: {
      $and: [
        { 'name.$ne': 'root' },
        { 'name.$ne': 'admin' },
        { 'name.$ne': 'member' },
      ],
    },
  };
});

// Навіть якщо користувач має дозвіл на видалення ролей, він не зможе видалити системні ролі, такі як root, admin, member

Порада: addFixedParams можна використовувати для запобігання випадковому видаленню або зміні конфіденційних даних, наприклад, вбудованих системних ролей, облікових записів адміністраторів тощо. Ці обмеження діють у поєднанні з дозволами ролей, гарантуючи, що навіть за наявності дозволів захищені дані не можуть бути змінені.

#Перевірка дозволів (can)

acl.can() використовується для перевірки, чи має певна роль дозвіл на виконання вказаної операції, і повертає об'єкт результату дозволу або null. Зазвичай використовується для динамічної перевірки дозволів у бізнес-логіці, наприклад, у проміжному ПЗ або обробниках операцій, щоб визначити, чи дозволено виконання певних операцій на основі ролі.

const result = acl.can({
  roles: ['admin', 'manager'], // Можна передати одну роль або масив ролей
  resource: 'orders',
  action: 'delete',
});

if (result) {
  console.log(`Роль ${result.role} може виконати операцію ${result.action}`);
  // result.params містить фіксовані параметри, встановлені через addFixedParams
  console.log('Фіксовані параметри:', result.params);
} else {
  console.log('Немає дозволу на виконання цієї операції');
}

Порада: Якщо передано кілька ролей, кожна роль перевіряється послідовно, і повертається результат для першої ролі, яка має дозвіл.

Визначення типів:

interface CanArgs {
  role?: string;      // Одна роль
  roles?: string[];   // Кілька ролей (перевіряються послідовно, повертається перша роль з дозволом)
  resource: string;   // Назва ресурсу
  action: string;    // Назва операції
}

interface CanResult {
  role: string;       // Роль з дозволом
  resource: string;   // Назва ресурсу
  action: string;    // Назва операції
  params?: any;       // Інформація про фіксовані параметри (якщо встановлено через addFixedParams)
}

#Реєстрація конфігурованих операцій (setAvailableAction)

Якщо ви хочете, щоб користувацькі операції можна було конфігурувати в інтерфейсі (наприклад, відображати на сторінці керування ролями), вам потрібно зареєструвати їх за допомогою setAvailableAction. Зареєстровані операції з'являться в інтерфейсі конфігурації дозволів, де адміністратори зможуть налаштовувати дозволи на операції для різних ролей.

acl.setAvailableAction('importXlsx', {
  displayName: '{{t("Import")}}', // Назва, що відображається в інтерфейсі, підтримує інтернаціоналізацію
  type: 'new-data',               // Тип операції
  onNewRecord: true,              // Чи застосовується при створенні нових записів
});

Опис параметрів:

• displayName: Назва, що відображається в інтерфейсі конфігурації дозволів, підтримує інтернаціоналізацію (використовуючи формат {{t("key")}}).
• type: Тип операції, який визначає її класифікацію в конфігурації дозволів.
  • 'new-data' : Операції, що створюють нові дані (наприклад, імпорт, додавання тощо).
  • 'existing-data' : Операції, що змінюють існуючі дані (наприклад, оновлення, видалення тощо).
• onNewRecord: Чи застосовується при створенні нових записів, дійсно лише для типу 'new-data'.

Після реєстрації ця операція з'явиться в інтерфейсі конфігурації дозволів, де адміністратори зможуть налаштовувати дозволи для цієї операції на сторінці керування ролями.