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#

  1. 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).
  2. Configure ACCESS_BASE_URL como a raiz HTTPS do Access correto e ACCESS_ORGANIZATION_ID como a organização esperada. A integração criada no painel fica presa à organização selecionada; não pode ser movida pelo chamador.
  3. 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.
  4. Use os IDs estáveis do provedor: channel (ex.: telegram), workspace (tenant, workspace, instalação ou conta do bot) e subject (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.

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

StatusCorpoDecisão
200{organizationId, authenticated: true, userId, roles, checkedAt}, dados atuaisConferir 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:

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

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

ts
// 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 onMessage próprio substitui a filtragem padrão de grupos do canal; este exemplo ignora tudo que não é conversa privada.
  • O eve substitui auth.current a 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:

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