Version 1.0.0-alpha.1dernière version
Chapitre 2.19
Les règles dont hérite chaque extension
Isolation sur trois axes, calcul via UNO, IA (intelligence artificielle) via le routeur, clés détenues par l'organisation et vérifications de licence. Ce que chaque règle implique pour votre code, quel point de contrôle l'applique, et pourquoi vous en héritez au lieu de devoir l'écrire.
Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

Le tout premier refus envoyé par mon plugin d'examen d'anomalies m'était adressé. J'avais écrit un client de test qui publiait un nouvel examen avec l'identifiant de l'organisation dans le corps de la requête, par habitude acquise sur une autre plateforme, et le plugin a répondu avant même l'exécution de mon gestionnaire :
{
"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."]
}Je n'avais pas écrit cette vérification. Elle provenait du garde de portée que le modèle du SDK (kit de développement logiciel) intègre dans chaque route /api, et elle se déclenche même lorsque l'identifiant présent dans le corps est celui de l'appelant lui-même. C'est le principe directeur de tout ce chapitre : un petit nombre de règles, chacune appliquée par un mécanisme dont vous héritez, et chacune associée à un contrôle qui fait échouer votre build si votre code tente de le contourner. Sur Nexus, votre plugin hérite son isolation de la plateforme, et les contrôles l'auditent.
Il existe cinq règles, que les sections ci-dessous abordent tour à tour : l'isolation sur trois axes ; le calcul qui s'exécute uniquement via la répartition UNO ; l'IA (intelligence artificielle) qui passe exclusivement par l'AI Provider Router ; les clés de modèle qui appartiennent à l'organisation ; et les fonctionnalités sous licence vérifiées par rapport à la licence. Chaque manifeste réaffirme également trois d'entre elles dans un même bloc de phrases.
Règle 1 : isolation sur trois axes, à partir de la requête authentifiée
Chaque lecture et écriture dans une extension a une portée définie sur trois axes, tout comme chaque appel d'outil et chaque répartition de compétence.
| Axe | Colonne | Répond à | Rigueur de la limite |
|---|---|---|---|
| Locataire (Tenant) | organization_id |
Quelle organisation | Une frontière stricte, franchie uniquement via une autorisation en lecture seule enregistrée |
| Propriétaire (Owner) | owner_user_id |
Quelle personne au sein de l'organisation | Privé même au sein d'une même organisation, pour tout ce qui est personnel |
| Unité (Unit) | business_unit_id |
Quelle partie de l'organisation | Une barrière facultative au sein d'un locataire |
L'axe du propriétaire est celui sur lequel les nouveaux venus se trompent. Une boîte aux lettres est personnelle, tout comme une vue enregistrée ou un graphe dérivé des données d'une personne. Deux membres de la même organisation, dans la même unité et avec le même rôle, ne voient pas les lignes limitées au propriétaire de l'autre. Sur un artefact d'organisation, une approbation ou un dossier par exemple, le propriétaire indique plutôt la provenance : il enregistre qui a agi, et les lectures sont limitées au locataire afin que la piste d'audit reste visible pour les personnes qui en ont besoin. Vous décidez pour chaque table de quel type il s'agit, et la couche de dépôt l'encode, sans jamais créer de cas particulier dans une route.
Les axes proviennent de la requête authentifiée et de nulle part ailleurs. Une variable d'environnement ne peut pas les fournir, pas plus qu'un paramètre de requête, un segment de chemin, un en-tête client ou une constante de build. Le SDK rend les mauvaises pratiques difficiles à écrire : resolveScope(identity, options) n'a aucun paramètre d'organisation. L'organisation se trouve à l'intérieur de identity, et seul un jeton vérifié peut en produire un. Il n'y a rien à travers quoi faire passer un identifiant.
C'est pourquoi un corps de requête nommant le locataire est refusé plutôt qu'ignoré. Le garde refuse chacun de ces cinq noms de champs : orgId, organizationId, organization_id, tenant et tenantId. Un champ ignoré silencieusement laisse croire à l'appelant que ce champ fonctionne. Le premier appelant le teste et voit ses propres données ; le second envoie l'identifiant d'une autre organisation. Refuser dès la première requête énonce clairement le contrat avant que quiconque ne s'appuie sur le mauvais. La même règle s'applique à inputParams lors d'une répartition : l'entrée d'une compétence qui contient un identifiant d'organisation est refusée à la répartition.
L'axe de l'unité est soit déclaré et appliqué, soit inutilisé. Une route qui déclare needsUnit: true refuse l'accès lorsque l'identifiant d'authentification ne résout aucune unité, en nommant unit dans missing[]. Ne synthétisez pas d'unité à partir d'un sous-domaine ou d'un en-tête, et n'en définissez pas par défaut. Une unité inventée cloisonne différemment des unités réelles de l'organisation et joint des lignes qu'elle ne devrait pas.
Une surface qui ne peut pas exprimer le prédicat oppose un refus
Si une route ne peut pas déterminer à quel locataire et à quel propriétaire appartient une ligne, ainsi qu'à quelle unité lorsqu'elle en a besoin, elle oppose un refus. Il n'y a pas de lecture à l'échelle de l'organisation en guise de repli, ni de valeur de substitution. Une valeur de substitution est la pire des options, car c'est une valeur et les valeurs correspondent à des lignes : un routeur d'outils qui définissait par défaut le locataire et l'utilisateur sur la chaîne 'unknown' a servi des données à l'échelle de l'organisation à quiconque l'appelait. Sur une frontière de locataire, ?? 'unknown' est un défaut.
Le refus a la même forme partout sur la plateforme, et il contient suffisamment d'informations pour qu'un client puisse afficher le correctif :
{
"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 vaut toujours true. code provient du catalogue de codes de la plateforme. resolved[] nomme les axes qui ont été dérivés et missing[] ceux dont la route avait besoin sans pouvoir les obtenir. troubleshooting[] indique ce qui corrigerait réellement le problème. Un simple « interdit » n'apprend rien à personne.
Distinguez bien les codes 401 et 403, car les clients y réagissent différemment.
| Statut | Signification | Ce que fait le client |
|---|---|---|
| 401 | Non authentifié | Se reconnecte |
| 403 | Authentifié, mais la portée de la requête ne peut pas être définie, ou l'appelant ne dispose pas du droit | Cesse de réessayer et modifie la requête |
Un refus de portée renvoyé sous forme de code 401 plonge le client dans une boucle de connexion qu'aucune authentification ne peut interrompre : il supprime la session et se reconnecte, réessaie et obtient à nouveau 401, pendant que l'utilisateur regarde une icône de chargement tourner indéfiniment.
Deux autres mécanismes rendent le refus total. À l'intérieur d'un gestionnaire, scopeOf(req) est le seul moyen de lire la portée, et il lève une exception si le garde ne s'est pas exécuté. De plus, le garde s'exécute après l'analyse du corps et avant tout gestionnaire ; un gestionnaire qui deviendrait accessible sans le prédicat répond 500 avec MIDDLEWARE_ORDERING_ERROR, délibérément, afin que cela atterrisse dans votre budget d'erreurs plutôt que dans un rapport d'incident.
La base de données applique la même règle de son propre chef
La barrière de code et la barrière de base de données sont deux mécanismes au service d'une seule loi, et vous bénéficiez des deux.
Chaque instruction sur une table à portée limitée compose tenantFence(scope) à partir du SDK ; vous n'écrivez jamais le prédicat à la main. Chaque instruction s'exécute également à l'intérieur de withScopedTx, qui lie les trois axes pour cette transaction unique via une seule fonction de base de données et refuse une seconde liaison (SCOPE_ALREADY_BOUND). En dessous, la sécurité au niveau des lignes est forcée sur chaque table de votre schéma, et le rôle sous lequel votre chemin de requête se connecte ne peut pas modifier lui-même le locataire lié. Un processus qui se connecte avec un rôle capable de contourner la sécurité au niveau des lignes refuse de démarrer avec DB_ROLE_BYPASSES_ISOLATION. Le chapitre 2.22, L'environnement d'exécution de plugin, montre le code ; le chapitre 2.21, Le SDK de plugin, montre comment les rôles sont générés pour vous.
L'unique franchissement : une autorisation enregistrée
Il existe exactement un seul moyen de franchir la frontière d'un locataire. L'organisation qui détient les lignes enregistre une autorisation nommant quelle organisation peut lire quelles tables, en vertu de quel accord et pour quelle durée. La base de données rend la lecture strictement en lecture seule, et chaque consultation est écrite avant la lecture, dans les deux organisations, uniquement par identifiant. Les écritures ne traversent jamais ; le travail confié à une autre entreprise voyage sous forme de message. Les rôles de propriétaire et d'administrateur ne lisent jamais au-delà de la frontière, et le manifeste est refusé si le droit qui admet une lecture inter-organisations ne les exclut pas. Un plugin qui voudrait un autre passage n'en obtiendra aucun.
Règle 2 : tout calcul s'exécute via le répartiteur UNO
UNO, le moteur de flux de travail, est le seul chemin de calcul. Votre code n'interroge jamais directement un fournisseur de modèles ou un moteur, ni une file d'attente ou un hôte de flux de travail. Vous envoyez une seule enveloppe au point de terminaison de répartition et recevez 202 avec des identifiants en retour ; le résultat arrive par interrogation (polling) ou par rappel (callback).
Trois habitudes en découlent, et le modèle les intègre déjà toutes les trois.
- Un seul fichier détient l'URL de répartition.
UNO_DISPATCH_URLest lu une seule fois dans le chargeur de configuration et doit être une adresse interne au cluster. Une adresse publique est refusée au démarrage, car rien ne quitte l'installation. - Une liste d'autorisation fermée définissant ce que cette surface peut répartir. Un backend qui répartirait n'importe quel identifiant de compétence transmis par un navigateur deviendrait un proxy universel pour toutes les compétences du registre, y compris celles d'autres plugins et celles qui consomment le budget de modèles de quelqu'un d'autre. La liste est une constante au niveau du module composée de types de tâches avec espace de noms, et jamais une variable d'environnement. Tout identifiant qui n'y figure pas est refusé avec
SKILL_NOT_ALLOWED. - Revérifiez ce qui revient. Lorsque vous relisez une tâche, le client du SDK compare le
organization_idde la ligne renvoyée avec le locataire de l'appelant de votre côté de l'appel réseau. Une barrière qui n'existe que de l'autre côté d'un appel n'est qu'une convention.
Règle 3 : toute l'IA passe par l'AI Provider Router
Un plugin n'effectue aucun appel à un modèle, où que ce soit. Il n'y a aucun SDK de fournisseur dans package.json, aucune clé de modèle dans l'environnement et aucun relais. Le routeur détient à lui seul les identifiants de fournisseur de l'organisation et prend la décision finale quant au fournisseur et au modèle.
Ce qu'un plugin peut faire, c'est exprimer des souhaits, au moment de l'enregistrement, sur la ligne de registre de la compétence du manifeste :
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}Le routeur n'honore un souhait que lorsque l'organisation a activé ce fournisseur et configuré ses identifiants. Sinon, il effectue une substitution à partir du propre pool de l'organisation. capabilityProfile ne sélectionne jamais ; il filtre, et son champ dataResidency est une contrainte juridictionnelle stricte que le routeur satisfait ou refuse. Omettre tous ces éléments est le bon choix par défaut pour la plupart des compétences : les attributions de rôles propres à l'organisation décident alors, puisque c'est l'organisation qui paie.
Deux types de refus peuvent être renvoyés, et ils ont des significations très différentes.
| Code | Statut | Ce que cela signifie |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | Votre code a tenté d'appeler le routeur lui-même. Arrêtez : c'est la jonction qui oppose un refus par conception, et l'opération ne peut pas être réessayée |
MODEL_CAPABILITY_UNAVAILABLE |
422 | Aucun fournisseur activé ne dispose d'un modèle satisfaisant au profil. Assouplissez le profil, ou demandez à l'organisation d'activer un fournisseur compatible |
NO_PROVIDER_FOR_ROLE |
422 | L'organisation n'a pas configuré le routage pour ce rôle. Affichez le texte de remédiation du routeur à l'utilisateur |
La seconde paire doit s'afficher à l'écran, et non dans un journal. Il n'y a ni modèle par défaut ni fournisseur de secours : un rôle que l'organisation n'a pas configuré échoue explicitement, avec une phrase indiquant ce qu'il faut configurer.
La seule lecture qu'un plugin peut effectuer auprès du routeur est effectiveRoute() depuis runtime/ai-route. Elle indique quel fournisseur et quel modèle le routeur choisirait pour l'organisation connectée sans envoyer de requête d'IA, et renvoie le refus formulé par le routeur lorsqu'aucun modèle n'est disponible. Le chapitre 2.22, L'environnement d'exécution de plugin, en présente le fonctionnement.
L'échelle de confiance ajoute une règle supplémentaire. Seuls les plugins core et verified peuvent déclarer les deux niveaux de compétence du manifeste qui atteignent le routeur, tool_using et llm_only. Tous les autres orchestrent des tâches déterministes et laissent la plateforme gérer la partie qui sollicite les modèles.
Règle 4 : les clés appartiennent à l'organisation
Chaque organisation apporte son propre compte fournisseur et sa propre clé, et paie sa propre facture. La clé réside dans le pool de fournisseurs d'IA de l'organisation, géré par ses propres administrateurs depuis la console, et le routeur la résout au moment de l'appel. Il n'y a pas de clé de plateforme partagée derrière un locataire, de sorte qu'aucune organisation ne dépense le budget d'une autre.
Pour une extension, cela implique trois choses.
- Vous ne détenez jamais de clé de modèle, que ce soit dans le code, dans la configuration ou dans un coffre de secrets. Le contrôle
no-credentialsfait échouer le build si une clé est lisible, et le chargeur de configuration refuse de démarrer si l'une d'elles est présente. - Vous n'énumérez jamais les clés d'une organisation. Si votre plugin pense devoir le faire, c'est que le besoin est mal placé.
- Une organisation sans clé n'obtient aucune réponse de l'IA. C'est un état attendu qui doit disposer d'un véritable écran. Nommez le rôle manquant et citez la remédiation, puis orientez la personne vers ses paramètres de fournisseur. Ne l'affichez pas comme un résultat vide.
Règle 5 : les fonctionnalités sous licence sont vérifiées par rapport à la licence
Ce qu'une installation peut utiliser au-delà du socle Community provient d'un seul endroit : le document de licence signé par Adverant, vérifié sur l'installation uniquement à l'aide de clés publiques. Votre extension ne prend jamais de décision sur la base d'un élément plus faible, tel qu'un nom de forfait dans un jeton ou un indicateur dans la configuration.
Dans un plugin, la façon la plus simple de lier une fonctionnalité à la licence consiste à l'associer au droit qui la protège. Un droit dans le registre rights du manifeste peut nommer une fonctionnalité licence :
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}Quiconque appelle une route protégée par ce droit se voit opposer un refus avec LICENCE_LOCKED (403), quels que soient ses rôles et ses sièges, lorsque la licence de l'organisation ne comporte pas compliance-packs. Le refus nomme la fonctionnalité et ce qui la contient, et indique qui peut l'activer.
L'état de la licence importe également. Tant qu'une licence est valide ou dans sa fenêtre d'avertissement, les fonctionnalités sous licence fonctionnent ; elles continuent de fonctionner pendant la période de grâce, laquelle affiche l'avis LICENCE_IN_GRACE. Une fois la période de grâce dépassée, la licence applique des restrictions : les tâches en cours et les lectures se poursuivent, tout comme les exportations et les mises à jour de sécurité, mais toute nouvelle création sous une fonctionnalité sous licence est refusée avec LICENCE_LOCKED. Construisez vos chemins de création en prévoyant cette réponse.
Lorsque votre plugin demande à la vérification des droits si une organisation détient une fonctionnalité, il obtient un verdict, et jamais un simple booléen. « Injoignable » et « joignable et non » sont deux faits différents associés à des codes différents : ENTITLEMENT_UNREACHABLE (502) et ENTITLEMENT_DENIED (403). Une micro-coupure d'accessibilité ne doit jamais rétrograder silencieusement tous les clients vers le socle gratuit.
MANIFEST_SCOPE_WIDENED jusqu'à ce que deux réviseurs et le responsable de la conformité donnent leur accord.Le manifeste réaffirme la règle
Chaque manifeste v2 comporte un bloc architecture contenant trois phrases obligatoires, dont le validateur exige la formulation exacte. Dans un plugin que vous développez pour votre propre installation, elles se lisent comme suit :
"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."
}Ces phrases sont vérifiées. Un plugin dont le manifeste accepterait ces lois alors que son code interrogerait directement un fournisseur de modèles mentirait dans son propre contrat, et les contrôles existent pour rendre ce mensonge détectable.
Les portes de contrôle qui appliquent chaque règle
Le SDK fournit vingt-deux contrôles de conformité réunis en une seule commande, nexus-gates. Le chapitre 2.21, Le SDK de plugin, décrit chacun d'eux. Ils sont regroupés ici selon la règle qu'ils font respecter.
| Règle | Contrôles | Ce qui fait échouer le build |
|---|---|---|
| Isolation dans la couche de routage | scope-adherence, one-fence, rights-register, crud-adherence |
Une route /api sans le garde de portée, un second prédicat de locataire écrit à la main, une route à portée définie sans droit associé, une route de modification dont le droit ne nomme rien |
| Isolation en SQL | sql-fence, no-set-config |
Une instruction sur une table à portée limitée sans la barrière ; du code de plugin liant lui-même le paramètre de locataire |
| Isolation dans la base de données | migrations-are-scoped, rls-present, db-role-honest |
Une table à laquelle il manque un axe ou une clé commençant par le locataire, une table sans sécurité au niveau des lignes forcée, un chemin de requête se connectant en tant que propriétaire ou superutilisateur |
| Le passage unique | grants-declared |
Une table autorisée dans les migrations mais que le manifeste ne déclare pas, ou un siège de lecture auquel des privilèges ont été attribués manuellement |
| Calcul via UNO | no-direct-compute |
Un appel direct à un fournisseur de modèles ou à un moteur, ou à une file d'attente ou un hôte de flux de travail ; un second lecteur de l'URL de répartition |
| IA et clés | no-credentials |
Un identifiant de fournisseur de modèles lisible dans le dépôt ou dans l'environnement |
| Le contrat déclaré | api-contract, platform-clients, declared-input |
Une route enregistrée mais non déclarée, ou déclarée mais non enregistrée ; un client de plateforme importé mais non nommé |
Chaque contrôle dispose d'un autotest prouvant qu'il échoue sur un jeu d'essai conçu pour le déclencher. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test les exécute tous, et un contrôle qui a cessé d'échouer sur son propre jeu d'essai a cessé de fonctionner.
Avant de demander une révision
Voici la liste que je parcours avant de demander à un collègue de réviser un plugin. Chaque ligne correspond à un point qu'un réviseur chez Corrán Orbital m'a renvoyé au moins une fois.
- Chaque route
/apienregistre le garde de portée, et les seules routes anonymes sont des chemins exacts déclarésauth: publicavecallowAnonymous: true. - Chaque route servie par le garde de portée nomme un
rightissu du registre du manifeste, et aucun gestionnaire ne comporte sa propre vérification des droits. - Aucun gestionnaire ne lit une organisation, une personne ou une unité à partir du corps, de la requête ou d'un en-tête.
- Chaque instruction sur une table à portée limitée passe par
tenantFenceà l'intérieur dewithScopedTx, et rien dans le dépôt n'appelleset_config. - Chaque table possède les trois colonnes d'axe, une clé primaire commençant par
organization_idet des clés étrangères composites qui transportent le locataire. - L'URL de répartition est lue dans un seul fichier, et la liste d'autorisation de répartition est une constante composée de types de tâches avec espace de noms.
- Rien dans
package.jsonne communique avec un fournisseur de modèles, et aucune clé ne se trouve dans l'environnement. - Chaque fonctionnalité réservée à certaines licences nomme son
licencesur le droit qui la protège. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testest au vert, tout commenpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.
Si ces neuf points sont respectés, la révision portera sur votre produit, qui est précisément ce à quoi un réviseur devrait consacrer son temps.
Pourquoi la plateforme impose ces règles
Chacune des règles ci-dessus n'était autrefois qu'une convention quelque part, et chaque convention a échoué de la même manière : les routes qui s'en souvenaient fonctionnaient bien, et celle qui l'oubliait provoquait l'incident. Une barrière d'unité opérationnelle appliquée sous forme de middleware facultatif a été contournée de six façons indépendantes, chacune étant une route qui ne l'avait jamais activée. Une variable d'environnement réécrivant l'identité du locataire a servi à une organisation les 1 406 contacts d'une autre, et cela semblait correct lors de la révision car c'était exact pour le pod pour lequel elle avait été écrite.
C'est pourquoi la plateforme place le prédicat là où chaque surface passe déjà obligatoirement : dans le garde de portée et la fonction de barrière, dans l'enveloppe de transaction et la sécurité au niveau des lignes forcée, ainsi que dans le client de répartition. Un contrôle énumère ensuite chaque route, chaque instruction et chaque importation, et fait échouer le build lorsque l'une d'elles accède à une table à portée limitée, à un modèle ou à un moteur de calcul sans passer par ces mécanismes. Le coût de cette conception est que votre premier plugin semble contraint. Le bénéfice est que le millième plugin est isolé sans même que son auteur ne soupçonne l'existence de cette fonctionnalité, car il n'existe aucun autre chemin d'accès aux données qu'il puisse emprunter.
Il y a toutefois une limite honnête à tout cela. Les contrôles prouvent que votre code passe par les mécanismes ; ils ne peuvent pas prouver que votre logique produit est exacte. Une route qui limite correctement une requête aux lignes du propriétaire peut malgré tout afficher les mauvaises lignes au bon propriétaire. Le kit de test d'isolation présenté au chapitre 2.22, L'environnement d'exécution de plugin, attaque chaque route en tant qu'autre organisation et en tant que collègue, en retirant chaque barrière tour à tour, et c'est le test que j'exécuterais avant de me fier à ma propre lecture de tout ceci.

