@vibecheckai/cli 3.5.0 → 3.5.2

package/mcp-server/lib/sandbox.ts

@@ -0,0 +1,395 @@
+/**
+ * Sandbox - Path Security for MCP Server
+ *
+ * Enforces that all tool requests resolve within an allowed workspace root.
+ * Prevents path traversal attacks, absolute path escapes, and symlink escapes.
+ *
+ * @module mcp-server/lib/sandbox
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+
+/**
+ * Default excluded directory patterns.
+ * These are enforced at the MCP level even if CLI forgets.
+ */
+export const DEFAULT_EXCLUSIONS = [
+  'node_modules/**',
+  'venv/**',
+  '.venv/**',
+  'dist/**',
+  'build/**',
+  '.next/**',
+  'out/**',
+  'coverage/**',
+  '.git/**',
+  '.cache/**',
+  '.turbo/**',
+] as const;
+
+/**
+ * Third-party directories (can be included via config)
+ */
+export const THIRD_PARTY_DIRS = ['node_modules/**', 'venv/**', '.venv/**'] as const;
+
+/**
+ * Generated/build directories (can be included via config)
+ */
+export const GENERATED_DIRS = ['dist/**', 'build/**', '.next/**', 'out/**'] as const;
+
+/**
+ * Configuration options for sandbox path resolution
+ */
+export interface SandboxConfig {
+  /** Workspace root directory (absolute path) */
+  workspaceRoot: string;
+  /** Include third-party directories (node_modules, venv, etc.) */
+  includeThirdParty?: boolean;
+  /** Include generated/build directories (dist, build, .next, out) */
+  includeGenerated?: boolean;
+  /** Additional paths to exclude (glob patterns) */
+  additionalExclusions?: string[];
+  /** Paths to explicitly allow (overrides exclusions) */
+  allowlist?: string[];
+}
+
+/**
+ * Result of a sandbox path validation
+ */
+export interface SandboxResult {
+  /** Whether the path is valid and safe */
+  valid: boolean;
+  /** The resolved absolute path (if valid) */
+  resolvedPath?: string;
+  /** Error message (if invalid) */
+  error?: string;
+  /** Error code for programmatic handling */
+  errorCode?:
+    | 'TRAVERSAL_DETECTED'
+    | 'ABSOLUTE_PATH_OUTSIDE_ROOT'
+    | 'SYMLINK_ESCAPE'
+    | 'EXCLUDED_PATH'
+    | 'INVALID_ROOT';
+}
+
+/**
+ * Checks if a path matches any of the given glob patterns.
+ * Simple glob matching supporting ** and * wildcards.
+ */
+function matchesGlob(filePath: string, patterns: readonly string[]): boolean {
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  for (const pattern of patterns) {
+    const normalizedPattern = pattern.replace(/\\/g, '/');
+
+    // Convert glob pattern to regex
+    const regexPattern = normalizedPattern
+      .replace(/\*\*/g, '<<<GLOBSTAR>>>')
+      .replace(/\*/g, '[^/]*')
+      .replace(/<<<GLOBSTAR>>>/g, '.*')
+      .replace(/\//g, '\\/');
+
+    const regex = new RegExp(`^${regexPattern}$|^${regexPattern}\\/|\\/${regexPattern}$|\\/${regexPattern}\\/`);
+
+    if (regex.test(normalizedPath)) {
+      return true;
+    }
+
+    // Also check if the path starts with the pattern's directory
+    const patternDir = normalizedPattern.replace(/\/?\*\*.*$/, '');
+    if (patternDir && normalizedPath.startsWith(patternDir + '/')) {
+      return true;
+    }
+    if (patternDir && normalizedPath === patternDir) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Detects path traversal attempts (../ sequences)
+ */
+function hasTraversalSequence(inputPath: string): boolean {
+  const normalized = inputPath.replace(/\\/g, '/');
+
+  // Check for .. sequences
+  if (normalized.includes('..')) {
+    return true;
+  }
+
+  // Check for URL-encoded traversal
+  if (normalized.includes('%2e%2e') || normalized.includes('%2E%2E')) {
+    return true;
+  }
+
+  // Check for null byte injection
+  if (normalized.includes('\0') || normalized.includes('%00')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a path is an absolute path
+ */
+function isAbsolutePath(inputPath: string): boolean {
+  // Windows absolute paths: C:\, D:\, etc.
+  if (/^[a-zA-Z]:[/\\]/.test(inputPath)) {
+    return true;
+  }
+
+  // Unix absolute paths: /
+  if (inputPath.startsWith('/')) {
+    return true;
+  }
+
+  // UNC paths: \\server\share
+  if (inputPath.startsWith('\\\\')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Gets the active exclusion patterns based on config
+ */
+export function getActiveExclusions(config: SandboxConfig): string[] {
+  const exclusions: string[] = [];
+
+  // Start with defaults that are always excluded
+  exclusions.push('coverage/**', '.git/**', '.cache/**', '.turbo/**');
+
+  // Add third-party dirs unless explicitly included
+  if (!config.includeThirdParty) {
+    exclusions.push(...THIRD_PARTY_DIRS);
+  }
+
+  // Add generated dirs unless explicitly included
+  if (!config.includeGenerated) {
+    exclusions.push(...GENERATED_DIRS);
+  }
+
+  // Add any additional exclusions
+  if (config.additionalExclusions) {
+    exclusions.push(...config.additionalExclusions);
+  }
+
+  return exclusions;
+}
+
+/**
+ * Validates and resolves a path within the sandbox.
+ *
+ * @param inputPath - The path to validate (can be relative or absolute)
+ * @param config - Sandbox configuration
+ * @returns SandboxResult with validation status and resolved path
+ */
+export function resolveSandboxPath(inputPath: string, config: SandboxConfig): SandboxResult {
+  // Validate workspace root exists and is absolute
+  if (!config.workspaceRoot || !isAbsolutePath(config.workspaceRoot)) {
+    return {
+      valid: false,
+      error: 'Invalid workspace root: must be an absolute path',
+      errorCode: 'INVALID_ROOT',
+    };
+  }
+
+  // Normalize workspace root
+  const normalizedRoot = path.resolve(config.workspaceRoot);
+
+  // Check for traversal sequences in the input
+  if (hasTraversalSequence(inputPath)) {
+    return {
+      valid: false,
+      error: `Path traversal detected in: ${inputPath}`,
+      errorCode: 'TRAVERSAL_DETECTED',
+    };
+  }
+
+  // Determine the target path
+  let targetPath: string;
+
+  if (isAbsolutePath(inputPath)) {
+    // Absolute path - check if it's within root
+    targetPath = path.resolve(inputPath);
+  } else {
+    // Relative path - resolve from workspace root
+    targetPath = path.resolve(normalizedRoot, inputPath);
+  }
+
+  // Normalize both paths for comparison
+  const normalizedTarget = path.normalize(targetPath);
+  const normalizedRootWithSep = normalizedRoot.endsWith(path.sep)
+    ? normalizedRoot
+    : normalizedRoot + path.sep;
+
+  // Check if target is within workspace root
+  if (!normalizedTarget.startsWith(normalizedRootWithSep) && normalizedTarget !== normalizedRoot) {
+    return {
+      valid: false,
+      error: `Path escapes workspace root: ${inputPath}`,
+      errorCode: 'ABSOLUTE_PATH_OUTSIDE_ROOT',
+    };
+  }
+
+  // Check for symlink escape (if the path exists)
+  try {
+    if (fs.existsSync(targetPath)) {
+      const realPath = fs.realpathSync(targetPath);
+      const normalizedRealPath = path.normalize(realPath);
+
+      if (
+        !normalizedRealPath.startsWith(normalizedRootWithSep) &&
+        normalizedRealPath !== normalizedRoot
+      ) {
+        return {
+          valid: false,
+          error: `Symlink escape detected: ${inputPath} resolves to ${realPath}`,
+          errorCode: 'SYMLINK_ESCAPE',
+        };
+      }
+    }
+  } catch {
+    // If we can't check realpath, allow it (file may not exist yet)
+  }
+
+  // Get relative path for exclusion checking
+  const relativePath = path.relative(normalizedRoot, normalizedTarget);
+
+  // Check against allowlist first (allowlist overrides exclusions)
+  if (config.allowlist && matchesGlob(relativePath, config.allowlist)) {
+    return {
+      valid: true,
+      resolvedPath: normalizedTarget,
+    };
+  }
+
+  // Check against exclusions
+  const activeExclusions = getActiveExclusions(config);
+  if (matchesGlob(relativePath, activeExclusions)) {
+    return {
+      valid: false,
+      error: `Path is excluded: ${relativePath}`,
+      errorCode: 'EXCLUDED_PATH',
+    };
+  }
+
+  return {
+    valid: true,
+    resolvedPath: normalizedTarget,
+  };
+}
+
+/**
+ * Validates multiple paths at once.
+ *
+ * @param inputPaths - Array of paths to validate
+ * @param config - Sandbox configuration
+ * @returns Object with overall validity and individual results
+ */
+export function validateSandboxPaths(
+  inputPaths: string[],
+  config: SandboxConfig
+): {
+  valid: boolean;
+  results: Map<string, SandboxResult>;
+  errors: string[];
+} {
+  const results = new Map<string, SandboxResult>();
+  const errors: string[] = [];
+
+  for (const inputPath of inputPaths) {
+    const result = resolveSandboxPath(inputPath, config);
+    results.set(inputPath, result);
+
+    if (!result.valid && result.error) {
+      errors.push(result.error);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    results,
+    errors,
+  };
+}
+
+/**
+ * Creates a sandbox-safe path resolver bound to a specific config.
+ * Useful for creating a resolver that can be reused multiple times.
+ *
+ * @param config - Sandbox configuration
+ * @returns A function that resolves paths within the sandbox
+ */
+export function createSandboxResolver(config: SandboxConfig) {
+  return (inputPath: string): SandboxResult => {
+    return resolveSandboxPath(inputPath, config);
+  };
+}
+
+/**
+ * RunRequest interface for config overrides.
+ * This matches the expected interface from tool requests.
+ */
+export interface RunRequest {
+  /** Path to resolve */
+  path?: string;
+  /** Paths to resolve */
+  paths?: string[];
+  /** Project path / workspace root */
+  projectPath?: string;
+  /** Include third-party directories (node_modules, venv) */
+  includeThirdParty?: boolean;
+  /** Include generated directories (dist, build, .next) */
+  includeGenerated?: boolean;
+}
+
+/**
+ * Creates a SandboxConfig from a RunRequest.
+ *
+ * @param request - The run request with optional overrides
+ * @param defaultRoot - Default workspace root if not in request
+ * @returns SandboxConfig ready for use
+ */
+export function configFromRunRequest(request: RunRequest, defaultRoot: string): SandboxConfig {
+  return {
+    workspaceRoot: request.projectPath || defaultRoot,
+    includeThirdParty: request.includeThirdParty ?? false,
+    includeGenerated: request.includeGenerated ?? false,
+  };
+}
+
+/**
+ * Validates a path from a RunRequest, applying config overrides.
+ *
+ * @param request - The run request containing path and overrides
+ * @param defaultRoot - Default workspace root
+ * @returns SandboxResult
+ */
+export function validateRunRequest(request: RunRequest, defaultRoot: string): SandboxResult {
+  const config = configFromRunRequest(request, defaultRoot);
+
+  if (request.path) {
+    return resolveSandboxPath(request.path, config);
+  }
+
+  if (request.paths && request.paths.length > 0) {
+    const multiResult = validateSandboxPaths(request.paths, config);
+    if (!multiResult.valid) {
+      return {
+        valid: false,
+        error: multiResult.errors.join('; '),
+        errorCode: 'TRAVERSAL_DETECTED', // Use first error type
+      };
+    }
+    return { valid: true };
+  }
+
+  // No path specified
+  return { valid: true };
+}

package/mcp-server/lib/types.ts

@@ -0,0 +1,267 @@
+/**
+ * Shared types for MCP tool handler system
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REQUEST/RESPONSE TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface RunRequest {
+  /** Unique request identifier for tracing */
+  requestId: string;
+  /** Optional trace ID for distributed tracing */
+  traceId?: string;
+  /** Tool name to execute */
+  tool: string;
+  /** Tool arguments */
+  args: Record<string, unknown>;
+  /** User context */
+  context?: RequestContext;
+}
+
+export interface RequestContext {
+  /** User's subscription tier */
+  tier?: "free" | "pro";
+  /** User ID for audit */
+  userId?: string;
+  /** Project root path */
+  projectRoot?: string;
+  /** API key (hashed) */
+  apiKeyHash?: string;
+}
+
+export interface RunResponse {
+  /** Request ID echo */
+  requestId: string;
+  /** Trace ID echo */
+  traceId?: string;
+  /** Success indicator */
+  ok: boolean;
+  /** Result data (on success) */
+  data?: ToolResult;
+  /** Error envelope (on failure) */
+  error?: ErrorEnvelope;
+  /** Execution metadata */
+  metadata: ResponseMetadata;
+}
+
+export interface ResponseMetadata {
+  /** Execution start time (ISO) */
+  startedAt: string;
+  /** Execution end time (ISO) */
+  completedAt: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Tool that was executed */
+  tool: string;
+  /** CLI command that was executed (if applicable) */
+  cliCommand?: string;
+  /** Exit code from CLI */
+  exitCode?: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ERROR ENVELOPE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface ErrorEnvelope {
+  /** Error code for programmatic handling */
+  code: ErrorCode;
+  /** Human-readable message */
+  message: string;
+  /** Suggested next steps */
+  nextSteps?: string[];
+  /** Evidence/receipt (file:line) */
+  receipt?: string;
+  /** Validation errors (for INPUT_VALIDATION) */
+  validationErrors?: ValidationError[];
+  /** Request ID for support */
+  requestId?: string;
+  /** User action to resolve (for tier errors) */
+  userAction?: string;
+  /** Whether the operation can be retried */
+  retryable?: boolean;
+  /** Current user tier (for tier errors) */
+  tier?: string;
+  /** Required tier (for tier errors) */
+  required?: string;
+  /** Tool name (for tier errors) */
+  tool?: string;
+  /** Blocked option (for option-level gates) */
+  option?: string;
+  /** Upgrade URL */
+  upgradeUrl?: string;
+}
+
+export type ErrorCode =
+  | "INPUT_VALIDATION"
+  | "TOOL_NOT_FOUND"
+  | "TIER_REQUIRED"
+  | "NOT_ENTITLED"          // Tool requires higher tier
+  | "OPTION_NOT_ENTITLED"   // Specific option requires higher tier
+  | "PATH_VIOLATION"
+  | "EXECUTOR_FAILED"
+  | "OUTPUT_PARSE_ERROR"
+  | "OUTPUT_VALIDATION"
+  | "TIMEOUT"
+  | "INTERNAL_ERROR"
+  | "INVALID_API_KEY"
+  | "RATE_LIMITED";
+
+export interface ValidationError {
+  /** JSON path to the invalid field */
+  path: string;
+  /** Error message */
+  message: string;
+  /** Expected value/type */
+  expected?: string;
+  /** Actual value/type */
+  actual?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL REGISTRY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface ToolDefinition {
+  /** Tool name (unique identifier) */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Subscription tier required */
+  tier: "free" | "pro";
+  /** Tool category */
+  category: ToolCategory;
+  /** JSON Schema for input validation */
+  inputSchema: JsonSchema;
+  /** JSON Schema for output validation */
+  outputSchema: JsonSchema;
+  /** CLI command mapping */
+  cli: CliMapping;
+  /** Tool aliases */
+  aliases?: string[];
+  /** Related tools */
+  related?: string[];
+}
+
+export type ToolCategory =
+  | "scan"
+  | "proof"
+  | "authority"
+  | "report"
+  | "setup"
+  | "account"
+  | "conductor"
+  | "firewall";
+
+export interface CliMapping {
+  /** CLI command to execute */
+  command: string;
+  /** Argument mapping: { inputField: "--flag" } */
+  argMap: Record<string, string>;
+  /** Fixed flags always passed */
+  fixedFlags?: string[];
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+}
+
+export interface JsonSchema {
+  type: string;
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+export interface JsonSchemaProperty {
+  type: string;
+  description?: string;
+  default?: unknown;
+  enum?: unknown[];
+  items?: JsonSchemaProperty;
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL RESULT (CANONICAL OUTPUT)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface ToolResult {
+  /** Verdict (for scan/ship tools) */
+  verdict?: "SHIP" | "WARN" | "BLOCK" | "PASS" | "FAIL";
+  /** Findings list */
+  findings?: Finding[];
+  /** Summary statistics */
+  summary?: ResultSummary;
+  /** Raw output (if applicable) */
+  raw?: unknown;
+}
+
+export interface Finding {
+  /** Stable finding ID: sha256(rule_id + path + line + message) */
+  id: string;
+  /** Rule that generated this finding */
+  ruleId: string;
+  /** Severity level */
+  severity: "critical" | "high" | "medium" | "low" | "info";
+  /** Finding message */
+  message: string;
+  /** File path (relative to project root) */
+  path: string;
+  /** Line number (1-based) */
+  line: number;
+  /** Column number (1-based, optional) */
+  column?: number;
+  /** Code snippet */
+  snippet?: string;
+  /** Finding category */
+  category?: string;
+  /** Suggested fix */
+  fix?: string;
+}
+
+export interface ResultSummary {
+  /** Total findings count */
+  total: number;
+  /** Findings by severity */
+  bySeverity: Record<string, number>;
+  /** Findings by category */
+  byCategory?: Record<string, number>;
+  /** Files scanned */
+  filesScanned?: number;
+  /** Duration of scan */
+  scanDurationMs?: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXECUTOR TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface ExecutorOptions {
+  /** Working directory */
+  cwd: string;
+  /** Timeout in milliseconds */
+  timeoutMs: number;
+  /** Environment variables to pass */
+  env?: Record<string, string>;
+  /** Request ID for logging */
+  requestId: string;
+  /** Trace ID for logging */
+  traceId?: string;
+}
+
+export interface ExecutorResult {
+  /** Exit code */
+  exitCode: number;
+  /** Stdout content */
+  stdout: string;
+  /** Stderr content */
+  stderr: string;
+  /** Whether command timed out */
+  timedOut: boolean;
+  /** Execution duration in ms */
+  durationMs: number;
+}

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibecheck-mcp-server",
-  "version": "3.5.0",
+  "version": "3.6.1",
   "description": "Professional MCP server for vibecheck - Intelligent development environment vibechecks",
   "type": "module",
   "main": "index.js",
@@ -9,7 +9,10 @@
   },
   "scripts": {
     "start": "node index.js",
-    "dev": "VIBECHECK_DEBUG=true node index.js"
+    "dev": "VIBECHECK_DEBUG=true node index.js",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "mcp",
@@ -21,7 +24,13 @@
     "architecture"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ajv": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
   },
   "engines": {
     "node": ">=20.11"