Skip to content
Arcjet Docs

Arcjet Redact reference

The Arcjet Redaction library makes it easy to redact sensitive information locally.

What are Arcjet utilities?

Arcjet utilities are independent libraries that do not require the use of the main Arcjet SDK—they can be used with or without other Arcjet rules.

We take the pain out of implementing security tasks through these utilities to provide a security as code approach to developer-first security.

Configuration

The configuration definition is:

type RedactOptions = {
  entities?: Array<SensitiveInfoType>;
  contextWindowSize?: number;
  detect?: (tokens: string[]) -> Array<SensitiveInfoType | undefined>;
  replace?: (detectedEntity: SensitiveInfoType) -> string | undefined;
};
  • entities: The list of entities that you wish to redact. If undefined then all entities are redacted. Valid values are: email, phone-number, ip-address, ‘credit-card, or any string returned from detect.
  • contextWindowSize - How many tokens to pass to the detect function at a time. Setting this to a higher value allows for more context to be used when determing if a token is sensitive or not. For best performance this should be set to as low a number as possible to provide the context that you need.
  • detect - An optional function that allows you to detect custom entities. It will be passed a list of tokens as big as contextWindowSize and should return a list of detected entities of the same length.
  • replace - An optional function that allows you to define your own replacements for detected entities. It is passed a string with the type of entity detected and it should either return a replacement for that entity type or undefined.

Redacting and Unredacting

The Arcjet Redaction library can be used to both redact and unredact text. First you redact using the redact() function which returns both the redacted text and an unredact() function as a tuple. You can use the unredact() function later on to replace redacted entities with their originals.

import { redact } from "@arcjet/redact";


const text = "My email address is test@example.com";


const [redacted, unredact] = await redact(text, {
  entities: ["email"],
});


console.log(redacted);
// My email address is <Redacted email #1>


const unredacted = unredact("Your email address is <Redacted email #1>");


console.log(unredacted);
// Your email address is test@example.com

Custom entity detection

When configuring a redaction you can provide a custom entity detect function, this enables you to detect entities that we don’t support out of the box using custom logic.

The function will take a list of tokens and must return a list of either undefined, if the corresponding token in the input list is not sensitive, or the name of the entity if it does match. The number of tokens that are provided to the function is controlled by the contextWindowSize option, which defaults to 1. If you need additional context to perform detections then you can increase this value.

In cases of a conflict the first identified entity type is used.

import { redact } from "@arcjet/redact";


const text = "my email-address is test@example.com";


function detectDash(tokens: string[]): Array<"contains-dash" | undefined> {
  return tokens.map((token) => {
    if (token.includes("-")) {
      return "contains-dash";
    }
  });
}


const [redacted] = await redact(text, {
  entities: ["email", "contains-dash"],
  detect: detectDash,
});


console.log(redacted);
// my <Redacted contains-dash #1> is <Redacted email #2>

Custom entity redaction

You can provide a function to perform custom entity redaction if have different requirements for the redacted entities. A common example of this is to use a library such as faker.js to generate redacted entities that look exactly like the real ones.

import { redact } from "@arcjet/redact";
import { faker } from "@faker-js/faker";


const text = "my email address is test@example.com";


function customRedact(detectedEntity: string) {
  // If we detect an email generate a fake one
  if (detectedEntity === "email") {
    return faker.internet.email();
  }


  // Otherwise we'll return undefined and use the default
  return undefined;
}


const [redacted] = await redact(text, {
  entities: ["email"],
  replace: customRedact,
});


console.log(redacted);
// my email address is john.smith@email-provider.com