Começar · SKILL.md
Sobre este documento
- Identificador
- eve-access-integration
- Descrição
- Integra um agente eve ao Access com Better Auth, login pelo navegador, autenticação HTTP ou vínculo de canais externos e autorização por papéis nas ferramentas. Use ao implementar ou revisar essa integração em um projeto de agente, não para administrar usuários nem para orientar o agente de negócio em execução.
Integrar eve com Access#
Esta skill é para o agente implementador, com acesso ao código do projeto eve. Você não tem acesso ao código do Access: use somente o contrato HTTP, os exemplos e os testes deste kit. Não adivinhe nem chame outros endpoints. Não coloque esta skill como única proteção no prompt do agente de negócio.
1. Inspecione antes de implementar#
- Identifique a versão instalada de
eve, o diretório do agente, seu canal, ferramentas, login, armazenamento de sessões e proteção de rotas existentes. - Prefira
node_modules/eve/docs/, que acompanha a versão instalada. A documentação em eve.dev pode ser de uma versão diferente. - Leia o guia para o contrato Access, fluxo completo, integração do canal, armazenamento da credencial e isolamento de sessões.
- Obtenha
ACCESS_BASE_URLda configuração do operador. É a URL raiz deste Access, em HTTPS, sem/api/v1/identity. Não invente um domínio de produção. O operador encontraACCESS_ORGANIZATION_IDna tela Integração do Access e os slugs na tela Papéis. Se algum valor faltar, pergunte; não invente. - Exija
ACCESS_ORGANIZATION_IDconfigurado pelo operador. Transporte-o no parâmetro obrigatórioorganizationIdna identidade HTTP e confira o mesmo valor na resposta antes de cada efeito. Em canais, a chave determina o tenant; o cliente ainda confere o tenant esperado. Workspace do provedor não é organização Access. - Identifique os slugs reais dos papéis e a política de cada ferramenta. Se
faltarem, peça ao responsável. Não transforme o papel chamado
adminem privilégio do console nem acrescente regras de negócio ao Access.
2. Implemente o transporte da sessão#
Escolha pelo canal: para WhatsApp, Telegram, Slack e outros provedores, leia canais externos antes de implementar. O Access já oferece criação de links, confirmação, vínculos e consulta por integração. Nesse fluxo a credencial do usuário fica no Access; o adaptador usa uma chave própria de servidor e recebe só identidade/papéis. Não a confunda com o token de usuário usado no fluxo HTTP abaixo. Valide o webhook oficial e isole tenants.
Login pelo chat (login interativo do eve 1.0+, em qualquer canal): quando
uma ferramenta precisa da identidade e a pessoa ainda não entrou, o eve envia
na própria conversa, em privado, um pedido para entrar no Access e continua o
turno quando o navegador volta ao callbackUrl dele. Use
o provedor do kit com o modo redirect descrito
em o login pelo navegador.
O token fica num AccessGrantStore do servidor, nunca no modelo.
Login pelo navegador (recomendado no canal HTTP, em apps web e CLIs): quando o canal responder 401, o servidor do agente pede um login ao Access com a chave da integração, mostra o link à pessoa e, depois que ela entra no Access e confirma, recebe um token de sessão próprio, restrito à identidade desta organização. A senha não passa pelo agente. Leia o login pelo navegador; o token resultante segue exatamente o mesmo caminho descrito abaixo (cofre, Bearer, ponte eve).
Login por senha (alternativa): o backend do aplicativo autentica o usuário
no próprio Access com signInToAccess de o cliente. Ele chama
POST /api/auth/sign-in/email com Origin igual à origem de ACCESS_BASE_URL
(sem isso o fetch do Node recebe 403 MISSING_OR_NULL_ORIGIN) e devolve o
token do cabeçalho set-auth-token. Esse token opaco assinado não é JWT e não
é o campo token do JSON, que não funciona como Bearer.
Uma conta recém-criada não pertence a nenhuma organização: a identidade responde
403 até um administrador do Access incluir o e-mail dela. Trate como falta de
acesso, com uma mensagem que oriente a pedir a inclusão.
Guarde-o no armazenamento seguro de credenciais do servidor. Vincule-o ao
usuário e ao ambiente; use TTL e remoção ao sair. O navegador pode usar uma
sessão HttpOnly do aplicativo. Não coloque o token em mensagens, argumentos de
ferramentas, clientContext, estado durável do eve, atributos de identidade,
logs, URLs, sandbox ou localStorage. Nunca use uma sessão administrativa
compartilhada por todos.
O cookie do painel Access não cria automaticamente uma sessão em outro domínio. Uma sessão Better Auth criada por outro aplicativo também não é válida no Access. Não invente SSO/OIDC ou troca de tokens. Use somente os endpoints documentados.
3. Implemente dois controles no código#
- No canal HTTP, consulte
GET /api/v1/identity?organizationId=…com o Bearer do usuário. Só após a validação retorne um principaluser, comprincipalIdigual aouserIdrecebido e um issuer que identifique o ambiente Access. - Antes de cada efeito sensível, consulte novamente o Access e compare o
slug exigido pela política local. Confira que o
userIdcontinua sendo o principal atual e queorganizationIdé a organização configurada. Só depois execute a operação real.
Use o cliente TypeScript e
a ponte eve, copiados para agent/lib/ sem a
extensão .ts nos imports (o tsc do projeto eve acusa TS5097). No canal
agent/channels/eve.ts, troque o auth padrão por
[vercelOidc(), accessBridge.authenticate]: placeholderAuth() bloqueia tudo
em produção na Vercel e localDev() aceita chamadas sem token em eve dev.
A ponte recebe uma interface de cofre:
conectá-la ao armazenamento seguro do aplicativo é obrigatório. Não substitua
por um Map global nem por um stub que aceita tudo.
Negue diante de token ausente/inválido, conta suspensa, papel ausente, timeout,
redirecionamento, HTTP inesperado, resposta malformada ou identidade trocada.
Não use none(), localDev() nem outra estratégia como fallback para contornar
um token Access rejeitado. Proteja também chamadas diretas das operações,
subagentes, canais alternativos e caminhos de retomada.
4. Proteja as sessões do eve#
Autenticação de rota não implica propriedade de uma sessão eve. Implemente
uma associação persistida entre sessão e usuário/tenant no servidor. Negue
leitura, stream, mensagens, respostas de aprovação e controles de outra pessoa.
Use ctx.session.auth.current, não initiator, para o chamador do turno.
Não confie em IDs ou papéis enviados em texto, headers inventados ou JSON.
A associação de sessão e o cofre usam (issuer, organizationId, userId), inclusive
quando a mesma conta pertence a duas organizações. Trocar organização cria outro
contexto; não reutilize conversa nem autorização obtida no tenant anterior.
O guia detalha o ponto de integração do gateway/BFF. Não exponha o eve diretamente se esse gateway for o único lugar que aplica a ACL de sessões.
5. Instrua o agente e verifique#
- Coloque as instruções de execução em
agent/instructions.mdou num arquivo deagent/instructions/, que é o que o eve carrega. São orientação de comportamento, não autorização. - Execute a matriz de aceite. Em cada caso negado, confirme que o efeito de negócio não aconteceu.
- Os testes incluídos exercitam os clientes HTTP e a política local com
respostas simuladas:
node --test tests/*.test.mjsem Node 22.18+. Não substituem testes do login/cofre/ACL/canal no agente de destino. - Valide imports/tipos com a versão instalada e faça um teste real com uma conta de aula e papéis reais, sem registrar credenciais.
O que entregar#
Arquivos alterados, versão do eve, URL configurada sem credenciais, tabela ferramenta → slug, origem segura da sessão, política de propriedade de sessão, testes executados e limites restantes. Não afirme que uma integração foi verificada ao vivo se apenas os exemplos ou mocks foram executados.
Referências verificadas#
Em 08/11/2026, o contrato HTTP foi conferido chamando um Access real, e os
exemplos foram executados contra ele. O login pelo navegador (10/11/2026) foi
conferido pelos testes HTTP do próprio Access e pelos testes simulados deste kit;
o modo redirect e examples/eve-access-login.ts (10/11/2026) passaram no tsc
estrito com o eve 1.0.0-rc.8 e foram exercitados contra um Access real
(início, confirmação, retorno, troca, recusa, repetição do retorno e sessão
encerrada), chamando as funções do provedor diretamente, sem um canal eve real;
o trecho server/access-login.ts passou no tsc estrito, mas ainda não foi
exercitado num projeto eve. As interfaces do eve foram conferidas no
eve 0.83.3 instalado: os exemplos e os trechos dos guias passaram no tsc de um
projeto criado pelo eve, e o canal HTTP foi exercitado com eve dev. Em outra
versão, prefira node_modules/eve/docs/ às páginas abaixo.