Conectar (verificação na nuvem opcional)

npx -y zn-gate connect

(ou zn-gate connect se você o instalou com npm i -g zn-gate).

O zn-gate funciona por completo no seu computador, não precisa de conta e, por padrão, não envia nada. Este comando é opcional. Ele acrescenta uma só coisa: quando você ou o seu agente usam a ferramenta analyze_prompt (ou zn-gate analyze), o texto, com os segredos detectados já ocultos, também é verificado pelo classificador Galvanize 2 em usezn.com. Os hooks, a proteção de arquivos e segredos, o shield e todos os outros comandos continuam locais e nunca o usam.

O que o zn-gate connect faz

1. Só roda em um terminal em que você está digitando. Se um agente de IA o iniciou, ele se recusa.
2. Diz o que vai mudar e pede a sua confirmação.
3. Abre usezn.com/connect no seu navegador. Crie uma conta gratuita (ou entre) e crie lá uma chave de API só de análise. A página de conexão faz isso por você.
4. De volta ao terminal, cole a chave no campo oculto. O que você digita não aparece, e a chave nunca é lida da linha de comando nem de uma variável de ambiente.
5. Ele verifica a chave uma vez com https://api.usezn.com. Só a chave é enviada, como cabeçalho da requisição, a esse único endereço, por uma conexão TLS verificada.
6. Ele guarda a chave e mostra os quatro últimos caracteres para você reconhecê-la.

Quais chaves ele aceita

O connect só aceita uma chave limitada a analisar texto. Uma chave assim não pode ler o seu uso, listar, criar ou revogar outras chaves, nem usar o painel, então uma cópia vazada pouco ajuda. Uma chave de acesso total é recusada, com um aviso que aponta para a página de conexão. Uma chave que o servidor rejeita, ou que não pôde ser verificada (sem resposta, um erro), também é recusada. Em todos esses casos nada é guardado.

Onde a chave fica guardada

Só em um destes lugares, nunca em um arquivo:

• O chaveiro do seu sistema: o Chaveiro do macOS, o Gerenciador de Credenciais do Windows ou o Secret Service do Linux (GNOME Keyring, KWallet).
• O cofre do zn, quando o seu sistema não tem chaveiro e o cofre está desbloqueado (zn unlock). O cofre a criptografa.

Se nenhum dos dois estiver disponível (por exemplo, Linux sem sessão de desktop), nada é guardado e o zn-gate connect avisa. Você ainda pode definir ZN_CLOUD=1 e ZN_API_KEY no seu shell por conta própria.

O ~/.zn/config.json registra apenas que você se conectou, onde a chave está guardada e os seus quatro últimos caracteres. Ele nunca contém a chave. A verificação na nuvem só liga a partir desse registro quando a chave guardada termina nesses quatro caracteres, então um registro escrito à mão não faz nada. Uma chave guardada só é enviada a https://api.usezn.com: --url e ZN_API_URL são ignorados para ela. Se o registro existir mas a chave guardada não puder ser lida, os prompts são verificados localmente e o zn-gate avisa uma vez.

Os hooks do zn recusam os caminhos diretos para o seu agente ler a chave guardada, como comandos que pedem ao chaveiro do sistema as entradas do zn ou código que a carrega pelos módulos do zn. Os próprios comandos connect e disconnect são recusados quando um agente os executa, e o zn oculta o formato da chave (zn_ seguido de 48 caracteres) no que o agente vê.

Isso é uma barreira, não uma parede de cofre: um programa executado como você ainda pode pedir a chave ao chaveiro, como acontece com qualquer entrada do chaveiro. Por isso o connect só aceita uma chave limitada a analisar texto, e por isso você pode revogá-la a qualquer momento.

Ver e mudar o estado

• zn-gate status mostra se há uma chave conectada e de onde ela vem (ZN_API_KEY, --key, o chaveiro ou o cofre), nunca a chave. Mostra também o mecanismo de detecção e se a verificação opcional na nuvem está ligada.
• zn-gate connect --reconnect substitui a chave guardada.
• zn-gate disconnect remove a chave deste computador e desliga a verificação na nuvem.
• Uma chave em --key ou ZN_API_KEY só é usada no lugar da guardada se você também definir ZN_CLOUD=1; sem isso, a chave guardada é usada e ZN_API_KEY e ZN_API_URL são ignorados. ZN_LOCAL_ONLY=true ou --local-only desliga a verificação na nuvem mesmo com a conexão feita.

Desconectar e revogar a chave

Se houver uma chave guardada, o zn-gate disconnect pergunta se você também quer revogá-la em usezn.com, para que ela pare de funcionar em todo lugar. A resposta padrão é não, e só um sim explícito envia alguma coisa: uma requisição com a chave a https://api.usezn.com, pela mesma conexão verificada que o connect usa.

• A cópia local é removida em todos os casos, mesmo que a requisição falhe. Se falhar, o comando avisa e aponta para usezn.com/api-keys, onde você mesmo pode revogar a chave.
• zn-gate disconnect --revoke pula a pergunta, e --no-revoke nunca revoga e não faz nenhuma chamada de rede.
• Se a chave guardada não puder ser lida, nada é removido. Nesse caso, --no-revoke remove só a cópia local.
• Como o connect, o comando só roda no seu próprio terminal. Sem terminal, ou a partir de um agente de IA, ele se recusa e não muda nada, então nada é revogado.

Se algo falhar

• Ele se recusa a rodar: só roda em um terminal em que você digita. Abra o seu próprio terminal e execute lá, não por meio de um agente de IA nem de um script.
• A chave é recusada: use a página de conexão para criar uma chave só de análise e rode zn-gate connect de novo.
• Não foi possível verificar a chave (sem resposta, um erro): confira a sua conexão e tente de novo.
• Ele diz que nada foi guardado porque não há chaveiro: desbloqueie o cofre com zn unlock e rode zn-gate connect de novo, ou defina ZN_CLOUD=1 e ZN_API_KEY no seu shell por conta própria.
• Você quer parar: rode zn-gate disconnect.

O que é enviado

Só o texto das chamadas a analyze_prompt e zn-gate analyze, depois que o zn-gate remove os segredos que detecta (nesse caminho os dados pessoais não são removidos), e a chave como cabeçalho da requisição. A saída das ferramentas, os argumentos das chamadas de ferramentas e as descrições de ferramentas nunca são enviados. Veja O que sai da sua máquina.