@currentfear/web-politica-enmascaramiento-amovil

Librería vanilla JavaScript para aplicar y visualizar técnicas de enmascaramiento de datos directamente en el DOM. No requiere ningún framework.

Instalación

npm

npm install @currentfear/web-politica-enmascaramiento-amovil

CDN (UMD global)

<script src="https://cdn.jsdelivr.net/npm/@currentfear/web-politica-enmascaramiento-amovil/dist/politica-enmascaramiento.umd.js"></script>

Al usar la versión CDN, todas las funciones quedan disponibles en el objeto global PoliticaEnmascaramiento.

Uso básico

import { renderMasking } from '@currentfear/web-politica-enmascaramiento-amovil';

const el = document.getElementById('mi-elemento');

renderMasking(el, 'sustitucion', {
  type: 'sustitucion',
  original: 'Juan Pérez',
});

API — renderMasking

renderMasking(element, type, data, options)

| Parámetro | Tipo | Descripción | |-----------|------|-------------| | element | HTMLElement | Elemento DOM donde se renderiza el resultado | | type | string | Tipo de enmascaramiento (ver tipos disponibles) | | data | object | Datos de entrada para el enmascaramiento | | options | object | Opciones de renderizado (ver tabla de opciones) |

Opciones de renderizado

| Opción | Tipo | Por defecto | Descripción | |--------|------|-------------|-------------| | showOriginal | boolean | false | Muestra el valor original junto al enmascarado | | showLabel | boolean | true | Muestra la etiqueta del tipo de enmascaramiento | | className | string | '' | Clase CSS adicional aplicada al contenedor | | maskCount | number | — | Cantidad fija de caracteres de máscara. Si se combina con maskWordsStart/maskWordsEnd, aplica por palabra | | maskChar | string | '*' | Carácter usado para enmascarar | | maskWordsStart | number | 0 | Cantidad de palabras a enmascarar desde el inicio del valor | | maskWordsEnd | number | 0 | Cantidad de palabras a enmascarar desde el final del valor | | nullValue | string | — | Texto a mostrar cuando original es nulo, undefined o cadena vacía | | constantValue | string | — | Si se define, renderiza este valor directamente sin aplicar ningún enmascaramiento |

Tipos de enmascaramiento

sustitucion

Reemplaza el valor original por un nombre ficticio determinista generado a partir del original. El resultado es siempre el mismo para el mismo valor de entrada.

Campos soportados:

| Campo | Tipo | Por defecto | Descripción | |------|------|-------------|-------------| | original | string | — | Valor original a enmascarar | | suffix | string | — | Sufijo opcional para nombres de empresa, por ejemplo S.A. o S.A.S. |

renderMasking(el, 'sustitucion', {
  type: 'sustitucion',
  original: 'Ana Gómez',
  suffix: 'S.A.S.', // opcional
});

Si se define suffix, se agrega al valor generado. Ejemplo: Laura Martínez S.A.S.

permutacion

Intercambia el valor con otro registro. Si se omite swappedWith, genera un valor ficticio.

Campos soportados:

| Campo | Tipo | Por defecto | Descripción | |------|------|-------------|-------------| | original | string | — | Valor original a enmascarar | | swappedWith | string | — | Valor alternativo a usar directamente | | suffix | string | — | Sufijo opcional. Solo aplica cuando la librería genera un valor ficticio y no cuando se usa swappedWith |

renderMasking(el, 'permutacion', {
  type: 'permutacion',
  original: 'Carlos Ruiz',
  swappedWith: 'Luis Martínez', // opcional
  suffix: 'S.A.', // opcional, aplica cuando se genera un valor ficticio
});

cifrado

Codifica el valor en Base64.

renderMasking(el, 'cifrado', {
  type: 'cifrado',
  original: '1023456789',
  algorithm: 'Base64', // opcional, solo informativo
});

enmascaramiento-parcial

Oculta una parte del valor mostrando solo los últimos N caracteres.

renderMasking(el, 'enmascaramiento-parcial', {
  type: 'enmascaramiento-parcial',
  original: '3001234567',
  visibleChars: 4,  // por defecto 4
  maskChar: '*',    // por defecto '*'
});
// Resultado: ******4567

Opciones del dato para enmascaramiento parcial:

| Campo | Tipo | Por defecto | Descripción | |------|------|-------------|-------------| | visibleChars | number | 4 | Cantidad de caracteres visibles al final cuando el valor es texto | | maskChar | string | '*' | Carácter usado para enmascarar | | valueType | 'text' \| 'email' | 'text' | Si es email, oculta el usuario y conserva el dominio. Si el correo no tiene dominio válido, usa dominio-ficticio.test |

Comportamiento:

• Si valueType es 'text', la librería deja visibles los últimos visibleChars caracteres del valor completo.
• Si valueType es 'email', la librería enmascara la parte antes de @ y conserva el dominio.
• Si el correo no tiene un formato válido, el resultado será ****@dominio-ficticio.test.

Ejemplo para correo:

renderMasking(el, 'enmascaramiento-parcial', {
  type: 'enmascaramiento-parcial',
  original: '[email protected]',
  valueType: 'email',
});
// Resultado: *******@gmail.com

envejecimiento-fechas

Desplaza una fecha aplicando un offset en días.

renderMasking(el, 'envejecimiento-fechas', {
  type: 'envejecimiento-fechas',
  original: '2024-06-15',
  originalDate: '2024-06-15', // formato YYYY-MM-DD
  offsetDays: -180,           // por defecto -180
});

tokenizacion

Reemplaza el valor por un token único y consistente derivado del original.

renderMasking(el, 'tokenizacion', {
  type: 'tokenizacion',
  original: '[email protected]',
  tokenPrefix: 'TKN', // por defecto 'TKN'
});
// Resultado: TKN-A1B2-C3D4

datos-sinteticos

Genera un valor sintético completamente nuevo, diferente al original.

Campos soportados:

| Campo | Tipo | Por defecto | Descripción | |------|------|-------------|-------------| | original | string | — | Valor original a usar como base determinista | | suffix | string | — | Sufijo opcional para nombres de empresa, por ejemplo S.A. o S.A.S. |

renderMasking(el, 'datos-sinteticos', {
  type: 'datos-sinteticos',
  original: 'Pedro Sánchez',
  suffix: 'S.A.S.', // opcional
});

Opciones avanzadas

Controlar la cantidad de caracteres de máscara

// Muestra siempre 6 asteriscos independientemente del valor
renderMasking(el, 'sustitucion', {
  type: 'sustitucion',
  original: 'Juan Pérez',
}, {
  maskCount: 6,
  maskChar: '*',
});
// Resultado en pantalla: ******

Enmascarar palabras al inicio o al final

// Enmascara la primera palabra del resultado
renderMasking(el, 'sustitucion', {
  type: 'sustitucion',
  original: 'María López García',
}, {
  maskWordsStart: 1,
  maskCount: 4, // cantidad de caracteres por palabra enmascarada (por defecto 3)
});
// Si el valor generado fuera "Laura Martínez":
// Resultado: **** Martínez

// Enmascara la última palabra
renderMasking(el, 'permutacion', {
  type: 'permutacion',
  original: 'Carlos Díaz',
}, {
  maskWordsEnd: 1,
  maskCount: 5,
});
// Resultado: Carlos *****

// Enmascara inicio y final simultáneamente
renderMasking(el, 'datos-sinteticos', {
  type: 'datos-sinteticos',
  original: 'Ana Beatriz Torres',
}, {
  maskWordsStart: 1,
  maskWordsEnd: 1,
  maskChar: '#',
  maskCount: 3,
});
// Resultado: ### Beatriz ###

Manejar valores nulos o vacíos

renderMasking(el, 'sustitucion', {
  type: 'sustitucion',
  original: '',
}, {
  nullValue: 'Sin dato',
});
// Resultado: Sin dato

Valor constante (sin enmascaramiento)

Útil cuando se quiere mostrar un valor fijo sin importar los datos de entrada, por ejemplo para registros que por configuración siempre deben mostrar un texto específico.

renderMasking(el, 'sustitucion', {
  type: 'sustitucion',
  original: 'Juan Pérez',
}, {
  constantValue: 'CONFIDENCIAL',
});
// Resultado: CONFIDENCIAL

Uso de generadores directamente

Si no se necesita renderizado DOM, se pueden usar las funciones generadoras directamente:

import {
  generateSustitucion,
  generateEnmascaramientoParcial,
  generateTokenizacion,
} from '@currentfear/web-politica-enmascaramiento-amovil';

const nombre = generateSustitucion({ type: 'sustitucion', original: 'Juan Pérez' });
// 'Laura Martínez' (determinista)

const empresa = generateSustitucion({
  type: 'sustitucion',
  original: 'Acme',
  suffix: 'S.A.S.',
});
// 'Laura Martínez S.A.S.'

const cc = generateEnmascaramientoParcial({
  type: 'enmascaramiento-parcial',
  original: '1023456789',
  visibleChars: 4,
});
// '******6789'

const correo = generateEnmascaramientoParcial({
  type: 'enmascaramiento-parcial',
  original: '[email protected]',
  valueType: 'email',
});
// '*******@gmail.com'

const { token } = generateTokenizacion({
  type: 'tokenizacion',
  original: '[email protected]',
});
// 'TKN-A1B2-C3D4'

Reglas importantes:

• suffix está disponible en sustitucion, permutacion y datos-sinteticos.
• En permutacion, suffix solo aplica cuando no se envía swappedWith.
• valueType: 'email' solo aplica en enmascaramiento-parcial.
• Las opciones de renderizado como maskWordsStart, maskWordsEnd y maskCount afectan la visualización final, no el valor generado por las funciones generadoras.

Uso con CDN

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/@currentfear/web-politica-enmascaramiento-amovil/dist/politica-enmascaramiento.umd.js"></script>
</head>
<body>
  <div id="campo"></div>

  <script>
    const { renderMasking } = PoliticaEnmascaramiento;

    renderMasking(document.getElementById('campo'), 'enmascaramiento-parcial', {
      type: 'enmascaramiento-parcial',
      original: '3001234567',
      visibleChars: 3,
    }, {
      maskCount: 6,
      showLabel: false,
    });
  </script>
</body>
</html>

Integración con backend

La librería está diseñada para recibir datos ya procesados desde el backend. El flujo recomendado es:

1. El backend aplica la política de enmascaramiento y envía el tipo y los datos al frontend.
2. El frontend usa esta librería para visualizarlos de forma consistente.

Ejemplo con fetch:

fetch('/api/datos-enmascarados')
  .then(res => res.json())
  .then(({ type, data }) => {
    renderMasking(document.getElementById('resultado'), type, data);
  });

Ejemplo de respuesta esperada del backend:

{
  "type": "enmascaramiento-parcial",
  "data": {
    "type": "enmascaramiento-parcial",
    "original": "3001234567",
    "visibleChars": 4
  }
}

Licencia

MIT