@cosignet/sdk

Cliente TypeScript fino, de dependência zero, para Cosignet — aprovação humano-no-circuito para ações de alto risco de agentes de IA, com assinaturas de chave de acesso vinculadas ao payload.

Coloque um humano no circuito antes de uma ação perigosa ser executada: pause-a, obtenha uma aprovação explícita por chave de acesso de uma pessoa (Face ID / Touch ID / Windows Hello / chave de segurança) e continue apenas com uma decisão assinada vinculada ao payload exato — altere a ação depois e a assinatura não corresponderá mais. Cosignet é uma camada de aprovação e evidência, não um executor ou motor de política. Funciona em qualquer lugar com fetch global + Web Crypto: Node 18+, Cloudflare Workers, Deno e navegadores.

Status: acesso antecipado. Publicado no npm como @cosignet/sdk.

Instalação

npm install @cosignet/sdk

Solicitar uma aprovação e aguardar a decisão

import { Cosignet } from '@cosignet/sdk';

const cosignet = new Cosignet({ apiKey: process.env.COSIGNET_API_KEY! });

const decision = await cosignet.requestApproval(
  {
    username: 'alex',
    action: 'Transferência bancária para fornecedor',
    payload: { to: 'acct_8821', amount_usd: 4200, memo: 'INV-2025-118' },
    notify: 'telegram_or_email',
  },
  { onCreated: (c) => console.log('Aprovar aqui:', c.url) },
);

if (decision.status === 'approved') {
  // prossiga — decision.rawAssertion é a prova assinada
} else {
  // 'rejected' | 'expired' | 'pending' (tempo esgotado)
}

requestApproval faz long-polling sobre sua própria conexão de saída (~saltos de 25s), então funciona a partir de ferramentas CLI e VPCs restritas atrás de NAT/firewalls — sem necessidade de webhook de entrada, porta aberta ou IP público.

Falhar fechado quando o Cosignet estiver indisponível

Se seu sistema não puder obter uma aprovação assinada, a ação bloqueada não deve ser executada. A indisponibilidade nunca deve degradar para auto-aprovação. Trate todo tempo limite, erro de rede e 5xx como "não aprovado".

Notas de implementação:

• Distinga "rejeitado" de "indisponível" em seus logs e alertas. Um é uma decisão humana, o outro é uma condição operacional.
• Repita leituras com backoff exponencial e jitter; limite a espera total ao prazo da sua própria ação, depois trate como expirado.
• Torne as ações bloqueadas idempotentes do seu lado, para que uma nova tentativa após um estado incerto não possa executar duas vezes.
• Nunca armazene em cache uma aprovação para reutilização. Uma decisão assinada está vinculada a um hash de payload; trate-a como de uso único.

Consulte Quando o Cosignet está indisponível para orientações completas sobre disponibilidade e break-glass.

Chamadas de nível inferior

const created = await cosignet.createConfirmation({ username, action, payload });
const status  = await cosignet.getConfirmation(created.id, { wait: 25 }); // long-poll

Tentativas seguras com uma chave de idempotência

Passe idempotencyKey (enviada como cabeçalho Idempotency-Key) para que uma nova tentativa de criação — por exemplo, após uma interrupção de rede durante um long-poll — com a mesma chave e mesma ação/payload retorne a confirmação original (idempotent: true) em vez de criar uma duplicata ou re-notificar o aprovador. Reutilizar uma chave com parâmetros diferentes é rejeitado com um 422.

await cosignet.createConfirmation({
  username: 'alex',
  action: 'Transferência bancária para fornecedor',
  payload: { to: 'acct_8821', amount_usd: 4200 },
  idempotencyKey: 'wire-INV-2025-118', // estável por operação lógica
});

Enviar o aprovador de volta para seu aplicativo

Passe returnUrl para mostrar um botão "Retornar a <host>" na página de aprovação assim que a solicitação for resolvida (aprovada / rejeitada / expirada) — útil para que um humano possa voltar ao seu aplicativo para re-triggerar uma ação que expirou. Deve ser uma URL https e é apenas renderizada como um link clicável (nunca buscada no lado do servidor).

await cosignet.requestApproval({
  username: 'alex',
  action: 'Transferência bancária para fornecedor',
  payload: { to: 'acct_8821', amount_usd: 4200 },
  returnUrl: 'https://app.example.com/approvals',
});

Notificações

notify ('none' | 'telegram' | 'email' | 'telegram_or_email') controla o ping de alcance pessoal para o signatário específico:

• telegram — uma DM para o Telegram vinculado do aprovador (telegram_or_email prefere isso quando o aprovador vinculou um chat).
• email — um e-mail para o endereço próprio do aprovador. Prioridade: o e-mail direto que você definiu para o aprovador no painel (apenas entrega), depois o e-mail verificado do membro, depois o endereço de contato da conta como último recurso.
• telegram_or_email — Telegram se vinculado, caso contrário o e-mail acima.
• none — nenhum ping pessoal.

Separadamente, o alcance de equipe é uma transmissão Slack para um canal compartilhado, configurado por conta no painel. É aditivo e sempre dispara quando configurado, independente de notify (então notify:'none' ainda publica no Slack). Os aprovadores recebem seus Telegram e e-mail definidos na seção Aprovadores do painel.

Nota sobre a revelação public: true: o e-mail comprometido no log de transparência é o e-mail verificado designado da conta (escolhido nas configurações do painel, como a parte responsável — não o signatário individual). O e-mail de notificação direta é apenas para entrega e nunca usado para o hash de revelação.

Cada canal é apenas de link: a notificação carrega a URL de aprovação e nunca a action ou payload. A aprovação sempre requer a chave de acesso vinculada ao payload do aprovador na página de confirmação — não há aprovação no canal.

Verificar um webhook

verifyWebhookSignature recalcula o HMAC-SHA256 hex do corpo bruto da solicitação e compara em tempo constante com o cabeçalho Cosignet-Signature. Passe os bytes exatos que você recebeu — re-serializar JSON altera a assinatura.

import { verifyWebhookSignature } from '@cosignet/sdk';

const ok = await verifyWebhookSignature({
  body: rawBody,                              // string bruta, não JSON re-parseado
  signature: req.headers['cosignet-signature'],
  secret: process.env.COSIGNET_WEBHOOK_SECRET!,
  timestamp: req.headers['cosignet-timestamp'], // proteção opcional contra replay
  toleranceSeconds: 300,                         // opcional
});
if (!ok) return res.status(401).end();

Verificação

Consulte docs/verification.md para a lista de verificação do lado do chamador: prossiga apenas em approved, compare a decisão com a operação que você está prestes a executar, e trate rejeitado/expirado/tempo limite como paradas fortes.

API

• new Cosignet({ apiKey, baseUrl?, fetch? })
• createConfirmation(input) → CreatedConfirmation
• getConfirmation(id, { wait? }) → Confirmation
• requestApproval(input, { timeoutMs?, onCreated? }) → Confirmation
• verifyWebhookSignature({ body, signature, secret, timestamp?, toleranceSeconds? }) → Promise<boolean>

Revelação pública de aprovação (opt-in, desligado por padrão)

Por padrão, o log de transparência retém o payload e não expõe nenhuma identidade de aprovador. Defina public: true em createConfirmation/requestApproval para optar por uma aprovação única em revelação pública: sua action bruta + payload tornam-se legíveis no pacote de verificação, e um hash PBKDF2 do e-mail verificado designado da conta (escolhido nas configurações do painel – a parte responsável, não o signatário individual) é comprometido na folha Merkle para que qualquer um possa verificar um endereço candidato contra ele.

await cosignet.requestApproval({
  username: 'alice',
  action: 'Publicar resolução do conselho Q3',
  payload: { docId: 'res-2026-Q3' },
  public: true, // permanente, irreversível — veja as ressalvas abaixo
});

• Permanente e irreversível — uma vez publicado, não pode ser despublicado.
• Requer que a revelação pública esteja ativada para sua conta (configurações do painel); caso contrário, a solicitação é rejeitada.
• Honestidade: a revelação do payload é vinculada à chave de acesso (forte); o hash do e-mail é atestado pela raiz de árvore assinada do Cosignet — não assinada pela chave de acesso — e o e-mail é de baixa entropia, então uma correspondência prova um endereço conhecido em vez de anonimato. O e-mail comprometido nomeia a parte responsável escolhida da conta, não necessariamente o indivíduo que assinou; quando nenhum e-mail é escolhido, a folha revela apenas o payload.
• Não ative para confirmações que contenham segredos ou dados pessoais.

Exemplos e documentos de segurança

• examples/ — exemplos prontos para copiar e colar em cURL, Node, Python, GitLab CI, MCP/wrapper de ferramenta e Worker.
• security/ — vinculação de payload, modelo de prova WebAuthn, modelo de ameaça, log de transparência e divulgação responsável.

Receitas

Bloqueie ações de alto risco atrás de uma aprovação por chave de acesso:

• recipes/ai-agent-gate — pause um agente de IA de codificação (Claude Code) antes de executar um comando shell perigoso até que um humano co-assine.
• recipes/cli-approval — envolva qualquer comando (ex.: terraform destroy).
• recipes/ci-cd — bloqueie um pipeline (GitHub Actions / GitLab CI) até aprovação.
• recipes/backend-service — pause uma operação irreversível em um serviço.

Feedback e solicitações

• Solicitações de funcionalidades, ideias de produto, ergonomia do SDK/API e discussão de roadmap: abra uma issue de Funcionalidade.
• Solicitações de novos exemplos ou integrações: abra uma issue de Solicitação de Exemplo.
• Relatórios de segurança: envie e-mail para [email protected]; não abra issues públicas para vulnerabilidades.

Contribuição e segurança

• Código, issues e discussão estão no GitLab: https://gitlab.com/cosignet/sdk.
• Contribuições são bem-vindas — veja CONTRIBUTING e nosso Código de Conduta.
• Reporte vulnerabilidades em privado: SECURITY.md · [email protected].

Licença

MIT © Cosignet