feat: redact username in logging paths (#45)

* fix: `getAllExtensionDiscoveryPaths` to prevent external mutation of paths.

The `getAllExtensionDiscoveryPaths` method signature has always been typed as returning a readonly Map, but that's just for compile-time. For run-time it was still returning the actual Map which could be mutated externally.

- Fixed `getAllExtensionDiscoveryPaths` ExtensionData method to return a new Map of the `extensionDiscoveryPaths` Map, to prevent external mutation of the paths.

* feat: redact username in logging output

- Implemented `redactUsername` utility function to sanitise logs by removing the OS username.

- Updated logging statements to use the new redaction utility in:
    - `logDebugInfo` method in `Configuration` class.
    - `getAllExtensionDiscoveryPaths` and `prepareForLogging` methods in `ExtensionData` class.

* refactor: `redactUsername` to be directly implemented into the Logger.

- Moved `redactUsername` function from utils into Logger, simplifying the new method, and adding it's call into the `formatMeta` method after it's transformed the data into a string.

By implementing the `redactUsername` method directly into Logger, we can ensure that any calls to logger with additional meta data, will have the username automatically redacted. So even if more logs are added in future, we don't forget to redact the usernames before Logger gets it.

This also fixes various copilot review comments on the previous implementation because its no longer recursing into objects or arrays, it's just replacing directly on the string immediately before logging to output.

- Updated logging statements to remove the old redaction utility in:
    - `logDebugInfo` method in `Configuration` class.
    - `getAllExtensionDiscoveryPaths` and `prepareForLogging` methods in `ExtensionData` class.

* fix: missing node `os` import.

* feat: add `warn` log level and add `warnOnRedactionFailure` method.

- Introduced new `warn` log level.

    - Added `warn` enum option to the `logLevel` user setting and adjusted all the options descriptions.

    - Implemented `warn` method in `Logger` class to handle warning messages.

    - Updated `logLevels` in the `utils` interface to include `warn`.

    - Added `warn` level in `shouldLog` method in `Logger` and adjusted all the weights.

- Added new `hasWarnedAboutRedactionFailure` property to determine whether the user has already been warned about a redaction failure.

- Added new `warnOnRedactionFailure` method in Logger to warn users when the username couldn't be determined and redaction failed. This method uses the new `hasWarnedAboutRedactionFailure` property to check if it's already been outputted, as this is a once per session warning. It also uses the new `warn` logger method.

* refactor: move `warn` method to below the `error method in Logger.

* fix: wording of the redaction failure warning

* fix: log messages that could have usernames weren't being redacted.

- Added the `redactUsername` method call in the `logMessage` method to redact usernames from the log messages, as they could have them too.

- Moved the method call to redact the meta data from `formatMeta` method into the `logMessage` method, so that the log message and data are both redacted from the same centralised method.

* feat: skip username redaction if previous attempt failed.

- Added a `hasWarnedAboutRedactionFailure` guard conditional at the top of the `redactUsername` method to skip redaction if a previous redact attempt failed.

* refactor: `hasWarnedAboutRedactionFailure` property into a new name.

- Changed the `hasWarnedAboutRedactionFailure` property flag to `skipRedaction` to better describe it's actual job of skipping redaction attempts after failure.

- Changed references to the old `hasWarnedAboutRedactionFailure` property to use the new `skipRedaction` property in the `redactUsername` and `warnOnRedactionFailure` methods.

- Removed the old `hasWarnedAboutRedactionFailure` guard conditional from the `warnOnRedactionFailure` method.

This is because the method will only run when the new `skipRedaction` flag is false thanks to the guard at the top of `redactUsername` method. So the extra guard is now redundant.

- Revised docblocks and code comments for clarity on the redaction behaviour.

Author: yCodeTech

package.json

@@ -85,12 +85,14 @@
 					"enum": [
 						"debug",
 						"info",
+						"warn",
 						"error",
 						"off"
 					],
 					"markdownEnumDescriptions": [
-						"Log debug, info, and errors",
-						"Log info and errors",
+						"Log debug, info, warnings, and errors",
+						"Log info, warnings, and errors",
+						"Log warnings and errors",
 						"Log errors only",
 						"Disable logging"
 					],

src/configuration.ts

@@ -1002,6 +1002,7 @@ export class Configuration {
 				),
 			},
 		};
+
 		logger.debug("Environment:", env);
 
 		// Log the extension's user configuration settings.

src/extensionData.ts

@@ -350,10 +350,12 @@ export class ExtensionData {
 
 	/**
 	 * Get all extension discovery paths.
+	 * Used for logging the paths to the output channel.
 	 *
 	 * @returns {ReadonlyMap<keyof ExtensionPaths, string>} A read-only Map containing all extension discovery paths.
 	 */
 	public getAllExtensionDiscoveryPaths(): ReadonlyMap<keyof ExtensionPaths, string> {
-		return this.extensionDiscoveryPaths;
+		// Return a new Map to prevent external mutation of the internal state.
+		return new Map(this.extensionDiscoveryPaths);
 	}
 }

src/interfaces/utils.ts

@@ -44,6 +44,7 @@ export type LanguageId = string;
 export const logLevels = {
 	debug: "debug",
 	info: "info",
+	warn: "warn",
 	error: "error",
 	off: "off",
 } as const;

src/logger.ts

@@ -1,3 +1,4 @@
+import * as os from "node:os";
 import {OutputChannel, window} from "vscode";
 import {LogLevel, logLevels} from "./interfaces/utils";
 
@@ -26,6 +27,15 @@ class Logger {
 	 */
 	private logLevel: LogLevel = "debug";
 
+	/**
+	 * Whether username redaction should be skipped, because it previously failed.
+	 * Once set, further attempts are not made since the username is unlikely to become
+	 * resolvable later in the same session.
+	 *
+	 * @type {boolean}
+	 */
+	private skipRedaction: boolean = false;
+
 	/***********
 	 * Methods *
 	 ***********/
@@ -121,6 +131,17 @@ class Logger {
 		}
 	}
 
+	/**
+	 * Sends a warning log to the output channel.
+	 *
+	 * @param {string} message The message to be logged.
+	 */
+	public warn(message: string): void {
+		if (this.shouldLog("warn")) {
+			this.logMessage("WARN", message);
+		}
+	}
+
 	/**
 	 * Send an important message to the output channel.
 	 * This is a special log level that is always emitted regardless of the log level,
@@ -150,8 +171,9 @@ class Logger {
 	private shouldLog(requiredLevel: LogLevel): boolean {
 		// Numeric weights used for level comparison.
 		const levelWeight: Record<LogLevel, number> = {
-			debug: 3, // Emits debug, info, and error logs - the most verbose level.
-			info: 2, // Emits info and error logs.
+			debug: 4, // Emits debug, info, warn, and error logs - the most verbose level.
+			info: 3, // Emits info, warn, and error logs.
+			warn: 2, // Emits warn and error logs.
 			error: 1, // Emits error logs only.
 			off: 0, // Disables all logs, except for the special "important" logs that are always emitted.
 		};
@@ -171,13 +193,18 @@ class Logger {
 		if (!this.outputChannel) {
 			this.setupOutputChannel();
 		}
+
+		message = this.redactUsername(message);
+
 		const time = new Date().toLocaleTimeString();
 
 		// Output the log message to the output channel.
 		this.outputChannel.append(`["${level}" - ${time}] ${message}`);
 
 		if (meta) {
-			const data: string = this.formatMeta(message, meta);
+			let data: string = this.formatMeta(message, meta);
+
+			data = this.redactUsername(data);
 
 			// Output the meta data to the output channel with a leading space.
 			this.outputChannel.appendLine(` ${data}`);
@@ -232,6 +259,55 @@ class Logger {
 
 		return value;
 	}
+
+	/**
+	 * Redact the OS username from a string, replacing it with `<redacted>`,
+	 * to avoid leaking it into the logs that could be shared.
+	 *
+	 * @param {string} text The text to redact.
+	 * @returns {string} If redaction was possible, returns the redacted text,
+	 * otherwise the original text.
+	 */
+	private redactUsername(text: string): string {
+		// If redaction previously failed, skip attempting it again and return the original text.
+		if (this.skipRedaction) {
+			return text;
+		}
+
+		let username: string;
+
+		// Get the current OS username using Node's userInfo() method which is
+		// cross-platform compatible. It can throw an error in sandboxed/remote environments where
+		// the username can't be determined. So catch any errors and return the original text
+		// if we can't get the username.
+		try {
+			username = os.userInfo().username;
+		} catch {
+			this.warnOnRedactionFailure();
+			return text;
+		}
+
+		// If the username is empty, return the original text.
+		if (!username) {
+			this.warnOnRedactionFailure();
+			return text;
+		}
+
+		// Escape special characters in the username.
+		const escapedUsername = username.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		// Replace any occurrence of the username in the text with "<redacted>", case-insensitively, and return it.
+		return text.replace(new RegExp(escapedUsername, "gi"), "<redacted>");
+	}
+
+	/**
+	 * Warn once per session that debug logs may not have the username redacted,
+	 * so users don't unknowingly share it in a bug report.
+	 */
+	private warnOnRedactionFailure(): void {
+		// Set the flag to skip further redaction attempts before warning to avoid recursion.
+		this.skipRedaction = true;
+		this.warn("Could not determine OS username; logs won't be redacted. Manually redact any sensitive information before sharing logs.");
+	}
 }
 
 export const logger = new Logger();