Referências · references/browser-login.md

Login pelo navegador#

Quando o canal do agente responde 401 (sem sessão Access válida), o agente mostra um link. A pessoa abre o link, entra no próprio Access e confirma o agente. Depois disso o agente continua sozinho (modo poll), pede o código que o Access exibiu (modo code) ou recebe o código no retorno do navegador (modo redirect, usado pelo login interativo do eve). A senha nunca passa pelo agente, pelo modelo ou pelo servidor do aplicativo.

Este fluxo está implementado no Access. Não é OAuth/OIDC: é um pedido de uso único, confirmado por uma pessoa e trocado pelo servidor do agente por uma sessão Better Auth nova, só dele.

O que o agente recebe#

O token final tem o mesmo formato do set-auth-token do login por senha e funciona da mesma forma como Bearer em GET /api/v1/identity. Por isso o resto da integração (cofre, ponte eve, requireRole, ACL das sessões) não muda: troque só a forma de obter o token.

A sessão emitida a um agente é restrita:

  • Só consulta /api/v1/identity da organização da integração. Em outra organização responde 403, mesmo que a pessoa participe dela.
  • Não acessa o painel nem a API dele (403), nem edita conta, senha ou outras sessões em /api/auth/* (403 AGENT_SESSION_SCOPE). Pode apenas GET /api/auth/get-session e POST /api/auth/sign-out.
  • Dura até sete dias, como as demais sessões, e o uso pode estendê-la.
  • Termina quando a pessoa a encerra em Minhas sessões (/account no Access, disponível a qualquer conta), quando o agente chama sign-out, quando a pessoa é removida da organização ou quando o administrador revoga a integração. Suspensão nega a identidade (403) enquanto durar.

Preparar#

  1. Um administrador do Access cria uma integração em Integração → Integrações para este aplicativo e ambiente. A chave aparece uma única vez.
  2. Configure no servidor do agente, nunca no navegador, no repositório ou no prompt do modelo:
VariávelO que é
ACCESS_BASE_URLRaiz HTTPS do Access, sem caminho de API
ACCESS_ORGANIZATION_IDOrganização Access cujos papéis valem
ACCESS_CHANNEL_KEYChave da integração (acc_channel_ + 43 caracteres). É a mesma chave usada por canais externos

A chave identifica o aplicativo, não a pessoa: ela só pede logins e troca pedidos aprovados. A organização vem da chave; o corpo não aceita organizationId.

Escolher o modo#

ModoComo a pessoa voltaUse quando
pollAutomaticamente: o servidor consulta a cada interval segundos até a confirmaçãoInterface web do agente aberta no mesmo dispositivo, CLI/TUI local
codeA pessoa copia o código exibido pelo Access e cola no login do agenteO link pode ser aberto em outro dispositivo, ou o agente não consegue esperar
redirectO navegador volta à redirectUri do agente com ?code=…; o servidor troca o códigoLogin interativo do eve (defineInteractiveAuthorization), em qualquer canal

O modo code também protege contra phishing do link: quem iniciou o pedido só recebe a sessão se a pessoa que confirmou entregar o código. Nos modos poll e redirect, quem iniciou o pedido recebe a sessão assim que alguém o confirma (como no OAuth). Por isso a página do Access mostra o nome da integração e pede que a pessoa só confirme um pedido que ela mesma iniciou.

Protocolo servidor → Access#

As duas chamadas usam HTTPS, JSON e Authorization: Bearer <ACCESS_CHANNEL_KEY>, sem cookie e sem Origin (com Origin o Access responde 403).

Iniciar: POST /api/v1/agent-logins#

http
POST /api/v1/agent-logins
Content-Type: application/json
Authorization: Bearer <chave da integração>

{"mode":"poll"}

201:

json
{
  "deviceCode": "acc_device_<43 caracteres>",
  "verificationPath": "/agent-login#code=<43 caracteres>",
  "mode": "poll",
  "expiresAt": "<ISO, +10 min>",
  "interval": 5
}

No modo redirect, envie também a URL de retorno:

http
POST /api/v1/agent-logins
Content-Type: application/json
Authorization: Bearer <chave da integração>

{"mode":"redirect","redirectUri":"https://agente.exemplo/…/callback/…"}
  • redirectUri é obrigatória no modo redirect e recusada (400) nos demais. Precisa ser HTTPS, ou HTTP só em localhost/127.0.0.1 (para eve dev), sem usuário, senha ou fragmento, com até 2048 caracteres. Use o callbackUrl que o eve entrega a startAuthorization, sem alterá-lo.
  • Depois que a pessoa confirma, o navegador vai a redirectUri com ?code=<código> (os parâmetros que a URL já tinha são mantidos). O código não aparece na tela. Se ela recusa, vai a redirectUri com ?error=access_denied. A página do Access mostra a origem do retorno antes da confirmação.
  • O código que volta no navegador não é uma credencial: sozinho não vale nada. A troca exige também o deviceCode e a chave da integração.
  • deviceCode é segredo do servidor. Guarde-o associado à sessão do aplicativo (cookie HttpOnly) ou ao processo da CLI. Nunca o envie ao navegador, ao modelo, a logs ou a URLs.
  • Monte o link com a origem de ACCESS_BASE_URL + verificationPath, nunca com o host de uma requisição. Mostre-o à pessoa como link ou botão.
  • 400 corpo inválido; 401 chave inválida ou revogada; 429 limite.

Concluir: POST /api/v1/agent-logins/token#

http
POST /api/v1/agent-logins/token
Content-Type: application/json
Authorization: Bearer <chave da integração>

{"deviceCode":"acc_device_…"}

Nos modos code e redirect, envie também "code": "<código>": o colado pela pessoa ou o recebido no retorno. O Access ignora maiúsculas, espaços e hífens.

StatusCorpoDecisão
200{token, organizationId, userId, expiresAt}Conferir organizationId; guardar token no cofre. Funciona uma única vez
202{status: "pending", interval}Modo poll: a pessoa ainda não confirmou; consultar de novo após interval
400—Com code: código incorreto (restam tentativas). Sem code: chamada inválida, ou modo code/redirect sem código
403—A pessoa recusou, ou a conta não tem participação ativa nesta organização
410—Expirado, já usado, bloqueado após 5 códigos errados ou integração revogada: iniciar outro login
401—Chave da integração inválida ou revogada: erro de configuração
429, 5xx, timeout, redirect, JSON inválido—Negar; tentar de novo mais tarde, sem laço apertado

Decida pelo status HTTP, não pelo texto de error.

Limites por minuto: 10 logins novos por integração, 20 consultas por pedido e 120 chamadas por chave (somando canais). Não inicie um login a cada mensagem: reutilize o pedido pendente da mesma sessão até ele expirar.

Código no servidor do agente#

Copie examples/access-client.ts para agent/lib/ (sem a extensão .ts nos imports, como no guia). Ele traz startBrowserLogin, completeBrowserLogin e waitForBrowserLogin, com timeout, sem redirects e sem expor chave ou token em erros.

Crie um módulo do aplicativo, nunca uma ferramenta exposta ao modelo:

ts
// server/access-login.ts
import {
  BrowserLoginError, completeBrowserLogin, startBrowserLogin, type BrowserLoginMode,
} from "../agent/lib/access-client";

for (const name of ["ACCESS_BASE_URL", "ACCESS_ORGANIZATION_ID", "ACCESS_CHANNEL_KEY"]) {
  if (!process.env[name]) throw new Error(`Configure ${name}.`);
}
const access = {
  baseUrl: process.env.ACCESS_BASE_URL!,
  organizationId: process.env.ACCESS_ORGANIZATION_ID!,
  integrationKey: process.env.ACCESS_CHANNEL_KEY!,
};

type Pending = { deviceCode: string; expiresAt: string };
/** Pedido em andamento, guardado no servidor e ligado à sessão HttpOnly do aplicativo. */
export interface PendingLoginStore {
  set(appSessionId: string, pending: Pending): Promise<void>;
  get(appSessionId: string): Promise<Pending | null>;
  delete(appSessionId: string): Promise<void>;
}
/** Guarda o token no cofre (AccessCredentialVault.put) e liga a sessão do aplicativo à pessoa. */
export type SaveAccessLogin = (
  appSessionId: string,
  login: { token: string; userId: string; organizationId: string },
) => Promise<void>;

export function createAccessLogin(pending: PendingLoginStore, save: SaveAccessLogin) {
  return {
    /** Chame quando o canal eve responder 401. Devolve só o que pode ir ao navegador. */
    async begin(appSessionId: string, mode: BrowserLoginMode) {
      const current = await pending.get(appSessionId);
      if (current && Date.parse(current.expiresAt) > Date.now() + 60_000) {
        throw new Error("Já existe um login em andamento nesta sessão; mostre o mesmo link.");
      }
      const started = await startBrowserLogin({ ...access, mode });
      await pending.set(appSessionId, { deviceCode: started.deviceCode, expiresAt: started.expiresAt });
      return { verificationUrl: started.verificationUrl, mode: started.mode, expiresAt: started.expiresAt, interval: started.interval };
    },
    /** Modo poll: chame a cada `interval` segundos. Modo code: chame com o código colado. */
    async check(appSessionId: string, code?: string): Promise<"pending" | "signed_in"> {
      const current = await pending.get(appSessionId);
      if (!current) throw new BrowserLoginError("expired");
      try {
        const result = await completeBrowserLogin({ ...access, deviceCode: current.deviceCode, code });
        if (result.status === "pending") return "pending";
        await pending.delete(appSessionId);
        await save(appSessionId, result);
        return "signed_in";
      } catch (error) {
        // Código errado e falhas transitórias permitem tentar de novo; o resto encerra o pedido.
        const retry = error instanceof BrowserLoginError &&
          ["invalid_code", "rate_limited", "unavailable"].includes(error.reason);
        if (!retry) await pending.delete(appSessionId);
        throw error;
      }
    },
  };
}

PendingLoginStore e SaveAccessLogin são dependências a implementar com o armazenamento do aplicativo, como o cofre do guia: no servidor, com TTL de até dez minutos para o pedido, entre réplicas e reinícios. Não use um Map global em produção nem guarde o deviceCode em cookie legível, localStorage ou URL.

Ligar ao aplicativo#

  1. O cliente do aplicativo chama o canal eve com o Bearer da sessão atual. Sem token, ou com 401, ele chama uma rota do aplicativo que executa accessLogin.begin(...) e devolve verificationUrl.
  2. A interface mostra “Entrar com o Access” abrindo verificationUrl em nova aba. No modo code, mostra também um campo para colar o código.
  3. Modo poll: a interface consulta uma rota do aplicativo que chama accessLogin.check(sessionId) a cada interval segundos, até signed_in. Modo code: o formulário envia o código a uma rota que chama accessLogin.check(sessionId, code).
  4. Em signed_in, save já guardou o token no cofre. O gateway passa a enviar o Bearer ao canal eve, e a ponte accessBridge.authenticate valida no Access como antes. Associe as sessões eve a (issuer, organizationId, userId).
  5. Em forbidden, explique que o login foi recusado ou que a conta precisa ser incluída em Membros pelo responsável. Em expired, ofereça um novo login.

Em uma CLI ou TUI local, sem navegador no servidor: imprima verificationUrl e use waitForBrowserLogin (modo poll), ou leia o código do terminal e chame completeBrowserLogin (modo code). Guarde o token no armazenamento seguro de credenciais do sistema, nunca em arquivo de texto do projeto.

O link não é segredo de login, mas não o coloque no contexto do modelo: quem o confirmar entrega a sessão a quem iniciou o pedido. O código do modo code deve ser colado na interface de login do aplicativo. Se o agente só tiver o chat, intercepte a mensagem com o código no canal, antes do modelo, e nunca crie uma ferramenta que receba deviceCode ou código do modelo.

Sair#

Chame signOutFromAccess({ baseUrl, token }) e apague o token do cofre e a sessão local, como no login por senha. A pessoa também pode encerrar a sessão do agente em Minhas sessões no Access; a próxima consulta recebe 401.

Login interativo do eve em qualquer canal#

O eve (1.0+) pausa o turno quando uma ferramenta precisa de uma credencial que a pessoa ainda não deu, mostra um pedido de entrada na própria conversa e continua de onde parou quando o provedor redireciona de volta ao callbackUrl que ele criou. O modo redirect do Access é esse provedor. Assim, em Telegram, Slack, WhatsApp (Chat SDK), Twilio ou no canal HTTP, a pessoa é orientada a entrar pelo próprio chat:

  1. A pessoa pede algo; a ferramenta chama ctx.getToken(accessAuth).
  2. Sem sessão guardada, o eve chama startAuthorization({ callbackUrl }): o servidor pede um login redirect ao Access com esse callbackUrl.
  3. O eve envia o link à pessoa em privado: na conversa direta, em mensagem efêmera no Slack, ou depois do botão Authorize no Telegram em grupos. O link nunca entra no contexto do modelo.
  4. A pessoa entra no Access, confere o agente e a origem do retorno, e confirma.
  5. O navegador volta ao callbackUrl com ?code=…; o eve chama completeAuthorization, que troca o código pelo token e o guarda no cofre.
  6. A ferramenta roda de novo, agora com o token, e consulta papéis no Access.

Copie examples/access-client.ts e examples/eve-access-login.ts para agent/lib/ (sem a extensão .ts nos imports). O módulo usa defineInteractiveAuthorization de eve/connections e fica fora do alcance do modelo: o modelo só vê o resultado das ferramentas.

ts
// agent/lib/access-sign-in.ts
import { createAccessSignIn } from "./eve-access-login";
import { accessGrants } from "./access-grants"; // AccessGrantStore do aplicativo

for (const name of ["ACCESS_BASE_URL", "ACCESS_ORGANIZATION_ID", "ACCESS_CHANNEL_KEY"]) {
  if (!process.env[name]) throw new Error(`Configure ${name}.`);
}
// requireRole e identify pedem a entrada no chat quando a pessoa ainda não entrou.
export const access = createAccessSignIn({
  baseUrl: process.env.ACCESS_BASE_URL!,
  organizationId: process.env.ACCESS_ORGANIZATION_ID!,
  integrationKey: process.env.ACCESS_CHANNEL_KEY!,
}, accessGrants);

AccessGrantStore é uma dependência a implementar com o armazenamento do servidor, como o cofre do guia: chave (issuer, id) da pessoa no canal, valor { token, userId, expiresAt }, cifrado em repouso, com TTL até expiresAt e compartilhado entre réplicas. O eve não guarda tokens.

Em cada ferramenta sensível, exija o papel imediatamente antes do efeito:

ts
// agent/tools/aprovar_pagamento.ts
import { defineTool } from "eve/tools";
import { z } from "zod";
import { access } from "../lib/access-sign-in";

export default defineTool({
  description: "Aprova o pagamento informado.",
  inputSchema: z.object({ pagamentoId: z.string().min(1) }),
  async execute({ pagamentoId }, ctx) {
    // Sem sessão Access, o eve pede a entrada no chat e repete esta chamada depois.
    const identity = await access.requireRole(ctx, "financeiro");
    return { aprovado: pagamentoId, por: identity.userId };
  },
});

Para a pessoa poder entrar antes de precisar (“quero entrar”, “o que posso fazer?”), ofereça uma ferramenta que só identifica:

ts
// agent/tools/minha_identidade.ts
import { defineTool } from "eve/tools";
import { z } from "zod";
import { AccessDeniedError } from "../lib/access-client";
import { access } from "../lib/access-sign-in";

export default defineTool({
  description: "Entra no Access e mostra os papéis da pessoa. Use quando ela pedir para entrar ou perguntar o que pode fazer.",
  inputSchema: z.object({}),
  async execute(_input, ctx) {
    try {
      const identity = await access.identify(ctx);
      return { entrou: true, papeis: [...identity.roles] };
    } catch (error) {
      // Conta criada, mas ainda não incluída (ou suspensa) nesta organização.
      if (error instanceof AccessDeniedError && error.reason === "suspended") {
        return { entrou: true, papeis: [], aviso: "Peça ao responsável pelo Access para incluir seu e-mail em Membros." };
      }
      throw error;
    }
  },
});

Regras deste fluxo:

  • A rota do canal continua identificando o remetente pelo provedor (o canal nativo do eve valida o webhook e cria um principal user). O Access entra como credencial da ferramenta, ligada a esse remetente; não troque o auth do canal por accessBridge.authenticate neste fluxo.
  • resume guarda o deviceCode no estado durável do eve até o retorno, como um verificador PKCE: sozinho não vale nada, expira em dez minutos e é de uso único. O token fica só no AccessGrantStore.
  • O retorno é do navegador e pode ser forjado: completeAuthorization só aceita o que o Access confirmar na troca. ?error=… (recusa no Access ou cancelamento pelo eve) termina o pedido sem nova tentativa no turno.
  • Sessão encerrada em Minhas sessões, pessoa removida ou integração revogada: a próxima consulta recebe 401, identify chama ctx.requireAuth e o eve pede uma nova entrada.
  • Turnos iniciados por agendamento não pedem entrada (sign_in_unavailable).
  • Limites: 10 logins novos por minuto por integração. Uma nova mensagem da pessoa encerra o pedido aberto (withdrawn); o próximo turno pede de novo.

Canais externos: login interativo ou vínculo#

Login interativo do eve (acima)Vínculo de canais
Quem guarda a sessãoO servidor do agente (AccessGrantStore)Só o Access; o adaptador nunca recebe token
O que o agente consultaGET /api/v1/identity com o token da pessoaPOST /api/v1/channels/identity com a chave da integração
Quando pede a entradaSó quando uma ferramenta precisaNa primeira mensagem sem vínculo
EncerrarMinhas sessões → sessões de agentesMinhas sessões → vínculos de canais

Os dois são seguros; escolha um por canal. Prefira o vínculo quando o servidor do agente não deve guardar tokens de usuários; prefira o login interativo quando o agente já usa os pedidos de entrada do eve ou quando parte das ferramentas deve funcionar sem identificar a pessoa.

Aceite adicional#

Com conta de aula e integração real, confirme: link aberto sem login pede login; confirmação libera a sessão (poll) ou exige o código (code); código errado não libera e cinco erros bloqueiam o pedido; “Recusar” devolve 403; pedido expirado devolve 410; conta não incluída não consegue confirmar; o token recebido não abre o painel nem outra organização; encerrar a sessão na em Minhas sessões, sair, remover a pessoa ou revogar a integração faz a próxima operação negar; nenhum log, URL, mensagem ou contexto do modelo contém chave, deviceCode, código ou token.

No login interativo, confirme também, em cada canal usado: o pedido de entrada aparece só para quem pediu (nunca no grupo nem no modelo); confirmar continua o mesmo turno; “Recusar” encerra o pedido sem executar a ferramenta; repetir a URL de retorno não cria outra sessão; encerrar a sessão em Minhas sessões faz a próxima ferramenta pedir nova entrada.