---
doc_id: PRD-CK8S-AAC-0001
type: prd
title: kodex — требования домена доступа и аккаунтов
status: active
owner_role: PM
created_at: 2026-04-26
updated_at: 2026-06-03
related_issues: [599, 600, 601, 602, 711]
related_prs: []
related_docsets:
  - docs/platform/product/requirements.md
  - docs/platform/architecture/domain_map.md
  - docs/platform/architecture/service_boundaries.md
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-26-wave6-4-access-domain"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-26
---

# PRD: доступ, организации, группы и внешние аккаунты

## TL;DR

- Что строим: первый доменный пакет `access-manager` для организаций, пользователей, групп, членства, входа, allowlist, внешних аккаунтов, правил доступа и аудита решений.
- Для кого: владелец платформы, администраторы организаций, оператор платформы, agent-manager и другие сервисы-владельцы.
- Почему: без единого домена доступа остальные сервисы начнут создавать локальные статусы пользователей, токены, группы и собственные схемы проверки прав.
- Минимум первой версии: организация-владелец, клиентские организации, SaaS-клиенты, SaaS-исполнители, пользователи, SSO/OIDC-вход через allowlist, группы, членство, внешние аккаунты, вычисление доступа, явный запрет и объяснимый аудит.
- Критерии успеха: `access-manager` можно реализовать без пересмотра продуктовой модели и без зашивания одноорганизационного режима.

## Проблема и цель

Проблема:
- платформа должна сразу поддерживать несколько организаций, группы и внешних исполнителей, но первая установка стартует с одной организацией-владельцем;
- пользователь не должен саморегистрироваться, а должен входить через SSO/OIDC и проходить allowlist;
- внешние аккаунты, аккаунты ботов и сервисные аккаунты нельзя хранить как разрозненные секреты без владельца, области применения и политики;
- другие домены должны получать решение доступа от `access-manager`, а не повторять свои локальные правила.

Цель:
- зафиксировать минимальный продуктовый объём домена доступа перед реализацией;
- разделить пользовательскую идентичность, членство, внешние аккаунты и вычисление прав;
- задать объяснимую модель `allow/deny/pending/blocked` для пользовательского интерфейса, аудита, MCP и сервисов-владельцев.

## Пользователи и роли

| Роль | Главный сценарий |
|---|---|
| Владелец | Создаёт организацию-владельца, допускает администраторов, принимает опасные изменения доступа. |
| Администратор организации | Управляет пользователями, группами, членством и внешними аккаунтами своей организации. |
| Оператор платформы | Видит состояния `pending`/`blocked`, ошибки входа, проблемы внешних аккаунтов и объяснение доступа. |
| Пользователь платформы | Входит через SSO/OIDC, получает доступ к разрешённым проектам, задачам и действиям. |
| `agent-manager` | Проверяет, можно ли выполнить действие, запустить роль, создать задачу или запросить Human gate. |
| Сервис-владелец | Вызывает `access-manager` для авторитетной проверки доступа и не хранит собственную модель прав. |

## Функциональные требования

| ID | Требование | Приоритет |
|---|---|---|
| AAC-FR-1 | Домен должен поддерживать организацию-владельца, клиентские организации, организации внешних исполнителей, SaaS-организации, SaaS-клиентов и SaaS-исполнителей. | Обязательно |
| AAC-FR-2 | Пользователь может состоять в нескольких организациях и группах. | Обязательно |
| AAC-FR-3 | Группы бывают глобальными и организационными; модель не должна запрещать будущие проектные группы. | Обязательно |
| AAC-FR-4 | Членство должно быть типизированной сущностью с состоянием, ролью, источником назначения, версией и аудитом. | Обязательно |
| AAC-FR-5 | Вход пользователя идёт через SSO/OIDC-контур; саморегистрация запрещена. | Обязательно |
| AAC-FR-6 | Базовый самостоятельно управляемый IdP — Keycloak; GitHub/GitLab могут быть внешними поставщиками идентичности. | Обязательно |
| AAC-FR-7 | Allowlist по email и домену управляет первичным допуском до создания или связывания профиля пользователя. | Обязательно |
| AAC-FR-8 | Пользовательские состояния включают `active`, `pending`, `blocked` и `disabled`. | Обязательно |
| AAC-FR-9 | Домен должен хранить внешний идентификатор пользователя у поставщика идентичности отдельно от платформенного пользователя. | Обязательно |
| AAC-FR-10 | Домен должен хранить внешний аккаунт как субъект политики: поставщик, тип, область применения, статус готовности, ссылка на секрет и допустимые операции. | Обязательно |
| AAC-FR-10.1 | Поставщики внешних аккаунтов должны храниться как расширяемый каталог, а не как жёсткий enum в поле внешнего аккаунта. | Обязательно |
| AAC-FR-11 | Сырые секреты внешних аккаунтов не хранятся в PostgreSQL, не показываются в пользовательском интерфейсе, не попадают в тело аудита и выдаются только через общий resolver-контракт после положительного решения доступа. | Обязательно |
| AAC-FR-12 | Внешний аккаунт может принадлежать глобальному контуру, организации, проекту, репозиторию, пользователю, группе, агенту, роли агента, flow или пакету, а использоваться только через явную привязку политики. | Обязательно |
| AAC-FR-13 | Домен должен вычислять итоговый доступ через прямые правила, членство, наследование и явный запрет. | Обязательно |
| AAC-FR-13.1 | Правила доступа должны поддерживать `service` как прямой субъект для внутренних сервисов платформы, чтобы межсервисные команды и bootstrap/onboarding runner проходили аудит без подмены на человека, бота или внешний аккаунт. | Обязательно |
| AAC-FR-14 | Явный запрет имеет приоритет над разрешением и должен быть объясним в аудите. | Обязательно |
| AAC-FR-15 | Каждое решение доступа должно иметь типизированный след аудита: субъект, действие, ресурс, контекст, результат, причина и использованные правила. | Обязательно |
| AAC-FR-16 | Опасные изменения доступа и внешних аккаунтов должны проходить через политику и, при необходимости, Human gate. | Обязательно |
| AAC-FR-17 | Сервис должен публиковать доменные события по изменениям организаций, пользователей, групп, членства, правил и внешних аккаунтов. | Обязательно |
| AAC-FR-18 | Домен должен давать оператору путь чтения для графа членства, пользователей в состояниях `pending` и `blocked`, внешних аккаунтов и объяснения доступа. | Обязательно |
| AAC-FR-19 | Домен не должен владеть проектами, репозиториями, зеркалом провайдера, жизненным циклом `run`/`job`, релизными решениями и доставкой уведомлений. | Обязательно |

## Критерии приёмки

| ID | Критерий |
|---|---|
| AAC-AC-1 | Если платформа стартует в одноорганизационном режиме, схема всё равно поддерживает несколько организаций без миграции модели. |
| AAC-AC-2 | Если пользователь входит впервые, платформа проверяет allowlist, создаёт или связывает профиль и назначает статус `active`, `pending` или `blocked`. |
| AAC-AC-3 | Если пользователь состоит в нескольких группах и организациях, итоговый доступ вычисляется детерминированно и объяснимо. |
| AAC-AC-4 | Если есть явный запрет, итоговое решение запрещает действие даже при наличии разрешающих правил. |
| AAC-AC-5 | Если внешний аккаунт используется другим доменом, другой домен получает ссылку и разрешённые операции, но не становится владельцем секретов и политики. |
| AAC-AC-6 | Если внешний аккаунт заблокирован или требует повторной авторизации, оператор видит статус и связанный контур использования. |
| AAC-AC-7 | Если сервис-владелец запрашивает доступ, он получает решение, версию политики и объяснение, достаточное для аудита. |
| AAC-AC-8 | Если команда повторяется после сетевой ошибки, идемпотентный ключ не создаёт второе бизнес-изменение. |

## Что не входит

- Не реализовывать код в рамках этого документа.
- Не проектировать полный набор экранов управления доступом.
- Не смешивать проверку доступа с Human gate по PR, релизу или риску.
- Не хранить зеркало провайдера, лимиты API и webhook-журнал в `access-manager`.
- Не выбирать окончательную платежную модель для SaaS-организаций.

## Нефункциональные требования

| ID | Категория | Требование |
|---|---|---|
| AAC-NFR-1 | Безопасность | Сырые секреты живут во внешнем хранилище секретов платформы, БД хранит только ссылку и метаданные, а значения не возвращаются через публичные API домена. |
| AAC-NFR-2 | Аудит | Все изменения доступа, членства, allowlist и внешних аккаунтов аудируются. |
| AAC-NFR-3 | Производительность | Проверка доступа для горячих операций должна работать без обращения к GitHub/GitLab. |
| AAC-NFR-4 | Надёжность | Изменение доступа публикует доменное событие через outbox в той же транзакции. |
| AAC-NFR-5 | Расширяемость | Модель должна поддерживать новые типы внешних аккаунтов и субъектов политики без произвольного JSON как основного контракта. |
| AAC-NFR-6 | Локализация | Пользовательские статусы, причины отказа и операторские объяснения должны поддерживать локали пользовательского интерфейса. |

## Зависимости

| Зависимость | Зачем нужна |
|---|---|
| `project-catalog` | Проверка контекста проекта, репозитория и проектной политики. |
| `provider-hub` | Использование внешних аккаунтов для операций провайдера, лимитов и webhook. |
| `agent-manager` | Проверяет через `access-manager`, можно ли выбранному субъекту запускать роль, использовать внешний аккаунт и выполнять действие над проектом, задачей, пакетом или средой исполнения. |
| `interaction-hub` | Human gate и уведомления по опасным изменениям доступа. |
| Vault или иное хранилище секретов платформы | Хранение секретов платформы и ссылок на секреты внешних аккаунтов. |

## Апрув

- request_id: `owner-2026-04-26-wave6-4-access-domain`
- Решение: approved
- Комментарий: требования домена доступа согласованы как целевое состояние.
