a.tolmachev
305 lines
14 KiB
Markdown
305 lines
14 KiB
Markdown
# Модель машинной аутентификации и уровней защиты операций
|
||
|
||
## 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 — при необходимости одноразовые токены;
|
||
- уровень защиты определяется операцией, а не агентом;
|
||
- агент никогда не ослабляет обязательную защиту опубликованной операции.
|
||
|
||
## 13. Public contract seam
|
||
|
||
В public Community-коде должны существовать стабильные HTTP contracts для будущего token service:
|
||
|
||
- `POST /mcp-auth/v1/token`
|
||
- `POST /mcp-auth/v1/token/one-time`
|
||
|
||
На первом этапе Community может не содержать private issuer implementation, но должна:
|
||
|
||
- сохранить DTO и shape ответов;
|
||
- возвращать предсказуемый `403 forbidden` для short-lived и one-time token flows;
|
||
- явно сообщать через structured context, что для выбранного `machine_access_mode` требуется расширенная редакция.
|
||
|
||
Это позволяет:
|
||
|
||
- не менять public API при подключении private реализации;
|
||
- держать open-core границу на уровне реализации, а не на уровне transport contract;
|
||
- не смешивать Community static agent-key flow с commercial `elevated/strict` реализацией.
|