Logga inBoka en genomgång

Kapitel 2.19

Reglerna som varje tillägg ärver

Isolering på tre axlar, beräkning genom UNO, AI (artificiell intelligens) genom routern, organisationsägda nycklar och licenskontroller. Vad varje regel betyder för er kod och vilken grind som upprätthåller den, och varför ni ärver den i stället för att skriva den.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

15 minuters läsning

Det första avvisandet min plugin för avvikelsegranskning någonsin skickade var till mig. Jag hade skrivit en testklient som postade en ny granskning med organisationens id i brödtexten, av gammal vana från en annan plattform, och pluginen svarade innan min hanterare kördes:

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

Jag hade inte skrivit den kontrollen. Den följde med den räckviddsvakt som SDK-mallen (software development kit) kopplar in i varje /api-rutt, och den utlöses även när id:t i brödtexten är anroparens eget. Det är mönstret för hela det här kapitlet: ett litet antal regler, var och en upprätthållen av en mekanism som du ärver, och var och en med en spärr som stoppar ditt bygge om din kod försöker gå runt den. På Nexus ärver din plugin sin isolering från plattformen, och spärrarna granskar den.

Det finns fem regler, och avsnitten nedan tar dem i tur och ordning: isolering på tre axlar; beräkningar som endast körs via UNO-dispatch; AI (artificiell intelligens) som endast går via AI Provider Router; modellnycklar som tillhör organisationen; och licensierade funktioner som kontrolleras mot licensen. Varje manifest upprepar också tre av dem i ett stycke med meningar.

Regel 1: isolering på tre axlar, från den autentiserade begäran

Varje läsning och skrivning i ett tillägg begränsas på tre axlar, och detsamma gäller varje verktygsanrop och färdighets-dispatch.

Axel Kolumn Svarar på Hur skarp gränsen är
Klientorganisation (Tenant) organization_id Vilken organisation En skarp gräns, som endast passeras genom ett registrerat skrivskyddat tillstånd
Ägare owner_user_id Vilken person inom organisationen Privat även inom en och samma organisation, för allt personligt
Enhet business_unit_id Vilken del av organisationen En valfri avgränsning inom en klientorganisation (tenant)

Ägaraxeln är den som nykomlingar tar fel på. En postlåda är personlig, och det är även en sparad vy eller en graf som härletts från en persons data. Två medlemmar i samma organisation, i samma enhet och med samma roll, ser inte varandras ägarbegränsade rader. På en organisationsartefakt, till exempel ett godkännande eller ett ärende, utgör ägaren i stället ursprung: den registrerar vem som agerade, och läsningar begränsas till klientorganisationen så att revisionsspåret förblir synligt för de personer som behöver det. Du bestämmer per tabell vilken sort det är, och repositorielagret kodar in det – aldrig som ett specialfall i en rutt.

Axlarna kommer från det autentiserade anropet och ingen annanstans ifrån. En miljövariabel kan inte tillhandahålla dem, och det kan inte heller en frågeparameter, ett sökvägssegment, ett klienthuvud eller en byggkonstant. SDK:t gör det svårt att skriva fel: resolveScope(identity, options) har ingen organisationsparameter alls. Organisationen finns inuti identity, och endast en verifierad token skapar en sådan. Det finns ingenting att skicka ett id genom.

Det är därför en brödtext som namnger klientorganisationen avvisas i stället för att ignoreras. Vakten avvisar vart och ett av fem fältnamn: orgId, organizationId, organization_id, tenant och tenantId. Ett fält som ignoreras i tysthet lär anroparen att fältet fungerar. Den första anroparen testar det och ser sina egna data; den andra skickar en annan organisations id. Genom att avvisa vid det första anropet klargörs kontraktet innan någon bygger vidare på fel grund. Samma regel gäller för inputParams i en dispatch: indata till en färdighet som innehåller ett organisations-id avvisas vid dispatch.

Enhetsaxeln är antingen deklarerad och upprätthållen eller så används den inte. En rutt som deklarerar needsUnit: true avvisar när autentiseringsuppgiften inte fastställer en enhet, med unit angivet i missing[]. Syntetisera inte en enhet från en underdomän eller ett huvud, och ange ingen standardenhet. En påhittad enhet avgränsar på ett annat sätt än organisationens verkliga enheter, och den sammanfogar rader som den inte borde.

En yta som inte kan uttrycka predikatet avvisar

Om en rutt inte kan avgöra vilken klientorganisation och ägare en rad tillhör, och vilken enhet när det behövs, avvisar den. Det finns ingen organisationsövergripande läsning som reservlösning och inget platshållarvärde. En platshållare är det sämsta alternativet, eftersom en platshållare är ett värde och värden matchar rader: en verktygsrouter som satte både klientorganisation och användare som standard till strängen 'unknown' levererade organisationsövergripande data till vem som än anropade den. Vid en gräns för en klientorganisation är ?? 'unknown' en defekt.

Avvisandet har samma form överallt på plattformen, och det innehåller tillräckligt för att en klient ska kunna visa 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 är alltid true. code kommer från plattformens kodkatalog. resolved[] anger de axlar som härleddes och missing[] de som rutten behövde men inte kunde få. troubleshooting[] anger vad som faktiskt skulle lösa det. Ett enkelt "forbidden" lär ingen någonting.

Håll isär 401 och 403, eftersom klienter agerar olika på dem.

Status Betydelse Vad klienten gör
401 Inte autentiserad Loggar in igen
403 Autentiserad, men anropet kan inte räckviddsbegränsas, eller så saknar anroparen behörighet Slutar försöka igen och ändrar anropet

Ett räckviddsavvisande som besvaras med 401 skickar in klienten i en inloggningsloop som ingen inloggning kan avsluta: den kastar bort sessionen och loggar in igen, försöker på nytt och får 401 igen, medan personen ser en laddningssymbol i en evighet.

Ytterligare två mekanismer gör avvisandet totalt. Inuti en hanterare är scopeOf(req) det enda sättet att läsa räckvidden, och den kastar ett undantag om vakten inte kördes. Och vakten körs efter tolkning av brödtexten och före varje hanterare; en hanterare som blir nåbar utan predikatet svarar avsiktligt 500 med MIDDLEWARE_ORDERING_ERROR, så att det hamnar i din felbudget i stället för i en incidentrapport.

Databasen håller samma linje på egen hand

Kodavgränsningen och databasavgränsningen är två mekanismer för en och samma lag, och du får båda.

Varje sats mot en räckviddsbegränsad tabell sätter samman tenantFence(scope) från SDK:t; du skriver aldrig predikatet för hand. Varje sats körs också inuti withScopedTx, som binder de tre axlarna för den enskilda transaktionen genom en enda databasfunktion och avvisar en andra bindning (SCOPE_ALREADY_BOUND). Därunder har varje tabell i ditt schema påtvingad säkerhet på radnivå, och den roll som din anropssökväg ansluter som kan inte själv ändra den bundna klientorganisationen. En process som ansluter som en roll med förmåga att kringgå säkerhet på radnivå vägrar att starta med DB_ROLE_BYPASSES_ISOLATION. Kapitel 2.22, Exekveringsmiljön för plugins, visar koden; kapitel 2.21, Plugin-SDK:t, visar hur rollerna genereras åt dig.

Den enda korsningen: ett registrerat tillstånd

Det finns exakt en väg över gränsen mellan klientorganisationer. Den organisation som äger raderna registrerar ett tillstånd som anger vilken organisation som får läsa vilka tabeller, under vilket avtal och hur länge. Databasen gör läsningen skrivskyddad, och varje titt loggas före läsningen, i båda organisationerna, endast med id. Skrivningar korsar aldrig gränsen; arbete som lämnas över till ett annat företag färdas som ett meddelande. Ägar- och administratörsrollerna läser överhuvudtaget aldrig över gränsen, och manifestet avvisas om den behörighet som tillåter läsning över organisationsgränser inte blockerar dem. En plugin som vill ha en annan väg över får ingen.

Regel 2: all beräkning körs genom UNO-utskick

UNO, arbetsflödesmotorn, är den enda beräkningsvägen. Din kod anropar aldrig en modelleverantör eller en motor direkt, och aldrig heller en kö eller en arbetsflödesvärd. Du skickar ett kuvert till dispatch-slutpunkten och får tillbaka 202 med identifierare; resultatet kommer via pollning eller via återanrop (callback).

Tre rutiner följer av detta, och mallen har redan alla tre.

  • En fil äger dispatch-URL:en. UNO_DISPATCH_URL läses en gång i konfigurationsladdaren och måste vara en adress inom klustret. En publik adress avvisas vid uppstart, eftersom ingenting lämnar installationen.
  • En sluten tillåtelselista över vad denna yta får skicka (dispatcha). En backend som skickar vilket färdighets-id som helst som en webbläsare ger den är en allmän proxy för varje färdighet i registret, inklusive färdigheter från andra plugins och färdigheter som förbrukar någon annans modellbudget. Listan är en konstant på modulnivå med namnrymdsindelade jobbtyper, aldrig en miljövariabel. Ett id som inte finns med på den avvisas med SKILL_NOT_ALLOWED.
  • Kontrollera det som kommer tillbaka igen. När du läser tillbaka ett jobb jämför SDK-klienten den returnerade radens organization_id med anroparens klientorganisation på din sida av nätverksanropet. En avgränsning som bara finns på andra sidan av ett anrop är en konvention.

Regel 3: all AI går genom AI-leverantörsroutern

En plugin gör inga anrop till en modell, någonstans. Det finns inget leverantörs-SDK i package.json, ingen modellnyckel i miljön och inget relä. Routern ensam håller organisationens autentiseringsuppgifter för leverantören och fattar det slutgiltiga beslutet om leverantör och modell.

Vad en plugin får göra är att uttrycka önskemål, vid registreringstillfället, på manifestfärdighetens registerrad:

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

Routern tillgodoser ett önskemål endast när organisationen har den leverantören aktiverad och försedd med autentiseringsuppgifter. Annars väljer den en ersättare från organisationens egen pool. capabilityProfile väljer aldrig; den filtrerar, och dess dataResidency-fält är en strikt jurisdiktionell begränsning som routern antingen uppfyller eller avvisar. Att utelämna alla dessa är rätt standardval för de flesta färdigheter: organisationens egna rolltilldelningar avgör då, och det är organisationen som betalar.

Två typer av avvisanden kan komma tillbaka, och de betyder helt olika saker.

Kod Status Vad det innebär
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER 403 Din kod försökte anropa routern själv. Stopp: detta är gränssnittet som avvisar enligt sin design, och anropet kan inte försökas igen
MODEL_CAPABILITY_UNAVAILABLE 422 Ingen aktiverad leverantör har en modell som uppfyller profilen. Lätta på profilen, eller låt organisationen aktivera en kapabel leverantör
NO_PROVIDER_FOR_ROLE 422 Organisationen har inte konfigurerat routning för denna roll. Visa routerns åtgärdstext för personen

Det andra paret hör hemma på skärmen, inte i en logg. Det finns ingen standardmodell och ingen reservleverantör: en roll som organisationen inte har konfigurerat misslyckas tydligt, med en mening som anger vad som behöver konfigureras.

Den enda läsning en plugin får göra från routern är effectiveRoute() från runtime/ai-route. Den svarar på vilken leverantör och modell routern skulle välja för den inloggade organisationen utan att skicka ett AI-anrop, och den returnerar routerns avvisande i text när det inte finns någon modell. Kapitel 2.22, Exekveringsmiljön för plugins, visar detta.

Tillitstrappan lägger till ytterligare en gräns. Endast core- och verified-plugins får deklarera de två nivåer av manifestfärdigheter som når routern, tool_using och llm_only. Alla andra förmedlar deterministiskt arbete och låter plattformen sköta den del som når modellen.

Regel 4: nycklar tillhör organisationen

Varje organisation tar med sitt eget leverantörskonto och sin egen nyckel, och betalar sin egen räkning. Nyckeln ligger i organisationens pool av AI-leverantörer, som hanteras av dess egna administratörer från konsolen, och routern slår upp den vid anropstillfället. Det finns ingen delad plattformsnyckel bakom en klientorganisation, så ingen organisation förbrukar någon annans budget.

För ett tillägg innebär det tre saker.

  • Du innehar aldrig en modellnyckel, varken i kod, konfiguration eller ett hemlighetslager (secret store). Spärren no-credentials stoppar bygget om en sådan är läsbar, och konfigurationsladdaren vägrar att starta om en sådan finns.
  • Du räknar aldrig upp en organisations nycklar. Om din plugin tror att den behöver göra det ligger kravet på fel ställe.
  • En organisation utan nyckel får inga AI-svar. Det är ett förväntat tillstånd med en riktig vy. Ange den roll som saknas och citera åtgärdsförslaget, och hänvisa sedan personen till sina leverantörsinställningar. Visa det inte som ett tomt resultat.

Regel 5: licensierade funktioner kontrolleras mot licensen

Vad en installation får använda utöver Community-basnivån kommer från ett enda ställe: licensdokumentet som Adverant signerar, verifierat på installationen med enbart publika nycklar. Ditt tillägg fattar aldrig beslut utifrån något svagare, såsom ett plannamn i en token eller en flagga i konfigurationen.

I en plugin är det enklaste sättet att knyta en funktion till licensen via den behörighet som skyddar den. En behörighet i manifestets rights-register kan namnge en licence-funktion:

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

Den som anropar en rutt som skyddas av den behörigheten avvisas med LICENCE_LOCKED (403), oavsett vilka roller och platser (seats) personen har, när organisationens licens inte innehåller compliance-packs. Avvisandet anger funktionen och vad som krävs för den, samt vem som kan aktivera den.

Licensens tillstånd spelar också roll. Så länge en licens är giltig eller befinner sig i sitt varningsfönster fungerar licensierade funktioner, och de fortsätter att fungera under respittiden (grace), då respittiden visar meddelandet LICENCE_IN_GRACE. När en licens har passerat respittiden begränsas den: pågående arbete och läsningar fortsätter, liksom exporter och säkerhetsuppdateringar, men att skapa något nytt under en licensierad funktion avvisas med LICENCE_LOCKED. Bygg dina flöden för att skapa nytt så att de förväntar sig det svaret.

När din plugin frågar behörighetskontrollen om en organisation innehar en funktion får den ett utlåtande, aldrig ett enkelt booleskt värde. "Kan inte nås" och "kan nås och nej" är olika fakta med olika koder: ENTITLEMENT_UNREACHABLE (502) och ENTITLEMENT_DENIED (403). Ett tillfälligt avbrott i nåbarheten får aldrig i tysthet nedgradera varje kund till gratisnivån.

Manifest och behörigheter
Manifest och behörigheter
Manifest och behörigheter jämför vad en utgåva deklarerar med den föregående. Här lägger version 0.4.0 till e-postutskick och en extern adress, så utgåvan hålls kvar med MANIFEST_SCOPE_WIDENED tills två granskare och efterlevnadsansvarig (compliance officer) godkänner det.

Manifestet upprepar lagen

Varje v2-manifest innehåller ett architecture-block med tre obligatoriska meningar, och validatorn låser deras ordalydelse. I en plugin som du bygger för 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."
}

Dessa meningar kontrolleras. En plugin vars manifest samtycker till lagarna samtidigt som dess kod anropar en modelleverantör skulle ljuga i sitt eget kontrakt, och spärrarna finns till för att göra lögnen upptäckbar.

Grindarna som upprätthåller varje regel

SDK:t levererar tjugotvå efterlevnadsspärrar som ett enda kommando, nexus-gates. Kapitel 2.21, Plugin-SDK:t, beskriver var och en. Här är de grupperade efter den regel de upprätthåller.

Regel Spärrar Vad som stoppar bygget
Isolering i ruttlagret scope-adherence, one-fence, rights-register, crud-adherence En /api-rutt utan räckviddsvakten, ett andra handskrivet predikat för klientorganisation, en räckviddsrutt utan behörighet, en ändrande rutt vars behörighet inte anger någonting
Isolering i SQL sql-fence, no-set-config En sats mot en räckviddsbegränsad tabell utan avgränsningen; pluginkod som själv binder inställningen för klientorganisation
Isolering i databasen migrations-are-scoped, rls-present, db-role-honest En tabell som saknar en axel eller en nyckel som inleds med klientorganisation, en tabell utan påtvingad säkerhet på radnivå, en anropssökväg som ansluter som ägare eller superanvändare
Den enda korsningen grants-declared En tabell som beviljats tillstånd i migreringar som manifestet inte deklarerar, eller en läsplats som tilldelats privilegier för hand
Beräkning genom UNO no-direct-compute Ett direktanrop till en modelleverantör eller motor, eller till en kö eller arbetsflödesvärd; en andra läsare av dispatch-URL:en
AI och nycklar no-credentials En autentiseringsuppgift för en modelleverantör som är läsbar i repositoriet eller miljön
Det deklarerade kontraktet api-contract, platform-clients, declared-input En rutt som är registrerad men inte deklarerad, eller deklarerad men inte registrerad; en plattformsklient som är importerad men inte angiven

Varje spärr har ett självtest som bevisar att den slår bakut på en testfixtur som byggts för att utlösa den. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test kör dem alla, och en spärr som har slutat slå bakut på sin egen fixtur har slutat fungera.

Vad en app får nå
Vad en app får nå
Vad en app får nå listar varje extern adress som en app har deklarerat och huruvida efterlevnadsansvarig har godkänt den. Ett anrop till en adress som ingen har deklarerat stoppas och räknas innan någonting lämnar systemet.

Innan ni ber om en granskning

Det här är listan jag går igenom innan jag ber en kollega att granska en plugin. Varje rad är någonting som en granskare på Corrán Orbital har skickat tillbaka till mig minst en gång.

  1. Varje /api-rutt registrerar räckviddsvakten, och de enda anonyma rutterna är exakta sökvägar som deklarerats som auth: public med allowAnonymous: true.
  2. Varje rutt som räckviddsvakten betjänar anger en right från manifestets register, och ingen hanterare har en egen behörighetskontroll.
  3. Ingen hanterare läser en organisation, en person eller en enhet från brödtexten, frågeparametrarna eller ett huvud.
  4. Varje sats mot en räckviddsbegränsad tabell går genom tenantFence inuti withScopedTx, och ingenting i repositoriet anropar set_config.
  5. Varje tabell har de tre axelkolumnerna, en primärnyckel som inleds med organization_id och sammansatta främmande nycklar som bär klientorganisationen.
  6. Dispatch-URL:en läses i en enda fil, och tillåtelselistan för dispatch är en konstant av namnrymdsindelade jobbtyper.
  7. Ingenting i package.json pratar med en modelleverantör, och ingen nyckel ligger i miljön.
  8. Varje funktion som endast vissa licenser innehåller anger sin licence på den behörighet som skyddar den.
  9. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test är grön, och det är även npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.

Om alla nio stämmer kan granskningen handla om din produkt, vilket är vad en granskares tid bör gå till.

Varför plattformen upprätthåller dessa regler

Varje regel ovan var en gång en konvention någonstans, och varje konvention misslyckades på samma sätt: de rutter som kom ihåg den fungerade bra och den som glömde den blev incidenten. En affärsenhetsavgränsning som tillämpades som valfri mellanprogramvara (middleware) kringgicks på sex oberoende sätt, vart och ett via en rutt som aldrig valde att delta. En miljövariabel som skrev om klientorganisationens identitet visade en organisation en annan organisations 1 406 kontakter, och det såg korrekt ut vid granskningen eftersom det var korrekt för den podd det skrevs för.

Därför placerar plattformen predikatet där varje yta redan passerar igenom det: i räckviddsvakten och avgränsningsfunktionen, i transaktionsomslutningen och den påtvingade säkerheten på radnivå, samt i dispatch-klienten. En spärr räknar sedan upp varje rutt, varje sats och varje import, och stoppar bygget när någon av dem når en räckviddsbegränsad tabell, en modell eller en beräkningsmotor utan att gå genom dessa mekanismer. Kostnaden för den designen är att din första plugin känns begränsad. Vinsten är att den tusende pluginen är isolerad utan att dess skapare ens vet att funktionen finns, eftersom det inte finns någon annan väg till datan för den att ta.

Det finns en ärlig gräns för allt detta. Spärrarna bevisar att din kod går genom mekanismerna; de kan inte bevisa att din produktlogik är rätt. En rutt som korrekt begränsar en fråga till ägarens rader kan fortfarande visa fel rader för rätt ägare. Testpaketet för isolering i kapitel 2.22, Exekveringsmiljön för plugins, angriper varje rutt som en annan organisation och som en kollega, med varje avgränsning borttagen i tur och ordning, och det är det testet jag skulle köra innan jag litade på min egen tolkning av något av det här.