crank/docs/agent-auth-model.md

# Модель машинной аутентификации и уровней защиты операций

## 1. Назначение документа

Этот документ фиксирует целевую модель машинного доступа к опубликованным инструментам платформы. Модель строится вокруг двух принципов:

- длинноживущий машинный доступ принадлежит конкретному AI-агенту, а не рабочей области в целом;
- требуемый уровень защиты определяется характером данных конкретной операции.

Именно поэтому в системе должны быть одновременно:

- ключ AI-агента как базовый машинный credential;
- режимы выдачи токенов разной строгости;
- обязательная политика защиты на уровне операции.

## 2. Базовая идея

Внутри платформы нужно различать:

1. чем клиент подтверждает право подключиться к агенту;
2. какой уровень защиты требует операция;
3. достаточно ли текущего машинного доступа для вызова этой операции.

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

## 3. Уровни защиты операции

Каждая операция получает обязательный уровень защиты.

### 3.1. `standard`

Используется для обычных данных и типовых интеграционных вызовов.

Разрешенный доступ:

- статический ключ AI-агента;
- короткоживущий токен;
- одноразовый токен.

### 3.2. `elevated`

Используется для чувствительных внутренних данных, для которых постоянного ключа уже недостаточно.

Разрешенный доступ:

- короткоживущий токен;
- одноразовый токен.

Статический ключ AI-агента для такого уровня уже недостаточен.

### 3.3. `strict`

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

Разрешенный доступ:

- только одноразовый токен на вызов.

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

## 4. Виды машинного доступа

### 4.1. Статический ключ AI-агента

Это длинноживущий ключ, принадлежащий одному агенту.

Свойства:

- привязан к одному `workspace`;
- привязан к одному `agent`;
- не используется для административных действий;
- может быть отозван и перевыпущен;
- в открытой редакции является основным механизмом подключения.

### 4.2. Короткоживущий токен

Это временный токен, выдаваемый на ограниченный срок.

Свойства:

- небольшой срок жизни;
- ограниченная область действия;
- может обновляться через стандартный поток OAuth 2.0;
- подходит для платформенного размещения, где важен баланс удобства и безопасности.

### 4.3. Одноразовый токен

Это токен, который разрешает один вызов конкретной операции или одной логической единицы доступа.

Свойства:

- очень короткий срок жизни;
- один допустимый вызов;
- после первого использования считается исчерпанным;
- предназначен для максимально чувствительных операций.

## 5. Правило сопоставления

Для вызова операции сервер сравнивает:

- уровень машинного доступа клиента;
- обязательный уровень защиты операции.

Правило простое:

- если уровень доступа ниже, чем требует операция, вызов запрещается;
- если уровень доступа равен или выше, вызов разрешается.

Именно это правило делает политику защиты независимой от того, в каком агенте опубликована операция.

## 6. Роль AI-агента

AI-агент:

- группирует операции;
- формирует MCP-поверхность;
- имеет собственный ключ подключения.

AI-агент не должен:

- ослаблять уровень защиты операции;
- переопределять критичность данных;
- разрешать более слабый способ вызова, чем требует сама операция.

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

## 7. Поддержка по редакциям продукта

### 7.1. Community

Открытая редакция должна поддерживать только один режим:

- статический ключ AI-агента.

Соответственно, в Community допустимы только операции уровня:

- `standard`.

### 7.2. Cloud или управляемая платформа

Для платформенного размещения должны поддерживаться:

- статический ключ AI-агента как режим совместимости;
- короткоживущие токены по OAuth 2.0 как рекомендуемый режим.

Реализация этого режима должна рассматриваться как коммерческий контур и не должна требовать размещения private token-issuer logic в public repository.

Соответственно, платформа может обслуживать операции уровня:

- `standard`;
- `elevated`.

### 7.3. Enterprise

Для корпоративной редакции должны поддерживаться все три режима:

- статический ключ AI-агента;
- короткоживущий токен;
- одноразовый токен.

Enterprise-реализация должна поставляться через private delivery и опираться на capability-gated integrations в public codebase.

Соответственно, допускаются операции уровня:

- `standard`;
- `elevated`;
- `strict`.

## 8. Потоки аутентификации

### 8.1. Community

1. Пользователь создает AI-агента.
2. Платформа выдает статический ключ AI-агента.
3. Клиент `Codex`, `Claude Code` или другой MCP-клиент использует этот ключ как bearer token при подключении к MCP endpoint.

Это самый простой и совместимый вариант.

### 8.2. Cloud или управляемая платформа

1. Пользователь или клиент проходит машинную аутентификацию.
2. Сервер авторизации выдает короткоживущий токен доступа.
3. Клиент использует его при работе с MCP endpoint.
4. По истечении срока действия токен обновляется через стандартный механизм обновления.

Этот вариант должен опираться на OAuth 2.0 и обычный механизм refresh.

### 8.3. Enterprise

1. Клиент получает разрешение на вызов чувствительной операции.
2. Сервер выдает одноразовый токен.
3. Клиент выполняет один вызов.
4. Токен становится недействительным.

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

## 9. Опорные стандарты

Для реализации расширенных режимов разумно опираться на готовые стандарты.

### OAuth 2.0

Используется как основа для короткоживущих токенов и их обновления.

### RFC 8693

Может использоваться как ориентир для схемы обмена одного вида machine credential на другой токен доступа.

### RFC 9449

Может использоваться как ориентир для будущей привязки токена к ключевой паре клиента, если потребуется дополнительная защита от повторного использования перехваченного токена.

## 10. Модель данных

Для этой схемы достаточно следующих базовых сущностей.

### `AgentKey`

Поля:

- `id`
- `workspace_id`
- `agent_id`
- `name`
- `prefix`
- `secret_hash`
- `status`
- `created_at`
- `last_used_at`
- `expires_at`

### `IssuedAgentToken`

Поля:

- `id`
- `workspace_id`
- `agent_id`
- `token_kind`
- `status`
- `expires_at`
- `used_at`
- `max_uses`
- `used_count`
- `created_at`

### Поля операции

На уровне операции должна появиться обязательная политика:

- `security_level`

Допустимые значения:

- `standard`
- `elevated`
- `strict`

## 11. Административный интерфейс

Настройка должна быть максимально простой.

На этапе создания или редактирования операции пользователь выбирает:

- `Обычный`
- `Повышенная защита`
- `Максимальная защита`

Смысл вариантов:

- `Обычный` — стандартный уровень для обычных данных;
- `Повышенная защита` — короткоживущий токен;
- `Максимальная защита` — одноразовый токен.

Пользователь не должен вручную настраивать детали OAuth или внутреннюю механику выдачи токенов на уровне операции.

## 12. Практический итог

Целевая модель машинного доступа для Crank должна строиться так:

- в Community — статический ключ AI-агента;
- в управляемой платформе — короткоживущие токены;
- в Enterprise — при необходимости одноразовые токены;
- уровень защиты определяется операцией, а не агентом;
- агент никогда не ослабляет обязательную защиту опубликованной операции.