@hackylabs/deep-redact 2.1.0 → 2.2.0

package/README.md

@@ -6,7 +6,9 @@
 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.
+and other outputs. Supporting both strings and objects or a mix of both, Deep Redact can be used to redact sensitive
+information from more data structures than any other redaction library. Even partially redacting sensitive information
+from strings is supported, by way of custom regex patterns and replacers.
 
 Circular references and other unsupported values are handled gracefully, and the library is designed to be as fast as
 possible while still being easy to use and configure.
@@ -58,7 +60,7 @@ objRedaction.redact(obj)
 // }
 
 const strRedaction = new DeepRedact({
-  stringTests: [
+  partialStringTests: [
     {
       pattern: /<(email|password)>([^<]+)<\/\1>/gi,
       replacer: (value: string, pattern: RegExp) => value.replace(pattern, '<$1>[REDACTED]</$1>'),
@@ -78,7 +80,8 @@ strRedaction.redact('<email>someone@somewhere.com</email><keepThis>This is fine<
 | 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 | Array<RegExp￨StringTestConfig> | [] | N |
+| stringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. Will redact whole string values. If you want to redact only part of the string, use `partialStringTests` instead. If a replacer function is provided in the config for the associated test, it will be used to redact the value. | array | Array<RegExp￨StringTestConfig> | [] | N |
+| partialStringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. Will redact only the matched part of the string using the replacer function provided in the config for the associated test. | array | 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 |
@@ -131,22 +134,23 @@ Redact and Obglob are slower and rely on dependencies.
 
 | scenario | ops / sec | op duration (ms) | margin of error | sample count |
 | --- | --- | --- | --- | --- |
-| 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 |
+| DeepRedact, partial redaction | 178183.03 | 0.0056122067 | 0.00003 | 89092 |
+| JSON.stringify, large object | 161672.63 | 0.0061853388 | 0.00004 | 80837 |
+| DeepRedact, remove item, single object | 25085.95 | 0.039862959 | 0.00033 | 12543 |
+| DeepRedact, default config, large object | 23164.57 | 0.0431693713 | 0.00023 | 11583 |
+| Regex replace, large object | 22828.32 | 0.043805244 | 0.00031 | 11415 |
+| DeepRedact, custom replacer function, single object | 22520.52 | 0.0444039553 | 0.00039 | 11261 |
+| DeepRedact, replace string by length, single object | 22470.94 | 0.0445019191 | 0.00025 | 11236 |
+| DeepRedact, retain structure, single object | 18315.67 | 0.0545980591 | 0.00026 | 9158 |
+| DeepRedact, fuzzy matching, single object | 18077.45 | 0.0553175285 | 0.00035 | 9039 |
+| DeepRedact, config per key, single object | 16055.96 | 0.0622821745 | 0.00031 | 8028 |
+| DeepRedact, default config, 1000 large objects | 8077.4 | 0.1238022 | 0.00187 | 4039 |
+| fast redact, large object | 5918.61 | 0.1689584628 | 0.00151 | 2960 |
+| ObGlob, large object | 5193.29 | 0.1925563273 | 0.00972 | 2597 |
+| DeepRedact, case insensitive matching, single object | 3477.6 | 0.2875549482 | 0.00324 | 1739 |
+| DeepRedact, fuzzy and case insensitive matching, single object | 3437.73 | 0.2908896131 | 0.00239 | 1719 |
+| ObGlob, 1000 large objects | 237.69 | 4.2072005126 | 0.05005 | 119 |
+| JSON.stringify, 1000 large objects | 230.33 | 4.3416907672 | 0.04373 | 116 |
+| DeepRedact, partial redaction large string | 127.18 | 7.8628400156 | 0.4176 | 64 |
+| fast redact, 1000 large objects | 119.33 | 8.3803393 | 0.31943 | 60 |
+| Regex replace, 1000 large objects | 97.12 | 10.2963537755 | 0.29341 | 49 |

package/dist/cjs/index.js

@@ -53,7 +53,7 @@ class DeepRedact {
                 return {
                     __unsupported: {
                         type: 'bigint',
-                        value: value.toString(),
+                        value: value.toString(10),
                         radix: 10,
                     },
                 };
@@ -148,7 +148,10 @@ class DeepRedact {
          */
         this.maybeSerialise = (value) => {
             this.circularReference = null;
-            return this.config.serialise ? JSON.stringify(value) : value;
+            const result = this.redactorUtils.partialStringRedact(value);
+            if (!this.config.serialise)
+                return result;
+            return typeof result === 'string' ? result : JSON.stringify(result);
         };
         /**
          * Redact the provided value. The value will be stripped of any circular references and other unsupported data types, before being redacted according to the configuration and finally serialised if required.

package/dist/cjs/utils/redactorUtils.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const defaultConfig = {
     stringTests: [],
     blacklistedKeys: [],
+    partialStringTests: [],
     blacklistedKeysTransformed: [],
     fuzzyKeyMatch: false,
     caseSensitiveKeyMatch: true,
@@ -14,7 +15,7 @@ const defaultConfig = {
 };
 class RedactorUtils {
     constructor(customConfig) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         /**
          * The configuration for the redaction.
          * @private
@@ -160,6 +161,28 @@ class RedactorUtils {
                 return [prop, this.recurse(val, key !== null && key !== void 0 ? key : prop, shouldRedact)];
             }).filter(([prop]) => prop !== undefined));
         };
+        this.partialStringRedact = (value) => {
+            const { partialStringTests } = this.config;
+            if (partialStringTests.length === 0)
+                return value;
+            let result;
+            if (typeof value === 'string') {
+                result = value;
+            }
+            else {
+                try {
+                    result = JSON.stringify(value);
+                }
+                catch (error) {
+                    // It should never reach this point, but if it does, it will throw an error that must not contain sensitive data.
+                    throw new Error('Failed to stringify value for partialStringRedact. Did you replace the rewriteUnsupported method with something that returns non-serialisable data?');
+                }
+            }
+            partialStringTests.forEach((test) => {
+                result = test.replacer(result, test.pattern);
+            });
+            return typeof value === 'string' ? result : JSON.parse(result);
+        };
         /**
          * Redact a value. If the value is an object or array, the redaction will be performed recursively, otherwise the value will be redacted if it is a supported type using the `replace` method.
          * @private
@@ -185,7 +208,7 @@ class RedactorUtils {
                 return this.redactArray(value);
             return this.redactObject(value, key, parentShouldRedact);
         };
-        this.config = Object.assign(Object.assign(Object.assign({}, defaultConfig), customConfig), { blacklistedKeys: (_a = customConfig.blacklistedKeys) !== null && _a !== void 0 ? _a : [], blacklistedKeysTransformed: (_c = (_b = customConfig.blacklistedKeys) === null || _b === void 0 ? void 0 : _b.map((key) => {
+        this.config = Object.assign(Object.assign(Object.assign({}, defaultConfig), customConfig), { partialStringTests: (_a = customConfig.partialStringTests) !== null && _a !== void 0 ? _a : [], blacklistedKeys: (_b = customConfig.blacklistedKeys) !== null && _b !== void 0 ? _b : [], blacklistedKeysTransformed: (_d = (_c = customConfig.blacklistedKeys) === null || _c === void 0 ? void 0 : _c.map((key) => {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
                 const isObject = !(typeof key === 'string' || key instanceof RegExp);
                 const setKey = isObject ? key.key : key;
@@ -208,7 +231,7 @@ class RedactorUtils {
                     };
                 }
                 return fallback;
-            })) !== null && _c !== void 0 ? _c : [] });
+            })) !== null && _d !== void 0 ? _d : [] });
     }
 }
 /**
@@ -217,7 +240,7 @@ class RedactorUtils {
  * @param str The string to normalise.
  * @returns {string} The normalised string.
  */
-RedactorUtils.normaliseString = (str) => str.toLowerCase().replace(/\W/g, '');
+RedactorUtils.normaliseString = (str) => str.toLowerCase().replaceAll(/\W/g, '');
 /**
  * Determine if a key matches a given blacklistedKeyConfig. This will check the key against the blacklisted keys,
  * using the configuration option for the given key falling back to the default configuration.

package/dist/esm/index.mjs

@@ -48,7 +48,7 @@ class DeepRedact {
             return {
                 __unsupported: {
                     type: 'bigint',
-                    value: value.toString(),
+                    value: value.toString(10),
                     radix: 10,
                 },
             };
@@ -141,7 +141,10 @@ class DeepRedact {
      */
     maybeSerialise = (value) => {
         this.circularReference = null;
-        return this.config.serialise ? JSON.stringify(value) : value;
+        const result = this.redactorUtils.partialStringRedact(value);
+        if (!this.config.serialise)
+            return result;
+        return typeof result === 'string' ? result : JSON.stringify(result);
     };
     /**
      * Redact the provided value. The value will be stripped of any circular references and other unsupported data types, before being redacted according to the configuration and finally serialised if required.

package/dist/esm/utils/redactorUtils.mjs

@@ -1,6 +1,7 @@
 const defaultConfig = {
     stringTests: [],
     blacklistedKeys: [],
+    partialStringTests: [],
     blacklistedKeysTransformed: [],
     fuzzyKeyMatch: false,
     caseSensitiveKeyMatch: true,
@@ -20,6 +21,7 @@ class RedactorUtils {
         this.config = {
             ...defaultConfig,
             ...customConfig,
+            partialStringTests: customConfig.partialStringTests ?? [],
             blacklistedKeys: customConfig.blacklistedKeys ?? [],
             blacklistedKeysTransformed: customConfig.blacklistedKeys?.map((key) => {
                 const isObject = !(typeof key === 'string' || key instanceof RegExp);
@@ -52,7 +54,7 @@ class RedactorUtils {
      * @param str The string to normalise.
      * @returns {string} The normalised string.
      */
-    static normaliseString = (str) => str.toLowerCase().replace(/\W/g, '');
+    static normaliseString = (str) => str.toLowerCase().replaceAll(/\W/g, '');
     /**
      * Determine if a key matches a given blacklistedKeyConfig. This will check the key against the blacklisted keys,
      * using the configuration option for the given key falling back to the default configuration.
@@ -211,6 +213,28 @@ class RedactorUtils {
             return [prop, this.recurse(val, key ?? prop, shouldRedact)];
         }).filter(([prop]) => prop !== undefined));
     };
+    partialStringRedact = (value) => {
+        const { partialStringTests } = this.config;
+        if (partialStringTests.length === 0)
+            return value;
+        let result;
+        if (typeof value === 'string') {
+            result = value;
+        }
+        else {
+            try {
+                result = JSON.stringify(value);
+            }
+            catch (error) {
+                // It should never reach this point, but if it does, it will throw an error that must not contain sensitive data.
+                throw new Error('Failed to stringify value for partialStringRedact. Did you replace the rewriteUnsupported method with something that returns non-serialisable data?');
+            }
+        }
+        partialStringTests.forEach((test) => {
+            result = test.replacer(result, test.pattern);
+        });
+        return typeof value === 'string' ? result : JSON.parse(result);
+    };
     /**
      * Redact a value. If the value is an object or array, the redaction will be performed recursively, otherwise the value will be redacted if it is a supported type using the `replace` method.
      * @private

package/dist/types/types.d.ts

@@ -42,6 +42,10 @@ export interface BlacklistKeyConfig {
      */
     key: string | RegExp;
 }
+export interface ComplexStringTest {
+    pattern: RegExp;
+    replacer: (value: string, pattern: RegExp) => string;
+}
 export interface BaseDeepRedactConfig {
     /**
      * Keys that should be redacted. Can be a string, or an object with additional configuration options.
@@ -58,10 +62,8 @@ 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?: Array<RegExp | {
-        pattern: RegExp;
-        replacer: (value: string, pattern: RegExp) => string;
-    }>;
+    stringTests?: Array<RegExp | ComplexStringTest>;
+    partialStringTests?: Array<ComplexStringTest>;
     /**
      * Perform a fuzzy match on the key. This will match any key that contains the string, rather than a case-sensitive match.
      * @default false
@@ -122,8 +124,20 @@ export interface BaseDeepRedactConfig {
     serialize?: boolean;
 }
 export type DeepRedactConfig = Partial<Omit<BaseDeepRedactConfig, 'blacklistedKeysTransformed' | 'blacklistedKeys' | 'stringTests'>> & ({
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
     blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
     stringTests: BaseDeepRedactConfig['stringTests'];
+} | {
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
+    blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
+} | {
+    blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
+    stringTests: BaseDeepRedactConfig['stringTests'];
+} | {
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
+    stringTests: BaseDeepRedactConfig['stringTests'];
+} | {
+    partialStringTests: BaseDeepRedactConfig['partialStringTests'];
 } | {
     blacklistedKeys: BaseDeepRedactConfig['blacklistedKeys'];
 } | {

package/dist/types/utils/redactorUtils.d.ts

@@ -77,6 +77,7 @@ declare class RedactorUtils {
      * @param {boolean} parentShouldRedact Whether the item should be redacted based on the key within the parent object.
      */
     private redactObject;
+    partialStringRedact: (value: unknown) => unknown;
     /**
      * Redact a value. If the value is an object or array, the redaction will be performed recursively, otherwise the value will be redacted if it is a supported type using the `replace` method.
      * @private

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackylabs/deep-redact",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A fast, safe and configurable zero-dependency library for redacting strings or deeply redacting arrays and objects.",
   "private": false,
   "license": "MIT",