@daniel.stefan/metalink 1.3.1

package/packages/core/dist/config/registry.js

@@ -0,0 +1,754 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { EventEmitter } from 'events';
+import { ServerConfigSchema } from './schema.js';
+import { FileLock } from '../utils/file-lock.js';
+/**
+ * Security configuration for registry operations.
+ * Whitelist of allowed commands to prevent arbitrary command execution.
+ *
+ * SECURITY NOTE (OWASP CWE-78: OS Command Injection Prevention):
+ * - Only package runners and runtimes are whitelisted
+ * - 'bash' and 'sh' are EXPLICITLY PROHIBITED to prevent shell command injection
+ * - If registry is compromised, attackers cannot execute arbitrary shell commands
+ * - All server commands must use absolute paths or whitelisted runners
+ *
+ * @see https://owasp.org/www-community/attacks/Command_Injection
+ */
+export const ALLOWED_COMMANDS = [
+    'npx', // npm package runner - executes specific npm packages
+    'uvx', // uv package runner - Python package execution
+    'node', // Node.js runtime - requires explicit script path
+    'python3', // Python 3 runtime - requires explicit script path
+    'python', // Python runtime alias - requires explicit script path
+    'mcp-grafana', // Specific MCP server binary (pre-approved)
+    // SECURITY: 'bash' and 'sh' REMOVED - shell execution prohibited
+    // Rationale: Shell access allows arbitrary command injection if registry is compromised
+    // Alternative: Use absolute paths (e.g., /usr/local/bin/myserver) for custom servers
+];
+/**
+ * Patterns that indicate dangerous shell metacharacters or injection attempts.
+ * Used by validateServerArguments() to detect malicious input.
+ *
+ * @see https://owasp.org/www-community/attacks/Command_Injection
+ */
+export const DANGEROUS_PATTERNS = [
+    /;/, // Command chaining
+    /\|/, // Pipe operator
+    /&/, // Background/chaining
+    /`/, // Command substitution (backticks)
+    /\$\(/, // Command substitution $(...)
+    /\$\{/, // Variable expansion ${...}
+    />/, // Output redirection
+    /</, // Input redirection
+    /\n/, // Newline injection
+    /\r/, // Carriage return injection
+];
+/**
+ * SECURITY (CWE-78): Dangerous flags that could execute arbitrary code.
+ * These flags are blocked even for whitelisted commands to prevent
+ * command injection via flags like `node --eval "malicious code"`.
+ *
+ * @see https://owasp.org/www-community/attacks/Command_Injection
+ */
+export const DANGEROUS_FLAGS = {
+    'node': [
+        '--eval', '-e', // Run inline JavaScript code
+        '--print', '-p', // Evaluate and print expression
+        '--require', '-r', // Preload module (can run arbitrary code)
+        '--import', // ESM module preloading
+        '--input-type', // Interpret stdin as module (bypass detection)
+    ],
+    'python': [
+        '-c', '--command', // Run inline Python code
+        '-m', // Run module as script (can be abused)
+    ],
+    'python3': [
+        '-c', '--command', // Run inline Python code
+        '-m', // Run module as script (can be abused)
+    ],
+    'npx': [
+        '--yes', '-y', // Auto-install without confirmation (malicious packages)
+    ],
+};
+/**
+ * Check if any argument contains a dangerous flag for the given command.
+ * Prevents command injection via flags like `node --eval "malicious code"`.
+ *
+ * SECURITY (CWE-78): This function blocks dangerous interpreter flags that
+ * could be used to run arbitrary code even when the command itself is whitelisted.
+ *
+ * @param command - The command being validated (e.g., 'node', 'python3')
+ * @param args - Array of command arguments
+ * @param serverName - Optional server name for audit logging
+ * @throws Error if a dangerous flag is detected
+ *
+ * @see https://owasp.org/www-community/attacks/Command_Injection
+ */
+export function validateCommandFlags(command, args, serverName) {
+    const dangerousForCommand = DANGEROUS_FLAGS[command];
+    if (!dangerousForCommand)
+        return; // No restrictions for this command
+    const timestamp = new Date().toISOString();
+    for (const arg of args) {
+        // Check exact match and prefix match (e.g., --eval=code, -e=code)
+        for (const dangerousFlag of dangerousForCommand) {
+            if (arg === dangerousFlag || arg.startsWith(`${dangerousFlag}=`)) {
+                logSecurityEvent({
+                    timestamp,
+                    eventType: 'DANGEROUS_FLAG_BLOCKED',
+                    severity: 'CRITICAL',
+                    details: `Dangerous flag '${dangerousFlag}' blocked for command '${command}'. ` +
+                        `This flag could be used to run arbitrary code.`,
+                    serverName,
+                    command,
+                    // Note: Not logging full args array to avoid leaking potential attack payloads
+                });
+                throw new Error(`SECURITY VIOLATION: Flag '${dangerousFlag}' is not allowed for command '${command}'. ` +
+                    `This flag could be used to run arbitrary code and is blocked for security reasons.`);
+            }
+        }
+    }
+}
+/**
+ * Log a security audit event.
+ * In production, this should be connected to a SIEM or audit log system.
+ *
+ * @param entry - Security audit log entry
+ */
+export function logSecurityEvent(entry) {
+    const logMessage = `[SECURITY ${entry.severity}] ${entry.eventType}: ${entry.details}`;
+    // Always log to console with timestamp
+    if (entry.severity === 'CRITICAL' || entry.severity === 'HIGH') {
+        console.error(logMessage, {
+            timestamp: entry.timestamp,
+            serverName: entry.serverName,
+            command: entry.command,
+            // Intentionally not logging args for security (may contain sensitive data)
+        });
+    }
+    else {
+        console.warn(logMessage, {
+            timestamp: entry.timestamp,
+            serverName: entry.serverName,
+        });
+    }
+}
+/**
+ * Validate server command against security rules.
+ * Throws an error if command is not whitelisted or contains dangerous patterns.
+ *
+ * SECURITY: This is a critical function for preventing command injection.
+ *
+ * @param command - The command to execute (e.g., 'npx', 'node')
+ * @param args - Command arguments array
+ * @param serverName - Name of the server (for audit logging)
+ * @throws Error if validation fails
+ */
+export function validateServerCommand(command, args, serverName) {
+    const timestamp = new Date().toISOString();
+    // Check 1: Is it a whitelisted command?
+    if (!ALLOWED_COMMANDS.includes(command)) {
+        // Special handling for shell commands - log as CRITICAL
+        if (command === 'bash' || command === 'sh' || command === 'zsh' || command === 'csh') {
+            logSecurityEvent({
+                timestamp,
+                eventType: 'SHELL_COMMAND_BLOCKED',
+                severity: 'CRITICAL',
+                details: `Shell command '${command}' is prohibited. Use package runners or absolute paths instead.`,
+                serverName,
+                command,
+            });
+            throw new Error(`SECURITY VIOLATION: Shell command '${command}' is not allowed. ` +
+                `Shell execution is prohibited to prevent command injection attacks. ` +
+                `Use 'npx', 'uvx', 'node', or 'python3' with explicit script paths.`);
+        }
+        logSecurityEvent({
+            timestamp,
+            eventType: 'COMMAND_VALIDATION_FAILED',
+            severity: 'HIGH',
+            details: `Command '${command}' not whitelisted. Allowed: ${ALLOWED_COMMANDS.join(', ')}`,
+            serverName,
+            command,
+        });
+        throw new Error(`Command '${command}' not whitelisted. Allowed commands: ${ALLOWED_COMMANDS.join(', ')}`);
+    }
+    // Check 2: SECURITY (CWE-78) - Block dangerous flags that could run arbitrary code
+    validateCommandFlags(command, args, serverName);
+    // Check 3: For node/python - first argument should be an absolute path or package name
+    if (['node', 'python3', 'python'].includes(command)) {
+        if (args.length === 0) {
+            logSecurityEvent({
+                timestamp,
+                eventType: 'COMMAND_VALIDATION_FAILED',
+                severity: 'MEDIUM',
+                details: `${command} requires a script path argument`,
+                serverName,
+                command,
+            });
+            throw new Error(`${command} requires a script path argument`);
+        }
+        const scriptPath = args[0];
+        // Allow: absolute paths, package names starting with @, relative paths from current dir
+        const isAbsolutePath = scriptPath.startsWith('/') || scriptPath.startsWith('~');
+        const isPackageName = scriptPath.startsWith('@') || /^[a-z0-9-]+$/i.test(scriptPath);
+        const isRelativeFromCurrent = scriptPath.startsWith('./');
+        // Reject paths starting with .. (path traversal attempt)
+        if (scriptPath.startsWith('..')) {
+            logSecurityEvent({
+                timestamp,
+                eventType: 'PATH_TRAVERSAL_DETECTED',
+                severity: 'HIGH',
+                details: `Script path starts with '..' which indicates path traversal: ${scriptPath}`,
+                serverName,
+                command,
+                args,
+            });
+            throw new Error(`Script path must not start with '..'. Use absolute paths or paths relative to current directory (./)`);
+        }
+        // Warn but allow relative paths from current directory
+        if (!isAbsolutePath && !isPackageName && !isRelativeFromCurrent) {
+            console.warn(`[SECURITY] Non-absolute script path: ${scriptPath}. Consider using absolute paths for security.`);
+        }
+    }
+    // Check 3: No path traversal in any arguments
+    for (const arg of args) {
+        if (arg.includes('../') || arg.includes('..\\')) {
+            logSecurityEvent({
+                timestamp,
+                eventType: 'PATH_TRAVERSAL_DETECTED',
+                severity: 'HIGH',
+                details: `Path traversal detected in argument: ${arg}`,
+                serverName,
+                command,
+                args,
+            });
+            throw new Error(`Path traversal detected in argument: ${arg}`);
+        }
+        // Check 4: No dangerous shell metacharacters in arguments
+        for (const pattern of DANGEROUS_PATTERNS) {
+            if (pattern.test(arg)) {
+                logSecurityEvent({
+                    timestamp,
+                    eventType: 'DANGEROUS_PATTERN_DETECTED',
+                    severity: 'HIGH',
+                    details: `Dangerous pattern detected in argument: ${arg}`,
+                    serverName,
+                    command,
+                    args,
+                });
+                throw new Error(`Dangerous shell metacharacter detected in argument: ${arg}. ` +
+                    'Arguments must not contain shell operators (;|&`$<>).');
+            }
+        }
+    }
+}
+/**
+ * Validate registry integrity - checks all server configurations for security issues.
+ * This should be called when loading the registry to detect tampering.
+ *
+ * @param registry - The registry object containing servers array
+ * @returns Object with valid flag and any warnings/errors found
+ */
+export async function validateRegistryIntegrity(registry) {
+    const timestamp = new Date().toISOString();
+    const warnings = [];
+    const errors = [];
+    for (const server of registry.servers) {
+        // Validate server name (alphanumeric, hyphens, underscores only)
+        if (!/^[a-zA-Z0-9_-]+$/.test(server.name)) {
+            errors.push(`Server name '${server.name}' contains invalid characters. Use alphanumeric, hyphens, or underscores only.`);
+        }
+        // Validate command if present (stdio server)
+        if (server.command) {
+            // Check for shell commands
+            if (['bash', 'sh', 'zsh', 'csh'].includes(server.command)) {
+                errors.push(`Server '${server.name}' uses prohibited shell command '${server.command}'. ` +
+                    `Shell commands are blocked to prevent command injection.`);
+                logSecurityEvent({
+                    timestamp,
+                    eventType: 'SHELL_COMMAND_BLOCKED',
+                    severity: 'CRITICAL',
+                    details: `Registry contains shell command for server '${server.name}'`,
+                    serverName: server.name,
+                    command: server.command,
+                });
+            }
+            // Check command whitelist
+            if (!ALLOWED_COMMANDS.includes(server.command)) {
+                warnings.push(`Server '${server.name}' uses non-whitelisted command '${server.command}'. ` +
+                    `Consider using whitelisted commands: ${ALLOWED_COMMANDS.join(', ')}`);
+            }
+            // Validate arguments
+            if (server.args) {
+                // SECURITY (CWE-78): Check for dangerous flags that could run arbitrary code
+                const dangerousForCommand = DANGEROUS_FLAGS[server.command];
+                if (dangerousForCommand) {
+                    for (const arg of server.args) {
+                        for (const dangerousFlag of dangerousForCommand) {
+                            if (arg === dangerousFlag || arg.startsWith(`${dangerousFlag}=`)) {
+                                errors.push(`Server '${server.name}' uses dangerous flag '${dangerousFlag}' for command '${server.command}'. ` +
+                                    `This flag is blocked to prevent arbitrary code running.`);
+                                logSecurityEvent({
+                                    timestamp,
+                                    eventType: 'DANGEROUS_FLAG_BLOCKED',
+                                    severity: 'CRITICAL',
+                                    details: `Registry contains dangerous flag '${dangerousFlag}' for server '${server.name}'`,
+                                    serverName: server.name,
+                                    command: server.command,
+                                });
+                            }
+                        }
+                    }
+                }
+                // Check for path traversal and dangerous patterns
+                for (const arg of server.args) {
+                    if (arg.includes('../') || arg.includes('..\\')) {
+                        errors.push(`Server '${server.name}' has path traversal in argument: ${arg}`);
+                    }
+                    for (const pattern of DANGEROUS_PATTERNS) {
+                        if (pattern.test(arg)) {
+                            errors.push(`Server '${server.name}' has dangerous pattern in argument: ${arg}`);
+                        }
+                    }
+                }
+            }
+        }
+        // Validate environment variables
+        if (server.env) {
+            for (const [key, value] of Object.entries(server.env)) {
+                // Check for path traversal in env values
+                if (typeof value === 'string' && (value.includes('../') || value.includes('..\\'))) {
+                    warnings.push(`Server '${server.name}' has path traversal in env var '${key}'`);
+                }
+                // Don't log actual env values - they may contain secrets
+            }
+        }
+    }
+    const valid = errors.length === 0;
+    logSecurityEvent({
+        timestamp,
+        eventType: valid ? 'INTEGRITY_CHECK_PASSED' : 'INTEGRITY_CHECK_FAILED',
+        severity: valid ? 'LOW' : 'HIGH',
+        details: `Registry integrity check: ${errors.length} errors, ${warnings.length} warnings`,
+    });
+    return { valid, warnings, errors };
+}
+/**
+ * RegistryManager handles atomic read/write operations on mcp-registry.json.
+ * Ensures data integrity through file locking and rolling backups.
+ *
+ * Events emitted:
+ *   - server:added { server: ServerConfig, timestamp: number }
+ *   - server:removed { name: string, timestamp: number }
+ *   - registry:saved { path: string, timestamp: number }
+ *   - registry:error { error: string, path: string }
+ */
+export class RegistryManager extends EventEmitter {
+    /**
+     * Get the default persistent registry path (~/.config/metalink/mcp-registry.json)
+     * Respects METALINK_CONFIG_DIR environment variable if set
+     */
+    static getDefaultRegistryPath() {
+        const configDir = process.env.METALINK_CONFIG_DIR ||
+            path.join(process.env.HOME || process.env.USERPROFILE || '~', '.config', 'metalink');
+        return path.join(configDir, 'mcp-registry.json');
+    }
+    constructor(registryPath = '') {
+        super();
+        this.maxBackups = 3;
+        // Use persistent config dir by default if no path provided
+        const resolvedPath = registryPath || RegistryManager.getDefaultRegistryPath();
+        this.registryPath = path.resolve(resolvedPath);
+        this.lock = new FileLock(this.registryPath);
+    }
+    /**
+     * Read and parse the registry file.
+     * Does not require lock (read-only operation).
+     */
+    async readRegistry() {
+        try {
+            const content = await fs.readFile(this.registryPath, 'utf8');
+            const parsed = JSON.parse(content);
+            if (!Array.isArray(parsed.servers)) {
+                throw new Error('Invalid registry format: servers must be an array');
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Return empty registry if file doesn't exist yet
+                return { servers: [] };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get all servers from registry.
+     */
+    async getServers() {
+        const registry = await this.readRegistry();
+        return registry.servers;
+    }
+    /**
+     * Get a single server by name.
+     */
+    async getServer(name) {
+        const servers = await this.getServers();
+        return servers.find(s => s.name === name) || null;
+    }
+    /**
+     * Validate a server configuration.
+     * Returns { valid: true } or { valid: false, errors: [...] }
+     *
+     * SECURITY: Uses validateServerCommand() for comprehensive security checks.
+     */
+    async validateServer(config, options = {}) {
+        // Validate schema
+        const schemaResult = ServerConfigSchema.safeParse(config);
+        if (!schemaResult.success) {
+            const errors = schemaResult.error.errors.map(e => {
+                return `${e.path.join('.')}: ${e.message}`;
+            });
+            return { valid: false, errors };
+        }
+        const server = schemaResult.data;
+        const errors = [];
+        // Validate command (only for stdio servers, and unless allowAnyCommand is true)
+        if (!options.allowAnyCommand) {
+            if (server.transport === 'stdio' || server.transport === undefined) {
+                // For stdio servers, validate the command using security-hardened function
+                const stdioServer = server;
+                // SECURITY: Use validateServerCommand for comprehensive checks
+                try {
+                    validateServerCommand(stdioServer.command, stdioServer.args || [], server.name);
+                }
+                catch (validationError) {
+                    errors.push(validationError instanceof Error
+                        ? validationError.message
+                        : String(validationError));
+                }
+            }
+            else {
+                // For HTTP servers, check if mcp-remote proxy is available
+                if (!ALLOWED_COMMANDS.includes('mcp-remote')) {
+                    errors.push(`HTTP server '${server.name}' requires 'mcp-remote' proxy to be enabled`);
+                }
+            }
+        }
+        // Validate environment variables (no path traversal)
+        for (const [key, value] of Object.entries(server.env || {})) {
+            if (typeof value !== 'string') {
+                errors.push(`Environment variable '${key}' must be a string`);
+                continue;
+            }
+            if (value.includes('../') || value.includes('..\\')) {
+                errors.push(`Environment variable '${key}' contains path traversal`);
+            }
+            // SECURITY: Check for dangerous patterns in env values
+            for (const pattern of DANGEROUS_PATTERNS) {
+                if (pattern.test(value)) {
+                    // Only warn for env vars (may have legitimate uses like URLs with &)
+                    // But log it for security monitoring
+                    console.warn(`[SECURITY] Server '${server.name}' env var '${key}' contains pattern that may indicate injection`);
+                    break;
+                }
+            }
+        }
+        return errors.length > 0 ? { valid: false, errors } : { valid: true };
+    }
+    /**
+     * Add a new server to the registry.
+     * Validates config, checks uniqueness, acquires lock, writes atomically.
+     *
+     * @throws Error if validation fails, server already exists, or write fails
+     */
+    async addServer(config, options = {}) {
+        const { allowAnyCommand = false, timeout = 5000 } = options;
+        // Validate configuration
+        const validation = await this.validateServer(config, { allowAnyCommand });
+        if (!validation.valid) {
+            const errorMsg = validation.errors.join('; ');
+            throw new Error(`Server validation failed: ${errorMsg}`);
+        }
+        const server = ServerConfigSchema.parse(config);
+        // Acquire lock
+        await this.lock.acquire(timeout);
+        try {
+            // Read current registry (double-check uniqueness under lock)
+            const registry = await this.readRegistry();
+            if (registry.servers.some(s => s.name === server.name)) {
+                throw new Error(`Server '${server.name}' already exists in registry`);
+            }
+            // Add server
+            registry.servers.push(server);
+            // Write atomically with backup
+            await this.writeRegistry(registry);
+            // Emit event
+            this.emit('server:added', {
+                server,
+                timestamp: Date.now(),
+            });
+            return server;
+        }
+        finally {
+            await this.lock.release();
+        }
+    }
+    /**
+     * Remove a server from the registry by name.
+     * Acquires lock, removes server, writes atomically.
+     *
+     * @throws Error if server not found or write fails
+     */
+    async removeServer(name, options = {}) {
+        const { timeout = 5000 } = options;
+        // Acquire lock
+        await this.lock.acquire(timeout);
+        try {
+            // Read current registry
+            const registry = await this.readRegistry();
+            const initialCount = registry.servers.length;
+            // Remove server
+            registry.servers = registry.servers.filter(s => s.name !== name);
+            // Check if server was found
+            if (registry.servers.length === initialCount) {
+                throw new Error(`Server '${name}' not found in registry`);
+            }
+            // Write atomically with backup
+            await this.writeRegistry(registry);
+            // Emit event
+            this.emit('server:removed', {
+                name,
+                timestamp: Date.now(),
+            });
+        }
+        finally {
+            await this.lock.release();
+        }
+    }
+    /**
+     * Update an existing server configuration.
+     * Validates config, replaces server, writes atomically.
+     */
+    async updateServer(name, config, options = {}) {
+        const { allowAnyCommand = false, timeout = 5000 } = options;
+        // Validate new configuration
+        const validation = await this.validateServer(config, { allowAnyCommand });
+        if (!validation.valid) {
+            const errorMsg = validation.errors.join('; ');
+            throw new Error(`Server validation failed: ${errorMsg}`);
+        }
+        const newConfig = ServerConfigSchema.parse(config);
+        // Acquire lock
+        await this.lock.acquire(timeout);
+        try {
+            // Read current registry
+            const registry = await this.readRegistry();
+            const serverIndex = registry.servers.findIndex(s => s.name === name);
+            if (serverIndex === -1) {
+                throw new Error(`Server '${name}' not found in registry`);
+            }
+            // Replace server (name must match)
+            if (newConfig.name !== name) {
+                throw new Error(`Cannot change server name from '${name}' to '${newConfig.name}'`);
+            }
+            registry.servers[serverIndex] = newConfig;
+            // Write atomically with backup
+            await this.writeRegistry(registry);
+            // Emit event
+            this.emit('server:updated', {
+                server: newConfig,
+                timestamp: Date.now(),
+            });
+            return newConfig;
+        }
+        finally {
+            await this.lock.release();
+        }
+    }
+    /**
+     * Internal method to write registry with backup and rollback on failure.
+     */
+    async writeRegistry(registry) {
+        const content = JSON.stringify(registry, null, 2);
+        try {
+            // Create backup before write
+            await this.createBackup();
+            // Atomic write with temp file + rename
+            const dir = path.dirname(this.registryPath);
+            const tempPath = path.join(dir, `.registry.tmp.${Date.now()}`);
+            try {
+                // Write to temp file
+                await fs.writeFile(tempPath, content, 'utf8');
+                // Atomic rename
+                await fs.rename(tempPath, this.registryPath);
+                // Clean up old backups
+                await this.rotateBackups();
+                // Emit success event
+                this.emit('registry:saved', {
+                    path: this.registryPath,
+                    timestamp: Date.now(),
+                });
+            }
+            catch (error) {
+                // Cleanup temp file on error
+                try {
+                    await fs.unlink(tempPath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            // Emit error event
+            this.emit('registry:error', {
+                error: error.message,
+                path: this.registryPath,
+                timestamp: Date.now(),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Create a backup of the current registry.
+     * Backups are named: registry.json.backup, registry.json.backup.1, etc.
+     */
+    async createBackup() {
+        try {
+            const backupPath = `${this.registryPath}.backup`;
+            await fs.copyFile(this.registryPath, backupPath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                // Only log, don't throw - backup failure shouldn't block writes
+                console.warn('Failed to create backup:', error);
+            }
+        }
+    }
+    /**
+     * Rotate backups to keep only the last N backups.
+     * Keeps: .backup, .backup.1, .backup.2 (maxBackups = 3)
+     */
+    async rotateBackups() {
+        const dir = path.dirname(this.registryPath);
+        const filename = path.basename(this.registryPath);
+        try {
+            // Remove oldest backup if we've exceeded max
+            const oldestBackup = `${this.registryPath}.backup.${this.maxBackups}`;
+            try {
+                await fs.unlink(oldestBackup);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw error;
+                }
+            }
+            // Shift backups: .backup.1 → .backup.2, .backup → .backup.1
+            for (let i = this.maxBackups - 1; i >= 1; i--) {
+                const oldPath = `${this.registryPath}.backup${i === 1 ? '' : '.' + (i - 1)}`;
+                const newPath = `${this.registryPath}.backup.${i}`;
+                try {
+                    await fs.rename(oldPath, newPath);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.warn('Failed to rotate backups:', error);
+            // Don't throw - backup rotation failure shouldn't block writes
+        }
+    }
+    /**
+     * Restore registry from backup.
+     * Useful for rollback on catastrophic failure.
+     */
+    async restoreFromBackup(backupIndex = 0) {
+        const backupPath = backupIndex === 0
+            ? `${this.registryPath}.backup`
+            : `${this.registryPath}.backup.${backupIndex}`;
+        try {
+            await fs.copyFile(backupPath, this.registryPath);
+            this.emit('registry:restored', {
+                from: backupPath,
+                to: this.registryPath,
+                timestamp: Date.now(),
+            });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new Error(`Backup not found: ${backupPath}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get backup file info for monitoring/debugging.
+     */
+    async getBackupInfo() {
+        const backups = [];
+        for (let i = 0; i < this.maxBackups; i++) {
+            const backupPath = i === 0
+                ? `${this.registryPath}.backup`
+                : `${this.registryPath}.backup.${i}`;
+            try {
+                const stat = await fs.stat(backupPath);
+                backups.push({
+                    path: backupPath,
+                    size: stat.size,
+                    modified: stat.mtime,
+                });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    console.warn(`Failed to stat backup ${backupPath}:`, error);
+                }
+            }
+        }
+        return backups;
+    }
+    /**
+     * Get registry file info.
+     */
+    async getRegistryInfo() {
+        try {
+            const stat = await fs.stat(this.registryPath);
+            return {
+                path: this.registryPath,
+                size: stat.size,
+                exists: true,
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return {
+                    path: this.registryPath,
+                    size: 0,
+                    exists: false,
+                };
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Singleton instance for global registry management.
+ * Usage: import { registryManager } from './registry';
+ */
+let globalRegistry = null;
+export function getRegistryManager(registryPath) {
+    if (!globalRegistry) {
+        globalRegistry = new RegistryManager(registryPath);
+    }
+    return globalRegistry;
+}
+export function resetRegistryManager() {
+    globalRegistry = null;
+}
+//# sourceMappingURL=registry.js.map