Přihlásit seDomluvit prezentaci

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ě

15 min čtení

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_URL se 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_id vrá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-credentials zastaví 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 a oprávnění
Manifest a oprávnění
Manifest a oprávnění porovnává to, co deklaruje nové vydání, s tím posledním. Zde verze 0.4.0 přidává odesílání pošty a jednu externí adresu, takže vydání je pozdrženo se stavem 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.

Kam může aplikace přistupovat
Kam může aplikace přistupovat
Kam může aplikace přistupovat vypisuje každou externí adresu, kterou aplikace deklarovala, a to, zda ji schválil compliance officer. Volání na adresu, kterou nikdo nedeklaroval, je zastaveno a započítáno dříve, než cokoli opustí systém.

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.

  1. Každá trasa /api registruje strážce rozsahu a jediné anonymní trasy jsou přesné cesty deklarované jako auth: public s allowAnonymous: true.
  2. Každá trasa obsluhovaná strážcem rozsahu jmenuje right z registru manifestu a žádná obslužná rutina nenese svou vlastní kontrolu oprávnění.
  3. Žádná obslužná rutina nečte organizaci, osobu ani jednotku z těla požadavku, dotazu nebo hlavičky.
  4. Každý příkaz nad tabulkou s vymezeným rozsahem prochází přes tenantFence uvnitř withScopedTx a nic v repozitáři nevolá set_config.
  5. 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.
  6. 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.
  7. Nic v package.json nekomunikuje s poskytovatelem modelu a v prostředí neleží žádný klíč.
  8. Každá funkce, kterou nesou jen některé licence, jmenuje své licence na oprávnění, které ji chrání.
  9. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test svítí zeleně a npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json také.

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.