@hackylabs/deep-redact 2.0.2 → 2.1.0

package/README.md

@@ -3,13 +3,13 @@
 [![npm version](https://badge.fury.io/js/@hackylabs%2Fdeep-redact.svg)](https://badge.fury.io/js/@hackylabs%2Fdeep-redact)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/hackylabs/deep-redact/blob/main/LICENSE)
 
-Faster than Fast Redact <sup>1</sup> as well as being safer and more configurable than many other redaction libraries,
+Faster than Fast Redact <sup>1</sup> as well as being safer and more configurable than many other redaction solutions,
 Deep Redact is a zero-dependency tool that redacts sensitive information from strings and objects. It is designed to be
 used in a production environment where sensitive information needs to be redacted from logs, error messages, files,
 and other outputs.
 
 Circular references and other unsupported values are handled gracefully, and the library is designed to be as fast as
-possible while still being configurable.
+possible while still being easy to use and configure.
 
 Supporting both CommonJS and ESM, with named and default exports, Deep Redact is designed to be versatile and easy to
 use in any modern JavaScript or TypeScript project in Node or the browser.
@@ -31,9 +31,8 @@ library outside of your global logging/error-reporting libraries.</h4>
 // ./src/example.ts
 import {DeepRedact} from '@hackylabs/deep-redact'; // If you're using CommonJS, import with require('@hackylabs/deep-redact') instead. Both CommonJS and ESM support named and default imports.
 
-const redaction = new DeepRedact({
+const objRedaction = new DeepRedact({
   blacklistedKeys: ['sensitive', 'password', /name/i],
-  serialise: false,
 })
 
 const obj = {
@@ -46,7 +45,8 @@ const obj = {
   }
 }
 
-redaction.redact(obj)
+// Recursively redact sensitive information from an object
+objRedaction.redact(obj)
 // {
 //  keepThis: 'This is fine',
 //  sensitive: '[REDACTED]',
@@ -56,6 +56,19 @@ redaction.redact(obj)
 //    firstName: '[REDACTED]'
 //  }
 // }
+
+const strRedaction = new DeepRedact({
+  stringTests: [
+    {
+      pattern: /<(email|password)>([^<]+)<\/\1>/gi,
+      replacer: (value: string, pattern: RegExp) => value.replace(pattern, '<$1>[REDACTED]</$1>'),
+    },
+  ],
+})
+
+// Partially redact sensitive information from a string
+strRedaction.redact('<email>someone@somewhere.com</email><keepThis>This is fine</keepThis><password>secret</password>')
+// '<email>[REDACTED]</email><keepThis>This is fine</keepThis><password>[REDACTED]</password>'
 ```
 
 ## Configuration
@@ -65,7 +78,7 @@ redaction.redact(obj)
 | key | description | type | options | default | required |
 | --- | --- | --- | --- | --- | --- |
 | blacklistedKeys | Deeply compare names of these keys against the keys in your object. | array | Array<string￨RegExp￨BlacklistKeyConfig> | [] | N |
-| stringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. | array | RegExp[] | [] | N |
+| stringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. | array | Array<RegExp￨StringTestConfig> | [] | N |
 | fuzzyKeyMatch | Loosely compare key names by checking if the key name of your unredacted object is included anywhere within the name of your blacklisted key. For example, is "pass" (your key) included in "password" (from config). | boolean |  | false | N |
 | caseSensitiveKeyMatch | Loosely compare key names by normalising the strings. This involves removing non-word characters and transforms the string to lowercase. This means you never have to worry having to list duplicate keys in different formats such as snake_case, camelCase, PascalCase or any other case. | boolean |  | true | N |
 | remove | Determines whether or not to remove the key from the object when it is redacted. | boolean |  | false | N |
@@ -86,6 +99,13 @@ redaction.redact(obj)
 | remove | boolean | Main options `remove` | N |
 | retainStructure | boolean | Main options `retainStructure` | N |
 
+### StringTestConfig
+
+| key | description | type | required |
+| --- | --- | --- | --- |
+| pattern | A regular expression to perform against a string value, whether that value is a flat string or nested within an object. | RegExp | Y |
+| replacer | A function that will be called with the value of the string that matched the pattern and the pattern itself. This function should return the new (redacted) value to replace the original value. | function | Y |
+
 ### Benchmark
 Comparisons are made against JSON.stringify, Regex.replace, Fast Redact &
 (one of my other creations, [@hackylabs/obglob](https://npmjs.com/package/@hackylabs/obglob)) as well as different
@@ -111,21 +131,22 @@ Redact and Obglob are slower and rely on dependencies.
 
 | scenario | ops / sec | op duration (ms) | margin of error | sample count |
 | --- | --- | --- | --- | --- |
-| JSON.stringify, large object | 161827.79 | 0.0061794083 | 0.00002 | 80914 |
-| DeepRedact, remove item, single object | 26010.46 | 0.0384460656 | 0.00016 | 13006 |
-| DeepRedact, custom replacer function, single object | 22412.54 | 0.0446178767 | 0.00031 | 11207 |
-| DeepRedact, replace string by length, single object | 22323.79 | 0.044795253 | 0.00024 | 11162 |
-| DeepRedact, default config, large object | 21932.77 | 0.0455938725 | 0.00025 | 10967 |
-| Regex replace, large object | 21919.75 | 0.0456209497 | 0.00027 | 10960 |
-| DeepRedact, retain structure, single object | 18417.65 | 0.0542957469 | 0.00024 | 9212 |
-| DeepRedact, fuzzy matching, single object | 17428.25 | 0.0573781129 | 0.00028 | 8715 |
-| DeepRedact, config per key, single object | 16975.98 | 0.0589067685 | 0.00033 | 8488 |
-| DeepRedact, default config, 1000 large objects | 7787.76 | 0.1284065968 | 0.00319 | 3894 |
-| fast redact, large object | 5847.55 | 0.1710116908 | 0.00143 | 2924 |
-| DeepRedact, case insensitive matching, single object | 5136.64 | 0.1946798809 | 0.00152 | 2569 |
-| ObGlob, large object | 5083.79 | 0.1967037628 | 0.01079 | 2542 |
-| DeepRedact, fuzzy and case insensitive matching, single object | 4819.04 | 0.2075101033 | 0.00142 | 2410 |
-| JSON.stringify, 1000 large objects | 226.71 | 4.4109355351 | 0.04147 | 114 |
-| ObGlob, 1000 large objects | 164.41 | 6.0825151928 | 0.15338 | 83 |
-| fast redact, 1000 large objects | 121.82 | 8.2088192787 | 0.09619 | 61 |
-| Regex replace, 1000 large objects | 94.57 | 10.5740055833 | 0.30159 | 48 |
+| DeepRedact, XML | 171985.01 | 0.0058144601 | 0.00004 | 85993 |
+| JSON.stringify, large object | 162406.59 | 0.0061573855 | 0.00002 | 81204 |
+| DeepRedact, remove item, single object | 25293.55 | 0.039535775 | 0.00023 | 12647 |
+| Regex replace, large object | 22529.52 | 0.0443862153 | 0.00024 | 11265 |
+| DeepRedact, custom replacer function, single object | 22324.84 | 0.0447931554 | 0.00037 | 11163 |
+| DeepRedact, default config, large object | 21437.04 | 0.046648239 | 0.00028 | 10719 |
+| DeepRedact, replace string by length, single object | 21018.32 | 0.0475775519 | 0.00084 | 10510 |
+| DeepRedact, fuzzy matching, single object | 18000.38 | 0.0555543858 | 0.0003 | 9001 |
+| DeepRedact, retain structure, single object | 17581.5 | 0.056877956 | 0.00037 | 8791 |
+| DeepRedact, config per key, single object | 16914.73 | 0.0591200552 | 0.0004 | 8458 |
+| DeepRedact, default config, 1000 large objects | 7989.05 | 0.1251712531 | 0.0018 | 3995 |
+| fast redact, large object | 5929.58 | 0.1686459096 | 0.00126 | 2965 |
+| ObGlob, large object | 4939.98 | 0.2024300664 | 0.01105 | 2470 |
+| DeepRedact, case insensitive matching, single object | 4721.59 | 0.2117932541 | 0.00378 | 2361 |
+| DeepRedact, fuzzy and case insensitive matching, single object | 4686.29 | 0.2133882948 | 0.0018 | 2344 |
+| JSON.stringify, 1000 large objects | 222.05 | 4.5035912679 | 0.04553 | 112 |
+| ObGlob, 1000 large objects | 164.55 | 6.0771323614 | 0.11829 | 83 |
+| fast redact, 1000 large objects | 120.7 | 8.2848202295 | 0.05702 | 61 |
+| Regex replace, 1000 large objects | 93.5 | 10.6954525319 | 0.39014 | 47 |

package/dist/cjs/index.js

@@ -77,6 +77,24 @@ class DeepRedact {
                     },
                 };
             }
+            if (value instanceof Set) {
+                return {
+                    __unsupported: {
+                        type: 'set',
+                        values: Array.from(value),
+                    },
+                };
+            }
+            if (value instanceof Map) {
+                return {
+                    __unsupported: {
+                        type: 'map',
+                        entries: Object.fromEntries(value.entries()),
+                    },
+                };
+            }
+            if (value instanceof URL)
+                return value.toString();
             if (value instanceof Date)
                 return value.toISOString();
             return value;

package/dist/cjs/utils/redactorUtils.js

@@ -80,11 +80,32 @@ class RedactorUtils {
          * @param shouldRedact
          */
         this.redactString = (value, replacement, remove, shouldRedact) => {
-            if (!value)
+            if (!value || typeof value !== 'string')
                 return value;
             const { stringTests } = this.config;
-            if (!shouldRedact && !(stringTests === null || stringTests === void 0 ? void 0 : stringTests.some((pattern) => pattern.test(value))))
+            if (!shouldRedact) {
+                const result = stringTests === null || stringTests === void 0 ? void 0 : stringTests.map((test) => {
+                    if (test instanceof RegExp) {
+                        if (!test.test(value))
+                            return value;
+                        if (remove)
+                            return undefined;
+                        if (typeof replacement === 'function')
+                            return replacement(value);
+                        if (this.config.replaceStringByLength)
+                            return replacement.repeat(value.length);
+                        return replacement;
+                    }
+                    if (remove && test.pattern.test(value))
+                        return undefined;
+                    return test.replacer(value, test.pattern);
+                }).filter(Boolean)[0];
+                if (result)
+                    return result;
+                if (remove)
+                    return undefined;
                 return value;
+            }
             if (remove)
                 return undefined;
             if (typeof replacement === 'function')

package/dist/esm/index.mjs

@@ -72,6 +72,24 @@ class DeepRedact {
                 },
             };
         }
+        if (value instanceof Set) {
+            return {
+                __unsupported: {
+                    type: 'set',
+                    values: Array.from(value),
+                },
+            };
+        }
+        if (value instanceof Map) {
+            return {
+                __unsupported: {
+                    type: 'map',
+                    entries: Object.fromEntries(value.entries()),
+                },
+            };
+        }
+        if (value instanceof URL)
+            return value.toString();
         if (value instanceof Date)
             return value.toISOString();
         return value;

package/dist/esm/utils/redactorUtils.mjs

@@ -131,11 +131,32 @@ class RedactorUtils {
      * @param shouldRedact
      */
     redactString = (value, replacement, remove, shouldRedact) => {
-        if (!value)
+        if (!value || typeof value !== 'string')
             return value;
         const { stringTests } = this.config;
-        if (!shouldRedact && !stringTests?.some((pattern) => pattern.test(value)))
+        if (!shouldRedact) {
+            const result = stringTests?.map((test) => {
+                if (test instanceof RegExp) {
+                    if (!test.test(value))
+                        return value;
+                    if (remove)
+                        return undefined;
+                    if (typeof replacement === 'function')
+                        return replacement(value);
+                    if (this.config.replaceStringByLength)
+                        return replacement.repeat(value.length);
+                    return replacement;
+                }
+                if (remove && test.pattern.test(value))
+                    return undefined;
+                return test.replacer(value, test.pattern);
+            }).filter(Boolean)[0];
+            if (result)
+                return result;
+            if (remove)
+                return undefined;
             return value;
+        }
         if (remove)
             return undefined;
         if (typeof replacement === 'function')

package/dist/types/types.d.ts

@@ -58,7 +58,10 @@ export interface BaseDeepRedactConfig {
      *   /^[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}$/,  // redact any string that looks like an IP address.
      * ]
      */
-    stringTests?: RegExp[];
+    stringTests?: Array<RegExp | {
+        pattern: RegExp;
+        replacer: (value: string, pattern: RegExp) => string;
+    }>;
     /**
      * Perform a fuzzy match on the key. This will match any key that contains the string, rather than a case-sensitive match.
      * @default false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackylabs/deep-redact",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "A fast, safe and configurable zero-dependency library for redacting strings or deeply redacting arrays and objects.",
   "private": false,
   "license": "MIT",
@@ -25,6 +25,10 @@
     "dist"
   ],
   "keywords": [
+    "json",
+    "xml",
+    "document",
+    "fast",
     "redact",
     "redaction",
     "redactor",