@cyanheads/git-mcp-server 2.2.3 → 2.3.1

package/dist/utils/parsing/jsonParser.js

@@ -1,88 +1,128 @@
+/**
+ * @fileoverview Provides a utility class for parsing potentially partial JSON strings.
+ * It wraps the 'partial-json' npm library and includes functionality to handle
+ * optional <think>...</think> blocks often found at the beginning of LLM outputs.
+ * @module src/utils/parsing/jsonParser
+ */
 import { parse as parsePartialJson, Allow as PartialJsonAllow, } from "partial-json";
 import { BaseErrorCode, McpError } from "../../types-global/errors.js";
-// Import utils from the main barrel file (logger, RequestContext from ../internal/*)
-import { logger } from "../index.js";
+import { logger, requestContextService } from "../index.js";
 /**
- * Enum mirroring partial-json's Allow constants for specifying
+ * Enum mirroring `partial-json`'s `Allow` constants. These specify
  * what types of partial JSON structures are permissible during parsing.
- * Use bitwise OR to combine options (e.g., Allow.STR | Allow.OBJ).
+ * They can be combined using bitwise OR (e.g., `Allow.STR | Allow.OBJ`).
+ *
+ * The available properties are:
+ * - `STR`: Allow partial string.
+ * - `NUM`: Allow partial number.
+ * - `ARR`: Allow partial array.
+ * - `OBJ`: Allow partial object.
+ * - `NULL`: Allow partial null.
+ * - `BOOL`: Allow partial boolean.
+ * - `NAN`: Allow partial NaN. (Note: Standard JSON does not support NaN)
+ * - `INFINITY`: Allow partial Infinity. (Note: Standard JSON does not support Infinity)
+ * - `_INFINITY`: Allow partial -Infinity. (Note: Standard JSON does not support -Infinity)
+ * - `INF`: Allow both partial Infinity and -Infinity.
+ * - `SPECIAL`: Allow all special values (NaN, Infinity, -Infinity).
+ * - `ATOM`: Allow all atomic values (strings, numbers, booleans, null, special values).
+ * - `COLLECTION`: Allow all collection values (objects, arrays).
+ * - `ALL`: Allow all value types to be partial (default for `partial-json`'s parse).
+ * @see {@link https://github.com/promplate/partial-json-parser-js} for more details.
  */
 export const Allow = PartialJsonAllow;
-// Regex to find a <think> block at the start, capturing its content and the rest of the string
+/**
+ * Regular expression to find a <think> block at the start of a string.
+ * Captures content within <think>...</think> (Group 1) and the rest of the string (Group 2).
+ * @private
+ */
 const thinkBlockRegex = /^<think>([\s\S]*?)<\/think>\s*([\s\S]*)$/;
 /**
  * Utility class for parsing potentially partial JSON strings.
- * Wraps the 'partial-json' library to provide a consistent interface
- * within the atlas-mcp-agent project.
- * Handles optional <think>...</think> blocks at the beginning of the input.
+ * Wraps the 'partial-json' library for robust JSON parsing, handling
+ * incomplete structures and optional <think> blocks from LLMs.
  */
-class JsonParser {
+export class JsonParser {
     /**
-     * Parses a JSON string, potentially allowing for incomplete structures
-     * and handling optional <think> blocks at the start.
+     * Parses a JSON string, which may be partial or prefixed with a <think> block.
+     * If a <think> block is present, its content is logged, and parsing proceeds on the
+     * remainder. Uses 'partial-json' to handle incomplete JSON.
      *
-     * @param jsonString The JSON string to parse.
-     * @param allowPartial A bitwise OR combination of 'Allow' constants specifying permissible partial types (defaults to Allow.ALL).
-     * @param context Optional RequestContext for error correlation and logging think blocks.
+     * @template T The expected type of the parsed JSON object. Defaults to `unknown`.
+     * @param jsonString - The JSON string to parse.
+     * @param allowPartial - Bitwise OR combination of `Allow` constants specifying permissible
+     *   partial JSON types. Defaults to `Allow.ALL`.
+     * @param context - Optional `RequestContext` for logging and error correlation.
      * @returns The parsed JavaScript value.
-     * @throws {McpError} Throws an McpError with BaseErrorCode.VALIDATION_ERROR if parsing fails due to malformed JSON.
+     * @throws {McpError} If the string is empty after processing or if `partial-json` fails.
      */
     parse(jsonString, allowPartial = Allow.ALL, context) {
         let stringToParse = jsonString;
         const match = jsonString.match(thinkBlockRegex);
         if (match) {
-            const thinkContent = match[1].trim();
-            const restOfString = match[2];
+            const thinkContent = (match[1] || "").trim();
+            const restOfString = match[2] || "";
+            const logContext = context ||
+                requestContextService.createRequestContext({
+                    operation: "JsonParser.thinkBlock",
+                });
             if (thinkContent) {
                 logger.debug("LLM <think> block detected and logged.", {
-                    ...context,
+                    ...logContext,
                     thinkContent,
                 });
             }
             else {
-                logger.debug("Empty LLM <think> block detected.", context);
+                logger.debug("Empty LLM <think> block detected.", logContext);
             }
-            stringToParse = restOfString; // Parse only the part after </think>
+            stringToParse = restOfString;
         }
-        // Trim leading/trailing whitespace which might interfere with JSON parsing, especially if only JSON is left
         stringToParse = stringToParse.trim();
         if (!stringToParse) {
-            // If after removing think block and trimming, the string is empty, it's an error
-            throw new McpError(BaseErrorCode.VALIDATION_ERROR, "JSON string is empty after removing <think> block.", context);
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, "JSON string is empty after removing <think> block and trimming.", context);
         }
         try {
-            // Ensure the string starts with '{' or '[' if we expect an object or array after stripping <think>
-            // This helps catch cases where only non-JSON text remains.
-            if (!stringToParse.startsWith("{") && !stringToParse.startsWith("[")) {
-                // Check if it might be a simple string value that partial-json could parse
-                // Allow simple strings only if specifically permitted or Allow.ALL is used
-                const allowsString = (allowPartial & Allow.STR) === Allow.STR;
-                if (!allowsString && !stringToParse.startsWith('"')) {
-                    // Allow quoted strings if Allow.STR is set
-                    throw new Error("Remaining content does not appear to be valid JSON object or array.");
-                }
-                // If it starts with a quote and strings are allowed, let parsePartialJson handle it
-            }
             return parsePartialJson(stringToParse, allowPartial);
         }
-        catch (error) {
-            // Wrap the original error in an McpError for consistent error handling
-            // Include the original error message for better debugging context.
+        catch (e) {
+            const error = e;
+            const errorLogContext = context ||
+                requestContextService.createRequestContext({
+                    operation: "JsonParser.parseError",
+                });
             logger.error("Failed to parse JSON content.", {
-                ...context,
-                error: error.message,
-                contentAttempted: stringToParse,
+                ...errorLogContext,
+                errorDetails: error.message,
+                contentAttempted: stringToParse.substring(0, 200),
             });
             throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Failed to parse JSON: ${error.message}`, {
-                // Combine context and details into the third argument
                 ...context,
-                originalContent: stringToParse,
-                rawError: error instanceof Error ? error.stack : String(error), // Include raw error info
+                originalContentSample: stringToParse.substring(0, 200) +
+                    (stringToParse.length > 200 ? "..." : ""),
+                rawError: error instanceof Error ? error.stack : String(error),
             });
         }
     }
 }
 /**
- * Singleton instance of the JsonParser utility.
+ * Singleton instance of the `JsonParser`.
+ * Use this instance to parse JSON strings, with support for partial JSON and <think> blocks.
+ * @example
+ * ```typescript
+ * import { jsonParser, Allow, requestContextService } from './utils';
+ * const context = requestContextService.createRequestContext({ operation: 'TestJsonParsing' });
+ *
+ * const fullJson = '{"key": "value"}';
+ * const parsedFull = jsonParser.parse(fullJson, Allow.ALL, context);
+ * console.log(parsedFull); // Output: { key: 'value' }
+ *
+ * const partialObject = '<think>This is a thought.</think>{"key": "value", "arr": [1,';
+ * try {
+ *   const parsedPartial = jsonParser.parse(partialObject, undefined, context);
+ *   console.log(parsedPartial);
+ * } catch (e) {
+ *   console.error("Parsing partial object failed:", e);
+ * }
+ * ```
  */
 export const jsonParser = new JsonParser();
+//# sourceMappingURL=jsonParser.js.map

package/dist/utils/parsing/jsonParser.js.map

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

package/dist/utils/security/idGenerator.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Interface for entity prefix configuration
+ */
+export interface EntityPrefixConfig {
+    [key: string]: string;
+}
+/**
+ * ID Generation Options
+ */
+export interface IdGenerationOptions {
+    length?: number;
+    separator?: string;
+    charset?: string;
+}
+/**
+ * Generic ID Generator class for creating and managing unique identifiers
+ */
+export declare class IdGenerator {
+    private static DEFAULT_CHARSET;
+    private static DEFAULT_SEPARATOR;
+    private static DEFAULT_LENGTH;
+    private entityPrefixes;
+    private prefixToEntityType;
+    /**
+     * Constructor that accepts entity prefix configuration
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    constructor(entityPrefixes?: EntityPrefixConfig);
+    /**
+     * Set or update entity prefixes and rebuild the reverse lookup
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    setEntityPrefixes(entityPrefixes: EntityPrefixConfig): void;
+    /**
+     * Get all registered entity prefixes
+     * @returns The entity prefix configuration
+     */
+    getEntityPrefixes(): EntityPrefixConfig;
+    /**
+     * Generates a cryptographically secure random alphanumeric string
+     * @param length The length of the random string to generate
+     * @param charset Optional custom character set
+     * @returns Random alphanumeric string
+     */
+    generateRandomString(length?: number, charset?: string): string;
+    /**
+     * Generates a unique ID with an optional prefix
+     * @param prefix Optional prefix to add to the ID
+     * @param options Optional generation options
+     * @returns A unique identifier string
+     */
+    generate(prefix?: string, options?: IdGenerationOptions): string;
+    /**
+     * Generates a custom ID for an entity with format PREFIX_XXXXXX
+     * @param entityType The type of entity to generate an ID for
+     * @param options Optional generation options
+     * @returns A unique identifier string (e.g., "PROJ_A6B3J0")
+     * @throws {McpError} If the entity type is not registered
+     */
+    generateForEntity(entityType: string, options?: IdGenerationOptions): string;
+    /**
+     * Validates if a given ID matches the expected format for an entity type
+     * @param id The ID to validate
+     * @param entityType The expected entity type
+     * @param options Optional validation options
+     * @returns boolean indicating if the ID is valid
+     */
+    isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
+    /**
+     * Strips the prefix from an ID
+     * @param id The ID to strip
+     * @param separator Optional custom separator
+     * @returns The ID without the prefix
+     */
+    stripPrefix(id: string, separator?: string): string;
+    /**
+     * Determines the entity type from an ID
+     * @param id The ID to get the entity type for
+     * @param separator Optional custom separator
+     * @returns The entity type
+     * @throws {McpError} If the ID format is invalid or entity type is unknown
+     */
+    getEntityType(id: string, separator?: string): string;
+    /**
+     * Normalizes an entity ID to ensure consistent uppercase format
+     * @param id The ID to normalize
+     * @param separator Optional custom separator
+     * @returns The normalized ID in uppercase format
+     */
+    normalize(id: string, separator?: string): string;
+}
+export declare const idGenerator: IdGenerator;
+export declare const generateUUID: () => string;
+//# sourceMappingURL=idGenerator.d.ts.map

package/dist/utils/security/idGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idGenerator.d.ts","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,WAAW;IAEtB,OAAO,CAAC,MAAM,CAAC,eAAe,CAA0C;IAExE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAO;IAEvC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAK;IAElC,OAAO,CAAC,cAAc,CAA0B;IAEhD,OAAO,CAAC,kBAAkB,CAA8B;IAExD;;;OAGG;gBACS,cAAc,GAAE,kBAAuB;IAInD;;;OAGG;IACI,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,GAAG,IAAI;IAgBlE;;;OAGG;IACI,iBAAiB,IAAI,kBAAkB;IAI9C;;;;;OAKG;IACI,oBAAoB,CACzB,MAAM,GAAE,MAAmC,EAC3C,OAAO,GAAE,MAAoC,GAC5C,MAAM;IAYT;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM;IAY3E;;;;;;OAMG;IACI,iBAAiB,CACtB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,mBAAwB,GAChC,MAAM;IAaT;;;;;;OAMG;IACI,OAAO,CACZ,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,mBAAwB,GAChC,OAAO;IAeV;;;;;OAKG;IACI,WAAW,CAChB,EAAE,EAAE,MAAM,EACV,SAAS,GAAE,MAAsC,GAChD,MAAM;IAIT;;;;;;OAMG;IACI,aAAa,CAClB,EAAE,EAAE,MAAM,EACV,SAAS,GAAE,MAAsC,GAChD,MAAM;IAsBT;;;;;OAKG;IACI,SAAS,CACd,EAAE,EAAE,MAAM,EACV,SAAS,GAAE,MAAsC,GAChD,MAAM;CAeV;AAGD,eAAO,MAAM,WAAW,aAAoB,CAAC;AAG7C,eAAO,MAAM,YAAY,QAAO,MAE/B,CAAC"}

package/dist/utils/security/idGenerator.js

@@ -52,7 +52,8 @@ export class IdGenerator {
         const bytes = randomBytes(length);
         let result = "";
         for (let i = 0; i < length; i++) {
-            result += charset[bytes[i] % charset.length];
+            const byte = bytes[i] ?? 0;
+            result += charset[byte % charset.length];
         }
         return result;
     }
@@ -134,7 +135,12 @@ export class IdGenerator {
     normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
         const entityType = this.getEntityType(id, separator);
         const idParts = id.split(separator);
-        return `${this.entityPrefixes[entityType]}${separator}${idParts[1].toUpperCase()}`;
+        const randomPart = idParts[1];
+        if (!randomPart) {
+            // This case should theoretically be caught by getEntityType, but this adds robustness
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid ID format for normalization: ${id}. Random part is missing.`);
+        }
+        return `${this.entityPrefixes[entityType]}${separator}${randomPart.toUpperCase()}`;
     }
 }
 // Create and export a default instance with an empty entity prefix configuration
@@ -143,3 +149,4 @@ export const idGenerator = new IdGenerator();
 export const generateUUID = () => {
     return cryptoRandomUUID(); // Use imported cryptoRandomUUID
 };
+//# sourceMappingURL=idGenerator.js.map

package/dist/utils/security/idGenerator.js.map

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

package/dist/utils/security/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./sanitization.js";
+export * from "./rateLimiter.js";
+export * from "./idGenerator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/security/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/utils/security/index.js

@@ -1,3 +1,4 @@
 export * from "./sanitization.js";
 export * from "./rateLimiter.js";
 export * from "./idGenerator.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/security/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/utils/security/rateLimiter.d.ts

@@ -0,0 +1,93 @@
+import { RequestContext } from "../index.js";
+/**
+ * Rate limiting configuration options
+ */
+export interface RateLimitConfig {
+    /** Time window in milliseconds */
+    windowMs: number;
+    /** Maximum number of requests allowed in the window */
+    maxRequests: number;
+    /** Custom error message template */
+    errorMessage?: string;
+    /** Whether to skip rate limiting in certain environments (e.g. development) */
+    skipInDevelopment?: boolean;
+    /** Custom key generator function */
+    keyGenerator?: (identifier: string, context?: RequestContext) => string;
+    /** How often to run cleanup of expired entries (in milliseconds) */
+    cleanupInterval?: number;
+}
+/**
+ * Individual rate limit entry
+ */
+export interface RateLimitEntry {
+    /** Current request count */
+    count: number;
+    /** When the window resets (timestamp) */
+    resetTime: number;
+}
+/**
+ * Generic rate limiter that can be used across the application
+ */
+export declare class RateLimiter {
+    private config;
+    /** Map storing rate limit data */
+    private limits;
+    /** Cleanup interval timer */
+    private cleanupTimer;
+    /** Default configuration */
+    private static DEFAULT_CONFIG;
+    /**
+     * Create a new rate limiter
+     * @param config Rate limiting configuration
+     */
+    constructor(config: RateLimitConfig);
+    /**
+     * Start the cleanup timer to periodically remove expired entries
+     */
+    private startCleanupTimer;
+    /**
+     * Clean up expired rate limit entries to prevent memory leaks
+     */
+    private cleanupExpiredEntries;
+    /**
+     * Update rate limiter configuration
+     * @param config New configuration options
+     */
+    configure(config: Partial<RateLimitConfig>): void;
+    /**
+     * Get current configuration
+     * @returns Current rate limit configuration
+     */
+    getConfig(): RateLimitConfig;
+    /**
+     * Reset all rate limits
+     */
+    reset(): void;
+    /**
+     * Check if a request exceeds the rate limit
+     * @param key Unique identifier for the request source
+     * @param context Optional request context
+     * @throws {McpError} If rate limit is exceeded
+     */
+    check(key: string, context?: RequestContext): void;
+    /**
+     * Get rate limit information for a key
+     * @param key The rate limit key
+     * @returns Current rate limit status or null if no record exists
+     */
+    getStatus(key: string): {
+        current: number;
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    } | null;
+    /**
+     * Stop the cleanup timer when the limiter is no longer needed
+     */
+    dispose(): void;
+}
+/**
+ * Create and export a default rate limiter instance
+ */
+export declare const rateLimiter: RateLimiter;
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/utils/security/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../../src/utils/security/rateLimiter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAU,cAAc,EAAE,MAAM,aAAa,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oCAAoC;IACpC,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;IACxE,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,WAAW;IAmBV,OAAO,CAAC,MAAM;IAlB1B,kCAAkC;IAClC,OAAO,CAAC,MAAM,CAA8B;IAC5C,6BAA6B;IAC7B,OAAO,CAAC,YAAY,CAA+B;IACnD,4BAA4B;IAC5B,OAAO,CAAC,MAAM,CAAC,cAAc,CAO3B;IAEF;;;OAGG;gBACiB,MAAM,EAAE,eAAe;IAQ3C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;OAGG;IACI,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IASxD;;;OAGG;IACI,SAAS,IAAI,eAAe;IAInC;;OAEG;IACI,KAAK,IAAI,IAAI;IAKpB;;;;;OAKG;IACI,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IAqDzD;;;;OAIG;IACI,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG;QAC7B,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAeR;;OAEG;IACI,OAAO,IAAI,IAAI;CASvB;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,aAGtB,CAAC"}

package/dist/utils/security/rateLimiter.js

@@ -174,3 +174,4 @@ export const rateLimiter = new RateLimiter({
     windowMs: 15 * 60 * 1000, // 15 minutes
     maxRequests: 100, // 100 requests per window
 });
+//# sourceMappingURL=rateLimiter.js.map

package/dist/utils/security/rateLimiter.js.map

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

package/dist/utils/security/sanitization.d.ts

@@ -0,0 +1,181 @@
+import sanitizeHtml from "sanitize-html";
+/**
+ * Options for path sanitization.
+ */
+export interface PathSanitizeOptions {
+    /**
+     * Restrict paths to a specific root directory.
+     * If provided, the sanitized path will be relative to this root,
+     * and attempts to traverse above this root will be prevented.
+     */
+    rootDir?: string;
+    /**
+     * Normalize Windows-style backslashes (`\\`) to POSIX-style forward slashes (`/`).
+     * Defaults to `false`.
+     */
+    toPosix?: boolean;
+    /**
+     * Allow absolute paths.
+     * If `false` (default), absolute paths will be converted to relative paths
+     * (by removing leading slashes or drive letters).
+     * If `true`, absolute paths are permitted, subject to `rootDir` constraints if provided.
+     */
+    allowAbsolute?: boolean;
+}
+/**
+ * Information returned by the sanitizePath method, providing details about the sanitization process.
+ */
+export interface SanitizedPathInfo {
+    /** The final sanitized and normalized path string. */
+    sanitizedPath: string;
+    /** The original path string passed to the function before any normalization or sanitization. */
+    originalInput: string;
+    /** Indicates if the input path was determined to be absolute after initial `path.normalize()`. */
+    wasAbsolute: boolean;
+    /**
+     * Indicates if an initially absolute path was converted to a relative path.
+     * This typically happens if `options.allowAbsolute` was `false`.
+     */
+    convertedToRelative: boolean;
+    /** The effective options that were used for sanitization, including defaults. */
+    optionsUsed: PathSanitizeOptions;
+}
+/**
+ * Context-specific input sanitization options
+ */
+export interface SanitizeStringOptions {
+    /** Handle content differently based on context */
+    context?: "text" | "html" | "attribute" | "url" | "javascript";
+    /** Custom allowed tags when using html context */
+    allowedTags?: string[];
+    /** Custom allowed attributes when using html context */
+    allowedAttributes?: Record<string, string[]>;
+}
+/**
+ * Configuration for HTML sanitization
+ */
+export interface HtmlSanitizeConfig {
+    /** Allowed HTML tags */
+    allowedTags?: string[];
+    /** Allowed HTML attributes (global or per-tag) */
+    allowedAttributes?: sanitizeHtml.IOptions["allowedAttributes"];
+    /** Allow preserving comments - uses allowedTags internally */
+    preserveComments?: boolean;
+    /** Custom URL sanitizer */
+    transformTags?: sanitizeHtml.IOptions["transformTags"];
+}
+/**
+ * Sanitization class for handling various input sanitization tasks.
+ * Provides methods to clean and validate strings, HTML, URLs, paths, JSON, and numbers.
+ */
+export declare class Sanitization {
+    private static instance;
+    /** Default list of sensitive fields for sanitizing logs */
+    private sensitiveFields;
+    /** Default sanitize-html configuration */
+    private defaultHtmlSanitizeConfig;
+    /**
+     * Private constructor to enforce singleton pattern.
+     */
+    private constructor();
+    /**
+     * Get the singleton Sanitization instance.
+     * @returns {Sanitization} The singleton instance.
+     */
+    static getInstance(): Sanitization;
+    /**
+     * Set sensitive fields for log sanitization. These fields will be redacted when
+     * `sanitizeForLogging` is called.
+     * @param {string[]} fields - Array of field names to consider sensitive.
+     */
+    setSensitiveFields(fields: string[]): void;
+    /**
+     * Get the current list of sensitive fields used for log sanitization.
+     * @returns {string[]} Array of sensitive field names.
+     */
+    getSensitiveFields(): string[];
+    /**
+     * Sanitize HTML content using the `sanitize-html` library.
+     * Removes potentially malicious tags and attributes.
+     * @param {string} input - HTML string to sanitize.
+     * @param {HtmlSanitizeConfig} [config] - Optional custom sanitization configuration.
+     * @returns {string} Sanitized HTML string.
+     */
+    sanitizeHtml(input: string, config?: HtmlSanitizeConfig): string;
+    /**
+     * Sanitize string input based on context.
+     *
+     * **Important:** Using `context: 'javascript'` is explicitly disallowed and will throw an `McpError`.
+     * This is a security measure to prevent accidental execution or ineffective sanitization of JavaScript code.
+     *
+     * @param {string} input - String to sanitize.
+     * @param {SanitizeStringOptions} [options={}] - Sanitization options.
+     * @returns {string} Sanitized string.
+     * @throws {McpError} If `context: 'javascript'` is used.
+     */
+    sanitizeString(input: string, options?: SanitizeStringOptions): string;
+    /**
+     * Sanitize URL with robust validation.
+     * Ensures the URL uses allowed protocols and is well-formed.
+     * @param {string} input - URL to sanitize.
+     * @param {string[]} [allowedProtocols=['http', 'https']] - Allowed URL protocols.
+     * @returns {string} Sanitized URL.
+     * @throws {McpError} If URL is invalid or uses a disallowed protocol.
+     */
+    sanitizeUrl(input: string, allowedProtocols?: string[]): string;
+    /**
+     * Sanitizes a file path to prevent path traversal and other common attacks.
+     * Normalizes the path, optionally converts to POSIX style, and can restrict
+     * the path to a root directory.
+     *
+     * @param {string} input - The file path to sanitize.
+     * @param {PathSanitizeOptions} [options={}] - Options to control sanitization behavior.
+     * @returns {SanitizedPathInfo} An object containing the sanitized path and metadata about the sanitization process.
+     * @throws {McpError} If the path is invalid, unsafe (e.g., contains null bytes, attempts traversal).
+     */
+    sanitizePath(input: string, options?: PathSanitizeOptions): SanitizedPathInfo;
+    /**
+     * Sanitize a JSON string. Validates format and optionally checks size.
+     * @template T - The expected type of the parsed JSON object.
+     * @param {string} input - JSON string to sanitize.
+     * @param {number} [maxSize] - Maximum allowed size in bytes.
+     * @returns {T} Parsed and sanitized object.
+     * @throws {McpError} If JSON is invalid, too large, or input is not a string.
+     */
+    sanitizeJson<T = unknown>(input: string, maxSize?: number): T;
+    /**
+     * Ensure input is a valid number and optionally within a numeric range.
+     * Clamps the number to the range if min/max are provided and value is outside.
+     * @param {number | string} input - Number or string to validate.
+     * @param {number} [min] - Minimum allowed value (inclusive).
+     * @param {number} [max] - Maximum allowed value (inclusive).
+     * @returns {number} Sanitized number.
+     * @throws {McpError} If input is not a valid number or parsable string.
+     */
+    sanitizeNumber(input: number | string, min?: number, max?: number): number;
+    /**
+     * Sanitize input for logging to protect sensitive information.
+     * Deep clones the input and redacts fields matching `this.sensitiveFields`.
+     * @param {unknown} input - Input to sanitize.
+     * @returns {unknown} Sanitized input safe for logging.
+     */
+    sanitizeForLogging(input: unknown): unknown;
+    /**
+     * Private helper to convert attribute format for sanitize-html.
+     */
+    private convertAttributesFormat;
+    /**
+     * Recursively redact sensitive fields in an object or array.
+     * Modifies the object in place.
+     * @param {unknown} obj - The object or array to redact.
+     */
+    private redactSensitiveFields;
+}
+export declare const sanitization: Sanitization;
+/**
+ * Convenience function to sanitize input for logging.
+ * @param {unknown} input - Input to sanitize.
+ * @returns {unknown} Sanitized input safe for logging.
+ */
+export declare const sanitizeInputForLogging: (input: unknown) => unknown;
+//# sourceMappingURL=sanitization.d.ts.map

package/dist/utils/security/sanitization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitization.d.ts","sourceRoot":"","sources":["../../../src/utils/security/sanitization.ts"],"names":[],"mappings":"AACA,OAAO,YAAY,MAAM,eAAe,CAAC;AAMzC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,aAAa,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B,iFAAiF;IACjF,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,KAAK,GAAG,YAAY,CAAC;IAC/D,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAC/D,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,2BAA2B;IAC3B,aAAa,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;CACxD;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAe;IAEtC,2DAA2D;IAC3D,OAAO,CAAC,eAAe,CAcrB;IAEF,0CAA0C;IAC1C,OAAO,CAAC,yBAAyB,CAoC/B;IAEF;;OAEG;IACH,OAAO;IAIP;;;OAGG;WACW,WAAW,IAAI,YAAY;IAOzC;;;;OAIG;IACI,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAOjD;;;OAGG;IACI,kBAAkB,IAAI,MAAM,EAAE;IAIrC;;;;;;OAMG;IACI,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM;IAkBvE;;;;;;;;;;OAUG;IACI,cAAc,CACnB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM;IAyCT;;;;;;;OAOG;IACI,WAAW,CAChB,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,MAAM,EAAsB,GAC7C,MAAM;IAyBT;;;;;;;;;OASG;IACI,YAAY,CACjB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,mBAAwB,GAChC,iBAAiB;IAsGpB;;;;;;;OAOG;IACI,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC;IA4BpE;;;;;;;;OAQG;IACI,cAAc,CACnB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,GAAG,CAAC,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,MAAM,GACX,MAAM;IAmDT;;;;;OAKG;IACI,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAqBlD;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAM/B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;CA6B9B;AAGD,eAAO,MAAM,YAAY,cAA6B,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAO,OAAO,KAAG,OACjB,CAAC"}