NPM-пакеты для контроля доступа в админских и клиентских приложениях

Почему права быстро становятся запутанными

Сначала права кажутся простыми. Вы добавляете роль «admin», роль «customer» и пару проверок в интерфейсе. На неделю этого хватает, а потом начинается реальная жизнь.

Администраторам часто нужен широкий доступ. Они могут редактировать товары, смотреть заказы, оформлять возвраты, управлять сотрудниками и читать логи. Клиентам обычно нужно намного меньше. Чаще всего они должны только смотреть свои данные, менять профиль, отслеживать заказ или отменять то, что сами создали.

Проблемы начинаются, когда на одном экране смешано несколько действий. На странице поддержки может быть заказ, данные клиента, статус оплаты, управление возвратом, внутренние заметки и кнопка удаления. Один человек должен видеть всё. Другой — только заметки и статус заказа. А клиент может видеть ту же страницу заказа, но только свой заказ и без внутренних инструментов.

Вот тут простых названий ролей уже не хватает. «Admin» звучит понятно, но в реальных командах всё быстро дробится. Финансы могут делать возвраты, но не должны редактировать пользователей. Поддержка может обновлять статус заказа, но не должна выгружать все данные клиентов. Менеджер магазина может редактировать товары в одном регионе, но не во всех.

Мелкие исключения накапливаются. Пользователи входят в команды. У записей есть владельцы. Аккаунты блокируются. Тестовые пользователи могут читать страницу, но не могут нажать «Создать». Один и тот же человек может быть и клиентом, и администратором компании — в зависимости от того, какое рабочее пространство он открыл.

Проверки в интерфейсе только усугубляют ситуацию, если команда слишком им доверяет. Скрыть кнопку — не значит защитить что-то. Если API всё равно принимает запрос, пользователь может отправить его напрямую и получить данные или изменить записи, к которым не должен иметь доступа.

Поэтому код прав так быстро превращается в хаос. Проблема редко в одном большом правиле. Обычно это пятьдесят маленьких правил, которые пересекаются, меняются со временем и по-разному работают в админских и клиентских приложениях. Хороший контроль доступа держит эти правила в одном месте, чтобы приложение не превратилось в груду разрозненных проверок.

Когда простых проверок по ролям достаточно

Простые проверки по ролям подходят приложениям с небольшим набором действий и почти без исключений. Если каждый менеджер может одобрять возвраты, редактировать товары и смотреть отчёты, одна общая роль понятна и её легко тестировать.

Часто это как раз правильная отправная точка, прежде чем сравнивать NPM packages for access control. Многие команды слишком рано берутся за policy engines, а потом тратят больше времени на моделирование правил, чем на выпуск функций.

Такой подход хорошо работает для role based access control в Node.js, когда границы обязанностей чёткие. Администратор делает админские задачи. Сотрудник поддержки отвечает на обращения. Клиент управляет только своим профилем, заказами или платёжными данными.

Небольшой магазин — хороший пример. Все менеджеры могут делать одни и те же действия в админском приложении, а клиенты могут только смотреть или менять свои базовые данные. Для этого не нужна сложная система прав. Короткой карты ролей и одной проверки владения обычно хватает почти во всех случаях.

Простая схема обычно выдерживает, когда:

• у каждой роли фиксированный набор действий
• правила владения остаются простыми, например «клиент может редактировать только свой адрес»
• новые функции редко добавляют исключения
• команда может объяснить правила несколькими простыми фразами

Роли начинают ломаться, когда одно и то же название даёт разные права в разных ситуациях. Один менеджер может делать возврат до 100 долларов, другой — редактировать цены, а третий — только смотреть отчёты. Название роли перестаёт говорить правду.

Обычно это и есть тревожный сигнал. Если в заметках о правах всё чаще появляются слова вроде «кроме», «если не», «только если», значит, простые роли почти дошли до предела.

Пока правила короткие, проверки по ролям быстро собираются, легко проверяются и их сложно неправильно понять. Когда исключений становится слишком много, добавление новых ролей обычно только усугубляет хаос. В этот момент логика политик начинает оправдывать себя.

Пакеты для простых проверок по ролям

Среди NPM packages for access control первыми обычно всплывают два названия: AccessControl и CASL. Оба подходят для базовых прав, но ощущаются по-разному, когда приложение начинает расти.

AccessControl — более простой старт для обычных правил «роль — действие — ресурс». Если ваша команда думает фразами вроде «админы могут обновлять пользователей» и «клиенты могут читать свои заказы», он подходит хорошо. Вы задаёте роли, перечисляете действия и связываете их с ресурсами. Такой формат легко просматривать в одном файле, а это важнее, чем многие признают.

Небольшим приложениям обычно лучше с одним центральным файлом прав, чем с проверками, разбросанными по роутам, контроллерам и компонентам интерфейса. Когда все правила лежат в одном месте, новым разработчикам нужно всего несколько минут, чтобы их понять. Им не нужен разбор на доске, чтобы увидеть, кто что может.

Простая настройка обычно выглядит так:

• admin может создавать, читать, обновлять и удалять товары
• support может читать пользователей и обновлять тикеты
• customer может читать свой профиль и свои заказы
• guest может читать публичные страницы

AccessControl хорошо подходит под такой стиль. Это хороший выбор для админ-панелей, внутренних инструментов и ранних клиентских приложений, где роли остаются стабильными.

CASL тоже без проблем справляется с простыми ролями, но даёт больше пространства на будущее. Если вы ожидаете правила вроде «менеджер может редактировать заказ только до отгрузки» или «пользователь может читать счета своей компании», CASL начинает выглядеть логичнее. Можно начать с базовых проверок по ролям и перейти к правилам с условиями, не меняя библиотеку.

У этой гибкости есть цена. CASL требует чуть внимательнее думать об ability, subject и conditions. Это не сложно, но абстракция выше, чем у простой карты ролей.

Я бы упростил выбор так:

• Берите AccessControl, когда роли фиксированы, а правила короткие.
• Берите CASL, когда простых ролей пока достаточно, но впереди уже видны исключения.
• Не берите ни то ни другое, если команда не может объяснить модель прав простыми словами.

Если для пакета нужна схема, прежде чем кто-то напишет guard для маршрута, скорее всего, он слишком сложен для текущего приложения.

Пакеты для логики политик

Простые проверки по ролям перестают работать, когда доступ зависит от контекста. Администратор может редактировать товар только до публикации. Клиент может смотреть счёт только если он принадлежит ему. Когда правила зависят от владения, статуса, суммы или состояния аккаунта, обычные карты ролей быстро превращаются в хаос.

CASL хорошо подходит, когда нужна логика политик, но без ухода слишком далеко от обычного JavaScript. Вы описываете abilities в коде, а потом проверяете, может ли пользователь читать, обновлять или удалять запись при определённых условиях. Это отлично работает для правил владения и проверок статуса. Правило вроде «клиент может отменить свой заказ, если заказ ещё в статусе pending» легко выразить, и за ним проще следить, чем за кучей разбросанных if.

Для многих команд CASL — это первый серьёзный шаг дальше basic role based access control в Node.js. Он также хорошо подходит для прав в админском приложении, потому что те же правила можно использовать и для того, какие кнопки видит пользователь, и для того, что разрешает backend.

Oso — это другой стиль. Он хорошо работает там, где правила доступа начинают выглядеть как бизнес-политика, а не как внутренняя логика приложения. Если менеджеры поддержки могут делать возвраты до одной суммы, менеджеры финансов — одобрять более крупные суммы, а партнёры — видеть только аккаунты, связанные с их контрактом, такие правила обычно читаются в Oso лучше, чем в самописных картах ролей. Компромисс в том, что команде нужно освоить его policy layer и поддерживать порядок.

node-casbin подходит командам, которым нужна более строгая схема с отдельными файлами модели и политик. Это может быть хорошим вариантом, когда правилам нужна формальная структура или когда вы хотите управлять правами вне основного кода приложения. Часто это удачный выбор для более крупных систем, где важно, чтобы модель авторизации оставалась одинаковой в разных сервисах.

То, как эти инструменты читаются, тестируются и отлаживаются, не менее важно, чем их набор возможностей:

• CASL обычно ближе всего к обычному коду приложения, поэтому разработчики могут тестировать правила обычными unit-тестами.
• Oso читается хорошо, когда правила становятся более бизнесовыми, но отладка сложнее, если команда смешивает policy logic с предположениями приложения.
• node-casbin предсказуем, когда модель стабильна, хотя matcher logic и policy files поначалу могут казаться абстрактными.

Если правила меняются каждую неделю, выбирайте пакет, который команда сможет прочитать в уставший вторник днём. Обычно именно его потом нормально тестируют и действительно используют в продакшене.

Как выбрать пакет шаг за шагом

Начните не со списка возможностей пакета, а с реальных фраз о правах в вашем приложении. Запишите примерно десять правил так, как их видят пользователи: «админы могут редактировать любой заказ», «клиенты могут отменять свой неоплаченный заказ», «сотрудники могут смотреть счета своей компании», «заблокированные пользователи не могут создавать тикеты».

Этот список скажет больше, чем любая сравнительная таблица. Если большинство правил просто называют роль, например admin, manager или customer, обычно достаточно простого пакета для ролей. AccessControl или даже небольшая карта ролей в Node.js отлично подойдут, когда правило по сути звучит как «роль X может делать действие Y».

Если в фразах всё чаще появляются условия, на это стоит обратить внимание. Слова вроде «свой», «того же аккаунта», «только если активен», «если не заблокировано» или «до одобрения» означают, что вы уходите от простых проверок по ролям. Здесь policy tool вроде CASL подходит лучше, потому что он может описывать владение и состояние записи, не превращая код в набор особых случаев.

Держите в голове разделение между интерфейсом и backend. Интерфейс может скрывать кнопки, пункты меню и экраны, чтобы уменьшить путаницу. Но backend всё равно должен проверять каждое правило, потому что скрытая кнопка не останавливает прямой API-запрос.

Короткая проверка помогает:

• посчитайте, сколько правил завязано только на роли
• отметьте каждое правило, которое зависит от владения
• отметьте каждое правило, которое зависит от состояния аккаунта или записи
• проверьте, должно ли одно и то же правило работать и во frontend, и в API
• выберите самый простой пакет, который закроет всё это без обходных решений

Потом протестируйте один сценарий для admin и один для customer, прежде чем принимать решение. Например, дайте администратору одобрить возврат, а потом пусть клиент попробует отменить тот же заказ после блокировки. Если пакет делает оба случая понятными и удобными для проверки, вы близки к хорошему выбору.

Не пытайтесь растянуть библиотеку только для ролей на policy work просто потому, что на первый взгляд она выглядит проще. Простые правила должны оставаться простыми. Смешанные правила требуют пакет, который точно говорит, кто что может делать и при каких условиях.

Простой пример для админского и клиентского приложения

Представьте небольшой интернет-магазин с двумя приложениями. Сотрудники пользуются админским приложением. Покупатели пользуются клиентским приложением. Один и тот же backend обслуживает оба, но правила доступа у них не одинаковые.

Гость — самый простой случай. Гости могут просматривать товары, искать их и читать страницы товаров, но ничего не могут менять. Это чистая проверка по роли. Если у пользователя роль «guest» или вообще нет аккаунта, код разрешает операции чтения и блокирует операции записи.

Менеджер магазина тоже хорошо подходит для ролей. Отчёты по выручке — чувствительная информация, но правило здесь прямое: менеджеры могут их смотреть, остальные — нет. Не нужно проверять содержимое отчёта или сравнивать ID пользователей. Достаточно проверки по роли.

Сотрудник поддержки — промежуточный случай. Если бизнес говорит, что support может делать возвраты, правило по роли тоже часто работает хорошо. Можно оставить всё прямо: пользователи с ролью «support_agent» могут запускать возвраты. Это легко читать в админском приложении, и это хорошо ложится на библиотеки вроде AccessControl.

Правило для клиента — это уже место, где начинает важничать логика политик. Клиент может отменить заказ только если заказ его и если статус всё ещё «pending». Роль «customer» не даёт полного ответа. Она показывает, кто этот человек, но не говорит, можно ли отменять именно этот заказ.

Такому правилу нужны две проверки, связанные с самой записью:

• заказ принадлежит текущему клиенту
• статус заказа — pending

Вот такой случай как раз удобнее описывать через CASL или другую библиотеку, ориентированную на политики. Вы задаёте одно правило для действия «cancel» над субъектом «Order» с условиями по владельцу и статусу. Потом используете это правило и в API, и, если нужно, в интерфейсе.

Разделение здесь довольно ясное. Роли помогают с широким доступом: например, когда гости просматривают товары, а менеджеры открывают отчёты по выручке. Правила политик помогают, когда ответ зависит от реальных данных перед вами, например от того, принадлежит ли клиенту заказ в статусе pending.

Когда люди сравнивают NPM packages for access control, этот пример — хороший фильтр. Если большинство ваших правил звучит как «админы могут делать X», библиотека для ролей может быть достаточной. Если правила звучат как «клиенты могут делать X только когда Y и Z верны», выбирайте пакет, который умеет policy logic, не превращая каждый роут в набор своих if-statements.

Ошибки, которые создают баги в правах

Баги в правах редко начинаются с хакера. Обычно они начинаются с shortcut. Кто-то скрывает кнопку в админском приложении, экран выглядит нормально, и команда забывает проверить то же действие на сервере.

Это самая старая ошибка: интерфейс говорит «нет», а API всё ещё говорит «да». Если клиент или сотрудник может вручную отправить запрос, скрытая кнопка ничего не значит. Возвраты, удаления, выгрузки и изменения аккаунта всегда должны проверяться на сервере.

Другая частая проблема появляется, когда команды создают новую роль под каждый странный случай. Сначала у вас есть admin, support и customer. Через пару месяцев появляются роли вроде support_refunds_eu, support_refunds_weekend и junior_admin_no_delete. Это не контроль доступа. Это куча исключений с названиями.

Роли должны оставаться широкими. Странные случаи относятся к правилам. Сотрудник поддержки может делать возврат только по своим заказам, только до определённой суммы и только до выплаты. Это логика политики, а не новый ярлык.

Разрозненные проверки приводят к более тихим багам. В React-компоненте может быть проверка canDeleteOrder, в API-маршруте — isAdmin, а фоновая задача не проверяет ничего. В итоге одно действие получает три разных ответа, и никто не замечает проблему, пока плохой запрос не проходит.

Большинство NPM packages for access control работают лучше, когда у вас один источник правды для правил. Важнее привычка, чем сам пакет. Если одно и то же право живёт в роутерах, компонентах и helper-файлах под разными именами, расхождения появляются очень быстро.

Ещё одна ловушка — смешивать бизнес-правила с ярлыками пользователей. «Manager» звучит понятно, но реальное правило может зависеть от статуса заказа, региона, суммы или того, кто создал запись. Ярлыки описывают человека. Правила определяют действие.

Баги, которые код-ревью пропускает, ловятся тестами. Для рискованных действий нужны и разрешённые, и запрещённые сценарии.

Короткий чек-лист помогает:

• тестируйте API, а не только экран
• тестируйте один обычный случай и один запрещённый
• держите рискованные права в одном файле правил или сервисе
• в первую очередь проверяйте возвраты, удаления, выгрузки и impersonation

Если право может стоить денег или раскрыть данные, относитесь к нему как к бизнес-логике. Потому что именно этим оно и является.

Быстрые проверки перед тем, как принять решение

Код прав должен казаться скучным. Если одно небольшое изменение вызывает у вас тревогу, значит, правила уже слишком разбросаны.

Хороший пакет делает правила настолько короткими, что новый коллега может прочитать их за один раз и всё равно объяснить, что пользователи могут делать. Если логика растянута по файлам роутов, компонентам интерфейса, helper-файлам и коду базы данных, стоит притормозить. Такая схема обычно создаёт баги, как только кто-то добавляет новый экран.

Backend тоже должен проверять те же правила. Скрыть кнопку в админском приложении полезно, но само по себе это ничего не защищает. Если пользователь всё ещё может вызвать API и пройти действие, ваша система прав — это только декорация.

Правила владения заслуживают отдельного теста. Вы должны суметь доказать, что «клиент может редактировать свой заказ» и «клиент не может редактировать чужой заказ», вообще не открывая интерфейс. Если для такой проверки нужен браузерный тест, значит, правило живёт не там, где нужно.

Изменения ролей должны оставаться небольшими. Добавьте одну новую роль, например «support agent», и посчитайте, сколько файлов придётся трогать. Если ответ восемь или десять, схема быстро испортится. Простые проверки по ролям работают лучше всего, когда роли аккуратно совпадают с действиями. Когда исключений становится слишком много, логика политик обычно подходит лучше.

Отказ в доступе тоже нужно объяснять простыми словами. «Forbidden» — не лучший вариант ни для пользователей, ни для вашей support-команды. Сообщение должно говорить, что именно заблокировало действие, например: «Только владелец аккаунта может экспортировать данные по биллингу». Такая мелочь экономит время, когда кто-то сообщает о «баге», который на самом деле ожидаемое поведение.

Перед коммитом спросите себя:

• Может ли один человек прочитать набор правил за 15 минут и пересказать его?
• Блокирует ли API то же действие, даже если интерфейс разрешает клик?
• Можно ли покрыть случаи владения тестами без рендера страниц?
• Можно ли добавить роль, не меняя половину приложения?
• Может ли приложение объяснить отказ нормальными словами?

Такой короткий ревью ловит больше проблем с правами, чем ещё один быстрый просмотр кода. И он же показывает, подходят ли выбранные NPM packages for access control именно к тому приложению, которое у вас есть сейчас, а не к тому, которое было три месяца назад.

Что делать дальше

Соберите все роли и действия в одну общую матрицу прав. Для начала достаточно одной страницы. Слева перечислите роли, сверху — действия, и отметьте, кто может смотреть, создавать, редактировать, одобрять, экспортировать или удалять. Этот документ сильно уменьшает путаницу ещё до того, как вы выберете между простыми проверками по ролям и логикой политик.

Потом напишите тесты для действий, которые могут стоить денег, утечь наружу или заблокировать пользователей. В первую очередь сосредоточьтесь на рискованных сценариях. Например, проверьте, кто может оформить возврат, скачать данные клиентов, изменить биллинг или увидеть внутренние заметки админов. Если одна ошибка в правах может вызвать поток обращений в поддержку, ей нужен автоматический тест.

Практичная последовательность выглядит так:

• Составьте матрицу прав и храните её в репозитории.
• Привяжите каждое правило к одному действию в приложении или API-эндпоинту.
• Добавьте тесты для биллинга, выгрузок, удалений и экранов только для администраторов.
• Пересматривайте правила каждый раз, когда меняется логика продукта.

Последний шаг важнее, чем думают многие команды. Права ломаются не тогда, когда ставится пакет, а когда меняется продукт. Новый тип пользователя, тестовый тариф, командные рабочие пространства, делегированный доступ или новый процесс одобрения могут превратить чистую схему в хаос, если никто не обновляет правила.

Если у вас есть и админское, и клиентское приложение, проверяйте их вместе. Команды часто хорошо защищают админскую часть и забывают, что у клиентской тоже есть чувствительные действия. Клиент, который может приглашать пользователей, управлять подпиской или получать доступ к общим записям, всё равно нуждается в чётких ограничениях.

Если схема уже кажется запутанной, посмотрите на неё ещё раз с новой парой глаз, прежде чем баги начнут накапливаться. Oleg Sotnikov помогает стартапам и небольшим командам разбираться с ролями, политиками и enforcement в рамках Fractional CTO и advisory-работы для стартапов. Такой обзор особенно полезен, когда команда уже переросла разрозненные проверки и ей нужны правила, которые остаются понятными по мере роста продукта.

Хороший контроль доступа в повседневной жизни ощущается скучным. И это хороший знак. Люди спокойно делают свою работу, клиенты видят только то, что должны, а рискованные действия надёжно закрыты тестами.