Referências · references/channels.md
Canais externos · vínculo por link#
Este fluxo está implementado no Access. Não é OAuth/OIDC nem troca de tokens: o Access guarda uma referência à sessão Better Auth que aprovou o vínculo. O adaptador recebe somente identidade e papéis; não recebe o token do usuário.
Preparar#
- O administrador abre Integração → Canais externos, cria uma integração
por aplicação/ambiente e guarda a chave exibida uma vez em um gerenciador
de segredos no servidor do adaptador (
ACCESS_CHANNEL_KEY). - Configure
ACCESS_BASE_URLcomo a raiz HTTPS do Access correto eACCESS_ORGANIZATION_IDcomo a organização esperada. A integração criada no painel fica presa à organização selecionada; não pode ser movida pelo chamador. - Implemente a validação oficial do webhook/provedor: assinatura, timestamp, prevenção de replay e deduplicação. Uma chave Access não valida o remetente de uma mensagem. Não aceite IDs de remetente vindos do modelo.
- Use os IDs estáveis do provedor:
channel(ex.:telegram),workspace(tenant, workspace, instalação ou conta do bot) esubject(ID do remetente, não nome de exibição, texto, chat/grupo compartilhado). Não normalize ou reutilize esses IDs entre ambientes.workspaceé do provedor, não uma organização Access.
Protocolo servidor → Access#
Todas as requisições abaixo usam HTTPS, JSON e Authorization: Bearer <ACCESS_CHANNEL_KEY>, sem cookie e sem Origin: com Origin o Access
responde 403, porque esta API é só para servidor. Nunca chame do navegador e
nunca inclua a chave em conversa, URL, prompt, atributos, ferramenta ou log.
A chave tem o formato acc_channel_ seguido de 43 caracteres.
POST /api/v1/channels/identity
Content-Type: application/json
Authorization: Bearer <chave da integração>
{"channel":"telegram","workspace":"<id do bot>","subject":"<id do remetente>"}O corpo aceita exatamente esses três campos; qualquer campo extra, inclusive
organizationId, recebe 400. A organização vem só da chave.
| Status | Corpo | Decisão |
|---|---|---|
| 200 | {organizationId, authenticated: true, userId, roles, checkedAt}, dados atuais | Conferir organizationId e userId esperados antes de qualquer efeito |
| 401 | {"error":"Sem vínculo com sessão válida. Solicite nova autenticação."} | Remetente sem vínculo, ou sessão que aprovou o vínculo encerrada: ofereça novo link |
| 401 | {"error":"Chave de integração inválida ou revogada."} | Configuração: chave errada ou revogada; não ofereça link |
| 403 | {"error":"Acesso suspenso."} | Conta suspensa nesta organização; negue |
| 403 | {"error":"Esta API é exclusiva do servidor do adaptador."} | Chamada com Origin ou cookie; corrija o adaptador |
| 400, 429, 5xx, timeout, redirect, JSON inválido | — | Negue; não use papéis antigos nem conta compartilhada |
Limites por minuto: 240 chamadas por IP, 120 por chave (identidade e links somados) e 10 links novos por integração. Não crie um link a cada mensagem de um remetente não vinculado: reutilize o pedido recente ou espere alguns minutos.
Quando o remetente precisar entrar:
POST /api/v1/channels/challenges
Content-Type: application/json
Authorization: Bearer <chave da integração>
{"channel":"telegram","workspace":"<id do bot>","subject":"<id do remetente>"}Resposta 201: {"verificationPath":"/connect-channel#code=<43 caracteres>","expiresAt":"<ISO, +10 min>"}.
Monte o link usando a origem ACCESS_BASE_URL configurada, nunca Host ou URL
da mensagem. Envie somente ao remetente em conversa privada. Não envie um
link de vinculação em grupo, nem inclua o link em contexto do modelo.
O código tem 256 bits, expira em dez minutos, só é armazenado como hash e é
consumido atomicamente na confirmação. Não é o token de sessão do usuário.
O usuário abre o link, faz login no Access, revisa organização, integração, canal, workspace e remetente, e confirma explicitamente. A página remove o fragmento do endereço e não confirma só por visitar o link. Link encaminhado pode tentar vincular a conta da vítima ao remetente do atacante: instrua o usuário a nunca aprovar pedido que não iniciou no próprio canal privado. Preview e aprovação exigem participação ativa nessa organização. Cadastrar uma conta não concede participação; o administrador local deve adicioná-la por e-mail exato. A organização é obtida do challenge/integração, nunca do workspace nem de um tenant livre enviado na aprovação.
A confirmação acontece só no navegador da pessoa, na página do Access.
O adaptador não aprova pelo usuário e não tem como fazê-lo.
Não há callback externo ou redirecionamento arbitrário. Na próxima mensagem,
ou após um botão “Já entrei” do seu canal, consulte novamente /identity.
Não faça polling irrestrito; limite tentativas e respeite 429.
Sessão e revogação#
- O vínculo referencia a sessão Better Auth usada na confirmação. Termina quando essa sessão expira ou é revogada; sair dessa sessão no Access encerra esse acesso. Outra sessão do mesmo usuário não renova o vínculo sozinha.
- O usuário vê e remove seus próprios vínculos em Minhas sessões (
/account) no Access. O restante do painel é dos administradores. - O administrador revoga uma integração, bloqueando todos os seus vínculos, links pendentes e chave. Para substituir uma chave, crie outra integração e refaça os vínculos; não há recuperação do segredo.
- Não há troca silenciosa para outra conta: o titular precisa remover o vínculo anterior primeiro. A mesma conta pode renovar sua sessão com novo link.
- Suspensão e remoção de papel são checadas nas chamadas seguintes.
- Remover a participação apaga os vínculos locais; outras organizações não são afetadas.
- Vínculos e chaves são administrados nas telas do Access, por pessoas. O adaptador não tem API para isso e não deve tentar criá-los.
- O Access não armazena outra cópia do token em um cofre externo: como mantém a sessão original no próprio banco, guarda só sua referência interna.
Integração com eve#
Com o eve 1.0+, há uma alternativa a este vínculo: o login interativo, em que o próprio eve pede a entrada na conversa e o servidor do agente guarda a sessão Access da pessoa. Veja a comparação em login pelo navegador. O restante desta seção usa o vínculo.
O eve tem canais nativos para Telegram (eve/channels/telegram), Slack
(eve/channels/slack) e Twilio (eve/channels/twilio). Eles validam o webhook
(segredo do Telegram, assinatura do Slack) antes de chamar o seu onMessage.
O WhatsApp não tem canal nativo: use o adaptador eve/channels/chat-sdk ou um
canal próprio com defineChannel, validando você mesmo a assinatura do provedor.
Copie para agent/lib/ os arquivos access-client.ts, channel-access-client.ts
e eve-channel-access.ts, removendo a extensão .ts dos imports entre eles.
Configure no servidor ACCESS_CHANNEL_KEY e ACCESS_CHANNEL_WORKSPACE, um
identificador estável deste bot definido pelo operador (por exemplo, o username).
// agent/lib/channel-runtime.ts
import { ChannelAccessClient } from "./channel-access-client";
for (const name of ["ACCESS_BASE_URL", "ACCESS_ORGANIZATION_ID", "ACCESS_CHANNEL_KEY", "ACCESS_CHANNEL_WORKSPACE"]) {
if (!process.env[name]) throw new Error(`Configure ${name}.`);
}
export const channelAccess = new ChannelAccessClient({
baseUrl: process.env.ACCESS_BASE_URL!,
organizationId: process.env.ACCESS_ORGANIZATION_ID!,
integrationKey: process.env.ACCESS_CHANNEL_KEY!,
});
// Identificador estável deste bot (ex.: o username), definido pelo operador.
export const channelWorkspace = process.env.ACCESS_CHANNEL_WORKSPACE!;No Telegram, resolva a identidade no onMessage. O link de vínculo vai direto
ao remetente pelo próprio canal e nunca passa pelo modelo:
// agent/channels/telegram.ts
import { defaultTelegramAuth, telegramChannel } from "eve/channels/telegram";
import { AccessDeniedError } from "../lib/access-client";
import { channelUserAuth } from "../lib/eve-channel-access";
import { channelAccess, channelWorkspace } from "../lib/channel-runtime";
export default telegramChannel({
// O eve já validou o segredo do webhook antes de chamar onMessage.
// Devolver null descarta a mensagem: o modelo não a recebe.
async onMessage(ctx, message) {
const base = defaultTelegramAuth(message);
if (!base) return null;
// Vínculo e identidade só em conversa privada: em grupo o ID muda e o link vazaria.
if (base.attributes.chat_type !== "private") return null;
const userId = base.attributes.user_id;
if (typeof userId !== "string" || !userId) return null;
const sender = { channel: "telegram", workspace: channelWorkspace, subject: userId };
try {
const identity = await channelAccess.identity(sender);
return { auth: channelUserAuth(channelAccess, sender, identity, base.attributes) };
} catch (error) {
if (error instanceof AccessDeniedError && error.reason === "unauthenticated") {
// Envie o link direto ao remetente, fora do contexto do modelo.
const link = await channelAccess.challenge(sender).catch(() => null);
await ctx.telegram.sendMessage(link
? `Para continuar, entre no Access e confirme o vínculo (expira em 10 minutos): ${link.verificationUrl}`
: "Não foi possível gerar o link agora. Tente novamente em instantes.");
} else if (error instanceof AccessDeniedError && error.reason === "suspended") {
await ctx.telegram.sendMessage("Sua conta não tem acesso nesta organização. Procure o responsável.");
} else {
await ctx.telegram.sendMessage("Não foi possível verificar seu acesso agora. Nada foi executado.");
}
return null;
}
},
});- Um
onMessagepróprio substitui a filtragem padrão de grupos do canal; este exemplo ignora tudo que não é conversa privada. - O eve substitui
auth.currenta cada mensagem;channelUserAuthé chamado em toda mensagem e mantém nos atributos o remetente e a organização. - Limite a criação de links por remetente (veja os limites acima). O exemplo cria um link a cada mensagem não vinculada para ficar curto.
Em cada ferramenta sensível, revalide imediatamente antes do efeito:
// agent/tools/aprovar_reembolso.ts
import { defineTool } from "eve/tools";
import { z } from "zod";
import { requireChannelRole } from "../lib/eve-channel-access";
import { channelAccess } from "../lib/channel-runtime";
export default defineTool({
description: "Aprova um reembolso do pedido informado.",
inputSchema: z.object({ pedidoId: z.string().min(1) }),
async execute({ pedidoId }, ctx) {
// Imediatamente antes do efeito, sempre consultando o Access de novo.
const identity = await requireChannelRole(channelAccess, ctx.session.auth.current, "financeiro");
return { pedidoId, aprovadoPor: identity.userId };
},
});requireChannelRole só aceita o principal criado por channelUserAuth, na
organização configurada, e consulta o Access de novo: suspensão, papel removido
e vínculo encerrado valem na hora.
Slack: use slackChannel com onDirectMessage (só mensagens diretas). Parta
de defaultSlackAuth(message, ctx); use team_id dos atributos como workspace
e user_id como subject. Envie o link com ctx.thread.postDirectMessage(userId, texto)
e devolva null. Confira os tipos em node_modules/eve/docs/channels/.
Não passe a chave da integração para createAccessBridge do canal HTTP: ele
aceita token de sessão de usuário, não chave de servidor. As duas formas de
autenticação são diferentes. O remetente vem sempre do webhook validado, nunca
de argumentos de ferramenta. Rechecar o papel não substitui escopo do recurso,
isolamento das conversas e idempotência.
Aceite adicional#
Teste com adaptador real do canal: assinatura inválida, replay, mensagens de grupo, isolamento de tenants/integrações, confirmação explícita e repetida, expiração, conta suspensa, papel removido, sessão encerrada, desvincular e revogar chave. Em todo caso negado o efeito deve permanecer inexistente. Os testes deste repositório não comprovam conexão real com Telegram/WhatsApp/Slack.