@lbruton/spec-workflow-mcp 2.2.4

package/dist/core/project-registry.js

@@ -0,0 +1,297 @@
+import { join } from 'path';
+import { promises as fs } from 'fs';
+import { basename, resolve } from 'path';
+import { createHash } from 'crypto';
+import { getGlobalDir, getPermissionErrorHelp } from './global-dir.js';
+/**
+ * Generate a stable projectId from an absolute path
+ * Uses SHA-1 hash encoded as base64url
+ */
+export function generateProjectId(absolutePath) {
+    const hash = createHash('sha1').update(absolutePath).digest('base64url');
+    // Take first 16 characters for readability
+    return hash.substring(0, 16);
+}
+/**
+ * Build display name for a workspace.
+ * - Main repo: "repo"
+ * - Worktree: "repo · worktree"
+ */
+export function generateProjectDisplayName(workspacePath, workflowRootPath) {
+    const workspaceName = basename(workspacePath);
+    const repoName = basename(workflowRootPath);
+    if (workspacePath === workflowRootPath) {
+        return repoName;
+    }
+    return `${repoName} · ${workspaceName}`;
+}
+export class ProjectRegistry {
+    registryPath;
+    registryDir;
+    needsInitialization = false;
+    constructor() {
+        this.registryDir = getGlobalDir();
+        this.registryPath = join(this.registryDir, 'activeProjects.json');
+    }
+    /**
+     * Ensure the registry directory exists
+     */
+    async ensureRegistryDir() {
+        try {
+            await fs.mkdir(this.registryDir, { recursive: true });
+        }
+        catch (error) {
+            // Directory might already exist, ignore EEXIST errors
+            if (error.code === 'EEXIST') {
+                return;
+            }
+            // For permission errors, provide helpful guidance
+            if (error.code === 'EACCES' || error.code === 'EPERM') {
+                console.error(getPermissionErrorHelp('create directory', this.registryDir));
+                throw error;
+            }
+            // Re-throw other errors
+            throw error;
+        }
+    }
+    /**
+     * Read the registry file with atomic operations
+     * Returns a map keyed by projectId
+     */
+    async readRegistry() {
+        await this.ensureRegistryDir();
+        try {
+            const content = await fs.readFile(this.registryPath, 'utf-8');
+            // Handle empty or whitespace-only files
+            const trimmedContent = content.trim();
+            if (!trimmedContent) {
+                console.error(`[ProjectRegistry] Warning: ${this.registryPath} is empty, initializing with empty registry`);
+                // Mark that we need to write the file
+                this.needsInitialization = true;
+                return new Map();
+            }
+            const data = JSON.parse(trimmedContent);
+            const registry = new Map();
+            // Ensure backward compatibility with older formats:
+            // - instances may be missing
+            // - workflowRootPath may be missing
+            for (const [projectId, entry] of Object.entries(data)) {
+                const normalizedProjectPath = resolve(entry.projectPath);
+                const normalizedWorkflowRootPath = resolve(entry.workflowRootPath || entry.projectPath);
+                registry.set(projectId, {
+                    ...entry,
+                    projectPath: normalizedProjectPath,
+                    workflowRootPath: normalizedWorkflowRootPath,
+                    projectName: entry.projectName || generateProjectDisplayName(normalizedProjectPath, normalizedWorkflowRootPath),
+                    instances: Array.isArray(entry.instances) ? entry.instances : []
+                });
+            }
+            return registry;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // File doesn't exist yet, return empty map
+                this.needsInitialization = true;
+                return new Map();
+            }
+            if (error instanceof SyntaxError) {
+                // JSON parsing error - file is corrupted or invalid
+                console.error(`[ProjectRegistry] Error: Failed to parse ${this.registryPath}: ${error.message}`);
+                console.error(`[ProjectRegistry] The file may be corrupted. Initializing with empty registry.`);
+                // Back up the corrupted file
+                try {
+                    const backupPath = `${this.registryPath}.corrupted.${Date.now()}`;
+                    await fs.copyFile(this.registryPath, backupPath);
+                    console.error(`[ProjectRegistry] Corrupted file backed up to: ${backupPath}`);
+                }
+                catch (backupError) {
+                    // Ignore backup errors
+                }
+                this.needsInitialization = true;
+                return new Map();
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write the registry file atomically
+     */
+    async writeRegistry(registry) {
+        await this.ensureRegistryDir();
+        const data = Object.fromEntries(registry);
+        const content = JSON.stringify(data, null, 2);
+        // Write to temporary file first, then rename for atomic operation
+        const tempPath = `${this.registryPath}.tmp`;
+        await fs.writeFile(tempPath, content, 'utf-8');
+        await fs.rename(tempPath, this.registryPath);
+    }
+    /**
+     * Check if a process is still running
+     * Note: When running in Docker with path translation, we can't check host PIDs,
+     * so we assume processes are alive if path translation is enabled.
+     */
+    isProcessAlive(pid) {
+        // If path translation is enabled, we're in Docker and can't check host PIDs
+        const hostPrefix = process.env.SPEC_WORKFLOW_HOST_PATH_PREFIX;
+        const containerPrefix = process.env.SPEC_WORKFLOW_CONTAINER_PATH_PREFIX;
+        if (hostPrefix && containerPrefix) {
+            // Can't verify host PIDs from inside Docker, assume alive
+            return true;
+        }
+        try {
+            // Sending signal 0 checks if process exists without actually sending a signal
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Register a project in the global registry
+     * Self-healing: If a project exists with dead PIDs, cleans them up and adds new PID
+     * Multi-instance: Allows unlimited MCP server instances per project
+     */
+    async registerProject(projectPath, pid, options = {}) {
+        const registry = await this.readRegistry();
+        const workspacePath = resolve(projectPath);
+        const workflowRootPath = resolve(options.workflowRootPath || projectPath);
+        const projectId = generateProjectId(workspacePath);
+        const projectName = options.projectName || generateProjectDisplayName(workspacePath, workflowRootPath);
+        const existing = registry.get(projectId);
+        if (existing) {
+            // Self-healing: Filter out dead PIDs
+            const liveInstances = existing.instances.filter(i => this.isProcessAlive(i.pid));
+            // Check if this PID is already registered (avoid duplicates)
+            if (!liveInstances.some(i => i.pid === pid)) {
+                liveInstances.push({ pid, registeredAt: new Date().toISOString() });
+            }
+            // Update with live instances (no limit on number of instances)
+            existing.projectPath = workspacePath;
+            existing.workflowRootPath = workflowRootPath;
+            existing.projectName = projectName;
+            existing.instances = liveInstances;
+            registry.set(projectId, existing);
+        }
+        else {
+            // New project
+            const entry = {
+                projectId,
+                projectPath: workspacePath,
+                workflowRootPath,
+                projectName,
+                instances: [{ pid, registeredAt: new Date().toISOString() }]
+            };
+            registry.set(projectId, entry);
+        }
+        await this.writeRegistry(registry);
+        return projectId;
+    }
+    /**
+     * Unregister a project from the global registry by path
+     * If pid is provided, only removes that specific instance
+     * If no pid provided, removes the entire project (backwards compat)
+     */
+    async unregisterProject(projectPath, pid) {
+        const registry = await this.readRegistry();
+        const absolutePath = resolve(projectPath);
+        const projectId = generateProjectId(absolutePath);
+        const entry = registry.get(projectId);
+        if (!entry)
+            return;
+        if (pid !== undefined) {
+            // Remove only this PID's instance
+            entry.instances = entry.instances.filter(i => i.pid !== pid);
+            if (entry.instances.length === 0) {
+                registry.delete(projectId);
+            }
+            else {
+                registry.set(projectId, entry);
+            }
+        }
+        else {
+            // Remove entire project (backwards compat)
+            registry.delete(projectId);
+        }
+        await this.writeRegistry(registry);
+    }
+    /**
+     * Unregister a project by projectId
+     */
+    async unregisterProjectById(projectId) {
+        const registry = await this.readRegistry();
+        registry.delete(projectId);
+        await this.writeRegistry(registry);
+    }
+    /**
+     * Get all active projects from the registry
+     */
+    async getAllProjects() {
+        const registry = await this.readRegistry();
+        return Array.from(registry.values());
+    }
+    /**
+     * Get a specific project by path
+     */
+    async getProject(projectPath) {
+        const registry = await this.readRegistry();
+        const absolutePath = resolve(projectPath);
+        const projectId = generateProjectId(absolutePath);
+        return registry.get(projectId) || null;
+    }
+    /**
+     * Get a specific project by projectId
+     */
+    async getProjectById(projectId) {
+        const registry = await this.readRegistry();
+        return registry.get(projectId) || null;
+    }
+    /**
+     * Clean up stale instances (where the process is no longer running)
+     * Projects with no live instances are removed entirely
+     * Returns the count of removed instances
+     */
+    async cleanupStaleProjects() {
+        const registry = await this.readRegistry();
+        let removedInstanceCount = 0;
+        let needsWrite = this.needsInitialization; // Write if file needs initialization
+        for (const [projectId, entry] of registry.entries()) {
+            const liveInstances = entry.instances.filter(i => this.isProcessAlive(i.pid));
+            const deadCount = entry.instances.length - liveInstances.length;
+            if (deadCount > 0) {
+                removedInstanceCount += deadCount;
+                needsWrite = true;
+                if (liveInstances.length === 0) {
+                    // No live instances, remove entire project
+                    registry.delete(projectId);
+                }
+                else {
+                    // Keep project with only live instances
+                    entry.instances = liveInstances;
+                    registry.set(projectId, entry);
+                }
+            }
+        }
+        if (needsWrite) {
+            await this.writeRegistry(registry);
+            this.needsInitialization = false; // Reset flag after successful write
+        }
+        return removedInstanceCount;
+    }
+    /**
+     * Check if a project is registered by path
+     */
+    async isProjectRegistered(projectPath) {
+        const registry = await this.readRegistry();
+        const absolutePath = resolve(projectPath);
+        const projectId = generateProjectId(absolutePath);
+        return registry.has(projectId);
+    }
+    /**
+     * Get the registry file path for watching
+     */
+    getRegistryPath() {
+        return this.registryPath;
+    }
+}
+//# sourceMappingURL=project-registry.js.map

package/dist/core/project-registry.js.map

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

package/dist/core/security-utils.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Security utilities for rate limiting and audit logging
+ * Implements security best practices for MCP servers
+ */
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { SecurityConfig } from '../types.js';
+export declare const DEFAULT_DASHBOARD_PORT = 5000;
+export declare const DEFAULT_SECURITY_CONFIG: SecurityConfig;
+export declare const VITE_DEV_PORT = 5173;
+/**
+ * Generate allowed origins for CORS based on the actual port
+ * @param port - The port the dashboard is running on
+ * @returns Array of allowed origin URLs
+ */
+export declare function generateAllowedOrigins(port: number): string[];
+/**
+ * Check if an IP address is localhost
+ * @param address - IP address or hostname to check
+ * @returns true if the address is localhost (127.x.x.x, localhost, or ::1)
+ */
+export declare function isLocalhostAddress(address: string): boolean;
+/**
+ * Get security configuration with secure defaults
+ * Note: Network binding validation (bindAddress/allowExternalAccess) is handled separately at the config layer
+ * @param userConfig - Optional user-provided security configuration overrides
+ * @param port - The port the dashboard is running on (used to generate dynamic allowedOrigins)
+ */
+export declare function getSecurityConfig(userConfig?: Partial<SecurityConfig>, port?: number): SecurityConfig;
+/**
+ * Rate limiting implementation
+ */
+export declare class RateLimiter {
+    private requests;
+    private config;
+    constructor(config: SecurityConfig);
+    /**
+     * Check if request should be rate limited
+     */
+    checkLimit(clientId: string): {
+        allowed: boolean;
+        retryAfter?: number;
+    };
+    /**
+     * Create rate limiting middleware
+     */
+    middleware(): (request: FastifyRequest, reply: FastifyReply) => Promise<undefined>;
+    /**
+     * Clean up old request records
+     */
+    private cleanup;
+}
+/**
+ * Audit log entry
+ */
+export interface AuditLogEntry {
+    timestamp: string;
+    actor: string;
+    action: string;
+    resource: string;
+    result: 'success' | 'failure' | 'denied';
+    details?: Record<string, any>;
+}
+/**
+ * Audit logger for security events
+ */
+export declare class AuditLogger {
+    private config;
+    private logPath;
+    constructor(config: SecurityConfig, workspaceRoot?: string);
+    /**
+     * Initialize audit log (create directory if needed)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Log an audit event
+     */
+    log(entry: AuditLogEntry): Promise<void>;
+    /**
+     * Create audit logging middleware
+     */
+    middleware(): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+}
+/**
+ * Security headers middleware
+ * @param port - The port the dashboard is running on (used for CSP connect-src for WebSocket)
+ */
+export declare function createSecurityHeadersMiddleware(port?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+/**
+ * CORS configuration
+ */
+export declare function getCorsConfig(config: SecurityConfig): false | {
+    origin: (origin: string, callback: (error: Error | null, allow?: boolean) => void) => void;
+    credentials: boolean;
+    methods: string[];
+    allowedHeaders: string[];
+};
+//# sourceMappingURL=security-utils.d.ts.map

package/dist/core/security-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-utils.d.ts","sourceRoot":"","sources":["../../src/core/security-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAI3C,eAAO,MAAM,uBAAuB,EAAE,cAOrC,CAAC;AAGF,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAW7D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CAarG;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,cAAc;IAOlC;;OAEG;IACI,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IA6B9E;;OAEG;IACI,UAAU,KACD,SAAS,cAAc,EAAE,OAAO,YAAY;IAmB5D;;OAEG;IACH,OAAO,CAAC,OAAO;CAahB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,MAAM;IAc1D;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C;;OAEG;IACH,UAAU,KACM,SAAS,cAAc,EAAE,OAAO,YAAY;CA0B7D;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,CAAC,EAAE,MAAM,IAW7C,SAAS,cAAc,EAAE,OAAO,YAAY,mBAe3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc;qBAM/B,MAAM,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI;;;;EAkBpF"}

package/dist/core/security-utils.js

@@ -0,0 +1,264 @@
+/**
+ * Security utilities for rate limiting and audit logging
+ * Implements security best practices for MCP servers
+ */
+import { appendFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+// Default port for the dashboard
+export const DEFAULT_DASHBOARD_PORT = 5000;
+// Default security configuration (secure by default)
+// Note: allowedOrigins should be dynamically generated based on the actual port
+export const DEFAULT_SECURITY_CONFIG = {
+    rateLimitEnabled: true,
+    rateLimitPerMinute: 120, // 120 requests per minute per client
+    auditLogEnabled: true,
+    auditLogRetentionDays: 30,
+    corsEnabled: true,
+    allowedOrigins: [`http://localhost:${DEFAULT_DASHBOARD_PORT}`, `http://127.0.0.1:${DEFAULT_DASHBOARD_PORT}`]
+};
+// Default Vite dev server port (used when running frontend in dev mode)
+export const VITE_DEV_PORT = 5173;
+/**
+ * Generate allowed origins for CORS based on the actual port
+ * @param port - The port the dashboard is running on
+ * @returns Array of allowed origin URLs
+ */
+export function generateAllowedOrigins(port) {
+    const origins = [`http://localhost:${port}`, `http://127.0.0.1:${port}`];
+    // In non-production environments, also allow Vite dev server origin (port 5173)
+    // The Vite proxy forwards requests but preserves the Origin header
+    // Use !== 'production' to be permissive by default for local dev tools
+    if (process.env.NODE_ENV !== 'production') {
+        origins.push(`http://localhost:${VITE_DEV_PORT}`, `http://127.0.0.1:${VITE_DEV_PORT}`);
+    }
+    return origins;
+}
+/**
+ * Check if an IP address is localhost
+ * @param address - IP address or hostname to check
+ * @returns true if the address is localhost (127.x.x.x, localhost, or ::1)
+ */
+export function isLocalhostAddress(address) {
+    return address === 'localhost' ||
+        address === '::1' || // IPv6 localhost
+        address.startsWith('127.'); // Any 127.x.x.x address (includes 127.0.0.1)
+}
+/**
+ * Get security configuration with secure defaults
+ * Note: Network binding validation (bindAddress/allowExternalAccess) is handled separately at the config layer
+ * @param userConfig - Optional user-provided security configuration overrides
+ * @param port - The port the dashboard is running on (used to generate dynamic allowedOrigins)
+ */
+export function getSecurityConfig(userConfig, port) {
+    const actualPort = port || DEFAULT_DASHBOARD_PORT;
+    // Generate dynamic allowedOrigins based on the actual port if not explicitly provided
+    const dynamicAllowedOrigins = generateAllowedOrigins(actualPort);
+    const config = {
+        ...DEFAULT_SECURITY_CONFIG,
+        allowedOrigins: dynamicAllowedOrigins,
+        ...userConfig
+    };
+    return config;
+}
+/**
+ * Rate limiting implementation
+ */
+export class RateLimiter {
+    requests = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+        // Clean up old entries every minute
+        setInterval(() => this.cleanup(), 60000);
+    }
+    /**
+     * Check if request should be rate limited
+     */
+    checkLimit(clientId) {
+        if (!this.config.rateLimitEnabled) {
+            return { allowed: true };
+        }
+        const now = Date.now();
+        const windowMs = 60000; // 1 minute window
+        const maxRequests = this.config.rateLimitPerMinute;
+        // Get client request history
+        const requests = this.requests.get(clientId) || [];
+        // Filter to requests within the current window
+        const recentRequests = requests.filter(timestamp => now - timestamp < windowMs);
+        // Check if limit exceeded
+        if (recentRequests.length >= maxRequests) {
+            const oldestRequest = recentRequests[0];
+            const retryAfter = Math.ceil((oldestRequest + windowMs - now) / 1000);
+            return { allowed: false, retryAfter };
+        }
+        // Add current request
+        recentRequests.push(now);
+        this.requests.set(clientId, recentRequests);
+        return { allowed: true };
+    }
+    /**
+     * Create rate limiting middleware
+     */
+    middleware() {
+        return async (request, reply) => {
+            // Use IP address as client identifier
+            const clientId = request.ip || 'unknown';
+            const result = this.checkLimit(clientId);
+            if (!result.allowed) {
+                return reply
+                    .code(429)
+                    .header('Retry-After', String(result.retryAfter || 60))
+                    .send({
+                    error: 'Too Many Requests',
+                    message: `Rate limit exceeded. Maximum ${this.config.rateLimitPerMinute} requests per minute.`,
+                    retryAfter: result.retryAfter
+                });
+            }
+        };
+    }
+    /**
+     * Clean up old request records
+     */
+    cleanup() {
+        const now = Date.now();
+        const windowMs = 60000;
+        for (const [clientId, requests] of this.requests.entries()) {
+            const recentRequests = requests.filter(timestamp => now - timestamp < windowMs);
+            if (recentRequests.length === 0) {
+                this.requests.delete(clientId);
+            }
+            else {
+                this.requests.set(clientId, recentRequests);
+            }
+        }
+    }
+}
+/**
+ * Audit logger for security events
+ */
+export class AuditLogger {
+    config;
+    logPath;
+    constructor(config, workspaceRoot) {
+        this.config = config;
+        // Determine audit log path
+        if (config.auditLogPath) {
+            this.logPath = config.auditLogPath;
+        }
+        else if (workspaceRoot) {
+            this.logPath = join(workspaceRoot, '.spec-workflow', 'audit.log');
+        }
+        else {
+            // Fallback to temp directory
+            this.logPath = join(process.cwd(), 'audit.log');
+        }
+    }
+    /**
+     * Initialize audit log (create directory if needed)
+     */
+    async initialize() {
+        if (!this.config.auditLogEnabled) {
+            return;
+        }
+        try {
+            const logDir = join(this.logPath, '..');
+            await mkdir(logDir, { recursive: true });
+        }
+        catch (error) {
+            console.error('Failed to initialize audit log:', error);
+        }
+    }
+    /**
+     * Log an audit event
+     */
+    async log(entry) {
+        if (!this.config.auditLogEnabled) {
+            return;
+        }
+        try {
+            const logLine = JSON.stringify(entry) + '\n';
+            await appendFile(this.logPath, logLine, 'utf-8');
+        }
+        catch (error) {
+            console.error('Failed to write audit log:', error);
+        }
+    }
+    /**
+     * Create audit logging middleware
+     */
+    middleware() {
+        return async (request, reply) => {
+            const startTime = Date.now();
+            // Log after response is sent using reply.then() which fires after response completes
+            reply.then(() => {
+                const entry = {
+                    timestamp: new Date().toISOString(),
+                    actor: request.ip || 'unknown',
+                    action: `${request.method} ${request.url}`,
+                    resource: request.url,
+                    result: reply.statusCode < 400 ? 'success' : reply.statusCode === 401 || reply.statusCode === 403 ? 'denied' : 'failure',
+                    details: {
+                        statusCode: reply.statusCode,
+                        duration: Date.now() - startTime,
+                        userAgent: request.headers['user-agent']
+                    }
+                };
+                // Fire and forget - don't await to avoid blocking
+                this.log(entry).catch(() => { });
+            }, () => { } // Ignore errors from reply.then
+            );
+        };
+    }
+}
+/**
+ * Security headers middleware
+ * @param port - The port the dashboard is running on (used for CSP connect-src for WebSocket)
+ */
+export function createSecurityHeadersMiddleware(port) {
+    const actualPort = port || DEFAULT_DASHBOARD_PORT;
+    // Build connect-src directive with WebSocket endpoints
+    let connectSrc = `'self' ws://localhost:${actualPort} ws://127.0.0.1:${actualPort}`;
+    // In non-production environments, also allow Vite dev server connections
+    if (process.env.NODE_ENV !== 'production') {
+        connectSrc += ` ws://localhost:${VITE_DEV_PORT} ws://127.0.0.1:${VITE_DEV_PORT}`;
+    }
+    return async (request, reply) => {
+        // Add security headers
+        reply.header('X-Content-Type-Options', 'nosniff'); // Prevent MIME type sniffing
+        reply.header('X-Frame-Options', 'DENY'); // Prevent clickjacking
+        reply.header('X-XSS-Protection', '1; mode=block'); // Enable XSS protection
+        reply.header('Referrer-Policy', 'strict-origin-when-cross-origin'); // Prevent referrer leakage
+        // CSP for dashboard
+        // Note: cdn.jsdelivr.net is required for highlight.js stylesheets used by the MDX editor
+        // connect-src allows WebSocket connections to the dashboard on the actual port
+        reply.header('Content-Security-Policy', `default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data:; connect-src ${connectSrc};`);
+    };
+}
+/**
+ * CORS configuration
+ */
+export function getCorsConfig(config) {
+    if (!config.corsEnabled) {
+        return false; // Disable CORS
+    }
+    return {
+        origin: (origin, callback) => {
+            // Allow requests with no origin (e.g., curl, Postman)
+            if (!origin) {
+                callback(null, true);
+                return;
+            }
+            // Check if origin is in allowed list
+            if (config.allowedOrigins.includes(origin)) {
+                callback(null, true);
+            }
+            else {
+                callback(new Error('Not allowed by CORS'));
+            }
+        },
+        credentials: true,
+        methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+        allowedHeaders: ['Content-Type']
+    };
+}
+//# sourceMappingURL=security-utils.js.map