#ACL

ACL (Access Control List) используется для контроля прав доступа к операциям с ресурсами. Вы можете назначать права ролям или напрямую ограничивать их, минуя ролевые ограничения. Система ACL предлагает гибкий механизм управления правами, поддерживающий фрагменты прав (snippets), промежуточное ПО (middleware), условные проверки и другие методы.

#Регистрация фрагментов прав (Snippet)

Фрагменты прав (snippets) позволяют регистрировать часто используемые комбинации прав в качестве многократно используемых единиц. После привязки роли к фрагменту она получает соответствующий набор прав, что сокращает дублирование настроек и повышает эффективность управления правами.

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'.

После регистрации эта операция появится в интерфейсе настройки прав, где администраторы смогут конфигурировать права доступа к ней на странице управления ролями.