Agentfy для платформ: організації, власники та платники
Проєкт специфікації · AGNT2-424
Це лише документація. Організації, партнерський API, зв’язки акаунтів і призначення платника нижче ще не реалізовані. Документ замінює пропозицію AGNT2-423. Підтверджені рішення відокремлено від технічних рекомендацій; перед випуском потрібні перевірки реалізації.
Після прямої реєстрації людина отримує команду в організації Agentfy та стає власником і початковим відповідальним платником. BONSITE може підготувати команду клієнта за стабільними зовнішніми ID ще до першого відвідування. Типово платить BONSITE; оплата організацією та оплата командою обов’язкові вже у v1. Зміна власника чи платника не змінює організацію команди.
Угода про іменування (затверджено)
Organization — назва сутності, organizationId — її поле в моделі. Канонічний сегмент ресурсу API — orgs: /v1/orgs/{orgId}, де orgId — параметр шляху цієї організації. «Партнер» означає бізнес-роль або інтеграцію (наприклад, BONSITE як реселер), а не окремий простір endpoints організації. Видавець ідентичностей, зовнішній суб’єкт та автентифікація через партнера залишаються окремими технічними поняттями.
Підтверджені продуктові рішення
- Agentfy — типова організація, а не ознака адміністратора платформи. Її самостійно зареєстровані приватні команди ізольовані одна від одної.
- BONSITE керує входом у свій продукт і серверними ключами. Email, ім’я та пароль передавати необов’язково. ID користувача та команди різні: людина має кілька команд, команда — кількох людей.
- Пряма реєстрація робить творця власником. У серверному bootstrap
createdByфіксує сервіс-ініціатор, власником стає визначений зовнішній користувач, ніколи ключ. Передача особистої відповідальності за оплату потребує згоди нового платника. - Адміністратор може дозволити покриття організацією. Покриття Agentfy — внутрішнє спонсорство, не рахунок самому собі.
- Учасник клієнтської команди не стає учасником організації. Учасники організації — оператори партнера; ключі — сервісні суб’єкти, не вигадані люди.
- Користувач може залишатися в BONSITE, відкрити інтерфейс Agentfy або під’єднати незалежно підтверджений прямий акаунт. Збіг email не доводить тотожність.
Рекомендована архітектура
Зберігаємо стабільних суб’єктів прав та явні зв’язки. Прямий User і партнерський User — різні записи. ExternalIdentity(namespace, externalUserId) визначає партнерського суб’єкта; AccountLink дозволяє незалежно автентифікованому прямому акаунту явно вибрати його контекст. Зв’язок не переписує членство, власників агентів, рахунки чи історію.
Глобальне об’єднання користувачів зменшує кількість записів, але перетворює наявні запити userId → teams на можливий обхід прав. Безпечне об’єднання потребувало б походження кожного дозволу та широкої переробки авторизації. Окремі суб’єкти зберігають зміст ключів власності та дають змогу скасувати зв’язок без перенесення даних. Це обрана рекомендація, не готова схема БД.
Organization Agentfy ─ пряма команда ─ UserTeam(owner: прямий User D)
Organization BONSITE ─ команда партнера ─ UserTeam(owner: зовнішній User P)
незмінний namespace + externalUserId ─ ExternalIdentity ─ P
D ─ AccountLink ─ P (власність не змінюється)
Team ─ PayerAssignment за періодами ─ BillingAccount| Поняття | Значення та інваріант |
|---|---|
| Organization | Межа адміністрування/інтеграції; у команди рівно одна. У v1 немає перенесення між організаціями чи вкладених реселерів. |
| Namespace | Незмінна область організації та середовища. Test/prod розділяють ключі, суб’єктів, redirects і ресурси; перейменування BONSITE її не змінює. |
| User | Стабільний суб’єкт авторизації/власності. Прямий має незалежні credentials; партнерський належить одному namespace і може не мати email. |
| Спосіб входу | Доказ для прямого акаунта чи зовнішнього суб’єкта, не членство або платник. Партнерський ключ не відновлює прямі credentials. |
| ExternalIdentity | Постійна унікальна пара namespace + opaque subject, включно з tombstone; ID не використовують повторно. |
| AccountLink | Один активний прямий акаунт на зовнішній subject; прямий акаунт може мати кілька зв’язків. Без транзитивного обходу, email matching чи суми прав. |
| UserTeam | Унікальне членство суб’єкт + команда, owner/admin/member. Власників може бути кілька; дубль Team.ownerUserId не вводимо. |
| OrganizationMember | Окрема роль оператора, не наслідок членства у клієнтській команді. |
| BillingAccount | Відповідальний прямий користувач або організація. Контакт для рахунків — лише адреса повідомлень. |
| PayerAssignment | Одне чинне призначення на команду, неперетинні напіввідкриті інтервали та незмінна історія. Безплатний тариф не потребує платіжного мандата. |
| Мітка клієнта | Необов’язковий externalCustomerId для звітів, без прав і боргу. |
| Visitor | Гість embed-чату, не учасник команди; поточне виконання від власника — окрема межа продукту. |
Внутрішні та зовнішні ID незмінні. Зовнішній team ID унікальний у namespace незалежно від user ID; agent external ID — у команді. Прив’язки переживають строк квитанції операції; видалені ID залишаються зайнятими. Власність агента не створює приватного простору всередині спільної команди.
Доступ і довіра
Партнерська сесія діє лише як свій зовнішній суб’єкт, у своєму namespace та за активного членства. Зв’язок не відкриває прямі/особисті команди, інші організації, список зв’язків, credentials, особисті платіжні методи чи роль платформи. Прямий вхід явно активує партнерський контекст лише за активних link, subject, org policy та membership. Аудит фіксує фактичний акаунт автентифікації, чинного суб’єкта, джерело, організацію, команду та ID ключа/делегування.
BONSITE довірено підтверджувати своїх користувачів. Видавець, здатний стверджувати будь-який subject BONSITE, може діяти як він і читати доступний йому вміст. Окремі scope обмежують звичайний provisioning/billing ключ, але не приховують дані від зловмисного видавця ідентичностей або оператора з правом видавати такі ключі. Захист навіть від BONSITE потребував би незалежного користувацького доказу й не входить у v1. Обов’язкова межа навіть для такого видавця — недоступність прямого акаунта та інших namespace.
| Роль/суб’єкт | Явно дозволено | Не випливає з ролі |
|---|---|---|
| Власник організації | Активація/закриття, операторські ролі, договір; окремо підтверджене керування видавцем ідентичностей | Роль платформи, прямі акаунти |
| Адміністратор організації | Життєвий цикл команд, дозволені grants; покриття лише з фінансовим делегуванням | Чати/секрети, browser issuance звичайним admin-ключем |
| Розробник організації | Provisioning, діагностика операцій, профілі агентів у запиті | Фінансова згода, підвищення ролей, вхід provisioning-ключем |
| Billing організації | Рахунки/підсумки, згода організації платити, контакти | Чати, секрети, членство |
| Support організації | Безпечна діагностика; вміст лише за явним тимчасовим делегуванням | Постійна імперсонація |
| Власник команди | Налаштування, запрошення, передача власності, запит платника, видалення | Роль організації, згода за іншу людину |
| Адміністратор команди | Учасники за політикою, операції команди | Призначення/зняття власників, фінансова згода, видалення команди |
| Учасник команди | Дозволені дані та дії агентів | Керування учасниками/оплатою |
| Відповідальний платник | Свій мандат/рахунки, прийняття/припинення майбутньої відповідальності | Вміст/власність; членство необов’язкове |
| Сервісний суб’єкт | Точні scope/namespace; provisioning окремо від identity issuance | Людський власник, прямий вхід, платформа |
| Адміністратор платформи | Незалежно автентифіковане втручання/recovery з аудитом, причиною та строком support | Влада через organizationId=Agentfy |
Заборона типово діє у jobs, sockets, пошуку, експорті, сховищах, підписаних URL та cache keys, не лише в контролері. Чужі ID повертають нерозкривний 404. Зміна платника не дає членства/даних; зміна власника дає роль лише цільової команди, не організації/платформи/інших команд. У v1 клієнтські команди партнера приймають лише зовнішніх суб’єктів його namespace, прямі клієнти входять через AccountLink. Прямі запрошення — для Agentfy, оператори використовують явне делегування. Інакше зовнішній власник міг би запросити свій direct account і обійти deprovision.
Порядок читання
- Ідентичність і сценарії: екрани, browser-протокол, зв’язки та recovery.
- Provisioning та оплата: запропоновані запити, повтори, фінансові переходи.
- Міграція та самоперевірка: поточний код, атаки/гонки, умови випуску.
Поточний білінг і гостьове вбудовування описують реалізовану поведінку, не гарантії цього проєкту.