@bryan-thompson/inspector-assessment-client 1.15.1 → 1.16.0

package/lib/services/assessment/modules/ResourceAssessor.js

@@ -0,0 +1,296 @@
+/**
+ * Resource Assessor Module
+ * Tests MCP server resources for accessibility, security, and compliance
+ *
+ * Tests include:
+ * - Resource accessibility (can read declared resources)
+ * - Path traversal vulnerabilities in resource URIs
+ * - Sensitive data exposure detection
+ * - URI validation and format compliance
+ */
+import { BaseAssessor } from "./BaseAssessor.js";
+// Sensitive file patterns that shouldn't be exposed
+const SENSITIVE_PATTERNS = [
+    /\.env$/i,
+    /\.pem$/i,
+    /\.key$/i,
+    /id_rsa/i,
+    /id_dsa/i,
+    /\.crt$/i,
+    /password/i,
+    /secret/i,
+    /credential/i,
+    /\/etc\/passwd/i,
+    /\/etc\/shadow/i,
+    /\.ssh\//i,
+    /aws_access_key/i,
+    /api[_-]?key/i,
+    /\.htpasswd/i,
+    /\.git\/config/i,
+];
+// Path traversal patterns to test
+const PATH_TRAVERSAL_PAYLOADS = [
+    "../../../etc/passwd",
+    "..\\..\\..\\windows\\system32\\config\\sam",
+    "....//....//....//etc/passwd",
+    "%2e%2e%2f%2e%2e%2f%2e%2e%2fetc%2fpasswd",
+    "..%252f..%252f..%252fetc/passwd",
+];
+// Sensitive content patterns in resource content
+const SENSITIVE_CONTENT_PATTERNS = [
+    /-----BEGIN.*PRIVATE KEY-----/i,
+    /-----BEGIN RSA PRIVATE KEY-----/i,
+    /sk-[a-zA-Z0-9]{32,}/i, // OpenAI-style API keys
+    /ghp_[a-zA-Z0-9]{36}/i, // GitHub tokens
+    /glpat-[a-zA-Z0-9-_]{20}/i, // GitLab tokens
+    /xox[baprs]-[a-zA-Z0-9-]+/i, // Slack tokens
+    /AKIA[A-Z0-9]{16}/i, // AWS access keys
+    /password\s*[:=]\s*['"][^'"]+['"]/i,
+    /secret\s*[:=]\s*['"][^'"]+['"]/i,
+];
+export class ResourceAssessor extends BaseAssessor {
+    async assess(context) {
+        const results = [];
+        // Check if resources are provided
+        if (!context.resources && !context.resourceTemplates) {
+            return this.createNoResourcesResponse();
+        }
+        const resources = context.resources || [];
+        const templates = context.resourceTemplates || [];
+        this.log(`Testing ${resources.length} resources and ${templates.length} resource templates`);
+        // Test each resource
+        for (const resource of resources) {
+            this.testCount++;
+            const result = await this.testResource(resource, context);
+            results.push(result);
+        }
+        // Test resource templates with path traversal payloads
+        for (const template of templates) {
+            this.testCount++;
+            const templateResults = await this.testResourceTemplate(template, context);
+            results.push(...templateResults);
+        }
+        // Calculate metrics
+        const accessibleResources = results.filter((r) => r.accessible).length;
+        const securityIssuesFound = results.filter((r) => r.securityIssues.length > 0).length;
+        const pathTraversalVulnerabilities = results.filter((r) => r.pathTraversalVulnerable).length;
+        const sensitiveDataExposures = results.filter((r) => r.sensitiveDataExposed).length;
+        // Determine status
+        const status = this.determineResourceStatus(pathTraversalVulnerabilities, sensitiveDataExposures, securityIssuesFound, results.length);
+        // Generate explanation and recommendations
+        const explanation = this.generateExplanation(results, pathTraversalVulnerabilities, sensitiveDataExposures);
+        const recommendations = this.generateRecommendations(results);
+        return {
+            resourcesTested: resources.length,
+            resourceTemplatesTested: templates.length,
+            accessibleResources,
+            securityIssuesFound,
+            pathTraversalVulnerabilities,
+            sensitiveDataExposures,
+            results,
+            status,
+            explanation,
+            recommendations,
+        };
+    }
+    createNoResourcesResponse() {
+        return {
+            resourcesTested: 0,
+            resourceTemplatesTested: 0,
+            accessibleResources: 0,
+            securityIssuesFound: 0,
+            pathTraversalVulnerabilities: 0,
+            sensitiveDataExposures: 0,
+            results: [],
+            status: "PASS",
+            explanation: "No resources declared by server. Resource assessment skipped.",
+            recommendations: [],
+        };
+    }
+    async testResource(resource, context) {
+        const result = {
+            resourceUri: resource.uri,
+            resourceName: resource.name,
+            mimeType: resource.mimeType,
+            tested: true,
+            accessible: false,
+            securityIssues: [],
+            pathTraversalVulnerable: false,
+            sensitiveDataExposed: false,
+            validUri: this.isValidUri(resource.uri),
+        };
+        // Check URI for sensitive patterns
+        if (this.isSensitiveUri(resource.uri)) {
+            result.securityIssues.push(`Resource URI matches sensitive file pattern: ${resource.uri}`);
+            result.sensitiveDataExposed = true;
+        }
+        // Try to read the resource if readResource function is provided
+        if (context.readResource) {
+            try {
+                const startTime = Date.now();
+                const content = await this.executeWithTimeout(context.readResource(resource.uri), 5000);
+                result.readTime = Date.now() - startTime;
+                result.accessible = true;
+                result.contentSizeBytes = content?.length || 0;
+                // Check content for sensitive data
+                if (content && this.containsSensitiveContent(content)) {
+                    result.securityIssues.push("Resource content contains sensitive data patterns (credentials, keys, etc.)");
+                    result.sensitiveDataExposed = true;
+                }
+            }
+            catch (error) {
+                result.error = this.extractErrorMessage(error);
+                result.accessible = false;
+            }
+        }
+        else {
+            result.tested = false;
+            result.error = "readResource function not provided - skipping read test";
+        }
+        return result;
+    }
+    async testResourceTemplate(template, context) {
+        const results = [];
+        // Test the template itself
+        const templateResult = {
+            resourceUri: template.uriTemplate,
+            resourceName: template.name,
+            mimeType: template.mimeType,
+            tested: true,
+            accessible: false,
+            securityIssues: [],
+            pathTraversalVulnerable: false,
+            sensitiveDataExposed: false,
+            validUri: this.isValidUriTemplate(template.uriTemplate),
+        };
+        // Check template for sensitive patterns
+        if (this.isSensitiveUri(template.uriTemplate)) {
+            templateResult.securityIssues.push(`Resource template matches sensitive file pattern: ${template.uriTemplate}`);
+            templateResult.sensitiveDataExposed = true;
+        }
+        results.push(templateResult);
+        // Test path traversal vulnerabilities if readResource is available
+        if (context.readResource) {
+            for (const payload of PATH_TRAVERSAL_PAYLOADS) {
+                this.testCount++;
+                const testUri = this.injectPayloadIntoTemplate(template.uriTemplate, payload);
+                const traversalResult = {
+                    resourceUri: testUri,
+                    resourceName: `${template.name} (path traversal test)`,
+                    tested: true,
+                    accessible: false,
+                    securityIssues: [],
+                    pathTraversalVulnerable: false,
+                    sensitiveDataExposed: false,
+                    validUri: false,
+                };
+                try {
+                    const content = await this.executeWithTimeout(context.readResource(testUri), 3000);
+                    // If we got content with a path traversal payload, it's vulnerable
+                    if (content &&
+                        (content.includes("root:") || content.includes("[fonts]"))) {
+                        traversalResult.pathTraversalVulnerable = true;
+                        traversalResult.accessible = true;
+                        traversalResult.securityIssues.push(`Path traversal vulnerability: successfully accessed ${testUri}`);
+                    }
+                }
+                catch {
+                    // Expected - path traversal should be rejected
+                    traversalResult.accessible = false;
+                }
+                results.push(traversalResult);
+            }
+        }
+        return results;
+    }
+    isValidUri(uri) {
+        try {
+            // Check for common URI schemes
+            if (uri.startsWith("file://") ||
+                uri.startsWith("http://") ||
+                uri.startsWith("https://") ||
+                uri.startsWith("resource://") ||
+                uri.match(/^[a-z][a-z0-9+.-]*:/i)) {
+                return true;
+            }
+            // Allow relative paths
+            return !uri.includes("..") || uri.startsWith("/");
+        }
+        catch {
+            return false;
+        }
+    }
+    isValidUriTemplate(template) {
+        // URI templates can contain {variable} placeholders
+        const withoutPlaceholders = template.replace(/\{[^}]+\}/g, "placeholder");
+        return this.isValidUri(withoutPlaceholders);
+    }
+    isSensitiveUri(uri) {
+        return SENSITIVE_PATTERNS.some((pattern) => pattern.test(uri));
+    }
+    containsSensitiveContent(content) {
+        return SENSITIVE_CONTENT_PATTERNS.some((pattern) => pattern.test(content));
+    }
+    injectPayloadIntoTemplate(template, payload) {
+        // Replace template variables with payload
+        const result = template.replace(/\{[^}]+\}/g, payload);
+        // If no variables, append payload
+        if (result === template) {
+            return template + "/" + payload;
+        }
+        return result;
+    }
+    determineResourceStatus(pathTraversalVulnerabilities, sensitiveDataExposures, securityIssuesFound, totalResources) {
+        // Critical failures
+        if (pathTraversalVulnerabilities > 0)
+            return "FAIL";
+        if (sensitiveDataExposures > 0)
+            return "FAIL";
+        // Moderate issues
+        if (securityIssuesFound > 0)
+            return "NEED_MORE_INFO";
+        // No resources tested
+        if (totalResources === 0)
+            return "PASS";
+        return "PASS";
+    }
+    generateExplanation(results, pathTraversalVulnerabilities, sensitiveDataExposures) {
+        const parts = [];
+        parts.push(`Tested ${results.length} resource(s).`);
+        if (pathTraversalVulnerabilities > 0) {
+            parts.push(`CRITICAL: ${pathTraversalVulnerabilities} path traversal vulnerability(ies) detected.`);
+        }
+        if (sensitiveDataExposures > 0) {
+            parts.push(`WARNING: ${sensitiveDataExposures} resource(s) may expose sensitive data.`);
+        }
+        const accessibleCount = results.filter((r) => r.accessible).length;
+        if (accessibleCount > 0) {
+            parts.push(`${accessibleCount} resource(s) are accessible.`);
+        }
+        return parts.join(" ");
+    }
+    generateRecommendations(results) {
+        const recommendations = [];
+        // Path traversal recommendations
+        const pathTraversalResults = results.filter((r) => r.pathTraversalVulnerable);
+        if (pathTraversalResults.length > 0) {
+            recommendations.push("CRITICAL: Implement path validation to prevent path traversal attacks. Normalize paths and validate against allowed directories.");
+        }
+        // Sensitive data recommendations
+        const sensitiveResults = results.filter((r) => r.sensitiveDataExposed);
+        if (sensitiveResults.length > 0) {
+            recommendations.push("Review resources for sensitive data exposure. Remove or restrict access to resources containing credentials, keys, or sensitive configuration.");
+        }
+        // Invalid URI recommendations
+        const invalidUriResults = results.filter((r) => !r.validUri);
+        if (invalidUriResults.length > 0) {
+            recommendations.push("Fix invalid resource URIs to ensure proper URI format compliance.");
+        }
+        // Inaccessible resource recommendations
+        const inaccessibleResults = results.filter((r) => r.tested && !r.accessible && !r.pathTraversalVulnerable);
+        if (inaccessibleResults.length > 0) {
+            recommendations.push(`${inaccessibleResults.length} declared resource(s) are not accessible. Verify resource paths and permissions.`);
+        }
+        return recommendations;
+    }
+}

package/lib/services/assessment/modules/SecurityAssessor.d.ts

@@ -1,9 +1,11 @@
 /**
  * Security Assessor Module
- * Tests for backend API security vulnerabilities using 8 focused patterns
- * - Critical Injection (3): Command, SQL, Path Traversal
+ * Tests for backend API security vulnerabilities using 18 focused patterns
+ * - Critical Injection (6): Command, Calculator, SQL, Path Traversal, XXE, NoSQL
  * - Input Validation (3): Type Safety, Boundary Testing, Required Fields
  * - Protocol Compliance (2): MCP Error Format, Timeout Handling
+ * - Tool-Specific (7): SSRF, Unicode Bypass, Nested Injection, Package Squatting,
+ *                      Data Exfiltration, Configuration Drift, Tool Shadowing
  */
 import { SecurityAssessment } from "../../../lib/assessmentTypes.js";
 import { BaseAssessor } from "./BaseAssessor.js";

package/lib/services/assessment/modules/SecurityAssessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SecurityAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/SecurityAssessor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,kBAAkB,EAInB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAU9D,qBAAa,gBAAiB,SAAQ,YAAY;IAC1C,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuFrE;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkC7B;;;;OAIG;YACW,yBAAyB;IAuKvC;;;;OAIG;YACW,qBAAqB;IA2JnC;;OAEG;YACW,WAAW;IA2HzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAkDzB;;;OAGG;IACH,OAAO,CAAC,8BAA8B;IAmDtC;;OAEG;IACH,OAAO,CAAC,aAAa;IA+BrB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAgClC;;;OAGG;IACH,OAAO,CAAC,eAAe;IA6HvB;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAiE7B;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAqC5B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAkC5B;;OAEG;YACW,+BAA+B;IAiC7C;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAYjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA0B/B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAkEnC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAuI3B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB;IAiM5B;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IAiDhC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAW9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,oBAAoB;IAoE5B;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAiB9B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAmB3B"}
+{"version":3,"file":"SecurityAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/SecurityAssessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,kBAAkB,EAInB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAa9D,qBAAa,gBAAiB,SAAQ,YAAY;IAC1C,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuFrE;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkC7B;;;;OAIG;YACW,yBAAyB;IAuKvC;;;;OAIG;YACW,qBAAqB;IA2JnC;;OAEG;YACW,WAAW;IA2HzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAkDzB;;;OAGG;IACH,OAAO,CAAC,8BAA8B;IAmDtC;;OAEG;IACH,OAAO,CAAC,aAAa;IA+BrB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAgClC;;;OAGG;IACH,OAAO,CAAC,eAAe;IA6HvB;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAiE7B;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAqC5B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAkC5B;;OAEG;YACW,+BAA+B;IAiC7C;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAYjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA0B/B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAkEnC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAuI3B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB;IAgK5B;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAW9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,oBAAoB;IAoE5B;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAiB9B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAmB3B"}

package/lib/services/assessment/modules/SecurityAssessor.js

@@ -1,9 +1,11 @@
 /**
  * Security Assessor Module
- * Tests for backend API security vulnerabilities using 8 focused patterns
- * - Critical Injection (3): Command, SQL, Path Traversal
+ * Tests for backend API security vulnerabilities using 18 focused patterns
+ * - Critical Injection (6): Command, Calculator, SQL, Path Traversal, XXE, NoSQL
  * - Input Validation (3): Type Safety, Boundary Testing, Required Fields
  * - Protocol Compliance (2): MCP Error Format, Timeout Handling
+ * - Tool-Specific (7): SSRF, Unicode Bypass, Nested Injection, Package Squatting,
+ *                      Data Exfiltration, Configuration Drift, Tool Shadowing
  */
 import { BaseAssessor } from "./BaseAssessor.js";
 import { getAllAttackPatterns, getPayloadsForAttack, } from "../../../lib/securityPatterns.js";
@@ -1071,8 +1073,6 @@ export class SecurityAssessor extends BaseAssessor {
      * Layer 2: Verify NO execution evidence (defense-in-depth)
      */
     isReflectionResponse(responseText) {
-        console.log("[DIAG] isReflectionResponse called");
-        console.log("[DIAG] Response preview:", responseText.substring(0, 200));
         // Status message patterns (NEW)
         const statusPatterns = [
             // "Action executed successfully: <anything>" (generic status message)
@@ -1152,18 +1152,7 @@ export class SecurityAssessor extends BaseAssessor {
             /error:.*too (long|short|large)/i,
         ];
         // LAYER 1: Check for reflection/status patterns
-        const matchedPatterns = [];
-        const hasReflection = reflectionPatterns.some((pattern) => {
-            const matches = pattern.test(responseText);
-            if (matches) {
-                matchedPatterns.push(pattern.source.substring(0, 50));
-            }
-            return matches;
-        });
-        console.log("[DIAG] Has reflection:", hasReflection);
-        if (matchedPatterns.length > 0) {
-            console.log("[DIAG] Matched reflection patterns:", matchedPatterns.join(", "));
-        }
+        const hasReflection = reflectionPatterns.some((pattern) => pattern.test(responseText));
         if (hasReflection) {
             // LAYER 2: Defense-in-depth - verify NO execution evidence
             // For JSON responses, check execution artifacts only in result/output fields
@@ -1187,25 +1176,18 @@ export class SecurityAssessor extends BaseAssessor {
                     ? this.detectExecutionArtifacts(outputFields) // Skip result, check only output fields
                     : this.detectExecutionArtifacts(resultText) ||
                         this.detectExecutionArtifacts(outputFields);
-                console.log("[DIAG] JSON mode - checking execution in result/output fields only");
-                console.log("[DIAG] Has execution in output:", hasExecutionInOutput);
                 if (hasExecutionInOutput) {
-                    console.log("[DIAG] RESULT: Reflection + Execution in output = VULNERABLE (false)");
-                    return false;
+                    return false; // Reflection + Execution in output = VULNERABLE
                 }
-                console.log("[DIAG] RESULT: Reflection + clean output = SAFE (true)");
-                return true;
+                return true; // Reflection + clean output = SAFE
             }
             catch {
                 // Not JSON, check entire response for execution
                 const hasExecution = this.detectExecutionArtifacts(responseText);
-                console.log("[DIAG] Text mode - Has execution artifacts:", hasExecution);
                 if (hasExecution) {
-                    console.log("[DIAG] RESULT: Reflection + Execution = VULNERABLE (false)");
-                    return false;
+                    return false; // Reflection + Execution = VULNERABLE
                 }
-                console.log("[DIAG] RESULT: Reflection only = SAFE (true)");
-                return true;
+                return true; // Reflection only = SAFE
             }
         }
         // JSON Structural Analysis with execution verification
@@ -1238,7 +1220,6 @@ export class SecurityAssessor extends BaseAssessor {
      * MEDIUM confidence: Contextual patterns (root alone, paths)
      */
     detectExecutionArtifacts(responseText) {
-        console.log("[DIAG] detectExecutionArtifacts called");
         const executionIndicators = [
             // HIGH CONFIDENCE - System files (requires format)
             /[a-z]+:x:\d+:\d+:/i, // passwd: "root:x:0:0:"
@@ -1259,19 +1240,7 @@ export class SecurityAssessor extends BaseAssessor {
             // MEDIUM CONFIDENCE - Process info
             /PID:\s*\d{3,}/i, // Process ID
         ];
-        const matchedExecutionPatterns = [];
-        const found = executionIndicators.some((pattern) => {
-            const matches = pattern.test(responseText);
-            if (matches) {
-                matchedExecutionPatterns.push(pattern.source.substring(0, 50));
-            }
-            return matches;
-        });
-        if (matchedExecutionPatterns.length > 0) {
-            console.log("[DIAG] Matched execution patterns:", matchedExecutionPatterns.join(", "));
-        }
-        console.log("[DIAG] Execution artifacts found:", found);
-        return found;
+        return executionIndicators.some((pattern) => pattern.test(responseText));
     }
     /**
      * Analyze injection response (existing logic)

package/lib/utils/jsonUtils.d.ts

@@ -0,0 +1,68 @@
+export type JsonValue = string | number | boolean | null | undefined | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonSchemaConst = {
+    const: JsonValue;
+    title?: string;
+    description?: string;
+};
+export type JsonSchemaType = {
+    type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "null" | ("string" | "number" | "integer" | "boolean" | "array" | "object" | "null")[];
+    title?: string;
+    description?: string;
+    required?: string[];
+    default?: JsonValue;
+    properties?: Record<string, JsonSchemaType>;
+    items?: JsonSchemaType;
+    minItems?: number;
+    maxItems?: number;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    nullable?: boolean;
+    pattern?: string;
+    format?: string;
+    enum?: string[];
+    enumNames?: string[];
+    const?: JsonValue;
+    oneOf?: (JsonSchemaType | JsonSchemaConst)[];
+    anyOf?: (JsonSchemaType | JsonSchemaConst)[];
+    $ref?: string;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type DataType = "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "array" | "null";
+/**
+ * Determines the specific data type of a JSON value
+ * @param value The JSON value to analyze
+ * @returns The specific data type including "array" and "null" as distinct types
+ */
+export declare function getDataType(value: JsonValue): DataType;
+/**
+ * Attempts to parse a string as JSON, only for objects and arrays
+ * @param str The string to parse
+ * @returns Object with success boolean and either parsed data or original string
+ */
+export declare function tryParseJson(str: string): {
+    success: boolean;
+    data: JsonValue;
+};
+/**
+ * Updates a value at a specific path in a nested JSON structure
+ * @param obj The original JSON value
+ * @param path Array of keys/indices representing the path to the value
+ * @param value The new value to set
+ * @returns A new JSON value with the updated path
+ */
+export declare function updateValueAtPath(obj: JsonValue, path: string[], value: JsonValue): JsonValue;
+/**
+ * Gets a value at a specific path in a nested JSON structure
+ * @param obj The JSON value to traverse
+ * @param path Array of keys/indices representing the path to the value
+ * @param defaultValue Value to return if path doesn't exist
+ * @returns The value at the path, or defaultValue if not found
+ */
+export declare function getValueAtPath(obj: JsonValue, path: string[], defaultValue?: JsonValue): JsonValue;
+//# sourceMappingURL=jsonUtils.d.ts.map

package/lib/utils/jsonUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonUtils.d.ts","sourceRoot":"","sources":["../../src/utils/jsonUtils.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,CAAC,EACD,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,OAAO,GACP,QAAQ,GACR,MAAM,GACN,CACI,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,OAAO,GACP,QAAQ,GACR,MAAM,CACT,EAAE,CAAC;IACR,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,cAAc,GAAG,eAAe,CAAC,EAAE,CAAC;IAC7C,KAAK,CAAC,EAAE,CAAC,cAAc,GAAG,eAAe,CAAC,EAAE,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,UAAU,GACV,OAAO,GACP,MAAM,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAItD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;CACjB,CAcA;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,SAAS,GACf,SAAS,CAkBX;AA+ED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EAAE,EACd,YAAY,GAAE,SAAgB,GAC7B,SAAS,CAyBX"}

package/lib/utils/jsonUtils.js

@@ -0,0 +1,141 @@
+/**
+ * Determines the specific data type of a JSON value
+ * @param value The JSON value to analyze
+ * @returns The specific data type including "array" and "null" as distinct types
+ */
+export function getDataType(value) {
+    if (Array.isArray(value))
+        return "array";
+    if (value === null)
+        return "null";
+    return typeof value;
+}
+/**
+ * Attempts to parse a string as JSON, only for objects and arrays
+ * @param str The string to parse
+ * @returns Object with success boolean and either parsed data or original string
+ */
+export function tryParseJson(str) {
+    const trimmed = str?.trim();
+    if (trimmed &&
+        !(trimmed.startsWith("{") && trimmed.endsWith("}")) &&
+        !(trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        return { success: false, data: str };
+    }
+    try {
+        return { success: true, data: JSON.parse(str) };
+    }
+    catch {
+        return { success: false, data: str };
+    }
+}
+/**
+ * Updates a value at a specific path in a nested JSON structure
+ * @param obj The original JSON value
+ * @param path Array of keys/indices representing the path to the value
+ * @param value The new value to set
+ * @returns A new JSON value with the updated path
+ */
+export function updateValueAtPath(obj, path, value) {
+    if (path.length === 0)
+        return value;
+    if (obj === null || obj === undefined) {
+        obj = !isNaN(Number(path[0])) ? [] : {};
+    }
+    if (Array.isArray(obj)) {
+        return updateArray(obj, path, value);
+    }
+    else if (typeof obj === "object" && obj !== null) {
+        return updateObject(obj, path, value);
+    }
+    else {
+        console.error(`Cannot update path ${path.join(".")} in non-object/array value:`, obj);
+        return obj;
+    }
+}
+/**
+ * Updates an array at a specific path
+ */
+function updateArray(array, path, value) {
+    const [index, ...restPath] = path;
+    const arrayIndex = Number(index);
+    if (isNaN(arrayIndex)) {
+        console.error(`Invalid array index: ${index}`);
+        return array;
+    }
+    if (arrayIndex < 0) {
+        console.error(`Array index out of bounds: ${arrayIndex} < 0`);
+        return array;
+    }
+    let newArray = [];
+    for (let i = 0; i < array.length; i++) {
+        newArray[i] = i in array ? array[i] : null;
+    }
+    if (arrayIndex >= newArray.length) {
+        const extendedArray = new Array(arrayIndex).fill(null);
+        // Copy over the existing elements (now guaranteed to be dense)
+        for (let i = 0; i < newArray.length; i++) {
+            extendedArray[i] = newArray[i];
+        }
+        newArray = extendedArray;
+    }
+    if (restPath.length === 0) {
+        newArray[arrayIndex] = value;
+    }
+    else {
+        newArray[arrayIndex] = updateValueAtPath(newArray[arrayIndex], restPath, value);
+    }
+    return newArray;
+}
+/**
+ * Updates an object at a specific path
+ */
+function updateObject(obj, path, value) {
+    const [key, ...restPath] = path;
+    // Validate object key
+    if (typeof key !== "string") {
+        console.error(`Invalid object key: ${key}`);
+        return obj;
+    }
+    const newObj = { ...obj };
+    if (restPath.length === 0) {
+        newObj[key] = value;
+    }
+    else {
+        // Ensure key exists
+        if (!(key in newObj)) {
+            newObj[key] = {};
+        }
+        newObj[key] = updateValueAtPath(newObj[key], restPath, value);
+    }
+    return newObj;
+}
+/**
+ * Gets a value at a specific path in a nested JSON structure
+ * @param obj The JSON value to traverse
+ * @param path Array of keys/indices representing the path to the value
+ * @param defaultValue Value to return if path doesn't exist
+ * @returns The value at the path, or defaultValue if not found
+ */
+export function getValueAtPath(obj, path, defaultValue = null) {
+    if (path.length === 0)
+        return obj;
+    const [first, ...rest] = path;
+    if (obj === null || obj === undefined) {
+        return defaultValue;
+    }
+    if (Array.isArray(obj)) {
+        const index = Number(first);
+        if (isNaN(index) || index < 0 || index >= obj.length) {
+            return defaultValue;
+        }
+        return getValueAtPath(obj[index], rest, defaultValue);
+    }
+    if (typeof obj === "object" && obj !== null) {
+        if (!(first in obj)) {
+            return defaultValue;
+        }
+        return getValueAtPath(obj[first], rest, defaultValue);
+    }
+    return defaultValue;
+}

package/lib/utils/paramUtils.d.ts

@@ -0,0 +1,11 @@
+import type { JsonSchemaType } from "./jsonUtils.js";
+/**
+ * Cleans parameters by removing undefined, null, and empty string values for optional fields
+ * while preserving all values for required fields and fields with explicit default values.
+ *
+ * @param params - The parameters object to clean
+ * @param schema - The JSON schema defining which fields are required
+ * @returns Cleaned parameters object with optional empty fields omitted
+ */
+export declare function cleanParams(params: Record<string, unknown>, schema: JsonSchemaType): Record<string, unknown>;
+//# sourceMappingURL=paramUtils.d.ts.map

package/lib/utils/paramUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paramUtils.d.ts","sourceRoot":"","sources":["../../src/utils/paramUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,cAAc,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BzB"}