Iniciar sessãoAgendar apresentação

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

15 minutos de leitura

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_id da 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-credentials faz 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.

Manifesto e permissões
Manifesto e permissões
Manifesto e permissões compara o que uma versão declara com a anterior. Aqui, a versão 0.4.0 adiciona o envio de correio e um endereço externo, pelo que a versão fica retida com 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.

O que uma aplicação pode alcançar
O que uma aplicação pode alcançar
O que uma aplicação pode alcançar lista todos os endereços externos que uma aplicação declarou e se o responsável pela conformidade os aprovou. Uma chamada para um endereço que ninguém declarou é interrompida e contabilizada antes que algo saia.

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.

  1. Cada rota /api regista a guarda de âmbito, e as únicas rotas anónimas são caminhos exatos declarados auth: public com allowAnonymous: true.
  2. Cada rota que a guarda de âmbito serve nomeia um right do registo do manifesto, e nenhum processador contém uma verificação de direitos própria.
  3. Nenhum processador lê uma organização, uma pessoa ou uma unidade a partir do corpo, da consulta ou de um cabeçalho.
  4. Cada instrução numa tabela com âmbito definido passa por tenantFence dentro de withScopedTx, e nada no repositório chama set_config.
  5. Cada tabela tem as três colunas de eixo, uma chave primária que começa com organization_id e chaves estrangeiras compostas que transportam o inquilino.
  6. 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.
  7. Nada em package.json comunica com um fornecedor de modelos, e nenhuma chave reside no ambiente.
  8. Cada funcionalidade que apenas algumas licenças incluem nomeia o seu licence no direito que a protege.
  9. npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test está verde, assim como npx -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.