miinventario-v2/docs/90-transversal/SEGURIDAD.md

---
id: SEGURIDAD
type: Guide
status: Vigente
version: "1.0.0"
created_date: 2026-01-13
updated_date: 2026-01-13
simco_version: "4.0.0"
author: "Agente Arquitecto de Documentación"
---

# Seguridad - MiInventario

## 1. Resumen de Seguridad

MiInventario implementa múltiples capas de seguridad para proteger datos de usuarios y transacciones financieras.

| Capa | Mecanismo | Estado |
|------|-----------|--------|
| Autenticación | JWT + OTP | Implementado |
| Autorización | RBAC (Roles) | Implementado |
| Datos | Row-Level Security | Implementado |
| Comunicación | HTTPS/TLS | Requerido en producción |
| Inputs | Sanitización | Implementado |

## 2. Autenticación

### 2.1 JWT (JSON Web Tokens)

**Implementación:** `src/modules/auth/strategies/jwt.strategy.ts`

```typescript
// Configuración JWT
{
  secret: process.env.JWT_SECRET,
  signOptions: {
    expiresIn: '15m', // Access token: 15 minutos
  }
}
```

**Flujo de autenticación:**

```
[Usuario] → [Login con teléfono] → [Envío OTP SMS] → [Verificación OTP]
    ↓
[Generación Access Token (15m) + Refresh Token (7d)]
    ↓
[Acceso a recursos protegidos]
```

### 2.2 OTP (One-Time Password)

**Implementación:** `src/modules/auth/services/otp.service.ts`

- Código de 6 dígitos
- Expiración: 5 minutos
- Máximo 3 intentos por código
- Rate limiting: 1 OTP por minuto

### 2.3 Refresh Tokens

**Tabla:** `refresh_tokens`

| Campo | Descripción |
|-------|-------------|
| token | Token hasheado |
| userId | Usuario propietario |
| expiresAt | Fecha de expiración (7 días) |
| revokedAt | Fecha de revocación (nullable) |

## 3. Autorización (RBAC)

### 3.1 Roles del Sistema

| Rol | Nivel | Permisos |
|-----|-------|----------|
| USER | 1 | Acceso básico a su tienda |
| OWNER | 2 | Gestión completa de su tienda |
| OPERATOR | 3 | Operaciones en tiendas asignadas |
| VIEWER | 4 | Solo lectura |
| MODERATOR | 5 | Moderación de contenido |
| ADMIN | 10 | Administración del sistema |
| SUPER_ADMIN | 100 | Acceso total |

### 3.2 Guard de Roles

**Implementación:** `src/common/guards/roles.guard.ts`

```typescript
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN', 'SUPER_ADMIN')
@Get('admin/dashboard')
getDashboard() {
  // Solo accesible por ADMIN y SUPER_ADMIN
}
```

### 3.3 Decorator de Roles

**Implementación:** `src/common/decorators/roles.decorator.ts`

```typescript
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
```

## 4. Row-Level Security (RLS)

### 4.1 Multi-tenancy

Cada tienda (tenant) solo puede acceder a sus propios datos:

```sql
-- Política RLS ejemplo
CREATE POLICY tenant_isolation ON inventory_sessions
  USING (store_id = current_setting('app.current_store_id')::uuid);
```

### 4.2 Verificación de Propiedad

**Implementación en servicios:**

```typescript
async getSession(sessionId: string, userId: string) {
  const session = await this.sessionRepository.findOne({
    where: { id: sessionId },
    relations: ['store', 'store.users'],
  });

  // Verificar que el usuario pertenece a la tienda
  if (!session.store.users.some(u => u.id === userId)) {
    throw new ForbiddenException('No tienes acceso a esta sesión');
  }

  return session;
}
```

## 5. Sanitización de Inputs

### 5.1 Validación con class-validator

**Ejemplo de DTO:**

```typescript
export class CreateStoreDto {
  @IsString()
  @MinLength(3)
  @MaxLength(100)
  @Transform(({ value }) => value.trim())
  name: string;

  @IsOptional()
  @IsString()
  @MaxLength(500)
  @Transform(({ value }) => sanitizeHtml(value))
  description?: string;
}
```

### 5.2 Pipes de Validación

```typescript
// En main.ts
app.useGlobalPipes(new ValidationPipe({
  whitelist: true,        // Elimina campos no definidos
  forbidNonWhitelisted: true, // Error si hay campos extras
  transform: true,        // Transforma tipos automáticamente
}));
```

## 6. Secretos y Variables de Entorno

### 6.1 Variables Sensibles

| Variable | Descripción | Rotación |
|----------|-------------|----------|
| `JWT_SECRET` | Firma de tokens | Trimestral |
| `STRIPE_SECRET_KEY` | API Stripe | Según necesidad |
| `STRIPE_WEBHOOK_SECRET` | Verificación webhooks | Según necesidad |
| `AI_API_KEY` | API de IA | Según necesidad |
| `S3_SECRET_KEY` | Acceso MinIO/S3 | Anual |

### 6.2 Generación de Secrets

```bash
# JWT Secret
openssl rand -base64 32

# Verificar que no hay secrets en código
grep -r "sk_live\|sk_test\|secret" --include="*.ts" src/
```

### 6.3 Archivo .env.example

```bash
# Database
DATABASE_URL=postgresql://user:pass@localhost:5433/db

# Auth
JWT_SECRET=<generar-con-openssl>

# Stripe (usar test keys en desarrollo)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# IA
AI_API_KEY=<api-key>
AI_PROVIDER=openai
```

## 7. Seguridad en Pagos

### 7.1 Stripe Integration

- Nunca almacenar números de tarjeta
- Usar Stripe Elements en frontend
- Validar webhooks con firma

**Verificación de webhook:**

```typescript
const event = stripe.webhooks.constructEvent(
  req.body,
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);
```

### 7.2 Protección Anti-Fraude

- Verificación de transacciones duplicadas
- Límites de monto por transacción
- Logs de auditoría para pagos

## 8. Auditoría

### 8.1 Tabla audit_logs

```sql
CREATE TABLE audit_logs (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  action VARCHAR(50) NOT NULL,
  entity_type VARCHAR(50) NOT NULL,
  entity_id UUID,
  old_values JSONB,
  new_values JSONB,
  ip_address INET,
  user_agent TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);
```

### 8.2 Eventos Auditados

- Login/Logout
- Cambios en permisos
- Transacciones financieras
- Modificación de datos sensibles
- Acceso a reportes

## 9. Headers de Seguridad

```typescript
// En main.ts con Helmet
app.use(helmet({
  contentSecurityPolicy: true,
  crossOriginEmbedderPolicy: true,
  crossOriginOpenerPolicy: true,
  crossOriginResourcePolicy: true,
  dnsPrefetchControl: true,
  frameguard: true,
  hidePoweredBy: true,
  hsts: true,
  ieNoOpen: true,
  noSniff: true,
  referrerPolicy: true,
  xssFilter: true,
}));
```

## 10. Checklist de Seguridad

### Pre-Deploy

- [ ] Variables de entorno configuradas
- [ ] JWT_SECRET rotado desde desarrollo
- [ ] HTTPS habilitado
- [ ] CORS configurado correctamente
- [ ] Rate limiting activo
- [ ] Logs de auditoría funcionando

### Periódico

- [ ] Revisar logs de acceso
- [ ] Rotar secrets (trimestral)
- [ ] Actualizar dependencias
- [ ] Pruebas de penetración (anual)

---

**Documento creado:** 2026-01-13
**Última actualización:** 2026-01-13
**Versión:** 1.0.0