@currentfear/react-web-politica-enmascaramiento-amovil

Componente React con soporte TypeScript para aplicar y visualizar técnicas de enmascaramiento de datos. Compatible con React 18 y 19.

Instalación

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

React y ReactDOM son peer dependencies y deben estar instalados en el proyecto.

Uso básico

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

function App() {
  return (
    <DataMasking
      type="sustitucion"
      data={{ type: 'sustitucion', original: 'Juan Pérez' }}
    />
  );
}

Props del componente

| Prop | Tipo | Por defecto | Descripción | |------|------|-------------|-------------| | type | MaskingType | — | Tipo de enmascaramiento a aplicar | | data | MaskingData | — | Datos de entrada para el enmascaramiento | | className | string | — | Clase CSS adicional aplicada al contenedor | | showOriginal | boolean | false | Muestra el valor original junto al enmascarado | | showLabel | boolean | true | Muestra la etiqueta del tipo de enmascaramiento | | 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. El resultado es siempre el mismo para el mismo valor de entrada.

Campos soportados en SustitucionData:

| 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. |

<DataMasking
  type="sustitucion"
  data={{ type: 'sustitucion', original: 'Ana Gómez', suffix: 'S.A.S.' }}
/>

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 en PermutacionData:

| 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 |

<DataMasking
  type="permutacion"
  data={{
    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.

<DataMasking
  type="cifrado"
  data={{
    type: 'cifrado',
    original: '1023456789',
    algorithm: 'Base64', // opcional, solo informativo
  }}
/>

enmascaramiento-parcial

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

<DataMasking
  type="enmascaramiento-parcial"
  data={{
    type: 'enmascaramiento-parcial',
    original: '3001234567',
    visibleChars: 4,  // por defecto 4
    maskChar: '*',    // por defecto '*'
  }}
/>
// Resultado: ******4567

Campos soportados en EnmascaramientoParcialData:

| 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:

<DataMasking
  type="enmascaramiento-parcial"
  data={{
    type: 'enmascaramiento-parcial',
    original: '[email protected]',
    valueType: 'email',
  }}
/>
// Resultado: *******@gmail.com

envejecimiento-fechas

Desplaza una fecha aplicando un offset en días.

<DataMasking
  type="envejecimiento-fechas"
  data={{
    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.

<DataMasking
  type="tokenizacion"
  data={{
    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 en DatosSinteticosData:

| 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. |

<DataMasking
  type="datos-sinteticos"
  data={{ type: 'datos-sinteticos', original: 'Pedro Sánchez', suffix: 'S.A.S.' }}
/>

Props avanzadas

Controlar la cantidad de caracteres de máscara

// Muestra siempre 6 asteriscos independientemente del valor
<DataMasking
  type="sustitucion"
  data={{ 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 generado
<DataMasking
  type="sustitucion"
  data={{ type: 'sustitucion', original: 'María López García' }}
  maskWordsStart={1}
  maskCount={4}
/>
// Si el valor generado fuera "Laura Martínez":
// Resultado: **** Martínez

// Enmascara la última palabra
<DataMasking
  type="permutacion"
  data={{ type: 'permutacion', original: 'Carlos Díaz' }}
  maskWordsEnd={1}
  maskCount={5}
/>
// Resultado: Carlos *****

// Enmascara inicio y final simultáneamente
<DataMasking
  type="datos-sinteticos"
  data={{ type: 'datos-sinteticos', original: 'Ana Beatriz Torres' }}
  maskWordsStart={1}
  maskWordsEnd={1}
  maskChar="#"
  maskCount={3}
/>
// Resultado: ### Beatriz ###

Manejar valores nulos o vacíos

<DataMasking
  type="sustitucion"
  data={{ type: 'sustitucion', original: '' }}
  nullValue="Sin dato"
/>
// Resultado: Sin dato

// Funciona también con original undefined o null en runtime
<DataMasking
  type="sustitucion"
  data={{ type: 'sustitucion', original: datosDelApi?.nombre ?? '' }}
  nullValue="—"
/>

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.

<DataMasking
  type="sustitucion"
  data={{ type: 'sustitucion', original: 'Juan Pérez' }}
  constantValue="CONFIDENCIAL"
/>
// Resultado: CONFIDENCIAL

Generadores directamente

Si se necesita el valor enmascarado sin renderizar un componente:

• Todas las funciones generate* aceptan un segundo parámetro opcional displayOptions: maskCount, maskChar, maskWordsStart, maskWordsEnd, nullValue, constantValue.

import {
  generateSustitucion,
  generateEnmascaramientoParcial,
  generateTokenizacion,
} from '@currentfear/react-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.',
}, {
  maskWordsStart: 1,
  maskCount: 4,
});
// '**** 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'

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

Reglas importantes:

• suffix está disponible en SustitucionData, PermutacionData y DatosSinteticosData.
• En PermutacionData, suffix solo aplica cuando no se envía swappedWith.
• valueType: 'email' solo aplica en EnmascaramientoParcialData.
• Las mismas opciones de visualización del componente (maskCount, maskChar, maskWordsStart, maskWordsEnd, nullValue, constantValue) se pueden usar también en funciones generadoras mediante el segundo parámetro.
• En funciones que retornan objetos (generateTokenizacion, generateEnvejecimientoFechas, generateDatosSinteticos), las opciones solo modifican la propiedad masked; los campos auxiliares (token, maskedDate, syntheticValue) conservan su valor original generado.

Ejemplo completo

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

interface UsuarioProps {
  nombre: string | null;
  cedula: string;
  correo: string;
}

function TarjetaUsuario({ nombre, cedula, correo }: UsuarioProps) {
  return (
    <div>
      <DataMasking
        type="sustitucion"
        data={{ type: 'sustitucion', original: nombre ?? '' }}
        nullValue="Sin nombre"
        maskWordsEnd={1}
        maskCount={4}
      />
      <DataMasking
        type="enmascaramiento-parcial"
        data={{ type: 'enmascaramiento-parcial', original: cedula, visibleChars: 4 }}
        showLabel={false}
      />
      <DataMasking
        type="tokenizacion"
        data={{ type: 'tokenizacion', original: correo, tokenPrefix: 'USR' }}
      />
    </div>
  );
}

Licencia

MIT