mcp-server-framework 1.0.0

package/build/logger/mcp-logger.js

@@ -0,0 +1,294 @@
+/**
+ * MCP Notification Logger Module
+ *
+ * Provides structured logging via MCP notifications/message protocol.
+ * This allows MCP clients to receive and display server-side logs.
+ *
+ * Per MCP Spec, logging levels follow RFC 5424 (syslog):
+ * - emergency: System is unusable
+ * - alert: Action must be taken immediately
+ * - critical: Critical conditions
+ * - error: Error conditions
+ * - warning: Warning conditions
+ * - notice: Normal but significant condition
+ * - info: Informational messages
+ * - debug: Debug-level messages
+ *
+ * @module logger/mcp-logger
+ */
+import { LOG_LEVEL_TO_MCP, MCP_LEVEL_ORDER } from "./core/constants.js";
+import { secretScrubber as sharedScrubber } from "./scrubbing/secret-scrubber.js";
+import { InjectionGuard } from "./scrubbing/injection-guard.js";
+import { logger as baseLogger } from "./logger.js";
+import { LOGGER_COMPONENTS } from "./core/constants.js";
+// Create a child logger for this module
+const localLogger = baseLogger.child({
+    component: LOGGER_COMPONENTS.MCP_LOGGER,
+});
+// ============================================================
+// Constants
+// ============================================================
+// Use centralized constants from core/constants.ts
+const LOG_LEVEL_MAP = LOG_LEVEL_TO_MCP;
+// ============================================================
+// McpNotificationLogger Class
+// ============================================================
+/**
+ * MCP Notification Logger
+ *
+ * Sends structured log messages to MCP clients via the notifications/message protocol.
+ * Clients that support the logging capability will receive and display these messages.
+ *
+ * Features:
+ * - Multi-server support for multi-session scenarios
+ * - Level filtering with configurable minimum level
+ * - Secret scrubbing for security
+ * - Context-aware logger creation for tool handlers
+ *
+ * @example
+ * ```typescript
+ * // Set up with MCP server
+ * mcpLogger.addServer(mcpServer);
+ *
+ * // Log messages (sent to all connected clients)
+ * await mcpLogger.info('Processing request...');
+ * await mcpLogger.warn('Resource limit approaching', { current: 80, max: 100 });
+ * await mcpLogger.error('Failed to connect', { error: 'Connection refused' });
+ * ```
+ */
+export class McpNotificationLogger {
+    // ============================================================
+    // Instance Properties
+    // ============================================================
+    /** Set of registered notification handlers */
+    handlers = new Set();
+    /** Whether logging is enabled */
+    enabled;
+    /** Minimum log level to send */
+    minLevel;
+    /** Use shared secret scrubber instance for consistency */
+    secretScrubber = sharedScrubber;
+    /** Injection guard for CWE-117 protection (consistent with main logger pipeline) */
+    injectionGuard = new InjectionGuard();
+    // ============================================================
+    // Constructor
+    // ============================================================
+    /**
+     * Create a new McpNotificationLogger.
+     *
+     * @param config - Optional configuration
+     */
+    constructor(config = {}) {
+        this.enabled = config.enabled ?? true;
+        this.minLevel = config.minLevel ?? "debug";
+    }
+    // ============================================================
+    // Server Management
+    // ============================================================
+    /**
+     * Register a notification handler for receiving log notifications.
+     * Multiple handlers can be registered for multi-session scenarios.
+     *
+     * @param handler - The notification handler to register
+     */
+    addHandler(handler) {
+        this.handlers.add(handler);
+        localLogger.debug("Log notification handler registered", {
+            totalHandlers: this.handlers.size,
+        });
+    }
+    /**
+     * Unregister a notification handler.
+     *
+     * @param handler - The notification handler to remove
+     */
+    removeHandler(handler) {
+        this.handlers.delete(handler);
+        localLogger.trace("Log notification handler unregistered", {
+            remainingHandlers: this.handlers.size,
+        });
+    }
+    /**
+     * Clear all registered handlers.
+     */
+    clearHandlers() {
+        this.handlers.clear();
+        localLogger.trace("All log notification handlers cleared");
+    }
+    /**
+     * Get the number of registered handlers.
+     */
+    getHandlerCount() {
+        return this.handlers.size;
+    }
+    // ============================================================
+    // Configuration
+    // ============================================================
+    /**
+     * Enable or disable MCP logging.
+     * When disabled, log methods become no-ops but still return resolved promises.
+     *
+     * @param enabled - Whether to enable logging
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    /**
+     * Check if logging is enabled.
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Set the minimum log level.
+     * Messages below this level will not be sent.
+     *
+     * @param level - The minimum log level
+     */
+    setMinLevel(level) {
+        this.minLevel = level;
+    }
+    /**
+     * Get the current minimum log level.
+     */
+    getMinLevel() {
+        return this.minLevel;
+    }
+    /**
+     * Check if logging is currently available (enabled and has servers).
+     */
+    isAvailable() {
+        return this.enabled && this.handlers.size > 0;
+    }
+    // ============================================================
+    // Core Logging Methods
+    // ============================================================
+    /**
+     * Send a log message to all connected MCP clients.
+     *
+     * @param level - The MCP log level
+     * @param message - The log message
+     * @param data - Optional structured data to include
+     * @returns Promise that resolves when all sends complete
+     */
+    async log(level, message, data) {
+        // Early return if not available or below minimum level
+        if (!this.enabled || this.handlers.size === 0 || !this.shouldLog(level)) {
+            return;
+        }
+        // Format message with optional data, sanitize, and scrub secrets
+        const formattedMessage = this.formatMessage(message, data);
+        const sanitized = this.injectionGuard.sanitize(formattedMessage);
+        const safeMessage = this.secretScrubber.scrub(sanitized);
+        // Send to all registered handlers in parallel
+        const sendPromises = Array.from(this.handlers).map((handler) => this.sendToHandler(handler, level, safeMessage));
+        await Promise.all(sendPromises);
+    }
+    // ============================================================
+    // Convenience Methods (RFC 5424 Levels)
+    // ============================================================
+    /** Log a debug message */
+    async debug(message, data) {
+        return this.log("debug", message, data);
+    }
+    /** Log an info message */
+    async info(message, data) {
+        return this.log("info", message, data);
+    }
+    /** Log a notice message */
+    async notice(message, data) {
+        return this.log("notice", message, data);
+    }
+    /** Log a warning message */
+    async warn(message, data) {
+        return this.log("warning", message, data);
+    }
+    /** Log a warning message (alias for warn) */
+    async warning(message, data) {
+        return this.log("warning", message, data);
+    }
+    /** Log an error message */
+    async error(message, data) {
+        return this.log("error", message, data);
+    }
+    /** Log a critical message */
+    async critical(message, data) {
+        return this.log("critical", message, data);
+    }
+    /** Log an alert message */
+    async alert(message, data) {
+        return this.log("alert", message, data);
+    }
+    /** Log an emergency message */
+    async emergency(message, data) {
+        return this.log("emergency", message, data);
+    }
+    // ============================================================
+    // Context Logger Factory
+    // ============================================================
+    /**
+     * Create a context-aware logger function for use in tool handlers.
+     * Returns a function that can be passed to LogContext.sendMcpLog.
+     *
+     * @param handler - The notification handler for this context
+     * @returns A function compatible with LogContext.sendMcpLog
+     *
+     * @example
+     * ```typescript
+     * const sendMcpLog = mcpLogger.createContextLogger(handler);
+     * logger.runWithContext({ sendMcpLog }, () => {
+     *   logger.info('This will also be sent to MCP client');
+     * });
+     * ```
+     */
+    createContextLogger(handler) {
+        return (level, message) => {
+            const mcpLevel = LOG_LEVEL_MAP[level];
+            const sanitized = this.injectionGuard.sanitize(message);
+            const safeMessage = this.secretScrubber.scrub(sanitized);
+            handler.sendLogNotification(mcpLevel, safeMessage).catch(() => {
+                // Silently ignore errors (client may have disconnected)
+            });
+        };
+    }
+    // ============================================================
+    // Private Helper Methods
+    // ============================================================
+    /**
+     * Check if a log level should be logged based on minimum level.
+     */
+    shouldLog(level) {
+        const minIndex = MCP_LEVEL_ORDER.indexOf(this.minLevel);
+        const currentIndex = MCP_LEVEL_ORDER.indexOf(level);
+        return currentIndex >= minIndex;
+    }
+    /**
+     * Format message with optional data.
+     */
+    formatMessage(message, data) {
+        if (!data || Object.keys(data).length === 0) {
+            return message;
+        }
+        return `${message} ${JSON.stringify(data)}`;
+    }
+    /**
+     * Send a log message to a specific handler.
+     */
+    async sendToHandler(handler, level, message) {
+        try {
+            await handler.sendLogNotification(level, message);
+        }
+        catch {
+            // Silently ignore errors (client may have disconnected)
+        }
+    }
+}
+// ============================================================
+// Singleton Export
+// ============================================================
+/**
+ * Singleton instance of the MCP Notification Logger.
+ * Use this for sending log messages to MCP clients.
+ */
+export const mcpLogger = new McpNotificationLogger();
+//# sourceMappingURL=mcp-logger.js.map

package/build/logger/mcp-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-logger.js","sourceRoot":"","sources":["../../src/logger/mcp-logger.ts"],"names":[],"mappings":"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"}

package/build/logger/scrubbing/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Scrubbing Module
+ *
+ * Security utilities for log sanitization.
+ * Provides secret redaction and injection prevention.
+ *
+ * Note: Security constants (SENSITIVE_KEYS, REDACTED_VALUE, etc.) should be
+ * imported directly from '../core/constants.js' or '../core/index.js'
+ *
+ * @module logger/scrubbing
+ */
+export { SecretScrubber, secretScrubber } from "./secret-scrubber.js";
+export { InjectionGuard, injectionGuard, sanitizeForLogging } from "./injection-guard.js";
+//# sourceMappingURL=index.d.ts.map

package/build/logger/scrubbing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logger/scrubbing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/build/logger/scrubbing/index.js

@@ -0,0 +1,16 @@
+/**
+ * Scrubbing Module
+ *
+ * Security utilities for log sanitization.
+ * Provides secret redaction and injection prevention.
+ *
+ * Note: Security constants (SENSITIVE_KEYS, REDACTED_VALUE, etc.) should be
+ * imported directly from '../core/constants.js' or '../core/index.js'
+ *
+ * @module logger/scrubbing
+ */
+// Secret Scrubber
+export { SecretScrubber, secretScrubber } from "./secret-scrubber.js";
+// Injection Guard
+export { InjectionGuard, injectionGuard, sanitizeForLogging } from "./injection-guard.js";
+//# sourceMappingURL=index.js.map

package/build/logger/scrubbing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/logger/scrubbing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtE,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/build/logger/scrubbing/injection-guard.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Injection Guard Module
+ *
+ * Provides protection against log injection attacks (CWE-117).
+ * Prevents attackers from forging log entries by injecting newlines or control characters.
+ *
+ * @see https://cwe.mitre.org/data/definitions/117.html
+ * @module logger/scrubbing/injection-guard
+ */
+/**
+ * Injection Guard class for preventing log injection attacks.
+ *
+ * Provides:
+ * - Newline escaping (CWE-117 mitigation)
+ * - Control character escaping
+ * - ANSI escape sequence stripping
+ *
+ * @example
+ * ```typescript
+ * const guard = new InjectionGuard();
+ * const safe = guard.sanitize('User: admin\nLevel: root'); // "User: admin\\nLevel: root"
+ * ```
+ */
+export declare class InjectionGuard {
+    private stripAnsi;
+    /**
+     * Create a new InjectionGuard.
+     * @param options - Configuration options
+     * @param options.stripAnsi - Whether to strip ANSI escape sequences (default: true)
+     */
+    constructor(options?: {
+        stripAnsi?: boolean;
+    });
+    /**
+     * Sanitize text to prevent log injection.
+     * Replaces newlines and control characters with escaped versions.
+     *
+     * @param text - The text to sanitize
+     * @returns Sanitized text safe for logging
+     */
+    sanitize(text: string): string;
+    /**
+     * Check if text contains potential injection characters.
+     *
+     * @param text - The text to check
+     * @returns true if the text contains injection characters
+     */
+    containsInjectionChars(text: string): boolean;
+    /**
+     * Check if text contains ANSI escape sequences.
+     *
+     * @param text - The text to check
+     * @returns true if the text contains ANSI sequences
+     */
+    containsAnsiSequences(text: string): boolean;
+}
+/**
+ * Default injection guard instance.
+ */
+export declare const injectionGuard: InjectionGuard;
+/**
+ * Convenience function to sanitize text for logging.
+ * Uses the default injection guard instance.
+ *
+ * @param text - The text to sanitize
+ * @returns Sanitized text
+ */
+export declare function sanitizeForLogging(text: string): string;
+//# sourceMappingURL=injection-guard.d.ts.map

package/build/logger/scrubbing/injection-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection-guard.d.ts","sourceRoot":"","sources":["../../../src/logger/scrubbing/injection-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAU;IAE3B;;;;OAIG;gBACS,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO;IAIjD;;;;;;OAMG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAkBrC;;;;;OAKG;IACI,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpD;;;;;OAKG;IACI,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGpD;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/build/logger/scrubbing/injection-guard.js

@@ -0,0 +1,102 @@
+/**
+ * Injection Guard Module
+ *
+ * Provides protection against log injection attacks (CWE-117).
+ * Prevents attackers from forging log entries by injecting newlines or control characters.
+ *
+ * @see https://cwe.mitre.org/data/definitions/117.html
+ * @module logger/scrubbing/injection-guard
+ */
+import { CONTROL_CHAR_REPLACEMENTS, CONTROL_CHAR_PATTERN, ANSI_ESCAPE_PATTERN } from "../core/constants.js";
+/**
+ * Pre-compiled regex for control characters (with /g flag for replacement).
+ */
+const CONTROL_CHAR_REGEX = new RegExp(CONTROL_CHAR_PATTERN, "g");
+/**
+ * Pre-compiled regex for testing control characters (without /g flag).
+ */
+const CONTROL_CHAR_TEST_REGEX = new RegExp(CONTROL_CHAR_PATTERN);
+/**
+ * Pre-compiled regex for ANSI escape sequences (with /g flag for replacement).
+ */
+const ANSI_ESCAPE_REGEX = new RegExp(ANSI_ESCAPE_PATTERN, "g");
+/**
+ * Pre-compiled regex for testing ANSI sequences (without /g flag).
+ */
+const ANSI_ESCAPE_TEST_REGEX = new RegExp(ANSI_ESCAPE_PATTERN);
+/**
+ * Injection Guard class for preventing log injection attacks.
+ *
+ * Provides:
+ * - Newline escaping (CWE-117 mitigation)
+ * - Control character escaping
+ * - ANSI escape sequence stripping
+ *
+ * @example
+ * ```typescript
+ * const guard = new InjectionGuard();
+ * const safe = guard.sanitize('User: admin\nLevel: root'); // "User: admin\\nLevel: root"
+ * ```
+ */
+export class InjectionGuard {
+    stripAnsi;
+    /**
+     * Create a new InjectionGuard.
+     * @param options - Configuration options
+     * @param options.stripAnsi - Whether to strip ANSI escape sequences (default: true)
+     */
+    constructor(options = {}) {
+        this.stripAnsi = options.stripAnsi ?? true;
+    }
+    /**
+     * Sanitize text to prevent log injection.
+     * Replaces newlines and control characters with escaped versions.
+     *
+     * @param text - The text to sanitize
+     * @returns Sanitized text safe for logging
+     */
+    sanitize(text) {
+        let result = text;
+        // 1. Strip ANSI escape sequences if enabled
+        if (this.stripAnsi) {
+            result = result.replace(ANSI_ESCAPE_REGEX, "");
+        }
+        // 2. Escape control characters using centralized mapping.
+        //    Unknown control chars get a generic \\xHH replacement.
+        result = result.replace(CONTROL_CHAR_REGEX, (char) => CONTROL_CHAR_REPLACEMENTS[char] ?? `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`);
+        return result;
+    }
+    /**
+     * Check if text contains potential injection characters.
+     *
+     * @param text - The text to check
+     * @returns true if the text contains injection characters
+     */
+    containsInjectionChars(text) {
+        return CONTROL_CHAR_TEST_REGEX.test(text);
+    }
+    /**
+     * Check if text contains ANSI escape sequences.
+     *
+     * @param text - The text to check
+     * @returns true if the text contains ANSI sequences
+     */
+    containsAnsiSequences(text) {
+        return ANSI_ESCAPE_TEST_REGEX.test(text);
+    }
+}
+/**
+ * Default injection guard instance.
+ */
+export const injectionGuard = new InjectionGuard();
+/**
+ * Convenience function to sanitize text for logging.
+ * Uses the default injection guard instance.
+ *
+ * @param text - The text to sanitize
+ * @returns Sanitized text
+ */
+export function sanitizeForLogging(text) {
+    return injectionGuard.sanitize(text);
+}
+//# sourceMappingURL=injection-guard.js.map

package/build/logger/scrubbing/injection-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection-guard.js","sourceRoot":"","sources":["../../../src/logger/scrubbing/injection-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE5G;;GAEG;AACH,MAAM,kBAAkB,GAAG,IAAI,MAAM,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,uBAAuB,GAAG,IAAI,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,iBAAiB,GAAG,IAAI,MAAM,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,sBAAsB,GAAG,IAAI,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IACjB,SAAS,CAAU;IAE3B;;;;OAIG;IACH,YAAY,UAAmC,EAAE;QAC/C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC7C,CAAC;IAED;;;;;;OAMG;IACI,QAAQ,CAAC,IAAY;QAC1B,IAAI,MAAM,GAAG,IAAI,CAAC;QAElB,4CAA4C;QAC5C,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,0DAA0D;QAC1D,4DAA4D;QAC5D,MAAM,GAAG,MAAM,CAAC,OAAO,CACrB,kBAAkB,EAClB,CAAC,IAAI,EAAE,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACtG,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACI,sBAAsB,CAAC,IAAY;QACxC,OAAO,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACI,qBAAqB,CAAC,IAAY;QACvC,OAAO,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/build/logger/scrubbing/secret-scrubber.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Secret Scrubber Module
+ *
+ * Provides utilities for detecting and redacting sensitive information from logs.
+ * Handles JWTs, Bearer tokens, and key-value pairs with sensitive keys.
+ *
+ * @module logger/scrubbing/secret-scrubber
+ */
+/**
+ * Secret Scrubber class for detecting and redacting sensitive information.
+ *
+ * Usage:
+ * - Create a scrubber: `const scrubber = new SecretScrubber();`
+ * - Scrub a string: `scrubber.scrub('token=secret123')` returns `'token=**********'`
+ * - Scrub an object: `scrubber.scrubObject({ password: 'secret' })` returns `{ password: '**********' }`
+ */
+export declare class SecretScrubber {
+    /**
+     * Additional sensitive keys provided at construction time.
+     * These bypass the shared blocklist since they are explicitly
+     * provided by the consumer as known-sensitive patterns.
+     */
+    private readonly additionalKeys;
+    /**
+     * Create a new SecretScrubber.
+     * @param additionalKeys - Additional keys to consider sensitive
+     */
+    constructor(additionalKeys?: string[]);
+    /**
+     * Scrub secrets from a text string.
+     *
+     * Handles:
+     * - JWTs (eyJ...)
+     * - Bearer tokens
+     * - Key-value pairs with sensitive keys
+     *
+     * @param text - The text to scrub
+     * @returns The scrubbed text
+     */
+    scrub(text: string): string;
+    /**
+     * Recursively scrub sensitive keys from an object.
+     *
+     * Also scrubs string values that may contain embedded secrets
+     * (e.g., "password=secret123" patterns).
+     *
+     * @param obj - The object to scrub
+     * @returns A new object with sensitive values redacted
+     */
+    scrubObject(obj: unknown): unknown;
+    /**
+     * Internal recursive scrub with circular reference protection.
+     */
+    private scrubObjectRecursive;
+    /**
+     * Check if a key is sensitive.
+     *
+     * Delegates to the shared utility for base sensitive keys (including
+     * blocklist logic). Additional keys provided at construction are checked
+     * separately — they bypass the blocklist since they are explicitly
+     * declared as sensitive by the consumer.
+     *
+     * @param key - The key to check
+     * @returns true if the key matches a sensitive pattern
+     */
+    isSensitiveKey(key: string): boolean;
+}
+/**
+ * Default secret scrubber instance.
+ */
+export declare const secretScrubber: SecretScrubber;
+//# sourceMappingURL=secret-scrubber.d.ts.map

package/build/logger/scrubbing/secret-scrubber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-scrubber.d.ts","sourceRoot":"","sources":["../../../src/logger/scrubbing/secret-scrubber.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA4CH;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IAEnD;;;OAGG;gBACS,cAAc,GAAE,MAAM,EAAO;IAIzC;;;;;;;;;;OAUG;IACI,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAoClC;;;;;;;;OAQG;IACI,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IAIzC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAyC5B;;;;;;;;;;OAUG;IACI,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAS5C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC"}