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/identityda organização da integração. Em outra organização responde403, 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 apenasGET /api/auth/get-sessionePOST /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 (
/accountno Access, disponível a qualquer conta), quando o agente chamasign-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#
- Um administrador do Access cria uma integração em Integração → Integrações para este aplicativo e ambiente. A chave aparece uma única vez.
- Configure no servidor do agente, nunca no navegador, no repositório ou no prompt do modelo:
| Variável | O que é |
|---|---|
ACCESS_BASE_URL | Raiz HTTPS do Access, sem caminho de API |
ACCESS_ORGANIZATION_ID | Organização Access cujos papéis valem |
ACCESS_CHANNEL_KEY | Chave 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#
| Modo | Como a pessoa volta | Use quando |
|---|---|---|
poll | Automaticamente: o servidor consulta a cada interval segundos até a confirmação | Interface web do agente aberta no mesmo dispositivo, CLI/TUI local |
code | A pessoa copia o código exibido pelo Access e cola no login do agente | O link pode ser aberto em outro dispositivo, ou o agente não consegue esperar |
redirect | O navegador volta à redirectUri do agente com ?code=…; o servidor troca o código | Login 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#
POST /api/v1/agent-logins
Content-Type: application/json
Authorization: Bearer <chave da integração>
{"mode":"poll"}201:
{
"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:
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 modoredirecte recusada (400) nos demais. Precisa ser HTTPS, ou HTTP só emlocalhost/127.0.0.1(paraeve dev), sem usuário, senha ou fragmento, com até 2048 caracteres. Use ocallbackUrlque o eve entrega astartAuthorization, sem alterá-lo.- Depois que a pessoa confirma, o navegador vai a
redirectUricom?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 aredirectUricom?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
deviceCodee 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. 400corpo inválido;401chave inválida ou revogada;429limite.
Concluir: POST /api/v1/agent-logins/token#
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.
| Status | Corpo | Decisã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:
// 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#
- 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 executaaccessLogin.begin(...)e devolveverificationUrl. - A interface mostra “Entrar com o Access” abrindo
verificationUrlem nova aba. No modocode, mostra também um campo para colar o código. - Modo
poll: a interface consulta uma rota do aplicativo que chamaaccessLogin.check(sessionId)a cadaintervalsegundos, atésigned_in. Modocode: o formulário envia o código a uma rota que chamaaccessLogin.check(sessionId, code). - Em
signed_in,savejá guardou o token no cofre. O gateway passa a enviar o Bearer ao canal eve, e a ponteaccessBridge.authenticatevalida no Access como antes. Associe as sessões eve a(issuer, organizationId, userId). - Em
forbidden, explique que o login foi recusado ou que a conta precisa ser incluída em Membros pelo responsável. Emexpired, 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:
- A pessoa pede algo; a ferramenta chama
ctx.getToken(accessAuth). - Sem sessão guardada, o eve chama
startAuthorization({ callbackUrl }): o servidor pede um loginredirectao Access com essecallbackUrl. - 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.
- A pessoa entra no Access, confere o agente e a origem do retorno, e confirma.
- O navegador volta ao
callbackUrlcom?code=…; o eve chamacompleteAuthorization, que troca o código pelo token e o guarda no cofre. - 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.
// 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:
// 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:
// 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 oauthdo canal poraccessBridge.authenticateneste fluxo. resumeguarda odeviceCodeno 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ó noAccessGrantStore.- O retorno é do navegador e pode ser forjado:
completeAuthorizationsó 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,identifychamactx.requireAuthe 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ão | O servidor do agente (AccessGrantStore) | Só o Access; o adaptador nunca recebe token |
| O que o agente consulta | GET /api/v1/identity com o token da pessoa | POST /api/v1/channels/identity com a chave da integração |
| Quando pede a entrada | Só quando uma ferramenta precisa | Na primeira mensagem sem vínculo |
| Encerrar | Minhas sessões → sessões de agentes | Minhas 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.