@jrooig/mcpshield 0.1.0

package/dist/security/sanitizer.js

@@ -0,0 +1,130 @@
+/**
+ * MCP-Shield output sanitizer (blueprint Component C — hook (c) in src/index.ts).
+ *
+ * Tool results and resource contents are EXTERNAL DATA (web pages, files,
+ * API responses) that land directly in the client model's context window. A
+ * hostile document can carry instruction-override phrasing that hijacks the
+ * agent's goals ("ignore previous instructions", "SYSTEM OVERRIDE: ...").
+ * The sanitizer scans every text surface of a server → client result and
+ * replaces a detected block with a safe marker before it reaches the client.
+ */
+export const NEUTRALIZED_MARKER = '[PROMPT INJECTION DETECTED AND NEUTRALIZED BY MCP-SHIELD]';
+// Case-insensitive, with \s+ wherever a space is expected so a phrase cannot
+// dodge detection by line-wrapping or padding. Kept deliberately tight: every
+// pattern is an instruction *aimed at the model*, not prose that could appear
+// in ordinary tool output.
+const INJECTION_PATTERNS = [
+    {
+        label: 'ignore-previous-instructions',
+        pattern: /\b(?:ignore|disregard|forget|override)\s+(?:all\s+|any\s+|the\s+|everything\s+)?(?:previous|prior|above|earlier|preceding|your)\s+(?:instructions?|prompts?|directives?|rules?|messages?|guidelines?|context|training)\b/i,
+    },
+    { label: 'system-override', pattern: /\bsystem[\s\-_]*override\b/i },
+    { label: 'you-must-now', pattern: /\byou\s+must\s+now\b/i },
+    // "New/updated instructions" followed by a colon, dash or period — the
+    // punctuation an attacker uses to introduce the injected directive.
+    { label: 'new-instructions', pattern: /\b(?:new|updated|revised)\s+instructions?\s*[:.\-]/i },
+    {
+        label: 'goal-hijack',
+        pattern: /\byour\s+(?:new|real|true|actual)\s+(?:task|goal|objective|mission|instructions?)\s+(?:is|are)\b/i,
+    },
+    {
+        label: 'hide-from-user',
+        // "do not" and its contraction "don't" (any apostrophe), same verb set.
+        pattern: /\bdo(?:\s+not|n['’]?t)\s+(?:tell|inform|alert|notify|warn)\s+the\s+user\b/i,
+    },
+    {
+        label: 'fake-role-tag',
+        pattern: /<\/?\s*(?:system|assistant)(?:_?(?:prompt|message))?\s*>/i,
+    },
+    {
+        label: 'act-as-unrestricted',
+        pattern: /\bact\s+as\s+(?:an?\s+)?(?:unrestricted|jailbroken|uncensored)\b/i,
+    },
+];
+// Zero-width and invisible formatting characters an attacker can splice into
+// a phrase ("ig<ZWSP>nore all previous instructions") to break \b/\s while a
+// model still reads the intact words. Stripped before scanning.
+const INVISIBLE_CHARS = /[\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2064\uFEFF]/g;
+/** Labels of every injection pattern the text triggers; empty means clean. */
+export function scanText(text) {
+    // NFKC folds confusable/compatibility forms to their canonical characters,
+    // then invisibles are removed, so obfuscated phrasings collapse back to the
+    // plain text the patterns match.
+    const normalized = text.normalize('NFKC').replace(INVISIBLE_CHARS, '');
+    const hits = [];
+    for (const { label, pattern } of INJECTION_PATTERNS) {
+        if (pattern.test(normalized)) {
+            hits.push(label);
+        }
+    }
+    return hits;
+}
+/**
+ * Scan a server → client message and neutralize injected text blocks.
+ *
+ * Covers both content shapes external data travels in:
+ *  - tools/call results:    result.content[]  ({type:'text'} blocks and
+ *                           {type:'resource'} embedded resources)
+ *  - resources/read results: result.contents[] (text resource items)
+ *
+ * A clean message is returned as the SAME object (`modified: false`), so the
+ * caller can tell whether anything was rewritten.
+ */
+export function sanitizeServerMessage(message) {
+    if (!('result' in message) || typeof message.result !== 'object' || message.result === null) {
+        return { message, modified: false, detections: [] };
+    }
+    const result = message.result;
+    const sanitizedResult = { ...result };
+    const detections = [];
+    let modified = false;
+    for (const key of ['content', 'contents']) {
+        const blocks = result[key];
+        if (!Array.isArray(blocks)) {
+            continue;
+        }
+        const sanitizedBlocks = blocks.map((block) => sanitizeBlock(block, detections));
+        if (sanitizedBlocks.some((block, i) => block !== blocks[i])) {
+            sanitizedResult[key] = sanitizedBlocks;
+            modified = true;
+        }
+    }
+    if (!modified) {
+        return { message, modified: false, detections: [] };
+    }
+    return {
+        message: { ...message, result: sanitizedResult },
+        modified: true,
+        detections: [...new Set(detections)],
+    };
+}
+/** Returns the same block when clean, a rewritten copy when a text surface is hostile. */
+function sanitizeBlock(block, detections) {
+    if (typeof block !== 'object' || block === null) {
+        return block;
+    }
+    const record = block;
+    // {type:'text', text} blocks and resources/read items both carry top-level text.
+    const text = record['text'];
+    if (typeof text === 'string') {
+        const hits = scanText(text);
+        if (hits.length > 0) {
+            detections.push(...hits);
+            return { ...record, text: NEUTRALIZED_MARKER };
+        }
+    }
+    // {type:'resource', resource:{text}} embedded resources.
+    const resource = record['resource'];
+    if (typeof resource === 'object' && resource !== null) {
+        const resourceText = resource['text'];
+        if (typeof resourceText === 'string') {
+            const hits = scanText(resourceText);
+            if (hits.length > 0) {
+                detections.push(...hits);
+                return { ...record, resource: { ...resource, text: NEUTRALIZED_MARKER } };
+            }
+        }
+    }
+    return block;
+}
+//# sourceMappingURL=sanitizer.js.map

package/dist/server/dashboardServer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Dashboard server (blueprint Component D): Express for the static Web UI plus
+ * a Socket.io channel carrying the manual-approval flow.
+ *
+ * The proxy launches this on the CLI `--port` and hands the returned
+ * `ApprovalQueue` to its `ask` hook. If the preferred port is busy the server
+ * walks forward to the next free one rather than failing, so a second shielded
+ * server on the same machine still gets a dashboard.
+ *
+ * Diagnostics go to stderr only: stdout is the MCP protocol channel.
+ */
+import { ApprovalQueue } from './wsHandler.js';
+export interface DashboardServer {
+    /** The port actually bound (may differ from the requested one). */
+    port: number;
+    /** The approval queue the proxy parks `ask` requests in. */
+    queue: ApprovalQueue;
+    /** Push an event to every connected dashboard client (activity feed, etc.). */
+    broadcast(event: string, payload: unknown): void;
+    /** Number of connected dashboard clients right now. */
+    clientCount(): number;
+    /** Stop accepting connections and release the port. */
+    close(): Promise<void>;
+}
+export interface DashboardOptions {
+    /** Diagnostic sink (stderr in the proxy). */
+    log?: (message: string) => void;
+    /** Per-request approval timeout; forwarded to the ApprovalQueue. */
+    approvalTimeoutMs?: number;
+    /** How many sequential ports to try before giving up. */
+    maxPortProbes?: number;
+}
+/**
+ * Start the dashboard, probing forward from `preferredPort` on EADDRINUSE.
+ * Resolves once a port is bound; rejects if none is free within the probe
+ * budget or on any non-address error.
+ */
+export declare function startDashboardServer(preferredPort: number, options?: DashboardOptions): Promise<DashboardServer>;

package/dist/server/dashboardServer.js

@@ -0,0 +1,92 @@
+/**
+ * Dashboard server (blueprint Component D): Express for the static Web UI plus
+ * a Socket.io channel carrying the manual-approval flow.
+ *
+ * The proxy launches this on the CLI `--port` and hands the returned
+ * `ApprovalQueue` to its `ask` hook. If the preferred port is busy the server
+ * walks forward to the next free one rather than failing, so a second shielded
+ * server on the same machine still gets a dashboard.
+ *
+ * Diagnostics go to stderr only: stdout is the MCP protocol channel.
+ */
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { Server as SocketIoServer } from 'socket.io';
+import { ApprovalQueue, attachApprovalHandlers } from './wsHandler.js';
+/** Static assets live in <project>/public; this file compiles to <project>/dist/server/. */
+const PUBLIC_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'public');
+const MAX_PORT_PROBES = 20;
+/**
+ * Start the dashboard, probing forward from `preferredPort` on EADDRINUSE.
+ * Resolves once a port is bound; rejects if none is free within the probe
+ * budget or on any non-address error.
+ */
+export async function startDashboardServer(preferredPort, options = {}) {
+    const log = options.log ?? (() => { });
+    const maxProbes = options.maxPortProbes ?? MAX_PORT_PROBES;
+    const app = express();
+    app.disable('x-powered-by');
+    app.use(express.static(PUBLIC_DIR));
+    const httpServer = createServer(app);
+    const io = new SocketIoServer(httpServer, {
+        // The dashboard is a local operator tool; allow any origin to load it.
+        cors: { origin: '*' },
+    });
+    const queue = new ApprovalQueue({
+        broadcast: (event, payload) => io.emit(event, payload),
+        timeoutMs: options.approvalTimeoutMs,
+    });
+    attachApprovalHandlers(io, queue);
+    const port = await listenWithFallback(httpServer, preferredPort, maxProbes, log);
+    // Keep a permanent 'error' listener once bound: listenWithFallback removes
+    // its own on success, and an EventEmitter 'error' with no listener throws —
+    // which would crash the whole proxy, taking the stdout protocol channel with
+    // it. A dashboard-side failure must never do that; log and carry on.
+    httpServer.on('error', (err) => {
+        log(`dashboard server error (ignored): ${err.message}`);
+    });
+    log(`dashboard listening on http://localhost:${port} (static: ${PUBLIC_DIR})`);
+    return {
+        port,
+        queue,
+        broadcast: (event, payload) => io.emit(event, payload),
+        clientCount: () => io.engine.clientsCount,
+        close: () => new Promise((resolve) => {
+            io.close(() => httpServer.close(() => resolve()));
+        }),
+    };
+}
+function listenWithFallback(httpServer, startPort, maxProbes, log) {
+    return new Promise((resolve, reject) => {
+        let port = startPort;
+        let attempts = 0;
+        const onError = (err) => {
+            if (err.code === 'EADDRINUSE' && attempts < maxProbes) {
+                log(`port ${port} in use, trying ${port + 1}`);
+                attempts += 1;
+                port += 1;
+                // Retry on the next port; the 'error' listener stays attached.
+                setImmediate(tryListen);
+                return;
+            }
+            httpServer.removeListener('error', onError);
+            reject(err.code === 'EADDRINUSE'
+                ? new Error(`no free port found in ${startPort}..${startPort + maxProbes}`)
+                : err);
+        };
+        const tryListen = () => {
+            httpServer.listen(port, () => {
+                httpServer.removeListener('error', onError);
+                // Read the bound port from the socket, so port 0 (OS-assigned, used by
+                // tests for a hermetic ephemeral port) resolves to the real number.
+                const address = httpServer.address();
+                resolve(typeof address === 'object' && address !== null ? address.port : port);
+            });
+        };
+        httpServer.on('error', onError);
+        tryListen();
+    });
+}
+//# sourceMappingURL=dashboardServer.js.map

package/dist/server/wsHandler.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Manual-approval queue (blueprint Component D) — hook (b) from src/index.ts.
+ *
+ * When the firewall returns `ask`, the client → server pipeline parks the
+ * message here: an unresolved promise is stored alongside the captured
+ * JSON-RPC request, the dashboard is told over Socket.io, and nothing behind
+ * it moves until the user decides (approve / deny / modify). Because the
+ * proxy's client queue is sequential, at most one request is parked at a time
+ * in the current design, but the Map generalises to more.
+ *
+ * Every wait is bounded and fails CLOSED — the security default of the whole
+ * proxy. A request is denied automatically if:
+ *   - the user does not answer within `timeoutMs` (default 120 s), or
+ *   - the dashboard goes away (last client disconnects) with it still pending.
+ * so a hostile or absent operator can never leave the MCP client hanging.
+ *
+ * This module is transport-agnostic: `ApprovalQueue` takes a `broadcast`
+ * callback and is driven by plain method calls, so it is unit-testable
+ * without a live socket. `attachApprovalHandlers` is the thin Socket.io glue.
+ */
+import type { Server as SocketIoServer } from 'socket.io';
+import { type JsonRpcErrorResponse, type McpToolCallRequest } from '../types/mcp.js';
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS = 120000;
+/** How a parked request was released. `modify` swaps in operator-edited arguments. */
+export type ApprovalOutcome = {
+    action: 'approve';
+} | {
+    action: 'deny';
+    reason: string;
+} | {
+    action: 'modify';
+    arguments: Record<string, unknown>;
+};
+/** The record the dashboard receives so it can render the pending card. */
+export interface PendingView {
+    id: string;
+    ruleName: string;
+    /** Human-readable condition that fired (e.g. `arguments.command regex "..."`). */
+    reason: string;
+    createdAt: number;
+    tool: string;
+    arguments: Record<string, unknown> | undefined;
+    rpcRequest: McpToolCallRequest;
+}
+export interface ApprovalQueueOptions {
+    /** Push an event to every connected dashboard client. */
+    broadcast: (event: string, payload: unknown) => void;
+    timeoutMs?: number;
+    /** Injectable for deterministic tests; defaults to a monotonic counter. */
+    idFactory?: () => string;
+    /** Injectable clock for deterministic tests. */
+    now?: () => number;
+}
+export declare class ApprovalQueue {
+    private readonly pending;
+    private readonly broadcast;
+    private readonly timeoutMs;
+    private readonly now;
+    private readonly nextId;
+    private seq;
+    constructor(options: ApprovalQueueOptions);
+    /**
+     * Park a request pending the operator's verdict. Resolves with their choice,
+     * or auto-denies on timeout. Never rejects — the caller always gets a
+     * decision it can act on, so the MCP client is never left hanging.
+     */
+    enqueue(rpcRequest: McpToolCallRequest, ruleName: string, reason?: string): Promise<ApprovalOutcome>;
+    /** approve → let the original message through unchanged. */
+    approve(id: string): boolean;
+    /** deny → the caller returns Access Denied to the MCP client. */
+    deny(id: string, reason?: string): boolean;
+    /** modify → forward the call with operator-edited arguments instead. */
+    modify(id: string, newArguments: Record<string, unknown>): boolean;
+    /** Fail closed on every still-parked request (used when the dashboard vanishes). */
+    denyAll(reason: string): void;
+    /** Snapshot for a newly connected dashboard so it can render what is waiting. */
+    snapshot(): PendingView[];
+    get size(): number;
+    private settle;
+    private toView;
+}
+/** Build the Access Denied response the proxy returns for a denied/timed-out request. */
+export declare function deniedResponse(request: McpToolCallRequest, reason: string): JsonRpcErrorResponse;
+/**
+ * Wire a Socket.io server to an ApprovalQueue:
+ *  - a new client receives the current pending snapshot,
+ *  - `approve` / `deny` / `modify` events settle the matching request,
+ *  - when the LAST client disconnects, every still-pending request is denied
+ *    (fail closed) so no verdict can hang waiting on an operator who left.
+ *
+ * `modify` payloads are validated to a plain-object `arguments` map; a
+ * malformed edit is rejected rather than forwarded blindly.
+ */
+export declare function attachApprovalHandlers(io: SocketIoServer, queue: ApprovalQueue): void;

package/dist/server/wsHandler.js

@@ -0,0 +1,194 @@
+/**
+ * Manual-approval queue (blueprint Component D) — hook (b) from src/index.ts.
+ *
+ * When the firewall returns `ask`, the client → server pipeline parks the
+ * message here: an unresolved promise is stored alongside the captured
+ * JSON-RPC request, the dashboard is told over Socket.io, and nothing behind
+ * it moves until the user decides (approve / deny / modify). Because the
+ * proxy's client queue is sequential, at most one request is parked at a time
+ * in the current design, but the Map generalises to more.
+ *
+ * Every wait is bounded and fails CLOSED — the security default of the whole
+ * proxy. A request is denied automatically if:
+ *   - the user does not answer within `timeoutMs` (default 120 s), or
+ *   - the dashboard goes away (last client disconnects) with it still pending.
+ * so a hostile or absent operator can never leave the MCP client hanging.
+ *
+ * This module is transport-agnostic: `ApprovalQueue` takes a `broadcast`
+ * callback and is driven by plain method calls, so it is unit-testable
+ * without a live socket. `attachApprovalHandlers` is the thin Socket.io glue.
+ */
+import { createAccessDeniedResponse, } from '../types/mcp.js';
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 120_000;
+export class ApprovalQueue {
+    pending = new Map();
+    broadcast;
+    timeoutMs;
+    now;
+    nextId;
+    seq = 0;
+    constructor(options) {
+        this.broadcast = options.broadcast;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+        this.now = options.now ?? Date.now;
+        this.nextId = options.idFactory ?? (() => `ask-${++this.seq}`);
+    }
+    /**
+     * Park a request pending the operator's verdict. Resolves with their choice,
+     * or auto-denies on timeout. Never rejects — the caller always gets a
+     * decision it can act on, so the MCP client is never left hanging.
+     */
+    enqueue(rpcRequest, ruleName, reason = '') {
+        return new Promise((resolve) => {
+            const id = this.nextId();
+            // A ref'd timer on purpose: while a request is parked we are waiting for
+            // the operator, so this pending approval SHOULD keep the process alive
+            // until it is answered or auto-denied at the deadline.
+            const timer = setTimeout(() => {
+                this.settle(id, { action: 'deny', reason: `approval timed out after ${this.timeoutMs}ms` });
+            }, this.timeoutMs);
+            const entry = {
+                id,
+                rpcRequest,
+                ruleName,
+                reason,
+                createdAt: this.now(),
+                resolve,
+                reject: () => { },
+                timer,
+            };
+            this.pending.set(id, entry);
+            this.broadcast('pending_approval', this.toView(entry));
+        });
+    }
+    /** approve → let the original message through unchanged. */
+    approve(id) {
+        return this.settle(id, { action: 'approve' });
+    }
+    /** deny → the caller returns Access Denied to the MCP client. */
+    deny(id, reason = 'denied by operator') {
+        return this.settle(id, { action: 'deny', reason });
+    }
+    /** modify → forward the call with operator-edited arguments instead. */
+    modify(id, newArguments) {
+        return this.settle(id, { action: 'modify', arguments: newArguments });
+    }
+    /** Fail closed on every still-parked request (used when the dashboard vanishes). */
+    denyAll(reason) {
+        for (const id of [...this.pending.keys()]) {
+            this.settle(id, { action: 'deny', reason });
+        }
+    }
+    /** Snapshot for a newly connected dashboard so it can render what is waiting. */
+    snapshot() {
+        return [...this.pending.values()].map((entry) => this.toView(entry));
+    }
+    get size() {
+        return this.pending.size;
+    }
+    settle(id, outcome) {
+        const entry = this.pending.get(id);
+        if (entry === undefined) {
+            return false; // already resolved, timed out, or an unknown id from the UI
+        }
+        clearTimeout(entry.timer);
+        this.pending.delete(id);
+        this.broadcast('request_resolved', { id, outcome });
+        entry.resolve(outcome);
+        return true;
+    }
+    toView(entry) {
+        return {
+            id: entry.id,
+            ruleName: entry.ruleName,
+            reason: entry.reason,
+            createdAt: entry.createdAt,
+            tool: entry.rpcRequest.params.name,
+            arguments: entry.rpcRequest.params.arguments,
+            rpcRequest: entry.rpcRequest,
+        };
+    }
+}
+/** Build the Access Denied response the proxy returns for a denied/timed-out request. */
+export function deniedResponse(request, reason) {
+    return createAccessDeniedResponse(request.id, reason);
+}
+/**
+ * Wire a Socket.io server to an ApprovalQueue:
+ *  - a new client receives the current pending snapshot,
+ *  - `approve` / `deny` / `modify` events settle the matching request,
+ *  - when the LAST client disconnects, every still-pending request is denied
+ *    (fail closed) so no verdict can hang waiting on an operator who left.
+ *
+ * `modify` payloads are validated to a plain-object `arguments` map; a
+ * malformed edit is rejected rather than forwarded blindly.
+ */
+export function attachApprovalHandlers(io, queue) {
+    // Track clients ourselves instead of reading io.engine.clientsCount inside
+    // the disconnect handler: engine.io decrements that count asynchronously,
+    // AFTER the 'disconnect' event, so it still reads the leaving socket at that
+    // instant. A counter we bump on connect and drop in the disconnect handler
+    // is exact.
+    let clients = 0;
+    io.on('connection', (socket) => {
+        clients += 1;
+        socket.emit('pending_snapshot', queue.snapshot());
+        socket.on('approve', (payload) => {
+            const id = extractId(payload);
+            if (id !== undefined) {
+                queue.approve(id);
+            }
+        });
+        socket.on('deny', (payload) => {
+            const id = extractId(payload);
+            if (id !== undefined) {
+                queue.deny(id);
+            }
+        });
+        socket.on('modify', (payload) => {
+            const id = extractId(payload);
+            const args = extractArguments(payload);
+            if (id !== undefined && args !== undefined) {
+                queue.modify(id, args);
+            }
+            else if (id !== undefined) {
+                // A modify with an unusable payload must not silently approve; deny it.
+                queue.deny(id, 'modify payload was not a valid arguments object');
+            }
+        });
+        socket.on('disconnect', () => {
+            clients -= 1;
+            // If this was the last dashboard, fail closed on anything still parked:
+            // no operator remains to give a verdict. (A refresh briefly hits zero
+            // too; denying is the safe default the whole proxy is built on.)
+            if (clients === 0 && queue.size > 0) {
+                queue.denyAll('dashboard disconnected before a verdict was given');
+            }
+        });
+    });
+}
+function extractId(payload) {
+    if (typeof payload === 'string') {
+        return payload;
+    }
+    if (typeof payload === 'object' && payload !== null) {
+        const id = payload['id'];
+        if (typeof id === 'string') {
+            return id;
+        }
+    }
+    return undefined;
+}
+function extractArguments(payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        return undefined;
+    }
+    // Accept either { id, arguments: {...} } or { id, modifiedPayload: {...} }.
+    const record = payload;
+    const candidate = record['arguments'] ?? record['modifiedPayload'];
+    if (typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate)) {
+        return candidate;
+    }
+    return undefined;
+}
+//# sourceMappingURL=wsHandler.js.map

package/dist/types/mcp.d.ts

@@ -0,0 +1,123 @@
+/**
+ * JSON-RPC 2.0 & Model Context Protocol (MCP) type definitions.
+ *
+ * These types model the wire format that MCP-Shield intercepts on stdio:
+ * every packet exchanged between an MCP client (e.g. Claude Code) and an
+ * MCP server is a JSON-RPC 2.0 message, and MCP layers its own methods
+ * (`initialize`, `tools/call`, `resources/read`, ...) on top of it.
+ */
+export declare const JSONRPC_VERSION: "2.0";
+/** A request id. The spec allows string, number or null (null only in error responses to unparseable requests). */
+export type JsonRpcId = string | number | null;
+/** A request expects a response and therefore always carries an id. */
+export interface JsonRpcRequest {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown> | unknown[];
+}
+/** A notification is fire-and-forget: same shape as a request but without id. */
+export interface JsonRpcNotification {
+    jsonrpc: typeof JSONRPC_VERSION;
+    method: string;
+    params?: Record<string, unknown> | unknown[];
+}
+export interface JsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcSuccessResponse {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: JsonRpcId;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: JsonRpcId;
+    error: JsonRpcErrorObject;
+}
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+/** Any valid JSON-RPC 2.0 packet that can travel over the stdio pipe. */
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+/** Standard JSON-RPC 2.0 error codes, plus the code MCP-Shield uses for policy denials. */
+export declare const JsonRpcErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    /** MCP-Shield policy denial. The spec reserves -32000..-32099 for implementation-defined server errors. */
+    readonly AccessDenied: -32003;
+};
+export type JsonRpcErrorCodeValue = (typeof JsonRpcErrorCode)[keyof typeof JsonRpcErrorCode];
+/** MCP methods relevant to interception. Servers may expose more; the firewall matches on these. */
+export declare const McpMethod: {
+    readonly Initialize: "initialize";
+    readonly Initialized: "notifications/initialized";
+    readonly ToolsList: "tools/list";
+    readonly ToolsCall: "tools/call";
+    readonly ResourcesList: "resources/list";
+    readonly ResourcesRead: "resources/read";
+    readonly PromptsList: "prompts/list";
+    readonly PromptsGet: "prompts/get";
+    readonly Ping: "ping";
+};
+export type McpMethodValue = (typeof McpMethod)[keyof typeof McpMethod];
+/** Params of a `tools/call` request — the packet the firewall cares most about. */
+export interface McpToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/** A fully-typed `tools/call` request as seen on the client → server pipe. */
+export interface McpToolCallRequest extends JsonRpcRequest {
+    method: typeof McpMethod.ToolsCall;
+    params: McpToolCallParams & Record<string, unknown>;
+}
+/** Tool definition as returned by `tools/list`. */
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export interface McpToolListResult {
+    tools: McpTool[];
+}
+export interface McpTextContent {
+    type: 'text';
+    text: string;
+}
+export interface McpImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+export interface McpEmbeddedResource {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+}
+export type McpContent = McpTextContent | McpImageContent | McpEmbeddedResource;
+/** Result of a `tools/call` — travels server → client and passes through the sanitizer. */
+export interface McpToolCallResult {
+    content: McpContent[];
+    isError?: boolean;
+}
+export declare function isJsonRpcMessage(value: unknown): value is JsonRpcMessage;
+export declare function isJsonRpcRequest(value: unknown): value is JsonRpcRequest;
+export declare function isJsonRpcNotification(value: unknown): value is JsonRpcNotification;
+export declare function isJsonRpcResponse(value: unknown): value is JsonRpcResponse;
+export declare function isJsonRpcErrorResponse(value: unknown): value is JsonRpcErrorResponse;
+/** Narrow an intercepted packet down to the tool invocation the firewall must judge. */
+export declare function isToolCallRequest(value: unknown): value is McpToolCallRequest;
+/** Build the error response MCP-Shield returns to the client when a request is blocked by policy. */
+export declare function createAccessDeniedResponse(id: JsonRpcId, ruleName?: string): JsonRpcErrorResponse;
+export declare function createErrorResponse(id: JsonRpcId, code: JsonRpcErrorCodeValue | number, message: string, data?: unknown): JsonRpcErrorResponse;