Версия 1.0.0-alpha.1последно
Глава 2.19
Правилата, които всяко разширение наследява
Изолация по три оси, изчисления чрез UNO, ИИ (изкуствен интелект) през маршрутизатора, ключове, притежавани от организацията, и проверки на лиценза. Какво означава всяко правило за Вашия код, коя проверка го налага и защо го наследявате, вместо да го пишете сами.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Първият отказ, който моята приставка за преглед на аномалии някога изпрати, беше до мен. Бях написал тестов клиент, който публикуваше нов преглед с идентификатора на организацията в тялото на заявката, по навик от друга платформа, и приставката отговори, преди моят обработчик да се изпълни:
{
"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."]
}Не бях писал тази проверка. Тя дойде със защитата на обхвата, която шаблонът на SDK (пакет за разработка на софтуер) вгражда във всеки /api маршрут, и се задейства дори когато идентификаторът в тялото е на самия извикващ. Това е моделът за цялата тази глава: малък брой правила, всяко наложено от механизъм, който наследявате, всяко с контролна точка (gate), която проваля компилирането ви, ако кодът ви я заобиколи. В Nexus вашата приставка наследява своята изолация от платформата, а контролните точки я одитират.
Има пет правила и разделите по-долу ги разглеждат подред: изолация по три оси; изчисления, които се изпълняват само чрез диспечеризация на UNO; ИИ (изкуствен интелект), който преминава само през AI Provider Router; ключове за модели, които принадлежат на организацията; и лицензирани функции, проверявани спрямо лиценза. Всеки манифест също така преформулира три от тях в един блок от изречения.
Правило 1: изолация по три оси от удостоверената заявка
Всяко четене и запис в дадено разширение е ограничено по обхват по три оси, както и всяко извикване на инструмент и диспечеризация на умение.
| Ос | Колона | Отговаря на | Колко твърда е границата |
|---|---|---|---|
| Наемател (Tenant) | organization_id |
Коя организация | Твърда граница, пресичана само чрез записано разрешение само за четене |
| Собственик (Owner) | owner_user_id |
Кое лице вътре в организацията | Частно дори в рамките на една организация, за всичко лично |
| Звено (Unit) | business_unit_id |
Коя част от организацията | Незадължителна преграда вътре в клиента (tenant) |
Оста на собственика (owner) е тази, при която новите потребители грешат. Пощенската кутия е лична, както и запазеният изглед или графиката, извлечена от данните на един човек. Двама членове на една и съща организация, в едно и също звено с една и съща роля, не виждат редовете на другия, ограничени по обхват до собственика. При организационен артефакт, например одобрение или запис по случай, собственикът всъщност указва произхода: той записва кой е действал, а четенията са ограничени по обхват до клиента (tenant), така че одитната следа остава видима за хората, които се нуждаят от нея. Вие решавате за всяка таблица от кой вид е тя, а слоят на хранилището го кодира, никога като специален случай в маршрут.
Осите идват от удостоверената заявка и от никъде другаде. Променлива на средата не може да ги предостави, нито параметър на заявка, сегмент от път, заглавка на клиент или константа на компилиране. SDK прави грешното нещо трудно за написване: resolveScope(identity, options) изобщо няма параметър за организация. Организацията е вътре в identity и само потвърден токен създава такъв. Няма през какво да се подаде идентификатор.
Ето защо тяло на заявка, назоваващо клиента (tenant), бива отказано, а не игнорирано. Защитата отказва всяко от петте имена на полета: orgId, organizationId, organization_id, tenant и tenantId. Тихо игнорирано поле учи извикващия, че полето работи. Първият извикващ го тества и вижда собствените си данни; вторият изпраща идентификатор на различна организация. Отказът още при първата заявка назовава договора, преди някой да надгради върху грешния. Същото правило важи и за inputParams на диспечеризация: входни данни на умение, които носят идентификатор на организация, получават отказ при диспечеризация.
Оста на звеното (unit) или се декларира и налага, или не се използва. Маршрут, който декларира needsUnit: true, отказва, когато идентификационните данни не разрешават звено, като unit е назовано в missing[]. Не синтезирайте звено от поддомейн или заглавка и не задавайте такова по подразбиране. Измисленото звено поставя прегради по различен начин от реалните звена на организацията и обединява редове, които не би трябвало.
Повърхност, която не може да изрази предиката, отказва достъп
Ако даден маршрут не може да каже на кой клиент (tenant) и собственик принадлежи даден ред, както и на кое звено, когато се нуждае от такова, той отказва. Няма четене за цялата организация като резервен вариант и няма стойност на заместител. Заместителят е най-лошият вариант, защото заместителят е стойност, а стойностите съвпадат с редове: маршрутизатор на инструменти, който задаваше по подразбиране и за клиент, и за потребител низа 'unknown', обслужваше данни за цялата организация на всеки, който го извика. На границата на клиента (tenant), ?? '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[] казва какво всъщност би го поправило. Голото „забранено“ (forbidden) не учи никого на нищо.
Разграничавайте 401 и 403, защото клиентите действат различно при тях.
| Състояние | Значение | Какво прави клиентът |
|---|---|---|
| 401 | Не е удостоверен | Влиза отново |
| 403 | Удостоверен, но заявката не може да бъде ограничена по обхват или на извикващия му липсва правото | Спира повторните опити и променя заявката |
Отказ на обхват, върнат като 401, изпраща клиента в цикъл на влизане, който никое влизане не може да прекрати: той изхвърля сесията и влиза отново, опитва пак и отново получава 401, докато човекът гледа вечно въртящ се индикатор.
Още два механизма правят отказа пълен. Вътре в обработчика scopeOf(req) е единственият начин за четене на обхвата и той хвърля грешка, ако защитата не се е изпълнила. А защитата се изпълнява след анализа на тялото и преди всеки обработчик; обработчик, който стане достъпен без предиката, отговаря с 500 с MIDDLEWARE_ORDERING_ERROR, умишлено, така че да попадне във вашия бюджет за грешки, вместо в доклад за инцидент.
Базата данни сама поддържа същата граница
Преградата в кода и преградата в базата данни са два механизма за един закон и вие получавате и двата.
Всеки оператор срещу таблица с ограничен обхват съставя tenantFence(scope) от SDK; никога не пишете предиката на ръка. Всеки оператор също така се изпълнява вътре в withScopedTx, което обвързва трите оси за тази една транзакция чрез единична функция на базата данни и отказва второ обвързване (SCOPE_ALREADY_BOUND). Отдолу всяка таблица във вашата схема има принудително включена защита на ниво ред (row-level security) и ролята, като която се свързва вашият път на заявката, не може сама да промени обвързания клиент (tenant). Процес, който се свързва като роля, способна да заобиколи защитата на ниво ред, отказва да стартира с DB_ROLE_BYPASSES_ISOLATION. Глава 2.22, Средата за изпълнение на приставки, показва кода; глава 2.21, SDK за приставки, показва как ролите се генерират за вас.
Единственото пресичане: записано разрешение
Има точно един начин за преминаване през границата на клиента (tenant). Организацията, която държи редовете, записва разрешение, назоваващо коя организация кои таблици може да чете, съгласно кое споразумение и за колко време. Базата данни прави четенето само за четене и всеки поглед се записва преди четенето, и в двете организации, само по идентификатор. Записите никога не преминават границата; работата, предадена на друга фирма, пътува като съобщение. Ролите на собственик и администратор никога не четат през границата и манифестът бива отказан, ако правото, което допуска четене между организации, не ги блокира. Приставка, която иска друг начин за преминаване, не получава такъв.
Правило 2: всички изчисления преминават през диспечера на UNO
UNO, двигателят за работни потоци, е единственият изчислителен път. Вашият код никога не извлича директно доставчик на модели или двигател, нито пък опашка или хост на работни потоци. Изпращате един плик до крайната точка за диспечеризация и получавате обратно 202 с идентификатори; резултатът пристига чрез периодично запитване (polling) или чрез обратно извикване (callback).
Следват три навика и шаблонът вече има и трите.
- Един файл притежава URL адреса за диспечеризация.
UNO_DISPATCH_URLсе чете веднъж в зареждащия модул за конфигурация и трябва да бъде адрес вътре в клъстера. Публичен адрес се отказва при стартиране, защото нищо не напуска инсталацията. - Един затворен списък с разрешени елементи (allow-list) за това какво може да диспечеризира тази повърхност. Бекенд, който ще диспечеризира всеки идентификатор на умение, подаден му от браузър, е прокси с общо предназначение за всяко умение в регистъра, включително умения на други приставки и умения, които харчат бюджета за модели на някой друг. Списъкът е константа на ниво модул от типове задачи с пространство от имена, никога променлива на средата. Идентификатор, който не е в него, получава отказ с
SKILL_NOT_ALLOWED. - Проверете отново какво се връща. Когато прочетете задача обратно, клиентът на SDK сравнява
organization_idна върнатия ред с клиента (tenant) на извикващия от вашата страна на мрежовото извикване. Преграда, която съществува само от другата страна на извикването, е просто конвенция.
Правило 3: целият ИИ преминава през маршрутизатора на доставчици на ИИ
Приставката не прави извиквания към модел никъде. Няма SDK на доставчик в package.json, няма ключ за модел в средата и няма препредаване (relay). Единствено маршрутизаторът държи идентификационните данни за доставчика на организацията и взема окончателното решение за доставчик и модел.
Това, което една приставка може да направи, е да изрази желания по време на регистрацията в реда на регистъра за умението в манифеста:
{
"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: ключовете принадлежат на организацията
Всяка организация носи свой собствен акаунт и ключ за доставчик и плаща собствената си сметка. Ключът живее в пула от доставчици на ИИ на организацията, управляван от собствените ѝ администратори от конзолата, а маршрутизаторът го разрешава по време на извикването. Няма споделен ключ на платформата зад клиент (tenant), така че никоя организация не харчи бюджета на друга.
За едно разширение това означава три неща.
- Никога не държите ключ за модел, независимо дали в код, конфигурация или хранилище за тайни. Контролната точка
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), каквито и роли и места да заема, когато лицензът на организацията не носи compliance-packs. Отказът назовава функцията и какво я носи, и казва кой може да я включи.
Състоянието на лиценза също има значение. Докато лицензът е валиден или е в своя предупредителен прозорец, лицензираните функции работят и продължават да работят в гратисния период, а гратисният период показва известието LICENCE_IN_GRACE. След като лицензът изтече след гратисния период, той ограничава: текущата работа и четенията продължават, както и експортирането и актуализациите за сигурност, но създаването на нещо ново под лицензирана функция се отказва с LICENCE_LOCKED. Изградете вашите пътища за създаване, очаквайки този отговор.
Когато вашата приставка попита проверката за права дали дадена организация притежава функция, тя получава присъда, никога гола булева стойност. „Недостъпен“ и „достъпен и не“ са различни факти с различни кодове: ENTITLEMENT_UNREACHABLE (502) и ENTITLEMENT_DENIED (403). Моментно прекъсване на достъпността никога не трябва тихо да понижава всеки клиент до безплатното базово ниво.
MANIFEST_SCOPE_WIDENED, докато двама проверяващи и служителят по съответствието не се съгласят.Манифестът преповтаря закона
Всеки 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 без защита на обхвата, втори ръчно написан предикат за клиент (tenant), маршрут с обхват без право, променящ маршрут, чието право не назовава нищо |
| Изолация в SQL | sql-fence, no-set-config |
Оператор върху таблица с ограничен обхват без преградата; код на приставка, обвързващ сам настройката за клиент (tenant) |
| Изолация в базата данни | migrations-are-scoped, rls-present, db-role-honest |
Таблица с липсваща ос или ключ, започващ с клиента (tenant), таблица без принудителна защита на ниво ред, път на заявка, свързващ се като собственик или суперпотребител |
| Единственото пресичане | grants-declared |
Таблица, предоставена в миграции, която манифестът не декларира, или място за четене с ръчно раздадени привилегии |
| Изчисления чрез 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 ми е връщал поне веднъж.
- Всеки
/apiмаршрут регистрира защитата на обхвата, а единствените анонимни маршрути са точни пътища, декларирани вauth: publicсallowAnonymous: true. - Всеки маршрут, обслужван от защитата на обхвата, назовава
rightот регистъра на манифеста и никой обработчик не носи собствена проверка на права. - Никой обработчик не чете организация, лице или звено от тялото, заявката или заглавка.
- Всеки оператор върху таблица с ограничен обхват преминава през
tenantFenceвътре вwithScopedTxи нищо в хранилището не извикваset_config. - Всяка таблица има трите колони за оси, първичен ключ, който започва с
organization_id, и съставни външни ключове, които носят клиента (tenant). - URL адресът за диспечеризация се чете в един файл, а списъкът с разрешени елементи за диспечеризация е константа от типове задачи с пространство от имена.
- Нищо в
package.jsonне говори с доставчик на модели и в средата не стои никакъв ключ. - Всяка функция, която само някои лицензи носят, назовава своя
licenceвърху правото, което я защитава. 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), беше заобиколена по шест независими начина, всеки от които маршрут, който никога не се е включил. Променлива на средата, която презаписваше идентичността на клиента (tenant), обслужи на една организация 1,406 контакта на друга и това изглеждаше правилно при прегледа, защото беше правилно за пода (pod), за който беше написано.
Затова платформата поставя предиката там, откъдето всяка повърхност вече преминава през него: в защитата на обхвата и функцията за преграда, в обвивката на транзакцията и принудителната защита на ниво ред, както и в клиента за диспечеризация. След това контролна точка изброява всеки маршрут и оператор и всеки импорт и проваля компилирането, когато някой от тях достигне таблица с ограничен обхват, модел или изчислителен двигател, без да премине през тези механизми. Цената на този дизайн е, че първата ви приставка се усеща ограничена. Възвръщаемостта е, че хилядната приставка е изолирана, без авторът ѝ да знае, че функцията съществува, защото няма друг път до данните, по който тя да поеме.
Има честна граница за всичко това. Контролните точки доказват, че кодът ви преминава през механизмите; те не могат да докажат, че продуктовата ви логика е правилна. Маршрут, който правилно ограничава по обхват заявка до редовете на собственика, все още може да покаже грешните редове на правилния собственик. Комплектът за тестване на изолацията в глава 2.22, Средата за изпълнение на приставки, атакува всеки маршрут като друга организация и като колега, с премахната всяка преграда подред, и това е тестът, който бих пуснал, преди да се доверя на собствения си прочит на каквото и да е от това.

