@fourlights/mapper-plugin-anonymize v1.3.0

@fourlights/mapper-plugin-anonymize

This package is a plugin for the @fourlights/mapper package. It allows you to anonymize PII and sensitive data during mapping.

Installation

You can install this package using npm. It lists @fourlights/mapper as a peer dependency.

npm install @fourlights/mapper-plugin-anonymize

Usage

Quick example

import { map } from '@fourlights/mapper-plugin-anonymize'

const user = {
	firstName: 'John',
	lastName: 'Doe',
	birthdate: new Date(1990, 1, 1),
	creditCard: '12357689',
	theme: 'blue',
}
console.log(
	map(user, {
		firstName: [(d) => d.firstName, 'pii'],
		lastName: [(d) => d.lastName, 'pii'],
		creditCard: [(d) => d.creditCard, 'sensitive'],
		birthdate: [(d) => d.birthdate, 'pii'],
		theme: (d) => d.theme,
	}),
)

outputs

{
	firstName: 'Patty',
	lastName: 'Blanda',
	creditCard: '********',
	birthDate: 'Date(1999, 5, 11)',
	theme: 'blue',
}

In your mapper config, you supply data classification on each property that you want to anonymize. The plugin will then anonymize the data based on the classification. By default, the plugin will fake PII data and redact sensitive data. But everything is configurable, both on the plugin level or on a property level.

import { map, type MapperConfig } from '@fourlights/mapper'
import {
	AnonymizePlugin,
	type AnonymizePluginPropertyOptions,
} from '@fourlights/mapper-plugin-anonymize'

const user = { firstName: 'John', lastName: 'Doe', birthdate: new Date(1990, 1, 1) }
const config: MapperConfig<typeof user, AnonymizePluginPropertyOptions> = {
	firstName: { value: (data) => data.firstName, options: { classification: 'pii' } },
	lastName: {
		value: (data) => data.lastName,
		options: { classification: 'pii', anonymize: 'redact' },
	},
}

console.log(map(user, config, { plugins: [new AnonymizePlugin({ seed: 69 })] })) // NOTE: The seed to get deterministic results, for example purposes

This will output:

{
	firstName: 'Vicki',
	lastName: '*****',
}

Configuration

The plugin can be configured with the following options:

• seed (number): The seed to use for the random generator. This is useful for deterministic results. Default: undefined.
• piiData ('fake' | 'redact' | 'none' | (key: string, property: MapperProperty<T>) => MapperFn<T>): The method to use for anonymizing PII data. Default: 'fake'. fake and redact are built-in methods. You can also supply your own method factory.
• sensitiveData ('fake' | 'redact' | 'none' | (key: string, property: MapperProperty<T>) => MapperFn<T>): The method to use for anonymizing sensitive data. Default: 'redact'. fake and redact are built-in methods. You can also supply your own method factory.

These options can also be set (or overridden) on a property level by supplying the options.anonymize property. Note that piiData and sensitiveData also accept an object to override the built-in method configuration (see next example), which can also be provided on a property level.

const config = {
	firstName: {
		value: (data) => data.firstName,
		options: {
			classification: 'pii',
			// Use a built-in method
			anonymize: 'fake', // 'redact' | 'none'
		},
	},
	lastName: {
		value: (data) => data.lastName,
		options: {
			classification: 'pii',
			/* You can use an object to override the built-in method configuration */
			anonymize: {
				method: 'redact',
				options: { redactValue: 'X' }, // e.g. 'XXXXXX' instead of '******'
			},
		},
	},
}

Helper methods for augmenting your mapper config

You can use the withClassification method to easily add (sparse) classifications to your (short and long-form) properties.

import { map } from '@fourlights/mapper'
import {
	AnonymizePlugin,
	withClassification,
	type MapperConfigWithClassification,
} from '@fourlights/mapper-plugin-anonymize'

const user = {} // see example above
const config = {
	name: [(d) => d.name, 'pii'], // inline data classification
	birthdate: (d) => d.birthdate,
	theme: (d) => d.theme,
} as MapperConfigWithClassification<typeof user>

map(user, withClassification(config), { plugins: [new AnonymizePlugin()] })

// or, when providing additional properties
map(user, withClassification(config, { birthdate: 'sensitive' }), {
	plugins: [new AnonymizePlugin()],
})

Super simple anonymized mapping

You can also use the exported map function from this plugin instead of the one from @fourlights/mapper:

import { map } from '@fourlights/mapper-plugin-anonymize'

map(user, { name: [(d) => d.name, 'pii'], birthdate: (d) => d.birthdate })

which is equivalent to

import { map } from '@fourlights/mapper'
import { AnonymizePlugin, withClassification } from '@fourlights/mapper-plugin-anonymize'

map(user, withClassification({ name: [(d) => d.name, 'pii'], birthdate: (d) => d.birthdate }), {
	plugins: [new AnonymizePlugin()],
})

Contributing

Contributions are welcome. Please open an issue or submit a pull request on GitHub.

License

This package is licensed under the MIT license.