# Modelo de segurança

Este documento descreve a arquitetura de segurança, o modelo de ameaças e as boas práticas do Network-Agnostic Secure Payment Instruction Protocol (NASPIP).

## Arquitetura de segurança

### Fundamento criptográfico

NASPIP é construído sobre **tokens públicos PASETO v4** com chaves Ed25519:

#### Tokens públicos PASETO v4

- **Signing**: Ed25519 via PASETO v4 (`v4.public.*`)
- **Payload encoding**: Protobuf (não JSON bruto)
- **Claims**: Claims PASETO padrão mais `kis`, `kid`, `kep` específicos do NASPIP
- **Purpose**: Integridade e autenticidade de instruções de pagamento (não confidencialidade — tokens públicos são verificáveis por qualquer pessoa com a chave pública)

#### Identificação de chaves

- **`kis` (key issuer)**: Identifica a entidade emissora de chaves (ex.: `fluxis.us`)
- **`kid` (key ID)**: Seleciona a chave de assinatura específica para verificação
- **`kep` (key expiration)**: Quando a própria chave de assinatura expira

### Gerenciamento de chaves

#### Geração de chaves

```javascript
// Secure key generation using cryptographically secure random number generator
const keyPair = await crypto.subtle.generateKey(
  {
    name: "Ed25519",
  },
  true, // extractable
  ["sign", "verify"],
);
```

#### Boas práticas de armazenamento de chaves

1. **Hardware Security Modules (HSM)**: Armazene chaves privadas em hardware dedicado
2. **Key Derivation**: Use PBKDF2 ou Argon2 para derivação de chaves a partir de senhas
3. **Key Rotation**: Implemente procedimentos regulares de rotação de chaves
4. **Access Control**: Limite o acesso a chaves privadas apenas a pessoal autorizado

## Modelo de ameaças

### Vetores de ataque

NASPIP foi projetado para proteger contra os seguintes vetores de ataque:

#### 1. Manipulação de dados

**Threat**: Modificação maliciosa de instruções de pagamento
**Protection**: Assinaturas digitais garantem integridade dos dados
**Mitigation**:

- Todas as instruções de pagamento são assinadas criptograficamente
- A verificação de assinatura PASETO v4 impede modificações não autorizadas
- A codificação protobuf do payload impede bypass de assinatura via reordenação JSON

#### 2. Ataques de replay

**Threat**: Reutilizar instruções de pagamento válidas múltiplas vezes
**Protection**: Identificadores únicos e tempos de expiração
**Mitigation**:

- Cada instrução de pagamento tem um ID único
- Tempos de expiração impedem reutilização indefinida
- Validação de status de pagamento no servidor

#### 3. Ataques Man-in-the-Middle (MITM)

**Threat**: Interceptação e modificação de dados de pagamento em trânsito
**Protection**: Assinaturas criptográficas em cada token (PASETO v4)
**Mitigation**:

- Instruções de pagamento são assinadas na emissão com a chave privada do emissor
- Wallets verificam assinaturas usando a chave pública do emissor (busca `kis` + `kid`)
- TLS protege o transporte; a verificação de assinatura protege a integridade do payload independentemente do TLS

#### 4. Ataques de impersonação

**Threat**: Atores maliciosos se passando por provedores de pagamento legítimos
**Protection**: Verificação de chave pública
**Mitigation**:

- Chaves públicas são usadas para verificar autenticidade da assinatura
- Verificação de fingerprint de chave
- Certificate pinning para entidades conhecidas

#### 5. Ataques de força bruta

**Threat**: Tentar adivinhar chaves privadas ou assinaturas
**Protection**: Geração de chaves criptograficamente segura
**Mitigation**:

- Chaves Ed25519 de 256 bits fornecem segurança de 128 bits
- Geração segura de números aleatórios
- Rate limiting em tentativas de verificação

### Premissas de segurança

A segurança do NASPIP depende das seguintes premissas:

1. **Cryptographic Primitives**: PASETO v4 e Ed25519 são seguros
2. **Random Number Generation**: RNG criptograficamente seguro disponível
3. **Key Management**: Chaves privadas são mantidas seguras pelo emissor
4. **Network Transport**: Segurança de camada de transporte (TLS) para dados em trânsito
5. **Implementation**: Uso correto de naspip-go ou API Fluxis para assinar/verificar

## Recursos de segurança

### 1. Integridade de dados

Cada instrução de pagamento é envolvida em um token PASETO v4 public para garantir que não foi manipulada:

```javascript
// Verification via Fluxis API (recommended)
const response = await fetch("https://api.fluxis.us/v1/naspip/read", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "x-fluxis-api-key": "<api_key_id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token: naspipToken }),
});
// PASETO signature is verified server-side; invalid tokens return MD0004/MD0006
```

### 2. Autenticação

Assinaturas PASETO v4 fornecem prova de origem. Verificadores resolvem a chave pública do emissor usando `kis` e `kid` da string do token, depois validam a assinatura PASETO e os claims de expiração. A Fluxis faz isso automaticamente em `POST /v1/naspip/read`.

### 3. Não repúdio

Instruções de pagamento não podem ser negadas pelo signatário:

- Assinaturas digitais fornecem prova matemática de origem
- Assinaturas estão vinculadas a chaves privadas específicas
- Trilhas de auditoria podem ser mantidas

### 4. Expiração e timeouts

Tokens de instrução de pagamento incluem claims PASETO `exp` (padrão **1 hora**). Payloads de instrução também podem definir `payment.expires_at`:

```json
{
  "payment": {
    "expires_at": 1759397652
  }
}
```

### 5. Identificadores únicos

Cada instrução de pagamento tem um identificador único para impedir ataques de replay:

```json
{
  "payment": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### 6. Limite de confiança de payload URL (Fluxis)

Payloads URL adiam detalhes de pagamento para um endpoint HTTPS. Quando a Fluxis resolve uma URL durante `POST /v1/naspip/read`:

- A assinatura do token NASPIP é verificada **antes** da busca da URL
- A resposta obtida substitui `payload.data` — chamadores devem tratar dados resolvidos com a mesma validação que payloads de instrução diretos
- Endpoints URL devem ser URLs de checkout Fluxis confiáveis; URLs arbitrárias são rejeitadas em caso de falha na busca

## Boas práticas de segurança

### Para implementadores

#### 1. Gerenciamento de chaves

```javascript
// ✅ Good: Use secure key generation
const keyPair = await crypto.subtle.generateKey({ name: "Ed25519" }, true, [
  "sign",
  "verify",
]);

// ❌ Bad: Don't use predictable keys
const predictableKey = "my-secret-key-123";
```

#### 2. Validação de entrada

```javascript
// ✅ Good: Validate all inputs
function validatePaymentInstruction(instruction) {
  if (!instruction.amount || !instruction.amount.value) {
    throw new Error("Amount is required");
  }
  if (parseFloat(instruction.amount.value) <= 0) {
    throw new Error("Amount must be positive");
  }
  // ... more validation
}

// ❌ Bad: Trusting input without validation
function processPayment(instruction) {
  // Process without validation
  return process(instruction);
}
```

#### 3. Tratamento de erros

```javascript
// ✅ Good: Don't expose sensitive information
try {
  const result = await verifySignature(token, publicKey);
  return result;
} catch (error) {
  // Log internally for debugging
  logger.error('Signature verification failed', { error: error.message });
  // Return generic error to user
  throw new Error('Invalid payment instruction');
}

// ❌ Bad: Exposing internal details
catch (error) {
  throw new Error(`Signature verification failed: ${error.stack}`);
}
```

#### 4. Geração aleatória segura

```javascript
// ✅ Good: Use cryptographically secure random
const uniqueId = crypto.randomBytes(16).toString("hex");

// ❌ Bad: Using predictable values
const uniqueId = Date.now().toString();
```

### Para usuários

#### 1. Verificação de chave pública

- Sempre verifique a chave pública dos provedores de pagamento
- Use certificate pinning para entidades conhecidas
- Confira fingerprints de chave contra fontes confiáveis

#### 2. Validação de expiração

- Sempre verifique tempos de expiração antes de processar pagamentos
- Rejeite instruções de pagamento expiradas
- Implemente políticas de expiração razoáveis

#### 3. Validação de valores

- Valide valores de pagamento no lado do remetente e do receptor
- Implemente limites mínimos e máximos de valor
- Verifique faixas de pagamento razoáveis

## Auditoria de segurança

### Checklist de revisão de código

Ao revisar implementações NASPIP, certifique-se de:

- [ ] Geração criptograficamente segura de números aleatórios
- [ ] Gerenciamento e armazenamento adequados de chaves
- [ ] Validação e sanitização de entradas
- [ ] Tratamento seguro de erros
- [ ] Sem dados sensíveis em logs
- [ ] Verificação de assinatura adequada
- [ ] Validação de tempo de expiração
- [ ] Geração de identificadores únicos

### Testes de segurança

#### Testes automatizados

```javascript
describe("NASPIP Security", () => {
  test("should reject tampered data", async () => {
    const token = await createValidToken();
    const tamperedToken = token.replace("100.00", "1000.00");

    await expect(verifyToken(tamperedToken)).rejects.toThrow();
  });

  test("should reject expired tokens", async () => {
    const expiredToken = await createExpiredToken();

    await expect(verifyToken(expiredToken)).rejects.toThrow();
  });

  test("should reject invalid signatures", async () => {
    const invalidToken = "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.invalid";

    await expect(verifyToken(invalidToken)).rejects.toThrow();
  });
});
```

#### Testes de penetração

- Testar vulnerabilidades de bypass de assinatura
- Tentar ataques de replay
- Testar segurança de gerenciamento de chaves
- Validar sanitização de entradas
- Testar tratamento de erros por divulgação de informações

## Conformidade e padrões

### Padrões criptográficos

- **Ed25519**: RFC 8032
- **SHA-256**: FIPS 180-4
- **Random Number Generation**: NIST SP 800-90A

### Frameworks de segurança

- **OWASP Top 10**: Aborda vulnerabilidades comuns de aplicações web
- **NIST Cybersecurity Framework**: Abordagem de gestão de riscos
- **ISO 27001**: Gestão de segurança da informação

## Resposta a incidentes

### Tipos de incidentes de segurança

1. **Key Compromise**: Exposição de chave privada
2. **Signature Bypass**: Contorno da verificação de assinatura
3. **Replay Attack**: Reutilização bem-sucedida de instruções de pagamento
4. **Implementation Vulnerability**: Bugs em operações criptográficas

### Procedimentos de resposta

1. **Immediate Actions**:

   - Revogar chaves comprometidas
   - Gerar novos pares de chaves
   - Atualizar registros de chaves públicas
   - Notificar partes afetadas

2. **Investigation**:

   - Analisar vetores de ataque
   - Revisar logs e trilhas de auditoria
   - Identificar causas raiz
   - Avaliar escopo do impacto

3. **Recovery**:
   - Implementar patches de segurança
   - Atualizar procedimentos de segurança
   - Realizar treinamento de segurança
   - Monitorar ataques similares

## Considerações de segurança futuras

### Criptografia pós-quântica

À medida que a computação quântica avança, o NASPIP pode precisar transicionar para algoritmos resistentes a quântica:

- **Lattice-based cryptography**: NTRU, LWE
- **Hash-based signatures**: SPHINCS+
- **Code-based cryptography**: McEliece

### Recursos de segurança avançados

- **Multi-signature support**: Exigir múltiplas assinaturas para pagamentos de alto valor
- **Threshold signatures**: Geração e assinatura distribuída de chaves
- **Zero-knowledge proofs**: Verificação de pagamento preservando privacidade
- **Hardware security**: Integração TPM/HSM

## Recursos

- [Protocol Specification](/pt/docs/key-concepts/naspip/protocol-specification)
- [Implementation Guide](/pt/docs/key-concepts/naspip/implementation-guide)
- [OWASP Cryptographic Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html)
- [NIST Cryptographic Standards](https://www.nist.gov/cryptography)
- [RFC 8032 - Ed25519](https://tools.ietf.org/html/rfc8032)