Referências · references/integration.md
Guia de implementação · eve + Access#
Escopo e configuração#
Você não tem acesso ao código do Access. Tudo o que pode usar está neste kit: os endpoints da referência HTTP, os exemplos e os testes. Não procure, adivinhe nem chame outros endpoints.
Este documento cobre a sessão de usuário no canal HTTP do eve. Para obter o token sem que o agente veja a senha, prefira o login pelo navegador; ele entrega um token equivalente ao do login por senha descrito aqui, e todo o resto deste guia vale igual. Para Telegram, Slack e outros provedores, use o protocolo de vínculo: a chave da integração não substitui o Bearer de usuário deste documento.
O Access valida uma conta e retorna seus papéis. A política ferramenta → papel vive no agente. O painel, o login e o endpoint de identidade já existem; não crie outro provedor de autenticação nem replique contas ou papéis.
O operador fornece, e você exige na inicialização do servidor do agente:
| Variável | O que é | Onde o operador encontra |
|---|---|---|
ACCESS_BASE_URL | Raiz HTTPS do Access, sem caminho de API | Endereço do Access |
ACCESS_ORGANIZATION_ID | Organização Access cujos papéis valem | Tela Integração do Access |
| Slugs dos papéis | Ex.: financeiro, suporte | Tela Papéis do Access |
Não aceite esses valores do usuário nem do modelo: uma URL controlada por outra pessoa receberia os tokens. Não invente um domínio de produção.
Referência HTTP#
Todas as chamadas partem do servidor do aplicativo do agente, nunca do navegador: o Access só responde a CORS para as próprias origens. Use HTTPS e JSON, não siga redirecionamentos e use timeout.
Regra de Origin nas rotas /api/auth/*: envie Origin igual à origem de
ACCESS_BASE_URL (por exemplo https://access.example). O fetch do Node envia
Sec-Fetch-Mode: cors, e com ele o Access trata a chamada como de navegador:
sem Origin responde 403 MISSING_OR_NULL_ORIGIN, e com qualquer outra origem
responde 403 INVALID_ORIGIN. Nunca repasse o Origin do navegador do usuário.
Os helpers signInToAccess e signOutFromAccess já fazem isso.
Formatos de erro: as rotas /api/auth/* respondem { "message", "code" }; use
code. As demais respondem { "error": "<texto em português>" }; decida pelo
status HTTP, não pelo texto, que pode mudar.
Entrar: POST /api/auth/sign-in/email#
POST /api/auth/sign-in/email
Content-Type: application/json
Origin: https://access.example
{"email":"pessoa@example.com","password":"…"}200 com corpo { "redirect", "token", "user": { "id", "name", "email", … } }
e o cabeçalho set-auth-token: <token>.<assinatura>. Só o valor desse
cabeçalho funciona como Bearer. O campo token do JSON é a parte sem
assinatura e recebe 401 em /api/v1/identity.
| Status | code | Significado |
|---|---|---|
| 401 | INVALID_EMAIL_OR_PASSWORD | Credenciais erradas |
| 400 | VALIDATION_ERROR | E-mail mal formado |
| 403 | MISSING_OR_NULL_ORIGIN, INVALID_ORIGIN | Erro de integração: corrija o Origin |
| 429 | — | Limite atingido; aguarde os segundos de X-Retry-After |
O e-mail não diferencia maiúsculas e minúsculas.
Cadastrar: POST /api/auth/sign-up/email#
Mesmos cabeçalhos; corpo { "name", "email", "password" }, com senha de 12 a
128 caracteres. 200 com { "token", "user" } e o mesmo set-auth-token: a
conta já sai com sessão. Erros: 422 USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL,
400 PASSWORD_TOO_SHORT, 400 VALIDATION_ERROR, além do Origin e do 429.
Uma conta nova não pertence a nenhuma organização. Até um administrador do
Access incluir o e-mail exato dela em Membros, /api/v1/identity responde
403. Oriente a pessoa a pedir a inclusão; não trate como erro do agente.
Ofereça cadastro no aplicativo do agente só se fizer sentido: as pessoas também
podem criar a conta na própria tela do Access.
Identidade: GET /api/v1/identity#
GET /api/v1/identity?organizationId=<ACCESS_ORGANIZATION_ID>
Authorization: Bearer <valor de set-auth-token>
Accept: application/json{
"organizationId": "<organização Access configurada>",
"authenticated": true,
"userId": "<id da conta>",
"roles": ["financeiro"],
"checkedAt": "2026-11-08T12:00:00.000Z"
}| Status | Quando | Decisão |
|---|---|---|
| 200 | Sessão válida e participação ativa | Conferir organizationId e userId; aplicar a política local |
200, roles: [] | Membro sem papéis | Negar ferramentas que exigem papel |
| 400 | organizationId ausente ou repetido | Erro de configuração; negar |
| 401 | Bearer ausente, inválido, adulterado, sem assinatura, expirado ou após logout | Pedir novo login |
| 403 | Conta não incluída, removida ou suspensa nesta organização (ou organização desconhecida) | Negar; orientar a procurar o responsável |
| 429, 5xx, rede, timeout, redirect, JSON inválido | — | Negar sem executar; informar indisponibilidade |
Papéis são slugs imutáveis, válidos só nesta organização. A resposta não tem
allowed, actions nem permissões. userId é derivado do token, nunca da
requisição. Um papel chamado admin não concede administração do Access.
A resposta vem com Cache-Control: no-store; não guarde a decisão.
Sair: POST /api/auth/sign-out#
Com Authorization: Bearer <token>, Origin e corpo {}. 200
{ "success": true }; depois disso o token recebe 401. Repetir também
responde 200.
Validade: GET /api/auth/get-session#
Com o Bearer, devolve { "session": { "expiresAt", … }, "user" }. Use apenas
para escolher o TTL do cofre. Uma sessão inválida responde 200 com corpo
null: nunca use este endpoint para autorizar. As sessões duram até sete
dias e o uso pode estendê-las; trate qualquer 401 como fim da sessão.
Limites#
Por endereço IP de quem chama, ou seja, o servidor do aplicativo do agente:
10 logins e 5 cadastros por minuto, e 120 chamadas por minuto em /api/auth/*.
Aplicativos no mesmo provedor podem compartilhar IP de saída. Em 429, mostre
uma mensagem, respeite X-Retry-After e não repita automaticamente.
/api/v1/identity não tem limite próprio, mas consulte por efeito, sem polling.
Login e logout no backend#
Com o login pelo navegador, os passos 1 e 2 abaixo são
substituídos por startBrowserLogin + completeBrowserLogin; os passos 3 a 5
continuam iguais.
- O backend do aplicativo recebe e-mail e senha do usuário pela sua tela de login. A senha nunca passa pelo modelo nem por uma ferramenta.
- Chame
signInToAccess({ baseUrl, email, password })deexamples/access-client.ts. Ele envia oOrigincorreto, exige o cabeçalhoset-auth-tokene devolve{ token, userId }. Falhas chegam comoAccessAuthErrorcomreason:invalid_credentials,rate_limited,unavailableouinvalid_response. - Guarde o token no cofre do servidor, associado à sessão HttpOnly do aplicativo. Nunca o devolva ao navegador nem o coloque no contexto do modelo.
- O gateway/BFF resolve a sessão do navegador e encaminha o token ao canal eve
em
Authorization: Bearer. O cliente do eve aceita umbearerassíncrono:new Client({ host: "<url do agente>", auth: { bearer: async () => token } }), conformenode_modules/eve/docs/guides/client/overview.mdx. - Ao sair, chame
signOutFromAccess({ baseUrl, token })e apague o token do cofre e a sessão local. Se a chamada falhar, bloqueie o uso local mesmo assim e trate a revogação remota como pendente; não afirme que ela ocorreu.
O token é opaco e assinado. Não o decodifique como JWT, não implemente JWKS e não invente refresh token. O cookie do painel Access não vale em outro domínio e não há SSO nem troca de tokens entre aplicativos. Não há verificação nem recuperação de senha por e-mail.
Arquivos no projeto de destino#
Copie examples/access-client.ts e examples/eve-access.ts para agent/lib/.
Remova a extensão .ts dos imports entre eles ("./access-client.ts" vira
"./access-client"): o projeto criado pelo eve não habilita
allowImportingTsExtensions e o tsc falha com TS5097. A extensão existe no
kit só para os testes do Node.
Crie um módulo do aplicativo, não uma ferramenta exposta ao modelo:
// agent/lib/access-runtime.ts
import { AccessClient } from "./access-client";
import { createAccessBridge } from "./eve-access";
import { accessVault } from "../../server/access-vault";
if (!process.env.ACCESS_BASE_URL) throw new Error("Configure ACCESS_BASE_URL.");
if (!process.env.ACCESS_ORGANIZATION_ID) throw new Error("Configure ACCESS_ORGANIZATION_ID.");
const client = new AccessClient({ baseUrl: process.env.ACCESS_BASE_URL, organizationId: process.env.ACCESS_ORGANIZATION_ID });
export const accessBridge = createAccessBridge(client, accessVault);server/access-vault é uma dependência a implementar com o armazenamento
seguro do aplicativo, na interface AccessCredentialVault. Não existe no Access
nem no kit. Não deixe esse import quebrado nem entregue um stub que aceita tudo.
O cofre precisa:
- Cifrar os tokens em repouso e nunca retorná-los ao cliente ou ao modelo.
- Gerar referências aleatórias e validar usuário + issuer + organizationId ao lê-las.
- Ter TTL de no máximo sete dias, limpeza e revogação no logout, e funcionar entre reinícios e réplicas. Referência ausente ou expirada nega.
- Reutilizar ou limpar entradas criadas a cada autenticação do canal, para não crescer sem limite.
- Ficar fora do sandbox acessível ao agente.
Autenticação do canal eve#
O canal HTTP fica em agent/channels/eve.ts. O projeto criado pelo eve vem com
auth: [vercelOidc(), localDev(), placeholderAuth()], avaliados em ordem. Troque
por:
// agent/channels/eve.ts
import { eveChannel } from "eve/channels/eve";
import { vercelOidc } from "eve/channels/auth";
import { accessBridge } from "../lib/access-runtime";
export default eveChannel({
auth: [
// Mantém o acesso do TUI do eve e de chamadas de serviço da Vercel.
// Ignora (devolve null) tokens que não são OIDC da Vercel, como os do Access.
vercelOidc(),
// Usuários finais: Bearer do Access. Sem Bearer válido, responde 401.
accessBridge.authenticate,
],
});- Remova
placeholderAuth(): em produção na Vercel ele responde401e encerra a avaliação, e o Access nunca seria consultado. - Remova
localDev(): sobeve devele aceita qualquer chamada sem token, e você não conseguiria testar a rejeição. Teste localmente com um token real. - Preserve as demais opções do canal que o projeto já usa.
- O autenticador lança
UnauthenticatedError(401) eForbiddenError(403). Rejeite noauth, não noonMessage: no canal HTTP oonMessagenão pode devolvernull, e um erro ali vira500. - O principal retornado é
user, comprincipalIdigual aouserIddo Access. Valores deattributesprecisam ser strings. Não devolvaallowToolStubs: truepara usuários finais.
Autorização dentro da ferramenta#
// agent/tools/consultar_relatorio.ts
import { defineTool } from "eve/tools";
import { z } from "zod";
import { accessBridge } from "../lib/access-runtime";
import { reports } from "../../server/reports";
export default defineTool({
description: "Consulta um relatório que pertence ao usuário autenticado.",
inputSchema: z.object({ reportId: z.string().min(1) }),
async execute({ reportId }, ctx) {
// O slug é uma política do servidor. Não é escolhido pelo modelo.
const identity = await accessBridge.requireRole(
ctx.session.auth.current,
"leitor", // EXEMPLO: substitua por um slug real, acordado com o responsável.
);
// Adapte ao repositório real. Papel não substitui propriedade do recurso.
return reports.findOwnedBy({ reportId, organizationId: identity.organizationId, ownerId: identity.userId });
},
});server/reports é a operação de negócio do agente de destino, não parte do
kit. Implemente a consulta com filtro de propriedade no servidor.
Revalide imediatamente antes de cada efeito. O eve reproduz o resultado de um passo durável já concluído em vez de executá-lo de novo: não deixe uma autorização antiga num passo separado que será reutilizado antes de uma nova escrita. Garanta idempotência das escritas e revise após aprovação ou retomada.
Isolamento das conversas#
O eve autentica a rota, mas não tem ACL por sessão: qualquer chamador aceito
pelo canal pode continuar, ler ou controlar uma sessão cujo ID conheça. Apenas
configurar auth não torna o agente multiusuário seguro.
No gateway/BFF persistido do aplicativo:
- Crie a sessão eve autenticada e associe seu ID à tupla
(issuer, organizationId, userId)antes de expor o ID ao cliente. Falhe fechado se não conseguir registrar. Uma conta em duas organizações não compartilha conversas nem recursos entre elas. - Em stream, mensagens, respostas de aprovação, cancel/clear/compact/reset e leitura de artefatos, confira a associação antes de chamar o eve.
- Se o eve puder ser chamado diretamente, imponha a mesma ACL nele ou elimine esse caminho. CORS não é ACL.
- Autorize pelo chamador do turno,
ctx.session.auth.current. Não usectx.session.auth.initiatorcomo identidade atual e não configuretrustedForwarderspara chamadores arbitrários. - Subagentes sem
auth.currentválido devem negar a ferramenta protegida.
Diagnóstico#
| Sintoma | Verifique |
|---|---|
Login responde 403 MISSING_OR_NULL_ORIGIN | Falta Origin igual à origem de ACCESS_BASE_URL |
Login responde 403 INVALID_ORIGIN | Origin diferente da origem do Access, ou URL do ambiente errado |
| Login funciona, identidade responde 401 | Bearer usado é o token do JSON em vez de set-auth-token; sessão encerrada |
| Identidade responde 403 para uma conta nova | Conta ainda não incluída em Membros; peça ao administrador |
| Identidade responde 400 | ACCESS_ORGANIZATION_ID ausente ou parâmetro repetido |
| Identidade 200, ferramenta nega | Slug exato, atribuição real e principal correspondente |
tsc acusa TS5097 | Imports .ts copiados do kit; remova a extensão |
| Canal eve responde 401 com token válido em produção na Vercel | placeholderAuth() antes do autenticador do Access |
| Conta suspensa ainda executa | Falta revalidação ou há passo durável com decisão antiga |
| Outro usuário vê a conversa | Falta ACL de sessão; autenticação de rota não basta |
| Login pelo navegador fica em 202 | A pessoa ainda não confirmou; o pedido expira em 10 minutos |
| Login pelo navegador responde 401 | ACCESS_CHANNEL_KEY errada ou integração revogada |
| Token do login pelo navegador recebe 403 no painel | Esperado: a sessão do agente só consulta /api/v1/identity |
| 429 no login | Limite por IP; aguarde X-Retry-After |
Os testes do kit validam os clientes HTTP com respostas simuladas. Login, cofre, ACL, canal e ferramenta precisam de testes no projeto de destino, com a versão instalada do eve e uma conta real de aula.