apple-tools-mcp 1.0.0

package/lib/validators.js

@@ -0,0 +1,432 @@
+/**
+ * Security validation and escaping utilities for apple-tools-mcp
+ *
+ * This module centralizes input validation to prevent:
+ * - Path traversal attacks
+ * - Command injection
+ * - SQL injection
+ * - Integer overflow
+ */
+
+import path from "path";
+import fs from "fs";
+
+// ============ PATH VALIDATION ============
+
+/**
+ * Validates that a file path is within an allowed directory and has expected extension
+ * Prevents path traversal attacks like "../../../etc/passwd"
+ *
+ * @param {string} filePath - The path to validate
+ * @param {string} allowedDir - The directory the path must be within
+ * @param {string[]} allowedExtensions - Array of allowed extensions (e.g., ['.emlx'])
+ * @returns {string} The resolved, validated path
+ * @throws {Error} If validation fails
+ */
+export function validateFilePath(filePath, allowedDir, allowedExtensions = []) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('File path is required');
+  }
+
+  // Check extension if specified
+  if (allowedExtensions.length > 0) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (!allowedExtensions.includes(ext)) {
+      throw new Error(`Invalid file extension. Allowed: ${allowedExtensions.join(', ')}`);
+    }
+  }
+
+  // Resolve to absolute path (handles ../ etc)
+  const resolvedPath = path.resolve(filePath);
+  const resolvedAllowedDir = path.resolve(allowedDir);
+
+  // Ensure the resolved path starts with the allowed directory
+  if (!resolvedPath.startsWith(resolvedAllowedDir + path.sep) && resolvedPath !== resolvedAllowedDir) {
+    throw new Error('Access denied: path outside allowed directory');
+  }
+
+  return resolvedPath;
+}
+
+/**
+ * Validates an email file path specifically
+ * @param {string} filePath - The email file path
+ * @param {string} mailDir - The Mail directory (usually ~/Library/Mail)
+ * @returns {string} The validated path
+ */
+export function validateEmailPath(filePath, mailDir) {
+  return validateFilePath(filePath, mailDir, ['.emlx']);
+}
+
+// ============ NUMERIC VALIDATION ============
+
+/**
+ * Validates and constrains a limit parameter
+ * Prevents integer overflow and excessively large queries
+ *
+ * @param {any} value - The value to validate
+ * @param {number} defaultValue - Default if invalid (default: 30)
+ * @param {number} max - Maximum allowed value (default: 1000)
+ * @returns {number} A safe integer within bounds
+ */
+export function validateLimit(value, defaultValue = 30, max = 1000) {
+  const parsed = parseInt(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return defaultValue;
+  }
+  return Math.min(parsed, max);
+}
+
+/**
+ * Validates a days_back parameter
+ * @param {any} value - The value to validate
+ * @param {number} max - Maximum days back (default: 3650 = ~10 years)
+ * @returns {number} A safe integer >= 0
+ */
+export function validateDaysBack(value, max = 3650) {
+  const parsed = parseInt(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return 0;
+  }
+  return Math.min(parsed, max);
+}
+
+/**
+ * Validates a week offset parameter
+ * @param {any} value - The value to validate
+ * @param {number} max - Maximum weeks ahead (default: 52)
+ * @returns {number} A safe integer >= 0
+ */
+export function validateWeekOffset(value, max = 52) {
+  const parsed = parseInt(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return 0;
+  }
+  return Math.min(parsed, max);
+}
+
+// ============ STRING ESCAPING ============
+
+/**
+ * Escapes a string for use in AppleScript double-quoted strings
+ * Prevents AppleScript injection attacks
+ *
+ * @param {string} str - The string to escape
+ * @returns {string} Escaped string safe for AppleScript
+ */
+export function escapeAppleScript(str) {
+  if (!str || typeof str !== 'string') {
+    return '';
+  }
+  // Escape backslashes first, then double quotes
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"');
+}
+
+/**
+ * Validates a mailbox name for use in AppleScript
+ * Only allows safe characters to prevent injection
+ *
+ * @param {string} mailbox - The mailbox name
+ * @returns {string|null} Validated mailbox name or null if invalid
+ */
+export function validateMailboxName(mailbox) {
+  if (!mailbox || typeof mailbox !== 'string') {
+    return null;
+  }
+
+  // Only allow alphanumeric, spaces, hyphens, underscores, and periods
+  // This prevents any AppleScript injection
+  if (!/^[a-zA-Z0-9\s\-_.]+$/.test(mailbox)) {
+    return null;
+  }
+
+  // Also limit length
+  if (mailbox.length > 100) {
+    return null;
+  }
+
+  return mailbox;
+}
+
+/**
+ * Escapes a string for use in SQL single-quoted strings
+ * Note: Prefer parameterized queries when possible
+ *
+ * @param {string} str - The string to escape
+ * @returns {string} Escaped string safe for SQL
+ */
+export function escapeSQL(str) {
+  if (!str || typeof str !== 'string') {
+    return '';
+  }
+  // Double single quotes and escape backslashes
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "''");
+}
+
+/**
+ * Validates and sanitizes an ID string for LanceDB queries
+ * @param {string} id - The ID to validate
+ * @returns {string|null} Validated ID or null if invalid
+ */
+export function validateLanceDBId(id) {
+  if (!id || typeof id !== 'string') {
+    return null;
+  }
+
+  // IDs should only contain safe characters
+  // Allow alphanumeric, spaces, hyphens, colons, commas, periods
+  if (!/^[a-zA-Z0-9\s\-:,.]+$/.test(id)) {
+    return null;
+  }
+
+  // Limit length
+  if (id.length > 500) {
+    return null;
+  }
+
+  return id;
+}
+
+// ============ SEARCH QUERY VALIDATION ============
+
+/**
+ * Validates a search query string
+ * @param {string} query - The search query
+ * @param {number} maxLength - Maximum allowed length (default: 1000)
+ * @returns {string} Validated query
+ * @throws {Error} If query is invalid
+ */
+export function validateSearchQuery(query, maxLength = 1000) {
+  if (!query || typeof query !== 'string') {
+    throw new Error('Search query is required');
+  }
+
+  const trimmed = query.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Search query cannot be empty');
+  }
+
+  if (trimmed.length > maxLength) {
+    return trimmed.substring(0, maxLength);
+  }
+
+  return trimmed;
+}
+
+/**
+ * Validates a contact/name string
+ * @param {string} contact - The contact name or identifier
+ * @param {number} maxLength - Maximum length (default: 200)
+ * @returns {string|null} Validated contact or null
+ */
+export function validateContact(contact, maxLength = 200) {
+  if (!contact || typeof contact !== 'string') {
+    return null;
+  }
+
+  const trimmed = contact.trim();
+  if (trimmed.length === 0 || trimmed.length > maxLength) {
+    return null;
+  }
+
+  return trimmed;
+}
+
+// ============ DATE VALIDATION ============
+
+/**
+ * Validates a date string or timestamp
+ * @param {string|number} date - The date to validate
+ * @returns {Date|null} Validated Date object or null
+ */
+export function validateDate(date) {
+  if (!date) {
+    return null;
+  }
+
+  try {
+    const d = new Date(date);
+    if (isNaN(d.getTime())) {
+      return null;
+    }
+
+    // Sanity check: date should be between year 1990 and 2100
+    const year = d.getFullYear();
+    if (year < 1990 || year > 2100) {
+      return null;
+    }
+
+    return d;
+  } catch {
+    return null;
+  }
+}
+
+// ============ ENVIRONMENT VALIDATION ============
+
+/**
+ * Gets a validated home directory path
+ * @returns {string} The home directory
+ * @throws {Error} If HOME is invalid
+ */
+export function getValidatedHome() {
+  const home = process.env.HOME;
+
+  if (!home || typeof home !== 'string') {
+    throw new Error('HOME environment variable is not set');
+  }
+
+  // Ensure it's an absolute path
+  if (!path.isAbsolute(home)) {
+    throw new Error('HOME must be an absolute path');
+  }
+
+  // Ensure it exists and is a directory
+  try {
+    const stats = fs.statSync(home);
+    if (!stats.isDirectory()) {
+      throw new Error('HOME is not a directory');
+    }
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      throw new Error('HOME directory does not exist');
+    }
+    throw e;
+  }
+
+  return home;
+}
+
+// ============ REGEX SAFETY ============
+
+/**
+ * Escapes special regex characters in a string
+ * Prevents ReDoS when using user input in regex patterns
+ *
+ * @param {string} str - The string to escape
+ * @returns {string} Escaped string safe for use in RegExp
+ */
+export function escapeRegex(str) {
+  if (!str || typeof str !== 'string') {
+    return '';
+  }
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Safely execute a regex match with input length limits
+ * Prevents ReDoS by limiting input size
+ *
+ * @param {string} input - The input string to match against
+ * @param {RegExp} pattern - The regex pattern
+ * @param {number} maxLength - Maximum input length (default: 10000)
+ * @returns {RegExpMatchArray|null} Match result or null
+ */
+export function safeMatch(input, pattern, maxLength = 10000) {
+  if (!input || typeof input !== 'string') {
+    return null;
+  }
+  // Truncate overly long inputs to prevent ReDoS
+  const safeInput = input.length > maxLength ? input.substring(0, maxLength) : input;
+  try {
+    return safeInput.match(pattern);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safely execute a regex replace with input length limits
+ *
+ * @param {string} input - The input string
+ * @param {RegExp|string} pattern - The regex pattern or string
+ * @param {string|Function} replacement - The replacement string or function
+ * @param {number} maxLength - Maximum input length (default: 50000)
+ * @returns {string} Replaced string
+ */
+export function safeReplace(input, pattern, replacement, maxLength = 50000) {
+  if (!input || typeof input !== 'string') {
+    return '';
+  }
+  // Truncate overly long inputs
+  const safeInput = input.length > maxLength ? input.substring(0, maxLength) : input;
+  try {
+    return safeInput.replace(pattern, replacement);
+  } catch {
+    return safeInput;
+  }
+}
+
+/**
+ * Strip HTML tags safely without ReDoS vulnerability
+ * Uses iterative approach instead of complex regex
+ *
+ * @param {string} html - The HTML string
+ * @param {number} maxLength - Maximum input length (default: 100000)
+ * @returns {string} Text with HTML tags removed
+ */
+export function stripHtmlTags(html, maxLength = 100000) {
+  if (!html || typeof html !== 'string') {
+    return '';
+  }
+
+  // Truncate overly long inputs
+  let text = html.length > maxLength ? html.substring(0, maxLength) : html;
+
+  // Simple state machine approach - more predictable than regex
+  let result = '';
+  let inTag = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (char === '<') {
+      inTag = true;
+    } else if (char === '>') {
+      inTag = false;
+      result += ' '; // Replace tag with space
+    } else if (!inTag) {
+      result += char;
+    }
+  }
+
+  // Normalize whitespace
+  return result.replace(/\s+/g, ' ').trim();
+}
+
+// ============ DATE UTILITIES ============
+
+/**
+ * Mac Absolute Time epoch constant
+ * Mac epoch is January 1, 2001 00:00:00 UTC
+ * Unix epoch is January 1, 1970 00:00:00 UTC
+ * Difference is 978307200 seconds
+ */
+const MAC_ABSOLUTE_EPOCH = 978307200;
+
+/**
+ * Convert Mac Absolute Time to Unix timestamp (milliseconds)
+ * Handles both seconds and nanoseconds formats
+ *
+ * @param {number} macTime - Mac absolute time value
+ * @returns {number} Unix timestamp in milliseconds
+ */
+export function macAbsoluteTimeToDate(macTime) {
+  if (macTime === null || macTime === undefined || isNaN(macTime)) {
+    return 0;
+  }
+
+  let seconds = macTime;
+
+  // Detect nanoseconds (Messages database uses nanoseconds)
+  // If the value is larger than reasonable for seconds (> year 3000), assume nanoseconds
+  if (macTime > 50000000000) {
+    seconds = macTime / 1e9;
+  }
+
+  // Convert to Unix timestamp (milliseconds)
+  return (seconds + MAC_ABSOLUTE_EPOCH) * 1000;
+}

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "apple-tools-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for semantic search across Apple Mail, Messages, and Calendar",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "apple-tools-mcp": "./index.js"
+  },
+  "author": "Peter Coates",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sfls1397/apple-tools-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sfls1397/apple-tools-mcp/issues"
+  },
+  "homepage": "https://github.com/sfls1397/apple-tools-mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "apple",
+    "mail",
+    "email",
+    "calendar",
+    "messages",
+    "imessage",
+    "semantic-search",
+    "claude",
+    "anthropic",
+    "macos"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "indexer.js",
+    "search.js",
+    "contacts.js",
+    "lib/",
+    "scripts/audit-index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "build-index": "APPLE_TOOLS_INDEX_DAYS_BACK=30 node -e \"import('./indexer.js').then(i=>i.rebuildIndex()).catch(e=>{console.error(e.message);process.exit(1)})\"",
+    "audit": "APPLE_TOOLS_INDEX_DAYS_BACK=30 node scripts/audit-index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:integration:periodic": "vitest run tests/integration/periodic-indexing-e2e.test.js --reporter=verbose",
+    "test:perf": "vitest run tests/performance",
+    "test:fuzz": "vitest run tests/fuzz",
+    "test:chaos": "vitest run tests/chaos",
+    "test:contract": "vitest run tests/contract",
+    "test:concurrency": "vitest run tests/concurrency",
+    "test:recovery": "vitest run tests/recovery",
+    "test:timezone": "vitest run tests/timezone",
+    "test:stress": "vitest run tests/stress",
+    "test:snapshot": "vitest run tests/snapshots",
+    "test:all": "vitest run",
+    "test:idx": "vitest run tests/indexing",
+    "test:idx:unit": "vitest run tests/indexing/unit",
+    "test:idx:integration": "vitest run tests/indexing/integration",
+    "test:idx:accuracy": "vitest run tests/indexing/accuracy",
+    "test:idx:perf": "vitest run tests/indexing/performance",
+    "test:idx:resource": "vitest run tests/indexing/resource",
+    "test:idx:edge": "vitest run tests/indexing/edge-cases",
+    "test:idx:security": "vitest run tests/indexing/security",
+    "test:idx:contacts": "vitest run tests/indexing/contacts",
+    "test:idx:cache": "vitest run tests/indexing/caching",
+    "test:idx:negative": "vitest run tests/indexing/negative",
+    "test:idx:watch": "vitest tests/indexing",
+    "test:idx:build": "node scripts/build-test-index.js",
+    "test:idx:clean": "node scripts/clean-test-index.js",
+    "perf": "USE_REAL_DATA=1 vitest run tests/perf --reporter=verbose",
+    "perf:mock": "vitest run tests/perf --reporter=verbose",
+    "perf:watch": "USE_REAL_DATA=1 vitest tests/perf",
+    "perf:indexing": "vitest run tests/perf/indexing.perf.test.js --reporter=verbose",
+    "perf:search": "vitest run tests/perf/search.perf.test.js --reporter=verbose",
+    "perf:tools": "vitest run tests/perf/tools.perf.test.js --reporter=verbose",
+    "perf:server": "vitest run tests/perf/mcp-server.perf.test.js --reporter=verbose",
+    "perf:embedding": "vitest run tests/perf/embedding.perf.test.js --reporter=verbose",
+    "perf:datasources": "vitest run tests/perf/datasources.perf.test.js --reporter=verbose",
+    "perf:memory": "vitest run tests/perf/memory.perf.test.js --reporter=verbose",
+    "perf:stress": "vitest run tests/perf/stress.perf.test.js --reporter=verbose --testTimeout=120000",
+    "perf:mail": "vitest run tests/perf/datasources.perf.test.js -t 'Email' --reporter=verbose",
+    "perf:messages": "vitest run tests/perf/datasources.perf.test.js -t 'Messages' --reporter=verbose",
+    "perf:calendar": "vitest run tests/perf/datasources.perf.test.js -t 'Calendar' --reporter=verbose",
+    "perf:contacts": "vitest run tests/perf/datasources.perf.test.js -t 'Contacts' --reporter=verbose",
+    "perf:quick": "vitest run tests/perf/tools.perf.test.js tests/perf/search.perf.test.js --reporter=verbose",
+    "perf:negative": "vitest run tests/perf/negative.perf.test.js --reporter=verbose",
+    "perf:edge-cases": "vitest run tests/perf/edge-cases.perf.test.js --reporter=verbose",
+    "perf:regression": "vitest run tests/perf/regression.perf.test.js --reporter=verbose",
+    "perf:lancedb": "vitest run tests/perf/lancedb.perf.test.js --reporter=verbose",
+    "perf:background": "vitest run tests/perf/background-indexing.perf.test.js --reporter=verbose",
+    "perf:dates": "vitest run tests/perf/date-parsing.perf.test.js --reporter=verbose",
+    "perf:full": "vitest run tests/perf --reporter=verbose --testTimeout=120000"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "^0.22.3",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@xenova/transformers": "^2.17.2",
+    "chrono-node": "^2.9.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.14",
+    "fast-check": "^3.15.0",
+    "vitest": "^4.0.14"
+  }
+}

package/scripts/audit-index.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * CLI Script for Auditing Index
+ *
+ * Usage:
+ *   node scripts/audit-index.js
+ *   node scripts/audit-index.js --sources emails,messages
+ *   node scripts/audit-index.js --max-items 50
+ *   node scripts/audit-index.js --sources calendar --max-items 0
+ */
+
+import { auditAll, formatAuditReport } from '../lib/audit.js';
+
+// Parse command-line arguments
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    sources: ['emails', 'messages', 'calendar'],
+    maxItems: 100
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--sources' && i + 1 < args.length) {
+      options.sources = args[i + 1].split(',').map(s => s.trim());
+      i++;
+    } else if (arg === '--max-items' && i + 1 < args.length) {
+      options.maxItems = parseInt(args[i + 1], 10);
+      i++;
+    } else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`
+Audit Index - Check index integrity against source data
+
+Usage:
+  npm run audit
+  npm run audit -- --sources emails,messages
+  npm run audit -- --max-items 50
+  npm run audit -- --sources calendar --max-items 0
+
+Options:
+  --sources <list>    Comma-separated list of sources to audit
+                      Options: emails, messages, calendar
+                      Default: emails,messages,calendar
+
+  --max-items <num>   Maximum items to show per discrepancy category
+                      Use 0 for unlimited
+                      Default: 100
+
+  --help, -h          Show this help message
+
+Examples:
+  npm run audit                                    # Audit all sources
+  npm run audit -- --sources emails                # Audit emails only
+  npm run audit -- --sources emails,messages       # Audit emails and messages
+  npm run audit -- --max-items 50                  # Show max 50 items per category
+  npm run audit -- --sources calendar --max-items 0  # Show all calendar discrepancies
+`);
+}
+
+// Main execution
+async function main() {
+  try {
+    const options = parseArgs();
+
+    console.error('Starting index audit...');
+    console.error(`Sources: ${options.sources.join(', ')}`);
+    console.error(`Max items per category: ${options.maxItems === 0 ? 'unlimited' : options.maxItems}`);
+    console.error('');
+
+    const results = await auditAll(options);
+    const report = formatAuditReport(results);
+
+    // Print report to stdout
+    console.log(report);
+
+  } catch (error) {
+    console.error('Error running audit:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+main();