> ## Documentation Index
> Fetch the complete documentation index at: https://camarauth-docs.camarai.es/llms.txt
> Use this file to discover all available pages before exploring further.

# Seguridad

> Prácticas de seguridad en Camarauth SDK

# Seguridad

Camarauth SDK implementa múltiples capas de seguridad para proteger la autenticación de tus usuarios.

## Principios de Seguridad

<CardGroup cols={2}>
  <Card title="Zero Trust" icon="shield-check">
    No confiamos en ningún input hasta validarlo
  </Card>

  <Card title="Defense in Depth" icon="lock-closed">
    Múltiples capas de protección
  </Card>

  <Card title="Least Privilege" icon="key">
    Mínimos privilegios necesarios
  </Card>

  <Card title="Fail Secure" icon="exclamation-triangle">
    Si algo falla, lo hace de forma segura
  </Card>
</CardGroup>

## Capas de Seguridad

### 1. Rate Limiting

Protección contra fuerza bruta y abuso:

```typescript theme={null}
const backend = new CamarauthBackend({
  rateLimit: {
    enabled: true,
    windowMs: 60000,      // 1 minuto
    maxRequests: 100,     // 100 requests
    strictLogin: true     // 5 requests para login
  }
});
```

<Info>
  Rate limiting por IP y endpoint. El endpoint de login tiene límites más estrictos.
</Info>

### 2. Validación de Webhooks

Verificación de firma HMAC para webhooks de Evolution API:

```typescript theme={null}
const backend = new CamarauthBackend({
  webhookSecret: process.env.EVOLUTION_WEBHOOK_SECRET,
  webhookSignatureHeader: 'x-hub-signature-256'
});
```

El backend verifica:

```typescript theme={null}
const expectedSignature = createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');

// Timing-safe comparison
if (!timingSafeEqual(
  Buffer.from(expectedSignature, 'hex'),
  Buffer.from(providedSignature, 'hex')
)) {
  throw new Error('Firma inválida');
}
```

### 3. JWT Seguros

Tokens con expiración y firma:

```typescript theme={null}
// Access token (15 minutos)
const accessToken = jwt.sign(
  { userId, roles },
  JWT_SECRET,
  { 
    expiresIn: '15m',
    issuer: 'camarauth',
    audience: 'camarauth-client'
  }
);

// Refresh token (7 días)
const refreshToken = jwt.sign(
  { userId, type: 'refresh', jti: uuid() },
  JWT_SECRET,
  { expiresIn: '7d' }
);
```

### 4. CORS Estricto

```typescript theme={null}
const backend = new CamarauthBackend({
  corsOrigins: [
    'https://miapp.com',      // Dominio principal
    'https://app.miapp.com',  // Subdominio
    'https://admin.miapp.com' // Panel admin
  ]
});
```

<Warning>
  Nunca uses `*` en producción. Especifica explícitamente los orígenes permitidos.
</Warning>

### 5. Validación de Inputs

Todos los inputs son validados:

```typescript theme={null}
// Validación de PIN
if (!pin || pin.length !== 6) {
  throw new ValidationError('PIN inválido');
}

// Validación de teléfono
if (!/^\+[1-9]\d{1,14}$/.test(phoneNumber)) {
  throw new ValidationError('Teléfono inválido');
}

// Sanitización de queries SQL
const result = await db.query(
  'SELECT * FROM users WHERE id = $1',
  [userId] // Parameterized query
);
```

### 6. Expiración de PINs

Los PINs tienen vida corta por diseño:

```typescript theme={null}
{
  pin: 'ABC123',
  createdAt: Date.now(),
  expiresAt: Date.now() + (3 * 60 * 1000), // 3 minutos
  status: 'pending'
}
```

Beneficios:

* Ventana de ataque reducida
* Fuerza al atacante a actuar rápido
* Limpieza automática de datos antiguos

### 7. HTTPS/TLS

Obligatorio en producción:

```typescript theme={null}
import https from 'https';
import fs from 'fs';

const options = {
  key: fs.readFileSync('/path/to/privkey.pem'),
  cert: fs.readFileSync('/path/to/fullchain.pem')
};

https.createServer(options, app).listen(443);
```

## Headers de Seguridad

```typescript theme={null}
import helmet from 'helmet';

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      connectSrc: ["'self'", "wss:", "https:"],
      imgSrc: ["'self'", "data:", "https:"],
      scriptSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"]
    }
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true
  },
  referrerPolicy: { policy: 'same-origin' }
}));
```

## Almacenamiento Seguro

### JWT en Frontend

```typescript theme={null}
// ❌ No recomendado
localStorage.setItem('token', token);

// ✅ Recomendado - httpOnly cookies
res.cookie('token', token, {
  httpOnly: true,
  secure: true,      // Solo HTTPS
  sameSite: 'strict',
  maxAge: 15 * 60 * 1000  // 15 minutos
});

// O usar memory + refresh token
const storage = createAuthStorage({
  storage: memoryStorage // No persiste en disco
});
```

### Contraseñas y Secrets

```bash theme={null}
# ❌ No hardcodear
const JWT_SECRET = 'mi-secreto';

# ✅ Variables de entorno
const JWT_SECRET = process.env.JWT_SECRET;

# ✅ Longitud mínima
tr -dc 'A-Za-z0-9!@#$%^&*' < /dev/urandom | head -c 64
```

## Auditoría y Logs

```typescript theme={null}
const logger = createProductionLogger();

// Log de eventos de seguridad
logger.info('PIN registrado', {
  pinId: pin.id,
  ip: req.ip,
  userAgent: req.headers['user-agent'],
  timestamp: new Date().toISOString()
});

logger.warn('Rate limit exceeded', {
  ip: req.ip,
  endpoint: req.path,
  attempts: rateLimitData.count
});

logger.error('Invalid webhook signature', {
  ip: req.ip,
  signature: req.headers['x-hub-signature-256']
});
```

## Checklist de Seguridad

<Check>
  ### Backend

  * [ ] JWT\_SECRET de al menos 32 caracteres aleatorios
  * [ ] HTTPS obligatorio en producción
  * [ ] Rate limiting activado
  * [ ] CORS configurado explícitamente
  * [ ] Webhook validation habilitado
  * [ ] Headers de seguridad (helmet)
  * [ ] Validación de todos los inputs
  * [ ] SQL injection prevention (parameterized queries)
  * [ ] Logs de seguridad configurados
  * [ ] Dependencias actualizadas

  ### Frontend

  * [ ] XSS protection (React lo hace automáticamente)
  * [ ] CSRF tokens si usas cookies
  * [ ] No almacenar tokens en localStorage (preferir httpOnly cookies)
  * [ ] Validación de inputs en cliente
  * [ ] HTTPS-only

  ### Infraestructura

  * [ ] Firewall configurado
  * [ ] Base de datos no expuesta a internet
  * [ ] Backups cifrados
  * [ ] Monitoreo de seguridad
  * [ ] Alertas de intrusiones
</Check>

## Vulnerabilidades Comunes y Prevención

### XSS (Cross-Site Scripting)

<CodeGroup>
  ```jsx ❌ Vulnerable theme={null}
  function UserProfile({ user }) {
    return <div dangerouslySetInnerHTML={{ __html: user.bio }} />;
  }
  ```

  ```jsx ✅ Seguro theme={null}
  function UserProfile({ user }) {
    return <div>{user.bio}</div>; // React escapa automáticamente
  }
  ```
</CodeGroup>

### CSRF (Cross-Site Request Forgery)

```typescript theme={null}
// Protección con SameSite cookies
res.cookie('session', token, {
  sameSite: 'strict',  // o 'lax'
  httpOnly: true,
  secure: true
});

// O usar CSRF tokens
app.use(csrf());
```

### SQL Injection

<CodeGroup>
  ```typescript ❌ Vulnerable theme={null}
  const query = `SELECT * FROM users WHERE id = '${userId}'`;
  ```

  ```typescript ✅ Seguro theme={null}
  const query = 'SELECT * FROM users WHERE id = $1';
  const result = await db.query(query, [userId]);
  ```
</CodeGroup>

### Man-in-the-Middle

```typescript theme={null}
// Forzar HTTPS
if (process.env.NODE_ENV === 'production' && !req.secure) {
  return res.redirect(301, `https://${req.headers.host}${req.url}`);
}
```

## Reportar Vulnerabilidades

Si encuentras una vulnerabilidad de seguridad:

1. **NO** abras un issue público
2. Envía un email a: [security@camarauth.com](mailto:security@camarauth.com)
3. Incluye:
   * Descripción del problema
   * Pasos para reproducir
   * Impacto potencial
   * Sugerencias de mitigación (opcional)

<Info>
  Respondemos a reportes de seguridad en menos de 48 horas.
</Info>

## Recursos Adicionales

* [OWASP Top 10](https://owasp.org/www-project-top-ten/)
* [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
* [JWT Best Practices](https://tools.ietf.org/html/rfc8725)