@logtape/redaction 2.1.0-dev.600 → 2.1.0

package/dist/field.d.ts

@@ -14,6 +14,21 @@ type FieldPattern = string | RegExp;
  * @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
@@ -44,7 +59,50 @@ interface FieldRedactionOptions {
    * properties.
    * @default `"delete"`
    */
-  readonly action?: "delete" | ((value: unknown) => unknown);
+  readonly action?: FieldRedactionAction;
+}
+/**
+ * Options for asynchronously redacting fields in a {@link LogRecord}.  Used by
+ * the {@link redactByFieldAsync} function.
+ * @since 2.1.0
+ */
+interface AsyncFieldRedactionOptions {
+  /**
+   * 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;
+}
+/**
+ * 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
@@ -73,6 +131,48 @@ interface FieldRedactionOptions {
  * @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.
  *
@@ -90,5 +190,5 @@ declare function redactByField(sink: Sink | Sink & Disposable | Sink & AsyncDisp
  * @since 0.10.0
  */
 //#endregion
-export { DEFAULT_REDACT_FIELDS, FieldPattern, FieldPatterns, FieldRedactionOptions, redactByField };
+export { AsyncFieldRedactionAction, AsyncFieldRedactionOptions, DEFAULT_REDACT_FIELDS, FieldPattern, FieldPatterns, FieldRedactionAction, FieldRedactionOptions, HmacPseudonymizer, HmacPseudonymizerOptions, createHmacPseudonymizer, redactByField, redactByFieldAsync };
 //# sourceMappingURL=field.d.ts.map

package/dist/field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field.d.ts","names":[],"sources":["../src/field.ts"],"sourcesContent":[],"mappings":";;;;;;AAOA;AAOA;AAQA;AAqBiB,KApCL,YAAA,GAoCK,MAAqB,GApCF,MA2CV;AAyC1B;;;;;AACmC,KA9EvB,aAAA,GAAgB,YA8EO,EAAA;;;;;;;AAEL,cAxEjB,qBAwEiB,EAxEM,aAwEN;;AAAsB;;;;UAnDnC,qBAAA;;;;;;;0BAOS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyCV,aAAA,OACR,OAAO,OAAO,aAAa,OAAO,2BAC/B,wBAAwB,gBAChC,OAAO,OAAO,aAAa,OAAO"}
+{"version":3,"file":"field.d.ts","names":[],"sources":["../src/field.ts"],"sourcesContent":[],"mappings":";;;;;;AAOA;AAOA;AAMA;AAMY,KAnBA,YAAA,GAmBA,MAAyB,GAnBD,MAmBC;AAQrC;AAWA;AAqBA;;;AAmBoB,KAvER,aAAA,GAAgB,YAuER,EAAA;AAAoB;AAQxC;;;AAWmB,KApFP,oBAAA,GAoFO,QAAA,GAAA,CAAA,CAAA,KAAA,EAAA,OAAA,EAAA,GAAA,OAAA,CAAA;AAAyB;AAO5C;;;AAIsC,KAzF1B,yBAAA,GAyF0B,CAAA,KAAA,EAAA,OAAA,EAAA,GAvFjC,WAuFiC,CAAA,OAAA,CAAA;;AAAuB;AAgD7D;;AACQ,KAlII,iBAAA,GAkIJ,CAAA,KAAA,EAAA,OAAA,EAAA,GAlI4C,OAkI5C,CAAA,MAAA,CAAA;;;;;;;AAEL,cAzHU,qBAyHV,EAzHiC,aAyHjC;;;;;AAAiD;AA0EpC,UA9KC,qBAAA,CA8KiB;EAAA;;;;;;EACuB,SAC9C,aAAA,EAzKe,aAyKf;EAA0B;;AACZ;AAkIzB;;;;;AAEU;;oBAlSU;;;;;;;UAQH,0BAAA;;;;;;0BAMS;;;;mBAKP;;;;;;UAOF,wBAAA;;;;yBAIQ,aAAa,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgDpC,aAAA,OACR,OAAO,OAAO,aAAa,OAAO,2BAC/B,wBAAwB,gBAChC,OAAO,OAAO,aAAa,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0ErB,kBAAA,OACR,OAAO,OAAO,aAAa,OAAO,0BAC/B,6BACR,OAAO;;;;;;;;;;;;;iBAkIY,uBAAA,UACX,2BACR,QAAQ"}

package/dist/field.js

@@ -1,4 +1,8 @@
+import { getLogger } from "@logtape/logtape";
+
 //#region src/field.ts
+const metaLogger = getLogger(["logtape", "meta"]);
+let reportingRedactionFailure = false;
 /**
 * Default field patterns for redaction.  These patterns will match
 * common sensitive fields such as passwords, tokens, and personal
@@ -70,6 +74,133 @@ function redactByField(sink, options = DEFAULT_REDACT_FIELDS) {
 	return wrapped;
 }
 /**
+* 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
+*/
+function redactByFieldAsync(sink, options) {
+	let lastPromise = Promise.resolve();
+	let closed = false;
+	const sinkErrors = [];
+	const wrapped = (record) => {
+		if (closed) return;
+		const work = redactLogRecordAsync(record, options).catch((error) => {
+			reportRedactionFailure(error);
+			return null;
+		});
+		lastPromise = lastPromise.then(async () => {
+			const result = await work;
+			if (result == null) return;
+			try {
+				await sink({
+					...record,
+					message: result.message,
+					properties: result.properties
+				});
+			} catch (error) {
+				sinkErrors.push(error);
+			}
+		});
+	};
+	wrapped[Symbol.asyncDispose] = async () => {
+		closed = true;
+		await lastPromise;
+		let disposeError;
+		try {
+			if (Symbol.asyncDispose in sink) await sink[Symbol.asyncDispose]();
+			else if (Symbol.dispose in sink) sink[Symbol.dispose]();
+		} catch (error) {
+			disposeError = error;
+		}
+		if (sinkErrors.length > 0) {
+			const errors = disposeError == null ? sinkErrors : [...sinkErrors, disposeError];
+			if (errors.length === 1) throw errors[0];
+			throw new AggregateError(errors, "One or more errors occurred while emitting redacted log records.");
+		}
+		if (disposeError != null) throw disposeError;
+	};
+	return wrapped;
+}
+async function redactLogRecordAsync(record, options) {
+	const redactedProperties = await redactPropertiesAsync(record.properties, options);
+	if (typeof record.rawMessage === "string") {
+		const placeholders = extractPlaceholderNames(record.rawMessage);
+		const { redactedIndices, wildcardIndices } = getRedactedPlaceholderIndices(placeholders, options.fieldPatterns);
+		return {
+			message: await redactMessageArrayAsync(record.message, placeholders, redactedIndices, wildcardIndices, redactedProperties, options.action),
+			properties: redactedProperties
+		};
+	}
+	let redactedMessage = record.message;
+	const redactedValues = getRedactedValues(record.properties, redactedProperties);
+	if (redactedValues.size > 0) redactedMessage = redactMessageByValues(record.message, redactedValues);
+	return {
+		message: redactedMessage,
+		properties: redactedProperties
+	};
+}
+function reportRedactionFailure(error) {
+	if (reportingRedactionFailure || typeof metaLogger.warn !== "function") return;
+	try {
+		reportingRedactionFailure = true;
+		metaLogger.warn("Failed to redact a log record; dropping the record to avoid leaking sensitive data: {error}", { error });
+	} catch {} finally {
+		reportingRedactionFailure = false;
+	}
+}
+/**
+* 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
+*/
+async function createHmacPseudonymizer(options) {
+	const subtle = globalThis.crypto?.subtle;
+	if (subtle == null) throw new TypeError("The Web Crypto API is not available.");
+	const hash = getHmacHash(options.key, options.hash);
+	const encoding = options.encoding ?? "base64url";
+	const prefix = options.prefix ?? `hmac-${hash.toLowerCase().replaceAll("-", "")}:`;
+	const key = isCryptoKey(options.key) ? options.key : await subtle.importKey("raw", keyToBytes(options.key), {
+		name: "HMAC",
+		hash
+	}, false, ["sign"]);
+	const encoder = new TextEncoder();
+	return async (value) => {
+		const data = encoder.encode(String(value));
+		const signature = new Uint8Array(await subtle.sign("HMAC", key, data));
+		return prefix + encodeBytes(signature, encoding);
+	};
+}
+/**
 * Redacts properties from an object based on specified field patterns.
 *
 * This function creates a shallow copy of the input object and applies
@@ -89,7 +220,7 @@ function redactProperties(properties, options, visited = /* @__PURE__ */ new Map
 	if (visited.has(properties)) return visited.get(properties);
 	const copy = {};
 	visited.set(properties, copy);
-	for (const field in properties) {
+	for (const field of Object.keys(properties)) {
 		if (shouldFieldRedacted(field, options.fieldPatterns)) {
 			if (typeof options.action === "function") setProperty(copy, field, options.action(properties[field]));
 			continue;
@@ -102,6 +233,36 @@ function redactProperties(properties, options, visited = /* @__PURE__ */ new Map
 	}
 	return copy;
 }
+/**
+* Redacts properties from an object using an asynchronous action.
+* @param properties The properties to redact.
+* @param options The async redaction options.
+* @param visited Map of visited objects to prevent circular reference issues.
+* @returns The redacted properties.
+* @since 2.1.0
+*/
+async function redactPropertiesAsync(properties, options, visited = /* @__PURE__ */ new Map()) {
+	if (visited.has(properties)) return visited.get(properties);
+	const copy = {};
+	visited.set(properties, copy);
+	const fields = [];
+	const values = [];
+	for (const field of Object.keys(properties)) {
+		fields.push(field);
+		if (shouldFieldRedacted(field, options.fieldPatterns)) {
+			values.push(Promise.resolve(options.action(properties[field])));
+			continue;
+		}
+		const value = properties[field];
+		if (Array.isArray(value)) values.push(redactArrayAsync(value, options, visited));
+		else if (typeof value === "object" && value !== null) if (isBuiltInObject(value)) values.push(Promise.resolve(value));
+		else values.push(redactPropertiesAsync(value, options, visited));
+		else values.push(Promise.resolve(value));
+	}
+	const redactedValues = await Promise.all(values);
+	for (let i = 0; i < fields.length; i++) setProperty(copy, fields[i], redactedValues[i]);
+	return copy;
+}
 function setProperty(object, field, value) {
 	if (field === "__proto__") Object.defineProperty(object, field, {
 		value,
@@ -119,14 +280,40 @@ function setProperty(object, field, value) {
 * @returns A new array with redacted values.
 */
 function redactArray(array, options, visited) {
-	return array.map((item) => {
-		if (Array.isArray(item)) return redactArray(item, options, visited);
-		if (typeof item === "object" && item !== null) {
-			if (isBuiltInObject(item)) return item;
-			return redactProperties(item, options, visited);
+	if (visited.has(array)) return visited.get(array);
+	const copy = [];
+	copy.length = array.length;
+	visited.set(array, copy);
+	for (let i = 0; i < array.length; i++) {
+		if (!(i in array)) continue;
+		const item = array[i];
+		if (Array.isArray(item)) copy[i] = redactArray(item, options, visited);
+		else if (typeof item === "object" && item !== null) if (isBuiltInObject(item)) copy[i] = item;
+		else copy[i] = redactProperties(item, options, visited);
+		else copy[i] = item;
+	}
+	return copy;
+}
+async function redactArrayAsync(array, options, visited) {
+	if (visited.has(array)) return visited.get(array);
+	const copy = [];
+	copy.length = array.length;
+	visited.set(array, copy);
+	const itemPromises = [];
+	for (let i = 0; i < array.length; i++) {
+		if (!(i in array)) {
+			itemPromises.push(Promise.resolve(void 0));
+			continue;
 		}
-		return item;
-	});
+		const item = array[i];
+		if (Array.isArray(item)) itemPromises.push(redactArrayAsync(item, options, visited));
+		else if (typeof item === "object" && item !== null) if (isBuiltInObject(item)) itemPromises.push(Promise.resolve(item));
+		else itemPromises.push(redactPropertiesAsync(item, options, visited));
+		else itemPromises.push(Promise.resolve(item));
+	}
+	const redactedItems = await Promise.all(itemPromises);
+	for (let i = 0; i < redactedItems.length; i++) if (i in array) copy[i] = redactedItems[i];
+	return copy;
 }
 /**
 * Checks if a value is a built-in object that should not be recursively
@@ -187,11 +374,51 @@ function extractPlaceholderNames(template) {
 function parsePathSegments(path) {
 	const segments = [];
 	let current = "";
-	for (const char of path) if (char === "." || char === "[") {
-		if (current) segments.push(current);
+	let inBracket = false;
+	let quotedBracketSegment = false;
+	let quote;
+	let escaped = false;
+	const pushCurrent = (trim = false) => {
+		const segment = trim ? current.trimEnd() : current;
+		if (segment) segments.push(segment);
 		current = "";
-	} else if (char === "]" || char === "?") {} else current += char;
-	if (current) segments.push(current);
+	};
+	for (const char of path) {
+		if (quote != null) {
+			if (escaped) {
+				current += char;
+				escaped = false;
+			} else if (char === "\\") escaped = true;
+			else if (char === quote) quote = void 0;
+			else current += char;
+			continue;
+		}
+		if (inBracket && current === "" && /\s/.test(char)) continue;
+		if (inBracket && (char === "\"" || char === "'") && current === "") {
+			quote = char;
+			quotedBracketSegment = true;
+			continue;
+		}
+		if (inBracket && quotedBracketSegment && /\s/.test(char)) continue;
+		if (char === "." && !inBracket) {
+			pushCurrent();
+			continue;
+		}
+		if (char === "[") {
+			pushCurrent();
+			inBracket = true;
+			continue;
+		}
+		if (char === "]") {
+			pushCurrent(!quotedBracketSegment);
+			inBracket = false;
+			quotedBracketSegment = false;
+			continue;
+		}
+		if (char === "?") continue;
+		current += char;
+	}
+	pushCurrent();
 	return segments;
 }
 /**
@@ -246,14 +473,51 @@ function redactMessageArray(message, placeholders, redactedIndices, wildcardIndi
 		else result.push(action(message[i]));
 		else {
 			const placeholderName = placeholders[placeholderIndex];
-			const rootKey = parsePathSegments(placeholderName)[0];
-			if (rootKey in redactedProperties) result.push(redactedProperties[rootKey]);
+			const redactedValue = getPathValue(redactedProperties, placeholderName);
+			if (redactedValue.found) result.push(redactedValue.value);
+			else result.push(message[i]);
+		}
+		placeholderIndex++;
+	}
+	return result;
+}
+async function redactMessageArrayAsync(message, placeholders, redactedIndices, wildcardIndices, redactedProperties, action) {
+	const result = [];
+	const tasks = [];
+	let placeholderIndex = 0;
+	for (let i = 0; i < message.length; i++) if (i % 2 === 0) result.push(message[i]);
+	else {
+		if (wildcardIndices.has(placeholderIndex)) result.push(redactedProperties);
+		else if (redactedIndices.has(placeholderIndex)) {
+			const index = result.length;
+			result.push(void 0);
+			tasks.push(Promise.resolve(action(message[i])).then((redacted) => {
+				result[index] = redacted;
+			}));
+		} else {
+			const placeholderName = placeholders[placeholderIndex];
+			const redactedValue = getPathValue(redactedProperties, placeholderName);
+			if (redactedValue.found) result.push(redactedValue.value);
 			else result.push(message[i]);
 		}
 		placeholderIndex++;
 	}
+	await Promise.all(tasks);
 	return result;
 }
+function getPathValue(properties, path) {
+	const segments = parsePathSegments(path);
+	if (segments.length < 1) return { found: false };
+	let value = properties;
+	for (const segment of segments) {
+		if (typeof value !== "object" && typeof value !== "function" || value == null || !Object.hasOwn(value, segment)) return { found: false };
+		value = value[segment];
+	}
+	return {
+		found: true,
+		value
+	};
+}
 /**
 * Collects redacted value mappings from original to redacted properties.
 * @param original The original properties.
@@ -261,7 +525,7 @@ function redactMessageArray(message, placeholders, redactedIndices, wildcardIndi
 * @param map The map to populate with original -> redacted value pairs.
 */
 function collectRedactedValues(original, redacted, map) {
-	for (const key in original) {
+	for (const key of Object.keys(original)) {
 		const origVal = original[key];
 		const redVal = redacted[key];
 		if (origVal !== redVal) map.set(origVal, redVal);
@@ -297,7 +561,51 @@ function redactMessageByValues(message, redactedValues) {
 	}
 	return result;
 }
+function keyToBytes(key) {
+	if (typeof key === "string") return new TextEncoder().encode(key);
+	if (key instanceof ArrayBuffer) return key;
+	return key;
+}
+function isCryptoKey(key) {
+	return typeof key === "object" && key !== null && Object.prototype.toString.call(key) === "[object CryptoKey]";
+}
+function getHmacHash(key, hash) {
+	if (!isCryptoKey(key)) return hash ?? "SHA-256";
+	if (!key.usages.includes("sign")) throw new TypeError("The HMAC CryptoKey must include the \"sign\" usage.");
+	const keyHash = getCryptoKeyHmacHash(key);
+	if (hash != null && hash !== keyHash) throw new TypeError(`The HMAC CryptoKey uses ${keyHash}, but the "hash" option is ${hash}.`);
+	return keyHash;
+}
+function getCryptoKeyHmacHash(key) {
+	const algorithm = key.algorithm;
+	if (algorithm.name !== "HMAC" || !("hash" in algorithm)) throw new TypeError("The CryptoKey must be an HMAC key.");
+	const hashAlgorithm = algorithm.hash;
+	if (typeof hashAlgorithm !== "object" || hashAlgorithm == null || !("name" in hashAlgorithm) || typeof hashAlgorithm.name !== "string") throw new TypeError("The CryptoKey must specify an HMAC hash algorithm.");
+	const hash = hashAlgorithm.name;
+	switch (hash) {
+		case "SHA-256":
+		case "SHA-384":
+		case "SHA-512": return hash;
+		default: throw new TypeError(`Unsupported HMAC hash algorithm: ${hash}.`);
+	}
+}
+function encodeBytes(bytes, encoding) {
+	switch (encoding) {
+		case "base64url": return encodeBase64Url(bytes);
+		case "hex": return encodeHex(bytes);
+	}
+}
+function encodeBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+function encodeHex(bytes) {
+	let result = "";
+	for (const byte of bytes) result += byte.toString(16).padStart(2, "0");
+	return result;
+}
 
 //#endregion
-export { DEFAULT_REDACT_FIELDS, redactByField };
+export { DEFAULT_REDACT_FIELDS, createHmacPseudonymizer, redactByField, redactByFieldAsync };
 //# sourceMappingURL=field.js.map