УвійтиЗамовити брифінг

Розділ 2.19

Правила, які успадковує кожне розширення

Ізоляція за трьома осями, обчислення через UNO, ШІ (штучний інтелект) через маршрутизатор, ключі у власності організації та перевірки ліцензій. Що кожне правило означає для вашого коду, який контрольний рубіж (gate) забезпечує його виконання і чому ви успадковуєте цю логіку, а не пишете її самі.

Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

15 хв читання

Першу у своїй історії відмову мій плагін для перевірки аномалій надіслав мені самому. За звичкою з іншої платформи я написав тестовий клієнт, який надсилав нову перевірку з ідентифікатором організації в тілі запиту, і плагін відповів ще до того, як запустився мій обробник:

{
  "error": true,
  "code": "TENANT_NOT_A_PARAMETER",
  "message": "The request body names the organisation. Tenancy comes from the token.",
  "resolved": ["tenant", "owner"],
  "missing": [],
  "troubleshooting": ["Remove organizationId from the body. The organisation is read from your sign-in."]
}

Я не писав цієї перевірки. Вона надійшла разом із захисником області видимості (scope guard), який шаблон SDK (набору засобів розробки ПЗ) вбудовує в кожен маршрут /api, і вона спрацьовує, навіть коли ідентифікатор у тілі запиту належить самому ініціатору виклику. Це патерн для всього цього розділу: невелика кількість правил, кожне з яких примусово застосовується успадкованим вами механізмом, і кожне має контрольний шлюз (gate), який зупиняє збирання з помилкою, якщо ваш код намагається його обійти. У Nexus ваш плагін успадковує свою ізоляцію від платформи, а шлюзи проводять її аудит.

Існує п'ять правил, і в розділах нижче їх розглянуто по черзі: ізоляція за трьома осями; обчислення, що виконуються лише через диспетчеризацію UNO; ШІ (штучний інтелект), що працює лише через маршрутизатор постачальників ШІ (AI Provider Router); ключі моделей, що належать організації; і ліцензовані функції, що звіряються з ліцензією. Кожен маніфест також повторює три з них в одному блоці речень.

Правило 1: ізоляція за трьома осями на основі автентифікованого запиту

Кожна операція читання та запису в розширенні обмежується областю видимості за трьома осями, як і кожен виклик інструменту та диспетчеризація навички.

Вісь Стовпець Відповідає на питання Наскільки жорсткою є межа
Тенант (Tenant) organization_id Яка організація Жорстка межа, яку можна перетнути лише за допомогою зареєстрованого дозволу тільки на читання
Власник (Owner) owner_user_id Яка особа всередині організації Приватно навіть усередині однієї організації для всього особистого
Підрозділ (Unit) business_unit_id Яка частина організації Необов'язковий бар'єр усередині тенанта

Вісь власника (owner) — це те, у чому новачки найчастіше помиляються. Поштова скринька є особистою, так само як і збережене подання або граф, побудований на основі даних однієї особи. Два учасники однієї організації, в одному підрозділі та з однаковою роллю, не бачать рядків один одного, обмежених областю видимості власника. В артефакті організації — наприклад, у затвердженні чи записі справи — власник натомість указує на походження: він фіксує, хто виконав дію, а читання обмежується областю видимості тенанта, щоб аудиторський слід залишався видимим для людей, яким він потрібен. Ви самі для кожної таблиці вирішуєте, який це тип, і рівень репозиторію закріплює це в коді — жодних особливих випадків у маршруті.

Осі надходять із автентифікованого запиту і більше нізвідки. Змінна середовища не може їх надати, як і параметр запиту, сегмент шляху, заголовок клієнта чи константа збирання. SDK ускладнює написання неправильного коду: resolveScope(identity, options) взагалі не має параметра організації. Організація міститься всередині identity, і створити його може лише перевірений токен. Тут просто немає через що передати ідентифікатор.

Ось чому тіло запиту, у якому вказано тенанта, відхиляється, а не ігнорується. Захисник відхиляє будь-яке з п'яти імен полів: orgId, organizationId, organization_id, tenant та tenantId. Поле, яке тихо ігнорується, привчає ініціатора виклику до думки, що воно працює. Перший ініціатор тестує його й бачить власні дані; другий надсилає ідентифікатор іншої організації. Відмова на першому ж запиті чітко окреслює контракт, перш ніж хтось побудує логіку на хибному припущенні. Те саме правило діє для inputParams під час диспетчеризації: вхідні дані навички, які містять ідентифікатор організації, відхиляються під час диспетчеризації.

Вісь підрозділу або оголошується й примусово застосовується, або не використовується взагалі. Маршрут, який оголошує needsUnit: true, відповідає відмовою, коли облікові дані не визначають підрозділ, вказуючи unit у missing[]. Не синтезуйте підрозділ із піддомену чи заголовка та не задавайте його за замовчуванням. Вигаданий підрозділ встановлює бар'єри інакше, ніж реальні підрозділи організації, і об'єднує рядки, які об'єднувати не слід.

Інтерфейс, який не може виразити предикат, відхиляє запит

Якщо маршрут не може визначити, якому тенанту та власнику належить рядок, а також якому підрозділу (коли це необхідно), він відповідає відмовою. Тут немає читання в масштабі всієї організації як резервного варіанта і немає значень-заповнювачів. Заповнювач — це найгірший варіант, оскільки заповнювач є значенням, а значення збігаються з рядками: маршрутизатор інструментів, який за замовчуванням встановлював і для тенанта, і для користувача рядок 'unknown', видавав дані всієї організації кожному, хто його викликав. На межі тенанта ?? 'unknown' є дефектом.

Відмова має однакову форму всюди на платформі й містить достатньо інформації, щоб клієнт міг відобразити спосіб виправлення:

{
  "error": true,
  "code": "SCOPE_PREDICATE_MISSING",
  "message": "Request cannot be scoped to a tenant from the presented credential.",
  "resolved": ["tenant", "owner"],
  "missing": ["unit"],
  "troubleshooting": [
    "The credential resolved tenant+owner; this route additionally requires a business unit.",
    "Select a business unit in the client and retry — re-authentication will not change this outcome."
  ]
}

error завжди має значення true. code береться з каталогу кодів платформи. resolved[] називає осі, які вдалося вивести, а missing[] — ті, які були потрібні маршруту, але він не зміг їх отримати. troubleshooting[] пояснює, що саме допоможе це виправити. Голе «заборонено» нікого нічого не вчить.

Розрізняйте коди 401 і 403, оскільки клієнти реагують на них по-різному.

Статус Значення Що робить клієнт
401 Не автентифіковано Входить у систему знову
403 Автентифіковано, але для запиту неможливо визначити область видимості, або в ініціатора виклику немає відповідного права Припиняє повторні спроби та змінює запит

Відмова через область видимості, повернена з кодом 401, відправляє клієнта в нескінченний цикл входу, який жоден вхід не може завершити: він скидає сеанс і входить знову, повторює спробу й знову отримує 401, поки користувач безкінечно дивиться на індикатор завантаження.

Ще два механізми роблять відмову абсолютною. Усередині обробника scopeOf(req) є єдиним способом прочитати область видимості, і він генерує виняток, якщо захисник не спрацював. А захисник запускається після розбору тіла запиту й перед будь-яким обробником; обробник, який стає доступним без предиката, навмисно відповідає кодом 500 із MIDDLEWARE_ORDERING_ERROR, щоб це потрапило у ваш бюджет помилок, а не у звіт про інцидент.

База даних самостійно утримує ту саму межу

Бар'єр у коді та бар'єр у базі даних — це два механізми одного закону, і ви отримуєте обидва.

Кожен оператор для таблиці з обмеженою областю видимості формує tenantFence(scope) із SDK; ви ніколи не пишете предикат вручну. Кожен оператор також виконується всередині withScopedTx, який прив'язує три осі для цієї конкретної транзакції через єдину функцію бази даних і відхиляє повторну прив'язку (SCOPE_ALREADY_BOUND). На нижчому рівні для кожної таблиці у вашій схемі примусово ввімкнено захист на рівні рядків (row-level security), а роль, під якою підключається ваш шлях запиту, не може самостійно змінити прив'язаного тенанта. Процес, який підключається під роллю, здатною обходити захист на рівні рядків, відмовляється завантажуватися з помилкою DB_ROLE_BYPASSES_ISOLATION. У розділі 2.22 «Середовище виконання плагіна» показано код; у розділі 2.21 «SDK плагіна» показано, як ролі формуються для вас.

Єдиний виняток для перетину межі: зафіксований дозвіл

Існує рівно один шлях через межу тенанта. Організація, яка володіє рядками, реєструє дозвіл, у якому вказано, яка організація може читати які таблиці, за якою угодою і протягом якого часу. База даних робить це читання доступним лише для читання, і кожен перегляд записується перед сами́м читанням в обох організаціях лише за ідентифікатором. Записи ніколи не перетинають межу; робота, передана іншій фірмі, надсилається як повідомлення. Ролі власника та адміністратора взагалі ніколи не читають дані через межу, і маніфест відхиляється, якщо право, яке допускає міжорганізаційне читання, не забороняє їм це робити. Плагін, який хоче знайти інший шлях через межу, його не отримає.

Правило 2: усі обчислення виконуються через диспетчеризацію UNO

UNO, рушій робочих процесів, є єдиним шляхом для обчислень. Ваш код ніколи не звертається напряму до постачальника моделі чи рушія, а також до черги чи хосту робочих процесів. Ви надсилаєте один конверт до кінцевої точки диспетчеризації й отримуєте у відповідь 202 з ідентифікаторами; результат надходить шляхом опитування (polling) або через зворотний виклик (callback).

Звідси випливають три правила, і в шаблоні вже реалізовано всі три.

  • Один файл відповідає за URL-адресу диспетчеризації. UNO_DISPATCH_URL зчитується один раз у завантажувачі конфігурації і має бути внутрішньокластерною адресою. Публічна адреса відхиляється під час завантаження, оскільки нічого не виходить за межі інсталяції.
  • Один закритий список дозволеного (allow-list) для того, що ця поверхня може диспетчеризувати. Бекенд, який диспетчеризує будь-який ідентифікатор навички, переданий браузером, перетворюється на проксі загального призначення для кожної навички в реєстрі, включно з навичками інших плагінів і навичками, що витрачають чужий бюджет на моделі. Цей список є константою рівня модуля з типами завдань у просторі імен, і ніколи — змінною середовища. Ідентифікатор, якого немає в списку, відхиляється з помилкою SKILL_NOT_ALLOWED.
  • Перевіряйте те, що повертається. Коли ви зчитуєте завдання назад, клієнт SDK порівнює organization_id повернутого рядка з тенантом ініціатора виклику на вашому боці мережевого виклику. Бар'єр, який існує лише на іншому боці виклику, — це просто домовленість.

Правило 3: увесь трафік ШІ проходить через AI Provider Router

Плагін ніде не здійснює жодних викликів до моделі. У package.json немає SDK постачальника, у середовищі немає ключа моделі й немає ретранслятора. Лише маршрутизатор зберігає облікові дані постачальника організації та приймає остаточне рішення щодо постачальника й моделі.

Що плагін може зробити, так це висловити побажання під час реєстрації в рядку реєстру навички маніфесту:

{
  "execution_config_skill": {
    "preferredProvider": "gemini",
    "preferredModel": "gemini-3.5-flash",
    "capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
  }
}

Маршрутизатор виконує побажання лише тоді, коли в організації цього постачальника ввімкнено й забезпечено обліковими даними. В іншому разі він здійснює заміну з власного пулу організації. capabilityProfile ніколи не вибирає; він фільтрує, а його поле dataResidency є жорстким юрисдикційним обмеженням, яке маршрутизатор або задовольняє, або відхиляє. Пропустити все це — правильний варіант за замовчуванням для більшості навичок: тоді все вирішують власні призначення ролей організації, адже саме організація за це платить.

У відповідь можуть надійти два види відмов, і вони означають зовсім різні речі.

Код Статус Що це означає
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER 403 Ваш код намагався викликати маршрутизатор самостійно. Зупиніться: це стик, який відповідає відмовою за проєктом, і повторні спроби тут не допоможуть
MODEL_CAPABILITY_UNAVAILABLE 422 Жоден увімкнений постачальник не має моделі, яка задовольняє профіль. Послабте вимоги профілю, або нехай організація увімкне відповідного постачальника
NO_PROVIDER_FOR_ROLE 422 Організація не налаштувала маршрутизацію для цієї ролі. Покажіть користувачеві текст маршрутизатора з інструкціями щодо виправлення

Другій парі місце на екрані, а не в журналі. Тут немає моделі за замовчуванням і резервного постачальника: роль, яку організація не налаштувала, завершується гучним збоєм із реченням, де вказано, що саме потрібно налаштувати.

Єдиний запит на читання, який плагін може зробити до маршрутизатора, — це effectiveRoute() із runtime/ai-route. Він відповідає, якого постачальника та модель маршрутизатор вибрав би для авторизованої організації без надсилання запиту до ШІ, і повертає словесну відмову маршрутизатора, коли моделі немає. Це показано в розділі 2.22 «Середовище виконання плагіна».

Сходи довіри додають ще одну межу. Лише плагіни core та verified можуть оголошувати два рівні навичок маніфесту, які звертаються до маршрутизатора: tool_using та llm_only. Усі інші виступають посередниками для детермінованої роботи й дозволяють платформі виконувати частину, пов'язану зі зверненням до моделей.

Правило 4: ключі належать організації

Кожна організація використовує власний обліковий запис і ключ постачальника та сама оплачує свої рахунки. Ключ зберігається в пулі постачальників ШІ організації, яким керують її власні адміністратори з консолі, а маршрутизатор визначає його під час виклику. За тенантом немає спільного ключа платформи, тому жодна організація не витрачає бюджет іншої.

Для розширення це означає три речі.

  • Ви ніколи не зберігаєте ключ моделі — ані в коді, ані в конфігурації, ані в сховищі секретів. Шлюз no-credentials зупиняє збирання з помилкою, якщо ключ доступний для читання, а завантажувач конфігурації відмовляється запускатися, якщо він присутній.
  • Ви ніколи не перераховуєте ключі організації. Якщо ваш плагін вважає, що йому це потрібно, отже, цю вимогу розміщено не в тому місці.
  • Організація без ключа не отримує відповідей від ШІ. Це очікуваний стан із реальним екраном. Назвіть відсутню роль, процитуйте інструкцію з виправлення, а потім спрямуйте користувача до налаштувань його постачальника. Не відображайте це як порожній результат.

Правило 5: ліцензовані функції перевіряються за ліцензією

Те, що інсталяція може використовувати понад базовий рівень Community, визначається в одному місці: у документі ліцензії, який підписує Adverant і який перевіряється на інсталяції лише за допомогою відкритих ключів. Ваше розширення ніколи не приймає рішень на основі чогось слабшого, наприклад назви плану в токені чи прапорця в конфігурації.

У плагіні найпростіший спосіб прив'язати функцію до ліцензії — зробити це в праві, яке її захищає. Право в реєстрі rights маніфесту може вказувати функцію licence:

"rights": {
  "evidence.export": {
    "summary": "Export the evidence pack for an inspection.",
    "roles": ["owner", "admin", "member"],
    "licence": "compliance-packs"
  }
}

Кожен, хто викликає маршрут, захищений цим правом, отримує відмову з LICENCE_LOCKED (403), незалежно від своїх ролей і місць (seats), якщо ліцензія організації не містить compliance-packs. У відмові вказується сама функція, те, де вона міститься, а також хто може її увімкнути.

Стан ліцензії також має значення. Поки ліцензія дійсна або перебуває у вікні попередження, ліцензовані функції працюють; вони продовжують працювати й у пільговому періоді (grace), який показує сповіщення LICENCE_IN_GRACE. Коли пільговий період ліцензії минає, вона переходить у режим обмеження: поточні процеси та читання тривають, як і експорт та оновлення безпеки, але створення чогось нового в межах ліцензованої функції відхиляється з кодом LICENCE_LOCKED. Будуйте свої шляхи створення з розрахунком на таку відповідь.

Коли ваш плагін запитує у перевірки прав (entitlement check), чи має організація певну функцію, він отримує вердикт, а не просто булеве значення. «Недоступно» та «доступно, і відповідь — ні» — це різні факти з різними кодами: ENTITLEMENT_UNREACHABLE (502) та ENTITLEMENT_DENIED (403). Короткочасний збій доступності в жодному разі не повинен тихо понижувати кожного клієнта до безкоштовного базового рівня.

Маніфест і дозволи
Маніфест і дозволи
Розділ «Маніфест і дозволи» порівнює те, що оголошує поточний реліз, із попереднім. Тут версія 0.4.0 додає надсилання пошти та одну зовнішню адресу, тому реліз затримується зі статусом MANIFEST_SCOPE_WIDENED, доки не погодяться два рецензенти та спеціаліст із відповідності вимогам (compliance officer).

Маніфест повторно закріплює правила

Кожен маніфест версії v2 містить блок architecture із трьома обов'язковими реченнями, і валідатор жорстко перевіряє їхнє формулювання. У плагіні, який ви створюєте для власної інсталяції, вони звучать так:

"architecture": {
  "compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
  "ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
  "deploy": "Deploy is through the installation's release channels only."
}

Ці речення перевіряються. Плагін, чий маніфест погодився із законами, тоді як його код звертався б до постачальника моделі, брехав би у власному контракті, і шлюзи існують саме для того, щоб цю брехню можна було виявити.

Контрольні рубежі, що забезпечують виконання кожного правила

SDK постачає двадцять два шлюзи дотримання правил як одну команду — nexus-gates. У розділі 2.21 «SDK плагіна» описано кожен із них. Тут їх згруповано за правилом, яке вони підтримують.

Правило Шлюзи Що зупиняє збирання з помилкою
Ізоляція на рівні маршрутів scope-adherence, one-fence, rights-register, crud-adherence Маршрут /api без захисника області видимості; другий написаний вручну предикат тенанта; маршрут області видимості без права; маршрут модифікації даних, чиє право нічого не вказує
Ізоляція в SQL sql-fence, no-set-config Оператор для таблиці з обмеженою областю видимості без бар'єра; код плагіна, що самостійно прив'язує налаштування тенанта
Ізоляція в базі даних migrations-are-scoped, rls-present, db-role-honest Таблиця без осі або без ключа, що починається з тенанта; таблиця без примусового захисту на рівні рядків; шлях запиту, що підключається як власник або суперкористувач
Єдиний перетин grants-declared Таблиця, на яку надано дозвіл у міграціях, але яку не оголошено в маніфесті, або місце для читання (read seat), якому привілеї надано вручну
Обчислення через UNO no-direct-compute Пряме звернення до постачальника моделі чи рушія або до черги чи хосту робочих процесів; друге зчитування URL-адреси диспетчеризації
ШІ та ключі no-credentials Облікові дані постачальника моделі, доступні для читання в репозиторії або середовищі
Оголошений контракт api-contract, platform-clients, declared-input Маршрут, який зареєстровано, але не оголошено, або оголошено, але не зареєстровано; клієнт платформи, який імпортовано, але не вказано

Кожен шлюз має самотестування, яке доводить, що він видає помилку на тестовому наборі даних (fixture), створеному спеціально для його спрацьовування. Команда npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test запускає їх усі, і шлюз, який перестав видавати помилку на власному тестовому наборі, перестав працювати.

Куди може звертатися застосунок
Куди може звертатися застосунок
У розділі «Куди може звертатися застосунок» перелічено кожну зовнішню адресу, яку оголосив застосунок, і вказано, чи затвердив її спеціаліст із відповідності вимогам. Виклик за адресою, яку ніхто не оголошував, зупиняється й підраховується ще до того, як будь-які дані залишать систему.

Перш ніж подати запит на перевірку

Ось список, за яким я проходжуся, перш ніж попросити колегу перевірити плагін. Кожен пункт — це те, через що рецензент у Corrán Orbital принаймні один раз повертав мені код на доопрацювання.

  1. Кожен маршрут /api реєструє захисник області видимості, а єдиними анонімними маршрутами є точні шляхи, оголошені як auth: public із allowAnonymous: true.
  2. Кожен маршрут, який обслуговує захисник області видимості, вказує right із реєстру маніфесту, і жоден обробник не містить власної перевірки прав.
  3. Жоден обробник не зчитує організацію, особу чи підрозділ із тіла запиту, рядка запиту чи заголовка.
  4. Кожен оператор для таблиці з обмеженою областю видимості проходить через tenantFence усередині withScopedTx, і ніщо в репозиторії не викликає set_config.
  5. Кожна таблиця має три стовпці осей, первинний ключ, що починається з organization_id, і складені зовнішні ключі, які містять тенанта.
  6. URL-адреса диспетчеризації зчитується в одному файлі, а список дозволеного для диспетчеризації є константою з типами завдань у просторі імен.
  7. Ніщо в package.json не звертається до постачальника моделі, і в середовищі немає жодного ключа.
  8. Кожна функція, яка доступна лише за деякими ліцензіями, вказує свій licence у праві, яке її захищає.
  9. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test є зеленим, як і npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.

Якщо всі дев'ять пунктів виконуються, перевірка стосуватиметься вашого продукту — а саме на це і має витрачатися час рецензента.

Чому платформа вимагає дотримання цих правил

Кожне з наведених вище правил колись десь було просто домовленістю, і кожна домовленість зазнавала краху однаково: з маршрутами, які про неї пам'ятали, все було гаразд, а той єдиний, який забував, ставав причиною інциденту. Бар'єр бізнес-підрозділу, застосований як необов'язкове проміжне ПЗ (middleware), обійшли шістьма незалежними способами — і щоразу це був маршрут, де його просто не підключили. Змінна середовища, яка перезаписувала ідентифікатор тенанта, видала одній організації 1406 контактів іншої, і під час перевірки коду все виглядало правильно, тому що це було правильно для того пода (pod), для якого воно писалося.

Тому платформа розміщує предикат там, де через нього вже проходить кожна поверхня: у захиснику області видимості та функції бар'єра, в обгортці транзакцій та примусовому захисті на рівні рядків, а також у клієнті диспетчеризації. Потім шлюз перебирає кожен маршрут, кожен оператор і кожен імпорт та зупиняє збирання з помилкою, коли один із них звертається до таблиці з обмеженою областю видимості, моделі або обчислювального рушія в обхід цих механізмів. Ціна такого підходу полягає в тому, що під час створення першого плагіна ви почуваєтеся обмеженими. Вигода ж у тому, що тисячний плагін буде ізольований навіть тоді, коли його автор не знатиме про існування цієї функції, оскільки іншого шляху до даних для нього просто не існує.

У всього цього є чесна межа. Шлюзи доводять, що ваш код проходить через необхідні механізми; але вони не можуть довести, що логіка вашого продукту є правильною. Маршрут, який правильно обмежує запит рядками власника, все одно може показати неправильні рядки правильному власнику. Набір тестів ізоляції в розділі 2.22 «Середовище виконання плагіна» атакує кожен маршрут від імені іншої організації та від імені колеги, по черзі знімаючи кожен бар'єр, і це саме той тест, який я б запустив, перш ніж довіряти власному розумінню будь-чого з написаного тут.