Versión 1.0.0-alpha.1 más reciente
Capítulo 2.19
Las reglas que hereda toda extensión
Aislamiento en tres ejes, cómputo a través de UNO, IA (inteligencia artificial) a través del enrutador, claves propiedad de la organización y comprobaciones de licencia. Qué significa cada regla para su código y qué barrera la aplica, y por qué la hereda en lugar de programarla.
Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

El primer rechazo que envió mi complemento de revisión de anomalías fue para mí. Había escrito un cliente de prueba que enviaba una nueva revisión con el identificador de la organización en el cuerpo, por costumbre de otra plataforma, y el complemento respondió antes de que se ejecutara mi controlador:
{
"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."]
}Yo no había escrito esa comprobación. Venía con la protección de ámbito que la plantilla del SDK (kit de desarrollo de software) integra en cada ruta /api, y se activa incluso cuando el identificador del cuerpo pertenece al propio invocador. Ese es el patrón de todo este capítulo: un número reducido de reglas, cada una aplicada por un mecanismo heredado, cada una con un control que hace fallar la compilación si el código intenta eludirlo. En Nexus, su complemento hereda el aislamiento de la plataforma y los controles lo auditan.
Existen cinco reglas, y las secciones siguientes las abordan por orden: aislamiento en tres ejes; cómputo que se ejecuta únicamente mediante el despacho de UNO; IA (inteligencia artificial) que pasa exclusivamente por el enrutador de proveedores de IA (AI Provider Router); claves de modelo que pertenecen a la organización; y funciones con licencia verificadas frente a la licencia. Además, cada manifiesto reafirma tres de ellas en un bloque de frases.
Regla 1: aislamiento en tres ejes, desde la solicitud autenticada
Cada lectura y escritura en una extensión tiene su ámbito definido en tres ejes, al igual que cada llamada a herramientas y cada despacho de habilidades.
| Eje | Columna | Responde a | Firmeza del límite |
|---|---|---|---|
| Inquilino | organization_id |
Qué organización | Un límite estricto, que solo se cruza mediante una concesión de solo lectura registrada |
| Propietario | owner_user_id |
Qué persona dentro de la organización | Privado incluso dentro de una misma organización, para cualquier elemento personal |
| Unidad | business_unit_id |
Qué parte de la organización | Una barrera opcional dentro de un inquilino |
El eje del propietario es en el que suelen equivocarse los principiantes. Un buzón de correo es personal, al igual que una vista guardada o un gráfico derivado de los datos de una persona. Dos miembros de la misma organización, en la misma unidad y con el mismo rol, no ven las filas con ámbito de propietario del otro. En cambio, en un artefacto de la organización, como una aprobación o un registro de caso, el propietario indica la procedencia: registra quién actuó, y las lecturas se limitan al ámbito del inquilino para que la pista de auditoría permanezca visible para quienes la necesiten. Usted decide de qué tipo es para cada tabla, y la capa de repositorio lo codifica, sin usar nunca un caso especial en una ruta.
Los ejes provienen de la solicitud autenticada y de ningún otro lugar. Una variable de entorno no puede proporcionarlos, como tampoco pueden hacerlo un parámetro de consulta, un segmento de ruta, un encabezado de cliente ni una constante de compilación. El SDK dificulta escribir lo incorrecto: resolveScope(identity, options) no tiene ningún parámetro de organización. La organización está dentro de identity, y solo un token verificado produce uno. No hay nada a través de lo cual pasar un identificador.
Por eso se rechaza un cuerpo que indique el inquilino en lugar de ignorarlo. La protección rechaza cualquiera de estos cinco nombres de campo: orgId, organizationId, organization_id, tenant y tenantId. Un campo que se ignora en silencio hace creer al invocador que el campo funciona. El primer invocador lo prueba y ve sus propios datos; el segundo envía el identificador de otra organización. Rechazar en la primera solicitud deja claro el contrato antes de que alguien desarrolle sobre la base incorrecta. La misma regla se aplica a inputParams de un despacho: la entrada de una habilidad que contenga un identificador de organización se rechaza en el momento del despacho.
El eje de unidad o bien se declara y se aplica, o bien no se utiliza. Una ruta que declara needsUnit: true rechaza la solicitud cuando la credencial no resuelve una unidad, indicando unit en missing[]. No sintetice una unidad a partir de un subdominio o un encabezado, ni asigne una por defecto. Una unidad inventada delimita de forma diferente a las unidades reales de la organización y une filas que no debería.
Una superficie que no puede expresar el predicado lo rechaza
Si una ruta no puede determinar a qué inquilino y propietario pertenece una fila, y a qué unidad cuando la necesita, rechaza la solicitud. No existe una lectura de toda la organización como alternativa ni ningún valor de marcador de posición. Un marcador de posición es la peor opción, porque es un valor y los valores coinciden con las filas: un enrutador de herramientas que asignaba por defecto la cadena 'unknown' tanto al inquilino como al usuario acabó sirviendo datos de toda la organización a cualquiera que lo llamara. En un límite de inquilino, ?? 'unknown' es un defecto.
El rechazo tiene una única estructura en toda la plataforma y contiene información suficiente para que un cliente muestre la solución:
{
"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 es siempre true. code proviene del catálogo de códigos de la plataforma. resolved[] indica los ejes que se derivaron y missing[] los que la ruta necesitaba y no pudo obtener. troubleshooting[] indica qué lo solucionaría realmente. Un simple «prohibido» no enseña nada a nadie.
Mantenga separados los códigos 401 y 403, porque los clientes actúan de forma diferente ante ellos.
| Estado | Significado | Qué hace el cliente |
|---|---|---|
| 401 | No autenticado | Vuelve a iniciar sesión |
| 403 | Autenticado, pero no se puede determinar el ámbito de la solicitud o el invocador carece del permiso | Deja de reintentar y modifica la solicitud |
Un rechazo de ámbito respondido con un 401 envía al cliente a un bucle de inicio de sesión que ningún inicio de sesión puede resolver: descarta la sesión y vuelve a iniciarla, reintenta y vuelve a recibir un 401, mientras el usuario ve un indicador de carga indefinidamente.
Otros dos mecanismos hacen que el rechazo sea total. Dentro de un controlador, scopeOf(req) es la única forma de leer el ámbito, y lanza una excepción si la protección no se ejecutó. Además, la protección se ejecuta después de analizar el cuerpo y antes de cualquier controlador; un controlador al que se pueda llegar sin el predicado responde con un 500 y MIDDLEWARE_ORDERING_ERROR, deliberadamente, para que recaiga en su presupuesto de errores en lugar de en un informe de incidentes.
La base de datos mantiene la misma línea por sí sola
La barrera de código y la barrera de base de datos son dos mecanismos para una misma ley, y usted cuenta con ambos.
Cada sentencia contra una tabla con ámbito compone tenantFence(scope) desde el SDK; usted nunca escribe el predicado a mano. Cada sentencia también se ejecuta dentro de withScopedTx, que vincula los tres ejes para esa única transacción mediante una sola función de base de datos y rechaza una segunda vinculación (SCOPE_ALREADY_BOUND). Por debajo, cada tabla de su esquema tiene forzada la seguridad a nivel de fila, y el rol con el que se conecta su ruta de solicitud no puede cambiar por sí mismo el inquilino vinculado. Un proceso que se conecta con un rol capaz de eludir la seguridad a nivel de fila se niega a arrancar con DB_ROLE_BYPASSES_ISOLATION. El capítulo 2.22, El entorno de ejecución de complementos, muestra el código; el capítulo 2.21, El SDK de complementos, muestra cómo se generan los roles para usted.
El único cruce: una concesión registrada
Existe exactamente una forma de cruzar el límite del inquilino. La organización que posee las filas registra una concesión que indica qué organización puede leer qué tablas, bajo qué acuerdo y durante cuánto tiempo. La base de datos hace que la lectura sea de solo lectura, y cada consulta se registra antes de la lectura, en ambas organizaciones, únicamente por identificador. Las escrituras nunca cruzan; el trabajo entregado a otra empresa viaja como un mensaje. Los roles de propietario y administrador nunca leen a través del límite en absoluto, y el manifiesto se rechaza si el permiso que admite una lectura entre organizaciones no los excluye. Un complemento que busque otra forma de cruzar no la obtendrá.
Regla 2: todo el cómputo se ejecuta a través del despacho de UNO
UNO, el motor de flujos de trabajo, es la única vía de cómputo. Su código nunca consulta directamente a un proveedor de modelos ni a un motor, y tampoco a una cola ni a un host de flujos de trabajo. Usted envía un sobre al punto de conexión de despacho y recibe 202 con identificadores; el resultado llega mediante sondeo o devolución de llamada.
De esto se derivan tres hábitos, y la plantilla ya incluye los tres.
- Un único archivo posee la URL de despacho.
UNO_DISPATCH_URLse lee una sola vez en el cargador de configuración y debe ser una dirección interna del clúster. Una dirección pública se rechaza en el arranque, porque nada sale de la instalación. - Una lista blanca cerrada de lo que esta superficie puede despachar. Un backend que despache cualquier identificador de habilidad que le entregue un navegador es un proxy de propósito general para todas las habilidades del registro, incluidas las habilidades de otros complementos y las que consumen el presupuesto de modelos de terceros. La lista es una constante a nivel de módulo con tipos de trabajo con espacio de nombres, nunca una variable de entorno. Un identificador que no esté en ella se rechaza con
SKILL_NOT_ALLOWED. - Vuelva a comprobar lo que regresa. Cuando usted recupera un trabajo, el cliente del SDK compara el
organization_idde la fila devuelta con el inquilino del invocador en su lado de la llamada de red. Una barrera que solo existe al otro lado de una llamada es una simple convención.
Regla 3: toda la IA pasa por el Enrutador de Proveedores de IA
Un complemento no realiza ninguna llamada a un modelo, en ningún lugar. No hay ningún SDK de proveedor en package.json, ni clave de modelo en el entorno, ni retransmisor. Solo el enrutador posee la credencial de proveedor de la organización y toma la decisión final sobre el proveedor y el modelo.
Lo que un complemento puede hacer es expresar preferencias, en el momento del registro, en la fila de registro de la habilidad del manifiesto:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}El enrutador atiende una preferencia solo cuando la organización tiene ese proveedor habilitado y con credenciales. De lo contrario, lo sustituye a partir del grupo propio de la organización. capabilityProfile nunca selecciona; filtra, y su campo dataResidency es una restricción jurisdiccional estricta que el enrutador satisface o rechaza. Omitir todo esto es la opción por defecto correcta para la mayoría de las habilidades: las propias asignaciones de roles de la organización son las que deciden entonces, y la organización es quien paga.
Se devuelven dos tipos de rechazo, y significan cosas muy diferentes.
| Código | Estado | Qué significa |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | Su código intentó llamar al enrutador por sí mismo. Deténgase: este es el límite rechazando por diseño, y no se puede reintentar |
MODEL_CAPABILITY_UNAVAILABLE |
422 | Ningún proveedor habilitado tiene un modelo que satisfaga el perfil. Relaje el perfil, o bien la organización debe habilitar un proveedor compatible |
NO_PROVIDER_FOR_ROLE |
422 | La organización no ha configurado el enrutamiento para este rol. Muestre el texto de solución del enrutador al usuario |
El segundo par debe mostrarse en pantalla, no guardarse en un registro. No hay modelo por defecto ni proveedor de respaldo: un rol que la organización no ha configurado falla de forma explícita, con una frase que indica qué configurar.
La única lectura que un complemento puede hacer del enrutador es effectiveRoute() desde runtime/ai-route. Responde qué proveedor y modelo elegiría el enrutador para la organización que ha iniciado sesión sin enviar una solicitud de IA, y devuelve el rechazo del enrutador en palabras cuando no hay ningún modelo. El capítulo 2.22, El entorno de ejecución de complementos, lo muestra.
La escala de confianza añade una línea más. Solo los complementos core y verified pueden declarar los dos niveles de habilidad del manifiesto que llegan al enrutador, tool_using y llm_only. Todos los demás gestionan trabajo determinista y dejan que la plataforma se encargue de la parte que interactúa con el modelo.
Regla 4: las claves pertenecen a la organización
Cada organización aporta su propia cuenta y clave de proveedor, y paga su propia factura. La clave reside en el grupo de proveedores de IA de la organización, gestionado por sus propios administradores desde la consola, y el enrutador la resuelve en el momento de la llamada. No existe una clave de plataforma compartida detrás de un inquilino, por lo que ninguna organización consume el presupuesto de otra.
Para una extensión, eso significa tres cosas.
- Usted nunca posee una clave de modelo, ya sea en el código, en la configuración o en un almacén de secretos. El control
no-credentialshace fallar la compilación si alguna es legible, y el cargador de configuración se niega a arrancar si hay alguna presente. - Usted nunca enumera las claves de una organización. Si su complemento cree que necesita hacerlo, el requisito está en el lugar equivocado.
- Una organización sin clave no obtiene respuestas de IA. Ese es un estado esperado con una pantalla real. Indique el rol que falta y cite la solución; luego dirija a la persona a la configuración de su proveedor. No lo muestre como un resultado vacío.
Regla 5: las funciones con licencia se verifican frente a la licencia
Lo que una instalación puede utilizar más allá de la base Community proviene de un único lugar: el documento de licencia que firma Adverant, verificado en la instalación únicamente con claves públicas. Su extensión nunca toma decisiones a partir de nada más débil, como un nombre de plan en un token o un indicador en la configuración.
En un complemento, la forma más sencilla de vincular una función a la licencia es en el permiso que la protege. Un permiso en el registro rights del manifiesto puede indicar una función licence:
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}Quien llame a una ruta protegida por ese permiso será rechazado con LICENCE_LOCKED (403), independientemente de los roles y puestos que ocupe, cuando la licencia de la organización no incluya compliance-packs. El rechazo indica la función y qué la incluye, y especifica quién puede activarla.
El estado de la licencia también importa. Mientras una licencia es válida o se encuentra en su ventana de advertencia, las funciones con licencia operan con normalidad y siguen funcionando durante el periodo de gracia, el cual muestra el aviso LICENCE_IN_GRACE. Una vez que la licencia ha superado el periodo de gracia, aplica restricciones: el trabajo en ejecución y las lecturas continúan, al igual que las exportaciones y las actualizaciones de seguridad, pero la creación de algo nuevo bajo una función con licencia se rechaza con LICENCE_LOCKED. Diseñe sus rutas de creación esperando esa respuesta.
Cuando su complemento consulta a la verificación de derechos si una organización posee una función, obtiene un veredicto, nunca un simple valor booleano. «No accesible» y «accesible y no» son hechos distintos con códigos distintos: ENTITLEMENT_UNREACHABLE (502) y ENTITLEMENT_DENIED (403). Un fallo momentáneo de conectividad nunca debe degradar silenciosamente a todos los clientes al nivel gratuito.
MANIFEST_SCOPE_WIDENED hasta que dos revisores y el responsable de cumplimiento den su aprobación.El manifiesto reafirma la ley
Cada manifiesto v2 incluye un bloque architecture con tres frases obligatorias, y el validador fija su redacción exacta. En un complemento que usted cree para su propia instalación, dicen lo siguiente:
"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."
}Esas frases se comprueban. Un complemento cuyo manifiesto aceptara las leyes mientras su código consultara a un proveedor de modelos estaría mintiendo en su propio contrato, y los controles existen para hacer que esa mentira sea detectable.
Los controles que hacen cumplir cada regla
El SDK incluye veintidós controles de cumplimiento en un solo comando, nexus-gates. El capítulo 2.21, El SDK de complementos, describe cada uno de ellos. Aquí se agrupan según la regla que hacen cumplir.
| Regla | Controles | Qué hace fallar la compilación |
|---|---|---|
| Aislamiento en la capa de rutas | scope-adherence, one-fence, rights-register, crud-adherence |
Una ruta /api sin la protección de ámbito, un segundo predicado de inquilino escrito a mano, una ruta con ámbito sin permiso, una ruta de mutación cuyo permiso no indica nada |
| Aislamiento en SQL | sql-fence, no-set-config |
Una sentencia en una tabla con ámbito sin la barrera; código del complemento que vincula la configuración del inquilino por sí mismo |
| Aislamiento en la base de datos | migrations-are-scoped, rls-present, db-role-honest |
Una tabla a la que le falta un eje o una clave encabezada por el inquilino, una tabla sin seguridad a nivel de fila forzada, una ruta de solicitud que se conecta como propietario o superusuario |
| El único cruce | grants-declared |
Una tabla concedida en migraciones que el manifiesto no declara, o un puesto de lectura al que se han otorgado privilegios manualmente |
| Cómputo a través de UNO | no-direct-compute |
Una consulta directa a un proveedor o motor de modelos, o a una cola o host de flujos de trabajo; un segundo lector de la URL de despacho |
| IA y claves | no-credentials |
Una credencial de proveedor de modelos legible en el repositorio o en el entorno |
| El contrato declarado | api-contract, platform-clients, declared-input |
Una ruta registrada pero no declarada, o declarada pero no registrada; un cliente de plataforma importado pero no nombrado |
Cada control tiene una autoprueba que demuestra que falla ante un entorno de prueba diseñado para activarlo. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test los ejecuta todos, y un control que ha dejado de fallar ante su propio entorno de prueba ha dejado de funcionar.
Antes de solicitar una revisión
Esta es la lista que repaso antes de pedirle a un colega que revise un complemento. Cada línea es algo que un revisor en Corrán Orbital me ha devuelto al menos una vez.
- Cada ruta
/apiregistra la protección de ámbito, y las únicas rutas anónimas son rutas exactas declaradas comoauth: publicconallowAnonymous: true. - Cada ruta que atiende la protección de ámbito indica un
rightdel registro del manifiesto, y ningún controlador incluye una comprobación de permisos propia. - Ningún controlador lee una organización, una persona o una unidad desde el cuerpo, la consulta o un encabezado.
- Cada sentencia sobre una tabla con ámbito pasa por
tenantFencedentro dewithScopedTx, y nada en el repositorio llama aset_config. - Cada tabla tiene las tres columnas de eje, una clave primaria encabezada por
organization_idy claves foráneas compuestas que incluyen el inquilino. - La URL de despacho se lee en un único archivo, y la lista blanca de despacho es una constante de tipos de trabajo con espacio de nombres.
- Nada en
package.jsonse comunica con un proveedor de modelos, y no hay ninguna clave en el entorno. - Cada función que solo incluyen algunas licencias indica su
licenceen el permiso que la protege. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testestá en verde, al igual quenpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.
Si se cumplen los nueve puntos, la revisión se centra en su producto, que es a lo que debe dedicarse el tiempo de un revisor.
Por qué la plataforma hace cumplir estas reglas
Cada una de las reglas anteriores fue alguna vez una convención en algún lugar, y cada convención falló de la misma manera: las rutas que la recordaban funcionaban bien y la que la olvidaba se convertía en el incidente. Una barrera de unidad de negocio aplicada como middleware opcional fue eludida de seis formas independientes, cada una en una ruta que nunca la activó. Una variable de entorno que reescribía la identidad del inquilino sirvió a una organización los 1,406 contactos de otra, y parecía correcta en la revisión porque era correcta para el pod para el que fue escrita.
Por ello, la plataforma coloca el predicado donde todas las superficies ya pasan por él: en la protección de ámbito y la función de barrera, en el contenedor de transacciones y la seguridad a nivel de fila forzada, y en el cliente de despacho. A continuación, un control enumera cada ruta, cada sentencia y cada importación, y hace fallar la compilación cuando alguna de ellas accede a una tabla con ámbito, a un modelo o a un motor de cómputo sin pasar por esos mecanismos. El coste de ese diseño es que su primer complemento se siente restringido. El beneficio es que el complemento número mil queda aislado sin que su autor sepa siquiera que la función existe, porque no hay otro camino hacia los datos que pueda tomar.
Existe un límite honesto para todo esto. Los controles demuestran que su código pasa por los mecanismos, pero no pueden demostrar que la lógica de su producto sea correcta. Una ruta que limita correctamente una consulta a las filas del propietario aún puede mostrar las filas equivocadas al propietario correcto. El kit de pruebas de aislamiento del capítulo 2.22, El entorno de ejecución de complementos, ataca cada ruta haciéndose pasar por otra organización y por un colega, eliminando cada barrera por turno, y esa es la prueba que yo ejecutaría antes de confiar en mi propia lectura de todo esto.

