npm package: @fastsoftbr/security-sdk
Description: FastSoft Security SDK
Author: FastSoft
Latest version: 1.0.2

<p align="center">
  <a href="https://fastsoftbrasil.com" rel="noopener">
    <img width=256px height=55px src="https://cdn.fastsoftbrasil.com/logo.png" alt="FastSoft logo">
  </a>
</p>

<h1 align="center">FastSoft Security SDK</h1>

<p align="center">
  SDK de tokenização de cartões com integração para sistemas antifraude
</p>

---

## 📝 Tabela de Conteúdos

- [Sobre](#-sobre)
- [Funcionalidades](#-funcionalidades)
- [Instalação](#-instalação)
- [Guia de Uso](#-guia-de-uso)
  - [Configuração Básica](#configuração-básica)
  - [Tokenização de Cartão](#tokenização-de-cartão)
  - [Ambientes](#ambientes)
- [API de Referência](#-api-de-referência)
- [Características do Token](#-características-do-token)
- [Segurança](#-segurança)
- [Validações Implementadas](#-validações-implementadas)
- [Compatibilidade](#-compatibilidade)
- [Suporte](#-suporte)
- [FAQ](#-perguntas-frequentes)

## 🧐 Sobre

O FastSoft Security SDK uma biblioteca de segurança criada pela FastSoft que permite a tokenização de dados de cartão de crédito de maneira segura e eficiente. Além disso, coleta o fingerprint do dispositivo do consumidor para integração com sistemas de antifraude, aumentando a segurança das transações e reduzindo o risco de fraudes.

O SDK foi desenvolvido especificamente para adicionar uma camada extra de segurança e validação nos gateways de pagamento que utilizam a tecnologia white label da FastSoft. Essa abordagem permite que os gateways parceiros ofereçam proteção avançada contra fraudes sem precisarem desenvolver e manter sua própria infraestrutura de segurança.

## ⚡ Funcionalidades

| Funcionalidade                           | Status | Descrição                                                                      |
| ---------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| Tokenização de Cartão                 | ✅     | Criptografa dados sensíveis do cartão utilizando algoritmos de alta segurança |
| Fingerprint do Dispositivo               | ✅     | Coleta informações do dispositivo do consumidor para análise antifraude       |
| Integração com Antifraude              | ✅     | Envia dados anonimizados para análise de risco em tempo real                    |
| Compatibilidade com Múltiplos Ambientes | ✅     | Funciona perfeitamente em navegadores modernos e diferentes frameworks           |

## 💻 Instalação

A biblioteca pode ser instalada e utilizada de diversas formas, escolha a que melhor se adapta ao seu projeto:

### Via CDN (Recomendado para Integrações Rápidas)

```html
<script src="https://js.fastsoftbrasil.com/fastsoft.min.js"></script>
```

### Via NPM

```bash
npm install @fastsoftbr/security-sdk --save
```

### Via Yarn

```bash
yarn add @fastsoftbr/security-sdk
```

### Via PNPM

```bash
pnpm add @fastsoftbr/security-sdk
```

## 🚀 Guia de Uso

### Configuração Básica

Antes de utilizar o SDK, você precisa configurar sua chave pública obtida no painel da FastSoft:

```javascript
// Configure a chave pública (obrigatório)
await fastsoft.setPublicKey('sua_chave_publica_aqui');
```

### Tokenização de Cartão

```javascript
// Dados do cartão a serem tokenizados
const card = {
  number: '4111111111111111',     // Número do cartão
  holderName: 'NOME COMPLETO',    // Nome completo impresso no cartão
  expMonth: '12',                 // Mês de expiração (1-12)
  expYear: '2030',                // Ano de expiração (formato de 4 dígitos)
  cvv: '123'                      // Código de segurança
};

// Tokenizar os dados
const cardToken = await fastsoft.encrypt(card);

// O resultado será um token que pode ser enviado com segurança ao seu servidor
console.log('Token do cartão:', cardToken);
```

### Ambientes

O SDK suporta dois ambientes:

- **Produção**: Ambiente padrão, utilizado para transações reais
- **Sandbox**: Ambiente de testes, para desenvolvimento e homologação

Para utilizar o ambiente de sandbox:

```javascript
// Configura o SDK para utilizar o ambiente de desenvolvimento
fastsoft.setProductionOff();
```

## 📚 API de Referência

### Métodos Principais

#### `setPublicKey(key: string): Promise<void>`

- **Descrição**: Configura a chave pública para uso da API
- **Parâmetros**:
  - `key` (string): Chave pública fornecida pela FastSoft
- **Retorno**: Promise que resolve quando a configuração for concluída
- **Exemplo**:
  ```javascript
  await fastsoft.setPublicKey('pk_abcdefghijklmn');
  ```

#### `setProductionOff(): void`

- **Descrição**: Configura o SDK para utilizar o ambiente de desenvolvimento (sandbox)
- **Parâmetros**: Nenhum
- **Retorno**: Void
- **Exemplo**:
  ```javascript
  fastsoft.setProductionOff();
  ```

#### `encrypt(card: CardData): Promise<string>`

- **Descrição**: Criptografa dados do cartão e retorna um token seguro
- **Parâmetros**:
  - `card` (objeto): Dados do cartão com as seguintes propriedades:
    - `number` (string): Número do cartão
    - `holderName` (string): Nome do titular como impresso no cartão
    - `expMonth` (string): Mês de expiração (1-12)
    - `expYear` (string): Ano de expiração (formato de 4 dígitos)
    - `cvv` (string): Código de segurança
- **Retorno**: Promise que resolve com o token do cartão
- **Exemplo**:
  ```javascript
  const cardToken = await fastsoft.encrypt({
    number: '4111111111111111',
    holderName: 'NOME COMPLETO',
    expMonth: '12',
    expYear: '2030',
    cvv: '123'
  });
  ```

## 🎫 Características do Token

Os tokens gerados pelo SDK possuem as seguintes características de segurança:

- **Tempo de Expiração**: O token expira automaticamente após 5 minutos da sua geração
- **Uso Único**: Cada token só pode ser utilizado uma única vez para processamento
- **Ambiente-específico**: Tokens gerados em ambiente de sandbox não funcionam em produção e vice-versa
- **Validação no Servidor**: Os tokens são validados novamente nos servidores da FastSoft antes do processamento da transação

## 🔒 Segurança

A biblioteca implementa diversas camadas de segurança para garantir a proteção dos dados sensíveis:

- ✅ **Validação Completa dos Dados**: Validação extensiva de todos os campos do cartão
- ✅ **Criptografia de Ponta a Ponta**: Dados sensíveis são criptografados antes de sair do dispositivo do usuário
- ✅ **Integração com Sistema Antifraude**: Coleta de dados comportamentais e de dispositivo para análise de risco
- ✅ **Carregamento Dinâmico de Scripts**: Scripts de segurança são carregados sob demanda e apenas quando necessário
- ✅ **Verificação de Ambiente**: Sistema de prevenção que impede o carregamento dos scripts de segurança fora de um navegador
- ✅ **Conformidade PCI**: Implementação seguindo as melhores práticas de segurança PCI DSS
- ✅ **Sem Armazenamento Local**: Nenhum dado sensível é armazenado localmente

## 🔍 Validações Implementadas

O SDK realiza as seguintes validações antes da tokenização:

- 💳 **Número do Cartão**: Validação do algoritmo Luhn
- 👤 **Nome do Titular**: Verificação de caracteres válidos e remoção de caracteres especiais
- 📅 **Data de Expiração**: Validação de formato e verificação de data válida e não expirada
  - Mês de expiração deve ter no máximo 2 caracteres (1-12)
  - Ano de expiração deve ter exatamente 4 caracteres e ser maior ou igual ao ano atual
- 🔐 **CVV**: Validação de comprimento (3-4 caracteres) e formato numérico

## 💻 Compatibilidade

O SDK é compatível com:

- **Navegadores**: Chrome, Firefox, Safari, Edge (versões recentes)
- **Frameworks**: React, Vue, Angular, Vanilla JS
- **Plataformas**: Web, PWA, Webviews em aplicativos móveis
- **Versões JavaScript**: ES5+, com suporte para importação via CommonJS e ESModules

## 💬 Suporte

Para mais informações ou suporte técnico:

- 🌐 **Website**: [https://fastsoftbrasil.com](https://fastsoftbrasil.com)
- 📚 **Documentação Completa**: [https://developers.fastsoftbrasil.com](https://developers.fastsoftbrasil.com)
- 📧 **Suporte Técnico**: [suporte@fastsoftbrasil.com](mailto:suporte@fastsoftbrasil.com)
- 🔧 **Status dos Serviços**: [https://status.fastsoftbrasil.com](https://status.fastsoftbrasil.com)

## ❓ Perguntas Frequentes

### Como saber se o token foi gerado corretamente?

O método `encrypt()` retorna uma Promise que, quando resolvida com sucesso, contém o token. Caso ocorra algum erro, a Promise será rejeitada com uma mensagem de erro descritiva.

### É possível usar o SDK em ambientes Node.js?

O SDK foi projetado principalmente para uso em navegadores. Em ambientes Node.js, o SDK detectará automaticamente que não está em um navegador e algumas funcionalidades relacionadas à coleta de fingerprint do dispositivo serão limitadas.

### O que acontece se um campo do cartão estiver inválido?

O SDK realizará validações e retornará um erro específico indicando qual campo está inválido e o motivo.

### É necessário implementar autenticação 3D Secure?

Não, a autenticação 3D Secure é gerenciada separadamente pelo gateway de pagamento. O SDK da FastSoft cuida apenas da tokenização segura dos dados do cartão. No entanto, estamos atualmente desenvolvendo suporte nativo para 3DS, que estará disponível em uma versão futura da SDK.

---

<div align="center">
  <sub>Desenvolvido com ❤️ pela equipe FastSoft</sub>
  <br>
  <sub>© FastSoft Brasil - Todos os direitos reservados</sub>
</div>