Pular para o conteúdo principal

Credenciais & segredos

O Imaginne lida com três tipos de credencial, todos sob o mesmo princípio: a credencial vive no servidor, é write-only e nunca é devolvida a um aplicativo cliente. São eles as chaves de fornecedor de modelo (BYOK), os segredos usados por skills (env-secrets) e o token de identidade da sessão do usuário. Esta página explica cada um do ponto de vista de segurança.

Princípio comum: write-only e fora do cliente​

  • Write-only. Ao cadastrar uma chave ou segredo, você fornece o valor; depois disso, a interface mostra no máximo os últimos quatro caracteres. Não há leitura do valor completo de volta.
  • Nunca chega ao cliente. O Desktop, a TUI e a extensão do VS Code não recebem chaves de fornecedor nem env-secrets. Quem usa as chaves de fornecedor é o Gateway (no servidor); quem injeta env-secrets é o Engine local, mas apenas no processo da skill que os declarou — e o valor não fica acessível à conversa.
  • Sob controle da organização. Esses recursos são administrados no console /app, não pelo usuário final.

BYOK — chaves de fornecedor por organização​

Com BYOK ("traga sua própria chave"), a organização usa as suas próprias contas de fornecedor em vez da chave compartilhada da plataforma.

A chave do fornecedor é cadastrada no console, fica no servidor e é usada ao chamar o fornecedor de modelo; o cliente nunca a vê.
A chave BYOK fica no servidor e é usada no lado do servidor; o cliente nunca a recebe.
  • Escopo: por organização, não por usuário. Um usuário com permissão sai pelo modelo pago usando a chave da organização.
  • Fornecedores: definidos pela organização entre os provedores de modelo compatíveis (veja Administração → BYOK).
  • Valor write-only: mostra só os últimos 4 dígitos após o cadastro.
  • Modelos: registrar a chave não basta — é preciso Manage models (registrar os modelos do fornecedor, com display name e max tokens), e o modelo também precisa estar no AllowedModels do perfil. Sem modelo registrado, a chamada falha com byok_no_model.
  • Operações: Health check, Rotate (substituir o valor) e Delete.
  • Sem BYOK: vale a chave compartilhada da plataforma.

Detalhes operacionais em Administração → BYOK.

Env-secrets — segredos usados por skills​

Env-secrets são segredos por organização (tokens de API de terceiros, certificados, credenciais de sistemas internos) que uma skill precisa para funcionar.

O segredo é cadastrado no console e anexado a skills; no dispatch, o Engine injeta apenas os nomes declarados em required_env no processo da skill.
O Engine injeta apenas os segredos declarados pela skill, no processo dela, sem carry-over.
  • Escopo: por organização. Nome no formato ^[A-Z][A-Z0-9_]{0,127}$, único por organização; tipo string, pem ou json.
  • Valor write-only: assim como o BYOK.
  • Injeção restrita. No dispatch de uma skill, o Engine resolve apenas os nomes declarados pela skill (required_env / env.secrets), filtra para o que ela exige e injeta no processo daquela skill.
  • Sem carry-over. Um segredo injetado em uma skill não transita para outra. Cada skill recebe somente o que declara.
  • Falta de segredo: a skill falha com missing_required_env — o administrador precisa cadastrar e anexar o segredo (Manage skills).
Princípio do menor privilégio

A injeção por nome declarado significa que uma skill só "enxerga" os segredos de que precisa. Anexar um env-secret a uma skill é uma decisão explícita do administrador.

Detalhes operacionais em Administração → Env-secrets.

Token de identidade da sessão​

O acesso ao Imaginne é só por login pelo navegador, que produz um token de sessão opaco.

  • Uma sessão, em todo lugar: o mesmo token de sessão vale nas várias interfaces do Imaginne. É por organização.
  • Nunca exibido em claro. O /whoami mostra a sua identidade sem revelar o token; e se o token aparecer no corpo de um prompt, a redação de conteúdo o substitui por um marcador.
  • Revogável. Revogar a sessão corta o acesso rapidamente — não há chaves espalhadas para recolher.
  • Sem chaves de usuário. A criação de um usuário não gera senha nem chave de API — o acesso é sempre pela sessão de login da organização.

Veja Identidade.

Rotação e exclusão​

AçãoBYOKEnv-secret
RotaçãoRotate substitui o valor; manual.Rotate substitui o valor; manual.
ExclusãoDelete.Delete — recusado com 422 enquanto o segredo estiver referenciado por alguma skill (use force=true para forçar).
Efeito da trocaO Gateway passa a usar o novo valor nas próximas chamadas.A próxima execução da skill recebe o novo valor injetado.

A trava de exclusão dos env-secrets evita que você apague um segredo do qual uma skill ainda depende sem confirmar a intenção.

Por que isso é seguro​

  • Superfície de exposição mínima no cliente: o aplicativo nunca guarda chaves de fornecedor nem env-secrets.
  • Um único segredo de usuário, revogável: o token de sessão, que não é exibido e é redigido se vazar para um prompt.
  • Menor privilégio para skills: injeção só do que é declarado, sem propagação entre skills.

Veja também​

Segurança & privacidade

O modelo de confiança completo.

Abrir →Administração → BYOK

Cadastrar chaves de fornecedor e registrar modelos.

Abrir →Administração → Env-secrets

Cadastrar segredos e anexá-los a skills.

Abrir →