src/domain/interfaces/IAuthorizationService.ts - gitverse - tm-project/rbac-react-system

src/domain/interfaces/IAuthorizationService.ts
80 строк5 KB
Artem
chore: release v1.0.4
30 ноя 2025, 22:51
30 ноя 2025, 22:51f6f509c
/**
 * rbac-react-system v1.0.4
 * Copyright (c) 2025 TM Project
 * Licensed under the MIT License
 */

import { User } from '../entities'

/**
 * Интерфейс сервиса авторизации.
 * Определяет основные операции для проверки прав доступа, ролей и разрешений пользователя.
 */
export interface IAuthorizationService {
  /**
   * Проверяет, может ли пользователь получить доступ к указанному ресурсу с заданным действием.
   * Оценка включает прямые разрешения, разрешения по ролям, а также контекстные условия.
   *
   * @param {string} resource - Название ресурса (например, 'users', 'posts').
   * @param {string} action - Название действия (например, 'read', 'write', 'delete').
   * @param {User} user - Пользователь, для которого проверяется доступ.
   * @returns {Promise<boolean>} Промис, разрешающийся значением `true`, если доступ разрешён, иначе — `false`.
   *
   * @example
   * const canRead = await authService.canAccess('posts', 'read', user);
   */
  canAccess(resource: string, action: string, user: User): Promise<boolean>

  /**
   * Проверяет, обладает ли пользователь указанной ролью (включая роли, унаследованные по иерархии).
   *
   * @param {string} role - Идентификатор или название роли, которую необходимо проверить.
   * @param {User} user - Пользователь, для которого выполняется проверка роли.
   * @returns {Promise<boolean>} Промис, разрешающийся значением `true`, если пользователь имеет указанную роль, иначе — `false`.
   *
   * @example
   * const isAdmin = await authService.hasRole('admin', user);
   */
  hasRole(role: string, user: User): Promise<boolean>

  /**
   * Проверяет, имеет ли пользователь указанное разрешение (независимо от способа его получения).
   *
   * @param {string} permission - Строка разрешения в формате 'ресурс:действие' (например, 'users:read') или идентификатор разрешения.
   * @param {User} user - Пользователь, для которого выполняется проверка.
   * @returns {Promise<boolean>} Промис, разрешающийся значением `true`, если пользователь имеет разрешение, иначе — `false`.
   *
   * @example
   * const hasWrite = await authService.hasPermission('posts:write', user);
   */
  hasPermission(permission: string, user: User): Promise<boolean>

  /**
   * Возвращает все эффективные разрешения пользователя, включая:
   * - прямые разрешения,
   * - разрешения, полученные через назначенные роли,
   * - разрешения, унаследованные от родительских ролей.
   *
   * @param {User} user - Пользователь, для которого запрашиваются разрешения.
   * @returns {Promise<string[]>} Промис, разрешающийся массивом строк разрешений (в формате 'ресурс:действие').
   *
   * @example
   * const permissions = await authService.getUserEffectivePermissions(user);
   * // ['users:read', 'posts:write', 'settings:manage']
   */
  getUserEffectivePermissions(user: User): Promise<string[]>

  /**
   * Возвращает все эффективные роли пользователя, включая:
   * - напрямую назначенные роли,
   * - роли, унаследованные по иерархии.
   *
   * @param {User} user - Пользователь, для которого запрашиваются роли.
   * @returns {Promise<string[]>} Промис, разрешающийся массивом идентификаторов или названий ролей.
   *
   * @example
   * const roles = await authService.getUserEffectiveRoles(user);
   * // ['editor', 'moderator', 'user']
   */
  getUserEffectiveRoles(user: User): Promise<string[]>
}