@hackylabs/deep-redact 2.2.0 → 3.0.0

package/dist/esm/index.mjs

@@ -1,15 +1,10 @@
-import RedactorUtils from './utils/redactorUtils';
+import RedactorUtils from './utils';
 class DeepRedact {
     /**
      * The redactorUtils instance to handle the redaction.
      * @private
      */
     redactorUtils;
-    /**
-     * A WeakSet to store circular references during redaction. Reset to null after redaction is complete.
-     * @private
-     */
-    circularReference = null;
     /**
      * The configuration for the redaction.
      * @private
@@ -25,134 +20,20 @@ class DeepRedact {
      */
     constructor(config) {
         const { serialise, serialize, ...rest } = config;
-        this.redactorUtils = new RedactorUtils(rest);
-        if (serialise !== undefined)
-            this.config.serialise = serialise;
-        if (serialize !== undefined)
-            this.config.serialise = serialize;
+        const englishSerialise = serialise ?? serialize;
+        if (typeof englishSerialise === 'boolean')
+            this.config.serialise = englishSerialise;
+        this.redactorUtils = new RedactorUtils({ ...rest });
     }
-    /**
-     * A transformer for unsupported data types. If `serialise` is false, the value will be returned as is,
-     * otherwise it will transform the value into a format that is supported by JSON.stringify.
-     *
-     * Error, RegExp, and Date instances are technically supported by JSON.stringify,
-     * but they returned as empty objects, therefore they are also transformed here.
-     * @protected
-     * @param {unknown} value The value that is not supported by JSON.stringify.
-     * @returns {unknown} The value in a format that is supported by JSON.stringify.
-     */
-    unsupportedTransformer = (value) => {
-        if (!this.config.serialise)
-            return value;
-        if (typeof value === 'bigint') {
-            return {
-                __unsupported: {
-                    type: 'bigint',
-                    value: value.toString(10),
-                    radix: 10,
-                },
-            };
-        }
-        if (value instanceof Error) {
-            return {
-                __unsupported: {
-                    type: 'error',
-                    name: value.name,
-                    message: value.message,
-                    stack: value.stack,
-                },
-            };
-        }
-        if (value instanceof RegExp) {
-            return {
-                __unsupported: {
-                    type: 'regexp',
-                    source: value.source,
-                    flags: value.flags,
-                },
-            };
-        }
-        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;
-    };
-    /**
-     * Calls `unsupportedTransformer` on the provided value and rewrites any circular references.
-     *
-     * Circular references will always be removed to avoid infinite recursion.
-     * When a circular reference is found, the value will be replaced with `[[CIRCULAR_REFERENCE: path.to.original.value]]`.
-     * @protected
-     * @param {unknown} value The value to rewrite.
-     * @param {string | undefined} path The path to the value in the object.
-     * @returns {unknown} The rewritten value.
-     */
-    rewriteUnsupported = (value, path) => {
-        const safeValue = this.unsupportedTransformer(value);
-        if (!(safeValue instanceof Object))
-            return safeValue;
-        if (this.circularReference === null)
-            this.circularReference = new WeakSet();
-        if (Array.isArray(safeValue)) {
-            return safeValue.map((val, index) => {
-                const newPath = path ? `${path}.[${index}]` : `[${index}]`;
-                if (this.circularReference?.has(val))
-                    return `[[CIRCULAR_REFERENCE: ${newPath}]]`;
-                if (val instanceof Object) {
-                    this.circularReference?.add(val);
-                    return this.rewriteUnsupported(val, newPath);
-                }
-                return val;
-            });
-        }
-        return Object.fromEntries(Object.entries(safeValue).map(([key, val]) => {
-            const newPath = path ? `${path}.${key}` : key;
-            if (this.circularReference?.has(val))
-                return [key, `[[CIRCULAR_REFERENCE: ${newPath}]]`];
-            if (val instanceof Object)
-                this.circularReference?.add(val);
-            return [key, this.rewriteUnsupported(val, path ? `${path}.${key}` : key)];
-        }));
-    };
-    /**
-     * Depending on the value of `serialise`, return the value as a JSON string or as the provided value.
-     *
-     * Also resets the `circularReference` property to null after redaction is complete.
-     * This is to ensure that the WeakSet doesn't cause memory leaks.
-     * @private
-     * @param value
-     */
-    maybeSerialise = (value) => {
-        this.circularReference = null;
-        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.
      * @param {unknown} value The value to redact.
      * @returns {unknown} The redacted value.
+     * @throws {Error} If the value cannot be serialised to JSON and serialise is true.
      */
     redact = (value) => {
-        return this.maybeSerialise(this.redactorUtils.recurse(this.rewriteUnsupported(value)));
+        const redacted = this.redactorUtils.traverse(value);
+        return this.config.serialise ? JSON.stringify(redacted) : redacted;
     };
 }
-export { DeepRedact as default, DeepRedact };
+export { DeepRedact, DeepRedact as default, };

package/dist/esm/utils/index.mjs

@@ -0,0 +1,423 @@
+import { standardTransformers } from './standardTransformers';
+const defaultConfig = {
+    stringTests: [],
+    blacklistedKeys: [],
+    fuzzyKeyMatch: false,
+    caseSensitiveKeyMatch: true,
+    retainStructure: false,
+    remove: false,
+    replaceStringByLength: false,
+    replacement: '[REDACTED]',
+    types: ['string'],
+    transformers: standardTransformers,
+};
+class RedactorUtils {
+    /**
+     * The configuration for the redaction.
+     * @private
+     */
+    config = defaultConfig;
+    /**
+     * The computed regex pattern generated from sanitised blacklist keys of flat strings
+     * @private
+     */
+    computedRegex = null;
+    /**
+     * Regex to sanitise strings for the computed regex
+     * @private
+     */
+    sanitiseRegex = /[^a-zA-Z0-9_\-\$]/g;
+    /**
+     * The transformed blacklist keys of flat regex patterns and complex config objects
+     * @private
+     */
+    blacklistedKeysTransformed = [];
+    constructor(customConfig) {
+        this.config = {
+            ...defaultConfig,
+            ...customConfig,
+        };
+        this.blacklistedKeysTransformed = (customConfig.blacklistedKeys ?? []).filter(key => typeof key !== 'string').map((key) => this.createTransformedBlacklistedKey(key, customConfig));
+        const stringKeys = (customConfig.blacklistedKeys ?? []).filter(key => typeof key === 'string');
+        if (stringKeys.length > 0)
+            this.computedRegex = new RegExp(stringKeys.map(this.sanitiseStringForRegex).filter(Boolean).join('|'));
+    }
+    createTransformedBlacklistedKey = (key, customConfig) => {
+        if (key instanceof RegExp) {
+            return {
+                key,
+                fuzzyKeyMatch: customConfig.fuzzyKeyMatch ?? defaultConfig.fuzzyKeyMatch,
+                caseSensitiveKeyMatch: customConfig.caseSensitiveKeyMatch ?? defaultConfig.caseSensitiveKeyMatch,
+                retainStructure: customConfig.retainStructure ?? defaultConfig.retainStructure,
+                replacement: customConfig.replacement ?? defaultConfig.replacement,
+                replaceStringByLength: customConfig.replaceStringByLength ?? defaultConfig.replaceStringByLength,
+                remove: customConfig.remove ?? defaultConfig.remove,
+            };
+        }
+        return {
+            fuzzyKeyMatch: key.fuzzyKeyMatch ?? customConfig.fuzzyKeyMatch ?? defaultConfig.fuzzyKeyMatch,
+            caseSensitiveKeyMatch: key.caseSensitiveKeyMatch ?? customConfig.caseSensitiveKeyMatch ?? defaultConfig.caseSensitiveKeyMatch,
+            retainStructure: key.retainStructure ?? customConfig.retainStructure ?? defaultConfig.retainStructure,
+            replacement: key.replacement ?? customConfig.replacement ?? defaultConfig.replacement,
+            replaceStringByLength: key.replaceStringByLength ?? customConfig.replaceStringByLength ?? defaultConfig.replaceStringByLength,
+            remove: key.remove ?? customConfig.remove ?? defaultConfig.remove,
+            key: key.key,
+        };
+    };
+    /**
+     * Applies transformers to a value
+     * @param value - The value to transform
+     * @param key - The key to check
+     * @returns The transformed value
+     * @private
+     */
+    applyTransformers = (value, key, referenceMap) => {
+        if (typeof value === 'string')
+            return value;
+        let transformed = value;
+        for (const transformer of this.config.transformers) {
+            transformed = transformer(transformed, key, referenceMap);
+            if (transformed !== value)
+                return transformed;
+        }
+        return value;
+    };
+    /**
+     * Sanitises a string for the computed regex
+     * @param key - The string to sanitise
+     * @returns The sanitised string
+     * @private
+     */
+    sanitiseStringForRegex = (key) => key.replace(this.sanitiseRegex, '');
+    /**
+     * Checks if a key should be redacted
+     * @param key - The key to check
+     * @returns Whether the key should be redacted
+     * @private
+     */
+    shouldRedactKey = (key) => {
+        if (this.computedRegex?.test(this.sanitiseStringForRegex(key)))
+            return true;
+        return this.blacklistedKeysTransformed.some(config => {
+            const pattern = config.key;
+            if (pattern instanceof RegExp)
+                return pattern.test(key);
+            if (!config.fuzzyKeyMatch && !config.caseSensitiveKeyMatch)
+                return key.toLowerCase() === pattern.toLowerCase();
+            if (config.fuzzyKeyMatch && !config.caseSensitiveKeyMatch)
+                return key.toLowerCase().includes(pattern.toLowerCase());
+            if (config.fuzzyKeyMatch && config.caseSensitiveKeyMatch)
+                return key.includes(pattern);
+            if (!config.fuzzyKeyMatch && config.caseSensitiveKeyMatch)
+                return key === pattern;
+        });
+    };
+    /**
+     * Checks if a value should be redacted
+     * @param value - The value to check
+     * @param key - The key to check
+     * @returns Whether the value should be redacted
+     * @private
+     */
+    shouldRedactValue = (value, valueKey) => {
+        if (!this.config.types.includes(typeof value))
+            return false;
+        return this.shouldRedactKey(valueKey);
+    };
+    /**
+     * Redacts a value based on the key-specific config
+     * @param value - The value to redact
+     * @param key - The key to check
+     * @param redactingParent - Whether the parent is being redacted
+     * @returns The redacted value
+     * @private
+     */
+    redactValue = (value, redactingParent, keyConfig) => {
+        if (!this.config.types.includes(typeof value))
+            return { transformed: value, redactingParent };
+        const remove = keyConfig?.remove ?? this.config.remove;
+        const replacement = keyConfig?.replacement ?? this.config.replacement;
+        const replaceStringByLength = keyConfig?.replaceStringByLength ?? this.config.replaceStringByLength;
+        const retainStructure = keyConfig?.retainStructure ?? this.config.retainStructure;
+        if (retainStructure && typeof value === 'object' && value !== null)
+            return { transformed: value, redactingParent: true };
+        if (remove)
+            return { transformed: undefined, redactingParent };
+        if (typeof replacement === 'function')
+            return { transformed: replacement(value), redactingParent };
+        return {
+            redactingParent,
+            transformed: (typeof value === 'string' && replaceStringByLength)
+                ? replacement.toString().repeat(value.length)
+                : replacement,
+        };
+    };
+    /**
+     * Applies string transformations
+     * @param value - The value to transform
+     * @param key - The key to check
+     * @returns The transformed value
+     * @private
+     */
+    applyStringTransformations(value, amRedactingParent, keyConfig) {
+        if ((this.config.stringTests ?? []).length === 0)
+            return { transformed: value, redactingParent: amRedactingParent };
+        for (const test of this.config.stringTests) {
+            if (test instanceof RegExp) {
+                if (test.test(value)) {
+                    const { transformed, redactingParent } = this.redactValue(value, amRedactingParent, keyConfig);
+                    return { transformed: transformed, redactingParent };
+                }
+            }
+            else {
+                if (test.pattern.test(value)) {
+                    const transformed = test.replacer(value, test.pattern);
+                    return { transformed, redactingParent: amRedactingParent };
+                }
+            }
+        }
+        return { transformed: value, redactingParent: amRedactingParent };
+    }
+    /**
+     * Handles primitive values
+     * @param value - The value to handle
+     * @param key - The key to check
+     * @param redactingParent - Whether the parent is being redacted
+     * @param keyConfig - The key config
+     * @returns The transformed value
+     * @private
+     */
+    handlePrimitiveValue(value, valueKey, redactingParent, keyConfig) {
+        let transformed = value;
+        if (redactingParent) {
+            if (valueKey === '_transformer' || !this.config.types.includes(typeof value)) {
+                return { transformed: value, redactingParent };
+            }
+            const { transformed: transformedValue } = this.redactValue(value, redactingParent, keyConfig);
+            return { transformed: transformedValue, redactingParent };
+        }
+        if (keyConfig || this.shouldRedactValue(value, valueKey)) {
+            return this.redactValue(value, redactingParent, keyConfig);
+        }
+        if (typeof value === 'string') {
+            return this.applyStringTransformations(value, redactingParent, keyConfig);
+        }
+        return { transformed, redactingParent };
+    }
+    /**
+     * Handles object values
+     * @param value - The value to handle
+     * @param key - The key to check
+     * @param path - The path to the value
+     * @param redactingParent - Whether the parent is being redacted
+     * @param referenceMap - The reference map
+     * @returns The transformed value and stack
+     * @private
+     */
+    handleObjectValue(value, key, path, amRedactingParent, referenceMap, keyConfig) {
+        const fullPath = path.join('.');
+        const shouldRedact = amRedactingParent || Boolean(keyConfig) || this.shouldRedactValue(value, key);
+        referenceMap.set(value, fullPath);
+        if (shouldRedact && !(keyConfig?.retainStructure ?? this.config.retainStructure)) {
+            const { transformed, redactingParent } = this.redactValue(value, amRedactingParent, keyConfig);
+            return { transformed, redactingParent, stack: [] };
+        }
+        return this.handleRetainStructure(value, path, shouldRedact);
+    }
+    /**
+     * Handles object values
+     * @param value - The value to handle
+     * @param path - The path to the value
+     * @param redactingParent - Whether the parent is being redacted
+     * @returns The transformed value and stack
+     * @private
+     */
+    handleRetainStructure(value, path, redactingParent) {
+        const newValue = Array.isArray(value) ? [] : {};
+        const stack = [];
+        if (Array.isArray(value)) {
+            for (let i = value.length - 1; i >= 0; i--) {
+                stack.push({
+                    parent: newValue,
+                    key: i.toString(),
+                    value: value[i],
+                    path: [...path, i],
+                    redactingParent,
+                    keyConfig: this.findMatchingKeyConfig(i.toString()),
+                });
+            }
+        }
+        else {
+            for (const [propKey, propValue] of Object.entries(value).reverse()) {
+                stack.push({
+                    parent: newValue,
+                    key: propKey,
+                    value: propValue,
+                    path: [...path, propKey],
+                    redactingParent,
+                    keyConfig: this.findMatchingKeyConfig(propKey),
+                });
+            }
+        }
+        return { transformed: newValue, redactingParent, stack };
+    }
+    /**
+     * Finds the matching key config
+     * @param key - The key to find
+     * @returns The matching key config
+     * @private
+     */
+    findMatchingKeyConfig(key) {
+        if (this.computedRegex?.test(key)) {
+            return {
+                key,
+                fuzzyKeyMatch: this.config.fuzzyKeyMatch,
+                caseSensitiveKeyMatch: this.config.caseSensitiveKeyMatch,
+                replaceStringByLength: this.config.replaceStringByLength,
+                replacement: this.config.replacement,
+                retainStructure: this.config.retainStructure,
+                remove: this.config.remove,
+            };
+        }
+        return this.blacklistedKeysTransformed.find(config => {
+            const pattern = config.key;
+            if (pattern instanceof RegExp)
+                return pattern.test(key);
+            if (config.fuzzyKeyMatch) {
+                const compareKey = config.caseSensitiveKeyMatch ? key : key.toLowerCase();
+                const comparePattern = config.caseSensitiveKeyMatch ? pattern : pattern.toLowerCase();
+                return compareKey.includes(comparePattern);
+            }
+            return config.caseSensitiveKeyMatch ? key === pattern : key.toLowerCase() === pattern.toLowerCase();
+        });
+    }
+    /**
+     * Initialises the traversal
+     * @param raw - The raw value to traverse
+     * @returns The output and stack
+     * @private
+     */
+    initialiseTraversal(raw) {
+        const output = Array.isArray(raw) ? [] : {};
+        const stack = [];
+        if (typeof raw === 'object' && raw !== null) {
+            if (Array.isArray(raw)) {
+                for (let i = raw.length - 1; i >= 0; i--) {
+                    stack.push({
+                        parent: output,
+                        key: i.toString(),
+                        value: raw[i],
+                        path: [i],
+                        redactingParent: false,
+                        keyConfig: this.findMatchingKeyConfig(i.toString()),
+                    });
+                }
+            }
+            else {
+                for (const [propKey, propValue] of Object.entries(raw).reverse()) {
+                    stack.push({
+                        parent: output,
+                        key: propKey,
+                        value: propValue,
+                        path: [propKey],
+                        redactingParent: false,
+                        keyConfig: this.findMatchingKeyConfig(propKey),
+                    });
+                }
+            }
+        }
+        return { output, stack };
+    }
+    /**
+     * Pre-processes the input to replace circular references with transformer objects
+     * @param raw - The raw value to process
+     * @returns The processed value with circular references replaced
+     * @private
+     */
+    replaceCircularReferences(raw) {
+        if (typeof raw !== 'object' || raw === null)
+            return raw;
+        const visiting = new WeakSet();
+        const pathMap = new WeakMap();
+        const processValue = (value, path) => {
+            if (typeof value !== 'object' || value === null)
+                return value;
+            if (visiting.has(value)) {
+                const originalPath = pathMap.get(value) || '';
+                return {
+                    _transformer: 'circular',
+                    value: originalPath,
+                    path: path
+                };
+            }
+            visiting.add(value);
+            pathMap.set(value, path);
+            let result;
+            if (Array.isArray(value)) {
+                let hasCircular = false;
+                const newArray = value.map((item, index) => {
+                    const itemPath = path ? `${path}.${index}` : index.toString();
+                    const processed = processValue(item, itemPath);
+                    if (processed !== item)
+                        hasCircular = true;
+                    return processed;
+                });
+                result = hasCircular ? newArray : value;
+            }
+            else {
+                let hasCircular = false;
+                const newObj = {};
+                for (const [key, val] of Object.entries(value)) {
+                    const valuePath = path ? `${path}.${key}` : key;
+                    const processed = processValue(val, valuePath);
+                    newObj[key] = processed;
+                    if (processed !== val)
+                        hasCircular = true;
+                }
+                result = hasCircular ? newObj : value;
+            }
+            visiting.delete(value);
+            return result;
+        };
+        return processValue(raw, '');
+    }
+    /**
+     * Traverses the raw value
+     * @param raw - The raw value to traverse
+     * @returns The transformed value
+     */
+    traverse = (raw) => {
+        if (typeof raw === 'string') {
+            const { transformed } = this.applyStringTransformations(raw, false);
+            return transformed;
+        }
+        if (typeof raw !== 'object' || raw === null)
+            return raw;
+        const referenceMap = new WeakMap();
+        const cleanedInput = this.replaceCircularReferences(raw);
+        const { output, stack } = this.initialiseTraversal(cleanedInput);
+        if (typeof cleanedInput === 'object' && cleanedInput !== null)
+            referenceMap.set(cleanedInput, '');
+        while (stack.length > 0) {
+            const { parent, key, value, path, redactingParent: amRedactingParent, keyConfig } = stack.pop();
+            let transformed = this.applyTransformers(value, key, referenceMap);
+            let redactingParent = amRedactingParent;
+            if (typeof transformed !== 'object' || transformed === null) {
+                const primitiveResult = this.handlePrimitiveValue(transformed, key, amRedactingParent, keyConfig);
+                redactingParent = primitiveResult.redactingParent;
+                transformed = primitiveResult.transformed;
+                if (typeof transformed === 'undefined')
+                    continue;
+            }
+            else {
+                const objectResult = this.handleObjectValue(transformed, key, path, redactingParent, referenceMap, keyConfig);
+                transformed = objectResult.transformed;
+                stack.push(...objectResult.stack);
+            }
+            if (parent !== null && key !== null)
+                parent[key] = transformed;
+        }
+        return output;
+    };
+}
+export default RedactorUtils;

package/dist/esm/utils/standardTransformers/bigint.js

@@ -0,0 +1,6 @@
+export const _bigint = (value) => {
+    if (typeof value !== 'bigint')
+        return value;
+    const radix = 10;
+    return { value: { radix, number: value.toString(radix) }, _transformer: 'bigint' };
+};

package/dist/esm/utils/standardTransformers/date.js

@@ -0,0 +1,5 @@
+export const _date = (value) => {
+    if (value instanceof Date)
+        return { datetime: value.toISOString(), _transformer: 'date' };
+    return value;
+};

package/dist/esm/utils/standardTransformers/error.js

@@ -0,0 +1,12 @@
+export const _error = (value) => {
+    if (!(value instanceof Error))
+        return value;
+    return {
+        _transformer: 'error',
+        value: {
+            type: value.constructor.name,
+            message: value.message,
+            stack: value.stack,
+        },
+    };
+};

package/dist/esm/utils/standardTransformers/index.js

@@ -0,0 +1,16 @@
+import { _bigint } from "./bigint";
+import { _date } from "./date";
+import { _error } from "./error";
+import { _map } from "./map";
+import { _regex } from "./regex";
+import { _set } from "./set";
+import { _url } from "./url";
+export const standardTransformers = [
+    _bigint,
+    _url,
+    _date,
+    _error,
+    _map,
+    _set,
+    _regex,
+];

package/dist/esm/utils/standardTransformers/map.js

@@ -0,0 +1,5 @@
+export const _map = (value) => {
+    if (value instanceof Map)
+        return { value: Object.fromEntries(value.entries()), _transformer: 'map' };
+    return value;
+};

package/dist/esm/utils/standardTransformers/regex.js

@@ -0,0 +1,11 @@
+export const _regex = (value) => {
+    if (!(value instanceof RegExp))
+        return value;
+    return {
+        _transformer: 'regex',
+        value: {
+            source: value.source,
+            flags: value.flags,
+        },
+    };
+};

package/dist/esm/utils/standardTransformers/set.js

@@ -0,0 +1,5 @@
+export const _set = (value) => {
+    if (value instanceof Set)
+        return { value: Array.from(value), _transformer: 'set' };
+    return value;
+};

package/dist/esm/utils/standardTransformers/url.js

@@ -0,0 +1,5 @@
+export const _url = (value) => {
+    if (value instanceof URL)
+        return { value: value.toString(), _transformer: 'url' };
+    return value;
+};