Versão 1.0.0-alpha.1mais recente
Capítulo 2.19
As regras que cada extensão herda
Isolamento em três eixos, computação através do UNO, IA (inteligência artificial) através do encaminhador, chaves detidas pela organização e verificações de licença. O que cada regra significa para o seu código e que controlo a aplica, e porque é que a herda em vez de a escrever.
Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

A primeira recusa que o meu plugin de revisão de anomalias alguma vez enviou foi para mim. Eu tinha escrito um cliente de teste que publicava uma nova revisão com o id da organização no corpo do pedido, por hábito de outra plataforma, e o plugin respondeu antes de o meu processador ser executado:
{
"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."]
}Eu não tinha escrito essa verificação. Ela veio com a guarda de âmbito que o modelo do SDK (kit de desenvolvimento de software) liga a cada rota /api, e dispara mesmo quando o id no corpo é o do próprio autor da chamada. Esse é o padrão para todo este capítulo: um pequeno número de regras, cada uma imposta por um mecanismo que herda, cada uma com uma barreira de controlo que faz falhar a compilação se o seu código a contornar. No Nexus, o seu plugin herda o isolamento da plataforma, e as barreiras de controlo auditam-no.
Existem cinco regras, e as secções abaixo abordam-nas por ordem: isolamento em três eixos; computação que corre apenas através da expedição UNO; IA (inteligência artificial) que passa apenas pelo AI Provider Router; chaves de modelo que pertencem à organização; e funcionalidades licenciadas verificadas contra a licença. Cada manifesto também reafirma três delas num único bloco de frases.
Regra 1: isolamento em três eixos, a partir do pedido autenticado
Cada leitura e escrita numa extensão tem o seu âmbito definido em três eixos, assim como cada chamada de ferramenta e expedição de competência.
| Eixo | Coluna | Responde a | Quão rígida é a linha |
|---|---|---|---|
| Inquilino | organization_id |
Qual organização | Uma fronteira rígida, transposta apenas através de uma concessão só de leitura registada |
| Proprietário | owner_user_id |
Qual pessoa dentro da organização | Privado mesmo dentro de uma organização, para tudo o que seja pessoal |
| Unidade | business_unit_id |
Qual parte da organização | Uma barreira opcional dentro de um inquilino |
O eixo do proprietário é aquele em que os recém-chegados se enganam. Uma caixa de correio é pessoal, tal como uma vista guardada ou um gráfico derivado dos dados de uma pessoa. Dois membros da mesma organização, na mesma unidade e com a mesma função, não veem as linhas de âmbito de proprietário um do outro. Num artefacto da organização, uma aprovação ou um registo de caso, por exemplo, o proprietário é antes a proveniência: regista quem agiu, e as leituras são delimitadas ao inquilino para que o registo de auditoria permaneça visível para as pessoas que precisam dele. Decide por tabela de que tipo se trata, e a camada de repositório codifica-o, nunca como um caso especial numa rota.
Os eixos provêm do pedido autenticado e de mais nenhum lugar. Uma variável de ambiente não os pode fornecer, nem um parâmetro de consulta, um segmento de caminho, um cabeçalho de cliente ou uma constante de compilação. O SDK torna difícil escrever a coisa errada: resolveScope(identity, options) não tem qualquer parâmetro de organização. A organização está dentro de identity, e apenas um token verificado produz um. Não há nada por onde passar um id.
É por isso que um corpo que nomeie o inquilino é recusado em vez de ignorado. A guarda recusa qualquer um de cinco nomes de campos: orgId, organizationId, organization_id, tenant e tenantId. Um campo ignorado silenciosamente ensina ao autor da chamada que o campo funciona. O primeiro autor testa-o e vê os seus próprios dados; o segundo envia o id de uma organização diferente. Recusar no primeiro pedido estabelece o contrato antes que alguém construa sobre o contrato errado. A mesma regra aplica-se ao inputParams de uma expedição: a entrada de uma competência que transporte um id de organização é recusada na expedição.
O eixo da unidade ou é declarado e imposto ou não é utilizado. Uma rota que declara needsUnit: true recusa quando a credencial não resolve uma unidade, com unit nomeado em missing[]. Não sintetize uma unidade a partir de um subdomínio ou de um cabeçalho, e não defina uma por predefinição. Uma unidade inventada delimita de forma diferente das unidades reais da organização, e junta linhas que não deveria.
Uma superfície que não consegue expressar o predicado recusa
Se uma rota não puder indicar a que inquilino e proprietário pertence uma linha, e a que unidade quando necessita de uma, ela recusa. Não existe leitura a nível de toda a organização como recurso alternativo nem valor de marcador de posição. Um marcador de posição é a pior opção, porque um marcador de posição é um valor e os valores correspondem a linhas: um encaminhador de ferramentas que predefiniu tanto o inquilino como o utilizador para a cadeia 'unknown' serviu dados de toda a organização a quem quer que o chamasse. Numa fronteira de inquilino, ?? 'unknown' é um defeito.
A recusa tem uma única forma em toda a plataforma, e transporta informação suficiente para um cliente apresentar a correção:
{
"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 provém do catálogo de códigos da plataforma. resolved[] nomeia os eixos que foram derivados e missing[] os que a rota precisava e não conseguiu obter. troubleshooting[] indica o que realmente resolveria o problema. Um simples "forbidden" não ensina nada a ninguém.
Mantenha 401 e 403 separados, porque os clientes reagem a eles de forma diferente.
| Estado | Significado | O que o cliente faz |
|---|---|---|
| 401 | Não autenticado | Inicia sessão novamente |
| 403 | Autenticado, mas o âmbito do pedido não pode ser definido, ou o autor da chamada não tem o direito | Para de tentar novamente e altera o pedido |
Uma recusa de âmbito respondida como 401 envia o cliente para um ciclo de início de sessão que nenhum início de sessão consegue terminar: descarta a sessão e inicia sessão novamente, tenta outra vez e recebe 401 novamente, enquanto a pessoa observa um ícone de carregamento indefinidamente.
Mais dois mecanismos tornam a recusa total. Dentro de um processador, scopeOf(req) é a única forma de ler o âmbito, e lança uma exceção se a guarda não tiver sido executada. E a guarda é executada após a análise do corpo e antes de qualquer processador; um processador que se torne alcançável sem o predicado responde 500 com MIDDLEWARE_ORDERING_ERROR, deliberadamente, para que recaia no seu orçamento de erros em vez de num relatório de incidente.
A base de dados mantém a mesma linha por si só
A barreira de código e a barreira da base de dados são dois mecanismos para uma única lei, e obtém ambos.
Cada instrução contra uma tabela com âmbito definido compõe tenantFence(scope) a partir do SDK; nunca escreve o predicado manualmente. Cada instrução também corre dentro de withScopedTx, que vincula os três eixos para essa única transação através de uma única função da base de dados e recusa uma segunda vinculação (SCOPE_ALREADY_BOUND). Subjacente a isto, cada tabela no seu esquema tem a segurança ao nível da linha forçada, e a função com a qual o seu caminho de pedido se liga não pode alterar o próprio inquilino vinculado. Um processo que se ligue com uma função capaz de contornar a segurança ao nível da linha recusa arrancar com DB_ROLE_BYPASSES_ISOLATION. O Capítulo 2.22, O tempo de execução do plugin, mostra o código; o capítulo 2.21, O SDK de Plugins, mostra como as funções são geradas para si.
A única passagem: uma concessão registada
Existe exatamente uma forma de atravessar a fronteira do inquilino. A organização que detém as linhas regista uma concessão nomeando qual organização pode ler quais tabelas, sob qual acordo e por quanto tempo. A base de dados torna a leitura só de leitura, e cada consulta é registada antes da leitura, em ambas as organizações, apenas por id. As escritas nunca atravessam; o trabalho entregue a outra empresa viaja como uma mensagem. As funções de proprietário e administrador nunca leem através da fronteira de todo, e o manifesto é recusado se o direito que admite uma leitura entre organizações não os impedir. Um plugin que queira outra forma de atravessar não a obtém.
Regra 2: toda a computação é executada através do despacho UNO
O UNO, o motor de fluxo de trabalho, é o único caminho de computação. O seu código nunca acede diretamente a um fornecedor de modelos ou a um motor, nem tampouco a uma fila ou a um anfitrião de fluxo de trabalho. Envia um envelope para o endpoint de expedição e recebe 202 com identificadores de volta; o resultado chega por consulta periódica (polling) ou por retorno de chamada (callback).
Seguem-se três hábitos, e o modelo já tem os três.
- Um ficheiro detém o URL de expedição.
UNO_DISPATCH_URLé lido uma vez no carregador de configuração e deve ser um endereço interno do cluster. Um endereço público é recusado no arranque, porque nada sai da instalação. - Uma lista de permissões fechada do que esta superfície pode expedir. Um backend que expeça qualquer id de competência que um navegador lhe entregue é um proxy de uso geral para todas as competências no registo, incluindo competências de outros plugins e competências que gastam o orçamento de modelos de terceiros. A lista é uma constante ao nível do módulo de tipos de trabalhos com espaço de nomes, nunca uma variável de ambiente. Um id que não conste nela é recusado com
SKILL_NOT_ALLOWED. - Verifique novamente o que regressa. Quando lê um trabalho de volta, o cliente do SDK compara o
organization_idda linha devolvida com o inquilino do autor da chamada do seu lado da chamada de rede. Uma barreira que só existe do outro lado de uma chamada é uma convenção.
Regra 3: toda a IA passa pelo AI Provider Router
Um plugin não faz qualquer chamada a um modelo, em parte alguma. Não existe SDK de fornecedor em package.json, nem chave de modelo no ambiente, nem retransmissor. Apenas o encaminhador detém a credencial do fornecedor da organização e toma a decisão final sobre o fornecedor e o modelo.
O que um plugin pode fazer é expressar preferências, no momento do registo, na linha de registo da competência do manifesto:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}O encaminhador honra uma preferência apenas quando a organização tem esse fornecedor ativado e credenciado. Caso contrário, substitui-o a partir do conjunto próprio da organização. capabilityProfile nunca seleciona; filtra, e o seu campo dataResidency é uma restrição jurisdicional rígida que o encaminhador satisfaz ou recusa. Omitir tudo isto é a predefinição correta para a maioria das competências: as próprias atribuições de função da organização decidem então, sendo a organização quem paga.
Dois tipos de recusa regressam, e significam coisas muito diferentes.
| Código | Estado | O que significa |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | O seu código tentou chamar o próprio encaminhador. Pare: esta é a junção a recusar por conceção, e não pode ser tentada novamente |
MODEL_CAPABILITY_UNAVAILABLE |
422 | Nenhum fornecedor ativado tem um modelo que satisfaça o perfil. Relaxe o perfil, ou a organização ativa um fornecedor capaz |
NO_PROVIDER_FOR_ROLE |
422 | A organização não configurou o encaminhamento para esta função. Mostre o texto de resolução do encaminhador à pessoa |
O segundo par pertence ao ecrã, não a um registo (log). Não existe modelo predefinido nem fornecedor de recurso: uma função que a organização não tenha configurado falha de forma explícita, com uma frase a indicar o que configurar.
A única leitura que um plugin pode fazer ao encaminhador é effectiveRoute() a partir de runtime/ai-route. Responde qual o fornecedor e modelo que o encaminhador escolheria para a organização com sessão iniciada sem enviar um pedido de IA, e devolve a recusa do encaminhador por palavras quando não há modelo. O Capítulo 2.22, O tempo de execução do plugin, mostra-o.
A escada de confiança adiciona mais uma linha. Apenas plugins core e verified podem declarar os dois níveis de competência do manifesto que chegam ao encaminhador, tool_using e llm_only. Todos os outros intermedeiam trabalho determinístico e deixam a plataforma fazer a parte que acede ao modelo.
Regra 4: as chaves pertencem à organização
Cada organização traz a sua própria conta e chave de fornecedor, e paga a sua própria fatura. A chave reside no conjunto de fornecedores de IA da organização, gerido pelos seus próprios administradores a partir da consola, e o encaminhador resolve-a no momento da chamada. Não existe uma chave de plataforma partilhada por trás de um inquilino, pelo que nenhuma organização gasta o orçamento de outra.
Para uma extensão, isso significa três coisas.
- Nunca detém uma chave de modelo, seja em código, configuração ou num armazenamento de segredos. A barreira de controlo
no-credentialsfaz falhar a compilação se uma chave for legível, e o carregador de configuração recusa arrancar se uma estiver presente. - Nunca enumera as chaves de uma organização. Se o seu plugin acha que precisa de o fazer, o requisito está no lugar errado.
- Uma organização sem chave não obtém respostas de IA. Esse é um estado esperado com um ecrã real. Nomeie a função em falta e cite a resolução, depois encaminhe a pessoa para as suas definições de fornecedor. Não o apresente como um resultado vazio.
Regra 5: as funcionalidades licenciadas são verificadas face à licença
O que uma instalação pode utilizar além do patamar base Community provém de um único lugar: o documento de licença que a Adverant assina, verificado na instalação apenas com chaves públicas. A sua extensão nunca decide com base em algo mais fraco, como um nome de plano num token ou um indicador na configuração.
Num plugin, a forma mais simples de associar uma funcionalidade à licença é no direito que a protege. Um direito no registo rights do manifesto pode nomear uma funcionalidade licence:
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}Quem chamar uma rota protegida por esse direito é recusado com LICENCE_LOCKED (403), independentemente das funções e lugares que detenha, quando a licença da organização não inclui compliance-packs. A recusa nomeia a funcionalidade e o que a inclui, e indica quem a pode ativar.
O estado da licença também importa. Enquanto uma licença for válida ou estiver na sua janela de aviso, as funcionalidades licenciadas funcionam, e continuam a funcionar no período de tolerância, sendo que o período de tolerância mostra o aviso LICENCE_IN_GRACE. Assim que uma licença ultrapassa o período de tolerância, aplica restrições: o trabalho em execução e as leituras continuam, tal como as exportações e as atualizações de segurança, mas a criação de algo novo sob uma funcionalidade licenciada é recusada com LICENCE_LOCKED. Construa os seus caminhos de criação a contar com essa resposta.
Quando o seu plugin pergunta à verificação de direitos se uma organização detém uma funcionalidade, obtém um veredito, nunca um simples booleano. "Inalcançável" e "alcançável e não" são factos diferentes com códigos diferentes: ENTITLEMENT_UNREACHABLE (502) e ENTITLEMENT_DENIED (403). Uma falha momentânea de conectividade nunca deve despromover silenciosamente todos os clientes para o patamar gratuito.
MANIFEST_SCOPE_WIDENED até que dois revisores e o responsável pela conformidade concordem.O manifesto reafirma a lei
Cada manifesto v2 inclui um bloco architecture com três frases obrigatórias, e o validador fixa a sua redação. Num plugin que construa para a sua própria instalação, elas leem-se:
"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."
}Essas frases são verificadas. Um plugin cujo manifesto concordasse com as leis enquanto o seu código acedia diretamente a um fornecedor de modelos estaria a mentir no seu próprio contrato, e as barreiras de controlo existem para tornar a mentira detetável.
As barreiras de controlo que aplicam cada regra
O SDK inclui vinte e duas barreiras de controlo de conformidade num único comando, nexus-gates. O Capítulo 2.21, O SDK de Plugins, descreve cada uma delas. Aqui estão agrupadas pela regra que mantêm.
| Regra | Barreiras de controlo | O que faz falhar a compilação |
|---|---|---|
| Isolamento na camada de rota | scope-adherence, one-fence, rights-register, crud-adherence |
Uma rota /api sem a guarda de âmbito, um segundo predicado de inquilino escrito manualmente, uma rota de âmbito sem direito, uma rota de mutação cujo direito não nomeia nada |
| Isolamento em SQL | sql-fence, no-set-config |
Uma instrução numa tabela com âmbito definido sem a barreira; código do plugin a vincular a própria definição de inquilino |
| Isolamento na base de dados | migrations-are-scoped, rls-present, db-role-honest |
Uma tabela sem um eixo ou sem uma chave iniciada pelo inquilino, uma tabela sem segurança ao nível da linha forçada, um caminho de pedido a ligar-se como proprietário ou superutilizador |
| A única travessia | grants-declared |
Uma tabela concedida em migrações que o manifesto não declara, ou um lugar de leitura ao qual foram atribuídos privilégios manualmente |
| Computação através do UNO | no-direct-compute |
Um acesso direto a um fornecedor de modelos ou motor, ou a uma fila ou anfitrião de fluxo de trabalho; um segundo leitor do URL de expedição |
| IA e chaves | no-credentials |
Uma credencial de fornecedor de modelos legível no repositório ou no ambiente |
| O contrato declarado | api-contract, platform-clients, declared-input |
Uma rota registada mas não declarada, ou declarada mas não registada; um cliente da plataforma importado mas não nomeado |
Cada barreira de controlo tem um autoteste que prova que falha num cenário de teste construído para a acionar. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test executa-os a todos, e uma barreira de controlo que tenha deixado de falhar no seu próprio cenário de teste deixou de funcionar.
Antes de pedir uma revisão
Esta é a lista que percorro antes de pedir a um colega para rever um plugin. Cada linha é algo que um revisor na Corrán Orbital me devolveu pelo menos uma vez.
- Cada rota
/apiregista a guarda de âmbito, e as únicas rotas anónimas são caminhos exatos declaradosauth: publiccomallowAnonymous: true. - Cada rota que a guarda de âmbito serve nomeia um
rightdo registo do manifesto, e nenhum processador contém uma verificação de direitos própria. - Nenhum processador lê uma organização, uma pessoa ou uma unidade a partir do corpo, da consulta ou de um cabeçalho.
- Cada instrução numa tabela com âmbito definido passa por
tenantFencedentro dewithScopedTx, e nada no repositório chamaset_config. - Cada tabela tem as três colunas de eixo, uma chave primária que começa com
organization_ide chaves estrangeiras compostas que transportam o inquilino. - O URL de expedição é lido num único ficheiro, e a lista de permissões de expedição é uma constante de tipos de trabalhos com espaço de nomes.
- Nada em
package.jsoncomunica com um fornecedor de modelos, e nenhuma chave reside no ambiente. - Cada funcionalidade que apenas algumas licenças incluem nomeia o seu
licenceno direito que a protege. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testestá verde, assim comonpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json.
Se todas as nove se verificarem, a revisão será sobre o seu produto, que é onde o tempo de um revisor deve ser investido.
Por que razão a plataforma aplica estas regras
Cada regra acima foi em tempos uma convenção algures, e cada convenção falhou da mesma maneira: as rotas que se lembraram dela estavam bem e a que se esqueceu foi o incidente. Uma barreira de unidade de negócio aplicada como middleware opcional foi contornada de seis formas independentes, cada uma delas uma rota que nunca aderiu. Uma variável de ambiente que reescrevia a identidade do inquilino serviu a uma organização 1406 contactos de outra, e parecia correta na revisão porque estava correta para o pod para o qual foi escrita.
Por isso, a plataforma coloca o predicado onde todas as superfícies já passam por ele: na guarda de âmbito e na função de barreira, no invólucro de transação e na segurança ao nível da linha forçada, e no cliente de expedição. Uma barreira de controlo enumera então cada rota, cada instrução e cada importação, e faz falhar a compilação quando uma delas acede a uma tabela com âmbito definido, a um modelo ou a um motor de computação sem passar por esses mecanismos. O custo dessa conceção é que o seu primeiro plugin parece restringido. O retorno é que o milésimo plugin fica isolado sem que o seu autor saiba que a funcionalidade existe, porque não há outro caminho para os dados que ele possa tomar.
Há um limite honesto para tudo isto. As barreiras de controlo provam que o seu código passa pelos mecanismos; não podem provar que a lógica do seu produto está correta. Uma rota que delimita corretamente uma consulta às linhas do proprietário ainda pode mostrar as linhas erradas ao proprietário certo. O kit de testes de isolamento no capítulo 2.22, O tempo de execução do plugin, ataca cada rota como outra organização e como um colega, com cada barreira removida à vez, e esse é o teste que eu executaria antes de confiar na minha própria leitura de qualquer parte disto.

