TEC-007 — Cifrado en reposo de precios, montos y datos de proveedor
Implementación de la mejora TEC-007 (Cifrado en Reposo), dentro de 6.2 Seguridad y de la Fase 2. Hasta ahora los importes del módulo vivían en claro en la base: cualquier respaldo o consulta directa los mostraba tal cual.
📋 Alcance
| RF | Entregable |
|---|---|
| RF-TEC-007-01 | 23 columnas cifradas: precios, costos, montos, umbrales y los datos de contacto e identificación del proveedor |
| RF-TEC-007-02 | AES-256-GCM con formato versionado v1:iv:tag:cifrado y etiqueta de autenticación |
| RF-TEC-007-03 | Claves centralizadas en un único servicio, por ámbito, con versionado y rotación sin corte |
| RF-TEC-007-04 | Solo el API descifra; la visibilidad por rol decide qué usuario recibe el dato |
🤔 El problema difícil no era cifrar, sino seguir sumando
Cifrar un precio es trivial. Lo complicado es que 16 consultas de PostgreSQL hacen aritmética con él:
SUM(sa.stock_actual * p.precio_unitario) -- valorización de inventario
SUM(unidades * precio_unitario) AS valor -- series de consumo
Un ::numeric sobre ciphertext lanza excepción: el cifrado «a secas» habría tumbado REP-001,
REP-002, REP-005, REP-006, INV-008 y el bloqueo presupuestal de SOL-002/003.
La solución: un mapa de precios parametrizado
El API descifra los precios una vez y los envía a la consulta como un parámetro jsonb:
WITH precios_map AS (
SELECT * FROM jsonb_to_recordset($7::jsonb) AS x(id_producto integer, precio numeric)
)
SELECT ..., COALESCE(SUM(unidades * pm.precio), 0) AS valor
FROM filtrado
JOIN precios_map pm ON pm.id_producto = id_producto
Así la suma, la agrupación y el orden siguen ocurriendo en PostgreSQL (nada de traer filas a
memoria para totalizar), el precio nunca aparece como columna en la consulta, y el descifrado
queda concentrado en un solo punto. El índice del parámetro es un argumento de la CTE compartida,
porque REP-006 ya usa $7/$8 para lo suyo.
🔐 Gestión de claves
| Aspecto | Decisión |
|---|---|
| Ámbitos | datos (negocio) y 2fa (TOTP) con claves distintas: la misma clave no sirve para dos usos |
| Origen | Variables de entorno; no se derivan de JWT_SECRET (como hacía el 2FA antes) |
| Arranque | Sin clave, la API no arranca: falla en lugar de operar insegura |
| Formato | v1:iv:tag:cifrado, con el IV distinto en cada escritura |
| Rotación | *_KEY_ANTERIOR permite leer lo viejo mientras se re-cifra con la nueva |
👁️ Quién ve los importes
El cifrado protege el dato en la base; la visibilidad decide qué usuario lo recibe:
| Rol | Importes | Contacto del proveedor |
|---|---|---|
| Administrador, Almacenista | ✅ | ✅ |
| Auxiliar inventario, Auditor | ✅ | ❌ |
| Usuario Interno | ❌ | ❌ |
A quien no está autorizado el API omite el campo (no lo manda en cero) y la web muestra
«—». Omitir y no enmascarar es intencional: un 0 sería un dato falso en un reporte.
✅ Verificación contra la base real
No bastaba con que las pruebas unitarias pasaran: había que demostrar que ningún número cambió.
| Comprobación | Resultado |
|---|---|
| Importes vs línea base (12 endpoints) | 118/118 idénticos |
| Importes tras rotar la clave | 118/118 idénticos |
| Nada en claro en las 23 columnas | 0 valores |
| Migración + cifrado del dato heredado | 432 filas, 0 pendientes |
| Suite completa del API | 683 pruebas, 70 suites, verde |
Dos hallazgos que solo aparecieron al verificar de verdad
- La rotación de clave no re-cifraba nada. El script solo cubría «texto plano → cifrado»; al
rotar informaba «432 pendientes» y no escribía. Retirar entonces la clave anterior habría
dejado esos datos ilegibles para siempre. Ahora completa la rotación y termina con código
1 si queda algo pendiente, para detener el despliegue antes de perder datos. Se probó en
ambos sentidos (
v1 → v2 → v1) sobre los datos reales. - Un campo sensible anidado se filtraba. El interceptor omitía por nombre solo si el valor no
era un objeto, así que un
contactoque fuese objeto sobrevivía al filtro.
⚠️ Limitaciones asumidas
- La búsqueda de proveedores por NIT o contacto ya no puede hacerse en SQL (el dato está cifrado): se filtra en memoria sobre las filas descifradas, asumible porque el catálogo son decenas de filas. Si creciera, la salida es un índice ciego (HMAC determinista).
- El nombre del producto y del proveedor no se cifran: se ordenan y filtran en SQL.
- Perder la clave activa y todas las anteriores equivale a perder esos datos. Es la contrapartida de que un respaldo robado no sirva de nada: las claves van al gestor de secretos, nunca junto al respaldo.
- La rotación es un procedimiento con orden obligatorio (documentado paso a paso en el manual); retirar la clave anterior antes de re-cifrar es irreversible.
