Verze 1.0.0-alpha.1nejnovější
Kapitola 2.19
Pravidla, která dědí každé rozšíření
Izolace ve třech osách, výpočty přes UNO, AI (umělá inteligence) přes směrovač, klíče vlastněné organizací a kontroly licencí. Co jednotlivá pravidla znamenají pro váš kód, která brána je vynucuje a proč je dědíte, místo abyste je sami psali.
Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

První odmítnutí, které můj plugin pro kontrolu anomálií kdy odeslal, patřilo mně. Napsal jsem testovacího klienta, který ze zvyku z jiné platformy odeslal novou kontrolu s identifikátorem organizace v těle požadavku, a plugin odpověděl ještě před spuštěním mé obslužné rutiny:
{
"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."]
}Tuto kontrolu jsem nenapsal. Byla součástí strážce rozsahu (scope guard), kterého šablona SDK (software development kit) napojuje do každé trasy /api, a spustí se i tehdy, když je identifikátor v těle požadavku vlastní identifikátor volajícího. To je vzorec pro celou tuto kapitolu: malý počet pravidel, z nichž každé je vynucováno mechanismem, který zdědíte, a každé má bránu (gate), která zastaví vaše sestavení (build), pokud ji váš kód obejde. Na platformě Nexus váš plugin dědí svou izolaci od platformy a brány ji auditují.
Existuje pět pravidel a následující části je postupně rozebírají: izolace na třech osách; výpočty, které běží výhradně přes dispečink UNO; AI (umělá inteligence), která prochází výhradně přes AI Provider Router; klíče modelů, které patří organizaci; a licencované funkce kontrolované oproti licenci. Každý manifest také tři z nich znovu uvádí v jednom bloku vět.
Pravidlo 1: izolace ve třech osách, od ověřeného požadavku
Každé čtení a zápis v rozšíření má vymezený rozsah na třech osách, a totéž platí pro každé volání nástroje a odeslání dovednosti (skill dispatch).
| Osa | Sloupec | Odpovídá na otázku | Jak pevná je hranice |
|---|---|---|---|
| Tenant | organization_id |
Která organizace | Pevná hranice, kterou lze překročit pouze prostřednictvím zaznamenaného oprávnění pouze pro čtení |
| Vlastník | owner_user_id |
Která osoba v rámci organizace | Soukromé i uvnitř jedné organizace, pro cokoli osobního |
| Jednotka | business_unit_id |
Která část organizace | Volitelná ohrada uvnitř tenanta |
Osa vlastníka (owner) je ta, ve které nováčci chybují. Poštovní schránka je osobní, stejně jako uložené zobrazení nebo graf odvozený z dat jedné osoby. Dva členové téže organizace, ve stejné jednotce a se stejnou rolí, nevidí navzájem své řádky vymezené rozsahem vlastníka. U artefaktu organizace, například schválení nebo záznamu případu, však vlastník vyjadřuje původ: zaznamenává, kdo jednal, a čtení jsou vymezena rozsahem tenanta, aby auditní stopa zůstala viditelná pro lidi, kteří ji potřebují. O tom, o který druh jde, rozhodujete pro každou tabulku zvlášť a kóduje to vrstva repozitáře, nikdy ne speciální případ v trase (route).
Osy pocházejí z ověřeného požadavku a odnikud jinud. Nemůže je dodat proměnná prostředí, ani parametr dotazu, segment cesty, hlavička klienta či konstanta sestavení. SDK ztěžuje napsání špatného postupu: resolveScope(identity, options) nemá vůbec žádný parametr organizace. Organizace je uvnitř identity a vytvoří ji pouze ověřený token. Není zde nic, kudy by šlo předat identifikátor.
Proto je tělo požadavku uvádějící tenanta odmítnuto, nikoli ignorováno. Strážce odmítne kterýkoli z pěti názvů polí: orgId, organizationId, organization_id, tenant a tenantId. Tiše ignorované pole učí volajícího, že dané pole funguje. První volající ho otestuje a uvidí svá vlastní data; druhý pošle identifikátor jiné organizace. Odmítnutí hned při prvním požadavku jasně vymezí kontrakt dříve, než někdo začne stavět na tom špatném. Stejné pravidlo platí pro inputParams odeslání (dispatch): vstup dovednosti, který nese identifikátor organizace, je při odeslání odmítnut.
Osa jednotky (unit) je buď deklarována a vynucována, nebo se nepoužívá. Trasa, která deklaruje needsUnit: true, požadavek odmítne, pokud přihlašovací údaj neurčí jednotku, přičemž unit bude uvedeno v missing[]. Nesyntetizujte jednotku ze subdomény ani z hlavičky a nenastavujte výchozí hodnotu. Vymyšlená jednotka ohrazuje data jinak než skutečné jednotky organizace a spojuje řádky, které by spojovat neměla.
Rozhraní, které nedokáže vyjádřit predikát, požadavek zamítne
Pokud trasa nedokáže určit, kterému tenantovi a vlastníkovi řádek patří, a které jednotce, pokud ji potřebuje, požadavek odmítne. Neexistuje žádné nouzové čtení v rámci celé organizace ani žádná zástupná hodnota. Zástupná hodnota je tou nejhorší možností, protože zástupná hodnota je hodnota a hodnoty se shodují s řádky: směrovač nástrojů, který pro tenanta i uživatele nastavil jako výchozí hodnotu řetězec 'unknown', vydával celoorganizační data komukoli, kdo jej zavolal. Na hranici tenanta je ?? 'unknown' vadou.
Odmítnutí má všude na platformě stejný tvar a nese dostatek informací, aby klient mohl vykreslit nápravu:
{
"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 je vždy true. code pochází z katalogu kódů platformy. resolved[] uvádí osy, které byly odvozeny, a missing[] ty, které trasa potřebovala a nemohla získat. troubleshooting[] říká, co by to skutečně opravilo. Holé „forbidden“ (zakázáno) nikoho nic nenaučí.
Rozlišujte stavy 401 a 403, protože klienti na ně reagují odlišně.
| Stav | Význam | Co udělá klient |
|---|---|---|
| 401 | Neověřený | Znovu se přihlásí |
| 403 | Ověřený, ale požadavku nelze vymezit rozsah, nebo volajícímu chybí oprávnění | Přestane opakovat pokusy a změní požadavek |
Odmítnutí rozsahu zodpovězené jako 401 pošle klienta do přihlašovací smyčky, kterou žádné přihlášení nemůže ukončit: zahodí relaci a znovu se přihlásí, zopakuje pokus a znovu dostane 401, zatímco uživatel donekonečna sleduje ikonu načítání.
Dva další mechanismy činí odmítnutí úplným. Uvnitř obslužné rutiny je scopeOf(req) jediným způsobem, jak přečíst rozsah, a pokud strážce neproběhl, vyhodí výjimku. A strážce běží po zpracování těla požadavku a před jakoukoli obslužnou rutinou; obslužná rutina, která se stane dosažitelnou bez predikátu, odpoví stavem 500 s MIDDLEWARE_ORDERING_ERROR – a to záměrně, aby to skončilo ve vašem rozpočtu chyb (error budget) namísto v hlášení o incidentu.
Databáze sama udržuje stejnou hranici
Ohrada v kódu a ohrada v databázi jsou dva mechanismy pro jeden zákon a vy dostanete oba.
Každý příkaz vůči tabulce s vymezeným rozsahem skládá tenantFence(scope) z SDK; predikát nikdy nepíšete ručně. Každý příkaz také běží uvnitř withScopedTx, což naváže tři osy pro danou jednu transakci prostřednictvím jediné databázové funkce a odmítne druhé navázání (SCOPE_ALREADY_BOUND). Pod povrchem má každá tabulka ve vašem schématu vynucené zabezpečení na úrovni řádků (row-level security) a role, pod kterou se vaše cesta požadavku připojuje, nemůže sama změnit navázaného tenanta. Proces, který se připojí pod rolí schopnou obejít zabezpečení na úrovni řádků, odmítne nastartovat s chybou DB_ROLE_BYPASSES_ISOLATION. Kapitola 2.22, Běhové prostředí pluginu, ukazuje kód; kapitola 2.21, Sada Plugin SDK, ukazuje, jak jsou role pro vás generovány.
Jediný průchod: zaznamenané oprávnění
Přes hranici tenanta vede přesně jedna cesta. Organizace, která vlastní řádky, zaznamená oprávnění (grant) uvádějící, která organizace může číst které tabulky, na základě jaké dohody a jak dlouho. Databáze zajistí, že čtení je pouze pro čtení, a každé nahlédnutí je zapsáno před samotným čtením, v obou organizacích, pouze pomocí identifikátoru. Zápisy hranici nikdy nepřekračují; práce předaná jiné firmě putuje jako zpráva. Role vlastníka a administrátora nikdy nečtou přes hranici a manifest je odmítnut, pokud oprávnění připouštějící čtení napříč organizacemi tyto role nevylučuje. Plugin, který chce jinou cestu přes hranici, žádnou nedostane.
Pravidlo 2: veškeré výpočty běží přes dispečink UNO
UNO, workflow engine, je jedinou výpočetní cestou. Váš kód nikdy přímo nevolá poskytovatele modelu ani engine, a nikdy ani frontu nebo hostitele workflow. Odešlete jednu obálku na koncový bod dispečinku a zpět dostanete 202 s identifikátory; výsledek dorazí pomocí dotazování (polling) nebo zpětného volání (callback).
Z toho plynou tři návyky a šablona již obsahuje všechny tři.
- URL adresu dispečinku vlastní jeden soubor.
UNO_DISPATCH_URLse načte jednou v zavaděči konfigurace a musí jít o adresu uvnitř clusteru. Veřejná adresa je při startu odmítnuta, protože instalaci nic neopouští. - Jeden uzavřený seznam povolených položek (allow-list) toho, co toto rozhraní může odesílat. Backend, který odešle jakýkoli identifikátor dovednosti předaný prohlížečem, je univerzální proxy pro každou dovednost v registru, včetně dovedností jiných pluginů a dovedností, které čerpají rozpočet na modely někoho jiného. Seznam je konstanta na úrovni modulu obsahující typy úloh se jmennými prostory, nikdy ne proměnná prostředí. Identifikátor, který na seznamu není, je odmítnut s
SKILL_NOT_ALLOWED. - Znovu zkontrolujte, co se vrátí. Když načítáte úlohu zpět, klient SDK porovná
organization_idvráceného řádku s tenantem volajícího na vaší straně síťového volání. Ohrada, která existuje pouze na druhé straně volání, je jen konvencí.
Pravidlo 3: veškerá AI prochází přes směrovač poskytovatelů AI
Plugin nikde neprovádí žádné volání modelu. V package.json není žádné SDK poskytovatele, v prostředí není žádný klíč modelu a neexistuje žádné přeposílání (relay). Přihlašovací údaje k poskytovateli organizace drží výhradně směrovač (router) a ten také činí konečné rozhodnutí o poskytovateli a modelu.
Co plugin udělat může, je vyjádřit přání v době registrace na řádku registru dovednosti manifestu:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}Směrovač vyhoví přání pouze tehdy, když má organizace daného poskytovatele povoleného a opatřeného přihlašovacími údaji. V opačném případě jej nahradí z vlastního fondu organizace. capabilityProfile nikdy nevybírá; pouze filtruje a jeho pole dataResidency je tvrdým jurisdikčním omezením, kterému směrovač buď vyhoví, nebo požadavek odmítne. Vynechání všech těchto položek je správným výchozím nastavením pro většinu dovedností: rozhodují pak vlastní přiřazení rolí organizace, protože právě organizace je tím, kdo platí.
Vracejí se dva druhy odmítnutí a znamenají velmi odlišné věci.
| Kód | Stav | Co to znamená |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | Váš kód se pokusil zavolat samotný směrovač. Zastavte: toto rozhraní odmítá záměrně a pokus nelze opakovat |
MODEL_CAPABILITY_UNAVAILABLE |
422 | Žádný povolený poskytovatel nemá model, který by vyhovoval profilu. Uvolněte profil, nebo organizace povolí schopného poskytovatele |
NO_PROVIDER_FOR_ROLE |
422 | Organizace pro tuto roli nenakonfigurovala směrování. Zobrazte uživateli text nápravy ze směrovače |
Druhá dvojice patří na obrazovku, nikoli do protokolu (logu). Neexistuje žádný výchozí model ani záložní poskytovatel: role, kterou organizace nenastavila, hlasitě selže s větou říkající, co je třeba nakonfigurovat.
Jediné čtení, které může plugin ze směrovače provést, je effectiveRoute() z runtime/ai-route. Odpovídá na to, kterého poskytovatele a model by směrovač vybral pro přihlášenou organizaci bez odeslání požadavku na AI, a pokud žádný model neexistuje, vrátí odmítnutí směrovače vyjádřené slovy. Ukazuje to kapitola 2.22, Běhové prostředí pluginu.
Žebříček důvěryhodnosti přidává ještě jednu hranici. Pouze pluginy core a verified mohou deklarovat dvě úrovně dovedností manifestu, které dosáhnou na směrovač, tool_using a llm_only. Všichni ostatní zprostředkovávají deterministickou práci a část sahající na modely přenechávají platformě.
Pravidlo 4: klíče patří organizaci
Každá organizace si přináší svůj vlastní účet a klíč poskytovatele a platí svůj vlastní účet. Klíč žije ve fondu poskytovatelů AI dané organizace, který spravují její vlastní administrátoři z konzole, a směrovač jej vyhodnocuje v okamžiku volání. Za tenantem neexistuje žádný sdílený klíč platformy, takže žádná organizace nečerpá rozpočet jiné organizace.
Pro rozšíření to znamená tři věci.
- Nikdy nedržíte klíč modelu, ať už v kódu, konfiguraci nebo v úložišti tajemství (secret store). Brána
no-credentialszastaví sestavení, pokud je nějaký klíč čitelný, a zavaděč konfigurace odmítne nastartovat, pokud je nějaký přítomen. - Nikdy nevypisujete klíče organizace. Pokud si váš plugin myslí, že to potřebuje, je tento požadavek na špatném místě.
- Organizace bez klíče nedostane žádné odpovědi od AI. To je očekávaný stav se skutečnou obrazovkou. Uveďte chybějící roli, ocitujte nápravu a poté uživatele nasměrujte do nastavení poskytovatele. Nevykreslujte to jako prázdný výsledek.
Pravidlo 5: licencované funkce se kontrolují oproti licenci
To, co může instalace využívat nad rámec základního tarifu Community, pochází z jednoho místa: z licenčního dokumentu podepsaného společností Adverant, který je na instalaci ověřen výhradně pomocí veřejných klíčů. Vaše rozšíření se nikdy nerozhoduje na základě něčeho slabšího, jako je název tarifu v tokenu nebo příznak v konfiguraci.
Nejjednodušším způsobem, jak v pluginu navázat funkci na licenci, je přes oprávnění, které ji chrání. Oprávnění v registru rights manifestu může jmenovat funkci licence:
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}Kdokoli zavolá trasu chráněnou tímto oprávněním, je odmítnut s LICENCE_LOCKED (403) bez ohledu na to, jaké role a místa (seats) drží, pokud licence organizace neobsahuje compliance-packs. Odmítnutí jmenuje funkci i to, co ji obsahuje, a uvádí, kdo ji může zapnout.
Záleží také na stavu licence. Dokud je licence platná nebo v okně varování, licencované funkce fungují, a fungují i nadále v ochranné lhůtě (grace period), přičemž ochranná lhůta zobrazuje upozornění LICENCE_IN_GRACE. Jakmile licence překročí ochrannou lhůtu, přejde do omezeného režimu: běžící práce a čtení pokračují, stejně jako exporty a bezpečnostní aktualizace, ale vytvoření něčeho nového pod licencovanou funkcí je odmítnuto s LICENCE_LOCKED. Své cesty pro vytváření stavte s očekáváním této odpovědi.
Když se váš plugin dotáže kontroly nároků (entitlement check), zda organizace drží určitou funkci, dostane verdikt, nikdy ne holou booleovskou hodnotu. „Nedosažitelné“ a „dosažitelné a ne“ jsou odlišná fakta s odlišnými kódy: ENTITLEMENT_UNREACHABLE (502) a ENTITLEMENT_DENIED (403). Chvilkový výpadek dosažitelnosti nesmí nikdy tiše ponížit každého zákazníka na bezplatný základ.
MANIFEST_SCOPE_WIDENED, dokud to neschválí dva revizoři a compliance officer.Manifest znovu potvrzuje pravidla
Každý manifest v2 nese blok architecture se třemi povinnými větami a validátor vyžaduje jejich přesné znění. V pluginu, který stavíte pro svou vlastní instalaci, znějí takto:
"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."
}Tyto věty se kontrolují. Plugin, jehož manifest by souhlasil se zákony, zatímco jeho kód by volal poskytovatele modelu, by lhal ve svém vlastním kontraktu, a brány existují proto, aby tuto lež dokázaly odhalit.
Brány, které vynucují jednotlivá pravidla
SDK dodává dvacet dva bran dodržování pravidel (adherence gates) jako jeden příkaz, nexus-gates. Kapitola 2.21, Sada Plugin SDK, popisuje každou z nich. Zde jsou seskupeny podle pravidla, které prosazují.
| Pravidlo | Brány | Co zastaví sestavení |
|---|---|---|
| Izolace ve vrstvě tras | scope-adherence, one-fence, rights-register, crud-adherence |
Trasa /api bez strážce rozsahu, druhý ručně napsaný predikát tenanta, trasa s rozsahem bez oprávnění, mutující trasa, jejíž oprávnění nic nejmenuje |
| Izolace v SQL | sql-fence, no-set-config |
Příkaz nad tabulkou s vymezeným rozsahem bez ohrady; kód pluginu, který sám váže nastavení tenanta |
| Izolace v databázi | migrations-are-scoped, rls-present, db-role-honest |
Tabulka postrádající osu nebo klíč začínající tenantem, tabulka bez vynuceného zabezpečení na úrovni řádků, cesta požadavku připojující se jako vlastník nebo superuživatel |
| Jediné překročení hranice | grants-declared |
Tabulka s uděleným přístupem v migracích, kterou manifest nedeklaruje, nebo místo pro čtení (read seat), kterému byla privilegia předána ručně |
| Výpočty přes UNO | no-direct-compute |
Přímé volání poskytovatele modelu nebo enginu, případně fronty nebo hostitele workflow; druhé čtení URL adresy dispečinku |
| AI a klíče | no-credentials |
Přihlašovací údaj k poskytovateli modelu čitelný v repozitáři nebo v prostředí |
| Deklarovaný kontrakt | api-contract, platform-clients, declared-input |
Trasa zaregistrovaná, ale nedeklarovaná, nebo deklarovaná, ale nezaregistrovaná; klient platformy naimportovaný, ale neuvedený |
Každá brána má autotest, který prokazuje, že selže na testovacím přípravku (fixture) sestaveném tak, aby ji spustil. Příkaz npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test je spustí všechny a brána, která přestala selhávat na svém vlastním přípravku, přestala fungovat.
Než požádáte o revizi
Toto je seznam, který procházím, než požádám kolegu o revizi pluginu. Každý řádek představuje něco, co mi revizor ve společnosti Corrán Orbital alespoň jednou vrátil.
- Každá trasa
/apiregistruje strážce rozsahu a jediné anonymní trasy jsou přesné cesty deklarované jakoauth: publicsallowAnonymous: true. - Každá trasa obsluhovaná strážcem rozsahu jmenuje
rightz registru manifestu a žádná obslužná rutina nenese svou vlastní kontrolu oprávnění. - Žádná obslužná rutina nečte organizaci, osobu ani jednotku z těla požadavku, dotazu nebo hlavičky.
- Každý příkaz nad tabulkou s vymezeným rozsahem prochází přes
tenantFenceuvnitřwithScopedTxa nic v repozitáři nevoláset_config. - Každá tabulka má tři sloupce os, primární klíč, který začíná
organization_id, a složené cizí klíče, které nesou tenanta. - URL adresa dispečinku se čte v jednom souboru a seznam povolených položek dispečinku je konstanta typů úloh se jmennými prostory.
- Nic v
package.jsonnekomunikuje s poskytovatelem modelu a v prostředí neleží žádný klíč. - Každá funkce, kterou nesou jen některé licence, jmenuje své
licencena oprávnění, které ji chrání. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testsvítí zeleně anpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.jsontaké.
Pokud platí všech devět bodů, revize se týká vašeho produktu, což je přesně to, čemu by měl revizor věnovat svůj čas.
Proč platforma tato pravidla vynucuje
Každé z výše uvedených pravidel bylo kdysi někde pouhou konvencí a každá konvence selhala stejným způsobem: trasy, které si ji pamatovaly, byly v pořádku, a ta jedna, která na ni zapomněla, způsobila incident. Ohrada organizační jednotky aplikovaná jako volitelný middleware byla obejita šesti nezávislými způsoby, z nichž každý představoval trasu, která se k ní nikdy nepřihlásila. Proměnná prostředí, která přepisovala identitu tenanta, vydala jedné organizaci 1 406 kontaktů jiné organizace, a při revizi to vypadalo správně, protože to bylo správné pro pod, pro který to bylo napsáno.
Platforma proto umisťuje predikát tam, kudy již prochází každé rozhraní: do strážce rozsahu a funkce ohrady, do obálky transakce a vynuceného zabezpečení na úrovni řádků a do klienta dispečinku. Brána pak vypíše každou trasu, každý příkaz a každý import a zastaví sestavení, když některý z nich přistoupí k tabulce s vymezeným rozsahem, modelu nebo výpočetnímu enginu, aniž by prošel těmito mechanismy. Daní za tento návrh je, že váš první plugin působí svázaně. Odměnou je, že tisící plugin je izolovaný, aniž by jeho autor vůbec tušil, že tato funkce existuje, protože žádná jiná cesta k datům, kterou by se mohl vydat, neexistuje.
To vše má svůj přirozený limit. Brány prokazují, že váš kód prochází danými mechanismy; nedokážou však prokázat, že je správná logika vašeho produktu. Trasa, která správně vymezí rozsah dotazu na řádky vlastníka, může stále ukázat špatné řádky správnému vlastníkovi. Testovací sada izolace v kapitole 2.22, Běhové prostředí pluginu, útočí na každou trasu jako jiná organizace a jako kolega, přičemž postupně odstraňuje každou ohradu, a právě to je test, který bych spustil, než bych uvěřil svému vlastnímu výkladu čehokoli z výše uvedeného.

