AccediPrenota un briefing

Capitolo 2.19

Le regole che ogni estensione eredita

Isolamento su tre assi, calcolo tramite UNO, IA (intelligenza artificiale) tramite il router, chiavi di proprietà dell'organizzazione e verifiche della licenza. Cosa significa ogni regola per il vostro codice, quale controllo la applica e perché la ereditate invece di doverla scrivere.

Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

15 minuti di lettura

Il primo rifiuto mai inviato dal mio plugin di revisione delle anomalie è stato indirizzato a me. Avevo scritto un client di test che inviava una nuova revisione con l'ID dell'organizzazione nel corpo, per abitudine maturata su un'altra piattaforma, e il plugin ha risposto prima che il mio handler venisse eseguito:

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

Non avevo scritto io quel controllo. Faceva parte della protezione dell'ambito (scope guard) che il template dell'SDK (Software Development Kit) collega a ogni route /api, e si attiva anche quando l'ID nel corpo appartiene al chiamante stesso. Questo è lo schema dell'intero capitolo: un numero ridotto di regole, ciascuna applicata da un meccanismo ereditato, ciascuna dotata di un gate che blocca la build se il codice cerca di aggirarlo. Su Nexus il plugin eredita il proprio isolamento dalla piattaforma, e i gate lo verificano.

Ci sono cinque regole, che le sezioni seguenti esaminano una per una: isolamento su tre assi; calcolo eseguito esclusivamente tramite il dispatch di UNO; IA (intelligenza artificiale) che transita solo attraverso l'AI Provider Router; chiavi dei modelli appartenenti all'organizzazione; e funzionalità concesse in licenza verificate rispetto alla licenza stessa. Ogni manifesto, inoltre, ne ribadisce tre in un unico blocco di frasi.

Regola 1: isolamento su tre assi, a partire dalla richiesta autenticata

Ogni lettura e scrittura in un'estensione ha un ambito definito su tre assi, così come ogni chiamata a strumenti e ogni dispatch di skill.

Asse Colonna Risposte Rigidità del confine
Tenant organization_id Quale organizzazione Un confine rigido, superabile solo tramite una concessione di sola lettura registrata
Proprietario owner_user_id Quale persona all'interno dell'organizzazione Privato anche all'interno della stessa organizzazione, per tutto ciò che è personale
Unità business_unit_id Quale parte dell'organizzazione Una barriera opzionale all'interno di un tenant

L'asse del proprietario (owner) è quello su cui i nuovi arrivati commettono più errori. Una casella di posta è personale, così come una vista salvata o un grafico derivato dai dati di una singola persona. Due membri della stessa organizzazione, nella stessa unità e con lo stesso ruolo, non vedono le rispettive righe il cui ambito è limitato al proprietario. Su un artefatto dell'organizzazione, ad esempio un'approvazione o il record di un caso, il proprietario indica invece la provenienza: registra chi ha agito, e le letture hanno come ambito il tenant affinché l'audit trail rimanga visibile alle persone che ne hanno bisogno. Si decide per ogni tabella di quale tipo si tratti e il livello del repository lo codifica, senza mai creare un caso speciale in una route.

Gli assi provengono dalla richiesta autenticata e da nessun'altra parte. Una variabile d'ambiente non può fornirli, e nemmeno un parametro di query, un segmento di percorso, un header del client o una costante di build. L'SDK rende difficile scrivere il codice sbagliato: resolveScope(identity, options) non ha alcun parametro per l'organizzazione. L'organizzazione si trova all'interno di identity, che può essere prodotto solo da un token verificato. Non c'è nulla attraverso cui passare un ID.

Ecco perché un corpo che specifica il tenant viene rifiutato anziché ignorato. La protezione rifiuta ciascuno di questi cinque nomi di campo: orgId, organizationId, organization_id, tenant e tenantId. Un campo ignorato silenziosamente insegna al chiamante che quel campo funziona. Il primo chiamante lo testa e vede i propri dati; il secondo invia l'ID di un'altra organizzazione. Rifiutare alla prima richiesta chiarisce il contratto prima che qualcuno costruisca su quello sbagliato. La stessa regola vale per inputParams di un dispatch: l'input di una skill che contiene un ID organizzazione viene rifiutato al momento del dispatch.

L'asse dell'unità o viene dichiarato e applicato, oppure non viene utilizzato. Una route che dichiara needsUnit: true oppone un rifiuto quando la credenziale non risolve un'unità, indicando unit in missing[]. Non ricavare un'unità da un sottodominio o da un header e non impostarne una predefinita. Un'unità fittizia crea barriere diverse rispetto alle unità reali dell'organizzazione e unisce righe che non dovrebbe unire.

Una superficie che non può esprimere il predicato oppone un rifiuto

Se una route non è in grado di stabilire a quale tenant e proprietario appartenga una riga, e a quale unità quando necessario, oppone un rifiuto. Non esiste una lettura estesa a tutta l'organizzazione come fallback, né un valore segnaposto. Un segnaposto è l'opzione peggiore, perché è un valore e i valori trovano corrispondenze nelle righe: un router di strumenti che impostava come predefinita la stringa 'unknown' sia per il tenant sia per l'utente ha finito per servire dati dell'intera organizzazione a chiunque lo chiamasse. Su un confine di tenant, ?? 'unknown' è un difetto.

Il rifiuto ha un'unica forma ovunque sulla piattaforma e contiene informazioni sufficienti affinché un client possa mostrare la soluzione:

{
  "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 è sempre true. code proviene dal catalogo dei codici della piattaforma. resolved[] indica gli assi che sono stati derivati e missing[] quelli di cui la route aveva bisogno ma che non ha potuto ottenere. troubleshooting[] spiega cosa risolverebbe effettivamente il problema. Un semplice "forbidden" non insegna nulla a nessuno.

Mantenere distinti gli errori 401 e 403, poiché i client reagiscono ad essi in modo diverso.

Stato Significato Cosa fa il client
401 Non autenticato Effettua nuovamente l'accesso
403 Autenticato, ma non è possibile definire l'ambito della richiesta, oppure il chiamante non dispone del diritto necessario Interrompe i tentativi e modifica la richiesta

Un rifiuto di ambito restituito come 401 manda il client in un ciclo di accesso infinito: scarta la sessione ed effettua nuovamente l'accesso, riprova e ottiene di nuovo 401, mentre l'utente fissa all'infinito un indicatore di caricamento.

Altri due meccanismi rendono il rifiuto totale. All'interno di un handler, scopeOf(req) è l'unico modo per leggere l'ambito e solleva un'eccezione se la protezione non è stata eseguita. Inoltre, la protezione viene eseguita dopo il parsing del corpo e prima di qualsiasi handler; un handler che diventa raggiungibile senza il predicato risponde deliberatamente con un errore 500 e MIDDLEWARE_ORDERING_ERROR, in modo che finisca nel budget di errore anziché in un rapporto di incidente.

Il database mantiene la stessa linea autonomamente

La barriera nel codice e la barriera nel database sono due meccanismi per un'unica legge, ed entrambi vengono forniti di serie.

Ogni istruzione su una tabella con ambito compone tenantFence(scope) dall'SDK; non si scrive mai il predicato a mano. Ogni istruzione viene inoltre eseguita all'interno di withScopedTx, che vincola i tre assi per quella singola transazione tramite un'unica funzione di database e rifiuta un secondo vincolo (SCOPE_ALREADY_BOUND). Sotto il cofano, ogni tabella dello schema ha la sicurezza a livello di riga (row-level security) forzata, e il ruolo con cui si connette il percorso di richiesta non può modificare autonomamente il tenant vincolato. Un processo che si connette con un ruolo in grado di aggirare la sicurezza a livello di riga rifiuta di avviarsi restituendo DB_ROLE_BYPASSES_ISOLATION. Il capitolo 2.22, Il runtime dei plugin, mostra il codice; il capitolo 2.21, L'SDK dei plugin, mostra come i ruoli vengono generati automaticamente.

L'unico attraversamento: un'autorizzazione registrata

Esiste un solo modo per attraversare il confine del tenant. L'organizzazione che detiene le righe registra una concessione che specifica quale organizzazione può leggere quali tabelle, in base a quale accordo e per quanto tempo. Il database rende la lettura di sola lettura e ogni consultazione viene scritta prima della lettura, in entrambe le organizzazioni, esclusivamente tramite ID. Le scritture non attraversano mai il confine; il lavoro affidato a un'altra azienda viaggia sotto forma di messaggio. I ruoli di proprietario e amministratore non leggono mai oltre il confine, e il manifesto viene rifiutato se il diritto che ammette una lettura tra organizzazioni non li esclude. Un plugin che cerca un altro modo per attraversare il confine non lo ottiene.

Regola 2: tutto il calcolo viene eseguito tramite il dispatch UNO

UNO, il motore di workflow, è l'unico percorso di calcolo. Il codice non contatta mai direttamente un fornitore di modelli o un motore, e nemmeno una coda o un host di workflow. Si invia un'unica busta (envelope) all'endpoint di dispatch e si riceve 202 con gli identificatori; il risultato arriva tramite polling o callback.

Ne conseguono tre buone pratiche, tutte già integrate nel template.

  • Un solo file gestisce l'URL di dispatch. UNO_DISPATCH_URL viene letto una sola volta nel caricatore della configurazione e deve essere un indirizzo interno al cluster. Un indirizzo pubblico viene rifiutato all'avvio, poiché nulla esce dall'installazione.
  • Un'unica allow-list chiusa di ciò che questa superficie può inviare in dispatch. Un backend disposto a inviare in dispatch qualsiasi ID di skill ricevuto da un browser diventa un proxy generico per ogni skill nel registro, comprese le skill di altri plugin e quelle che consumano il budget per i modelli di qualcun altro. La lista è una costante a livello di modulo contenente tipi di job con namespace, mai una variabile d'ambiente. Un ID non presente nella lista viene rifiutato con SKILL_NOT_ALLOWED.
  • Ricontrollare ciò che torna indietro. Quando si rilegge un job, il client dell'SDK confronta il organization_id della riga restituita con il tenant del chiamante sul proprio lato della chiamata di rete. Una barriera che esiste solo sull'altro lato di una chiamata è solo una convenzione.

Regola 3: tutta l'IA passa attraverso l'AI Provider Router

Un plugin non effettua alcuna chiamata a un modello, in nessun punto. Non c'è alcun SDK del fornitore in package.json, nessuna chiave del modello nell'ambiente e nessun relay. Solo il router detiene le credenziali del fornitore dell'organizzazione e prende la decisione finale sul fornitore e sul modello.

Ciò che un plugin può fare è esprimere preferenze, al momento della registrazione, nella riga del registro relativa alla skill del manifesto:

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

Il router rispetta una preferenza solo quando l'organizzazione ha abilitato e configurato le credenziali per quel fornitore. Altrimenti lo sostituisce attingendo dal pool dell'organizzazione stessa. capabilityProfile non seleziona mai; filtra, e il suo campo dataResidency è un vincolo giurisdizionale rigido che il router soddisfa o rifiuta. Omettere tutti questi elementi è l'impostazione predefinita corretta per la maggior parte delle skill: a decidere saranno quindi le assegnazioni di ruolo dell'organizzazione, dato che è l'organizzazione stessa a pagare.

Possono essere restituiti due tipi di rifiuto, che hanno significati molto diversi.

Codice Stato Cosa significa
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER 403 Il codice ha tentato di chiamare direttamente il router. Fermarsi: questo è il punto di giunzione che oppone un rifiuto per impostazione progettuale, e l'operazione non è ripetibile
MODEL_CAPABILITY_UNAVAILABLE 422 Nessun fornitore abilitato dispone di un modello che soddisfi il profilo. Allentare i requisiti del profilo, oppure fare in modo che l'organizzazione abiliti un fornitore idoneo
NO_PROVIDER_FOR_ROLE 422 L'organizzazione non ha configurato il routing per questo ruolo. Mostrare all'utente il testo di risoluzione fornito dal router

La seconda coppia va mostrata sullo schermo, non scritta in un log. Non esiste un modello predefinito né un fornitore di fallback: un ruolo che l'organizzazione non ha configurato genera un errore esplicito, accompagnato da una frase che indica cosa configurare.

L'unica lettura che un plugin può effettuare sul router è effectiveRoute() da runtime/ai-route. Risponde indicando quale fornitore e modello il router sceglierebbe per l'organizzazione connessa senza inviare una richiesta di IA, e restituisce il rifiuto testuale del router quando non c'è alcun modello disponibile. Il capitolo 2.22, Il runtime dei plugin, ne illustra il funzionamento.

La scala di fiducia aggiunge un ulteriore limite. Solo i plugin core e verified possono dichiarare i due livelli di skill del manifesto che raggiungono il router, tool_using e llm_only. Tutti gli altri gestiscono lavoro deterministico e lasciano alla piattaforma il compito di contattare i modelli.

Regola 4: le chiavi appartengono all'organizzazione

Ogni organizzazione utilizza il proprio account e la propria chiave del fornitore, e paga la propria fattura. La chiave risiede nel pool dei fornitori di IA dell'organizzazione, gestito dai relativi amministratori tramite la console, e il router la risolve al momento della chiamata. Non esiste una chiave di piattaforma condivisa dietro un tenant, quindi nessuna organizzazione consuma il budget di un'altra.

Per un'estensione questo significa tre cose.

  • Non si detiene mai una chiave del modello, né nel codice, né nella configurazione, né in un archivio di segreti. Il gate no-credentials blocca la build se ne rileva una leggibile, e il caricatore della configurazione rifiuta di avviarsi se ne è presente una.
  • Non si enumerano mai le chiavi di un'organizzazione. Se il plugin ritiene di doverlo fare, il requisito si trova nel posto sbagliato.
  • Un'organizzazione priva di chiave non ottiene risposte dall'IA. Questo è uno stato previsto, a cui corrisponde una schermata reale. Indicare il ruolo mancante, riportare le istruzioni di risoluzione e indirizzare l'utente alle impostazioni del fornitore. Non presentarlo come un risultato vuoto.

Regola 5: le funzionalità concesse in licenza vengono verificate rispetto alla licenza

Ciò che un'installazione può utilizzare oltre la soglia base Community proviene da un unico posto: il documento di licenza firmato da Adverant, verificato sull'installazione esclusivamente tramite chiavi pubbliche. L'estensione non prende mai decisioni basandosi su elementi più deboli, come il nome di un piano in un token o un flag nella configurazione.

In un plugin, il modo più semplice per vincolare una funzionalità alla licenza è agire sul diritto che la protegge. Un diritto nel registro rights del manifesto può specificare una funzionalità licence:

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

Chiunque chiami una route protetta da quel diritto riceve un rifiuto con LICENCE_LOCKED (403), indipendentemente dai ruoli e dalle postazioni che detiene, quando la licenza dell'organizzazione non include compliance-packs. Il rifiuto indica la funzionalità, cosa la include e chi può attivarla.

Anche lo stato della licenza è importante. Finché una licenza è valida o si trova nella finestra di avviso, le funzionalità concesse in licenza sono operative e continuano a funzionare anche durante il periodo di tolleranza (grace period), durante il quale viene mostrato l'avviso LICENCE_IN_GRACE. Una volta superato il periodo di tolleranza, la licenza applica delle restrizioni: i lavori in corso e le letture proseguono, così come le esportazioni e gli aggiornamenti di sicurezza, ma la creazione di nuovi elementi nell'ambito di una funzionalità concessa in licenza viene rifiutata con LICENCE_LOCKED. Progettare i percorsi di creazione prevedendo questa risposta.

Quando il plugin interroga il controllo delle abilitazioni per sapere se un'organizzazione dispone di una funzionalità, ottiene un verdetto, mai un semplice valore booleano. "Non raggiungibile" e "raggiungibile e no" sono fatti diversi con codici diversi: ENTITLEMENT_UNREACHABLE (502) e ENTITLEMENT_DENIED (403). Un'interruzione momentanea della raggiungibilità non deve mai declassare silenziosamente tutti i clienti alla soglia gratuita.

Manifesto e autorizzazioni
Manifesto e autorizzazioni
Manifesto e autorizzazioni confronta ciò che una release dichiara rispetto alla precedente. Qui la versione 0.4.0 aggiunge l'invio di posta e un indirizzo esterno, pertanto la release viene bloccata con MANIFEST_SCOPE_WIDENED finché due revisori e il responsabile della conformità non danno il loro consenso.

Il manifest ribadisce le regole

Ogni manifesto v2 contiene un blocco architecture con tre frasi obbligatorie, la cui formulazione esatta è vincolata dal validatore. In un plugin sviluppato per la propria installazione, le frasi recitano:

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

Queste frasi vengono sottoposte a verifica. Un plugin il cui manifesto accettasse le regole mentre il suo codice contatta direttamente un fornitore di modelli mentirebbe nel proprio contratto, e i gate esistono proprio per rendere rilevabile questa menzogna.

I controlli che applicano ogni regola

L'SDK fornisce ventidue gate di conformità riuniti in un unico comando, nexus-gates. Il capitolo 2.21, L'SDK dei plugin, li descrive uno per uno. Qui sono raggruppati in base alla regola che fanno rispettare.

Regola Gate Cosa blocca la build
Isolamento nel livello delle route scope-adherence, one-fence, rights-register, crud-adherence Una route /api priva della protezione dell'ambito, un secondo predicato del tenant scritto a mano, una route con ambito priva di diritto, una route di modifica il cui diritto non specifica nulla
Isolamento in SQL sql-fence, no-set-config Un'istruzione su una tabella con ambito priva della barriera; codice del plugin che vincola autonomamente l'impostazione del tenant
Isolamento nel database migrations-are-scoped, rls-present, db-role-honest Una tabella priva di un asse o di una chiave che inizia con il tenant, una tabella senza sicurezza a livello di riga forzata, un percorso di richiesta che si connette come proprietario o superuser
L'unico attraversamento grants-declared Una tabella concessa nelle migrazioni ma non dichiarata dal manifesto, oppure una postazione di lettura a cui sono stati assegnati privilegi manualmente
Calcolo tramite UNO no-direct-compute Una chiamata diretta a un fornitore di modelli o a un motore, oppure a una coda o a un host di workflow; un secondo componente che legge l'URL di dispatch
IA e chiavi no-credentials Una credenziale di un fornitore di modelli leggibile nel repository o nell'ambiente
Il contratto dichiarato api-contract, platform-clients, declared-input Una route registrata ma non dichiarata, o dichiarata ma non registrata; un client di piattaforma importato ma non nominato

Ogni gate dispone di un autotest che dimostra il fallimento su una fixture costruita appositamente per farlo scattare. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test li esegue tutti, e un gate che ha smesso di fallire sulla propria fixture ha smesso di funzionare.

Cosa può raggiungere un'app
Cosa può raggiungere un'app
Cosa può raggiungere un'app elenca ogni indirizzo esterno dichiarato da un'app e indica se il responsabile della conformità lo ha approvato. Una chiamata verso un indirizzo non dichiarato da nessuno viene bloccata e conteggiata prima che qualsiasi dato esca.

Prima di richiedere una revisione

Questa è la lista che scorro prima di chiedere a un collega di revisionare un plugin. Ogni riga rappresenta un aspetto che un revisore presso Corrán Orbital mi ha segnalato almeno una volta.

  1. Ogni route /api registra la protezione dell'ambito, e le uniche route anonime sono percorsi esatti dichiarati auth: public con allowAnonymous: true.
  2. Ogni route servita dalla protezione dell'ambito specifica un right dal registro del manifesto, e nessun handler contiene un controllo dei diritti proprio.
  3. Nessun handler legge un'organizzazione, una persona o un'unità dal corpo, dalla query o da un header.
  4. Ogni istruzione su una tabella con ambito passa attraverso tenantFence all'interno di withScopedTx, e nulla nel repository chiama set_config.
  5. Ogni tabella ha le colonne dei tre assi, una chiave primaria che inizia con organization_id e chiavi esterne composte che includono il tenant.
  6. L'URL di dispatch viene letto in un solo file, e l'allow-list di dispatch è una costante di tipi di job con namespace.
  7. Nulla in package.json comunica con un fornitore di modelli e nessuna chiave risiede nell'ambiente.
  8. Ogni funzionalità inclusa solo in alcune licenze specifica il proprio licence sul diritto che la protegge.
  9. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test dà esito positivo (verde), così come npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.

Se tutti e nove i punti sono rispettati, la revisione si concentra sul prodotto, che è esattamente ciò a cui un revisore dovrebbe dedicare il proprio tempo.

Perché la piattaforma applica queste regole

Ciascuna delle regole precedenti era un tempo una convenzione adottata da qualche parte, e ogni convenzione ha fallito nello stesso modo: le route che la ricordavano andavano bene, mentre quella che la dimenticava causava l'incidente. Una barriera per unità aziendale applicata come middleware opzionale è stata aggirata in sei modi indipendenti, ciascuno costituito da una route che non l'aveva mai attivata. Una variabile d'ambiente che riscriveva l'identità del tenant ha servito a un'organizzazione i 1.406 contatti di un'altra, e in fase di revisione sembrava corretta perché lo era per il pod per cui era stata scritta.

Pertanto, la piattaforma colloca il predicato laddove ogni superficie transita già obbligatoriamente: nella protezione dell'ambito e nella funzione di barriera, nel wrapper della transazione e nella sicurezza a livello di riga forzata, nonché nel client di dispatch. Un gate enumera quindi ogni route, ogni istruzione e ogni importazione, bloccando la build quando uno di questi elementi raggiunge una tabella con ambito, un modello o un motore di calcolo senza passare attraverso tali meccanismi. Il costo di questa architettura è che il primo plugin sembra soggetto a molti vincoli. Il vantaggio è che il millesimo plugin risulta isolato senza che il suo autore sappia nemmeno dell'esistenza di questa funzionalità, perché non ha alcun altro percorso possibile per raggiungere i dati.

Tutto questo ha un limite oggettivo. I gate dimostrano che il codice passa attraverso i meccanismi previsti, ma non possono dimostrare che la logica del prodotto sia corretta. Una route che limita correttamente l'ambito di una query alle righe del proprietario può comunque mostrare le righe sbagliate al proprietario giusto. Il kit di test per l'isolamento descritto nel capitolo 2.22, Il runtime dei plugin, attacca ogni route fingendosi un'altra organizzazione e un collega, rimuovendo ciascuna barriera a turno: questo è il test che eseguirei prima di fidarmi della mia stessa interpretazione di tutto quanto esposto.