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ávelO que éOnde o operador encontra
ACCESS_BASE_URLRaiz HTTPS do Access, sem caminho de APIEndereço do Access
ACCESS_ORGANIZATION_IDOrganização Access cujos papéis valemTela Integração do Access
Slugs dos papéisEx.: financeiro, suporteTela 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#

http
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.

StatuscodeSignificado
401INVALID_EMAIL_OR_PASSWORDCredenciais erradas
400VALIDATION_ERRORE-mail mal formado
403MISSING_OR_NULL_ORIGIN, INVALID_ORIGINErro 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#

http
GET /api/v1/identity?organizationId=<ACCESS_ORGANIZATION_ID>
Authorization: Bearer <valor de set-auth-token>
Accept: application/json
json
{
  "organizationId": "<organização Access configurada>",
  "authenticated": true,
  "userId": "<id da conta>",
  "roles": ["financeiro"],
  "checkedAt": "2026-11-08T12:00:00.000Z"
}
StatusQuandoDecisão
200Sessão válida e participação ativaConferir organizationId e userId; aplicar a política local
200, roles: []Membro sem papéisNegar ferramentas que exigem papel
400organizationId ausente ou repetidoErro de configuração; negar
401Bearer ausente, inválido, adulterado, sem assinatura, expirado ou após logoutPedir novo login
403Conta 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.

  1. 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.
  2. Chame signInToAccess({ baseUrl, email, password }) de examples/access-client.ts. Ele envia o Origin correto, exige o cabeçalho set-auth-token e devolve { token, userId }. Falhas chegam como AccessAuthError com reason: invalid_credentials, rate_limited, unavailable ou invalid_response.
  3. 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.
  4. O gateway/BFF resolve a sessão do navegador e encaminha o token ao canal eve em Authorization: Bearer. O cliente do eve aceita um bearer assíncrono: new Client({ host: "<url do agente>", auth: { bearer: async () => token } }), conforme node_modules/eve/docs/guides/client/overview.mdx.
  5. 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:

ts
// 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:

ts
// 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 responde 401 e encerra a avaliação, e o Access nunca seria consultado.
  • Remova localDev(): sob eve dev ele 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) e ForbiddenError (403). Rejeite no auth, não no onMessage: no canal HTTP o onMessage não pode devolver null, e um erro ali vira 500.
  • O principal retornado é user, com principalId igual ao userId do Access. Valores de attributes precisam ser strings. Não devolva allowToolStubs: true para usuários finais.

Autorização dentro da ferramenta#

ts
// 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:

  1. 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.
  2. Em stream, mensagens, respostas de aprovação, cancel/clear/compact/reset e leitura de artefatos, confira a associação antes de chamar o eve.
  3. Se o eve puder ser chamado diretamente, imponha a mesma ACL nele ou elimine esse caminho. CORS não é ACL.
  4. Autorize pelo chamador do turno, ctx.session.auth.current. Não use ctx.session.auth.initiator como identidade atual e não configure trustedForwarders para chamadores arbitrários.
  5. Subagentes sem auth.current válido devem negar a ferramenta protegida.

Diagnóstico#

SintomaVerifique
Login responde 403 MISSING_OR_NULL_ORIGINFalta Origin igual à origem de ACCESS_BASE_URL
Login responde 403 INVALID_ORIGINOrigin diferente da origem do Access, ou URL do ambiente errado
Login funciona, identidade responde 401Bearer usado é o token do JSON em vez de set-auth-token; sessão encerrada
Identidade responde 403 para uma conta novaConta ainda não incluída em Membros; peça ao administrador
Identidade responde 400ACCESS_ORGANIZATION_ID ausente ou parâmetro repetido
Identidade 200, ferramenta negaSlug exato, atribuição real e principal correspondente
tsc acusa TS5097Imports .ts copiados do kit; remova a extensão
Canal eve responde 401 com token válido em produção na VercelplaceholderAuth() antes do autenticador do Access
Conta suspensa ainda executaFalta revalidação ou há passo durável com decisão antiga
Outro usuário vê a conversaFalta ACL de sessão; autenticação de rota não basta
Login pelo navegador fica em 202A pessoa ainda não confirmou; o pedido expira em 10 minutos
Login pelo navegador responde 401ACCESS_CHANNEL_KEY errada ou integração revogada
Token do login pelo navegador recebe 403 no painelEsperado: a sessão do agente só consulta /api/v1/identity
429 no loginLimite 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.