Encriptación

Manejo de datos sensibles

Copy page

Este documento explica la implementación de encriptación a nivel de base de datos usando PostgreSQL's pgcrypto extension en el proyecto Brein API.

Tabla de Contenidos

1. Introducción
2. Arquitectura
3. Componentes Principales
4. Flujo de Encriptación/Desencriptación
5. Cómo Aplicar Encriptación a una Nueva Entidad
6. Ejemplos de Entidades con Encriptación
7. Mejores Prácticas
8. Troubleshooting

---

Introducción

La encriptación se implementa a nivel de base de datos usando la extensión pgcrypto de PostgreSQL. Los datos sensibles se almacenan encriptados en columnas de tipo bytea y se desencriptan automáticamente al consultarlos.

Características Principales

• Encriptación transparente: Los datos se encriptan automáticamente antes de guardarse y se desencriptan al consultarlos
• A nivel de base de datos: La encriptación/desencriptación ocurre en PostgreSQL, no en la aplicación
• Detección automática: El sistema detecta automáticamente qué campos deben encriptarse
• Sin cambios en servicios: Los servicios trabajan con datos planos, la encriptación es transparente

Entidades con Encriptación Actual

• User: email, firstName, lastName, secondLastName, phone
• Parent: name, lastName, secondLastName, phone
• Student: bloodType, birthDate, firstName, lastName, secondLastName, genre
• Teacher: firstName, lastName, secondLastName, birthDate
• Administrative: firstName, lastName, secondLastName, birthDate
• SchoolAdministrator: firstName, lastName, secondLastName
• TrustedPeople: name, paternalLastName, maternalLastName, phone, slugImage, genre
• Address: formattedAddress
• TrustedAddress: alias

---

Arquitectura

Code
 
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  (Services trabajan con datos planos)                        │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              TypeORM Entity Layer                            │
│  - pgcryptoTransformer (conversión bytea ↔ string)         │
│  - PgcryptoEntitySubscriber (encriptación automática)      │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Repository Layer                                │
│  - PgcryptoQueryUtil (desencriptación en SELECT/WHERE)     │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Database Layer (PostgreSQL)                    │
│  - pgcrypto extension                                       │
│  - Columnas tipo bytea con datos encriptados                │
└─────────────────────────────────────────────────────────────┘

---

Componentes Principales

1. pgcryptoTransformer (src/commons/transformers/pgcrypto.transformer.ts)

Propósito: Convierte entre bytea (Buffer) y string para TypeORM.

Code
 
export const pgcryptoTransformer: ValueTransformer = {
  to(value: string | null): string | null {
    // Retorna el valor tal cual - la encriptación se hace en el subscriber
    if (value == null) return value
    return value
  },
  from(value: Buffer | string | null): string | null {
    // Convierte Buffer a string cuando TypeORM lee de la BD
    if (value == null) return value
    if (Buffer.isBuffer(value)) {
      return value.toString('utf8')
    }
    return value.toString()
  },
}

Uso: Se aplica en el decorador @Column de las entidades.

2. PgcryptoEntitySubscriber (src/commons/subscribers/pgcrypto.entity-subscriber.ts)

Propósito: Detecta automáticamente campos con pgcryptoTransformer y los encripta antes de INSERT o UPDATE.

Características:

• Se ejecuta automáticamente antes de cada insert() o update()
• Detecta automáticamente qué campos tienen pgcryptoTransformer
• No requiere configuración manual por entidad
• Usa PgcryptoEntityUtil para encriptar los valores

Registro: Se registra automáticamente en typeorm.config.ts:

Code
 
subscribers: [`${__dirname}/**/**/*.entity-subscriber{.ts,.js}`]

3. PgcryptoEntityUtil (src/commons/utils/pgcrypto-entity.util.ts)

Propósito: Utilidad para encriptar valores usando pgp_sym_encrypt a través del EntityManager.

Métodos principales:

• encryptValueWithManager(): Encripta un valor individual
• encryptEntityFields(): Encripta múltiples campos de una entidad

4. PgcryptoQueryUtil (src/commons/utils/pgcrypto-query.util.ts)

Propósito: Utilidad para desencriptar campos en queries de TypeORM.

Métodos principales:

• decryptField(): Genera expresión SQL para desencriptar un campo
• addDecryptedFieldToSelect(): Agrega campo desencriptado al SELECT
• addDecryptedFieldsToSelect(): Agrega múltiples campos desencriptados
• whereDecryptedField(): Genera condición WHERE con campo desencriptado
• addDecryptedUserFields(), addDecryptedParentFields(), etc.: Métodos helper para entidades específicas

Ejemplo de uso:

Code
 
// En un repository
const queryBuilder = this.createQueryBuilder('user')
PgcryptoQueryUtil.addDecryptedUserFields(queryBuilder, 'user')
queryBuilder.andWhere(PgcryptoQueryUtil.whereDecryptedField('user', 'phone', '='), { value: phone })

---

Flujo de Encriptación/Desencriptación

Al Guardar (INSERT/UPDATE)

1. Service crea/actualiza entidad con datos planos:

   Code
    
   const user = new User()
   user.email = 'user@example.com'
   user.firstName = 'John'
   await this.userRepository.save(user)

2. PgcryptoEntitySubscriber intercepta el evento beforeInsert/beforeUpdate:

   • Detecta que email y firstName tienen pgcryptoTransformer
   • Llama a PgcryptoEntityUtil.encryptEntityFields()

3. PgcryptoEntityUtil encripta los valores:

   • Ejecuta SELECT pgp_sym_encrypt($1, $2) para cada campo
   • Reemplaza los valores planos con Buffer encriptados

4. TypeORM guarda los Buffer en columnas bytea

Al Consultar (SELECT)

1. Repository construye query con desencriptación:

   Code
    
   const query = this.createQueryBuilder('user')
   PgcryptoQueryUtil.addDecryptedUserFields(query, 'user')

2. PgcryptoQueryUtil agrega campos desencriptados al SELECT:

   Code
    
   SELECT
     user.id,
     pgp_sym_decrypt(user.email, 'key')::text AS user_email,
     pgp_sym_decrypt(user.first_name, 'key')::text AS user_first_name
   FROM user

3. PostgreSQL ejecuta la query y retorna valores desencriptados

4. TypeORM mapea los resultados a la entidad usando pgcryptoTransformer.from()

5. Service recibe entidad con datos planos

---

Cómo Aplicar Encriptación a una Nueva Entidad

Paso 1: Actualizar la Entidad

Agregar type: 'bytea' y transformer: pgcryptoTransformer a los campos sensibles:

Code
 
import { pgcryptoTransformer } from '../../../commons/transformers/pgcrypto.transformer'

@Entity()
export class MyEntity extends EntityBase {
  @Column({ type: 'bytea', transformer: pgcryptoTransformer })
  sensitiveField: string

  @Column({ type: 'bytea', nullable: true, transformer: pgcryptoTransformer })
  optionalSensitiveField?: string
}

Importante:

• Siempre usar type: 'bytea' para columnas encriptadas
• El transformer es necesario para la conversión Buffer ↔ string
• El subscriber detectará automáticamente estos campos

Paso 2: Crear la Migración

Crear una migración para:

1. Habilitar la extensión pgcrypto (si no existe)
2. Cambiar el tipo de columna a bytea
3. Encriptar los datos existentes

Ejemplo:

Code
 
import 'dotenv/config'
import { MigrationInterface, QueryRunner } from 'typeorm'

export class EncryptMyEntityFields1234567890000 implements MigrationInterface {
  name = 'EncryptMyEntityFields1234567890000'

  public async up(queryRunner: QueryRunner): Promise<void> {
    const key = process.env.DB_ENCRYPTION_KEY
    if (!key) {
      throw new Error('DB_ENCRYPTION_KEY is not set')
    }
    const escapedKey = key.replace(/'/g, "''")

    await queryRunner.query(`
      DO $$
      BEGIN
        -- Habilitar pgcrypto si no existe
        CREATE EXTENSION IF NOT EXISTS pgcrypto;

        -- Encriptar campo obligatorio
        IF EXISTS (
          SELECT 1 FROM information_schema.columns 
          WHERE table_name = 'my_entity' 
          AND column_name = 'sensitive_field' 
          AND data_type != 'bytea'
        ) THEN
          ALTER TABLE my_entity 
          ALTER COLUMN sensitive_field TYPE bytea 
          USING pgp_sym_encrypt(sensitive_field::text, '${escapedKey}');
        END IF;

        -- Encriptar campo opcional (maneja NULL)
        IF EXISTS (
          SELECT 1 FROM information_schema.columns 
          WHERE table_name = 'my_entity' 
          AND column_name = 'optional_sensitive_field' 
          AND data_type != 'bytea'
        ) THEN
          ALTER TABLE my_entity 
          ALTER COLUMN optional_sensitive_field TYPE bytea 
          USING (
            CASE WHEN optional_sensitive_field IS NOT NULL 
            THEN pgp_sym_encrypt(optional_sensitive_field::text, '${escapedKey}') 
            ELSE NULL END
          );
        END IF;
      END $$;
    `)
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    const key = process.env.DB_ENCRYPTION_KEY
    if (!key) {
      throw new Error('DB_ENCRYPTION_KEY is not set')
    }
    const escapedKey = key.replace(/'/g, "''")

    await queryRunner.query(`
      DO $$
      BEGIN
        IF EXISTS (
          SELECT 1 FROM information_schema.columns 
          WHERE table_name = 'my_entity' 
          AND column_name = 'sensitive_field' 
          AND data_type = 'bytea'
        ) THEN
          ALTER TABLE my_entity 
          ALTER COLUMN sensitive_field TYPE text 
          USING pgp_sym_decrypt(sensitive_field, '${escapedKey}')::text;
        END IF;

        IF EXISTS (
          SELECT 1 FROM information_schema.columns 
          WHERE table_name = 'my_entity' 
          AND column_name = 'optional_sensitive_field' 
          AND data_type = 'bytea'
        ) THEN
          ALTER TABLE my_entity 
          ALTER COLUMN optional_sensitive_field TYPE text 
          USING (
            CASE WHEN optional_sensitive_field IS NOT NULL 
            THEN pgp_sym_decrypt(optional_sensitive_field, '${escapedKey}')::text 
            ELSE NULL END
          );
        END IF;
      END $$;
    `)
  }
}

Notas importantes:

• Verificar que DB_ENCRYPTION_KEY esté configurado
• Usar IF EXISTS para evitar errores si la migración se ejecuta múltiples veces
• Manejar campos NULL correctamente
• Si la columna tiene DEFAULT, usar DROP DEFAULT antes de cambiar el tipo

Paso 3: Actualizar el Repository

3.1 Agregar método helper para desencriptar campos

Code
 
import { PgcryptoQueryUtil } from '../../../commons/utils/pgcrypto-query.util'

export class MyEntityRepository extends Repository<MyEntity> {
  private addDecryptedMyEntityFields(queryBuilder: SelectQueryBuilder<MyEntity>, alias = 'myEntity'): void {
    PgcryptoQueryUtil.addDecryptedFieldsToSelect(queryBuilder, [
      { tableAlias: alias, columnName: 'sensitive_field', selectAlias: `${alias}_sensitive_field` },
      { tableAlias: alias, columnName: 'optional_sensitive_field', selectAlias: `${alias}_optional_sensitive_field` },
    ])
  }
}

3.2 Actualizar métodos de consulta

Para queries simples:

Code
 
findAll() {
  const query = this.createQueryBuilder('myEntity')
  this.addDecryptedMyEntityFields(query)
  return query.getMany()
}

Para queries con filtros en campos encriptados:

Code
 
findBySensitiveField(value: string) {
  const query = this.createQueryBuilder('myEntity')
    .where(
      PgcryptoQueryUtil.whereDecryptedField('myEntity', 'sensitive_field', '='),
      { value }
    )
  this.addDecryptedMyEntityFields(query)
  return query.getOne()
}

Para búsquedas con LIKE:

Code
 
searchBySensitiveField(searchTerm: string) {
  const sensitiveFieldDecrypt = PgcryptoQueryUtil.decryptField('myEntity', 'sensitive_field')
  const query = this.createQueryBuilder('myEntity')
    .andWhere(`UPPER(${sensitiveFieldDecrypt}) LIKE UPPER(:search)`, {
      search: `%${searchTerm}%`
    })
  this.addDecryptedMyEntityFields(query)
  return query.getMany()
}

Para ordenamiento:

Code
 
findAllOrdered() {
  const query = this.createQueryBuilder('myEntity')
  PgcryptoQueryUtil.addDecryptedFieldForOrderBy(
    query,
    'myEntity',
    'sensitive_field',
    'myEntity_sensitive_field',
    'ASC'
  )
  this.addDecryptedMyEntityFields(query)
  return query.getMany()
}

3.3 Actualizar queries con JOINs

Si la entidad se usa en JOINs de otras entidades, asegurarse de desencriptar sus campos:

Code
 
// En otro repository que hace JOIN con MyEntity
findWithMyEntity() {
  const query = this.createQueryBuilder('parent')
    .leftJoinAndSelect('parent.myEntity', 'myEntity')

  // Desencriptar campos de la entidad relacionada
  PgcryptoQueryUtil.addDecryptedFieldsToSelect(query, [
    { tableAlias: 'myEntity', columnName: 'sensitive_field', selectAlias: 'myEntity_sensitive_field' },
  ])

  return query.getMany()
}

Paso 4: (Opcional) Agregar método helper en PgcryptoQueryUtil

Si la entidad se usa frecuentemente, agregar un método helper:

Code
 
// En src/commons/utils/pgcrypto-query.util.ts

static addDecryptedMyEntityFields<T extends ObjectLiteral>(
  queryBuilder: SelectQueryBuilder<T>,
  alias = 'myEntity',
): void {
  const fields: DecryptFieldConfig[] = [
    { tableAlias: alias, columnName: 'sensitive_field', selectAlias: `${alias}_sensitive_field` },
    { tableAlias: alias, columnName: 'optional_sensitive_field', selectAlias: `${alias}_optional_sensitive_field` },
  ]
  this.addDecryptedFieldsToSelect(queryBuilder, fields)
}

Luego usar en los repositories:

Code
 
PgcryptoQueryUtil.addDecryptedMyEntityFields(queryBuilder, 'myEntity')

---

Ejemplos de Entidades con Encriptación

Ejemplo 1: User Entity

Entidad (src/features/user/entity/user.entity.ts):

Code
 
@Entity()
export class User extends EntityBase {
  @Column({ type: 'bytea', nullable: true, transformer: pgcryptoTransformer })
  email?: string

  @Column({ type: 'bytea', transformer: pgcryptoTransformer, nullable: true })
  firstName: string

  @Column({ type: 'bytea', transformer: pgcryptoTransformer, nullable: true })
  lastName: string

  @Column({ type: 'bytea', nullable: true, transformer: pgcryptoTransformer })
  secondLastName?: string

  @Column({ type: 'bytea', nullable: false, transformer: pgcryptoTransformer })
  phone: string
}

Repository (src/features/user/repository/user.repository.ts):

Code
 
export class UserRepository extends Repository<User> {
  private addDecryptedUserFields(queryBuilder: SelectQueryBuilder<User>, alias = 'user'): void {
    PgcryptoQueryUtil.addDecryptedUserFields(queryBuilder, alias)
  }

  findByPhone(phone: string) {
    const queryBuilder = this.createQueryBuilder('user')
      .leftJoinAndSelect('user.roles', 'roles')
      .andWhere(PgcryptoQueryUtil.whereDecryptedField('user', 'phone', '='), { value: phone })

    this.addDecryptedUserFields(queryBuilder)
    return queryBuilder.getOne()
  }

  findUsersByFiltersPaginated(payload: UserQueryDto) {
    const query = this.createQueryBuilder('user')

    if (payload.username) {
      const emailDecrypt = PgcryptoQueryUtil.decryptField('user', 'email')
      query.andWhere(`UPPER(${emailDecrypt}) LIKE UPPER(:username)`, {
        username: `%${payload.username}%`,
      })
    }

    this.addDecryptedUserFields(query)
    return query.getMany()
  }
}

Ejemplo 2: Parent Entity

Entidad (src/features/parent/entity/parent.entity.ts):

Code
 
@Entity()
export class Parent extends EntityBase {
  @Column({ type: 'bytea', transformer: pgcryptoTransformer })
  name: string

  @Column({ type: 'bytea', transformer: pgcryptoTransformer })
  lastName: string

  @Column({ type: 'bytea', nullable: true, transformer: pgcryptoTransformer })
  secondLastName?: string

  @Column({ type: 'bytea', nullable: false, transformer: pgcryptoTransformer })
  phone: string
}

Repository (src/features/parent/repository/parent.repository.ts):

Code
 
export class ParentRepository extends Repository<Parent> {
  private addDecryptedParentFields(queryBuilder: SelectQueryBuilder<Parent>, alias = 'parent'): void {
    PgcryptoQueryUtil.addDecryptedParentFields(queryBuilder, alias)
  }

  findByPhone(phone: string) {
    const queryBuilder = this.createQueryBuilder('parent')
      .innerJoinAndSelect('parent.user', 'user')
      .where(PgcryptoQueryUtil.whereDecryptedField('parent', 'phone', '='), { value: phone })

    this.addDecryptedParentFields(queryBuilder)
    PgcryptoQueryUtil.addDecryptedUserFields(queryBuilder, 'user')
    return queryBuilder.getOne()
  }
}

Ejemplo 3: Address Entity

Entidad (src/features/address/entity/address.entity.ts):

Code
 
@Entity()
export class Address extends EntityBase {
  @Column({ type: 'bytea', transformer: pgcryptoTransformer })
  formattedAddress: string
}

Repository (src/features/address/repository/address.repository.ts):

Code
 
export class AddressRepository extends Repository<Address> {
  private addDecryptedAddressFields(queryBuilder: SelectQueryBuilder<Address>, alias = 'address'): void {
    PgcryptoQueryUtil.addDecryptedFieldsToSelect(queryBuilder, [
      { tableAlias: alias, columnName: 'formatted_address', selectAlias: `${alias}_formatted_address` },
    ])
  }

  findAll() {
    const query = this.createQueryBuilder('address')
    this.addDecryptedAddressFields(query)
    return query.getMany()
  }
}

---

Mejores Prácticas

1. Siempre usar type: 'bytea' en columnas encriptadas

Code
 
// ✅ Correcto
@Column({ type: 'bytea', transformer: pgcryptoTransformer })
email: string

// ❌ Incorrecto (TypeORM generará migraciones incorrectas)
@Column({ transformer: pgcryptoTransformer })
email: string

2. Manejar campos NULL correctamente

Code
 
// ✅ Correcto para campos opcionales
@Column({ type: 'bytea', nullable: true, transformer: pgcryptoTransformer })
optionalField?: string

// En la migración
CASE WHEN optional_field IS NOT NULL
THEN pgp_sym_encrypt(optional_field::text, 'key')
ELSE NULL END

3. Desencriptar campos en todos los SELECT

Code
 
// ✅ Correcto - siempre desencriptar campos en queries
findAll() {
  const query = this.createQueryBuilder('user')
  this.addDecryptedUserFields(query) // ← Importante
  return query.getMany()
}

4. Desencriptar campos en JOINs

Code
 
// ✅ Correcto - desencriptar campos de entidades relacionadas
findWithParent() {
  const query = this.createQueryBuilder('user')
    .leftJoinAndSelect('user.parent', 'parent')

  this.addDecryptedUserFields(query)
  PgcryptoQueryUtil.addDecryptedParentFields(query, 'parent') // ← Importante

  return query.getMany()
}

5. Usar whereDecryptedField para filtros

Code
 
// ✅ Correcto
.where(PgcryptoQueryUtil.whereDecryptedField('user', 'phone', '='), { value: phone })

// ❌ Incorrecto (intentará comparar bytea con string)
.where('user.phone = :phone', { phone })

6. Verificar DB_ENCRYPTION_KEY en migraciones

Code
 
// ✅ Correcto
const key = process.env.DB_ENCRYPTION_KEY
if (!key) {
  throw new Error('DB_ENCRYPTION_KEY is not set')
}

7. No modificar datos encriptados directamente

Code
 
// ✅ Correcto - trabajar con datos planos
user.email = 'new@example.com'
await this.userRepository.save(user)

// ❌ Incorrecto - no encriptar manualmente
user.email = encrypt('new@example.com') // El subscriber lo hace automáticamente

---

Troubleshooting

Error: "Wrong key or corrupt data"

Causa: Se intenta desencriptar un campo que no está encriptado o está corrupto.

Solución:

• Verificar que la migración se ejecutó correctamente
• Verificar que DB_ENCRYPTION_KEY es el mismo usado para encriptar
• Verificar que no haya datos sin encriptar

Error: "default for column cannot be cast automatically to type bytea"

Causa: La columna tiene un DEFAULT que no puede convertirse a bytea.

Solución: En la migración, usar DROP DEFAULT antes de cambiar el tipo:

Code
 
ALTER TABLE user ALTER COLUMN email DROP DEFAULT;
ALTER TABLE user ALTER COLUMN email TYPE bytea USING ...;

TypeORM genera migraciones incorrectas después de encriptar

Causa: Falta type: 'bytea' en la definición de la entidad.

Solución: Agregar type: 'bytea' al decorador @Column:

Code
 
@Column({ type: 'bytea', transformer: pgcryptoTransformer })

Los datos no se encriptan al guardar

Causa: El PgcryptoEntitySubscriber no está registrado o no detecta los campos.

Solución:

1. Verificar que typeorm.config.ts incluye:

   Code
    
   subscribers: [`${__dirname}/**/**/*.entity-subscriber{.ts,.js}`]

2. Verificar que el campo tiene transformer: pgcryptoTransformer
3. Verificar que DB_ENCRYPTION_KEY está configurado

Los datos aparecen como Buffer en las respuestas

Causa: Falta desencriptar los campos en el SELECT o el transformer no está aplicado.

Solución:

1. Asegurarse de llamar addDecryptedFields() en el repository
2. Verificar que el campo tiene transformer: pgcryptoTransformer en la entidad

Error al filtrar por campo encriptado

Causa: Se está usando comparación directa en lugar de whereDecryptedField.

Solución: Usar PgcryptoQueryUtil.whereDecryptedField():

Code
 
// ✅ Correcto
.where(PgcryptoQueryUtil.whereDecryptedField('user', 'phone', '='), { value: phone })

// ❌ Incorrecto
.where('user.phone = :phone', { phone })

---

Variables de Entorno

Asegúrate de tener configurado:

Code
 
DB_ENCRYPTION_KEY=tu_clave_de_encriptacion_secreta

Importante:

• Esta clave debe ser la misma en todos los ambientes
• Debe mantenerse segura y no versionarse
• Si cambias la clave, los datos existentes no podrán desencriptarse

---

Referencias

• PostgreSQL pgcrypto Documentation
• TypeORM Value Transformers
• TypeORM Entity Subscribers