README.md

JSMasker

JSMasker is a flexible JavaScript module that masks sensitive properties in objects and arrays by replacing them with customizable masks. It can be used in both Node.js and browser environments.

Table of Contents

• Installation
• Usage
  • Masking Objects
  • Masking Arrays
  • Nested Structures
• Configuration Options
• Examples
• Building and Publishing
• Contributing
• License

Installation

Node.js

npm install jsmasker

Browser

Include JSMasker directly in your HTML file using a CDN:

<script src="https://cdn.jsdelivr.net/npm/jsmasker@1.2.0/dist/jsmasker.min.js"></script>

Usage

Masking Objects

const maskObject = require('jsmasker')

const sensitiveObject = {
  username: 'john_doe',
  password: 'secret123',
  data: {
    apiKey: 'abcdef123456'
  }
}

const maskedObject = maskObject(sensitiveObject)

console.log(maskedObject)
// Output:
// {
//   username: 'john_doe',
//   password: '********',
//   data: {
//     apiKey: '********'
//   }
// }

Masking Arrays

JSMasker can also mask elements within arrays:

const maskObject = require('jsmasker')

const sensitiveArray = ['public', 'secret123', 'private']

const maskedArray = maskObject(sensitiveArray, {
  properties: [''] // This will mask all elements
})

console.log(maskedArray)
// Output: ['******', '********', '******']

Nested Structures

JSMasker handles nested objects and arrays:

const maskObject = require('jsmasker')

const complexData = {
  user: {
    name: 'John Doe',
    credentials: ['user123', 'password123']
  },
  apiKeys: ['key1', 'key2', 'key3']
}

const maskedData = maskObject(complexData, {
  properties: ['credentials', 'apiKeys']
})

console.log(maskedData)
// Output:
// {
//   user: {
//     name: 'John Doe',
//     credentials: ['*******', '***********']
//   },
//   apiKeys: ['****', '****', '****']
// }

Configuration Options

Option	Type	Default	Description
properties	Array	['password', 'key', 'secret', 'token']	List of properties to mask
maskLength	number | 'random'	8	Length of the mask or 'random' for variable length
minLength	number	5	Minimum length for random mask
maxLength	number	15	Maximum length for random mask
maskChar	string	'*'	Character to use for masking
fullMask	string | boolean	false	String to use as full mask (e.g., 'REDACTED') or boolean to enable/disable full masking

Examples

1. Using random mask length:

const masked = maskObject(sensitiveData, { maskLength: 'random', minLength: 3, maxLength: 8 })

2. Masking specific array elements:

const data = {
  publicInfo: ['John', 'Doe', '1990'],
  privateInfo: ['SSN123456', 'CC4321']
}

const masked = maskObject(data, { properties: ['privateInfo'] })
// Result:
// {
//   publicInfo: ['John', 'Doe', '1990'],
//   privateInfo: ['********', '********']
// }

3. Using a full mask string:

const masked = maskObject(sensitiveData, { fullMask: 'REDACTED' })

Features

Nested Object Handling

JSMasker recursively traverses nested objects and arrays, applying the mask to sensitive properties at any level of nesting. This ensures that all sensitive data is properly masked, regardless of its position in the object structure.

Full Mask Option

The fullMask option can be used in two ways:

1. As a string: When set to a string value (e.g., 'REDACTED'), all sensitive properties will be replaced with this exact string.
2. As a boolean: When set to true, sensitive properties will be fully masked using the specified maskChar repeated to match the original string length. When set to false (default), the standard masking behavior is applied.

Non-Object Input Handling

If JSMasker receives a non-object input (such as a string, number, or null), it will return the input unchanged. This ensures that the function can be safely used even when the input type is uncertain.

Examples

1. Using random mask length:

const masked = JSMasker(sensitiveObject, { maskLength: 'random', minLength: 3, maxLength: 8 })

2. Using a custom mask character:

const masked = JSMasker(sensitiveObject, { maskChar: '#' })

3. Using a full mask string:

const masked = JSMasker(sensitiveObject, { fullMask: 'REDACTED' })

4. Using boolean full mask:

const masked = JSMasker(sensitiveObject, { fullMask: true })

Building and Publishing

For detailed instructions on building and publishing JSMasker, please refer to the BUILD.md file.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.