@girardmedia/bootspring 2.2.0 → 2.2.1

package/core/validation.js

@@ -1,572 +0,0 @@
-/**
- * CLI Input Validation Module
- * Comprehensive validation for CLI arguments and user input.
- *
- * @module core/validation
- */
-
-const path = require('path');
-const fs = require('fs');
-
-/**
- * Default limits for validation
- */
-const LIMITS = {
-  MAX_STRING_LENGTH: 1000,
-  MAX_PATH_LENGTH: 4096,
-  MAX_FILENAME_LENGTH: 255,
-  MAX_TODO_LENGTH: 500,
-  MAX_PROJECT_NAME_LENGTH: 100,
-  MAX_DESCRIPTION_LENGTH: 2000,
-  MIN_ID: 1,
-  MAX_ID: Number.MAX_SAFE_INTEGER,
-  MAX_ARRAY_LENGTH: 1000
-};
-
-/**
- * Patterns for validation
- */
-const PATTERNS = {
-  // Safe project names: alphanumeric, hyphens, underscores
-  PROJECT_NAME: /^[a-zA-Z][a-zA-Z0-9_-]*$/,
-  // Safe filenames: path separators and null bytes are checked separately
-  SAFE_FILENAME: /^[^:*?"<>|]+$/,
-  // Slug format: lowercase, hyphens only
-  SLUG: /^[a-z][a-z0-9-]*$/,
-  // Numeric ID
-  NUMERIC_ID: /^\d+$/,
-  // Email format (basic)
-  EMAIL: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-  // URL format (basic)
-  URL: /^https?:\/\/[^\s]+$/
-};
-
-/**
- * Characters that should be escaped or rejected in shell contexts
- */
-const SHELL_DANGEROUS_CHARS = /[;&|`$(){}[\]<>\\!#*?"'\n\r\t]/;
-
-function stripUnsafeControlChars(value, options = {}) {
-  const { allowTabs = false, allowNewlines = false } = options;
-  let sanitized = '';
-
-  for (const char of value) {
-    const code = char.charCodeAt(0);
-    const isLineBreak = code === 0x0A || code === 0x0D;
-    const isTab = code === 0x09;
-    const isControl = (code >= 0x00 && code <= 0x1F) || code === 0x7F;
-
-    if (!isControl) {
-      sanitized += char;
-      continue;
-    }
-
-    if (isLineBreak && allowNewlines) {
-      sanitized += char;
-      continue;
-    }
-
-    if (isTab && allowTabs) {
-      sanitized += char;
-    }
-  }
-
-  return sanitized;
-}
-
-/**
- * Validate string length
- * @param {string} value - Value to validate
- * @param {number} [maxLength] - Maximum length (default: 1000)
- * @param {number} [minLength] - Minimum length (default: 0)
- * @returns {{ valid: boolean, error?: string, sanitized?: string }}
- */
-function validateStringLength(value, maxLength = LIMITS.MAX_STRING_LENGTH, minLength = 0) {
-  if (typeof value !== 'string') {
-    return { valid: false, error: 'Value must be a string' };
-  }
-
-  if (value.length < minLength) {
-    return { valid: false, error: `String must be at least ${minLength} characters` };
-  }
-
-  if (value.length > maxLength) {
-    return {
-      valid: false,
-      error: `String exceeds maximum length of ${maxLength} characters`,
-      sanitized: value.slice(0, maxLength)
-    };
-  }
-
-  return { valid: true, sanitized: value };
-}
-
-/**
- * Validate and parse numeric ID
- * @param {string|number} value - Value to validate
- * @param {object} [options] - Options
- * @param {number} [options.min] - Minimum value
- * @param {number} [options.max] - Maximum value
- * @returns {{ valid: boolean, error?: string, value?: number }}
- */
-function validateNumericId(value, options = {}) {
-  const { min = LIMITS.MIN_ID, max = LIMITS.MAX_ID } = options;
-
-  // Handle string input
-  if (typeof value === 'string') {
-    if (!PATTERNS.NUMERIC_ID.test(value.trim())) {
-      return { valid: false, error: 'Invalid numeric ID format' };
-    }
-    value = parseInt(value.trim(), 10);
-  }
-
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    return { valid: false, error: 'Value must be a finite number' };
-  }
-
-  if (!Number.isInteger(value)) {
-    return { valid: false, error: 'Value must be an integer' };
-  }
-
-  if (value < min) {
-    return { valid: false, error: `Value must be at least ${min}` };
-  }
-
-  if (value > max) {
-    return { valid: false, error: `Value must be at most ${max}` };
-  }
-
-  return { valid: true, value };
-}
-
-/**
- * Validate project name
- * @param {string} name - Project name to validate
- * @returns {{ valid: boolean, error?: string, sanitized?: string }}
- */
-function validateProjectName(name) {
-  const lengthResult = validateStringLength(name, LIMITS.MAX_PROJECT_NAME_LENGTH, 1);
-  if (!lengthResult.valid) {
-    return lengthResult;
-  }
-
-  if (!PATTERNS.PROJECT_NAME.test(name)) {
-    // Try to sanitize
-    const sanitized = name
-      .toLowerCase()
-      .replace(/[^a-z0-9_-]/g, '-')
-      .replace(/^[^a-z]+/, '')
-      .replace(/-+/g, '-')
-      .replace(/-$/, '');
-
-    if (sanitized.length === 0) {
-      return { valid: false, error: 'Project name must start with a letter and contain only alphanumeric characters, hyphens, and underscores' };
-    }
-
-    return { valid: false, error: 'Invalid characters in project name', sanitized };
-  }
-
-  return { valid: true, sanitized: name };
-}
-
-/**
- * Validate filename (no path components)
- * @param {string} filename - Filename to validate
- * @returns {{ valid: boolean, error?: string, sanitized?: string }}
- */
-function validateFilename(filename) {
-  if (typeof filename !== 'string') {
-    return { valid: false, error: 'Filename must be a string' };
-  }
-
-  if (filename.length === 0) {
-    return { valid: false, error: 'Filename cannot be empty' };
-  }
-
-  if (filename.length > LIMITS.MAX_FILENAME_LENGTH) {
-    return { valid: false, error: `Filename exceeds maximum length of ${LIMITS.MAX_FILENAME_LENGTH} characters` };
-  }
-
-  // Check for path separators
-  if (filename.includes('/') || filename.includes('\\')) {
-    return { valid: false, error: 'Filename cannot contain path separators' };
-  }
-
-  // Check for null bytes
-  if (filename.includes('\x00')) {
-    return { valid: false, error: 'Filename contains invalid characters' };
-  }
-
-  // Check for reserved names (Windows compatibility)
-  const reserved = ['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', 'LPT1', 'LPT2', 'LPT3'];
-  if (reserved.includes(filename.toUpperCase().split('.')[0])) {
-    return { valid: false, error: 'Filename is a reserved name' };
-  }
-
-  // Check for hidden files starting with .
-  // (allowed but flagged)
-  const isHidden = filename.startsWith('.');
-
-  if (!PATTERNS.SAFE_FILENAME.test(filename)) {
-    const sanitized = filename.replace(/[:*?"<>|]/g, '_');
-    return { valid: false, error: 'Filename contains unsafe characters', sanitized };
-  }
-
-  return { valid: true, sanitized: filename, isHidden };
-}
-
-/**
- * Validate and canonicalize a file path
- * Prevents path traversal attacks by ensuring the resolved path
- * is within the allowed base directory.
- *
- * @param {string} inputPath - User-provided path
- * @param {string} baseDir - Base directory that path must be within
- * @param {object} [options] - Options
- * @param {boolean} [options.mustExist] - Path must exist
- * @param {boolean} [options.allowSymlinks] - Allow symbolic links
- * @returns {{ valid: boolean, error?: string, resolved?: string }}
- */
-function validatePath(inputPath, baseDir, options = {}) {
-  const { mustExist = false, allowSymlinks = false } = options;
-
-  if (typeof inputPath !== 'string') {
-    return { valid: false, error: 'Path must be a string' };
-  }
-
-  if (inputPath.length === 0) {
-    return { valid: false, error: 'Path cannot be empty' };
-  }
-
-  if (inputPath.length > LIMITS.MAX_PATH_LENGTH) {
-    return { valid: false, error: `Path exceeds maximum length of ${LIMITS.MAX_PATH_LENGTH} characters` };
-  }
-
-  // Check for null bytes (common path injection technique)
-  if (inputPath.includes('\x00')) {
-    return { valid: false, error: 'Path contains null bytes' };
-  }
-
-  // Resolve and normalize the path
-  const resolvedBase = path.resolve(baseDir);
-  const resolvedPath = path.resolve(baseDir, inputPath);
-
-  // Check that resolved path is within base directory
-  const relative = path.relative(resolvedBase, resolvedPath);
-  if (relative.startsWith('..') || path.isAbsolute(relative)) {
-    return { valid: false, error: 'Path traversal detected: path escapes base directory' };
-  }
-
-  // Check for symlinks if not allowed
-  if (!allowSymlinks && mustExist) {
-    try {
-      const stats = fs.lstatSync(resolvedPath);
-      if (stats.isSymbolicLink()) {
-        // Verify symlink target is also within bounds
-        const realPath = fs.realpathSync(resolvedPath);
-        const realRelative = path.relative(resolvedBase, realPath);
-        if (realRelative.startsWith('..') || path.isAbsolute(realRelative)) {
-          return { valid: false, error: 'Symlink target escapes base directory' };
-        }
-      }
-    } catch {
-      // Path doesn't exist, handled by mustExist check below
-    }
-  }
-
-  // Check existence if required
-  if (mustExist && !fs.existsSync(resolvedPath)) {
-    return { valid: false, error: 'Path does not exist' };
-  }
-
-  return { valid: true, resolved: resolvedPath };
-}
-
-/**
- * Validate command arguments for safe shell execution
- * @param {string[]} args - Arguments to validate
- * @returns {{ valid: boolean, error?: string, sanitized?: string[] }}
- */
-function validateCommandArgs(args) {
-  if (!Array.isArray(args)) {
-    return { valid: false, error: 'Arguments must be an array' };
-  }
-
-  if (args.length > LIMITS.MAX_ARRAY_LENGTH) {
-    return { valid: false, error: `Too many arguments (max: ${LIMITS.MAX_ARRAY_LENGTH})` };
-  }
-
-  const sanitized = [];
-  const warnings = [];
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-
-    if (typeof arg !== 'string') {
-      return { valid: false, error: `Argument at index ${i} must be a string` };
-    }
-
-    // Check for dangerous shell characters
-    if (SHELL_DANGEROUS_CHARS.test(arg)) {
-      warnings.push(`Argument at index ${i} contains shell metacharacters`);
-      // Don't reject, but warn - spawn() is safe, but log for audit
-    }
-
-    // Check length
-    if (arg.length > LIMITS.MAX_STRING_LENGTH) {
-      return { valid: false, error: `Argument at index ${i} exceeds maximum length` };
-    }
-
-    sanitized.push(arg);
-  }
-
-  return { valid: true, sanitized, warnings: warnings.length > 0 ? warnings : undefined };
-}
-
-/**
- * Validate todo text
- * @param {string} text - Todo text to validate
- * @returns {{ valid: boolean, error?: string, sanitized?: string }}
- */
-function validateTodoText(text) {
-  const result = validateStringLength(text, LIMITS.MAX_TODO_LENGTH, 1);
-  if (!result.valid) {
-    return result;
-  }
-
-  // Remove control characters except newlines
-  const sanitized = stripUnsafeControlChars(text, { allowNewlines: true });
-
-  return { valid: true, sanitized };
-}
-
-/**
- * Validate description text
- * @param {string} text - Description to validate
- * @returns {{ valid: boolean, error?: string, sanitized?: string }}
- */
-function validateDescription(text) {
-  const result = validateStringLength(text, LIMITS.MAX_DESCRIPTION_LENGTH, 0);
-  if (!result.valid) {
-    return result;
-  }
-
-  // Remove control characters except newlines and tabs
-  const sanitized = stripUnsafeControlChars(text, { allowTabs: true, allowNewlines: true });
-
-  return { valid: true, sanitized };
-}
-
-/**
- * Validate slug format
- * @param {string} slug - Slug to validate
- * @returns {{ valid: boolean, error?: string, sanitized?: string }}
- */
-function validateSlug(slug) {
-  if (typeof slug !== 'string') {
-    return { valid: false, error: 'Slug must be a string' };
-  }
-
-  const lengthResult = validateStringLength(slug, LIMITS.MAX_FILENAME_LENGTH, 1);
-  if (!lengthResult.valid) {
-    return lengthResult;
-  }
-
-  if (!PATTERNS.SLUG.test(slug)) {
-    const sanitized = slug
-      .toLowerCase()
-      .replace(/[^a-z0-9-]/g, '-')
-      .replace(/^[^a-z]+/, '')
-      .replace(/-+/g, '-')
-      .replace(/-$/, '');
-
-    if (sanitized.length === 0 || !PATTERNS.SLUG.test(sanitized)) {
-      return { valid: false, error: 'Invalid slug format' };
-    }
-
-    return { valid: false, error: 'Slug contains invalid characters', sanitized };
-  }
-
-  return { valid: true, sanitized: slug };
-}
-
-/**
- * Validate email format
- * @param {string} email - Email to validate
- * @returns {{ valid: boolean, error?: string }}
- */
-function validateEmail(email) {
-  if (typeof email !== 'string') {
-    return { valid: false, error: 'Email must be a string' };
-  }
-
-  if (email.length > 254) {
-    return { valid: false, error: 'Email exceeds maximum length' };
-  }
-
-  if (!PATTERNS.EMAIL.test(email)) {
-    return { valid: false, error: 'Invalid email format' };
-  }
-
-  return { valid: true };
-}
-
-/**
- * Validate URL format
- * @param {string} url - URL to validate
- * @returns {{ valid: boolean, error?: string }}
- */
-function validateUrl(url) {
-  if (typeof url !== 'string') {
-    return { valid: false, error: 'URL must be a string' };
-  }
-
-  if (url.length > LIMITS.MAX_STRING_LENGTH) {
-    return { valid: false, error: 'URL exceeds maximum length' };
-  }
-
-  if (!PATTERNS.URL.test(url)) {
-    return { valid: false, error: 'Invalid URL format' };
-  }
-
-  // Additional security check - no credentials in URL
-  try {
-    const parsed = new URL(url);
-    if (parsed.username || parsed.password) {
-      return { valid: false, error: 'URL cannot contain embedded credentials' };
-    }
-  } catch {
-    return { valid: false, error: 'Invalid URL format' };
-  }
-
-  return { valid: true };
-}
-
-/**
- * Validate array input
- * @param {Array} arr - Array to validate
- * @param {Function} [itemValidator] - Optional validator for each item
- * @param {object} [options] - Options
- * @param {number} [options.maxLength] - Maximum array length
- * @param {number} [options.minLength] - Minimum array length
- * @returns {{ valid: boolean, error?: string, sanitized?: Array }}
- */
-function validateArray(arr, itemValidator, options = {}) {
-  const { maxLength = LIMITS.MAX_ARRAY_LENGTH, minLength = 0 } = options;
-
-  if (!Array.isArray(arr)) {
-    return { valid: false, error: 'Value must be an array' };
-  }
-
-  if (arr.length < minLength) {
-    return { valid: false, error: `Array must have at least ${minLength} items` };
-  }
-
-  if (arr.length > maxLength) {
-    return { valid: false, error: `Array exceeds maximum length of ${maxLength} items` };
-  }
-
-  if (!itemValidator) {
-    return { valid: true, sanitized: arr };
-  }
-
-  const sanitized = [];
-  for (let i = 0; i < arr.length; i++) {
-    const result = itemValidator(arr[i]);
-    if (!result.valid) {
-      return { valid: false, error: `Item at index ${i}: ${result.error}` };
-    }
-    sanitized.push(result.sanitized !== undefined ? result.sanitized : arr[i]);
-  }
-
-  return { valid: true, sanitized };
-}
-
-/**
- * Create a validation chain for multiple validators
- * @param {Array<Function>} validators - Validators to run in sequence
- * @returns {Function} Combined validator
- */
-function chain(...validators) {
-  return (value) => {
-    let current = value;
-    for (const validator of validators) {
-      const result = validator(current);
-      if (!result.valid) {
-        return result;
-      }
-      if (result.sanitized !== undefined) {
-        current = result.sanitized;
-      }
-    }
-    return { valid: true, sanitized: current };
-  };
-}
-
-/**
- * Validate and sanitize user input with a schema
- * @param {object} input - Input object to validate
- * @param {object} schema - Validation schema
- * @returns {{ valid: boolean, errors?: string[], sanitized?: object }}
- */
-function validateInput(input, schema) {
-  if (typeof input !== 'object' || input === null) {
-    return { valid: false, errors: ['Input must be an object'] };
-  }
-
-  const errors = [];
-  const sanitized = {};
-
-  for (const [key, config] of Object.entries(schema)) {
-    const value = input[key];
-
-    // Check required
-    if (config.required && (value === undefined || value === null || value === '')) {
-      errors.push(`${key} is required`);
-      continue;
-    }
-
-    // Skip optional missing values
-    if (value === undefined || value === null) {
-      if (config.default !== undefined) {
-        sanitized[key] = config.default;
-      }
-      continue;
-    }
-
-    // Run validator
-    if (config.validator) {
-      const result = config.validator(value);
-      if (!result.valid) {
-        errors.push(`${key}: ${result.error}`);
-      } else {
-        sanitized[key] = result.sanitized !== undefined ? result.sanitized : value;
-      }
-    } else {
-      sanitized[key] = value;
-    }
-  }
-
-  return errors.length > 0
-    ? { valid: false, errors }
-    : { valid: true, sanitized };
-}
-
-module.exports = {
-  LIMITS,
-  PATTERNS,
-  validateStringLength,
-  validateNumericId,
-  validateProjectName,
-  validateFilename,
-  validatePath,
-  validateCommandArgs,
-  validateTodoText,
-  validateDescription,
-  validateSlug,
-  validateEmail,
-  validateUrl,
-  validateArray,
-  validateInput,
-  chain
-};

package/mcp/server.d.ts

@@ -1,57 +0,0 @@
-/**
- * Bootspring MCP Server Types
- * @module mcp
- */
-
-export interface ToolDefinition {
-  name: string;
-  description: string;
-  inputSchema: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-
-export interface ResourceDefinition {
-  uri: string;
-  name: string;
-  description: string;
-  mimeType: string;
-}
-
-export interface ToolResult {
-  content: Array<{
-    type: 'text';
-    text: string;
-  }>;
-  isError?: boolean;
-}
-
-export type ToolHandler = (args: Record<string, unknown>) => Promise<ToolResult>;
-export type ResourceHandler = () => Promise<{ contents: Array<{ uri: string; text: string; mimeType: string }> }>;
-
-/** Available MCP tools */
-export const TOOLS: ToolDefinition[];
-
-/** Available MCP resources */
-export const RESOURCES: ResourceDefinition[];
-
-/** Tool handlers by name */
-export const toolHandlers: Record<string, ToolHandler>;
-
-/** Resource handlers by URI */
-export const resourceHandlers: Record<string, ResourceHandler>;
-
-/**
- * Track telemetry event
- * @param event - Event name
- * @param data - Event data
- */
-export function trackTelemetry(event: string, data?: Record<string, unknown>): void;
-
-/**
- * Start the MCP server
- * Connects to stdio transport and handles tool/resource requests
- */
-export function main(): Promise<void>;