ctxman 3.0.0 → 3.1.1

package/lib/api/mcp/resources.js

@@ -1,269 +1,328 @@
-import { getLogger } from "../../utils/logger.js";
-import { Scanner } from "../../core/Scanner.js";
-import path from "path";
-import fs from "fs";
+import { getLogger } from '../../utils/logger.js';
+import { Scanner } from '../../core/Scanner.js';
+import path from 'path';
+import fs from 'fs';
+import FileUtils from '../../utils/file-utils.js';
+import { redactSecrets } from '../../utils/secret-redactor.js';
+import { loadPolicy } from '../../policy/policy.js';
 
-const logger = getLogger("MCP:Resources");
+const logger = getLogger('MCP:Resources');
+const MAX_CACHED_ANALYSES = 10;
 
 /**
  * ResourceProvider manages MCP resources for codebase access
  * Provides list, read, and template operations for resources
  */
 export class ResourceProvider {
-    constructor(projectPath) {
-        this.projectPath = projectPath;
-        this.scanner = null;
-        this.cache = new Map();
-        this.supportedTypes = {
-            FILE: "file",
-            ANALYSIS: "analysis",
-            CONTEXT: "context"
-        };
+  constructor(projectPath) {
+    this.scanner = null;
+    this.projectPath = projectPath;
+    this.cache = new Map();
+    this.supportedTypes = {
+      FILE: 'file',
+      ANALYSIS: 'analysis',
+      CONTEXT: 'context',
+    };
+  }
+
+  get projectPath() {
+    return this._projectPath;
+  }
+
+  // analyze_codebase/generate_context switch projects; drop the scanner of the previous one
+  set projectPath(value) {
+    if (value !== this._projectPath) {
+      this._projectPath = value;
+      this.scanner = null;
     }
-
-    /**
-     * List available resources with optional pagination
-     * @param {string} cursor - Optional cursor for pagination
-     * @returns {Promise<{resources: Array, nextCursor?: string}>}
-     */
-    async listResources(cursor = null) {
-        try {
-            logger.info(`Listing resources${cursor ? ` from cursor: ${cursor}` : ""}`);
-
-            // Initialize scanner if needed
-            if (!this.scanner && this.projectPath) {
-                this.scanner = new Scanner(this.projectPath);
-            }
-
-            const resources = [];
-
-            // Add file resources if project path is set
-            if (this.scanner) {
-                const files = this.scanner.scan();
-                const PAGE_SIZE = 100;
-                const startIdx = cursor ? parseInt(cursor, 10) : 0;
-                const endIdx = Math.min(startIdx + PAGE_SIZE, files.length);
-
-                for (let i = startIdx; i < endIdx; i++) {
-                    const file = files[i];
-                    resources.push({
-                        uri: `file://codebase/${file.relativePath}`,
-                        name: path.basename(file.relativePath),
-                        description: `Source file: ${file.relativePath}`,
-                        mimeType: this.getMimeType(file.relativePath)
-                    });
-                }
-
-                // Return next cursor if there are more results
-                const nextCursor = endIdx < files.length ? endIdx.toString() : undefined;
-
-                logger.info(`Listed ${resources.length} resources`);
-                return { resources, nextCursor };
-            }
-
-            return { resources };
-        } catch (error) {
-            logger.error(`Error listing resources: ${error.message}`);
-            throw error;
-        }
-    }
-
-    /**
-     * Read a specific resource by URI
-     * @param {string} uri - Resource URI
-     * @returns {Promise<{contents: Array}>}
-     */
-    async readResource(uri) {
-        try {
-            logger.info(`Reading resource: ${uri}`);
-
-            // Parse URI
-            const parsed = this.parseUri(uri);
-
-            switch (parsed.type) {
-                case this.supportedTypes.FILE:
-                    return await this.readFileResource(parsed.path);
-
-                case this.supportedTypes.ANALYSIS:
-                    return await this.readAnalysisResource(parsed.id);
-
-                case this.supportedTypes.CONTEXT:
-                    return await this.readContextResource(parsed.name);
-
-                default:
-                    throw new Error(`Unsupported resource type: ${parsed.type}`);
-            }
-        } catch (error) {
-            logger.error(`Error reading resource ${uri}: ${error.message}`);
-            throw error;
+  }
+
+  /**
+   * List available resources with optional pagination
+   * @param {string} cursor - Optional cursor for pagination
+   * @returns {Promise<{resources: Array, nextCursor?: string}>}
+   */
+  async listResources(cursor = null) {
+    try {
+      logger.info(`Listing resources${cursor ? ` from cursor: ${cursor}` : ''}`);
+
+      // Initialize scanner if needed
+      if (!this.scanner && this.projectPath) {
+        this.scanner = new Scanner(this.projectPath);
+      }
+
+      const resources = [];
+
+      // Analysis ids are generated by the server, so listing is the only way a client can
+      // find analysis://recent/{id}. The cursor pages through files, so they go on page one.
+      if (!cursor) {
+        resources.push(...this.listCachedAnalyses());
+      }
+
+      // Add file resources if project path is set
+      if (this.scanner) {
+        const files = this.scanner.scan();
+        const PAGE_SIZE = 100;
+        const startIdx = cursor ? parseInt(cursor, 10) : 0;
+        const endIdx = Math.min(startIdx + PAGE_SIZE, files.length);
+
+        for (let i = startIdx; i < endIdx; i++) {
+          const file = files[i];
+          resources.push({
+            uri: `file://codebase/${file.relativePath}`,
+            name: path.basename(file.relativePath),
+            description: `Source file: ${file.relativePath}`,
+            mimeType: this.getMimeType(file.relativePath),
+          });
         }
-    }
-
-    /**
-     * Get resource templates for dynamic resources
-     * @returns {Array}
-     */
-    getResourceTemplates() {
-        return [
-            {
-                uriTemplate: "file://codebase/{path}",
-                name: "Codebase Files",
-                description: "Access source files in the project",
-                mimeType: "text/plain"
-            },
-            {
-                uriTemplate: "analysis://recent/{id}",
-                name: "Analysis Results",
-                description: "Cached analysis results",
-                mimeType: "application/json"
-            },
-            {
-                uriTemplate: "context://template/{name}",
-                name: "Context Templates",
-                description: "Pre-generated context for common workflows",
-                mimeType: "text/plain"
-            }
-        ];
-    }
-
-    /**
-     * Read a file resource
-     * @private
-     */
-    async readFileResource(relativePath) {
-        const fullPath = path.join(this.projectPath || "", relativePath);
 
-        // Security check: ensure path is within project
-        const resolvedPath = path.resolve(fullPath);
-        const resolvedProject = path.resolve(this.projectPath || "");
+        // Return next cursor if there are more results
+        const nextCursor = endIdx < files.length ? endIdx.toString() : undefined;
 
-        if (!resolvedPath.startsWith(resolvedProject)) {
-            throw new Error("Access denied: path outside project directory");
-        }
-
-        const content = fs.readFileSync(fullPath, "utf-8");
+        logger.info(`Listed ${resources.length} resources`);
+        return { resources, nextCursor };
+      }
 
-        return {
-            contents: [{
-                uri: `file://codebase/${relativePath}`,
-                mimeType: this.getMimeType(relativePath),
-                text: content
-            }]
-        };
+      return { resources };
+    } catch (error) {
+      logger.error(`Error listing resources: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Read a specific resource by URI
+   * @param {string} uri - Resource URI
+   * @returns {Promise<{contents: Array}>}
+   */
+  async readResource(uri) {
+    try {
+      logger.info(`Reading resource: ${uri}`);
+
+      // Parse URI
+      const parsed = this.parseUri(uri);
+
+      switch (parsed.type) {
+        case this.supportedTypes.FILE:
+          return await this.readFileResource(parsed.path);
+
+        case this.supportedTypes.ANALYSIS:
+          return await this.readAnalysisResource(parsed.id);
+
+        case this.supportedTypes.CONTEXT:
+          return await this.readContextResource(parsed.name);
+
+        default:
+          throw new Error(`Unsupported resource type: ${parsed.type}`);
+      }
+    } catch (error) {
+      logger.error(`Error reading resource ${uri}: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Get resource templates for dynamic resources
+   * @returns {Array}
+   */
+  getResourceTemplates() {
+    return [
+      {
+        uriTemplate: 'file://codebase/{path}',
+        name: 'Codebase Files',
+        description: 'Access source files in the project',
+        mimeType: 'text/plain',
+      },
+      {
+        uriTemplate: 'analysis://recent/{id}',
+        name: 'Analysis Results',
+        description: 'Cached analysis results',
+        mimeType: 'application/json',
+      },
+      {
+        uriTemplate: 'context://template/{name}',
+        name: 'Context Templates',
+        description: 'Pre-generated context for common workflows',
+        mimeType: 'text/plain',
+      },
+    ];
+  }
+
+  /**
+   * Read a file resource
+   * @private
+   */
+  async readFileResource(relativePath) {
+    // Security check: the path must stay inside the project (a prefix check would let
+    // /proj-other through for /proj)
+    const resolvedProject = path.resolve(this.projectPath || '');
+    const resolvedPath = path.resolve(resolvedProject, relativePath);
+    const inside = path.relative(resolvedProject, resolvedPath);
+    if (inside === '' || inside.startsWith('..') || path.isAbsolute(inside)) {
+      throw new Error('Access denied: path outside project directory');
     }
 
-    /**
-     * Read an analysis resource from cache
-     * @private
-     */
-    async readAnalysisResource(id) {
-        const cached = this.cache.get(`analysis:${id}`);
-
-        if (!cached) {
-            throw new Error(`Analysis result not found: ${id}`);
-        }
+    // Same rule as the scanner: no binary or secret-bearing files such as .env or *.pem
+    if (!FileUtils.isText(resolvedPath)) {
+      throw new Error('Access denied: not a text source file');
+    }
 
-        return {
-            contents: [{
-                uri: `analysis://recent/${id}`,
-                mimeType: "application/json",
-                text: JSON.stringify(cached, null, 2)
-            }]
-        };
+    if (loadPolicy(resolvedProject).isDenied(inside)) {
+      throw new Error('Access denied: the export policy denies this file');
     }
 
-    /**
-     * Read a context template resource
-     * @private
-     */
-    async readContextResource(name) {
-        const cached = this.cache.get(`context:${name}`);
+    const { text } = redactSecrets(fs.readFileSync(resolvedPath, 'utf-8'));
+
+    return {
+      contents: [
+        {
+          uri: `file://codebase/${relativePath}`,
+          mimeType: this.getMimeType(relativePath),
+          text,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Read an analysis resource from cache
+   * @private
+   */
+  async readAnalysisResource(id) {
+    const cached = this.cache.get(`analysis:${id}`);
+
+    if (!cached) {
+      throw new Error(`Analysis result not found: ${id}`);
+    }
 
-        if (!cached) {
-            throw new Error(`Context template not found: ${name}`);
-        }
+    return {
+      contents: [
+        {
+          uri: `analysis://recent/${id}`,
+          mimeType: 'application/json',
+          text: JSON.stringify(cached, null, 2),
+        },
+      ],
+    };
+  }
+
+  /**
+   * Read a context template resource
+   * @private
+   */
+  async readContextResource(name) {
+    const cached = this.cache.get(`context:${name}`);
+
+    if (!cached) {
+      throw new Error(`Context template not found: ${name}`);
+    }
 
+    return {
+      contents: [
+        {
+          uri: `context://template/${name}`,
+          mimeType: 'text/plain',
+          text: cached,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Cache an analysis result
+   * @param {string} id - Resource ID
+   * @param {Object} data - Analysis data
+   */
+  cacheAnalysis(id, data) {
+    this.cache.set(`analysis:${id}`, data);
+    // Every analyze_codebase call adds a full analysis; a long-running server keeps the latest
+    const analyses = [...this.cache.keys()].filter((key) => key.startsWith('analysis:'));
+    for (const key of analyses.slice(0, -MAX_CACHED_ANALYSES)) {
+      this.cache.delete(key);
+    }
+    logger.info(`Cached analysis: ${id}`);
+  }
+
+  /**
+   * Resource entries for the cached analysis results
+   * @private
+   */
+  listCachedAnalyses() {
+    return [...this.cache.keys()]
+      .filter((key) => key.startsWith('analysis:'))
+      .map((key) => {
+        const id = key.slice('analysis:'.length);
         return {
-            contents: [{
-                uri: `context://template/${name}`,
-                mimeType: "text/plain",
-                text: cached
-            }]
+          uri: `analysis://recent/${id}`,
+          name: `Analysis ${id}`,
+          description: 'Cached analyze_codebase result',
+          mimeType: 'application/json',
         };
+      });
+  }
+
+  /**
+   * Cache a context template
+   * @param {string} name - Template name
+   * @param {string} content - Context content
+   */
+  cacheContext(name, content) {
+    this.cache.set(`context:${name}`, content);
+    logger.info(`Cached context: ${name}`);
+  }
+
+  /**
+   * Parse a resource URI
+   * @private
+   */
+  parseUri(uri) {
+    const fileMatch = uri.match(/^file:\/\/codebase\/(.+)$/);
+    if (fileMatch) {
+      return { type: this.supportedTypes.FILE, path: fileMatch[1] };
     }
 
-    /**
-     * Cache an analysis result
-     * @param {string} id - Resource ID
-     * @param {Object} data - Analysis data
-     */
-    cacheAnalysis(id, data) {
-        this.cache.set(`analysis:${id}`, data);
-        logger.info(`Cached analysis: ${id}`);
+    const analysisMatch = uri.match(/^analysis:\/\/recent\/(.+)$/);
+    if (analysisMatch) {
+      return { type: this.supportedTypes.ANALYSIS, id: analysisMatch[1] };
     }
 
-    /**
-     * Cache a context template
-     * @param {string} name - Template name
-     * @param {string} content - Context content
-     */
-    cacheContext(name, content) {
-        this.cache.set(`context:${name}`, content);
-        logger.info(`Cached context: ${name}`);
+    const contextMatch = uri.match(/^context:\/\/template\/(.+)$/);
+    if (contextMatch) {
+      return { type: this.supportedTypes.CONTEXT, name: contextMatch[1] };
     }
 
-    /**
-     * Parse a resource URI
-     * @private
-     */
-    parseUri(uri) {
-        const fileMatch = uri.match(/^file:\/\/codebase\/(.+)$/);
-        if (fileMatch) {
-            return { type: this.supportedTypes.FILE, path: fileMatch[1] };
-        }
-
-        const analysisMatch = uri.match(/^analysis:\/\/recent\/(.+)$/);
-        if (analysisMatch) {
-            return { type: this.supportedTypes.ANALYSIS, id: analysisMatch[1] };
-        }
-
-        const contextMatch = uri.match(/^context:\/\/template\/(.+)$/);
-        if (contextMatch) {
-            return { type: this.supportedTypes.CONTEXT, name: contextMatch[1] };
-        }
-
-        throw new Error(`Invalid resource URI: ${uri}`);
-    }
-
-    /**
-     * Get MIME type for a file
-     * @private
-     */
-    getMimeType(filePath) {
-        const ext = path.extname(filePath).toLowerCase();
-
-        const mimeTypes = {
-            ".js": "text/javascript",
-            ".ts": "text/typescript",
-            ".jsx": "text/javascript",
-            ".tsx": "text/typescript",
-            ".py": "text/x-python",
-            ".java": "text/x-java",
-            ".go": "text/x-go",
-            ".rs": "text/x-rust",
-            ".c": "text/x-c",
-            ".cpp": "text/x-c++",
-            ".h": "text/x-c",
-            ".json": "application/json",
-            ".md": "text/markdown",
-            ".txt": "text/plain",
-            ".html": "text/html",
-            ".css": "text/css",
-            ".xml": "application/xml",
-            ".yaml": "text/yaml",
-            ".yml": "text/yaml"
-        };
-
-        return mimeTypes[ext] || "text/plain";
-    }
+    throw new Error(`Invalid resource URI: ${uri}`);
+  }
+
+  /**
+   * Get MIME type for a file
+   * @private
+   */
+  getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+
+    const mimeTypes = {
+      '.js': 'text/javascript',
+      '.ts': 'text/typescript',
+      '.jsx': 'text/javascript',
+      '.tsx': 'text/typescript',
+      '.py': 'text/x-python',
+      '.java': 'text/x-java',
+      '.go': 'text/x-go',
+      '.rs': 'text/x-rust',
+      '.c': 'text/x-c',
+      '.cpp': 'text/x-c++',
+      '.h': 'text/x-c',
+      '.json': 'application/json',
+      '.md': 'text/markdown',
+      '.txt': 'text/plain',
+      '.html': 'text/html',
+      '.css': 'text/css',
+      '.xml': 'application/xml',
+      '.yaml': 'text/yaml',
+      '.yml': 'text/yaml',
+    };
+
+    return mimeTypes[ext] || 'text/plain';
+  }
 }

package/lib/api/mcp/sandbox.js

@@ -0,0 +1,89 @@
+/**
+ * Path checks for MCP tool and prompt arguments.
+ *
+ * Every `path` a client passes must name an existing directory. When the server runs with a
+ * root (`ctxman mcp --root <dir>` or CTXMAN_MCP_ROOT), the path must also lie inside that
+ * root once symlinks are resolved, and relative paths are taken relative to the root.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Resolve the sandbox root to its real path
+ * @param {string} root - Directory given with --root or CTXMAN_MCP_ROOT
+ * @returns {string} Absolute real path of the directory
+ * @throws {Error} When the directory does not exist
+ */
+export function resolveRootDir(root) {
+  const resolved = path.resolve(root);
+  const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+  if (!stat?.isDirectory()) {
+    throw new Error(`MCP root is not an existing directory: ${resolved}`);
+  }
+  return fs.realpathSync(resolved);
+}
+
+/**
+ * Whether `target` is `root` itself or lies below it (both absolute and already resolved)
+ * @param {string} root
+ * @param {string} target
+ * @returns {boolean}
+ */
+export function isInsideRoot(root, target) {
+  const relative = path.relative(root, target);
+  return (
+    relative === '' ||
+    (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+/**
+ * Check a client-supplied path.
+ *
+ * Without a root the value is returned as given, so tools behave as before; it only has to
+ * exist. With a root, a missing value means the root itself, and the real path is returned.
+ *
+ * @param {string|undefined} value - The `path` (or `projectPath`, `filePath`) argument
+ * @param {Object} [options]
+ * @param {string|null} [options.root] - Real path of the sandbox root, if any
+ * @param {'directory'|'file'|'any'} [options.expect='directory'] - What the path must name
+ * @param {string} [options.name='path'] - Argument name, for error messages
+ * @returns {string} Path to hand to the tool
+ * @throws {Error} When the path is missing, has the wrong type or lies outside the root
+ */
+export function resolveSandboxPath(
+  value,
+  { root = null, expect = 'directory', name = 'path' } = {}
+) {
+  if (value === undefined || value === null || value === '') {
+    if (root && expect !== 'file') return root;
+    throw new Error(`Missing required argument: ${name}`);
+  }
+  if (typeof value !== 'string') {
+    throw new Error(`Argument "${name}" must be a string`);
+  }
+
+  const candidate = root ? path.resolve(root, value) : path.resolve(value);
+  const stat = fs.statSync(candidate, { throwIfNoEntry: false });
+  if (!stat) {
+    throw new Error(`${name} does not exist: ${value}`);
+  }
+  if (expect === 'directory' && !stat.isDirectory()) {
+    throw new Error(`${name} is not a directory: ${value}`);
+  }
+  if (expect === 'file' && !stat.isFile()) {
+    throw new Error(`${name} is not a file: ${value}`);
+  }
+  if (expect === 'any' && !stat.isDirectory() && !stat.isFile()) {
+    throw new Error(`${name} is neither a file nor a directory: ${value}`);
+  }
+
+  if (!root) return value;
+
+  const real = fs.realpathSync(candidate);
+  if (!isInsideRoot(root, real)) {
+    throw new Error(`${name} is outside the MCP root ${root}: ${value}`);
+  }
+  return real;
+}