Verzija 1.0.0-alpha.1najnovije
Poglavlje 2.19
Pravila koja svako proširenje nasleđuje
Izolacija na tri ose, računarska obrada preko UNO, AI (veštačka inteligencija) preko rutera, ključevi u vlasništvu organizacije i provere licence. Šta svako pravilo znači za Vaš kod i koja kapija ga sprovodi, i zašto ga nasleđujete umesto da ga pišete.
Ovu stranicu je sa engleskog originala prevela AI tehnologija. Ako nešto nije jasno, merodavna je stranica na engleskom. Pročitajte ovu stranicu na engleskom

Prvo odbijanje koje je moj dodatak za pregled anomalija ikada poslao bilo je upućeno meni. Napisao sam testnog klijenta koji je slao novi pregled sa id-jem organizacije u telu zahteva, iz navike sa druge platforme, a dodatak je odgovorio pre nego što se moj rukovalac uopšte pokrenuo:
{
"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."]
}Tu proveru nisam napisao. Došla je sa čuvarom opsega koji šablon SDK-a (kompleta za razvoj softvera) ugrađuje u svaku /api rutu, i aktivira se čak i kada je id u telu zahteva id samog pozivaoca. To je obrazac za celo ovo poglavlje: mali broj pravila, od kojih svako sprovodi mehanizam koji nasleđujete i svako ima kontrolnu tačku koja obara vaš build ako vaš kod pokuša da ga zaobiđe. Na platformi Nexus vaš dodatak nasleđuje izolaciju od platforme, a kontrolne tačke je proveravaju.
Postoji pet pravila, a odeljci u nastavku obrađuju ih redom: izolacija po tri ose; izračunavanje koje se izvršava isključivo putem UNO dispatch-a; AI (veštačka inteligencija) koja prolazi isključivo kroz AI Provider Router; ključevi modela koji pripadaju organizaciji; i licencirane funkcije koje se proveravaju u odnosu na licencu. Svaki manifest takođe ponavlja tri od njih u jednom bloku rečenica.
Pravilo 1: izolacija na tri ose, na osnovu autentifikovanog zahteva
Svako čitanje i pisanje u proširenju ograničeno je po tri ose, kao i svaki poziv alata i svako pokretanje veštine.
| Osa | Kolona | Odgovara na pitanje | Koliko je granica stroga |
|---|---|---|---|
| Tenant | organization_id |
Koja organizacija | Čvrsta granica, koja se prelazi samo putem evidentiranog odobrenja samo za čitanje |
| Vlasnik | owner_user_id |
Koja osoba unutar organizacije | Privatno čak i unutar jedne organizacije, za sve što je lično |
| Jedinica | business_unit_id |
Koji deo organizacije | Opciona ograda unutar zakupca |
Osa vlasnika je ona koju pridošlice pogrešno shvate. Poštansko sanduče je lično, kao i sačuvani prikaz ili graf izveden iz podataka jedne osobe. Dva člana iste organizacije, u istoj jedinici i sa istom ulogom, ne vide jedan drugome redove ograničene na vlasnika. Kod artefakta organizacije, na primer odobrenja ili zapisa o predmetu, vlasnik umesto toga označava poreklo: beleži ko je izvršio radnju, a čitanja su ograničena na zakupca kako bi revizijski trag ostao vidljiv ljudima kojima je potreban. Vi za svaku tabelu odlučujete o kojoj se vrsti radi, a sloj repozitorijuma to kodira, nikada kao poseban slučaj u ruti.
Ose potiču iz autentifikovanog zahteva i ni odakle drugde. Ne može ih obezbediti promenljiva okruženja, kao ni parametar upita, segment putanje, zaglavlje klijenta ili konstanta builda. SDK otežava pisanje pogrešnog koda: resolveScope(identity, options) uopšte nema parametar organizacije. Organizacija se nalazi unutar identity, a njega proizvodi samo verifikovan token. Ne postoji ništa kroz šta bi se mogao proslediti id.
Zato se telo zahteva koje imenuje zakupca odbija, a ne ignoriše. Čuvar odbija bilo koje od pet imena polja: orgId, organizationId, organization_id, tenant i tenantId. Polje koje se tiho ignoriše uči pozivaoca da polje funkcioniše. Prvi pozivalac ga testira i vidi sopstvene podatke; drugi šalje id druge organizacije. Odbijanje već pri prvom zahtevu imenuje ugovor pre nego što bilo ko počne da gradi na pogrešnom. Isto pravilo važi i za inputParams pri pokretanju: ulaz veštine koji nosi id organizacije odbija se pri pokretanju.
Osa jedinice je ili deklarisana i sprovedena, ili se ne koristi. Ruta koja deklariše needsUnit: true odbija zahtev kada akreditiv ne razreši jedinicu, pri čemu je unit naveden u missing[]. Ne sintetišite jedinicu iz poddomena ili zaglavlja i ne postavljajte podrazumevanu. Izmišljena jedinica ograđuje drugačije od stvarnih jedinica organizacije i spaja redove koje ne bi trebalo.
Površina koja ne može da izrazi predikat odbija zahtev
Ako ruta ne može da kaže kom zakupcu i vlasniku red pripada, i kojoj jedinici kada je ona potrebna, ona odbija zahtev. Ne postoji čitanje na nivou cele organizacije kao rezervna opcija niti vrednost čuvara mesta. Čuvar mesta je najgora opcija, jer je čuvar mesta vrednost, a vrednosti se poklapaju sa redovima: ruter alata koji je i zakupca i korisnika podrazumevano postavljao na string 'unknown' isporučivao je podatke cele organizacije svakome ko ga pozove. Na granici zakupca, ?? 'unknown' je defekt.
Odbijanje ima isti oblik svuda na platformi i nosi dovoljno informacija da klijent prikaže rešenje:
{
"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 uvek true. code potiče iz kataloga kodova platforme. resolved[] navodi ose koje su izvedene, a missing[] one koje su ruti bile potrebne i koje nije mogla da dobije. troubleshooting[] kaže šta bi zaista rešilo problem. Golo „zabranjeno“ nikoga ničemu ne uči.
Držite 401 i 403 odvojeno, jer klijenti na njih reaguju različito.
| Status | Značenje | Šta klijent radi |
|---|---|---|
| 401 | Nije autentifikovan | Ponovo se prijavljuje |
| 403 | Autentifikovan, ali zahtev ne može da se ograniči opsegom ili pozivalac nema odgovarajuće pravo | Prestaje sa ponovnim pokušajima i menja zahtev |
Odbijanje zbog opsega na koje se odgovori sa 401 šalje klijenta u petlju prijavljivanja koju nijedna prijava ne može da okonča: odbacuje sesiju i ponovo se prijavljuje, pokušava ponovo i ponovo dobija 401, dok osoba beskonačno gleda indikator učitavanja.
Još dva mehanizma čine odbijanje potpunim. Unutar rukovaoca, scopeOf(req) je jedini način da se pročita opseg, i on baca izuzetak ako čuvar nije pokrenut. Takođe, čuvar se pokreće nakon parsiranja tela zahteva, a pre bilo kog rukovaoca; rukovalac koji postane dostupan bez predikata namerno odgovara sa 500 i MIDDLEWARE_ORDERING_ERROR, kako bi to završilo u vašem budžetu grešaka umesto u izveštaju o incidentu.
Baza podataka sama drži istu liniju odbrane
Ograda u kodu i ograda u bazi podataka su dva mehanizma za jedan zakon, i dobijate oba.
Svaka naredba nad tabelom ograničenom opsegom sastavlja tenantFence(scope) iz SDK-a; predikat nikada ne pišete ručno. Svaka naredba se takođe izvršava unutar withScopedTx, koji vezuje tri ose za tu jednu transakciju putem jedne funkcije baze podataka i odbija drugo vezivanje (SCOPE_ALREADY_BOUND). Ispod toga, svaka tabela u vašoj šemi ima prinudno uključenu bezbednost na nivou reda, a uloga kojom se povezuje putanja vašeg zahteva ne može sama da promeni vezanog zakupca. Proces koji se povezuje ulogom sposobnom da zaobiđe bezbednost na nivou reda odbija da se pokrene uz DB_ROLE_BYPASSES_ISOLATION. Poglavlje 2.22, Izvršno okruženje dodataka, prikazuje kod; poglavlje 2.21, Plugin SDK, prikazuje kako se uloge generišu za vas.
Jedini prelaz: zabeleženo odobrenje
Postoji tačno jedan način da se pređe granica zakupca. Organizacija koja drži redove evidentira odobrenje koje navodi koja organizacija sme da čita koje tabele, po kom sporazumu i koliko dugo. Baza podataka čini čitanje isključivo čitanjem, a svaki uvid se beleži pre čitanja, u obe organizacije, samo po id-ju. Pisanja nikada ne prelaze granicu; posao predat drugoj firmi putuje kao poruka. Uloge vlasnika i administratora nikada ne čitaju preko granice, a manifest se odbija ako ih pravo koje dozvoljava čitanje između organizacija ne isključuje. Dodatak koji želi drugi način prelaska ne dobija ga.
Pravilo 2: svi proračuni se izvršavaju kroz UNO raspoređivanje
UNO, mehanizam za tokove rada, jedina je putanja za izračunavanje. Vaš kod nikada direktno ne poziva provajdera modela ili mehanizam, a ni red čekanja ili host tokova rada. Šaljete jednu kovertu na krajnju tačku za pokretanje i dobijate 202 sa identifikatorima nazad; rezultat stiže prozivanjem ili povratnim pozivom.
Iz toga slede tri navike, a šablon već ima sve tri.
- Jedna datoteka je vlasnik URL-a za pokretanje.
UNO_DISPATCH_URLse čita jednom u učitavaču konfiguracije i mora biti adresa unutar klastera. Javna adresa se odbija pri pokretanju, jer ništa ne napušta instalaciju. - Jedna zatvorena lista dozvoljenih stavki za ono što ova površina sme da pokreće. Backend koji će pokrenuti bilo koji id veštine koji mu pregledač preda predstavlja proksi opšte namene za svaku veštinu u registru, uključujući veštine drugih dodataka i veštine koje troše tuđi budžet za modele. Lista je konstanta na nivou modula sa tipovima poslova u imenskim prostorima, nikada promenljiva okruženja. Id koji nije na njoj odbija se uz
SKILL_NOT_ALLOWED. - Ponovo proverite ono što se vraća. Kada pročitate posao nazad, klijent SDK-a upoređuje
organization_idvraćenog reda sa zakupcem pozivaoca na vašoj strani mrežnog poziva. Ograda koja postoji samo na drugoj strani poziva samo je konvencija.
Pravilo 3: sav AI saobraćaj ide kroz ruter AI provajdera
Dodatak nigde ne upućuje poziv modelu. Nema SDK-a provajdera u package.json, nema ključa modela u okruženju i nema posrednika. Samo ruter drži akreditiv provajdera organizacije i donosi konačnu odluku o provajderu i modelu.
Ono što dodatak sme da uradi jeste da izrazi želje, u trenutku registracije, u redu registra veštine iz manifesta:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}Ruter poštuje želju samo kada organizacija ima taj provajder omogućen i sa akreditivima. U suprotnom vrši zamenu, iz sopstvenog skupa organizacije. capabilityProfile nikada ne bira; on filtrira, a njegovo polje dataResidency je strogo jurisdikciono ograničenje koje ruter ili zadovoljava ili odbija. Izostavljanje svega ovoga ispravna je podrazumevana opcija za većinu veština: tada odlučuju sopstvene dodele uloga organizacije, a organizacija je ta koja plaća.
Vraćaju se dve vrste odbijanja, i one znače veoma različite stvari.
| Kod | Status | Šta znači |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | Vaš kod je pokušao da sam pozove ruter. Stanite: ovo je granica koja namerno odbija, i ponovni pokušaj nije moguć |
MODEL_CAPABILITY_UNAVAILABLE |
422 | Nijedan omogućeni provajder nema model koji zadovoljava profil. Ublažite profil ili neka organizacija omogući odgovarajućeg provajdera |
NO_PROVIDER_FOR_ROLE |
422 | Organizacija nije konfigurisala rutiranje za ovu ulogu. Prikažite osobi tekst rutera o otklanjanju problema |
Drugi par pripada ekranu, a ne logu. Ne postoji podrazumevani model niti rezervni provajder: uloga koju organizacija nije podesila glasno ne uspeva, uz rečenicu koja kaže šta treba konfigurisati.
Jedino čitanje rutera koje dodatak sme da izvrši je effectiveRoute() iz runtime/ai-route. Ono odgovara koji bi provajder i model ruter izabrao za prijavljenu organizaciju bez slanja AI zahteva, a kada modela nema, vraća odbijanje rutera rečima. Poglavlje 2.22, Izvršno okruženje dodataka, to prikazuje.
Lestvica poverenja dodaje još jednu granicu. Samo core i verified dodaci smeju da deklarišu dva nivoa veština u manifestu koji dopiru do rutera, tool_using i llm_only. Svi ostali posreduju determinističan posao i prepuštaju platformi deo koji dopire do modela.
Pravilo 4: ključevi pripadaju organizaciji
Svaka organizacija donosi sopstveni nalog i ključ provajdera i plaća sopstveni račun. Ključ se nalazi u skupu AI provajdera organizacije, kojim iz konzole upravljaju njeni sopstveni administratori, a ruter ga razrešava u trenutku poziva. Iza zakupca ne stoji zajednički ključ platforme, pa nijedna organizacija ne troši budžet druge.
Za proširenje to znači tri stvari.
- Nikada ne držite ključ modela, bilo u kodu, konfiguraciji ili skladištu tajni. Kontrolna tačka
no-credentialsobara build ako je neki ključ čitljiv, a učitavač konfiguracije odbija da se pokrene ako je ključ prisutan. - Nikada ne nabrajate ključeve organizacije. Ako vaš dodatak smatra da mu je to potrebno, zahtev je na pogrešnom mestu.
- Organizacija bez ključa ne dobija AI odgovore. To je očekivano stanje sa stvarnim ekranom. Navedite uloga koja nedostaje i citirajte tekst o otklanjanju problema, a zatim uputite osobu na podešavanja njenog provajdera. Ne prikazujte to kao prazan rezultat.
Pravilo 5: licencirane funkcionalnosti se proveravaju u odnosu na licencu
Ono što instalacija sme da koristi izvan Community osnove potiče sa jednog mesta: iz licencnog dokumenta koji potpisuje Adverant, a koji se na instalaciji verifikuje isključivo javnim ključevima. Vaše proširenje nikada ne odlučuje na osnovu nečeg slabijeg, kao što je naziv plana u tokenu ili oznaka u konfiguraciji.
U dodatku, najjednostavniji način da se funkcija veže za licencu jeste preko prava koje je štiti. Pravo u registru rights manifesta može da navede funkciju licence:
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}Svako ko pozove rutu zaštićenu tim pravom odbija se uz LICENCE_LOCKED (403), bez obzira na uloge i mesta koja ima, kada licenca organizacije ne sadrži compliance-packs. Odbijanje navodi funkciju i ono što je sadrži, i kaže ko može da je uključi.
Važno je i stanje licence. Dok je licenca važeća ili u periodu upozorenja, licencirane funkcije rade, nastavljaju da rade i u periodu odlaganja, a period odlaganja prikazuje obaveštenje LICENCE_IN_GRACE. Kada licenca pređe period odlaganja, ona ograničava: posao u toku i čitanja se nastavljaju, kao i izvozi i bezbednosna ažuriranja, ali se kreiranje nečeg novog u okviru licencirane funkcije odbija uz LICENCE_LOCKED. Gradite svoje putanje za kreiranje očekujući taj odgovor.
Kada vaš dodatak pita proveru prava da li organizacija poseduje funkciju, dobija presudu, nikada golu bulovu vrednost. „Nedostupno“ i „dostupno i ne“ su različite činjenice sa različitim kodovima: ENTITLEMENT_UNREACHABLE (502) i ENTITLEMENT_DENIED (403). Kratkotrajni prekid dostupnosti nikada ne sme tiho da spusti svakog korisnika na besplatnu osnovu.
MANIFEST_SCOPE_WIDENED dok se dva recenzenta i službenik za usklađenost ne slože.Manifest ponovo potvrđuje zakon
Svaki v2 manifest sadrži blok architecture sa tri obavezne rečenice, a validator fiksira njihovu formulaciju. U dodatku koji pravite za sopstvenu instalaciju one glase:
"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."
}Te rečenice se proveravaju. Dodatak čiji je manifest prihvatio pravila dok je njegov kod pozivao dobavljača modela lagao bi u sopstvenom ugovoru, a kontrole postoje upravo da bi takva laž mogla da se otkrije.
Kontrolne kapije (gates) koje sprovode svako pravilo
SDK isporučuje dvadeset dve kontrole usklađenosti kao jednu komandu, nexus-gates. Poglavlje 2.21, Plugin SDK, opisuje svaku od njih. Ovde su grupisane prema pravilu koje sprovode.
| Pravilo | Kontrole | Šta obara build |
|---|---|---|
| Izolacija u sloju ruta | scope-adherence, one-fence, rights-register, crud-adherence |
Ruta /api bez zaštite opsega, drugi ručno napisan predikat zakupca, ruta opsega bez prava, ruta koja menja podatke a čije pravo ne imenuje ništa |
| Izolacija u SQL-u | sql-fence, no-set-config |
Naredba nad tabelom sa opsegom bez ograde; kod dodatka koji sam postavlja podešavanje zakupca |
| Izolacija u bazi podataka | migrations-are-scoped, rls-present, db-role-honest |
Tabela kojoj nedostaje osa ili ključ koji počinje zakupcem, tabela bez prinudne bezbednosti na nivou redova, putanja zahteva koja se povezuje kao vlasnik ili superkorisnik |
| Jedini prelaz | grants-declared |
Tabela kojoj su u migracijama dodeljena prava, a koju manifest ne deklariše, ili nalog za čitanje kome su privilegije dodeljene ručno |
| Računanje preko UNO | no-direct-compute |
Direktan poziv dobavljaču modela ili mašini, ili hostu reda ili toka rada; drugi čitalac URL-a za otpremu |
| AI i ključevi | no-credentials |
Akreditiv dobavljača modela čitljiv u repozitorijumu ili okruženju |
| Deklarisani ugovor | api-contract, platform-clients, declared-input |
Ruta registrovana, a nije deklarisana, ili deklarisana, a nije registrovana; klijent platforme uvezen, a nije imenovan |
Svaka kontrola ima samotest koji dokazuje da ona pada na test-primeru napravljenom da je okine. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test ih pokreće sve, a kontrola koja je prestala da pada na sopstvenom test-primeru prestala je da radi.
Pre nego što zatražite pregled
Ovo je lista koju prolazim pre nego što zamolim kolegu da pregleda dodatak. Svaku stavku mi je recenzent u Corrán Orbital vratio bar jednom.
- Svaka ruta
/apiregistruje zaštitu opsega, a jedine anonimne rute su tačne putanje deklarisaneauth: publicsaallowAnonymous: true. - Svaka ruta koju opslužuje zaštita opsega imenuje
rightiz registra manifesta, i nijedan rukovalac nema sopstvenu proveru prava. - Nijedan rukovalac ne čita organizaciju, osobu ili jedinicu iz tela zahteva, upita ili zaglavlja.
- Svaka naredba nad tabelom sa opsegom prolazi kroz
tenantFenceunutarwithScopedTx, i ništa u repozitorijumu ne pozivaset_config. - Svaka tabela ima tri kolone osa, primarni ključ koji počinje sa
organization_idi složene strane ključeve koji nose zakupca. - URL za otpremu čita se u jednoj datoteci, a lista dozvoljenih za otpremu je konstanta tipova poslova sa imenskim prostorom.
- Ništa u
package.jsonne komunicira sa dobavljačem modela, i nijedan ključ se ne nalazi u okruženju. - Svaka funkcija koju nose samo neke licence imenuje svoj
licencena pravu koje je štiti. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testje zelen, kao inpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.
Ako je svih devet ispunjeno, pregled se odnosi na Vaš proizvod, a tu i treba da ide vreme recenzenta.
Zašto platforma sprovodi ova pravila
Svako gore navedeno pravilo nekada je negde bilo konvencija, i svaka konvencija je zakazala na isti način: rute koje su je se setile bile su u redu, a ona koja ju je zaboravila postala je incident. Ograda poslovne jedinice primenjena kao opcioni middleware zaobiđena je na šest nezavisnih načina, svaki put rutom koja se nikada nije uključila. Promenljiva okruženja koja je prepisivala identitet zakupca isporučila je jednoj organizaciji 1.406 kontakata druge, i na pregledu je izgledala ispravno jer je bila ispravna za pod za koji je napisana.
Zato platforma postavlja predikat tamo kuda svaka površina već prolazi: u zaštitu opsega i funkciju ograde, u omotač transakcije i prinudnu bezbednost na nivou redova, i u klijent za otpremu. Kontrola zatim nabraja svaku rutu, naredbu i svaki uvoz, i obara build kada neki od njih dosegne tabelu sa opsegom, model ili računsku mašinu bez prolaska kroz te mehanizme. Cena takvog dizajna je da Vaš prvi dodatak deluje ograničeno. Dobit je to što je hiljaditi dodatak izolovan, a da njegov autor i ne zna da ta funkcija postoji, jer ne postoji drugi put do podataka kojim bi mogao da krene.
Sve ovo ima iskreno ograničenje. Kontrole dokazuju da Vaš kod prolazi kroz mehanizme; ne mogu da dokažu da je logika Vašeg proizvoda ispravna. Ruta koja ispravno ograničava upit na redove vlasnika i dalje može pravom vlasniku prikazati pogrešne redove. Komplet za testiranje izolacije u poglavlju 2.22, Okruženje za izvršavanje dodataka, napada svaku rutu kao druga organizacija i kao kolega, uklanjajući redom svaku ogradu, i to je test koji bih pokrenuo pre nego što bih poverovao sopstvenom tumačenju bilo čega od ovoga.

