mcp-server-framework 1.0.0

package/build/logger/core/constants.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Logger Core Constants Module
+ *
+ * Centralized constants for the logging system.
+ * All logger-related constants should be defined here for consistency
+ * and to avoid magic values scattered throughout the codebase.
+ *
+ * @module logger/core/constants
+ */
+import type { LogLevel, McpLogLevel } from "./types.js";
+/**
+ * Numeric values for log levels to determine if a message should be logged.
+ * Higher values = more severe.
+ *
+ * @example
+ * ```typescript
+ * if (LOG_LEVELS[level] >= LOG_LEVELS[minLevel]) {
+ *   // Log the message
+ * }
+ * ```
+ */
+export declare const LOG_LEVELS: Readonly<Record<LogLevel, number>>;
+/**
+ * Log severity levels for ECS/structured logging.
+ * Based on RFC 5424 syslog severity (inverted: 0 = emergency, 7 = debug).
+ */
+export declare const LOG_SEVERITY: Readonly<Record<LogLevel, number>>;
+/**
+ * Maps internal log levels to MCP logging levels (RFC 5424).
+ * MCP uses syslog-style levels which are more granular.
+ */
+export declare const LOG_LEVEL_TO_MCP: Readonly<Record<LogLevel, McpLogLevel>>;
+/**
+ * Default log level when not specified in configuration.
+ */
+export declare const DEFAULT_LOG_LEVEL: LogLevel;
+/**
+ * Default log format when not specified in configuration.
+ */
+export declare const DEFAULT_LOG_FORMAT: "json" | "text";
+/**
+ * Default component name for loggers without explicit component.
+ */
+/**
+ * Default service name for structured logs.
+ */
+export declare const DEFAULT_SERVICE_NAME = "mcp-server";
+/**
+ * Maximum length for truncated session/request IDs in text logs.
+ */
+export declare const ID_DISPLAY_LENGTH = 8;
+/**
+ * Padding for log level alignment in text format.
+ */
+export declare const LEVEL_PAD_LENGTH = 5;
+/**
+ * File extension for log files.
+ */
+export declare const LOG_FILE_EXTENSION = ".log";
+/**
+ * Default components for file logging.
+ * Streams will be created for each component.
+ */
+export declare const DEFAULT_LOG_COMPONENTS: readonly ["server", "api", "transport", "tools"];
+/**
+ * Logger component names for the logging system.
+ * Used for consistent log categorization across the logger module.
+ */
+export declare const LOGGER_COMPONENTS: {
+    /** MCP protocol logger */
+    readonly MCP_LOGGER: "McpLogger";
+    /** File writer component */
+    readonly FILE_WRITER: "FileWriter";
+    /** Console writer component */
+    readonly CONSOLE_WRITER: "ConsoleWriter";
+};
+/**
+ * List of keys that are considered sensitive and should be redacted from logs.
+ * Re-exported from the shared utility for backwards compatibility.
+ *
+ * @see {@link ../../utils/sensitive-keys.ts} — canonical source
+ */
+export { SENSITIVE_KEYS, SENSITIVE_KEY_BLOCKLIST } from "../../utils/sensitive-keys.js";
+/**
+ * Type representing a sensitive key.
+ */
+export type SensitiveKey = string;
+/**
+ * The string used to replace redacted values.
+ */
+export declare const REDACTED_VALUE = "**********";
+/**
+ * JWT prefix pattern for detection.
+ */
+export declare const JWT_PREFIX = "eyJ";
+/**
+ * Control characters that could be used for log injection (CWE-117).
+ * These are replaced to ensure one log entry = one line.
+ *
+ * Note: Existing backslashes are intentionally NOT escaped before replacement.
+ * Escaping backslashes first would double-escape already-escaped sequences
+ * (e.g. a literal `\n` in source text would become `\\n`). The CWE-117
+ * threat model focuses on preventing attackers from forging new log entries
+ * via injected newlines — visual ambiguity between a literal backslash-n
+ * and an escaped newline is an acceptable trade-off.
+ */
+export declare const CONTROL_CHAR_REPLACEMENTS: Readonly<Record<string, string>>;
+/**
+ * Regex pattern string for all C0 control characters (U+0000–U+001F)
+ * except those commonly allowed in text (\t is replaced but kept readable).
+ */
+export declare const CONTROL_CHAR_PATTERN = "[\\x00-\\x1F\\x7F]";
+/**
+ * Regex pattern string for ANSI escape sequences.
+ */
+export declare const ANSI_ESCAPE_PATTERN = "\\x1B\\[[?>=<:0-9;]*[a-zA-Z]";
+/**
+ * Maximum depth for context merging to prevent infinite loops.
+ */
+export declare const MAX_CONTEXT_DEPTH = 10;
+/**
+ * Separator used for hierarchical component names.
+ */
+export declare const COMPONENT_SEPARATOR = ".";
+/**
+ * Ordered list of MCP log levels (RFC 5424) for severity comparison.
+ * Lower index = lower severity. Used for level filtering.
+ */
+export declare const MCP_LEVEL_ORDER: readonly McpLogLevel[];
+/**
+ * Maximum number of cached child loggers.
+ * Prevents memory leaks from excessive child logger creation.
+ */
+export declare const MAX_CHILD_LOGGER_CACHE_SIZE = 100;
+/**
+ * Maximum message length before truncation in non-debug modes.
+ */
+export declare const MAX_MESSAGE_LENGTH = 10000;
+/**
+ * Truncation suffix for long messages.
+ */
+export declare const TRUNCATION_SUFFIX = "... [truncated]";
+//# sourceMappingURL=constants.d.ts.map

package/build/logger/core/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/logger/core/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAMxD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAMhD,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAMlD,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,CAM3D,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAiB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,GAAG,MAAe,CAAC;AAE1D;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAMjD;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;GAEG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;GAEG;AACH,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,sBAAsB,kDAAmD,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B,0BAA0B;;IAE1B,4BAA4B;;IAE5B,+BAA+B;;CAEvB,CAAC;AAMX;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;GAEG;AACH,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,UAAU,QAAQ,CAAC;AAMhC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiB7D,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,mBAAmB,iCAAiC,CAAC;AAMlE;;GAEG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAMvC;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,WAAW,EASxC,CAAC;AAMX;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC"}

package/build/logger/core/constants.js

@@ -0,0 +1,206 @@
+/**
+ * Logger Core Constants Module
+ *
+ * Centralized constants for the logging system.
+ * All logger-related constants should be defined here for consistency
+ * and to avoid magic values scattered throughout the codebase.
+ *
+ * @module logger/core/constants
+ */
+// ============================================================================
+// Log Level Configuration
+// ============================================================================
+/**
+ * Numeric values for log levels to determine if a message should be logged.
+ * Higher values = more severe.
+ *
+ * @example
+ * ```typescript
+ * if (LOG_LEVELS[level] >= LOG_LEVELS[minLevel]) {
+ *   // Log the message
+ * }
+ * ```
+ */
+export const LOG_LEVELS = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+};
+/**
+ * Log severity levels for ECS/structured logging.
+ * Based on RFC 5424 syslog severity (inverted: 0 = emergency, 7 = debug).
+ */
+export const LOG_SEVERITY = {
+    trace: 7, // Debug
+    debug: 7, // Debug
+    info: 6, // Informational
+    warn: 4, // Warning
+    error: 3, // Error
+};
+/**
+ * Maps internal log levels to MCP logging levels (RFC 5424).
+ * MCP uses syslog-style levels which are more granular.
+ */
+export const LOG_LEVEL_TO_MCP = {
+    trace: "debug",
+    debug: "debug",
+    info: "info",
+    warn: "warning",
+    error: "error",
+};
+// ============================================================================
+// Default Configuration
+// ============================================================================
+/**
+ * Default log level when not specified in configuration.
+ */
+export const DEFAULT_LOG_LEVEL = "info";
+/**
+ * Default log format when not specified in configuration.
+ */
+export const DEFAULT_LOG_FORMAT = "text";
+/**
+ * Default component name for loggers without explicit component.
+ */
+/**
+ * Default service name for structured logs.
+ */
+export const DEFAULT_SERVICE_NAME = "mcp-server";
+// ============================================================================
+// Formatting Constants
+// ============================================================================
+/**
+ * Maximum length for truncated session/request IDs in text logs.
+ */
+export const ID_DISPLAY_LENGTH = 8;
+/**
+ * Padding for log level alignment in text format.
+ */
+export const LEVEL_PAD_LENGTH = 5;
+/**
+ * File extension for log files.
+ */
+export const LOG_FILE_EXTENSION = ".log";
+/**
+ * Default components for file logging.
+ * Streams will be created for each component.
+ */
+export const DEFAULT_LOG_COMPONENTS = ["server", "api", "transport", "tools"];
+/**
+ * Logger component names for the logging system.
+ * Used for consistent log categorization across the logger module.
+ */
+export const LOGGER_COMPONENTS = {
+    /** MCP protocol logger */
+    MCP_LOGGER: "McpLogger",
+    /** File writer component */
+    FILE_WRITER: "FileWriter",
+    /** Console writer component */
+    CONSOLE_WRITER: "ConsoleWriter",
+};
+// ============================================================================
+// Security Constants (Secret Scrubbing)
+// ============================================================================
+/**
+ * List of keys that are considered sensitive and should be redacted from logs.
+ * Re-exported from the shared utility for backwards compatibility.
+ *
+ * @see {@link ../../utils/sensitive-keys.ts} — canonical source
+ */
+export { SENSITIVE_KEYS, SENSITIVE_KEY_BLOCKLIST } from "../../utils/sensitive-keys.js";
+/**
+ * The string used to replace redacted values.
+ */
+export const REDACTED_VALUE = "**********";
+/**
+ * JWT prefix pattern for detection.
+ */
+export const JWT_PREFIX = "eyJ";
+// ============================================================================
+// Security Constants (Injection Prevention - CWE-117)
+// ============================================================================
+/**
+ * Control characters that could be used for log injection (CWE-117).
+ * These are replaced to ensure one log entry = one line.
+ *
+ * Note: Existing backslashes are intentionally NOT escaped before replacement.
+ * Escaping backslashes first would double-escape already-escaped sequences
+ * (e.g. a literal `\n` in source text would become `\\n`). The CWE-117
+ * threat model focuses on preventing attackers from forging new log entries
+ * via injected newlines — visual ambiguity between a literal backslash-n
+ * and an escaped newline is an acceptable trade-off.
+ */
+export const CONTROL_CHAR_REPLACEMENTS = {
+    "\n": "\\n", // Newline
+    "\r": "\\r", // Carriage return
+    "\t": "\\t", // Tab
+    "\0": "\\0", // Null
+    "\x07": "\\a", // Bell (BEL) — terminal DoS vector
+    "\x08": "\\b", // Backspace — can erase log entries in terminals
+    "\x0B": "\\v", // Vertical tab
+    "\x0C": "\\f", // Form feed
+    "\x0E": "\\x0E", // Shift Out — character set switching
+    "\x0F": "\\x0F", // Shift In — character set switching
+    "\x1A": "\\x1A", // Substitute (SUB) — terminates Windows command output
+    "\x1B": "\\e", // Escape
+    "\x1C": "\\x1C", // File Separator
+    "\x1D": "\\x1D", // Group Separator
+    "\x1E": "\\x1E", // Record Separator
+    "\x1F": "\\x1F", // Unit Separator
+};
+/**
+ * Regex pattern string for all C0 control characters (U+0000–U+001F)
+ * except those commonly allowed in text (\t is replaced but kept readable).
+ */
+export const CONTROL_CHAR_PATTERN = "[\\x00-\\x1F\\x7F]";
+/**
+ * Regex pattern string for ANSI escape sequences.
+ */
+export const ANSI_ESCAPE_PATTERN = "\\x1B\\[[?>=<:0-9;]*[a-zA-Z]";
+// ============================================================================
+// Context Constants
+// ============================================================================
+/**
+ * Maximum depth for context merging to prevent infinite loops.
+ */
+export const MAX_CONTEXT_DEPTH = 10;
+/**
+ * Separator used for hierarchical component names.
+ */
+export const COMPONENT_SEPARATOR = ".";
+// ============================================================================
+// MCP Level Configuration
+// ============================================================================
+/**
+ * Ordered list of MCP log levels (RFC 5424) for severity comparison.
+ * Lower index = lower severity. Used for level filtering.
+ */
+export const MCP_LEVEL_ORDER = [
+    "debug",
+    "info",
+    "notice",
+    "warning",
+    "error",
+    "critical",
+    "alert",
+    "emergency",
+];
+// ============================================================================
+// Performance Constants
+// ============================================================================
+/**
+ * Maximum number of cached child loggers.
+ * Prevents memory leaks from excessive child logger creation.
+ */
+export const MAX_CHILD_LOGGER_CACHE_SIZE = 100;
+/**
+ * Maximum message length before truncation in non-debug modes.
+ */
+export const MAX_MESSAGE_LENGTH = 10_000;
+/**
+ * Truncation suffix for long messages.
+ */
+export const TRUNCATION_SUFFIX = "... [truncated]";
+//# sourceMappingURL=constants.js.map

package/build/logger/core/constants.js.map

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

package/build/logger/core/context.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Logger Context Management Module
+ *
+ * Provides robust context management for correlated logging using AsyncLocalStorage.
+ * Enables automatic log enrichment with request/session context across async boundaries.
+ *
+ * Key features:
+ * - Automatic context propagation through async operations
+ * - Hierarchical context support (parent/child relationships)
+ * - Thread-safe context isolation (depth tracked per-context, not globally)
+ * - Memory-efficient context management
+ *
+ * @module logger/core/context
+ */
+import type { LogContext } from "./types.js";
+/**
+ * Run a function within a logging context.
+ *
+ * All logs within the function (and any async operations it spawns)
+ * will automatically include the provided context. This is the primary
+ * way to establish context for a request or operation.
+ *
+ * Thread-safety: Depth is tracked within the context object itself,
+ * making it safe for concurrent operations across different async contexts.
+ *
+ * @param context - The context to use for logging
+ * @param fn - The function to execute within the context
+ * @returns The result of the function
+ * @throws Error if maximum context depth is exceeded
+ *
+ * @example
+ * ```typescript
+ * const result = runWithContext(
+ *   { requestId: 'req-123', sessionId: 'sess-456' },
+ *   async () => {
+ *     logger.info('Processing request'); // Includes requestId and sessionId
+ *     return await processRequest();
+ *   }
+ * );
+ * ```
+ */
+export declare function runWithContext<T>(context: LogContext, fn: () => T): T;
+/**
+ * Get the current logging context.
+ *
+ * Returns undefined if called outside of a context established by `runWithContext`.
+ *
+ * @returns The current context or undefined
+ *
+ * @example
+ * ```typescript
+ * const context = getContext();
+ * if (context?.requestId) {
+ *   console.log(`Request: ${context.requestId}`);
+ * }
+ * ```
+ */
+export declare function getContext(): LogContext | undefined;
+/**
+ * Get a specific value from the current context.
+ *
+ * Convenience function for accessing individual context properties
+ * without retrieving the entire context object.
+ *
+ * @param key - The context property to retrieve
+ * @returns The value or undefined if not in context or key doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const requestId = getContextValue('requestId');
+ * const component = getContextValue('component') ?? 'unknown';
+ * ```
+ */
+export declare function getContextValue<K extends keyof LogContext>(key: K): LogContext[K] | undefined;
+/**
+ * Check if currently running within a logging context.
+ *
+ * @returns true if inside a context established by `runWithContext`
+ *
+ * @example
+ * ```typescript
+ * if (hasContext()) {
+ *   // Safe to access context values
+ * }
+ * ```
+ */
+export declare function hasContext(): boolean;
+/**
+ * Create a new context by merging additional values with the current context.
+ *
+ * This is useful for adding context without losing existing values.
+ * If called outside a context, returns only the additional context.
+ *
+ * @param additionalContext - Context values to add/override
+ * @returns A new merged context (does not modify current context)
+ *
+ * @example
+ * ```typescript
+ * const newContext = mergeContext({ component: 'api', traceId: 'trace-123' });
+ * runWithContext(newContext, () => {
+ *   // Has both original context + new values
+ * });
+ * ```
+ */
+export declare function mergeContext(additionalContext: Partial<LogContext>): LogContext;
+/**
+ * Create a child context that inherits from the current context.
+ *
+ * The child context inherits all parent values but can override specific ones.
+ * Component names are automatically concatenated with a separator.
+ *
+ * @param childContext - Context values for the child
+ * @returns A new child context
+ *
+ * @example
+ * ```typescript
+ * // Parent has component: 'api'
+ * const childCtx = createChildContext({ component: 'handlers' });
+ * // childCtx.component = 'api.handlers'
+ * ```
+ */
+export declare function createChildContext(childContext: Partial<LogContext>): LogContext;
+/**
+ * Execute a function with an extended context (adds to current context).
+ *
+ * Combines `mergeContext` and `runWithContext` for convenience.
+ * This is the preferred way to add context for a sub-operation.
+ *
+ * @param additionalContext - Context values to add
+ * @param fn - The function to execute
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * await withExtendedContext({ operation: 'create' }, async () => {
+ *   logger.info('Creating resource'); // Includes operation: 'create'
+ *   return await createResource();
+ * });
+ * ```
+ */
+export declare function withExtendedContext<T>(additionalContext: Partial<LogContext>, fn: () => T): T;
+/**
+ * Execute a function with a child context.
+ *
+ * Combines `createChildContext` and `runWithContext` for convenience.
+ * Useful for creating hierarchical logging scopes.
+ *
+ * @param childContext - Context values for the child scope
+ * @param fn - The function to execute
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * await withChildContext({ component: 'validation' }, async () => {
+ *   logger.info('Validating input'); // component: 'api.validation'
+ *   return await validateInput();
+ * });
+ * ```
+ */
+export declare function withChildContext<T>(childContext: Partial<LogContext>, fn: () => T): T;
+/**
+ * Get the current context depth.
+ *
+ * Thread-safe: reads depth from the current async context.
+ * Returns 0 if called outside of any context.
+ *
+ * @returns The current context nesting depth
+ */
+export declare function getContextDepth(): number;
+//# sourceMappingURL=context.d.ts.map

package/build/logger/core/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/logger/core/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoB7C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAiBrE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,IAAI,UAAU,GAAG,SAAS,CAEnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAE7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAG/E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAgBhF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAG7F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAGrF;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC"}