Logg innBestill en gjennomgang

Kapittel 2.19

Reglene hver utvidelse arver

Isolasjon på tre akser, beregning gjennom UNO, KI (kunstig intelligens) gjennom ruteren, organisasjonseide nøkler og lisenskontroller. Hva hver regel betyr for koden din og hvilken port som håndhever den, og hvorfor du arver den i stedet for å skrive den.

Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

15 minutter å lese

Den første avvisningen min programtillegg for avviksgjennomgang noensinne sendte, var til meg selv. Jeg hadde skrevet en testklient som sendte inn en ny gjennomgang med organisasjonens ID i forespørselskroppen, av gammel vane fra en annen plattform, og programtillegget svarte før min håndterer rakk å kjøre:

{
  "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."]
}

Jeg hadde ikke skrevet den kontrollen selv. Den fulgte med i omfangsvakten som SDK-malen (programvareutviklingssettet) kobler inn i hver /api-rute, og den løser ut selv når ID-en i kroppen tilhører kalleren selv. Dette er mønsteret for hele dette kapittelet: et lite antall regler, hver håndhevet av en mekanisme du arver, og hver med en portvakt som stopper bygget ditt hvis koden din prøver å omgå den. På Nexus arver programtillegget sin isolasjon fra plattformen, og portvaktene reviderer den.

Det er fem regler, og avsnittene nedenfor tar dem for seg etter tur: isolasjon langs tre akser; beregninger som kun kjører gjennom UNO-utsendelse; KI (kunstig intelligens) som kun går gjennom KI-leverandørruteren; modellnøkler som tilhører organisasjonen; og lisensierte funksjoner som sjekkes mot lisensen. Hvert manifest gjentar også tre av dem i én samlet tekstblokk.

Regel 1: isolasjon på tre akser, fra den autentiserte forespørselen

Hver lese- og skriveoperasjon i en utvidelse er avgrenset langs tre akser, og det samme gjelder hvert verktøykall og hver ferdighetsutsendelse.

Akse Kolonne Svarer på Hvor absolutt grensen er
Leietaker organization_id Hvilken organisasjon En absolutt grense, som kun krysses gjennom en registrert skrivebeskyttet tillatelse
Eier owner_user_id Hvilken person innad i organisasjonen Privat selv innad i én organisasjon, for alt som er personlig
Enhet business_unit_id Hvilken del av organisasjonen Et valgfritt gjerde innad i en leietaker

Eieraksen er den nybegynnere oftest tar feil av. En postkasse er personlig, og det samme er en lagret visning eller en graf utledet fra én persons data. To medlemmer av samme organisasjon, i samme enhet og med samme rolle, ser ikke hverandres eieravgrensede rader. På en organisasjonsartefakt, som en godkjenning eller en saksmappe, representerer eieren i stedet opphav: det registrerer hvem som handlet, og lesing er avgrenset til leietakeren slik at revisjonssporet forblir synlig for dem som trenger det. Du bestemmer per tabell hvilken type det er, og datalagringslaget koder det inn – aldri som et spesialtilfelle i en rute.

Aksene kommer fra den autentiserte forespørselen og ingen andre steder. En miljøvariabel kan ikke levere dem, og det kan heller ikke en spørreparameter, et banesegment, en klientheader eller en byggekonstant. SDK-et gjør det vanskelig å skrive feil: resolveScope(identity, options) har ingen organisasjonsparameter i det hele tatt. Organisasjonen ligger inne i identity, og kun et verifisert token produserer en slik. Det finnes ingenting å sende en ID gjennom.

Det er derfor en forespørselskropp som navngir leietakeren, blir avvist i stedet for ignorert. Vakten avviser ethvert av fem feltnavn: orgId, organizationId, organization_id, tenant og tenantId. Et felt som ignoreres i det stille, lærer kalleren at feltet virker. Den første kalleren tester det og ser sine egne data; den andre sender en annen organisasjons ID. Å avvise ved første forespørsel tydeliggjør kontrakten før noen bygger videre på feil grunnlag. Den samme regelen gjelder for inputParams i en utsendelse: inndata til en ferdighet som inneholder en organisasjons-ID, blir avvist ved utsendelse.

Enhetsaksen er enten deklarert og håndhevet, eller ikke i bruk. En rute som deklarerer needsUnit: true, avviser forespørselen når legitimasjonen ikke kan knyttes til en enhet, med unit navngitt i missing[]. Ikke konstruer en enhet fra et underdomene eller en header, og ikke bruk en standardverdi. En oppdiktet enhet gjerder inn på en annen måte enn organisasjonens faktiske enheter, og den kobler sammen rader den ikke burde.

En flate som ikke kan uttrykke predikatet, avviser

Hvis en rute ikke kan fastslå hvilken leietaker og eier en rad tilhører, og hvilken enhet når det trengs, avviser den forespørselen. Det finnes ingen organisasjonsomfattende lesing som reserveløsning og ingen plassholderverdi. En plassholder er det verste alternativet, fordi en plassholder er en verdi, og verdier gir treff på rader: en verktøyruter som satte både leietaker og bruker til standardstrengen 'unknown', leverte organisasjonsomfattende data til alle som kalte den. På en leietakergrense er ?? 'unknown' en defekt.

Avvisningen har samme form overalt på plattformen, og den inneholder nok informasjon til at en klient kan vise hvordan feilen rettes:

{
  "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 er alltid true. code kommer fra plattformens kodekatalog. resolved[] navngir aksene som ble utledet, og missing[] de aksene ruten trengte, men ikke kunne hente. troubleshooting[] forteller hva som faktisk vil løse problemet. Et nakent «forbidden» lærer ingen noen ting.

Hold 401 og 403 adskilt, fordi klienter reagerer ulikt på dem.

Status Betydning Hva klienten gjør
401 Ikke autentisert Logger inn på nytt
403 Autentisert, men forespørselen kan ikke avgrenses, eller kalleren mangler rettigheten Slutter å prøve på nytt og endrer forespørselen

En omfangsavvisning som besvares med 401, sender klienten inn i en innloggingsløkke som ingen innlogging kan avslutte: den kaster økten og logger inn på nytt, prøver igjen og får 401 på nytt, mens brukeren ser på et lastehjul i det uendelige.

To ytterligere mekanismer gjør avvisningen total. Inne i en håndterer er scopeOf(req) den eneste måten å lese omfanget på, og den kaster et unntak hvis vakten ikke har kjørt. Og vakten kjører etter tolking av forespørselskroppen og før enhver håndterer; en håndterer som blir nåbar uten predikatet, svarer med vilje 500 med MIDDLEWARE_ORDERING_ERROR, slik at det havner i feilbudsjettet ditt i stedet for i en hendelsesrapport.

Databasen holder den samme linjen på egen hånd

Kodegjerdet og databasegjerdet er to mekanismer for én og samme lov, og du får begge.

Hver spørring mot en avgrenset tabell setter sammen tenantFence(scope) fra SDK-et; du skriver aldri predikatet for hånd. Hver spørring kjører også inne i withScopedTx, som binder de tre aksene for den ene transaksjonen gjennom én enkelt databasefunksjon og avviser en ny binding (SCOPE_ALREADY_BOUND). Under panseret har hver tabell i skjemaet ditt tvungen sikkerhet på radnivå, og rollen forespørselsbanen din kobler til som, kan ikke selv endre den bundne leietakeren. En prosess som kobler til med en rolle som kan omgå sikkerhet på radnivå, nekter å starte opp med DB_ROLE_BYPASSES_ISOLATION. Kapittel 2.22, Kjøremiljøet for programtillegg, viser koden; kapittel 2.21, SDK for programtillegg, viser hvordan rollene genereres for deg.

Den ene kryssingen: en registrert tildeling

Det finnes nøyaktig én vei over leietakergrensen. Organisasjonen som eier radene, registrerer en tillatelse som navngir hvilken organisasjon som kan lese hvilke tabeller, under hvilken avtale og hvor lenge. Databasen gjør lesingen skrivebeskyttet, og hvert oppslag logges før selve lesingen, i begge organisasjoner, kun med ID. Skriveoperasjoner krysser aldri grensen; arbeid som overleveres til et annet firma, sendes som en melding. Eier- og administratorrollene leser aldri over grensen i det hele tatt, og manifestet avvises hvis rettigheten som åpner for lesing på tvers av organisasjoner, ikke utelukker dem. Et programtillegg som ønsker en annen vei over, får det ikke.

Regel 2: all beregning kjører gjennom UNO-utsendelse

Arbeidsflytmotoren UNO er den eneste beregningsbanen. Koden din kaller aldri en modelleverandør eller en motor direkte, og heller aldri en kø eller en arbeidsflytvert. Du sender én konvolutt til utsendelsesendepunktet og får 202 med identifikatorer tilbake; resultatet kommer via spørring (polling) eller tilbakekall.

Tre vaner følger av dette, og malen har allerede alle tre.

  • Én fil eier utsendelses-URL-en. UNO_DISPATCH_URL leses én gang i konfigurasjonslasteren og må være en adresse internt i klyngen. En offentlig adresse avvises ved oppstart, fordi ingenting forlater installasjonen.
  • Én lukket tillatelsesliste over hva denne flaten kan sende ut. En bakende som sender ut enhver ferdighets-ID en nettleser gir den, fungerer som en generell mellomtjener for hver eneste ferdighet i registeret, inkludert ferdigheter fra andre programtillegg og ferdigheter som bruker andres modellbudsjett. Listen er en konstant på modulnivå med navneromsavgrensede jobbtyper, aldri en miljøvariabel. En ID som ikke står på listen, avvises med SKILL_NOT_ALLOWED.
  • Dobbeltsjekk det som kommer tilbake. Når du leser tilbake en jobb, sammenligner SDK-klienten den returnerte radens organization_id med kallerens leietaker på din side av nettverkskallet. Et gjerde som kun eksisterer på den andre siden av et kall, er bare en konvensjon.

Regel 3: all KI går gjennom KI-leverandørruteren

Et programtillegg gjør ingen kall til en modell, noe sted. Det finnes ingen leverandør-SDK i package.json, ingen modellnøkkel i miljøet og ingen videresending. Ruteren alene sitter på organisasjonens leverandørlegitimasjon og tar den endelige avgjørelsen om leverandør og modell.

Det et programtillegg kan gjøre, er å uttrykke ønsker på registreringstidspunktet, i manifestferdighetens registerrad:

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

Ruteren oppfyller et ønske kun når organisasjonen har den aktuelle leverandøren aktivert og lagt inn legitimasjon for den. Ellers velger den en erstatning fra organisasjonens egen beholdning. capabilityProfile velger aldri; den filtrerer, og feltet dataResidency er en absolutt jurisdiksjonsbegrensning som ruteren enten oppfyller eller avviser. Å utelate alle disse er riktig standardvalg for de fleste ferdigheter: da er det organisasjonens egne rolletildelinger som avgjør, og det er organisasjonen som betaler.

To typer avvisninger kan komme tilbake, og de betyr svært forskjellige ting.

Kode Status Hva det betyr
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER 403 Koden din prøvde å kalle ruteren selv. Stopp: dette er grensesnittet som avviser som tiltenkt, og kallet kan ikke prøves på nytt
MODEL_CAPABILITY_UNAVAILABLE 422 Ingen aktivert leverandør har en modell som tilfredsstiller profilen. Lemp på profilen, eller la organisasjonen aktivere en kapabel leverandør
NO_PROVIDER_FOR_ROLE 422 Organisasjonen har ikke konfigurert ruting for denne rollen. Vis ruterens utbedringstekst til brukeren

Det andre paret hører hjemme på skjermen, ikke i en logg. Det finnes ingen standardmodell og ingen reserveleverandør: en rolle organisasjonen ikke har satt opp, feiler tydelig med en setning som forteller hva som må konfigureres.

Den eneste leseoperasjonen et programtillegg kan gjøre mot ruteren, er effectiveRoute() fra runtime/ai-route. Den svarer på hvilken leverandør og modell ruteren ville valgt for den innloggede organisasjonen uten å sende en KI-forespørsel, og den returnerer ruterens avvisning i klartekst når det ikke finnes noen modell. Kapittel 2.22, Kjøremiljøet for programtillegg, viser dette.

Tillitsstigen legger til enda en grense. Kun core- og verified-programtillegg kan deklarere de to ferdighetsnivåene i manifestet som når ruteren, tool_using og llm_only. Alle andre formidler deterministisk arbeid og lar plattformen ta seg av delen som kontakter modellen.

Regel 4: nøkler tilhører organisasjonen

Hver organisasjon tar med sin egen leverandørkonto og nøkkel, og betaler sin egen regning. Nøkkelen ligger i organisasjonens beholdning av KI-leverandører, administrert av dens egne administratorer fra konsollen, og ruteren slår den opp på kalletidspunktet. Det finnes ingen delt plattformnøkkel bak en leietaker, så ingen organisasjon bruker av en annens budsjett.

For en utvidelse betyr det tre ting.

  • Du sitter aldri på en modellnøkkel, verken i kode, konfigurasjon eller et hemmelighetslager. Portvakten no-credentials stopper bygget hvis en nøkkel er lesbar, og konfigurasjonslasteren nekter å starte opp hvis en er til stede.
  • Du lister aldri opp en organisasjons nøkler. Hvis programtillegget ditt tror det trenger å gjøre det, er kravet plassert på feil sted.
  • En organisasjon uten nøkkel får ingen KI-svar. Det er en forventet tilstand med et eget skjermbilde. Navngi den manglende rollen, siter utbedringsteksten og henvis deretter brukeren til leverandørinnstillingene. Ikke vis det som et tomt resultat.

Regel 5: lisensierte funksjoner kontrolleres mot lisensen

Hva en installasjon kan bruke utover Community-grunnivået, bestemmes fra ett sted: lisensdokumentet som Adverant signerer, verifisert på installasjonen kun med offentlige nøkler. Utvidelsen din tar aldri avgjørelser basert på noe svakere, som et abonnementsnavn i et token eller et flagg i konfigurasjonen.

I et programtillegg er den enkleste måten å knytte en funksjon til lisensen på, via rettigheten som beskytter den. En rettighet i manifestets rights-register kan navngi en licence-funksjon:

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

Alle som kaller en rute beskyttet av den rettigheten, avvises med LICENCE_LOCKED (403), uansett hvilke roller og lisenser de har, når organisasjonens lisens ikke inneholder compliance-packs. Avvisningen navngir funksjonen og hva som inkluderer den, og forteller hvem som kan slå den på.

Lisensens tilstand har også betydning. Mens en lisens er gyldig eller i varslingsvinduet sitt, fungerer lisensierte funksjoner, og de fortsetter å fungere i henstandsperioden, mens henstandsperioden viser varselet LICENCE_IN_GRACE. Når en lisens har passert henstandsperioden, begrenses den: pågående arbeid og lesing fortsetter, og det samme gjør eksporter og sikkerhetsoppdateringer, men å opprette noe nytt under en lisensiert funksjon avvises med LICENCE_LOCKED. Bygg opprettelsesbanene dine med forventning om dette svaret.

Når programtillegget ditt spør rettighetskontrollen om en organisasjon har en funksjon, får det en kjennelse, aldri en ren boolsk verdi. «Ikke nåbar» og «nåbar og nei» er to forskjellige fakta med forskjellige koder: ENTITLEMENT_UNREACHABLE (502) og ENTITLEMENT_DENIED (403). Et kortvarig nettverksbrudd må aldri i det stille nedgradere hver kunde til gratisnivået.

Manifest og tillatelser
Manifest og tillatelser
Manifest og tillatelser sammenligner hva en utgivelse deklarerer med den forrige. Her legger versjon 0.4.0 til sending av e-post og én ekstern adresse, så utgivelsen holdes tilbake med MANIFEST_SCOPE_WIDENED inntil to kontrollører og etterlevelsesansvarlig godkjenner den.

Manifestet gjentar loven

Hvert v2-manifest inneholder en architecture-blokk med tre påkrevde setninger, og validatoren låser ordlyden deres. I et programtillegg du bygger for din egen installasjon, lyder de slik:

"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."
}

Disse setningene blir kontrollert. Et programtillegg der manifestet godtok lovene samtidig som koden kalte en modelleverandør direkte, ville løyet i sin egen kontrakt, og portvaktene eksisterer for å gjøre løgnen mulig å oppdage.

Portene som håndhever hver regel

SDK-et leverer tjueto etterlevelsesportvakter som én kommando, nexus-gates. Kapittel 2.21, SDK for programtillegg, beskriver hver eneste en. Her er de gruppert etter regelen de håndhever.

Regel Portvakter Hva som stopper bygget
Isolasjon i rutelaget scope-adherence, one-fence, rights-register, crud-adherence En /api-rute uten omfangsvakten, et ekstra håndskrevet leietakerpredikat, en omfangsrute uten rettighet, en endrende rute hvis rettighet ikke navngir noe
Isolasjon i SQL sql-fence, no-set-config En spørring mot en avgrenset tabell uten gjerdet; programtilleggskode som binder leietakerinnstillingen selv
Isolasjon i databasen migrations-are-scoped, rls-present, db-role-honest En tabell som mangler en akse eller en nøkkel som starter med leietaker, en tabell uten tvungen sikkerhet på radnivå, en forespørselsbane som kobler til som eier eller superbruker
Den eneste krysningsveien grants-declared En tabell tildelt tilgang i migreringer som manifestet ikke deklarerer, eller en leserolle som er gitt privilegier for hånd
Beregninger gjennom UNO no-direct-compute Et direkte kall til en modelleverandør eller motor, eller til en kø eller arbeidsflytvert; en ekstra leser av utsendelses-URL-en
KI og nøkler no-credentials En legitimasjon for en modelleverandør som er lesbar i kodelageret eller miljøet
Den deklarerte kontrakten api-contract, platform-clients, declared-input En rute som er registrert, men ikke deklarert, eller deklarert, men ikke registrert; en plattformklient som er importert, men ikke navngitt

Hver portvakt har en selvtest som beviser at den feiler på et testoppsett som er bygget for å løse den ut. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test kjører dem alle, og en portvakt som har sluttet å feile på sitt eget testoppsett, har sluttet å virke.

Hva en app kan nå
Hva en app kan nå
Hva en app kan nå lister opp hver eksterne adresse en app har deklarert, og hvorvidt etterlevelsesansvarlig har godkjent den. Et kall til en adresse ingen har deklarert, blir stoppet og telt før noe forlater installasjonen.

Før du ber om en gjennomgang

Dette er listen jeg går gjennom før jeg ber en kollega om å gjennomgå et programtillegg. Hver linje er noe en kontrollør hos Corrán Orbital har sendt tilbake til meg minst én gang.

  1. Hver /api-rute registrerer omfangsvakten, og de eneste anonyme rutene er eksakte baner deklarert som auth: public med allowAnonymous: true.
  2. Hver rute som omfangsvakten betjener, navngir en right fra manifestets register, og ingen håndterer utfører en egen rettighetssjekk.
  3. Ingen håndterer leser en organisasjon, en person eller en enhet fra forespørselskroppen, spørringen eller en header.
  4. Hver spørring mot en avgrenset tabell går gjennom tenantFence inne i withScopedTx, og ingenting i datalagringslaget kaller set_config.
  5. Hver tabell har de tre aksekolonnene, en primærnøkkel som starter med organization_id, og sammensatte fremmednøkler som bærer leietakeren.
  6. Utsendelses-URL-en leses i én fil, og tillatelseslisten for utsendelse er en konstant med navneromsavgrensede jobbtyper.
  7. Ingenting i package.json snakker med en modelleverandør, og ingen nøkkel ligger i miljøet.
  8. Hver funksjon som kun enkelte lisenser inneholder, navngir sin licence på rettigheten som beskytter den.
  9. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test lyser grønt, og det gjør også npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.

Hvis alle ni punktene er oppfylt, handler gjennomgangen om produktet ditt, som er det kontrollørens tid faktisk bør gå til.

Hvorfor plattformen håndhever disse reglene

Hver regel ovenfor var en gang en konvensjon et eller annet sted, og hver konvensjon feilet på samme måte: rutene som husket den, gikk fint, og den ene som glemte den, ble til en hendelse. Et forretningsenhetsgjerde lagt på som valgfri mellomvare ble omgått på seks uavhengige måter, hver av dem en rute som aldri hadde koblet seg på. En miljøvariabel som skrev om leietakeridentiteten, serverte én organisasjon en annens 1406 kontakter, og det så riktig ut i gjennomgangen fordi det var riktig for podden det ble skrevet for.

Derfor plasserer plattformen predikatet der hver flate allerede passerer gjennom det: i omfangsvakten og gjerdefunksjonen, i transaksjonsinnpakningen og den tvungne sikkerheten på radnivå, samt i utsendelsesklienten. En portvakt lister deretter opp hver rute, hver spørring og hver import, og stopper bygget når en av dem når en avgrenset tabell, en modell eller en beregningsmotor uten å gå gjennom disse mekanismene. Kostnaden ved dette designet er at ditt første programtillegg føles begrenset. Gevinsten er at det tusende programtillegget er isolert uten at forfatteren engang vet at funksjonen eksisterer, fordi det ikke finnes noen annen vei til dataene.

Det finnes en ærlig begrensning ved alt dette. Portvaktene beviser at koden din går gjennom mekanismene; de kan ikke bevise at produktlogikken din er riktig. En rute som helt korrekt avgrenser en spørring til eierens rader, kan likevel vise feil rader til riktig eier. Testsettet for isolasjon i kapittel 2.22, Kjøremiljøet for programtillegg, angriper hver rute som en annen organisasjon og som en kollega, der hvert gjerde fjernes etter tur, og det er testen jeg ville kjørt før jeg stolte på min egen forståelse av noe av dette.