@jrooig/mcpshield 0.1.0

package/dist/install.js

@@ -0,0 +1,361 @@
+/**
+ * `mcp-shield install` / `mcp-shield uninstall` — zero-friction (un)wrapping
+ * of MCP client configs.
+ *
+ * With an explicit app id (`install cursor`) only that client is touched and
+ * any problem is fatal. With no argument the known clients are probed and
+ * every config found is processed; per-client problems are reported but do
+ * not abort the sweep, so one corrupt config can't block shielding the rest.
+ */
+import { readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+function fail(message) {
+    process.stderr.write(`[mcp-shield] ${message}\n`);
+    process.exit(1);
+}
+/** Green when a human is watching; plain when piped. Awaits the write
+ * callback so a process.exit right after cannot truncate the feedback. */
+async function writeFinal(message) {
+    const full = `[mcp-shield] ${message}`;
+    const line = process.stderr.isTTY ? `\x1b[32m${full}\x1b[0m\n` : `${full}\n`;
+    await new Promise((resolve) => {
+        process.stderr.write(line, () => resolve());
+    });
+}
+function appData() {
+    return process.env.APPDATA || path.join(homedir(), 'AppData', 'Roaming');
+}
+const CLIENTS = [
+    {
+        id: 'claude',
+        name: 'Claude Desktop',
+        serversKey: 'mcpServers',
+        autoDetect: true,
+        configPath: () => {
+            if (process.platform === 'win32') {
+                return path.join(appData(), 'Claude', 'claude_desktop_config.json');
+            }
+            if (process.platform === 'darwin') {
+                return path.join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+            }
+            return null; // No official Linux build of Claude Desktop.
+        },
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        serversKey: 'mcpServers',
+        autoDetect: true,
+        // Cursor's native MCP config lives in ~/.cursor on every platform. (The
+        // globalStorage/rooveterinaryinc.roo-cline path this used to target
+        // belongs to the Roo Code extension, not to Cursor itself.)
+        configPath: () => path.join(homedir(), '.cursor', 'mcp.json'),
+    },
+    {
+        id: 'vscode',
+        name: 'VS Code',
+        serversKey: 'servers',
+        autoDetect: true,
+        configPath: () => {
+            if (process.platform === 'win32') {
+                return path.join(appData(), 'Code', 'User', 'mcp.json');
+            }
+            if (process.platform === 'darwin') {
+                return path.join(homedir(), 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+            }
+            return path.join(homedir(), '.config', 'Code', 'User', 'mcp.json');
+        },
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        serversKey: 'mcpServers',
+        autoDetect: true,
+        configPath: () => path.join(homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+    },
+    {
+        id: 'claude-code',
+        name: 'Claude Code (project .mcp.json)',
+        serversKey: 'mcpServers',
+        autoDetect: false,
+        configPath: () => path.join(process.cwd(), '.mcp.json'),
+    },
+];
+const SUPPORTED_IDS = CLIENTS.map((c) => c.id).join(', ');
+// ---------------------------------------------------------------------------
+// Shield invocation — how a client can re-launch THIS mcp-shield
+// ---------------------------------------------------------------------------
+/**
+ * Command (+ leading args) that re-invokes the currently running mcp-shield
+ * using absolute paths only. A bare "mcp-shield" would be resolved against
+ * the CLIENT's PATH at spawn time, which breaks under every mainstream
+ * install channel: `npx @jrooig/mcpshield install` leaves nothing on PATH once it
+ * exits, GUI-launched clients on macOS inherit launchd's minimal PATH, and
+ * Windows clients can't exec the npm .cmd shim without a shell. Also used
+ * by `mcp-shield register`, which writes the same shape.
+ */
+export function shieldInvocation() {
+    // pkg standalone binary: the executable itself is the shield.
+    if (process.pkg !== undefined) {
+        return [process.execPath];
+    }
+    // Plain node (npx, npm -g shim, local checkout): the same node binary
+    // running the same entry script.
+    return [process.execPath, path.resolve(process.argv[1] ?? '')];
+}
+/**
+ * Does this command/arg string invoke mcp-shield? Deliberately exact — a
+ * loose substring test would make `uninstall` mangle an unrelated server
+ * whose command merely contains "mcp-shield" (e.g. "mcp-shield-audit").
+ * Matches: the bare/legacy name, our pkg binary names, and any path that
+ * traverses an "mcp-shield" directory (npm package dir, this repo).
+ */
+const SHIELD_BASENAMES = new Set(['mcp-shield', 'mcp-shield-linux', 'mcp-shield-macos', 'mcp-shield-win']);
+function invokesShield(value) {
+    if (typeof value !== 'string' || value === '') {
+        return false;
+    }
+    const segments = value.split(/[\\/]+/);
+    const last = segments[segments.length - 1] ?? '';
+    const basename = last.toLowerCase().replace(/\.(exe|cmd|ps1)$/, '');
+    return SHIELD_BASENAMES.has(basename) || segments.includes('mcp-shield');
+}
+function isShieldedEntry(serverConfig) {
+    if (invokesShield(serverConfig.command)) {
+        return true;
+    }
+    // node <abs .../mcp-shield/dist/index.js> -- <original...>
+    return Array.isArray(serverConfig.args) && invokesShield(serverConfig.args[0]);
+}
+/** Wraps every wrappable server in place; returns how many changed. */
+function wrapServers(servers) {
+    const invocation = shieldInvocation();
+    let modified = 0;
+    for (const serverConfig of Object.values(servers)) {
+        if (!serverConfig || typeof serverConfig !== 'object')
+            continue;
+        if (isShieldedEntry(serverConfig))
+            continue;
+        // Entries without a string command are remote (http/sse) servers — most
+        // common in VS Code's mcp.json — and carry no child process to proxy.
+        if (typeof serverConfig.command !== 'string')
+            continue;
+        // A present-but-non-array args is malformed; wrapping would silently
+        // discard the value with no way for uninstall to restore it. Leave the
+        // entry for the user to fix.
+        if (serverConfig.args !== undefined && !Array.isArray(serverConfig.args))
+            continue;
+        const originalCommand = serverConfig.command;
+        const originalArgs = serverConfig.args ?? [];
+        serverConfig.command = invocation[0];
+        serverConfig.args = [...invocation.slice(1), '--', originalCommand, ...originalArgs];
+        modified += 1;
+    }
+    return modified;
+}
+/** Restores every shielded server in place; returns how many changed. */
+function unwrapServers(servers) {
+    let modified = 0;
+    for (const serverConfig of Object.values(servers)) {
+        if (!serverConfig || typeof serverConfig !== 'object')
+            continue;
+        if (!isShieldedEntry(serverConfig))
+            continue;
+        const args = Array.isArray(serverConfig.args) ? serverConfig.args : [];
+        const sepIndex = args.indexOf('--');
+        if (sepIndex === -1 || args.length <= sepIndex + 1)
+            continue;
+        serverConfig.command = args[sepIndex + 1];
+        serverConfig.args = args.slice(sepIndex + 2);
+        if (serverConfig.args.length === 0) {
+            delete serverConfig.args;
+        }
+        modified += 1;
+    }
+    return modified;
+}
+/** Sibling-temp-file + rename: atomic on POSIX, and realpath first so an
+ * intentionally symlinked config keeps pointing at its real target. */
+async function writeConfigAtomic(configPath, config) {
+    let destPath = configPath;
+    try {
+        destPath = await realpath(configPath);
+    }
+    catch { }
+    const tmpPath = `${destPath}.${process.pid}.tmp`;
+    try {
+        await writeFile(tmpPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+        await rename(tmpPath, destPath);
+    }
+    catch (err) {
+        await rm(tmpPath, { force: true }).catch(() => undefined);
+        throw new Error(`cannot write ${destPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function applyToClient(client, mode) {
+    const configPath = client.configPath();
+    if (configPath === null) {
+        return { kind: 'unsupported' };
+    }
+    let raw;
+    try {
+        raw = await readFile(configPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { kind: 'not-found', configPath };
+        }
+        return { kind: 'error', configPath, reason: `cannot read ${configPath}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: 'error', configPath, reason: `${configPath} is not valid JSON. Please fix it manually first.` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { kind: 'error', configPath, reason: `${configPath} does not contain a JSON object at the top level` };
+    }
+    const config = parsed;
+    const existingServers = config[client.serversKey];
+    if (!existingServers || typeof existingServers !== 'object' || Array.isArray(existingServers)) {
+        return { kind: 'no-servers', configPath };
+    }
+    const servers = existingServers;
+    const modified = mode === 'install' ? wrapServers(servers) : unwrapServers(servers);
+    if (modified === 0) {
+        return { kind: 'unchanged', configPath };
+    }
+    try {
+        await writeConfigAtomic(configPath, config);
+    }
+    catch (err) {
+        return { kind: 'error', configPath, reason: err instanceof Error ? err.message : String(err) };
+    }
+    return { kind: 'changed', configPath, count: modified };
+}
+// ---------------------------------------------------------------------------
+// Explicit mode — `mcp-shield install <app>`: any problem is fatal
+// ---------------------------------------------------------------------------
+async function runExplicit(client, mode) {
+    const outcome = await applyToClient(client, mode);
+    switch (outcome.kind) {
+        case 'unsupported':
+            fail(`${client.name} is currently only supported on Windows and macOS.`);
+        case 'not-found':
+            fail(mode === 'install'
+                ? `Could not find config file at ${outcome.configPath}. Please ensure ${client.id} is installed and has been run at least once.`
+                : `Could not find config file at ${outcome.configPath}.`);
+        case 'error':
+            fail(outcome.reason);
+        case 'no-servers':
+            fail(mode === 'install'
+                ? `No "${client.serversKey}" found in ${outcome.configPath} to protect. Add some servers first!`
+                : `No "${client.serversKey}" found in ${outcome.configPath}.`);
+        case 'unchanged':
+            process.stderr.write(mode === 'install'
+                ? `[mcp-shield] All servers in ${client.id} are already protected!\n`
+                : `[mcp-shield] No servers were protected by mcp-shield in ${client.id}.\n`);
+            return;
+        case 'changed':
+            await writeFinal(mode === 'install'
+                ? `Successfully shielded ${outcome.count} server(s) in ${client.id}. Please restart ${client.id} to apply changes.`
+                : `Successfully UNINSTALLED from ${outcome.count} server(s) in ${client.id}.`);
+            return;
+    }
+}
+// ---------------------------------------------------------------------------
+// Auto-detect mode — `mcp-shield install`: probe every client, keep going
+// ---------------------------------------------------------------------------
+async function runAutoDetect(mode) {
+    let totalChanged = 0;
+    let clientsChanged = 0;
+    let detectedOk = 0;
+    let errors = 0;
+    for (const client of CLIENTS) {
+        if (!client.autoDetect) {
+            process.stderr.write(`[mcp-shield]   - ${client.name}: skipped in auto mode — run "mcp-shield ${mode} ${client.id}" inside a project to opt in\n`);
+            continue;
+        }
+        const outcome = await applyToClient(client, mode);
+        switch (outcome.kind) {
+            case 'unsupported':
+            case 'not-found':
+                process.stderr.write(`[mcp-shield]   - ${client.name}: not detected\n`);
+                break;
+            case 'error':
+                errors += 1;
+                process.stderr.write(`[mcp-shield]   ! ${client.name}: ${outcome.reason}\n`);
+                break;
+            case 'no-servers':
+                detectedOk += 1;
+                process.stderr.write(`[mcp-shield]   ✓ Detected ${client.name} — no MCP servers configured, nothing to ${mode === 'install' ? 'shield' : 'restore'}\n`);
+                break;
+            case 'unchanged':
+                detectedOk += 1;
+                process.stderr.write(mode === 'install'
+                    ? `[mcp-shield]   ✓ Detected ${client.name} — all servers already protected\n`
+                    : `[mcp-shield]   ✓ Detected ${client.name} — no shielded servers to restore\n`);
+                break;
+            case 'changed':
+                detectedOk += 1;
+                clientsChanged += 1;
+                totalChanged += outcome.count;
+                process.stderr.write(mode === 'install'
+                    ? `[mcp-shield]   ✓ Detected ${client.name} — shielded ${outcome.count} server(s)\n`
+                    : `[mcp-shield]   ✓ Detected ${client.name} — restored ${outcome.count} server(s)\n`);
+                break;
+        }
+    }
+    if (detectedOk === 0 && errors === 0) {
+        fail(`No supported MCP clients found on this machine. Supported: ${SUPPORTED_IDS}. You can also target one explicitly: mcp-shield ${mode} <app>.`);
+    }
+    if (detectedOk === 0) {
+        // Every config we found was unusable — that is a failure, not a sweep.
+        fail(`No client config could be ${mode === 'install' ? 'shielded' : 'restored'} (${errors} error(s) above).`);
+    }
+    if (errors > 0) {
+        // Partial success must not look like success: a scripted caller
+        // (`mcp-shield install && ...`) would otherwise believe the whole
+        // machine is protected when a detected client was left unshielded.
+        fail(`${mode === 'install' ? 'Shielded' : 'Restored'} ${totalChanged} server(s) across ${clientsChanged} client(s), but ${errors} client config(s) had errors (see above) and were left untouched.`);
+    }
+    if (totalChanged > 0) {
+        await writeFinal(mode === 'install'
+            ? `Proxy injected into ${totalChanged} server(s) across ${clientsChanged} client(s). Zero-trust policies active — restart the affected apps to apply changes.`
+            : `Restored ${totalChanged} server(s) across ${clientsChanged} client(s). Restart the affected apps to apply changes.`);
+    }
+    else {
+        await writeFinal(mode === 'install'
+            ? 'Nothing new to shield — every detected client is already protected.'
+            : 'Nothing to restore — no shielded servers found in the detected clients.');
+    }
+}
+// ---------------------------------------------------------------------------
+// Entry points
+// ---------------------------------------------------------------------------
+function resolveClient(targetApp) {
+    const client = CLIENTS.find((c) => c.id === targetApp);
+    if (client === undefined) {
+        fail(`unknown app "${targetApp}". Supported: ${SUPPORTED_IDS} — or run with no argument to auto-detect all of them.`);
+    }
+    return client;
+}
+export async function runInstallCommand(targetApp) {
+    if (targetApp === undefined || targetApp === '') {
+        await runAutoDetect('install');
+        return;
+    }
+    await runExplicit(resolveClient(targetApp), 'install');
+}
+export async function runUninstallCommand(targetApp) {
+    if (targetApp === undefined || targetApp === '') {
+        await runAutoDetect('uninstall');
+        return;
+    }
+    await runExplicit(resolveClient(targetApp), 'uninstall');
+}
+//# sourceMappingURL=install.js.map

package/dist/security/firewall.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MCP-Shield firewall (blueprint Component C — hook (a) in src/index.ts).
+ *
+ * Two layers:
+ *
+ * 1. screenClientLine() — wire-level screening of every client → server line:
+ *    - Deny by default: input that is not valid JSON is answered with a
+ *      ParseError and never reaches the target server (a laxer parser on the
+ *      server side might otherwise still act on it).
+ *    - JSON-RPC batches (arrays) are rejected outright: MCP is strictly
+ *      one-message-per-line and a batch is only useful here as a vehicle to
+ *      sneak a tools/call past inspection.
+ *    - Anything claiming `method: "tools/call"` is held to the strict shape
+ *      (params.name a non-empty string, a respondable id) or blocked.
+ *    - Canonical re-serialization: what gets forwarded is OUR JSON.stringify
+ *      of the object we judged — never the client's raw bytes — so
+ *      duplicate-key parser differentials like
+ *      {"command":"safe","command":"malicious"} cannot smuggle a second
+ *      reading past the firewall.
+ *
+ * 2. Firewall — the rule engine: matches SecurityRules (allow / block / ask)
+ *    against tools/call requests via contains / regex / outside_dir
+ *    conditions on dot-path fields of the call params.
+ */
+import { type SecurityRule } from '../config/rules.js';
+import { type JsonRpcErrorResponse, type JsonRpcMessage, type McpToolCallRequest } from '../types/mcp.js';
+export type FirewallVerdict = {
+    action: 'allow';
+} | {
+    action: 'block' | 'ask';
+    rule: SecurityRule;
+    reason: string;
+};
+export declare class Firewall {
+    private rules;
+    private compiledRegexes;
+    constructor(rules?: SecurityRule[]);
+    /** Loads from `~/.mcp-shield/rules.cache.json` if available, falls back to default rules. */
+    static create(): Promise<Firewall>;
+    /**
+     * Hot-reloads the active rule set in place. Compiles regexes first so that a
+     * bad rule from the cloud leaves the existing policy intact and throws instead
+     * of silently disabling protection.
+     */
+    reloadRules(rules: SecurityRule[]): void;
+    /** First matching rule wins; a call no rule claims is allowed (the rules define the restrictions). */
+    evaluateToolCall(request: McpToolCallRequest): FirewallVerdict;
+    private compileRules;
+    private conditionMatches;
+}
+export type ClientScreenResult = {
+    kind: 'forward';
+    message: JsonRpcMessage;
+    wire: string;
+} | {
+    kind: 'respond';
+    response: JsonRpcErrorResponse;
+    reason: string;
+} | {
+    kind: 'drop';
+    reason: string;
+};
+export declare function screenClientLine(line: string): ClientScreenResult;

package/dist/security/firewall.js

@@ -0,0 +1,202 @@
+/**
+ * MCP-Shield firewall (blueprint Component C — hook (a) in src/index.ts).
+ *
+ * Two layers:
+ *
+ * 1. screenClientLine() — wire-level screening of every client → server line:
+ *    - Deny by default: input that is not valid JSON is answered with a
+ *      ParseError and never reaches the target server (a laxer parser on the
+ *      server side might otherwise still act on it).
+ *    - JSON-RPC batches (arrays) are rejected outright: MCP is strictly
+ *      one-message-per-line and a batch is only useful here as a vehicle to
+ *      sneak a tools/call past inspection.
+ *    - Anything claiming `method: "tools/call"` is held to the strict shape
+ *      (params.name a non-empty string, a respondable id) or blocked.
+ *    - Canonical re-serialization: what gets forwarded is OUR JSON.stringify
+ *      of the object we judged — never the client's raw bytes — so
+ *      duplicate-key parser differentials like
+ *      {"command":"safe","command":"malicious"} cannot smuggle a second
+ *      reading past the firewall.
+ *
+ * 2. Firewall — the rule engine: matches SecurityRules (allow / block / ask)
+ *    against tools/call requests via contains / regex / outside_dir
+ *    conditions on dot-path fields of the call params.
+ */
+import path from 'node:path';
+import { defaultRules, loadCachedRules } from '../config/rules.js';
+import { createAccessDeniedResponse, createErrorResponse, isJsonRpcMessage, isToolCallRequest, JsonRpcErrorCode, McpMethod, } from '../types/mcp.js';
+export class Firewall {
+    rules;
+    compiledRegexes;
+    constructor(rules = defaultRules) {
+        this.compiledRegexes = this.compileRules(rules);
+        this.rules = rules;
+    }
+    /** Loads from `~/.mcp-shield/rules.cache.json` if available, falls back to default rules. */
+    static async create() {
+        const cached = await loadCachedRules();
+        return new Firewall(cached ?? defaultRules);
+    }
+    /**
+     * Hot-reloads the active rule set in place. Compiles regexes first so that a
+     * bad rule from the cloud leaves the existing policy intact and throws instead
+     * of silently disabling protection.
+     */
+    reloadRules(rules) {
+        const newRegexes = this.compileRules(rules);
+        this.compiledRegexes = newRegexes;
+        this.rules = rules;
+    }
+    /** First matching rule wins; a call no rule claims is allowed (the rules define the restrictions). */
+    evaluateToolCall(request) {
+        for (const rule of this.rules) {
+            if (rule.tool !== '*' && rule.tool !== request.params.name) {
+                continue;
+            }
+            if (rule.condition !== undefined && !this.conditionMatches(rule, rule.condition, request)) {
+                continue;
+            }
+            if (rule.action === 'allow') {
+                return { action: 'allow' };
+            }
+            return {
+                action: rule.action,
+                rule,
+                reason: rule.condition
+                    ? `${rule.condition.field} ${rule.condition.operator} "${rule.condition.value}"`
+                    : `tool "${rule.tool}"`,
+            };
+        }
+        return { action: 'allow' };
+    }
+    compileRules(rules) {
+        const regexes = new Map();
+        for (const rule of rules) {
+            if (rule.condition?.operator === 'regex') {
+                try {
+                    regexes.set(rule.id, new RegExp(rule.condition.value, 'i'));
+                }
+                catch (err) {
+                    throw new Error(`invalid regex in security rule "${rule.id}": ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        return regexes;
+    }
+    conditionMatches(rule, condition, request) {
+        const value = getByPath(request.params, condition.field);
+        if (value === undefined) {
+            return false;
+        }
+        // Nested objects/arrays are matched against their JSON form, so a payload
+        // cannot dodge a text rule by wrapping the string one level deeper.
+        const haystack = typeof value === 'string' ? value : JSON.stringify(value);
+        switch (condition.operator) {
+            case 'contains':
+                return haystack.toLowerCase().includes(condition.value.toLowerCase());
+            case 'regex':
+                return this.compiledRegexes.get(rule.id).test(haystack);
+            case 'outside_dir':
+                // A non-string path is unjudgeable — fail closed and let the rule fire.
+                return typeof value !== 'string' || isOutsideDir(value, condition.value);
+        }
+    }
+}
+function getByPath(root, fieldPath) {
+    let current = root;
+    for (const key of fieldPath.split('.')) {
+        if (typeof current !== 'object' || current === null || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+function isOutsideDir(candidate, root) {
+    const resolvedRoot = path.resolve(root);
+    const relative = path.relative(resolvedRoot, path.resolve(resolvedRoot, candidate));
+    return relative.startsWith('..') || path.isAbsolute(relative);
+}
+export function screenClientLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        // Deny by default: bytes we cannot parse are bytes we cannot judge.
+        return {
+            kind: 'respond',
+            reason: 'non-JSON input (deny-by-default)',
+            response: createErrorResponse(null, JsonRpcErrorCode.ParseError, 'Parse error: MCP-Shield forwards valid JSON-RPC 2.0 only'),
+        };
+    }
+    if (Array.isArray(parsed)) {
+        return {
+            kind: 'respond',
+            reason: `JSON-RPC batch of ${parsed.length} messages rejected`,
+            response: createErrorResponse(null, JsonRpcErrorCode.InvalidRequest, 'Invalid Request: batch requests are not permitted by MCP-Shield'),
+        };
+    }
+    if (!isJsonRpcMessage(parsed)) {
+        return {
+            kind: 'respond',
+            reason: 'not a JSON-RPC 2.0 message',
+            response: createErrorResponse(null, JsonRpcErrorCode.InvalidRequest, 'Invalid Request: not a JSON-RPC 2.0 message'),
+        };
+    }
+    // Anything that even LOOKS like the tools/call method — after trimming and
+    // case-folding — is treated as a tool invocation. A lenient server that
+    // route-matches "Tools/Call" or "tools/call " (trailing space) would still
+    // dispatch it, so we must not let the disguise skip the firewall: the
+    // padded/case variant is held to the exact strict shape or rejected. This
+    // covers id-less "notification" variants too (they execute unanswerably).
+    const method = 'method' in parsed ? parsed.method : undefined;
+    const claimsToolsCall = typeof method === 'string' && method.trim().toLowerCase() === McpMethod.ToolsCall;
+    if (claimsToolsCall && !isStrictToolCall(parsed)) {
+        const id = extractRespondableId(parsed);
+        if (id === undefined) {
+            return { kind: 'drop', reason: 'malformed tools/call without an id (would execute unanswerably)' };
+        }
+        return {
+            kind: 'respond',
+            reason: 'malformed tools/call (disguised method, or params.name missing/empty/padded/not a string, or bad arguments/id)',
+            response: createAccessDeniedResponse(id, 'malformed-tool-call'),
+        };
+    }
+    // Canonical re-serialization: the server receives OUR serialization of the
+    // object the firewall judged — never the client's raw bytes.
+    return { kind: 'forward', message: parsed, wire: JSON.stringify(parsed) };
+}
+/**
+ * The only tools/call shape allowed through: the exact method (no whitespace
+ * or case disguise), a routable id, a tool name with no surrounding whitespace
+ * (a padded name would dodge the rule engine's exact tool match yet still
+ * dispatch on a trimming server), and — if present — an `arguments` object
+ * that is a real object, so a positional-array `arguments` cannot make the
+ * rules' `arguments.command` field unresolvable and slip through as allowed.
+ */
+function isStrictToolCall(value) {
+    if (!isToolCallRequest(value) ||
+        value.method !== McpMethod.ToolsCall ||
+        !(typeof value.id === 'string' || typeof value.id === 'number') ||
+        value.params.name.trim() === '' ||
+        value.params.name !== value.params.name.trim()) {
+        return false;
+    }
+    const args = value.params['arguments'];
+    return args === undefined || (typeof args === 'object' && args !== null && !Array.isArray(args));
+}
+/**
+ * The id to address a rejection to: the request's own id when it is a legal
+ * one, null when an id field exists but is unusable (JSON-RPC prescribes a
+ * null id for errors on undeterminable requests), undefined when there is no
+ * id at all — a notification, which cannot be answered.
+ */
+function extractRespondableId(message) {
+    if (!('id' in message)) {
+        return undefined;
+    }
+    const { id } = message;
+    return typeof id === 'string' || typeof id === 'number' ? id : null;
+}
+//# sourceMappingURL=firewall.js.map

package/dist/security/sanitizer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+import type { JsonRpcMessage } from '../types/mcp.js';
+export declare const NEUTRALIZED_MARKER = "[PROMPT INJECTION DETECTED AND NEUTRALIZED BY MCP-SHIELD]";
+/** Labels of every injection pattern the text triggers; empty means clean. */
+export declare function scanText(text: string): string[];
+export interface SanitizationResult {
+    message: JsonRpcMessage;
+    modified: boolean;
+    detections: string[];
+}
+/**
+ * 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 declare function sanitizeServerMessage(message: JsonRpcMessage): SanitizationResult;