Log indBook en briefing

Kapitel 2.19

De regler enhver udvidelse arver

Isolation på tre akser, beregning gennem UNO, AI (kunstig intelligens) gennem routeren, organisationsejede nøgler og licenskontroller. Hvad hver regel betyder for Deres kode, hvilken kontrolport der håndhæver den, og hvorfor De arver den i stedet for at skrive den.

Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

15 minutters læsetid

Den første afvisning, mit plugin til anomaligenrelæsning nogensinde sendte, var til mig selv. Jeg havde skrevet en testklient, der sendte en ny gennemgang med organisationens id i brødteksten, af gammel vane fra en anden platform, og pluginnet svarede, før min handler kørte:

{
  "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 havde ikke skrevet det tjek. Det fulgte med den scope-guard, som SDK-skabelonen (software development kit) forbinder til hver /api-rute, og den udløses, selv når id'et i brødteksten er kalderens eget. Det er mønstret for hele dette kapitel: et lille antal regler, der hver især håndhæves af en mekanisme, du arver, og hver med en gate, der lader dit build fejle, hvis din kode forsøger at gå uden om den. På Nexus arver dit plugin sin isolation fra platformen, og gatene reviderer det.

Der er fem regler, og afsnittene nedenfor gennemgår dem efter tur: isolation på tre akser; beregning, der kun kører gennem UNO-dispatch; AI (kunstig intelligens), der kun går gennem AI Provider Router; modelnøgler, der tilhører organisationen; og licenserede funktioner, der kontrolleres op imod licensen. Hvert manifest gentager desuden tre af dem i én samlet tekstblok.

Regel 1: isolation på tre akser, ud fra den autentificerede forespørgsel

Hver læsning og skrivning i en udvidelse afgrænses (scopes) på tre akser, og det samme gælder hvert værktøjskald og hver skill-dispatch.

Akse Kolonne Besvarer Hvor skarp grænsen er
Lejer (Tenant) organization_id Hvilken organisation En skarp grænse, der kun krydses via en registreret skrivebeskyttet tilladelse
Ejer (Owner) owner_user_id Hvilken person i organisationen Privat selv inden for én organisation, for alt personligt
Enhed (Unit) business_unit_id Hvilken del af organisationen Et valgfrit hegn inden for en lejer (tenant)

Ejer-aksen (owner) er den, nye udviklere oftest tager fejl af. En postkasse er personlig, og det samme er en gemt visning eller en graf udledt af én persons data. To medlemmer af samme organisation, i samme enhed og med samme rolle, ser ikke hinandens ejer-afgrænsede rækker. På et organisationsartefakt, for eksempel en godkendelse eller en sagsregistrering, udgør ejeren i stedet oprindelsen (provenance): den registrerer, hvem der handlede, og læsninger er afgrænset til lejeren, så revisionssporet forbliver synligt for de personer, der har brug for det. Du beslutter pr. tabel, hvilken type det er, og repository-laget indkoder det – det er aldrig et særtilfælde i en rute.

Akserne kommer fra den autentificerede forespørgsel og intet andet sted fra. En miljøvariabel kan ikke levere dem, og det kan en forespørgselsparameter, et stisegment, en klient-header eller en build-konstant heller ikke. SDK'et gør det svært at skrive det forkerte: resolveScope(identity, options) har slet ingen organisationsparameter. Organisationen ligger inde i identity, og kun et verificeret token frembringer én. Der er intet at sende et id igennem.

Det er grunden til, at en brødtekst, der angiver lejeren, afvises i stedet for at blive ignoreret. Guarden afviser ethvert af fem feltnavne: orgId, organizationId, organization_id, tenant og tenantId. Et felt, der ignoreres i stilhed, lærer kalderen, at feltet virker. Den første kalder tester det og ser sine egne data; den anden sender en anden organisations id. Ved at afvise ved den første forespørgsel fastslås kontrakten, før nogen bygger videre på den forkerte antagelse. Den samme regel gælder for inputParams i en dispatch: et input til en skill, der indeholder et organisations-id, afvises ved dispatch.

Enhedsaksen (unit) er enten deklareret og håndhævet eller slet ikke brugt. En rute, der deklarerer needsUnit: true, afviser, når legitimationsoplysningerne ikke kan fastslå en enhed, med unit angivet i missing[]. Du må ikke danne en kunstig enhed ud fra et underdomæne eller en header, og du må ikke angive en standardværdi. En opdigtet enhed afgrænser anderledes end organisationens reelle enheder, og den fletter rækker, den ikke burde.

En flade, der ikke kan udtrykke prædikatet, afviser

Hvis en rute ikke kan oplyse, hvilken lejer og ejer en række tilhører, og hvilken enhed når den behøver en, afviser den. Der er ingen læsning på tværs af hele organisationen som nødløsning og ingen pladsholderværdi. En pladsholder er den værste løsning, fordi en pladsholder er en værdi, og værdier matcher rækker: en værktøjsrouter, der satte både lejer og bruger til standardstrengen 'unknown', udleverede data for hele organisationen til hvem som helst, der kaldte den. På en lejergrænse er ?? 'unknown' en defekt.

Afvisningen har samme form overalt på platformen, og den indeholder nok til, at en klient kan vise løsningen:

{
  "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 altid true. code kommer fra platformens kodekatalog. resolved[] angiver de akser, der blev udledt, og missing[] dem, som ruten havde brug for, men ikke kunne få. troubleshooting[] fortæller, hvad der rent faktisk vil løse problemet. Et blot "forbidden" lærer ingen noget.

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

Status Betydning Hvad klienten gør
401 Ikke autentificeret Logger ind igen
403 Autentificeret, men forespørgslen kan ikke afgrænses (scopes), eller kalderen mangler rettigheden Stopper nye forsøg og ændrer forespørgslen

En scope-afvisning, der besvares med 401, sender en klient ud i en login-løkke, som intet login kan afslutte: den kasserer sessionen og logger ind igen, prøver på ny og får 401 igen, mens brugeren ser på en uendelig indlæsningsindikator.

Yderligere to mekanismer gør afvisningen total. Inde i en handler er scopeOf(req) den eneste måde at læse scopet på, og den kaster en fejl, hvis guarden ikke kørte. Og guarden kører efter fortolkning af brødteksten og før enhver handler; en handler, der bliver tilgængelig uden prædikatet, svarer med vilje 500 med MIDDLEWARE_ORDERING_ERROR, så den lander i dit fejlbudget i stedet for i en hændelsesrapport.

Databasen fastholder den samme linje på egen hånd

Kodehegnet og databasehegnet er to mekanismer for én lov, og du får begge.

Hvert udtryk mod en scopet tabel sammensætter tenantFence(scope) fra SDK'et; du skriver aldrig prædikatet i hånden. Hvert udtryk kører også inde i withScopedTx, som binder de tre akser for den ene transaktion gennem en enkelt databasefunktion og afviser en anden binding (SCOPE_ALREADY_BOUND). Nedenunder har hver tabel i dit skema tvungen sikkerhed på rækkeniveau (row-level security) slået til, og den rolle, som din forespørgselssti forbinder som, kan ikke selv ændre den bundne lejer. En proces, der forbinder som en rolle, der kan omgå sikkerhed på rækkeniveau, nægter at starte op med DB_ROLE_BYPASSES_ISOLATION. Kapitel 2.22, The plugin runtime, viser koden; kapitel 2.21, The Plugin SDK, viser, hvordan rollerne genereres for dig.

Den eneste krydsning: en registreret tilladelse

Der er præcis én vej over lejergrænsen. Den organisation, der ejer rækkerne, registrerer en tilladelse (grant), der angiver, hvilken organisation der må læse hvilke tabeller, under hvilken aftale og i hvor lang tid. Databasen gør læsningen skrivebeskyttet, og hvert opslag logges før læsningen, i begge organisationer, kun med id. Skrivninger krydser aldrig grænsen; arbejde, der overdrages til et andet firma, sendes som en besked. Ejer- og administratorrollerne læser overhovedet aldrig på tværs af grænsen, og manifestet afvises, hvis den rettighed, der tillader en læsning på tværs af organisationer, ikke udelukker dem. Et plugin, der ønsker en anden vej over, får den ikke.

Regel 2: al beregning kører gennem UNO-afvikling

UNO, workflow-motoren, er den eneste beregningssti. Din kode kalder aldrig en modeludbyder eller en motor direkte, og heller aldrig en kø eller en workflow-vært. Du sender én kuvert (envelope) til dispatch-endpointet og får 202 med identifikatorer tilbage; resultatet ankommer ved polling eller via callback.

Tre faste rutiner følger heraf, og skabelonen har allerede alle tre.

  • Én fil ejer dispatch-URL'en. UNO_DISPATCH_URL læses én gang i konfigurationsindlæseren og skal være en adresse internt i klyngen. En offentlig adresse afvises ved opstart, fordi intet forlader installationen.
  • Én lukket positivliste (allow-list) over, hvad denne flade må dispatche. En backend, der dispatcher ethvert skill-id, som en browser giver den, fungerer som en generel proxy for hver eneste skill i registret, herunder skills fra andre plugins og skills, der bruger en andens modelbudget. Listen er en konstant på modulniveau med jobtyper i navnerum, aldrig en miljøvariabel. Et id, der ikke står på den, afvises med SKILL_NOT_ALLOWED.
  • Kontrollér det, der kommer tilbage, igen. Når du læser et job tilbage, sammenligner SDK'ets klient den returnerede rækkes organization_id med kalderens lejer på din side af netværkskaldet. Et hegn, der kun eksisterer på den anden side af et kald, er blot en konvention.

Regel 3: al AI går gennem AI-udbyderrouteren

Et plugin foretager intet kald til en model, overhovedet. Der er intet udbyder-SDK i package.json, ingen modelnøgle i miljøet og intet relæ. Routeren alene opbevarer organisationens legitimationsoplysninger til udbyderen og træffer den endelige beslutning om udbyder og model.

Det, et plugin må gøre, er at udtrykke ønsker på registreringstidspunktet på manifest-skillens registreringsrække:

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

Routeren imødekommer kun et ønske, når organisationen har den pågældende udbyder aktiveret og forsynet med legitimationsoplysninger. Ellers erstatter den fra organisationens egen pulje. capabilityProfile udvælger aldrig; den filtrerer, og dens dataResidency-felt er en ufravigelig jurisdiktionsbegrænsning, som routeren enten opfylder eller afviser. At udelade alle disse er den rette standard for de fleste skills: organisationens egne rolletildelinger afgør det så, og det er organisationen, der betaler.

To slags afvisninger kan komme tilbage, og de betyder vidt forskellige ting.

Kode Status Hvad det betyder
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER 403 Din kode forsøgte selv at kalde routeren. Stop: dette er grænsefladen, der afviser som tilsigtet, og kaldet kan ikke prøves igen
MODEL_CAPABILITY_UNAVAILABLE 422 Ingen aktiveret udbyder har en model, der opfylder profilen. Slæk på profilen, eller få organisationen til at aktivere en kompatibel udbyder
NO_PROVIDER_FOR_ROLE 422 Organisationen har ikke konfigureret routing for denne rolle. Vis routerens løsningstekst til brugeren

Det andet par hører hjemme på skærmen, ikke i en log. Der er ingen standardmodel og ingen reserveudbyder: en rolle, som organisationen ikke har sat op, fejler tydeligt med en sætning, der fortæller, hvad der skal konfigureres.

Den eneste læsning, et plugin må foretage fra routeren, er effectiveRoute() fra runtime/ai-route. Den svarer på, hvilken udbyder og model routeren ville vælge for den indloggede organisation uden at sende en AI-forespørgsel, og den returnerer routerens afvisning i tekstform, når der ikke er nogen model. Kapitel 2.22, The plugin runtime, viser det.

Tillidsstigen tilføjer endnu en grænse. Kun core- og verified-plugins må deklarere de to manifest-skill-niveauer, der når routeren, tool_using og llm_only. Alle andre formidler deterministisk arbejde og lader platformen stå for den del, der rækker ud til modellen.

Regel 4: nøgler tilhører organisationen

Hver organisation medbringer sin egen udbyderkonto og nøgle og betaler sin egen regning. Nøglen ligger i organisationens pulje af AI-udbydere, som administreres af dens egne administratorer fra konsollen, og routeren slår den op på kaldtidspunktet. Der er ingen delt platformsnøgle bag en lejer, så ingen organisation bruger af en andens budget.

For en udvidelse betyder det tre ting.

  • Du opbevarer aldrig en modelnøgle, hverken i kode, konfiguration eller et nøglelager (secret store). no-credentials-gaten lader buildet fejle, hvis en nøgle kan læses, og konfigurationsindlæseren nægter at starte op, hvis en nøgle er til stede.
  • Du oplister aldrig en organisations nøgler. Hvis dit plugin mener, at det har brug for det, er kravet placeret det forkerte sted.
  • En organisation uden nøgle får ingen AI-svar. Det er en forventet tilstand med et reelt skærmbillede. Angiv den manglende rolle, citér løsningsteksten, og henvis derefter brugeren til vedkommendes udbyderindstillinger. Vis det ikke som et tomt resultat.

Regel 5: licenserede funktioner kontrolleres mod licensen

Hvad en installation må bruge ud over Community-basisniveauet, kommer fra ét sted: det licensdokument, som Adverant signerer, og som verificeres på installationen udelukkende med offentlige nøgler. Din udvidelse træffer aldrig beslutninger ud fra noget svagere, såsom et abonnementsnavn i et token eller et flag i konfigurationen.

I et plugin er den enkleste måde at binde en funktion til licensen på via den rettighed, der beskytter den. En rettighed i manifestets rights-register kan angive en licence-funktion:

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

Enhver, der kalder en rute beskyttet af den rettighed, afvises med LICENCE_LOCKED (403), uanset hvilke roller og licenspladser (seats) vedkommende har, når organisationens licens ikke indeholder compliance-packs. Afvisningen angiver funktionen og hvilket abonnement der indeholder den, og oplyser, hvem der kan slå den til.

Licensens tilstand har også betydning. Mens en licens er gyldig eller i sin advarselsperiode, fungerer licenserede funktioner, og de bliver ved med at fungere i henstandsperioden (grace), hvor henstandsperioden viser meddelelsen LICENCE_IN_GRACE. Når en licens har overskredet henstandsperioden, begrænses den: igangværende arbejde og læsninger fortsætter, og det samme gør eksporter og sikkerhedsopdateringer, men oprettelse af noget nyt under en licenseret funktion afvises med LICENCE_LOCKED. Byg dine oprettelsesstier, så de forventer det svar.

Når dit plugin spørger rettighedstjekket (entitlement check), om en organisation har en funktion, får det en afgørelse, aldrig en blottet boolesk værdi. "Ikke tilgængelig" og "tilgængelig og nej" er forskellige fakta med forskellige koder: ENTITLEMENT_UNREACHABLE (502) og ENTITLEMENT_DENIED (403). Et kortvarigt udfald i tilgængelighed må aldrig i stilhed nedgradere hver eneste kunde til gratisniveauet.

Manifest og tilladelser
Manifest og tilladelser
Manifest og tilladelser sammenligner, hvad en udgivelse deklarerer, med den forrige. Her tilføjer version 0.4.0 afsendelse af e-mail og én ekstern adresse, så udgivelsen sættes i bero med MANIFEST_SCOPE_WIDENED, indtil to kontrollanter og den compliance-ansvarlige godkender det.

Manifestet gentager loven

Hvert v2-manifest indeholder en architecture-blok med tre påkrævede sætninger, og validatoren fastlåser deres ordlyd. I et plugin, du bygger til din egen installation, lyder de:

"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 sætninger kontrolleres. Et plugin, hvis manifest erklærede sig enig i lovene, mens dets kode kaldte en modeludbyder, ville lyve i sin egen kontrakt, og gatene eksisterer for at gøre løgnen mulig at opdage.

De kontrolporte, der håndhæver hver regel

SDK'et leverer toogtyve overholdelses-gates (adherence gates) som én kommando, nexus-gates. Kapitel 2.21, The Plugin SDK, beskriver hver eneste af dem. Her er de grupperet efter den regel, de håndhæver.

Regel Porte Hvad der får buildet til at fejle
Isolation i rutelaget scope-adherence, one-fence, rights-register, crud-adherence En /api-rute uden scope-guarden, et ekstra håndskrevet lejerprædikat, en scope-rute uden rettighed, en ændrende (muterende) rute, hvis rettighed intet angiver
Isolation i SQL sql-fence, no-set-config Et udtryk på en scopet tabel uden hegnet; plugin-kode, der selv binder lejerindstillingen
Isolation i databasen migrations-are-scoped, rls-present, db-role-honest En tabel, der mangler en akse eller en nøgle med lejeren først, en tabel uden tvungen sikkerhed på rækkeniveau, en forespørgselssti, der forbinder som ejeren eller en superbruger
Den ene krydsning grants-declared En tabel tildelt i migreringer, som manifestet ikke deklarerer, eller en læseplads, der er tildelt privilegier i hånden
Beregning gennem UNO no-direct-compute Et direkte kald til en modeludbyder eller motor, eller til en kø eller workflow-vært; en ekstra læser af dispatch-URL'en
AI og nøgler no-credentials Legitimationsoplysninger til en modeludbyder, der kan læses i repositoryet eller miljøet
Den deklarerede kontrakt api-contract, platform-clients, declared-input En rute, der er registreret, men ikke deklareret, eller deklareret, men ikke registreret; en platformsklient, der er importeret, men ikke angivet

Hver gate har en selvtest, der beviser, at den fejler på en testopstilling (fixture), der er bygget til at udløse den. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test kører dem alle, og en gate, der er holdt op med at fejle på sin egen testopstilling, er holdt op med at virke.

Hvad en app må kontakte
Hvad en app må kontakte
Hvad en app må kontakte oplister hver ekstern adresse, en app har deklareret, og hvorvidt den compliance-ansvarlige har godkendt den. Et kald til en adresse, som ingen har deklareret, stoppes og tælles, før noget forlader installationen.

Før De anmoder om en gennemgang

Dette er den liste, jeg gennemgår, før jeg beder en kollega om at gennemgå et plugin. Hver linje er noget, en kontrollant hos Corrán Orbital har sendt retur til mig mindst én gang.

  1. Hver /api-rute registrerer scope-guarden, og de eneste anonyme ruter er eksakte stier, der er deklareret auth: public med allowAnonymous: true.
  2. Hver rute, som scope-guarden betjener, angiver en right fra manifestets register, og ingen handler indeholder sit eget rettighedstjek.
  3. Ingen handler læser en organisation, en person eller en enhed fra brødteksten, forespørgslen eller en header.
  4. Hvert udtryk på en scopet tabel går gennem tenantFence inde i withScopedTx, og intet i repositoryet kalder set_config.
  5. Hver tabel har de tre aksekolonner, en primærnøgle, der starter med organization_id, og sammensatte fremmednøgler, der indeholder lejeren.
  6. Dispatch-URL'en læses i én fil, og positivlisten for dispatch er en konstant med jobtyper i navnerum.
  7. Intet i package.json taler med en modeludbyder, og der ligger ingen nøgle i miljøet.
  8. Hver funktion, som kun visse licenser indeholder, angiver sin licence på den rettighed, der beskytter den.
  9. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test er grøn, og det samme er npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.

Hvis alle ni punkter er opfyldt, handler gennemgangen om dit produkt, hvilket er det, en kontrollants tid bør gå med.

Hvorfor platformen håndhæver disse regler

Hver regel ovenfor var engang en konvention et sted, og hver konvention fejlede på samme måde: de ruter, der huskede den, var i orden, og den ene, der glemte den, blev til sikkerhedshændelsen. Et hegn for forretningsenheder, der blev anvendt som valgfri middleware, blev omgået på seks uafhængige måder, hver især en rute, der aldrig havde tilmeldt sig. En miljøvariabel, der omskrev lejeridentiteten, udleverede en anden organisations 1.406 kontakter til en organisation, og det så korrekt ud ved gennemgang, fordi det var korrekt for den pod, det var skrevet til.

Derfor placerer platformen prædikatet der, hvor hver flade allerede passerer igennem det: i scope-guarden og hegnsfunktionen, i transaktions-wrapperen og den tvungne sikkerhed på rækkeniveau samt i dispatch-klienten. En gate oplister derefter hver rute, hvert udtryk og hver import og lader buildet fejle, når en af dem tilgår en scopet tabel, en model eller en beregningsmotor uden at gå gennem disse mekanismer. Omkostningen ved det design er, at dit første plugin føles begrænset. Gevinsten er, at plugin nummer tusind er isoleret, uden at dets forfatter ved, at funktionen eksisterer, fordi der ikke er nogen anden vej til dataene, det kan tage.

Der er en reel grænse for alt dette. Gatene beviser, at din kode går gennem mekanismerne; de kan ikke bevise, at din produktlogik er rigtig. En rute, der korrekt afgrænser en forespørgsel til ejerens rækker, kan stadig vise de forkerte rækker til den rette ejer. Isolationstestsættet i kapitel 2.22, The plugin runtime, angriber hver rute som en anden organisation og som en kollega, hvor hvert hegn fjernes ét efter ét, og det er den test, jeg ville køre, før jeg stolede på min egen læsning af noget af dette.