@quint-security/proxy 0.1.2

package/src/http-relay.ts

@@ -0,0 +1,228 @@
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { EventEmitter } from "node:events";
+
+export interface HttpRelayEvents {
+  /** Fired for every JSON-RPC request received from the agent via HTTP */
+  request: (line: string) => void;
+  /** Fired for every JSON-RPC response received from the remote server */
+  response: (line: string) => void;
+  /** Unrecoverable error */
+  error: (err: Error) => void;
+}
+
+interface PendingRequest {
+  res: ServerResponse;
+  body: string;
+  headers: Record<string, string>;
+}
+
+/**
+ * Optional auth check function. Return null/undefined if auth passes,
+ * or an error message string to reject the request with 401.
+ */
+export type AuthCheckFn = (req: IncomingMessage) => string | undefined | null;
+
+/**
+ * HttpRelay manages:
+ *  - Running a local HTTP server that accepts JSON-RPC POST requests
+ *  - Forwarding allowed requests to a remote MCP server via fetch()
+ *  - Streaming SSE responses back when the remote uses text/event-stream
+ *
+ * The interceptor hooks into request/response events to inspect,
+ * allow, deny, or modify messages before they are forwarded.
+ */
+export class HttpRelay extends EventEmitter {
+  private server: Server | null = null;
+  private port: number;
+  private targetUrl: string;
+  private pending: Map<string, PendingRequest> = new Map();
+  private requestCounter = 0;
+  private authCheck: AuthCheckFn | null = null;
+
+  constructor(port: number, targetUrl: string, authCheck?: AuthCheckFn) {
+    super();
+    this.port = port;
+    this.targetUrl = targetUrl;
+    this.authCheck = authCheck ?? null;
+  }
+
+  start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server = createServer((req, res) => {
+        this.handleRequest(req, res);
+      });
+
+      this.server.on("error", (err) => {
+        this.emit("error", err);
+        reject(err);
+      });
+
+      this.server.listen(this.port, () => {
+        resolve();
+      });
+    });
+  }
+
+  stop(): void {
+    this.server?.close();
+  }
+
+  /**
+   * Send a deny response back to the HTTP client for a given pending request.
+   */
+  respondToClient(requestKey: string, body: string): void {
+    const pending = this.pending.get(requestKey);
+    if (!pending) return;
+    this.pending.delete(requestKey);
+
+    pending.res.writeHead(200, { "Content-Type": "application/json" });
+    pending.res.end(body);
+  }
+
+  /**
+   * Forward the original request to the remote MCP server and relay the response.
+   */
+  async forwardToRemote(requestKey: string): Promise<void> {
+    const pending = this.pending.get(requestKey);
+    if (!pending) return;
+    this.pending.delete(requestKey);
+
+    try {
+      // Forward relevant headers from the original request to the remote server
+      const forwardHeaders: Record<string, string> = {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+      };
+      if (pending.headers.authorization) {
+        forwardHeaders["Authorization"] = pending.headers.authorization;
+      }
+
+      const remoteRes = await fetch(this.targetUrl, {
+        method: "POST",
+        headers: forwardHeaders,
+        body: pending.body,
+      });
+
+      const contentType = remoteRes.headers.get("content-type") ?? "";
+
+      if (contentType.includes("text/event-stream") && remoteRes.body) {
+        // SSE streaming — relay each event back to the client
+        pending.res.writeHead(remoteRes.status, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        });
+
+        const reader = remoteRes.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            const chunk = decoder.decode(value, { stream: true });
+            buffer += chunk;
+            pending.res.write(chunk);
+
+            // Extract complete SSE data lines for logging
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+              if (line.startsWith("data: ")) {
+                const data = line.slice(6).trim();
+                if (data) {
+                  this.emit("response", data);
+                }
+              }
+            }
+          }
+        } finally {
+          // Flush remaining buffer
+          if (buffer.startsWith("data: ")) {
+            const data = buffer.slice(6).trim();
+            if (data) {
+              this.emit("response", data);
+            }
+          }
+          pending.res.end();
+        }
+      } else {
+        // Standard JSON response
+        const responseBody = await remoteRes.text();
+        this.emit("response", responseBody);
+
+        pending.res.writeHead(remoteRes.status, {
+          "Content-Type": contentType || "application/json",
+        });
+        pending.res.end(responseBody);
+      }
+    } catch (err) {
+      const errorBody = JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32603,
+          message: `Quint: failed to reach remote server: ${(err as Error).message}`,
+        },
+      });
+      this.emit("response", errorBody);
+      pending.res.writeHead(502, { "Content-Type": "application/json" });
+      pending.res.end(errorBody);
+    }
+  }
+
+  private handleRequest(req: IncomingMessage, res: ServerResponse): void {
+    // Only handle POST requests
+    if (req.method !== "POST") {
+      res.writeHead(405, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Method not allowed. Use POST." }));
+      return;
+    }
+
+    // CORS preflight support
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+
+    // Auth check (if configured)
+    if (this.authCheck) {
+      const authError = this.authCheck(req);
+      if (authError) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32600, message: authError },
+        }));
+        return;
+      }
+    }
+
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => {
+      const body = Buffer.concat(chunks).toString("utf-8");
+      const requestKey = String(++this.requestCounter);
+
+      // Capture headers to forward to remote server
+      const headers: Record<string, string> = {};
+      for (const key of ["authorization", "content-type", "accept"]) {
+        const val = req.headers[key];
+        if (typeof val === "string") headers[key] = val;
+      }
+
+      this.pending.set(requestKey, { res, body, headers });
+
+      // Emit the request for the interceptor to inspect.
+      // The interceptor will call respondToClient() for denials
+      // or forwardToRemote() for allowed requests.
+      this.emit("request", body, requestKey);
+    });
+
+    req.on("error", (err) => {
+      this.emit("error", err);
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,178 @@
+import {
+  type PolicyConfig,
+  ensureKeyPair,
+  openAuditDb,
+  resolveDataDir,
+  setLogLevel,
+  logDebug,
+  logInfo,
+  logWarn,
+  logError,
+  RiskEngine,
+} from "@quint-security/core";
+import { Relay } from "./relay.js";
+import { inspectRequest, inspectResponse, buildDenyResponse } from "./interceptor.js";
+import { AuditLogger } from "./logger.js";
+
+export { Relay } from "./relay.js";
+export { HttpRelay } from "./http-relay.js";
+export { inspectRequest, inspectResponse, buildDenyResponse } from "./interceptor.js";
+export { AuditLogger } from "./logger.js";
+export { startHttpProxy } from "./http-proxy.js";
+
+export interface ProxyOptions {
+  serverName: string;
+  command: string;
+  args: string[];
+  policy: PolicyConfig;
+}
+
+/**
+ * Start the proxy: spawn child MCP server, intercept all JSON-RPC
+ * messages, enforce policy, sign and log everything.
+ */
+export function startProxy(opts: ProxyOptions): void {
+  setLogLevel(opts.policy.log_level);
+  const dataDir = resolveDataDir(opts.policy.data_dir);
+
+  // Ensure signing keys exist
+  const kp = ensureKeyPair(dataDir);
+
+  // Open audit database
+  const db = openAuditDb(dataDir);
+
+  // Create audit logger
+  const logger = new AuditLogger(db, kp.privateKey, kp.publicKey, opts.policy);
+
+  // Create risk engine
+  const riskEngine = new RiskEngine();
+
+  // Create relay
+  const relay = new Relay(opts.command, opts.args);
+
+  // ── Handle messages from parent (AI agent) → child (MCP server) ──
+
+  relay.on("parentMessage", (line: string) => {
+    const result = inspectRequest(line, opts.serverName, opts.policy);
+
+    // For non-tool-call requests, log immediately. Tool calls get logged after risk scoring.
+    if (!result.toolName || result.verdict === "deny") {
+      logger.log({
+        serverName: opts.serverName,
+        direction: "request",
+        method: result.method,
+        messageId: result.messageId,
+        toolName: result.toolName,
+        argumentsJson: result.argumentsJson,
+        responseJson: null,
+        verdict: result.verdict,
+      });
+    }
+
+    if (result.verdict === "deny") {
+      const reqId = result.message && "id" in result.message ? result.message.id : null;
+      const errorResponse = buildDenyResponse(reqId ?? null);
+      relay.sendToParent(errorResponse);
+      logInfo(`denied ${result.toolName} on ${opts.serverName}`);
+
+      logger.log({
+        serverName: opts.serverName,
+        direction: "response",
+        method: result.method,
+        messageId: result.messageId,
+        toolName: result.toolName,
+        argumentsJson: null,
+        responseJson: errorResponse,
+        verdict: "deny",
+      });
+    } else if (result.toolName) {
+      const risk = riskEngine.score(result.toolName, result.argumentsJson, "anonymous");
+      const riskAction = riskEngine.evaluate(risk);
+
+      // Re-log the request with risk score attached
+      logger.log({
+        serverName: opts.serverName,
+        direction: "request",
+        method: result.method,
+        messageId: result.messageId,
+        toolName: result.toolName,
+        argumentsJson: result.argumentsJson,
+        responseJson: null,
+        verdict: result.verdict,
+        riskScore: risk.score,
+        riskLevel: risk.level,
+      });
+
+      if (riskAction === "deny") {
+        const reqId = result.message && "id" in result.message ? result.message.id : null;
+        const errorResponse = buildDenyResponse(reqId ?? null);
+        relay.sendToParent(errorResponse);
+        logWarn(`risk-denied ${result.toolName} (score=${risk.score}, level=${risk.level}): ${risk.reasons.join("; ")}`);
+
+        logger.log({
+          serverName: opts.serverName,
+          direction: "response",
+          method: result.method,
+          messageId: result.messageId,
+          toolName: result.toolName,
+          argumentsJson: null,
+          responseJson: errorResponse,
+          verdict: "deny",
+          riskScore: risk.score,
+          riskLevel: risk.level,
+        });
+      } else {
+        if (riskAction === "flag") {
+          logWarn(`high-risk ${result.toolName} (score=${risk.score}, level=${risk.level}): ${risk.reasons.join("; ")}`);
+        }
+        logDebug(`forwarding ${result.method} (risk=${risk.score}) to child`);
+        relay.sendToChild(line);
+      }
+
+      if (riskEngine.shouldRevoke("anonymous")) {
+        logWarn(`repeated high-risk actions detected — consider revoking agent credentials`);
+      }
+    } else {
+      // Non-tool-call — forward directly
+      logDebug(`forwarding ${result.method} (${result.verdict}) to child`);
+      relay.sendToChild(line);
+    }
+  });
+
+  // ── Handle messages from child (MCP server) → parent (AI agent) ──
+
+  relay.on("childMessage", (line: string) => {
+    const result = inspectResponse(line);
+
+    // Log the response
+    logger.log({
+      serverName: opts.serverName,
+      direction: "response",
+      method: result.method,
+      messageId: result.messageId,
+      toolName: null,
+      argumentsJson: null,
+      responseJson: result.responseJson,
+      verdict: "passthrough",
+    });
+
+    // Always forward responses to parent
+    relay.sendToParent(line);
+  });
+
+  // ── Handle child exit ──
+
+  relay.on("childExit", (code: number | null) => {
+    db.close();
+    process.exit(code ?? 0);
+  });
+
+  relay.on("error", (err: Error) => {
+    logError(`relay error: ${err.message}`);
+    db.close();
+    process.exit(1);
+  });
+
+  // Start
+  relay.start();
+}

package/src/interceptor.ts

@@ -0,0 +1,127 @@
+import {
+  type JsonRpcRequest,
+  type JsonRpcMessage,
+  type Verdict,
+  type PolicyConfig,
+  isJsonRpcRequest,
+  isToolCallRequest,
+  extractToolInfo,
+  evaluatePolicy,
+} from "@quint-security/core";
+
+export interface InspectionResult {
+  /** The parsed JSON-RPC message (null if line is not valid JSON-RPC) */
+  message: JsonRpcMessage | null;
+  /** Policy verdict */
+  verdict: Verdict;
+  /** Extracted tool name (for tools/call requests) */
+  toolName: string | null;
+  /** Extracted tool arguments as JSON string */
+  argumentsJson: string | null;
+  /** JSON-RPC method */
+  method: string;
+  /** JSON-RPC id */
+  messageId: string | null;
+}
+
+/**
+ * Try to parse a line as JSON-RPC and determine the policy verdict.
+ * Non-parseable lines or non-tools/call methods get "passthrough".
+ */
+export function inspectRequest(
+  line: string,
+  serverName: string,
+  policy: PolicyConfig,
+): InspectionResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return {
+      message: null,
+      verdict: "passthrough",
+      toolName: null,
+      argumentsJson: null,
+      method: "unknown",
+      messageId: null,
+    };
+  }
+
+  if (!isJsonRpcRequest(parsed)) {
+    return {
+      message: parsed as JsonRpcMessage,
+      verdict: "passthrough",
+      toolName: null,
+      argumentsJson: null,
+      method: "unknown",
+      messageId: extractId(parsed),
+    };
+  }
+
+  const req = parsed as JsonRpcRequest;
+  const toolInfo = extractToolInfo(req);
+  const toolName = toolInfo?.name ?? null;
+  const argumentsJson = toolInfo ? JSON.stringify(toolInfo.args) : null;
+
+  // Only policy-check tools/call; everything else is passthrough
+  let verdict: Verdict;
+  if (isToolCallRequest(req)) {
+    verdict = evaluatePolicy(policy, serverName, toolName);
+  } else {
+    verdict = "passthrough";
+  }
+
+  return {
+    message: req,
+    verdict,
+    toolName,
+    argumentsJson,
+    method: req.method,
+    messageId: req.id != null ? String(req.id) : null,
+  };
+}
+
+/**
+ * Inspect a response line from the child (just for logging purposes — responses always pass through).
+ */
+export function inspectResponse(line: string): {
+  method: string;
+  messageId: string | null;
+  responseJson: string | null;
+} {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return { method: "unknown", messageId: null, responseJson: null };
+  }
+
+  return {
+    method: "response",
+    messageId: extractId(parsed),
+    responseJson: line,
+  };
+}
+
+/**
+ * Build a JSON-RPC error response for a denied tool call.
+ */
+export function buildDenyResponse(requestId: string | number | null): string {
+  const response = {
+    jsonrpc: "2.0" as const,
+    id: requestId,
+    error: {
+      code: -32600,
+      message: "Quint: tool call denied by policy",
+    },
+  };
+  return JSON.stringify(response);
+}
+
+function extractId(obj: unknown): string | null {
+  if (typeof obj === "object" && obj !== null && "id" in obj) {
+    const id = (obj as Record<string, unknown>).id;
+    return id != null ? String(id) : null;
+  }
+  return null;
+}

package/src/logger.ts

@@ -0,0 +1,85 @@
+import {
+  type AuditEntry,
+  type AuditDb,
+  type Verdict,
+  type PolicyConfig,
+  signData,
+  canonicalize,
+  sha256,
+} from "@quint-security/core";
+import { randomUUID } from "node:crypto";
+
+export class AuditLogger {
+  private db: AuditDb;
+  private privateKey: string;
+  private publicKey: string;
+  private policyHash: string;
+
+  constructor(db: AuditDb, privateKey: string, publicKey: string, policy: PolicyConfig) {
+    this.db = db;
+    this.privateKey = privateKey;
+    this.publicKey = publicKey;
+    this.policyHash = sha256(canonicalize(policy as unknown as Record<string, unknown>));
+  }
+
+  log(opts: {
+    serverName: string;
+    direction: "request" | "response";
+    method: string;
+    messageId: string | null;
+    toolName: string | null;
+    argumentsJson: string | null;
+    responseJson: string | null;
+    verdict: Verdict;
+    riskScore?: number | null;
+    riskLevel?: string | null;
+  }): number {
+    // Use insertAtomic to read last signature and insert in one transaction,
+    // preventing chain breaks when multiple proxy instances share the same DB.
+    return this.db.insertAtomic((prevSignature: string | null) => {
+      const timestamp = new Date().toISOString();
+      const nonce = randomUUID();
+      const prevHash = prevSignature ? sha256(prevSignature) : "";
+
+      const signable: Record<string, unknown> = {
+        timestamp,
+        server_name: opts.serverName,
+        direction: opts.direction,
+        method: opts.method,
+        message_id: opts.messageId,
+        tool_name: opts.toolName,
+        arguments_json: opts.argumentsJson,
+        response_json: opts.responseJson,
+        verdict: opts.verdict,
+        risk_score: opts.riskScore ?? null,
+        risk_level: opts.riskLevel ?? null,
+        policy_hash: this.policyHash,
+        prev_hash: prevHash,
+        nonce,
+        public_key: this.publicKey,
+      };
+
+      const canonical = canonicalize(signable);
+      const signature = signData(canonical, this.privateKey);
+
+      return {
+        timestamp,
+        server_name: opts.serverName,
+        direction: opts.direction,
+        method: opts.method,
+        message_id: opts.messageId,
+        tool_name: opts.toolName,
+        arguments_json: opts.argumentsJson,
+        response_json: opts.responseJson,
+        verdict: opts.verdict,
+        risk_score: opts.riskScore ?? null,
+        risk_level: opts.riskLevel ?? null,
+        policy_hash: this.policyHash,
+        prev_hash: prevHash,
+        nonce,
+        signature,
+        public_key: this.publicKey,
+      };
+    });
+  }
+}

package/src/relay.ts

@@ -0,0 +1,90 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { createInterface } from "node:readline";
+import { EventEmitter } from "node:events";
+
+export interface RelayEvents {
+  /** Fired for every line received on stdin (from parent / AI agent) */
+  parentMessage: (line: string) => void;
+  /** Fired for every line the child process writes to stdout */
+  childMessage: (line: string) => void;
+  /** Child process exited */
+  childExit: (code: number | null, signal: string | null) => void;
+  /** Unrecoverable error */
+  error: (err: Error) => void;
+}
+
+/**
+ * Relay manages:
+ *  - Spawning the real MCP server as a child process
+ *  - Reading JSON-RPC lines from stdin and forwarding to child stdin
+ *  - Reading JSON-RPC lines from child stdout and forwarding to parent stdout
+ *
+ * The interceptor hooks into parentMessage/childMessage events to inspect,
+ * allow, deny, or modify messages before they are forwarded.
+ */
+export class Relay extends EventEmitter {
+  private child: ChildProcess | null = null;
+  private command: string;
+  private args: string[];
+
+  constructor(command: string, args: string[]) {
+    super();
+    this.command = command;
+    this.args = args;
+  }
+
+  start(): void {
+    // Spawn the real MCP server
+    this.child = spawn(this.command, this.args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    // Forward child stderr to our stderr (pass through diagnostics)
+    this.child.stderr?.pipe(process.stderr);
+
+    this.child.on("error", (err) => {
+      this.emit("error", err);
+    });
+
+    this.child.on("exit", (code, signal) => {
+      this.emit("childExit", code, signal);
+    });
+
+    // Read lines from child stdout
+    if (this.child.stdout) {
+      const childRl = createInterface({ input: this.child.stdout });
+      childRl.on("line", (line) => {
+        this.emit("childMessage", line);
+      });
+    }
+
+    // Read lines from parent stdin
+    const parentRl = createInterface({ input: process.stdin });
+    parentRl.on("line", (line) => {
+      this.emit("parentMessage", line);
+    });
+
+    parentRl.on("close", () => {
+      // Parent closed stdin — close child's stdin so it can finish and exit
+      this.child?.stdin?.end();
+    });
+  }
+
+  /** Send a line to the child process's stdin */
+  sendToChild(line: string): void {
+    if (this.child?.stdin?.writable) {
+      this.child.stdin.write(line + "\n");
+    }
+  }
+
+  /** Send a line to the parent process's stdout */
+  sendToParent(line: string): void {
+    process.stdout.write(line + "\n");
+  }
+
+  /** Gracefully shut down the child */
+  stop(): void {
+    this.child?.kill();
+  }
+}