@iflow-mcp/attio-mcp 1.3.6

package/dist/utils/config-loader.js

@@ -0,0 +1,255 @@
+/**
+ * Configuration loader for Attio MCP Server
+ * Handles loading and merging of configuration files
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createScopedLogger } from './logger.js';
+import { DANGEROUS_KEYS } from './security-constants.js';
+/**
+ * Default paths for configuration files
+ */
+const CONFIG_PATHS = {
+    default: path.resolve(process.cwd(), 'configs/runtime/mappings/default.json'),
+    user: path.resolve(process.cwd(), 'configs/runtime/mappings/user.json'),
+};
+/**
+ * Cached mapping configuration to avoid repeated disk I/O
+ * @see loadMappingConfig() is called on every tool request via canonicalizeResourceType()
+ */
+let cachedConfig = null;
+/**
+ * Invalidates the cached mapping configuration
+ * Call this when the config files are updated (e.g., after attio-discover)
+ */
+export function invalidateMappingConfigCache() {
+    cachedConfig = null;
+}
+/**
+ * Validates that a key is safe for object property assignment
+ * Prevents prototype pollution attacks by filtering dangerous keys
+ *
+ * @param key - The property key to validate
+ * @returns True if the key is safe to use, false otherwise
+ */
+function isSafeKey(key) {
+    return (!DANGEROUS_KEYS.includes(key) && !key.includes('.'));
+}
+/**
+ * Type guard to validate if an object is a valid MappingConfig
+ * @param obj - Object to validate
+ * @returns True if the object is a valid MappingConfig
+ */
+function isValidMappingConfig(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        'mappings' in obj &&
+        typeof obj.mappings === 'object');
+}
+/**
+ * Safely converts an object to MergeableObject for security processing
+ * @param obj - Object to convert
+ * @returns Converted object or empty object if invalid
+ */
+function toMergeableObject(obj) {
+    if (typeof obj === 'object' && obj !== null) {
+        return obj;
+    }
+    return {};
+}
+/**
+ * Validates section path parts for security risks
+ * @param sectionParts - Array of section path components to validate
+ * @throws Error if any part contains dangerous keys
+ */
+function validateSectionPath(sectionParts) {
+    const invalidPart = sectionParts.find((part) => !isSafeKey(part));
+    if (invalidPart) {
+        throw new Error(`Invalid section key detected: ${invalidPart}. This key poses a security risk.`);
+    }
+}
+/**
+ * Safely deep merges two objects, with values from the source object taking precedence
+ * Implements prototype pollution protection by filtering dangerous keys
+ *
+ * @param target - The target object
+ * @param source - The source object to merge in
+ * @returns The merged object
+ */
+function safeMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        // Security: Skip dangerous keys that could cause prototype pollution
+        if (!isSafeKey(key)) {
+            createScopedLogger('utils/config-loader', 'safeMerge').debug('Rejected dangerous key during merge', { key, source: 'config-loader' });
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            if (source[key] &&
+                typeof source[key] === 'object' &&
+                !Array.isArray(source[key])) {
+                // If both target and source have an object at this key, merge them recursively
+                if (result[key] &&
+                    typeof result[key] === 'object' &&
+                    !Array.isArray(result[key])) {
+                    result[key] = safeMerge(result[key], source[key]);
+                }
+                else {
+                    // Otherwise, safely copy the source value
+                    result[key] = safeMerge({}, source[key]);
+                }
+            }
+            else {
+                // For non-objects, use the source value
+                result[key] = source[key];
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Creates an empty mapping configuration with default structure
+ *
+ * @returns An empty mapping configuration
+ */
+function createEmptyConfig() {
+    return {
+        version: '1.0',
+        metadata: {
+            generated: new Date().toISOString(),
+            description: 'Generated empty configuration',
+        },
+        mappings: {
+            attributes: {
+                common: {},
+                objects: {},
+                custom: {},
+            },
+            objects: {},
+            lists: {},
+            relationships: {},
+        },
+    };
+}
+/**
+ * Loads a JSON configuration file
+ *
+ * @param filePath - Path to the JSON file
+ * @returns Parsed JSON object, or null if the file doesn't exist
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- JSON.parse returns any by design, content structure is unknown
+function loadJsonFile(filePath) {
+    try {
+        if (fs.existsSync(filePath)) {
+            const content = fs.readFileSync(filePath, 'utf8');
+            return JSON.parse(content);
+        }
+    }
+    catch (error) {
+        createScopedLogger('utils/config-loader', 'loadJsonFile').warn('Failed to load config file', {
+            filePath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return null;
+}
+/**
+ * Loads and merges the mapping configuration from default and user files
+ * Uses caching to avoid repeated disk I/O on hot paths
+ *
+ * @returns The merged mapping configuration
+ */
+export function loadMappingConfig() {
+    // Return cached config if available
+    if (cachedConfig) {
+        return cachedConfig;
+    }
+    // Start with empty configuration
+    let config = createEmptyConfig();
+    // Load and merge the default configuration
+    const defaultConfig = loadJsonFile(CONFIG_PATHS.default);
+    if (defaultConfig) {
+        const mergedConfig = safeMerge(toMergeableObject(config), toMergeableObject(defaultConfig));
+        if (isValidMappingConfig(mergedConfig)) {
+            config = mergedConfig;
+        }
+    }
+    // Load and merge the user configuration
+    const userConfig = loadJsonFile(CONFIG_PATHS.user);
+    if (userConfig) {
+        const mergedConfig = safeMerge(toMergeableObject(config), toMergeableObject(userConfig));
+        if (isValidMappingConfig(mergedConfig)) {
+            config = mergedConfig;
+        }
+    }
+    // Cache the result for subsequent calls
+    cachedConfig = config;
+    return config;
+}
+/**
+ * Writes a mapping configuration to a file
+ *
+ * @param config - The configuration to write
+ * @param filePath - The file path to write to (defaults to user.json)
+ */
+export async function writeMappingConfig(config, filePath = CONFIG_PATHS.user) {
+    try {
+        // Ensure the directory exists
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Update metadata
+        if (!config.metadata) {
+            config.metadata = {};
+        }
+        config.metadata.generated = new Date().toISOString();
+        // Write the file
+        const content = JSON.stringify(config, null, 2);
+        await fs.promises.writeFile(filePath, content, 'utf8');
+        // Invalidate cache so next read picks up changes
+        invalidateMappingConfigCache();
+    }
+    catch (error) {
+        throw new Error(`Failed to write config file ${filePath}: ${error}`);
+    }
+}
+/**
+ * Updates a specific section of the mapping configuration
+ *
+ * @param section - The section to update (e.g., 'attributes.common')
+ * @param mappings - The mappings to set or merge
+ * @param merge - Whether to merge with existing mappings (default: true)
+ * @param filePath - The file path to write to (defaults to user.json)
+ */
+export async function updateMappingSection(section, mappings, merge = true, filePath = CONFIG_PATHS.user) {
+    // Load the current config
+    const config = loadMappingConfig();
+    // Parse the section path and navigate to the target section
+    const sectionParts = section.split('.');
+    let target = config.mappings;
+    // Security: Validate all section parts for prototype pollution safety
+    validateSectionPath(sectionParts);
+    for (let i = 0; i < sectionParts.length - 1; i++) {
+        const part = sectionParts[i];
+        if (!target[part]) {
+            target[part] = {};
+        }
+        target = target[part];
+    }
+    const finalPart = sectionParts[sectionParts.length - 1];
+    // Update the target section with security validation
+    if (merge && target[finalPart]) {
+        // Use safe merging for existing sections
+        const mergedSection = safeMerge(toMergeableObject(target[finalPart]), toMergeableObject(mappings));
+        target[finalPart] = mergedSection;
+    }
+    else {
+        // For new sections, ensure the mappings object is safe
+        const safeSection = safeMerge({}, toMergeableObject(mappings));
+        target[finalPart] = safeSection;
+    }
+    // Write the updated config
+    await writeMappingConfig(config, filePath);
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/utils/config-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}

package/dist/utils/config-migration.d.ts

@@ -0,0 +1,140 @@
+import { MappingConfig } from './config-loader.js';
+export type { MappingConfig };
+export interface MigrationResult {
+    success: boolean;
+    message: string;
+    backupPath?: string;
+    changesApplied?: string[];
+    errors?: string[];
+}
+export interface MigrationDetection {
+    needsMigration: boolean;
+    outdatedMappings: string[];
+    filePath: string;
+    exists: boolean;
+}
+/**
+ * Detects if user.json needs migration for postal code mappings
+ *
+ * Scans the user configuration file for outdated postal code mappings
+ * that use "zip" instead of the correct "postal_code" attribute name.
+ *
+ * @returns MigrationDetection object containing:
+ *   - needsMigration: whether migration is required
+ *   - outdatedMappings: array of problematic mappings found
+ *   - filePath: path to the user config file
+ *   - exists: whether the config file exists
+ *
+ * @example
+ * ```typescript
+ * const detection = detectMigrationNeeds();
+ * if (detection.needsMigration) {
+ *   console.error('Found outdated mappings:', detection.outdatedMappings);
+ * }
+ * ```
+ */
+export declare function detectMigrationNeeds(): MigrationDetection;
+/**
+ * Creates a timestamped backup of the user.json file
+ *
+ * Creates a backup in config/mappings/backup/ directory with ISO timestamp.
+ * Ensures the backup directory exists before creating the backup file.
+ *
+ * @returns Object containing:
+ *   - success: whether backup creation succeeded
+ *   - backupPath: path to the created backup file (if successful)
+ *   - error: error message (if failed)
+ *
+ * @example
+ * ```typescript
+ * const backup = createBackup();
+ * if (backup.success) {
+ *   console.error('Backup created at:', backup.backupPath);
+ * } else {
+ *   console.error('Backup failed:', backup.error);
+ * }
+ * ```
+ */
+export declare function createBackup(): {
+    success: boolean;
+    backupPath?: string;
+    error?: string;
+};
+/**
+ * Applies the postal code mapping migration to user.json
+ *
+ * Performs the complete migration workflow:
+ * 1. Detects if migration is needed
+ * 2. Creates a backup of the current configuration
+ * 3. Applies the postal code mapping fixes
+ * 4. Updates metadata to track migration history
+ *
+ * @returns MigrationResult object containing:
+ *   - success: whether the migration succeeded
+ *   - message: descriptive message about the operation
+ *   - backupPath: path to the backup file (if created)
+ *   - changesApplied: array of changes that were made
+ *   - errors: array of error messages (if any failures occurred)
+ *
+ * @example
+ * ```typescript
+ * const result = applyMigration();
+ * if (result.success) {
+ *   console.error('Migration completed:', result.message);
+ *   console.error('Changes:', result.changesApplied);
+ * } else {
+ *   console.error('Migration failed:', result.message);
+ * }
+ * ```
+ */
+export declare function applyMigration(): MigrationResult;
+/**
+ * Validates that the migration was applied correctly
+ *
+ * Checks if the user configuration still contains any outdated postal
+ * code mappings after migration has been applied.
+ *
+ * @returns Object containing:
+ *   - valid: whether the configuration passes validation
+ *   - issues: array of validation issues found (if any)
+ *
+ * @example
+ * ```typescript
+ * const validation = validateMigration();
+ * if (!validation.valid) {
+ *   console.error('Validation failed:', validation.issues);
+ * }
+ * ```
+ */
+export declare function validateMigration(): {
+    valid: boolean;
+    issues: string[];
+};
+/**
+ * Complete migration workflow with validation
+ *
+ * Main entry point for the migration process. Orchestrates detection,
+ * migration, and validation with optional dry-run mode.
+ *
+ * @param options Configuration options for the migration:
+ *   - dryRun: if true, only shows what would be changed without applying
+ *
+ * @returns MigrationResult object with complete operation status
+ *
+ * @example
+ * ```typescript
+ * // Preview changes without applying
+ * const preview = migrateUserConfig({ dryRun: true });
+ * console.error('Would apply:', preview.changesApplied);
+ *
+ * // Apply the migration
+ * const result = migrateUserConfig();
+ * if (result.success) {
+ *   console.error('Migration completed successfully');
+ * }
+ * ```
+ */
+export declare function migrateUserConfig(options?: {
+    dryRun?: boolean;
+}): MigrationResult;
+//# sourceMappingURL=config-migration.d.ts.map

package/dist/utils/config-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-migration.d.ts","sourceRoot":"","sources":["../../src/utils/config-migration.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AA0BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,CA6CzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,IAAI;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAsBA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,IAAI,eAAe,CA6EhD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAmBxE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,eAAe,CAmDjB"}