@logtape/redaction/dist/field.d.ts

Redact sensitive data from log messages

import { RedactionTraversalOptions } from "./traversal.js";
import { Sink } from "@logtape/logtape";

//#region src/field.d.ts

/**
 * The type for a field pattern used in redaction.  A string or a regular
 * expression that matches field names.
 * @since 0.10.0
 */
type FieldPattern = string | RegExp;
/**
 * An array of field patterns used for redaction.  Each pattern can be
 * a string or a regular expression that matches field names.
 * @since 0.10.0
 */
type FieldPatterns = FieldPattern[];
/**
 * The synchronous action to perform on a redacted field value.
 * @since 0.10.0
 */
type FieldRedactionAction = "delete" | ((value: unknown) => unknown);
/**
 * The asynchronous action to perform on a redacted field value.
 * @since 2.1.0
 */
type AsyncFieldRedactionAction = (value: unknown) => PromiseLike<unknown>;
/**
 * A pseudonymizer created by {@link createHmacPseudonymizer}.
 * @since 2.1.0
 */
type HmacPseudonymizer = (value: unknown) => Promise<string>;
/**
 * Default field patterns for redaction.  These patterns will match
 * common sensitive fields such as passwords, tokens, and personal
 * information.
 * @since 0.10.0
 */
declare const DEFAULT_REDACT_FIELDS: FieldPatterns;
/**
 * Options for redacting fields in a {@link LogRecord}.  Used by
 * the {@link redactByField} function.
 * @since 0.10.0
 */
interface FieldRedactionOptions extends RedactionTraversalOptions {
  /**
   * The field patterns to match against.  This can be an array of
   * strings or regular expressions.  If a field matches any of the
   * patterns, it will be redacted.
   * @defaultValue {@link DEFAULT_REDACT_FIELDS}
   */
  readonly fieldPatterns: FieldPatterns;
  /**
   * The action to perform on the matched fields.  If not provided,
   * the default action is to delete the field from the properties.
   * If a function is provided, it will be called with the
   * value of the field, and the return value will be used to replace
   * the field in the properties.
   * If the action is `"delete"`, the field will be removed from the
   * properties.
   * @default `"delete"`
   */
  readonly action?: FieldRedactionAction;
  /**
   * Maximum recursion depth for object and array traversal.
   * @default `20`
   * @since 2.2.0
   */
  readonly maxDepth?: number;
  /**
   * Maximum number of properties or array elements to process per object.
   * @default `1000`
   * @since 2.2.0
   */
  readonly maxProperties?: number;
}
/**
 * Options for asynchronously redacting fields in a {@link LogRecord}.  Used by
 * the {@link redactByFieldAsync} function.
 * @since 2.1.0
 */
interface AsyncFieldRedactionOptions extends RedactionTraversalOptions {
  /**
   * The field patterns to match against.  This can be an array of
   * strings or regular expressions.  If a field matches any of the
   * patterns, it will be redacted.
   */
  readonly fieldPatterns: FieldPatterns;
  /**
   * The asynchronous action to perform on the matched fields.
   */
  readonly action: AsyncFieldRedactionAction;
  /**
   * Maximum recursion depth for object and array traversal.
   * @default `20`
   * @since 2.2.0
   */
  readonly maxDepth?: number;
  /**
   * Maximum number of properties or array elements to process per object.
   * @default `1000`
   * @since 2.2.0
   */
  readonly maxProperties?: number;
}
/**
 * Options for the {@link createHmacPseudonymizer} function.
 * @since 2.1.0
 */
interface HmacPseudonymizerOptions {
  /**
   * The secret key to use for HMAC.  Strings are encoded as UTF-8.
   */
  readonly key: string | Uint8Array | ArrayBuffer | CryptoKey;
  /**
   * The HMAC hash algorithm.
   * @default `"SHA-256"`
   */
  readonly hash?: "SHA-256" | "SHA-384" | "SHA-512";
  /**
   * The digest encoding.
   * @default `"base64url"`
   */
  readonly encoding?: "base64url" | "hex";
  /**
   * The string prefix to prepend to each pseudonym.  If omitted, a prefix based
   * on the hash algorithm is used, such as `"hmac-sha256:"`.  Set this to an
   * empty string to disable the prefix.
   */
  readonly prefix?: string;
}
/**
 * Redacts properties and message values in a {@link LogRecord} based on the
 * provided field patterns and action.
 *
 * Note that it is a decorator which wraps the sink and redacts properties
 * and message values before passing them to the sink.
 *
 * For string templates (e.g., `"Hello, {name}!"`), placeholder names are
 * matched against the field patterns to determine which values to redact.
 *
 * For tagged template literals (e.g., `` `Hello, ${name}!` ``), redaction
 * is performed by comparing message values with redacted property values.
 *
 * @example
 * ```ts
 * import { getConsoleSink } from "@logtape/logtape";
 * import { redactByField } from "@logtape/redaction";
 *
 * const sink = redactByField(getConsoleSink());
 * ```
 *
 * @param sink The sink to wrap.
 * @param options The redaction options.
 * @returns The wrapped sink.
 * @since 0.10.0
 */
declare function redactByField(sink: Sink | Sink & Disposable | Sink & AsyncDisposable, options?: FieldRedactionOptions | FieldPatterns): Sink | Sink & Disposable | Sink & AsyncDisposable;
/**
 * Redacts properties and message values in a {@link LogRecord} based on the
 * provided field patterns and asynchronous action.
 *
 * The returned sink preserves record ordering by processing redaction work in
 * sequence and implements {@link AsyncDisposable} so callers can wait for all
 * pending redaction work before shutdown.
 *
 * @example
 * ```ts
 * import { getConsoleSink } from "@logtape/logtape";
 * import {
 *   createHmacPseudonymizer,
 *   redactByFieldAsync,
 * } from "@logtape/redaction";
 *
 * const pseudonymize = await createHmacPseudonymizer({ key: "secret" });
 * const sink = redactByFieldAsync(getConsoleSink(), {
 *   fieldPatterns: [/userId/i, /email/i],
 *   action: pseudonymize,
 * });
 * ```
 *
 * @param sink The sink to wrap.
 * @param options The async redaction options.
 * @returns The wrapped sink.
 * @since 2.1.0
 */
declare function redactByFieldAsync(sink: Sink | Sink & Disposable | Sink & AsyncDisposable, options: AsyncFieldRedactionOptions): Sink & AsyncDisposable;
/**
 * Creates an asynchronous pseudonymizer based on HMAC using the Web Crypto API.
 *
 * The returned function converts each value with `String(value)`, encodes it
 * as UTF-8, and returns a stable pseudonym.  Because HMAC is keyed, this is
 * safer than a plain salted hash for values with small input spaces, such as
 * email addresses or numeric user IDs.
 *
 * @param options The HMAC pseudonymizer options.
 * @returns An async redaction action.
 * @since 2.1.0
 */
declare function createHmacPseudonymizer(options: HmacPseudonymizerOptions): Promise<HmacPseudonymizer>;
/**
 * Redacts properties from an object based on specified field patterns.
 *
 * This function creates a shallow copy of the input object and applies
 * redaction rules to its properties. For properties that match the redaction
 * patterns, the function either removes them or transforms their values based
 * on the provided action.
 *
 * The redaction process is recursive and will be applied to nested objects
 * as well, allowing for deep redaction of sensitive data in complex object
 * structures.
 * @param properties The properties to redact.
 * @param options The redaction options.
 * @returns The redacted properties.
 * @since 0.10.0
 */
//#endregion
export { AsyncFieldRedactionAction, AsyncFieldRedactionOptions, DEFAULT_REDACT_FIELDS, FieldPattern, FieldPatterns, FieldRedactionAction, FieldRedactionOptions, HmacPseudonymizer, HmacPseudonymizerOptions, createHmacPseudonymizer, redactByField, redactByFieldAsync };
//# sourceMappingURL=field.d.ts.map