# Modelo de seguridad

Este documento describe la arquitectura de seguridad, el modelo de amenazas y las buenas prácticas del Network-Agnostic Secure Payment Instruction Protocol (NASPIP).

## Arquitectura de seguridad

### Fundamento criptográfico

NASPIP se construye sobre **tokens públicos PASETO v4** con claves Ed25519:

#### Tokens públicos PASETO v4

- **Signing**: Ed25519 vía PASETO v4 (`v4.public.*`)
- **Payload encoding**: Protobuf (no JSON crudo)
- **Claims**: Claims PASETO estándar más `kis`, `kid`, `kep` específicos de NASPIP
- **Purpose**: Integridad y autenticidad de instrucciones de pago (no confidencialidad — los tokens públicos son verificables por cualquiera con la clave pública)

#### Identificación de claves

- **`kis` (key issuer)**: Identifica la entidad emisora de claves (p. ej. `fluxis.us`)
- **`kid` (key ID)**: Selecciona la clave de firma específica para verificación
- **`kep` (key expiration)**: Cuándo expira la propia clave de firma

### Administración de claves

#### Generación de claves

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

#### Buenas prácticas de almacenamiento de claves

1. **Hardware Security Modules (HSM)**: Almacene claves privadas en hardware dedicado
2. **Key Derivation**: Use PBKDF2 o Argon2 para derivación de claves desde contraseñas
3. **Key Rotation**: Implemente procedimientos regulares de rotación de claves
4. **Access Control**: Limite el acceso a claves privadas solo a personal autorizado

## Modelo de amenazas

### Vectores de ataque

NASPIP está diseñado para proteger contra los siguientes vectores de ataque:

#### 1. Manipulación de datos

**Threat**: Modificación maliciosa de instrucciones de pago
**Protection**: Las firmas digitales garantizan integridad de datos
**Mitigation**:

- Todas las instrucciones de pago están firmadas criptográficamente
- La verificación de firma PASETO v4 previene modificaciones no autorizadas
- La codificación protobuf del payload previene bypass de firma vía reordenamiento JSON

#### 2. Ataques de replay

**Threat**: Reutilizar instrucciones de pago válidas múltiples veces
**Protection**: Identificadores únicos y tiempos de expiración
**Mitigation**:

- Cada instrucción de pago tiene un ID único
- Los tiempos de expiración previenen reutilización indefinida
- Validación del estado de pago en el servidor

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

**Threat**: Intercepción y modificación de datos de pago en tránsito
**Protection**: Firmas criptográficas en cada token (PASETO v4)
**Mitigation**:

- Las instrucciones de pago se firman al emitirse con la clave privada del emisor
- Las wallets verifican firmas usando la clave pública del emisor (búsqueda `kis` + `kid`)
- TLS protege el transporte; la verificación de firma protege la integridad del payload independientemente de TLS

#### 4. Ataques de suplantación

**Threat**: Actores maliciosos haciéndose pasar por proveedores de pago legítimos
**Protection**: Verificación de clave pública
**Mitigation**:

- Las claves públicas se usan para verificar autenticidad de la firma
- Verificación de huella de clave
- Certificate pinning para entidades conocidas

#### 5. Ataques de fuerza bruta

**Threat**: Intentar adivinar claves privadas o firmas
**Protection**: Generación de claves criptográficamente segura
**Mitigation**:

- Las claves Ed25519 de 256 bits proporcionan seguridad de 128 bits
- Generación segura de números aleatorios
- Rate limiting en intentos de verificación

### Supuestos de seguridad

La seguridad de NASPIP depende de los siguientes supuestos:

1. **Cryptographic Primitives**: PASETO v4 y Ed25519 son seguros
2. **Random Number Generation**: RNG criptográficamente seguro disponible
3. **Key Management**: Las claves privadas se mantienen seguras por el emisor
4. **Network Transport**: Seguridad de capa de transporte (TLS) para datos en tránsito
5. **Implementation**: Uso correcto de naspip-go o API de Fluxis para firmar/verificar

## Características de seguridad

### 1. Integridad de datos

Cada instrucción de pago se envuelve en un token PASETO v4 public para garantizar que no ha sido 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. Autenticación

Las firmas PASETO v4 proporcionan prueba de origen. Los verificadores resuelven la clave pública del emisor usando `kis` y `kid` de la cadena del token, luego validan la firma PASETO y los claims de expiración. Fluxis realiza esto automáticamente en `POST /v1/naspip/read`.

### 3. No repudio

Las instrucciones de pago no pueden ser negadas por el firmante:

- Las firmas digitales proporcionan prueba matemática de origen
- Las firmas están vinculadas a claves privadas específicas
- Se pueden mantener pistas de auditoría

### 4. Expiración y timeouts

Los tokens de instrucción de pago incluyen claims PASETO `exp` (predeterminado **1 hora**). Los payloads de instrucción también pueden establecer `payment.expires_at`:

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

### 5. Identificadores únicos

Cada instrucción de pago tiene un identificador único para prevenir ataques de replay:

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

### 6. Límite de confianza de payload URL (Fluxis)

Los payloads URL difieren los detalles de pago a un endpoint HTTPS. Cuando Fluxis resuelve una URL durante `POST /v1/naspip/read`:

- La firma del token NASPIP se verifica **antes** de obtener la URL
- La respuesta obtenida reemplaza `payload.data` — los llamadores deben tratar los datos resueltos con la misma validación que payloads de instrucción directos
- Los endpoints URL deben ser URLs de checkout Fluxis de confianza; las URLs arbitrarias se rechazan al fallar la obtención

## Buenas prácticas de seguridad

### Para implementadores

#### 1. Administración de claves

```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. Validación 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. Manejo de errores

```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. Generación aleatoria segura

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

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

### Para usuarios

#### 1. Verificación de clave pública

- Verifique siempre la clave pública de los proveedores de pago
- Use certificate pinning para entidades conocidas
- Compruebe huellas de clave contra fuentes de confianza

#### 2. Validación de expiración

- Compruebe siempre los tiempos de expiración antes de procesar pagos
- Rechace instrucciones de pago expiradas
- Implemente políticas de expiración razonables

#### 3. Validación de importes

- Valide importes de pago en el lado del emisor y del receptor
- Implemente límites mínimos y máximos de importe
- Compruebe rangos de pago razonables

## Auditoría de seguridad

### Lista de verificación de revisión de código

Al revisar implementaciones NASPIP, asegúrese de:

- [ ] Generación criptográficamente segura de números aleatorios
- [ ] Administración y almacenamiento adecuados de claves
- [ ] Validación y sanitización de entradas
- [ ] Manejo seguro de errores
- [ ] Sin datos sensibles en logs
- [ ] Verificación de firma adecuada
- [ ] Validación de tiempo de expiración
- [ ] Generación de identificadores únicos

### Pruebas de seguridad

#### Pruebas automatizadas

```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();
  });
});
```

#### Pruebas de penetración

- Probar vulnerabilidades de bypass de firma
- Intentar ataques de replay
- Probar seguridad de administración de claves
- Validar sanitización de entradas
- Probar manejo de errores por divulgación de información

## Cumplimiento y estándares

### Estándares criptográficos

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

### Marcos de seguridad

- **OWASP Top 10**: Aborda vulnerabilidades comunes de aplicaciones web
- **NIST Cybersecurity Framework**: Enfoque de gestión de riesgos
- **ISO 27001**: Gestión de seguridad de la información

## Respuesta a incidentes

### Tipos de incidentes de seguridad

1. **Key Compromise**: Exposición de clave privada
2. **Signature Bypass**: Elusión de verificación de firma
3. **Replay Attack**: Reutilización exitosa de instrucciones de pago
4. **Implementation Vulnerability**: Bugs en operaciones criptográficas

### Procedimientos de respuesta

1. **Immediate Actions**:

   - Revocar claves comprometidas
   - Generar nuevos pares de claves
   - Actualizar registros de claves públicas
   - Notificar a las partes afectadas

2. **Investigation**:

   - Analizar vectores de ataque
   - Revisar logs y pistas de auditoría
   - Identificar causas raíz
   - Evaluar alcance del impacto

3. **Recovery**:
   - Implementar parches de seguridad
   - Actualizar procedimientos de seguridad
   - Realizar capacitación de seguridad
   - Monitorear ataques similares

## Consideraciones de seguridad futuras

### Criptografía post-cuántica

A medida que avanza la computación cuántica, NASPIP puede necesitar transicionar a algoritmos resistentes a cuántica:

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

### Características de seguridad avanzadas

- **Multi-signature support**: Requerir múltiples firmas para pagos de alto valor
- **Threshold signatures**: Generación y firma distribuida de claves
- **Zero-knowledge proofs**: Verificación de pago preservando privacidad
- **Hardware security**: Integración TPM/HSM

## Recursos

- [Protocol Specification](/es/docs/key-concepts/naspip/protocol-specification)
- [Implementation Guide](/es/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)