Файл auth.php в Cotonti

Мы завершили анализ кода файла auth.php в фреймворке Cotonti. Этот файл в основном управляет правами доступа и группами пользователей через механизмы авторизации и контроля доступа (ACL). Вот основные моменты, которые мы рассмотрели:

1. Управление правами доступа: В файле описаны функции, которые работают с правами групп, таких как чтение (R), запись (W), а также другие специфические разрешения (например, 1, 2, 3, 4, 5, A — для более детализированных настроек).

2. Основные функции:

   • Добавление и удаление групп: Например, функции cot_auth_add_group и cot_auth_remove_group управляют добавлением и удалением групп из таблицы auth.
   • Управление объектами в ACL: Функции cot_auth_add_item и cot_auth_remove_item позволяют добавлять или удалять объекты из системы контроля доступа, определяя разрешения для разных групп.
   • Чистка кэша: Функция cot_auth_clear очищает кэш прав пользователей.
   • Реорганизация таблицы: cot_auth_reorder сортирует строки в таблице auth, обеспечивая правильный порядок данных.

3. Работа с правами:

   • Использование битовых масок для представления и обработки прав доступа. Например, функции cot_auth_getmask и cot_auth_getvalue преобразуют права в маски и обратно.
   • Преобразования позволяют удобно работать с правами на уровне строк таблицы базы данных, которые хранят битовые значения для доступа.

4. Гибкость и настройки:

   • В коде есть возможность задавать права по умолчанию через массивы, такие как $cot_auth_default_permit и $cot_auth_default_lock, а также возможность их перекрывать в пользовательских настройках.

В целом, этот файл является ядром системы авторизации в Cotonti, обеспечивая гибкость в управлении правами доступа и группами пользователей. Функции, которые мы рассмотрели, позволяют добавлять, удалять, изменять права и организовывать доступ на уровне групп и объектов системы.

/**
 * Authorization Management API
 * Основные функции авторизации находятся в файле functions.php
 *
 * @package API - Authorization
 * @copyright (c) Cotonti Team
 * @license https://github.com/Cotonti/Cotonti/blob/master/License.txt
 */

defined('COT_CODE') or die('Неверный URL'); // Проверка, что код выполняется в рамках системы Cotonti, иначе завершение выполнения с ошибкой.

$cot_auth_default_permit = array( // Создание массива с правами доступа по умолчанию.
    COT_GROUP_DEFAULT => 'RW', // Группа по умолчанию имеет права на чтение и запись.
    COT_GROUP_GUESTS => 'R', // Гости имеют только права на чтение.
    COT_GROUP_INACTIVE => 'R', // Неактивные пользователи имеют только права на чтение.
    COT_GROUP_BANNED => '0', // Заблокированные пользователи не имеют прав.
    COT_GROUP_MEMBERS => 'RW', // Члены группы имеют права на чтение и запись.
    COT_GROUP_SUPERADMINS => 'RW12345A' // Суперадмины имеют полный доступ с правами на чтение, запись и дополнительные права.
);

$cot_auth_default_lock = array( // Создание массива с заблокированными (ограниченными) правами по умолчанию.
    COT_GROUP_DEFAULT => '0', // Группа по умолчанию не имеет доступ.
    COT_GROUP_GUESTS => 'A', // Гости имеют ограниченные права (A - ограничение).
    COT_GROUP_INACTIVE => 'A', // Неактивные пользователи имеют ограниченные права (A).
    COT_GROUP_BANNED => 'RW12345A', // Заблокированные пользователи имеют те же права, что и суперадмины.
    COT_GROUP_MEMBERS => '0', // Члены группы не имеют доступа.
    COT_GROUP_SUPERADMINS => 'RW12345A' // Суперадмины имеют полный доступ с правами на чтение, запись и дополнительные права.
);

/**
 * Регистрирует группу пользователей в таблице auth
 *
 * @param int $group_id Идентификатор группы
 * @param int $base_group_id Идентификатор группы, из которой копируются права
 * @return bool Статус выполнения операции
 * @global CotDB $db
 */
function cot_auth_add_group($group_id, $base_group_id = COT_GROUP_MEMBERS) // Функция для добавления группы в таблицу auth
{
	global $db, $db_auth, $usr; // Подключение глобальных переменных базы данных, таблицы и текущего пользователя
	if ($group_id <= COT_GROUP_SUPERADMINS) // Если ID группы меньше или равен ID супер-администраторов
	{
		return false; // Возвращаем false, если группа не может быть добавлена (не позволяет добавлять супер-администраторов)
	}
	if ($base_group_id <= 0) // Если ID базовой группы меньше или равен нулю
	{
		$base_group_id = COT_GROUP_MEMBERS; // Используем группу участников по умолчанию как базовую группу
	}
	$db->query("INSERT INTO $db_auth (auth_groupid, auth_code, auth_option, auth_rights, auth_rights_lock, auth_setbyuserid) // Выполняем запрос на добавление новых прав в таблицу auth
		SELECT $group_id, auth_code, auth_option, auth_rights, auth_rights_lock, {$usr['id']} // Копируем права из базовой группы для новой группы с добавлением ID текущего пользователя
			FROM $db_auth WHERE auth_groupid = $base_group_id"); // Извлекаем данные из таблицы auth для базовой группы
	cot_auth_reorder(); // Вызываем функцию для перераспределения прав, если нужно
	return true; // Возвращаем true, чтобы показать, что группа была успешно добавлена
}

/**
 * Добавляет новый объект в списки контроля доступа
 *
 * Пример использования:
 * <code>
 * $auth_permit = array(
 *     COT_GROUP_DEFAULT => 'R', // разрешение на чтение для группы по умолчанию
 *     COT_GROUP_GUESTS => '0',  // запрещено для гостей
 *     COT_GROUP_MEMBERS => 'R', // разрешение на чтение для членов
 *     12 => 'RW', // разрешает чтение и запись для группы с ID = 12
 * );
 *
 * $auth_lock = array(
 *     COT_GROUP_DEFAULT => 'A', // блокировка всех прав для группы по умолчанию
 *     COT_GROUP_GUESTS => 'W12345A', // блокировка некоторых прав для гостей
 *     COT_GROUP_MEMBERS => 'A', // блокировка всех прав для членов
 *     12 => 'R', // невозможно изменить право на чтение для группы с ID = 12
 * );
 *
 * cot_auth_add_item('test', 'item123', $auth_permit, $auth_lock);
 * </code>
 *
 * @param string $module_name Имя модуля, к которому относится объект
 * @param string $item_id Идентификатор объекта в рамках модуля
 * @param array $auth_permit Карта разрешённых прав
 * @param array $auth_lock Карта заблокированных прав
 * @return int Количество вставленных строк
 * @global CotDB $db
 */
function cot_auth_add_item($module_name, $item_id, $auth_permit = [], $auth_lock = [])
{
    global $cot_groups, $cot_auth_default_permit, $cot_auth_default_lock;

    $auth_permit = $auth_permit + $cot_auth_default_permit; // Объединение разрешений с значениями по умолчанию
    $auth_lock = $auth_lock + $cot_auth_default_lock; // Объединение заблокированных прав с значениями по умолчанию
    $ins_array = []; // Инициализация массива для вставки

    foreach ($cot_groups as $k => $v) {
        if (empty($v['skiprights'])) { // Пропуск групп с флагом пропуска прав
            $base_grp = $k > COT_GROUP_SUPERADMINS ? COT_GROUP_DEFAULT : $k; // Выбор группы для базовых прав
            $ins_array[] = array( // Заполнение массива для вставки
                'auth_groupid' => $k, // ID группы
                'auth_code' => $module_name, // Код модуля
                'auth_option' => $item_id, // Идентификатор объекта
                'auth_rights' => cot_auth_getvalue($auth_permit[$base_grp]), // Получение прав для группы
                'auth_rights_lock' => cot_auth_getvalue($auth_lock[$base_grp]), // Получение заблокированных прав для группы
                'auth_setbyuserid' => Cot::$usr['id'] // ID пользователя, который установил права
            );
        }
    }

    $res = 0; // Инициализация переменной для результата
    if (!empty($ins_array)) { // Если массив для вставки не пуст
        $res = Cot::$db->insert(Cot::$db->auth, $ins_array); // Выполнение вставки в базу данных
    }

    cot_auth_reorder(); // Перестроение списка прав доступа
    cot_auth_clear('all'); // Очистка кеша прав

    return $res; // Возвращение количества вставленных строк
}

/**
 * Возвращает наивысший уровень всех групп, в которых состоит пользователь.
 *
 * @param int $userid ID пользователя
 * @param bool $maingroup Возвращать уровень основной группы
 * @return int
 *
 * @deprecated Не используется нигде. Похоже, устаревшая механика уровней пользователей
 */
function cot_auth_getlevel($userid, $maingroup = false)
{
    global $db, $db_groups, $db_groups_users, $db_users;
    if ($maingroup) // Если нужно вернуть уровень основной группы
    {
        return (int)$db->query("
            SELECT grp_level FROM $db_groups
            INNER JOIN $db_users
            ON user_maingrp = grp_id
            WHERE user_id = ?
        ", array($userid))->fetchColumn(); // Получаем уровень основной группы пользователя
    }
    else
    {
        return (int)$db->query("
            SELECT MAX(grp_level) FROM $db_groups
            WHERE grp_id IN (
                SELECT gru_groupid
                FROM $db_groups_users
                WHERE gru_userid = ?
            )
        ", array($userid))->fetchColumn(); // Получаем наивысший уровень из всех групп, в которых состоит пользователь
    }
}

/**
 * Возвращает маску доступа для заданного байта доступа
 *
 * @param int $rn Байтовое представление прав
 * @return string
 */
function cot_auth_getmask($rn)
{
    $res = ($rn & 1) ? 'R' : ''; // Если младший бит равен 1, добавляем 'R' (Read)
    $res .= (($rn & 2) == 2) ? 'W' : ''; // Если второй бит равен 1, добавляем 'W' (Write)
    $res .= (($rn & 4) == 4) ? '1' : ''; // Если третий бит равен 1, добавляем '1'
    $res .= (($rn & 8) == 8) ? '2' : ''; // Если четвёртый бит равен 1, добавляем '2'
    $res .= (($rn & 16) == 16) ? '3' : ''; // Если пятый бит равен 1, добавляем '3'
    $res .= (($rn & 32) == 32) ? '4' : ''; // Если шестой бит равен 1, добавляем '4'
    $res .= (($rn & 64) == 64) ? '5' : ''; // Если седьмой бит равен 1, добавляем '5'
    $res .= (($rn & 128) == 128) ? 'A' : ''; // Если восьмой бит равен 1, добавляем 'A' (Access)
    return $res; // Возвращаем строку маски доступа
}

/**
 * Преобразует маску доступа в байт прав
 *
 * @param string $mask Маска доступа, например, 'RW1A'
 * @return int
 */
function cot_auth_getvalue($mask)
{
    $mn['0'] = 0; // Присваиваем значение 0 для '0'
    $mn['R'] = 1; // Присваиваем значение 1 для 'R'
    $mn['W'] = 2; // Присваиваем значение 2 для 'W'
    $mn['1'] = 4; // Присваиваем значение 4 для '1'
    $mn['2'] = 8; // Присваиваем значение 8 для '2'
    $mn['3'] = 16; // Присваиваем значение 16 для '3'
    $mn['4'] = 32; // Присваиваем значение 32 для '4'
    $mn['5'] = 64; // Присваиваем значение 64 для '5'
    $mn['A'] = 128; // Присваиваем значение 128 для 'A'

    $res = 0; // Инициализация переменной для хранения результата
    $masks = str_split($mask); // Разделяем строку маски на отдельные символы

    foreach ($masks as $k) { // Перебираем каждый символ маски
        if(isset($mn[$k])) $res += $mn[$k]; // Если символ найден в массиве $mn, добавляем его значение к результату
    }
    return $res; // Возвращаем итоговое байтовое представление прав
}

/**
 * Удаляет группу пользователей из таблицы auth
 *
 * @param int $group_id Идентификатор группы
 * @return int Количество удалённых записей
 * @global CotDB $db
 */
function cot_auth_remove_group($group_id)
{
	global $db, $db_auth;
	$db->delete($db_auth, 'auth_groupid=' . (int)$group_id); // Удаляем все записи из таблицы auth, где идентификатор группы равен $group_id
	return $db->affectedRows; // Возвращаем количество удалённых записей
}

/**
 * Удаляет объект из списка контроля доступа (ACL)
 *
 * @param string $module_name Модуль, к которому принадлежит объект
 * @param string $item_id Идентификатор объекта в модуле. Если не указан, удаляются все объекты.
 * @return int Количество удалённых записей
 * @global CotDB $db
 */
function cot_auth_remove_item($module_name, $item_id = null)
{
	global $db, $db_auth;

	$opt = is_null($item_id) ? '' : 'AND auth_option=' . $db->quote($item_id); // Если $item_id не задан, то условие пустое, иначе фильтруем по идентификатору объекта
	$db->delete($db_auth, "auth_code='$module_name' $opt"); // Удаляем записи из таблицы auth, соответствующие указанному модулю и объекту (если $item_id задан)
	return $db->affectedRows; // Возвращаем количество удалённых записей
}

/**
 * Оптимизирует таблицу auth, сортируя её строки
 * @global CotDB $db
 */
function cot_auth_reorder()
{
    global $db, $db_auth;

    $sql = $db->query("ALTER TABLE $db_auth ORDER BY auth_code ASC, auth_option ASC, auth_groupid ASC, auth_code ASC"); // Выполняем SQL-запрос для сортировки строк таблицы auth по столбцам auth_code, auth_option, auth_groupid
}