How to add a custom mask

Learn how to add a custom mask to a built-in data type

Overview

Masks reduce data exposure by replacing meaningful parts of a data item with a filler character. For example, a credit card number might be masked so only the first four digits could be read, such as "9734-——****."

Piiano Vault offers several built-in masks, each associated with a built-in data type. The types with built-in masks include SSN, EMAIL, and CC_NUMBER. You can learn more about these built-in types and masks from the Built-in transformations guide.

You enhance the built-in functionality by creating masks that complement the built-in masks or provide masks for data types that don't have a built-in option. You create masks using JavaScript code that defines how a mask is applied to an item of data. Then, you install this JavaScript using a bundle and link the mask function to a built-in data type. The mask can then be used by the built-in type or any custom data type based on it.

Check out the Get transformed properties for all objects in a collection section of the List all objects guide to see how you use masks.

In this tutorial, you learn how to add a simple mask to the built-in type NAME. The same process applies to more complex functions and other types, including custom types.

note

If your custom JavaScript code is self-contained, as this example is, you can use the JavaScript file as the bundle file without needing to build the bundle. For details on building a bundle with dependencies, refer to the bundles documentation.

This tutorial covers:

1. Adding the code files that contain the mask
2. Uploading the code to Vault
3. Connecting the mask function to a built-in type
4. Testing the mask

Prerequisites

1. A running Vault
2. The command line tool installed
3. Vault Javascript support must not be disabled (it is enabled by default and can be disabled with an environment variable PVAULT_FEATURES_DISABLE_JAVASCRIPT)

Add the code

First, write the code that applies the mask. In this case, code that accepts a string and replaces all the string's characters with * except for the first one.

// export the masking function to be used by the Vault
exports =  {
    "mask" : {
        type: "transformer",
        description: "Name mask - keep only the first character",
        handler: name_mask
    }
  }

// masks a name by replacing all charachters with "*" except for the first one
function name_mask(context, object, value) {
    if (value.length === 0) { // can not mask an empty name
        return "";
    }
    return value.charAt(0) + "*".repeat(value.length - 1);
}

Create a file and add this code to it. Save the file with the name main.js

Upload the code to Vault

To upload your code you use the CLI like this:

pvault bundle add --name name_mask --description "mask for NAME" --bundle-code @./main.js

+---------------+-------------------------------+-----------+-------------+------------+--------------+
|  description  |         creation_time         |   name    | normalizers | validators | transformers |
+---------------+-------------------------------+-----------+-------------+------------+--------------+
| mask for NAME | Tue, 26 Mar 2024 15:29:01 UTC | name_mask | []          | []         | [mask]       |
+---------------+-------------------------------+-----------+-------------+------------+--------------+

warning

The bundle name can not contain -.

Connect the mask to the datatype NAME

To connect the mask to the data type NAME, use the CLI like this:

pvault datatype update --name NAME --datatype-update-json '{ "custom_transformers": [ "name_mask.mask" ] }'

You get a response similar to this:

+-----------------------------+-----------+-------------------------------+------+----------------+------------+---------------------+------------------------+
|         description         | validator |         creation_time         | name | base_type_name | normalizer | default_transformer |      transformers      |
+-----------------------------+-----------+-------------------------------+------+----------------+------------+---------------------+------------------------+
| A string containing a name. |           | Sun, 14 May 2023 00:00:00 UTC | NAME |                |            |                     | [token name_mask.mask] |
+-----------------------------+-----------+-------------------------------+------+----------------+------------+---------------------+------------------------+

Test the mask

Use the Piiano Vault sample data to test your new mask, like this:

pvault collection add --collection-template persons --add-test-data -c Persons
pvault object list -c Persons -p email,first_name,last_name
# and now with the masks
pvault object list -c Persons -p email.mask,first_name.mask,last_name.mask

You get this response for the sample data (masking both the first name and last name):

+-----------------------------+-----------------+----------------+
|         email.mask          | first_name.mask | last_name.mask |
+-----------------------------+-----------------+----------------+
| R**********@gmail.com       | R****           | D****          |
| K****************@yahoo.com | K****           | S******        |
| J****************@yahoo.com | J*****          | W*****         |
| A**************@gmail.com   | A*****          | R******        |
| L*******@yahoo.com          | L******         | B*****         |
| D*********@hotmail.com      | D*******        | F*******       |
| Q************@hotmail.com   | M***            | S******        |
| E**********@gmail.com       | E****           | J****          |
| A************@hotmail.com   | A****           | P****          |
| j*******@gmail.com          | J***            | D**            |
+-----------------------------+-----------------+----------------+