Pular para o conteúdo principal

Biblioteca de Integração

Introdução​

Nessa seção, você conhecerá a biblioteca de integração com o LedgerSign.

Ela disponibiliza uma classe que expõe métodos para testar e realizar a comunicação com nossa extensão LedgerSign.

Biblioteca Frontend​

Dependendo do seu projeto, há duas formas de configurar a biblioteca.

Esta biblioteca só pode ser usada em frontend (navegador). Se for usado na renderização do lado do servidor (como Nextjs), faça uma importação dinâmica do componente que o usa.

Utilizando o NPM ou Yarn (Versão em Typescript)​

Instale rodando o comando yarn add sign-assistant-extension ou npm install sign-assistant-extension --save.

import Signer from 'sign-assistant-extension'

Utilizando a CDN (Versão em Javascript)​

Insira a importação abaixo dentro da tag <head> do html, e a Classe ficará disponível no objeto window do navegador.

<script src="https://cdn.jsdelivr.net/npm/sign-assistant-extension/dist/Sign.min.js"></script>

Instanciando o objeto da Lib​

const signer = new Signer({
  key: "", // chave de acesso web para o SignAssistant, deixe uma string vazia se não tiver uma chave
  id: "ledger", // id única da extensão, mantenha "ledger" para configurar com a extensão da Ledger
})

Essa lib dará acesso a alguns recursos, são eles:

  • Verificar se a extensão está instalada e habilitada
  • Verificar se o Sign Assistant está instalado
  • Baixar extensão com base no navegador atual
  • Fazer o download do Sign Assistant com base na resposta da extensão
  • Obter lista de certificados
  • Aplicar algoritmo criptográfico
  • Observar os erros, solicitações e respostas da extensão

Tipos de respostas​

Clique para expandir

Esta biblioteca é fortemente tipada, mas aqui estão as definições de tipo de resposta do método para ajudá-lo a entender melhor seu funcionamento.

interface Certificate {
  isValid: boolean;
  issuer: string;
  name: string;
  notAfter: string;
  notBefore: string;
  pem: string;
  provider: string;
  specialName: string;
  type: string;
  personId?: string;
}

interface Signature {
  key: number;
  signature: string;
}

interface ErrorResponse {
  level: "BACKGROUND" | "CONTENT" | "CLI" | "LIB" | "EXTENSION_RUNTIME"; // especifica onde ocorreu o erro
  error: string; // mensagem amigável
  code: number; // código baseado no nível de erro, explicado mais tarde...
  originalErrorMessage?: string; // mensagem de erro original se existir (definida se o nível for "EXTENSION_RUNTIME" ou "CLI")
}

Métodos​

Listar certificados​

const searchResponse = await signer.getCertificates();
// retorno: Certificate[] | ErrorResponse

Aplicar algoritmo criptográfico​

const dataToSignArray = [
  {
    dataToSign, // string of data to sign
    key: 1,
  },
];
const signResponse = await signer.sign({ dataToSignArray, certificate });
// retorno: Signature[] | ErrorResponse

Testar a instalação do LedgerSign​

const hasExtension = await signer.hasExtension(); // timeout = 1000ms
// retorno: true | ErrorResponse

Testar a instalação do SignAssistant​

const hasSoftware = await signer.hasSoftware(); // timeout = 1000ms
// retorno: true | ErrorResponse

Instalar LedgerSign​

(Não é uma Promise porque os URLs de download já estão definidos na propriedade downloadLinks).

const url = signer.downloadExtension({
  openUrl: false, // Opcional, padrão: true
});
// retorno: string | ErrorResponse
// string é o URL de download, ele será aberto como nova guia se openUrl não estiver definido como false

Instalar SignAssistant​

const url = await signer.downloadSoftware({
  openUrl: false, // Opcional, padrão: true
});
// retorno: string | ErrorResponse
// string é o URL de download, ele será aberto como nova guia se openUrl não estiver definido como false

Testar erro​

(Typescript narrow type check) - Este método também é exportado do index da biblioteca.

const dataToSignArray = [
  {
    dataToSign, // string de dados para aplicar algoritmo criptográfico
    key: 1,
  },
];
const signResponse = await signer.sign({ dataToSignArray, certificate });
const isError = signer.isError(signResponse); // boolean
if (isError) {
  console.log(signResponse.error);
}
// retorno: boolean

Propriedades​

PropriedadeTipoPadrãoDescrição
idstringobrigatórioID único da extensão, e.g: ledger.
keystringobrigatórioChave de acesso do Sign assistant.
requestTimeoutnumber3000Tempo limite para verificar se a extensão está ativada em milissegundos, ex: 1000.
logsbooleanfalseAtivar logs de lib e extensão.
downloadLinksobjectundefinedObjeto com os links de download da extensões nas lojas.
onLoadExtensionfunctionundefinedRetorno de chamada quando a extensão é carregada.
onErrorfunctionundefinedRetorno de chamada quando um erro é lançado.
onRequestfunctionundefinedRetorno de chamada quando a biblioteca envia uma solicitação para a extensão.
onResponsefunctionundefinedRetorno de chamada quando lib recebe uma resposta da extensão.

Códigos de erro​

NívelCódigoDescrição
CLI1Erro desconhecido no nosso Sign Assistant.
CLI2Argumentos inválidos enviados ao Sign Assistant.
CLI3A comunicação com o Sign Assistant foi interrompida.
CLI4Um campo obrigatório não foi enviado ao Sign Assistant.
CLI5Um campo obrigatório foi enviado ao Sign Assistant com tipo inválido.
CLI6Algorítmo inválido enviado ao Sign Assistant.
CLI7Senha incorreta fornecida ao Sign Assistant.
CLI8O certificado enviado ao Sign Assistant não foi encontrado.
CLI9Operação cancelada pelo usuário no Sign Assistant.
CLI10Falha ao ler certificado no Sign Assistant.
CLI11O certificado já existe no Sign Assistant.
CLI12Erro no SQLite no Sign Assistant.
CLI13Erro no OpenSLL no Sign Assistant.
CLI14Erro ao inicializar interface gráfica no Sign Assistant.
CLI15Não foi possível acessar o certificado no Sign Assistant. Verifique se o token está conectado.
CLI16O caminho do driver já existe no banco de dados do Sign Assistant.
CLI17O token foi bloqueado no Sign Assistant por excesso de falhas de PIN.
EXTENSION_RUNTIME1Falha não identificada ao comunicar com o Sign Assistant.
EXTENSION_RUNTIME2Cheque as permissões do local de instalação do Sign Assistant.
EXTENSION_RUNTIME3A extensão está tentando conectar com um host não existente.
EXTENSION_RUNTIME4A comunicação com o Sign Assistant foi interrompida.
EXTENSION_RUNTIME5O nosso software não foi instalado.
EXTENSION_RUNTIME6O ID da sua extensão precisa ser adicionado à lista de extensões no arquivo de configuração do Sign Assistant.
EXTENSION_RUNTIME7Problema de comunicação com o Sign Assistant. Certifique-se de tê-lo atualizado.
CONTENT1Falha ao receber resposta da extensão.
CONTENT2A extensão foi desabilitada.
CONTENT3Operação não permitida.
BACKGROUND1Falha de configuração de comunicação com o Sign Assistant.
BACKGROUND2Versão de software incompatível.
BACKGROUND3Sistema operacional ainda não suportado.
LIB1Extensão não instalada.
LIB2Os dados para assinar não foram fornecidos.
LIB3Certificado para assinar não foi fornecido.
LIB4O seu navegador ainda não é suportado.
LIB5O seu sistema operacional ainda não é suportado.
LIB6Links de download não fornecidos.

Experiência do usuário​

Após a instalação, alguns passos são necessários para o bom funcionamento da integração e experiência do usuário.

  1. Garantir que o sistema sempre saiba se a extensão e o software estão instalados.
  • Para isso, você pode usar o listener do Objeto.
export const signer = new Signer({
  ...
  onError: (err) => {
    // Você usar a propriedade erro, para identificar se o LedgerSign/SignAssistant não estão instalados
    // Bem como saber se o eles não são suportados pelo sistema operacional/browser
    console.log(err)
  },
  onResponse: (response) => {
    // Você pode usar essa resposta, para identificar a versão do LedgerSign/SignAssistant
    // e/ou ver todos os dados recebidos, e assim garantir que todas as informações sejam expostas aos usuários
    console.log(response)
  },
}
  1. Possibilitar recarregamento dos certificados.
  • É uma boa prática mostrar um botão de recarregar certificados ao lado da seleção do certificado.