che-rest 0.4.0

Typed REST framework and project tooling for che-orm applications
Documentation
# Группы и объектные разрешения

`che_rest::auth::access` предоставляет группы, прямые и групповые разрешения
на модели и объекты. REST использует асинхронный `Permission`; изменения ACL
выполняются в транзакции и записывают долговечные события доступа.

Рабочий пример с зафиксированной compiled migration:

```sh
cargo run --example object_permissions
```

Он создаёт одну заметку через REST, предоставляет второму пользователю чтение
через группу и проверяет потерю доступа после исключения из группы. База
изолирована в памяти. Исходники: `examples/object_permissions.rs` и
`examples/object_permissions/`. В настоящем приложении миграции выполняются
отдельной management-командой, а не при запуске HTTP-сервера.

## Подключение модели

1. Установить `che_rest::auth::module()`.
2. Объявить две модели назначений с FK к защищаемой модели и к `auth::User`
   либо `auth::Group`. FK должны быть обязательными, с `on_delete = "cascade"`.
3. Объявить `unique("object_id", "user_id", "permission")` и соответствующий
   вариант для группы. Добавить индексы `(subject_id, permission, object_id)`.
4. Реализовать `ObjectGrant<Model>` для обеих моделей назначений:
   `OBJECT`, `SUBJECT`, `PERMISSION` ссылаются на их generated field constants.
5. Реализовать `AccessModel` для защищаемой модели и указать уникальный
   стабильный `ACCESS_KEY`, `UserGrant`, `GroupGrant`.
6. В ViewSet указать `type Permission = Access<Model>`.
7. В чистом `AppModule::schema()` включить саму модель и
   `.merge(Access::<Model>::schema())`. Создать и применить compiled migrations.

Пример конфигурации после объявления моделей назначений:

```rust,ignore
use che_rest::auth::access::{AccessModel, PermissionMode, VIEW, CHANGE, MANAGE_ACCESS};

impl AccessModel for Note {
    const ACCESS_KEY: &'static str = "notes.note";
    type UserGrant = NoteUserPermission;
    type GroupGrant = NoteGroupPermission;
    const MODE: PermissionMode = PermissionMode::ObjectOnly;
    const CREATOR_PERMISSIONS: &'static [&'static str] = &[VIEW, CHANGE, MANAGE_ACCESS];
}
```

`CREATOR_PERMISSIONS` по умолчанию пуст. Перечисленные назначения создаются
атомарно с REST POST. Идентификатор объекта сохраняет тип модели: поддерживаются
`i64` и UUID; строкового универсального object PK в ACL нет.

Auth-модуль содержит новую миграцию `auth:0002_access`, зависящую от неизменённой
`auth:0001_initial`. Она добавляет группы, членство, разрешения моделей и события.
Таблицы ACL конкретного приложения принадлежат его собственным миграциям.

## Семантика

- `view` управляет GET и списками; `add` — созданием объектов модели;
  `change` — PUT/PATCH; `delete` — DELETE; `manage_access` — делегированием.
- `PERMISSIONS` содержит пять базовых имён; приложение может добавить свои.
- Прямые и групповые назначения объединяются. Отзыв одного источника сохраняет
  право, если остался другой источник.
- `change` и `delete` не предоставляют `view`. Изменение без права чтения
  возвращает 204; создание без права чтения — 201 без тела. Generated TypeScript
  `create`/`update` возвращают `Model | null` и преобразуют пустое тело в `null`;
  после обновления framework перегенерируйте клиентов.
- `add` назначается только на модель, в том числе через группу.
- `ObjectOnly` не расширяет объектную выборку по разрешениям модели.
  `ModelOrObject` учитывает и разрешение на всю модель, и объектные назначения.
- `is_staff` и `is_admin` не обходят ACL. Обход для суперпользователя включается
  явно через `SUPERUSER_BYPASS = true` и по умолчанию выключен.
- Владение записью, FK и membership приложения не создают права автоматически.
- Явных запрещающих записей, вложенных групп и наследования по связям нет.

Права фильтруют SQL до `count`, сортировки и пагинации. Detail для объекта без
права чтения возвращает 404. Мутации дополнительно проверяют разрешение объекта;
проверка, подготовка server-owned полей, сохранение и creator grants выполняются
в одной serializable транзакции. Конкурирующая транзакция может завершиться
ошибкой сериализации/SQLite busy; автоматический повтор пользовательских хуков
не выполняется.

## Транзакционные операции

Низкоуровневые функции предназначены для доверенного серверного кода. Они
требуют `&Transaction` и сами не проверяют право вызывающего управлять доступом:

```rust,ignore
use che_rest::{AppError, auth::access::{Access, Subject, VIEW, add_member}};

database.transaction_result(move |tx| Box::pin(async move {
    add_member(tx, user_id, group_id).await?;
    Access::<Note>::grant(tx, Subject::Group(group_id), VIEW, note_id).await?;
    Ok::<_, AppError>(())
})).await?;
```

Также доступны `revoke`, `grant_model`, `revoke_model`, `remove_member`.
Возвращаемый `bool` показывает, изменились ли назначения. Повтор той же операции
не создаёт повторное событие; нарушение FK или конкурирующий конфликт — ошибка
транзакции. Ошибка приложения через `transaction_result` откатывает и данные,
и назначения, и события.

Для запроса пользователя используйте `Access::change_access`: он требует
транзакционный `PermissionContext`, проверяет `manage_access` и разрешает менять
только переданный сервером список `delegable`. Целевой пользователь/группа,
границы организации и список делегируемых прав проверяются приложением. Этот
список нельзя брать из тела HTTP-запроса. Готового публичного ACL CRUD endpoint
нет; приложение объявляет собственные действия с этой проверкой.

`can` и `require` проверяют эффективное разрешение. `effective_permissions`
получает источники разрешений для страницы до 100 объектов пакетными запросами:
прямые назначения, конкретные группы и, в соответствующем режиме, разрешения
модели. Вызывающий код отдельно авторизует раскрытие самих ACL-метаданных.

Группа в этом API — набор пользователей. Роль можно выразить группой с набором
назначений. Области организаций и управление членством принадлежат приложению.

## Асинхронный Permission

Старого `Permission::check` больше нет. Реализации используют:

- `check_request(context, principal, action)` — обязательная проверка запроса;
- `scope(...)` — SQL-условие, применяемое до загрузки данных; объектная политика
  обязана объявить его явно, иначе запрос закрывается с 403;
- `check_object(...)` — проверка конкретной записи;
- `check_write(..., model, write)` — финальная проверка подготовленной записи
  внутри транзакции; для DELETE `write` отсутствует;
- `after_write(...)` — транзакционная инициализация после сохранения;
- `validate(fields)` — проверка допустимости конфигурации сериализатора.

Реализации могут писать `async fn`; trait требует `Send` future через
`impl Future + Send`, без зависимости от async-trait. `PermissionContext`
передаёт `state` и текущую `transaction`. Для запросов политики используйте
`context.fetch_all(...)` либо непосредственно переданную транзакцию. Обращение
к `context.state.database()` во время write-проверки выполнит запрос вне неё.

По умолчанию `scope` вызывает обязательную проверку запроса и разрешает
неограниченную выборку только глобальным политикам (`object_scoped() == false`).
Для объектной политики стандартный `scope` возвращает 403. `check_object`
проверяет явно объявленный SQL scope для данного PK. `check_write` проверяет запрос и объект.
Переопределённые методы обязаны сохранять эти ограничения. Сериализаторы
по-прежнему только преобразуют материализованные данные и не выполняют запросы.

Пользовательская политика считается объектной по умолчанию (`object_scoped()`).
Глобальная политика может явно вернуть `false`. Встроенные `AllowAny`,
`IsAuthenticated`, `IsAdminUser` и read-only admin используют глобальный режим.

## Media

Авторизация image field actions асинхронная. Пользовательский `authorize`
получает `PermissionContext` и дополняет ViewSet-проверку. Он больше не заменяет
её. Финальная проверка и CAS записи изображения выполняются в одной транзакции.
При неудаче новый файл удаляется; очистка прежнего файла происходит после commit.

После установки любой объектной политики общий `/api/media/{key}` разрешает
только ключи, связанные с доступными моделями через image-поля зарегистрированных
ViewSet-сериализаторов. Проверка сохраняет `get_queryset()` конкретного экземпляра
ViewSet, ограничения backend и SQL scope. Реестр принадлежит одной сборке сервера:
повторный `Server::build` и сбор метаданных с тем же `AppState` не разделяют
обработчики media. Права проверяются при каждом скачивании. Ответы содержат
`Cache-Control: private, no-store`. Незарегистрированные ключи закрыты; скрытые
image-поля требуют отдельного авторизованного маршрута приложения.

## События и границы первой реализации

`AccessEvent` записывается в той же транзакции, что ACL или членство. `kind`
различает `object_granted`, `object_revoked`, `model_granted`, `model_revoked`,
`member_added`, `member_removed`; JSON payload имеет оболочку
`{"version":1,"data":...}`. Это долговечные факты изменения доступа, а не готовая
пользовательская sync-лента. Обычные ORM/raw SQL изменения этих таблиц, включая
каскадное удаление групп, обходят сервис и не создают такие события.

Встроенная `Access<Model>` пока отклоняет при сборке приложения:

- nested serializers и writable FK без отдельного контракта авторизации связей;
- broad CRUD signals, поскольку они не проверяют объектные права получателей;
- mutation backends и существующие sync endpoints, не предоставляющие новый
  транзакционный контракт объектной авторизации.

Обычный REST, image actions и custom actions с явными вызовами сервиса доступа
работают независимо от sync. Наследование через связи, адресные WebSocket-события
остаются следующим этапом. Доставка выдачи и отзыва поддержана отдельным
`ObjectSyncEndpoints` протокола 3: см. [object-sync.md](object-sync.md).
Whole-model/scoped sync сохраняет прежний wire contract и pending requests;
переключение существующей клиентской БД требует явного upgrade после завершения
отправленных запросов. Полный план дальнейшего развития: `docs/OBJECT_SYNC_PLAN.md`.