@mhingston5/conduit 1.0.0

package/src/core/metrics.service.ts

@@ -0,0 +1,112 @@
+import { metrics as otelMetrics, Counter, Histogram, ObservableGauge, ValueType } from '@opentelemetry/api';
+
+export class MetricsService {
+    private static instance: MetricsService;
+    private meter = otelMetrics.getMeter('conduit');
+
+    private executionCounter: Counter;
+    private cacheHitsCounter: Counter;
+    private cacheMissesCounter: Counter;
+    private executionLatency: Histogram;
+    private toolExecutionDuration: Histogram;
+    private requestQueueLength: ObservableGauge;
+    private activeExecutionsGauge: ObservableGauge;
+
+    private activeExecutionsCount = 0;
+
+    private queueLengthCallback: () => number = () => 0;
+
+    private constructor() {
+        this.executionCounter = this.meter.createCounter('conduit.executions.total', {
+            description: 'Total number of executions',
+        });
+
+        this.cacheHitsCounter = this.meter.createCounter('conduit.cache.hits.total', {
+            description: 'Total number of schema cache hits',
+        });
+
+        this.cacheMissesCounter = this.meter.createCounter('conduit.cache.misses.total', {
+            description: 'Total number of schema cache misses',
+        });
+
+        this.executionLatency = this.meter.createHistogram('conduit.executions.latency', {
+            description: 'Execution latency in milliseconds',
+            unit: 'ms',
+            valueType: ValueType.DOUBLE,
+        });
+
+        this.toolExecutionDuration = this.meter.createHistogram('conduit.tool.execution_duration_seconds', {
+            description: 'Duration of tool executions',
+            unit: 's',
+            valueType: ValueType.DOUBLE,
+        });
+
+        this.requestQueueLength = this.meter.createObservableGauge('conduit.request_queue_length', {
+            description: 'Current request queue depth',
+            valueType: ValueType.INT,
+        });
+
+        this.activeExecutionsGauge = this.meter.createObservableGauge('conduit.executions.active', {
+            description: 'Current number of active executions',
+        });
+
+        this.activeExecutionsGauge.addCallback((result) => {
+            result.observe(this.activeExecutionsCount);
+        });
+
+        this.requestQueueLength.addCallback((result) => {
+            result.observe(this.queueLengthCallback());
+        });
+    }
+
+    static getInstance(): MetricsService {
+        if (!MetricsService.instance) {
+            MetricsService.instance = new MetricsService();
+        }
+        return MetricsService.instance;
+    }
+
+    recordExecutionStart() {
+        this.activeExecutionsCount++;
+        this.executionCounter.add(1);
+    }
+
+    recordExecutionEnd(durationMs: number, toolName?: string) {
+        this.activeExecutionsCount = Math.max(0, this.activeExecutionsCount - 1);
+        this.executionLatency.record(durationMs, { tool: toolName || 'unknown' });
+    }
+
+    recordToolExecution(durationMs: number, toolName: string, success: boolean) {
+        // Convert ms to seconds for the histogram
+        this.toolExecutionDuration.record(durationMs / 1000, {
+            tool_name: toolName,
+            success: String(success)
+        });
+    }
+
+    recordCacheHit() {
+        this.cacheHitsCounter.add(1);
+    }
+
+    recordCacheMiss() {
+        this.cacheMissesCounter.add(1);
+    }
+
+    // This is now handled by OTEL Prometheus exporter, 
+    // but we can provide a way to get the endpoint data if needed.
+
+
+    getMetrics() {
+        return {
+            activeExecutions: this.activeExecutionsCount,
+            uptime: process.uptime(),
+            memory: process.memoryUsage(),
+        };
+    }
+
+    registerQueueLengthProvider(provider: () => number) {
+        this.queueLengthCallback = provider;
+    }
+}
+
+export const metrics = MetricsService.getInstance();

package/src/core/middleware/auth.middleware.ts

@@ -0,0 +1,56 @@
+import { Middleware, NextFunction } from '../interfaces/middleware.interface.js';
+import { JSONRPCRequest, JSONRPCResponse, ConduitError } from '../types.js';
+import { ExecutionContext } from '../execution.context.js';
+import { SecurityService } from '../security.service.js';
+
+export class AuthMiddleware implements Middleware {
+    constructor(private securityService: SecurityService) { }
+
+    async handle(
+        request: JSONRPCRequest,
+        context: ExecutionContext,
+        next: NextFunction
+    ): Promise<JSONRPCResponse> {
+        const providedToken = request.auth?.bearerToken || '';
+
+        const isMaster = providedToken === this.securityService.getIpcToken();
+        const isSession = this.securityService.validateIpcToken(providedToken) && !isMaster;
+
+        if (!isMaster && !isSession) {
+            return {
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: ConduitError.Forbidden,
+                    message: 'Invalid bearer token'
+                }
+            };
+        }
+
+        // Strict scoping for session tokens
+        if (isSession) {
+            const allowedMethods = ['mcp.discoverTools', 'mcp.callTool'];
+            if (!allowedMethods.includes(request.method)) {
+                return {
+                    jsonrpc: '2.0',
+                    id: request.id,
+                    error: {
+                        code: ConduitError.Forbidden,
+                        message: 'Session tokens are restricted to tool discovery and calling only'
+                    }
+                };
+            }
+
+            // Enrich context with session details if needed
+            const session = this.securityService.getSession(providedToken);
+            if (session?.allowedTools && !context.allowedTools) {
+                // If context didn't already have specific tools (e.g. from request params override which shouldn't happen for sessions generally, 
+                // but usually session allowedTools wins or merges. 
+                // In generic logic, let's respect session.
+                context.allowedTools = session.allowedTools;
+            }
+        }
+
+        return next();
+    }
+}

package/src/core/middleware/error.middleware.ts

@@ -0,0 +1,21 @@
+import { Middleware, NextFunction } from '../interfaces/middleware.interface.js';
+import { JSONRPCRequest, JSONRPCResponse, ConduitError } from '../types.js';
+import { ExecutionContext } from '../execution.context.js';
+
+export class ErrorHandlingMiddleware implements Middleware {
+    async handle(request: JSONRPCRequest, context: ExecutionContext, next: NextFunction): Promise<JSONRPCResponse> {
+        try {
+            return await next();
+        } catch (err: any) {
+            context.logger.error({ err }, 'Error handling request');
+            return {
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: ConduitError.InternalError,
+                    message: err.message || 'Internal Server Error',
+                },
+            };
+        }
+    }
+}

package/src/core/middleware/logging.middleware.ts

@@ -0,0 +1,25 @@
+import { Middleware, NextFunction } from '../interfaces/middleware.interface.js';
+import { JSONRPCRequest, JSONRPCResponse } from '../types.js';
+import { ExecutionContext } from '../execution.context.js';
+import { metrics } from '../metrics.service.js';
+
+export class LoggingMiddleware implements Middleware {
+    async handle(request: JSONRPCRequest, context: ExecutionContext, next: NextFunction): Promise<JSONRPCResponse> {
+        const { method, id } = request;
+        const childLogger = context.logger.child({ method, id });
+        context.logger = childLogger; // Update context logger for downstream
+
+        metrics.recordExecutionStart();
+        const startTime = Date.now();
+
+        try {
+            const response = await next();
+            metrics.recordExecutionEnd(Date.now() - startTime, method);
+            return response;
+        } catch (err) {
+            // Should be caught by ErrorMiddleware, but just in case
+            metrics.recordExecutionEnd(Date.now() - startTime, method);
+            throw err;
+        }
+    }
+}

package/src/core/middleware/middleware.builder.ts

@@ -0,0 +1,24 @@
+/**
+ * MiddlewareBuilder - Factory for building middleware pipelines
+ * Extracted from RequestController per architecture-findings.md
+ */
+
+import { Middleware } from '../interfaces/middleware.interface.js';
+import { ErrorHandlingMiddleware } from './error.middleware.js';
+import { LoggingMiddleware } from './logging.middleware.js';
+import { AuthMiddleware } from './auth.middleware.js';
+import { RateLimitMiddleware } from './ratelimit.middleware.js';
+import { SecurityService } from '../security.service.js';
+
+/**
+ * Build the default middleware pipeline used by RequestController.
+ * This centralizes middleware configuration outside the controller.
+ */
+export function buildDefaultMiddleware(securityService: SecurityService): Middleware[] {
+    return [
+        new ErrorHandlingMiddleware(),
+        new LoggingMiddleware(),
+        new AuthMiddleware(securityService),
+        new RateLimitMiddleware(securityService),
+    ];
+}

package/src/core/middleware/ratelimit.middleware.ts

@@ -0,0 +1,31 @@
+import { Middleware, NextFunction } from '../interfaces/middleware.interface.js';
+import { JSONRPCRequest, JSONRPCResponse, ConduitError } from '../types.js';
+import { ExecutionContext } from '../execution.context.js';
+import { SecurityService } from '../security.service.js';
+
+export class RateLimitMiddleware implements Middleware {
+    constructor(private securityService: SecurityService) { }
+
+    async handle(
+        request: JSONRPCRequest,
+        context: ExecutionContext,
+        next: NextFunction
+    ): Promise<JSONRPCResponse> {
+        const providedToken = request.auth?.bearerToken;
+        // Use token if available, otherwise fallback to remote address from context
+        const rateLimitKey = providedToken || context.remoteAddress || 'unknown';
+
+        if (!this.securityService.checkRateLimit(rateLimitKey)) {
+            return {
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: -32005, // Rate limit exceeded code
+                    message: 'Rate limit exceeded'
+                }
+            };
+        }
+
+        return next();
+    }
+}

package/src/core/network.policy.service.ts

@@ -0,0 +1,106 @@
+import { Logger } from 'pino';
+import dns from 'node:dns/promises';
+import net from 'node:net';
+import { LRUCache } from 'lru-cache';
+
+export class NetworkPolicyService {
+    private logger: Logger;
+
+    private readonly privateRanges = [
+        /^127\./,
+        /^10\./,
+        /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+        /^192\.168\./,
+        /^169\.254\./, // Link-local
+        /^localhost$/i,
+        /^0\.0\.0\.0$/,
+        /^::1$/, // IPv6 localhost
+        /^fc00:/i, // IPv6 private
+        /^fe80:/i, // IPv6 link-local
+    ];
+
+    private readonly RATE_LIMIT = 30;
+    private readonly WINDOW_MS = 60000;
+    // Use LRUCache to prevent unbounded memory growth
+    private requestCounts: LRUCache<string, { count: number; resetTime: number }>;
+
+    constructor(logger: Logger) {
+        this.logger = logger;
+        this.requestCounts = new LRUCache({
+            max: 10000,
+            ttl: this.WINDOW_MS,
+        });
+    }
+
+    async validateUrl(url: string): Promise<{ valid: boolean; message?: string; resolvedIp?: string }> {
+        try {
+            const parsed = new URL(url);
+            const hostname = parsed.hostname;
+
+            // Check literal hostname against private ranges
+            for (const range of this.privateRanges) {
+                if (range.test(hostname)) {
+                    this.logger.warn({ hostname }, 'SSRF attempt detected: private range access');
+                    return { valid: false, message: 'Access denied: private network access forbidden' };
+                }
+            }
+
+            // DNS resolution check to prevent DNS rebinding and handle tricky hostnames
+            if (!net.isIP(hostname)) {
+                try {
+                    const lookup = await dns.lookup(hostname, { all: true });
+                    // Store resolved IPs to check against blocklist
+                    const resolvedIps: string[] = [];
+
+                    for (const address of lookup) {
+                        let ip = address.address;
+
+                        // Fix Sev0: Normalize IPv6-mapped IPv4 addresses
+                        if (ip.startsWith('::ffff:')) {
+                            ip = ip.substring(7);
+                        }
+
+                        for (const range of this.privateRanges) {
+                            if (range.test(ip)) {
+                                this.logger.warn({ hostname, ip }, 'SSRF attempt detected: DNS resolves to private IP');
+                                return { valid: false, message: 'Access denied: hostname resolves to private network' };
+                            }
+                        }
+                        resolvedIps.push(ip);
+                    }
+
+                    // Fix Sev1: Return the validated IP to prevent DNS rebinding
+                    // Use the first resolved IP
+                    return { valid: true, resolvedIp: resolvedIps[0] };
+                } catch (err: any) {
+                    // Strict SSRF protection: block if DNS lookup fails
+                    this.logger.warn({ hostname, err: err.message }, 'DNS lookup failed during URL validation, blocking request');
+                    return { valid: false, message: 'Access denied: hostname resolution failed' };
+                }
+            }
+
+            // If it was already an IP, it's valid if it passed the range check above
+            return { valid: true, resolvedIp: hostname };
+        } catch (err: any) {
+            return { valid: false, message: `Invalid URL: ${err.message}` };
+        }
+    }
+
+    checkRateLimit(key: string): boolean {
+        const now = Date.now();
+        const record = this.requestCounts.get(key);
+
+        if (!record || now > record.resetTime) {
+            this.requestCounts.set(key, { count: 1, resetTime: now + this.WINDOW_MS });
+            return true;
+        }
+
+        if (record.count >= this.RATE_LIMIT) {
+            this.logger.warn({ key }, 'Rate limit exceeded');
+            return false;
+        }
+
+        record.count++;
+        return true;
+    }
+}

package/src/core/ops.server.ts

@@ -0,0 +1,74 @@
+import Fastify from 'fastify';
+import { Logger } from 'pino';
+import { AppConfig } from './interfaces/app.config.js';
+import { GatewayService } from '../gateway/gateway.service.js';
+import { metrics } from './metrics.service.js';
+import { RequestController } from './request.controller.js';
+import axios from 'axios';
+
+export class OpsServer {
+    private fastify = Fastify();
+    private logger: Logger;
+    private config: AppConfig;
+    private gatewayService: GatewayService;
+    private requestController: RequestController;
+
+    constructor(logger: Logger, config: AppConfig, gatewayService: GatewayService, requestController: RequestController) {
+        this.logger = logger;
+        this.config = config;
+        this.gatewayService = gatewayService;
+        this.requestController = requestController;
+
+        this.setupRoutes();
+    }
+
+    private setupRoutes() {
+        this.fastify.get('/health', async (request, reply) => {
+            const gatewayHealth = await this.gatewayService.healthCheck();
+            const requestHealth = await this.requestController.healthCheck();
+
+            const overallStatus = gatewayHealth.status === 'ok' && requestHealth.status === 'ok' ? 'ok' : 'error';
+
+            return reply.status(overallStatus === 'ok' ? 200 : 503).send({
+                status: overallStatus,
+                version: '1.0.0',
+                gateway: gatewayHealth,
+                request: requestHealth,
+            });
+        });
+
+        this.fastify.get('/metrics', async (request, reply) => {
+            try {
+                // Proxy from OTEL Prometheus exporter
+                // Use ConfigService for metrics URL, default to standard localhost:9464
+                const metricsUrl = this.config.metricsUrl || 'http://127.0.0.1:9464/metrics';
+                const response = await axios.get(metricsUrl);
+                return reply.type('text/plain').send(response.data);
+            } catch (err) {
+                this.logger.error({ err }, 'Failed to fetch OTEL metrics');
+                // Fallback to minimal metrics if OTEL exporter is down
+                const fallback = '# Metrics consolidated into OpenTelemetry. Check port 9464.\n' +
+                    `conduit_uptime_seconds ${process.uptime()}\n` +
+                    `conduit_memory_rss_bytes ${process.memoryUsage().rss}\n`;
+                return reply.type('text/plain').send(fallback);
+            }
+        });
+    }
+
+    async listen(): Promise<string> {
+        // Use explicit opsPort from config
+        const port = this.config.opsPort || 3001;
+        try {
+            const address = await this.fastify.listen({ port, host: '0.0.0.0' });
+            this.logger.info({ address }, 'Ops server listening');
+            return address;
+        } catch (err) {
+            this.logger.error({ err }, 'Failed to start Ops server');
+            throw err;
+        }
+    }
+
+    async close() {
+        await this.fastify.close();
+    }
+}

package/src/core/otel.service.ts

@@ -0,0 +1,41 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import { PinoInstrumentation } from '@opentelemetry/instrumentation-pino';
+
+export class OtelService {
+    private sdk: NodeSDK | null = null;
+
+    constructor(private logger: any) { }
+
+    async start() {
+        this.sdk = new NodeSDK({
+            resource: resourceFromAttributes({
+                [SemanticResourceAttributes.SERVICE_NAME]: 'conduit',
+            }),
+            metricReader: new PrometheusExporter({
+                port: 9464, // Default prometheus exporter port
+            }),
+            instrumentations: [
+                getNodeAutoInstrumentations(),
+                new PinoInstrumentation(),
+            ],
+        });
+
+        try {
+            await this.sdk.start();
+            this.logger.info('OpenTelemetry SDK started');
+        } catch (error) {
+            this.logger.error({ error }, 'Error starting OpenTelemetry SDK');
+        }
+    }
+
+    async shutdown() {
+        if (this.sdk) {
+            await this.sdk.shutdown();
+            this.logger.info('OpenTelemetry SDK shut down');
+        }
+    }
+}

package/src/core/policy.service.ts

@@ -0,0 +1,77 @@
+/**
+ * PolicyService - Authorization and tool access control
+ * Extracted from GatewayService per architecture-findings.md
+ */
+
+/**
+ * Structured identifier for a tool, replacing fragile `upstream__toolname` strings.
+ */
+export interface ToolIdentifier {
+    namespace: string;  // upstream ID (e.g., "github")
+    name: string;       // tool name (e.g., "createIssue")
+}
+
+export class PolicyService {
+    /**
+     * Parse a qualified tool name string into a structured ToolIdentifier.
+     * @param qualifiedName - e.g., "github__createIssue" or "github__api__listRepos"
+     */
+    parseToolName(qualifiedName: string): ToolIdentifier {
+        const separatorIndex = qualifiedName.indexOf('__');
+        if (separatorIndex === -1) {
+            // No namespace - treat entire string as name with empty namespace
+            return { namespace: '', name: qualifiedName };
+        }
+        return {
+            namespace: qualifiedName.substring(0, separatorIndex),
+            name: qualifiedName.substring(separatorIndex + 2)
+        };
+    }
+
+    /**
+     * Format a ToolIdentifier back to a qualified string.
+     */
+    formatToolName(tool: ToolIdentifier): string {
+        if (!tool.namespace) {
+            return tool.name;
+        }
+        return `${tool.namespace}__${tool.name}`;
+    }
+
+    /**
+     * Check if a tool matches any pattern in the allowlist.
+     * Supports:
+     *   - Exact match: "github.createIssue" matches "github__createIssue"
+     *   - Wildcard: "github.*" matches any tool in the github namespace
+     * 
+     * @param tool - ToolIdentifier or qualified string
+     * @param allowedTools - Array of patterns (dot-notation, e.g., "github.*" or "github.createIssue")
+     */
+    isToolAllowed(tool: ToolIdentifier | string, allowedTools: string[]): boolean {
+        const toolId = typeof tool === 'string' ? this.parseToolName(tool) : tool;
+        const toolParts = [toolId.namespace, ...toolId.name.split('__')].filter(p => p);
+
+        return allowedTools.some(pattern => {
+            const patternParts = pattern.split('.');
+
+            // Wildcard pattern: "foo.*" or "foo.bar.*"
+            if (patternParts[patternParts.length - 1] === '*') {
+                const prefixParts = patternParts.slice(0, -1);
+                if (prefixParts.length > toolParts.length) return false;
+
+                // Check if prefix parts match tool parts exactly
+                for (let i = 0; i < prefixParts.length; i++) {
+                    if (prefixParts[i] !== toolParts[i]) return false;
+                }
+                return true;
+            }
+
+            // Exact match: pattern parts must equal tool parts
+            if (patternParts.length !== toolParts.length) return false;
+            for (let i = 0; i < patternParts.length; i++) {
+                if (patternParts[i] !== toolParts[i]) return false;
+            }
+            return true;
+        });
+    }
+}

package/src/core/registries/executor.registry.ts

@@ -0,0 +1,26 @@
+import { Executor } from '../interfaces/executor.interface.js';
+
+export class ExecutorRegistry {
+    private executors = new Map<string, Executor>();
+
+    register(name: string, executor: Executor): void {
+        this.executors.set(name, executor);
+    }
+
+    get(name: string): Executor | undefined {
+        return this.executors.get(name);
+    }
+
+    has(name: string): boolean {
+        return this.executors.has(name);
+    }
+
+    async shutdownAll(): Promise<void> {
+        for (const executor of this.executors.values()) {
+            if (executor.shutdown) {
+                await executor.shutdown();
+            }
+        }
+        this.executors.clear();
+    }
+}