@telepapo/sdk 0.0.0-stage → 0.2.0

package/src/index.js

@@ -0,0 +1,408 @@
+// @telepapo/sdk — o lado do servidor de um app do TelePapo Developers.
+//
+// O app é um APARELHO da conta comercial que o autorizou: tem chaves Signal
+// próprias (geradas aqui, nunca saem do seu servidor), recebe uma cópia
+// cifrada de cada mensagem que chega para a conta e envia em nome dela. O
+// celular do dono vê o que o app mandou (o SDK manda o "espelho").
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { ArmazenamentoArquivo, ArmazenamentoMemoria } from './armazenamento.js';
+import { verificarAssinatura } from './webhook.js';
+import { categoria, impressao } from './categoria.js';
+import { abrirAnexo, prepararAnexo } from './anexos.js';
+
+const require = createRequire(import.meta.url);
+const { Signal } = require('../signal/telepapo_signal.js');
+
+export { ArmazenamentoArquivo, ArmazenamentoMemoria, verificarAssinatura };
+export { cifrarAnexo, decifrarAnexo } from './anexos.js';
+
+export class ErroTelePapo extends Error {
+  constructor(status, corpo) {
+    super(corpo?.mensagem || `Erro ${status}`);
+    this.status = status;
+    this.codigo = corpo?.codigo;
+    this.corpo = corpo;
+  }
+}
+
+class SemAparelho extends Error {}
+
+const TIPOS_DE_MENSAGEM = new Set(['texto', 'midia', 'localizacao', 'contato', 'animacao', 'produto']);
+
+export class TelePapo {
+  /**
+   * @param {object} o
+   * @param {string} o.clientId      client_id do app (portal)
+   * @param {string} o.credencial    client_secret do app (portal; mostrado uma vez)
+   * @param {string} [o.chaveWebhook] chave de assinatura do webhook (portal)
+   * @param {string} [o.apiUrl]      padrão https://api.telepapo.com.br
+   * @param {object} [o.armazenamento] { ler, gravar, apagar } — padrão: memória
+   * @param {(chave: string, f: () => Promise<any>) => Promise<any>} [o.travar]
+   *   Trava ENTRE processos (ex.: Redis). Obrigatória se mais de um processo usa
+   *   a mesma conta: o estado do Signal e o refresh token não aguentam dois
+   *   escritores ao mesmo tempo. Sem ela, só a fila deste processo.
+   */
+  constructor({ clientId, credencial, chaveWebhook, apiUrl = 'https://api.telepapo.com.br', armazenamento = new ArmazenamentoMemoria(), fetch = globalThis.fetch, travar = null }) {
+    if (!clientId || !credencial) throw new Error('clientId e credencial são obrigatórios.');
+    this.clientId = clientId;
+    this.credencial = credencial;
+    this.chaveWebhook = chaveWebhook;
+    this.apiUrl = apiUrl.replace(/\/$/, '');
+    this.armazenamento = armazenamento;
+    this.fetch = fetch;
+    this.travar = travar;
+    this.contas = new Map();
+  }
+
+  async http(metodo, caminho, { corpo, token, basic } = {}) {
+    const headers = { 'User-Agent': 'telepapo-sdk/0.2' };
+    if (corpo !== undefined) headers['Content-Type'] = 'application/json';
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (basic) headers.Authorization = 'Basic ' + Buffer.from(`${this.clientId}:${this.credencial}`).toString('base64');
+    const r = await this.fetch(this.apiUrl + caminho, { method: metodo, headers, body: corpo === undefined ? undefined : JSON.stringify(corpo) });
+    const texto = await r.text();
+    const json = texto ? JSON.parse(texto) : null;
+    if (!r.ok) throw new ErroTelePapo(r.status, json);
+    return json;
+  }
+
+  /**
+   * Passo 1 da autorização: gera a identidade Signal do novo aparelho e pede a
+   * autorização. Mande o usuário para `url` (ele aprova no celular); depois o
+   * TelePapo o devolve para `redirectUri?code=…&state=<estado>`.
+   */
+  async iniciarAutorizacao({ redirectUri, estado = randomUUID(), escopos } = {}) {
+    const s = Signal.novo();
+    const chaves = JSON.parse(s.chavesIniciais(Date.now()));
+    const r = await this.http('POST', '/v1/autorizacoes', { basic: true, corpo: { chaves, redirectUri, estado, ...(escopos ? { escopos } : {}) } });
+    await this.armazenamento.gravar(`pedido:${estado}`, { signal: s.exportar(), id: r.id, criadoEm: Date.now() });
+    return { url: r.url, estado, id: r.id, expiraEm: r.expiraEm };
+  }
+
+  /** Passo 2: no seu `redirectUri`, troque o `code` (e o `state`) pela conta autorizada. */
+  async concluirAutorizacao({ code, estado }) {
+    const pedido = await this.armazenamento.ler(`pedido:${estado}`);
+    if (!pedido) throw new Error('Pedido de autorização desconhecido (estado inválido ou vencido).');
+    const t = await this.http('POST', '/v1/token', { basic: true, corpo: { code } });
+    const s = Signal.carregar(pedido.signal);
+    // A chave registrada na conta tem de ser a que geramos aqui.
+    if (t.identityKey !== s.identidadePublica()) throw new Error('A identidade registrada não confere.');
+    s.definirEndereco(t.conta.id, t.dispositivo.numero);
+    const estadoConta = {
+      id: t.conta.id, nome: t.conta.nome, username: t.conta.username, numero: t.dispositivo.numero, dispositivoId: t.dispositivo.id,
+      escopos: t.escopos, tokens: { acesso: t.acesso, refresh: t.refresh, acessoExpiraEm: t.acessoExpiraEm }, signal: s.exportar(),
+    };
+    await this.armazenamento.gravar(`conta:${t.conta.id}`, estadoConta);
+    await this.armazenamento.apagar(`pedido:${estado}`);
+    return this.conta(t.conta.id);
+  }
+
+  /** Uma conta já autorizada. */
+  conta(id) {
+    if (!this.contas.has(id)) this.contas.set(id, new Conta(this, id));
+    return this.contas.get(id);
+  }
+
+  /**
+   * Webhook: confere a assinatura com o corpo CRU e devolve o evento. Para
+   * `mensagem.recebida`, já decifra e confirma o envelope (`evento.mensagem`).
+   */
+  async processarWebhook(corpoCru, assinatura) {
+    if (!this.chaveWebhook) throw new Error('Configure chaveWebhook para receber webhooks.');
+    if (!verificarAssinatura(corpoCru, assinatura, this.chaveWebhook)) throw new Error('Assinatura do webhook inválida.');
+    const ev = JSON.parse(Buffer.isBuffer(corpoCru) ? corpoCru.toString('utf8') : corpoCru);
+    if (ev.tipo === 'mensagem.recebida') {
+      const conta = this.conta(ev.conta);
+      const mensagem = await conta.processarEnvelope(ev.dados.envelope);
+      await conta.confirmar([ev.dados.envelope.id]);
+      return { ...ev, mensagem };
+    }
+    if (ev.tipo === 'autorizacao.revogada') {
+      await this.armazenamento.apagar(`conta:${ev.conta}`);
+      this.contas.delete(ev.conta);
+    }
+    return ev;
+  }
+}
+
+class Conta {
+  constructor(cliente, id) {
+    this.cliente = cliente;
+    this.id = id;
+    this.fila = Promise.resolve();
+  }
+
+  /** Uma operação por vez por conta (o estado do Signal não pode ser usado por duas ao mesmo tempo). */
+  trava(f) {
+    const externa = this.cliente.travar;
+    const vez = this.fila.then(() => (externa ? externa(`telepapo:conta:${this.id}`, f) : f()));
+    this.fila = vez.catch(() => undefined);
+    return vez;
+  }
+
+  async estado() {
+    const e = await this.cliente.armazenamento.ler(`conta:${this.id}`);
+    if (!e) throw new Error('Conta não autorizada (ou o app foi desconectado).');
+    return e;
+  }
+
+  async gravar(e) {
+    await this.cliente.armazenamento.gravar(`conta:${this.id}`, e);
+  }
+
+  /** Mexe no Signal: carrega, roda e grava (antes de confirmar qualquer envelope). */
+  async comSignal(f) {
+    const e = await this.estado();
+    const s = Signal.carregar(e.signal);
+    const r = await f(s, e);
+    e.signal = s.exportar();
+    await this.gravar(e);
+    return r;
+  }
+
+  async token() {
+    const valido = (e) => new Date(e.tokens.acessoExpiraEm).getTime() - Date.now() > 60_000;
+    const e = await this.estado();
+    if (valido(e)) return e.tokens.acesso;
+    const renovar = async () => {
+      // Relê dentro da trava: outro processo pode ter acabado de renovar.
+      const atual = await this.estado();
+      if (valido(atual)) return atual.tokens.acesso;
+      const par = await this.cliente.http('POST', '/v1/auth/renovar', { corpo: { refresh: atual.tokens.refresh } });
+      atual.tokens = { acesso: par.acesso, refresh: par.refresh, acessoExpiraEm: par.acessoExpiraEm };
+      await this.gravar(atual);
+      return par.acesso;
+    };
+    const externa = this.cliente.travar;
+    return externa ? externa(`telepapo:token:${this.id}`, renovar) : renovar();
+  }
+
+  async api(metodo, caminho, corpo) {
+    return this.cliente.http(metodo, caminho, { corpo, token: await this.token() });
+  }
+
+  async dados() {
+    const e = await this.estado();
+    return { id: e.id, nome: e.nome, username: e.username, escopos: e.escopos };
+  }
+
+  // ------------------------------------------------------------ receber
+
+  /** Busca o que está pendente (alternativa/complemento ao webhook), decifra e confirma. */
+  receber() {
+    return this.trava(async () => {
+      const r = await this.api('GET', '/v1/mensagens');
+      const mensagens = [];
+      for (const env of r.envelopes) {
+        const m = await this.decifrarEnvelope(env);
+        if (m) mensagens.push(m);
+      }
+      if (r.envelopes.length) await this.api('POST', '/v1/mensagens-confirmadas', { ids: r.envelopes.map((e) => e.id) });
+      return mensagens;
+    });
+  }
+
+  processarEnvelope(env) {
+    return this.trava(() => this.decifrarEnvelope(env));
+  }
+
+  confirmar(ids) {
+    return this.api('POST', '/v1/mensagens-confirmadas', { ids });
+  }
+
+  /**
+   * Decifra um envelope e devolve a mensagem:
+   * `{ id, de, grupo, tipo, texto, conteudo, em, minha }`. `minha` = escrita
+   * pelo dono em outro aparelho (celular/navegador): `conversa` diz onde.
+   * Repetido ou ilegível: null.
+   */
+  async decifrarEnvelope(env) {
+    let claro;
+    try {
+      claro = await this.comSignal((s) => s.decifrar(env.de, env.deDispositivo, env.tipo, env.conteudo));
+    } catch (e) {
+      if (/duplicate|old counter/i.test(String(e?.message ?? e))) return null;
+      return { id: env.id, de: env.de, erro: 'nao_decifrou', em: Date.parse(env.recebidoEm) };
+    }
+    let c;
+    try {
+      c = JSON.parse(Buffer.from(claro).toString('utf8'));
+    } catch {
+      return null;
+    }
+    const minha = env.de === this.id;
+    return {
+      id: c.id,
+      de: env.de,
+      deDispositivo: env.deDispositivo,
+      grupo: env.grupoId ?? null,
+      conversa: env.grupoId ?? (minha ? c.para ?? null : env.de),
+      tipo: c.tipo,
+      texto: c.texto ?? null,
+      em: c.em,
+      minha,
+      conteudo: c,
+    };
+  }
+
+  // ------------------------------------------------------------ enviar
+
+  async abrirSessoes(usuario, numero) {
+    let r;
+    try {
+      r = await this.api('GET', `/v1/chaves/${usuario}` + (numero ? `?dispositivo=${numero}` : ''));
+    } catch (e) {
+      if (e.status === 404) throw new SemAparelho('O contato não está conectado em nenhum aparelho.');
+      throw e;
+    }
+    if (!r.pacotes.length) throw new SemAparelho('O contato não está conectado em nenhum aparelho.');
+    await this.comSignal((s) => {
+      for (const p of r.pacotes) s.abrirSessao(usuario, JSON.stringify(p), Date.now());
+    });
+  }
+
+  async cifrarPara(usuario, claro) {
+    return this.comSignal((s) => [...s.dispositivosComSessao(usuario)].map((n) => {
+      const r = JSON.parse(s.cifrar(usuario, n, claro, Date.now()));
+      return { dispositivo: n, registrationId: r.registrationId, tipo: r.tipo, conteudo: r.conteudo };
+    }));
+  }
+
+  async corrigir(usuario, d) {
+    await this.comSignal((s) => {
+      for (const n of [...(d.sobrando ?? []), ...(d.desatualizados ?? [])]) s.apagarSessao(usuario, n);
+    });
+    for (const n of [...(d.faltando ?? []), ...(d.desatualizados ?? [])]) await this.abrirSessoes(usuario, n);
+  }
+
+  async enviar1a1(dest, c, { efemero = false } = {}) {
+    const claro = new TextEncoder().encode(JSON.stringify(c));
+    const cat = categoria(c);
+    const imp = await impressao(c);
+    for (let tentativa = 1; ; tentativa++) {
+      const comSessao = await this.comSignal((s) => [...s.dispositivosComSessao(dest)]);
+      if (!comSessao.length) await this.abrirSessoes(dest);
+      const envelopes = await this.cifrarPara(dest, claro);
+      try {
+        await this.api('POST', `/v1/mensagens/${dest}`, { idCliente: c.id.replace(/-/g, ''), envelopes, categoria: cat, ...(imp ? { impressao: imp } : {}), ...(efemero ? { efemero: true } : {}) });
+        return;
+      } catch (e) {
+        if (tentativa >= 3 || (e.status !== 409 && e.status !== 410)) throw e;
+        await this.corrigir(dest, e.corpo ?? {});
+      }
+    }
+  }
+
+  /** Espelho: os outros aparelhos do dono (celular, navegador) ficam sabendo do que o app mandou. */
+  async espelhar(conversa, c) {
+    try {
+      await this.enviar1a1(this.id, { ...c, para: conversa });
+    } catch (e) {
+      if (!(e instanceof SemAparelho)) throw e;
+    }
+  }
+
+  /** Envia um Conteudo (formato do TelePapo) para um contato (1:1). */
+  enviar(para, conteudo) {
+    return this.trava(async () => {
+      const c = { v: 1, id: randomUUID(), em: Date.now(), ...conteudo };
+      await this.enviar1a1(para, c);
+      await this.espelhar(para, c);
+      return { id: c.id };
+    });
+  }
+
+  enviarTexto(para, texto, { resposta } = {}) {
+    if (!texto?.trim()) throw new Error('Texto vazio.');
+    return this.enviar(para, { tipo: 'texto', texto: texto.slice(0, 65000), ...(resposta ? { resposta } : {}) });
+  }
+
+  /** Avisa quem escreveu que a conta leu (e o celular do dono também). */
+  marcarLida(de, ids) {
+    return this.enviar(de, { tipo: 'recibo', estado: 'lido', ids });
+  }
+
+  reagir(para, mensagemId, emoji) {
+    return this.enviar(para, { tipo: 'reacao', alvo: mensagemId, emoji: emoji ?? '' });
+  }
+
+  /** "Digitando…" (efêmero: só chega a quem estiver online; não vai para o celular do dono). */
+  digitando(para, ativo = true) {
+    return this.trava(async () => {
+      const c = { v: 1, id: randomUUID(), em: Date.now(), tipo: 'digitando', estado: ativo ? 'inicio' : 'fim' };
+      try {
+        await this.enviar1a1(para, c, { efemero: true });
+      } catch (e) {
+        if (!(e instanceof SemAparelho)) throw e;
+      }
+    });
+  }
+
+  // ------------------------------------------------------------ anexos
+
+  /**
+   * Cifra e sobe um arquivo; devolve o `anexo` para pôr numa mensagem `midia`.
+   * @param {Buffer|Uint8Array} dados
+   * @param {{mime: string, nome?: string, largura?: number, altura?: number, duracaoMs?: number, miniatura?: string}} info
+   */
+  async subirAnexo(dados, info = {}) {
+    if (!info.mime) throw new Error('Informe o mime do anexo.');
+    const { blob, chave, digest } = prepararAnexo(dados);
+    const { id } = await this.api('POST', '/v1/anexos', { tamanho: blob.length });
+    const token = await this.token();
+    const r = await this.cliente.fetch(`${this.cliente.apiUrl}/v1/anexos/${id}/conteudo`, {
+      method: 'PUT',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/octet-stream', 'User-Agent': 'telepapo-sdk/0.2' },
+      body: blob,
+    });
+    if (!r.ok) {
+      const texto = await r.text();
+      throw new ErroTelePapo(r.status, texto ? JSON.parse(texto) : null);
+    }
+    const extra = Object.fromEntries(['nome', 'largura', 'altura', 'duracaoMs', 'miniatura'].filter((k) => info[k] != null).map((k) => [k, info[k]]));
+    return { id, chave, digest, tamanho: Buffer.byteLength(Buffer.from(dados)), mime: info.mime, ...extra };
+  }
+
+  /** Baixa, confere e decifra o anexo de uma mensagem recebida (`mensagem.conteudo.anexo`). */
+  async baixarAnexo(anexo) {
+    const token = await this.token();
+    const r = await this.cliente.fetch(`${this.cliente.apiUrl}/v1/anexos/${encodeURIComponent(anexo.id)}`, {
+      headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'telepapo-sdk/0.2' },
+    });
+    if (!r.ok) {
+      const texto = await r.text();
+      throw new ErroTelePapo(r.status, texto ? JSON.parse(texto) : null);
+    }
+    return abrirAnexo(Buffer.from(await r.arrayBuffer()), anexo);
+  }
+
+  /**
+   * Envia um arquivo (foto, vídeo, áudio, documento). A mensagem de mídia do
+   * TelePapo não tem legenda: `legenda`, se houver, vai logo depois como texto.
+   */
+  async enviarArquivo(para, dados, { mime, nome, largura, altura, duracaoMs, miniatura, legenda, resposta } = {}) {
+    const anexo = await this.subirAnexo(dados, { mime, nome, largura, altura, duracaoMs, miniatura });
+    const r = await this.enviar(para, { tipo: 'midia', anexo, ...(resposta ? { resposta } : {}) });
+    if (legenda?.trim()) await this.enviarTexto(para, legenda);
+    return { ...r, anexo };
+  }
+
+  /** Repõe as pré-chaves do aparelho quando o estoque no servidor baixa (rode de tempos em tempos). */
+  async garantirPreKeys() {
+    const c = await this.api('GET', '/v1/chaves/contagem');
+    const pre = c.preKeys < 15 ? 50 : 0;
+    const kyber = c.kyberPreKeys < 15 ? 20 : 0;
+    if (!pre && !kyber) return false;
+    const lote = await this.trava(() => this.comSignal((s) => JSON.parse(s.reposicao(Date.now(), pre, kyber))));
+    await this.api('PUT', '/v1/chaves', lote);
+    return true;
+  }
+
+  /** O app sai da conta (o dono também pode desconectar pelo celular). */
+  async desconectar() {
+    await this.api('POST', '/v1/auth/sair');
+    await this.cliente.armazenamento.apagar(`conta:${this.id}`);
+    this.cliente.contas.delete(this.id);
+  }
+}

package/src/webhook.js

@@ -0,0 +1,20 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Confere o cabeçalho `X-TelePapo-Assinatura: t=<segundos>,v1=<hex>` de um
+ * webhook: v1 = HMAC-SHA256(chave do webhook, `${t}.${corpo}`).
+ *
+ * Use o CORPO CRU da requisição (os bytes exatos, antes de qualquer
+ * JSON.parse). Recusa assinatura com mais de `toleranciaSegundos` (padrão 5
+ * min): um evento capturado não pode ser reapresentado depois.
+ */
+export function verificarAssinatura(corpo, cabecalho, chave, { toleranciaSegundos = 300, agora = Date.now() } = {}) {
+  const texto = Buffer.isBuffer(corpo) ? corpo.toString('utf8') : String(corpo);
+  const partes = Object.fromEntries(String(cabecalho ?? '').split(',').map((p) => p.trim().split('=')));
+  const t = Number(partes.t);
+  if (!Number.isInteger(t) || !partes.v1) return false;
+  if (Math.abs(agora / 1000 - t) > toleranciaSegundos) return false;
+  const esperado = createHmac('sha256', chave).update(`${t}.${texto}`).digest();
+  const recebido = Buffer.from(partes.v1, 'hex');
+  return recebido.length === esperado.length && timingSafeEqual(recebido, esperado);
+}