npm - @jrooig/mcpshield - Versions diffs - 0.1.0 - Mend

@jrooig/mcpshield 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/LICENSE +21 -0
package/README.md +141 -0
package/dist/config/rules.d.ts +29 -0
package/dist/config/rules.js +141 -0
package/dist/enterprise/apiClient.d.ts +16 -0
package/dist/enterprise/apiClient.js +121 -0
package/dist/enterprise/auth.d.ts +12 -0
package/dist/enterprise/auth.js +230 -0
package/dist/enterprise/ruleSync.d.ts +16 -0
package/dist/enterprise/ruleSync.js +81 -0
package/dist/enterprise/telemetry.d.ts +36 -0
package/dist/enterprise/telemetry.js +136 -0
package/dist/index.d.ts +16 -0
package/dist/index.js +622 -0
package/dist/install.d.ts +21 -0
package/dist/install.js +361 -0
package/dist/security/firewall.d.ts +63 -0
package/dist/security/firewall.js +202 -0
package/dist/security/sanitizer.d.ts +31 -0
package/dist/security/sanitizer.js +130 -0
package/dist/server/dashboardServer.d.ts +38 -0
package/dist/server/dashboardServer.js +92 -0
package/dist/server/wsHandler.d.ts +94 -0
package/dist/server/wsHandler.js +194 -0
package/dist/types/mcp.d.ts +123 -0
package/dist/types/mcp.js +97 -0
package/package.json +51 -0

package/dist/enterprise/auth.js ADDED Viewed

@@ -0,0 +1,230 @@
+import { exec } from 'node:child_process';
+import * as fs from 'node:fs/promises';
+import * as http from 'node:http';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+// NOTE: The spec names the session field "apiKey", but apiClient.ts was
+// established in Step 1 with "token". We use "token" throughout for
+// consistency with the existing validated schema.
+const SESSION_DIR = path.join(os.homedir(), '.mcp-shield');
+const SESSION_PATH = path.join(SESSION_DIR, 'session.json');
+// El portal SSO vive en el MISMO servidor que la API (endpoint login-mock), así
+// que su URL se deriva de MCP_SHIELD_SERVER_URL: un solo host que configurar.
+// MCP_SHIELD_AUTH_URL sigue disponible como override explícito.
+const SERVER_URL = (process.env['MCP_SHIELD_SERVER_URL'] ?? 'https://mcp-shield-server.onrender.com').replace(/\/+$/, '');
+const AUTH_URL = process.env['MCP_SHIELD_AUTH_URL'] ?? `${SERVER_URL}/api/v1/auth/login-mock`;
+const CLIENT_ID = 'mcp_shield_cli';
+const LOOPBACK_START = 3009;
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1_000;
+// ---------------------------------------------------------------------------
+// HTML success page
+// ---------------------------------------------------------------------------
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MCP-Shield — Authenticated</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: #0a0a0a;
+      color: #e5e5e5;
+    }
+    .card {
+      text-align: center;
+      padding: 3rem 4rem;
+      max-width: 520px;
+      background: #141414;
+      border: 1px solid #2a2a2a;
+      border-radius: 16px;
+      box-shadow: 0 24px 64px rgba(0, 0, 0, .6);
+    }
+    .shield { font-size: 3.5rem; margin-bottom: 1.5rem; }
+    h1 { font-size: 1.75rem; font-weight: 600; color: #22c55e; margin-bottom: .75rem; }
+    p { color: #a3a3a3; line-height: 1.65; font-size: .95rem; }
+    .badge {
+      display: inline-block;
+      margin-top: 1.75rem;
+      padding: .35rem 1rem;
+      background: #0f2a1a;
+      border: 1px solid #166534;
+      border-radius: 20px;
+      color: #86efac;
+      font-family: ui-monospace, monospace;
+      font-size: .8rem;
+      letter-spacing: .02em;
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="shield">🛡️</div>
+    <h1>Authentication successful!</h1>
+    <p>Your Enterprise session has been saved.<br>You can close this tab and return to your terminal.</p>
+    <div class="badge">mcp-shield enterprise &middot; active</div>
+  </div>
+</body>
+</html>`;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function openBrowser(url) {
+    let cmd;
+    if (process.platform === 'darwin') {
+        cmd = `open ${JSON.stringify(url)}`;
+    }
+    else if (process.platform === 'win32') {
+        // Escape & for Windows cmd.exe so it doesn't split the URL into two arguments.
+        cmd = `cmd.exe /c start "" ${JSON.stringify(url.replace(/&/g, '^&'))}`;
+    }
+    else {
+        // Linux / WSL: try xdg-open; wslview is preferred in WSL if xdg-open is absent.
+        cmd = `xdg-open ${JSON.stringify(url)} 2>/dev/null || wslview ${JSON.stringify(url)}`;
+    }
+    exec(cmd, (err) => {
+        if (err) {
+            process.stderr.write(`[mcp-shield] Browser could not be opened automatically.\n` +
+                `[mcp-shield] Please visit this URL to complete login:\n  ${url}\n`);
+        }
+    });
+}
+async function findFreePort(start) {
+    for (let port = start; port <= start + 20; port++) {
+        const available = await new Promise((resolve) => {
+            const probe = http.createServer();
+            probe.once('error', () => resolve(false));
+            probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)));
+        });
+        if (available)
+            return port;
+    }
+    return start; // last resort — the server will surface a clear bind error
+}
+async function saveSession(data) {
+    await fs.mkdir(SESSION_DIR, { recursive: true });
+    await fs.writeFile(SESSION_PATH, JSON.stringify(data, null, 2), 'utf-8');
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Returns true when ~/.mcp-shield/session.json exists and contains a valid token. */
+export async function hasSession() {
+    try {
+        const raw = await fs.readFile(SESSION_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return false;
+        const obj = parsed;
+        const token = obj['token'];
+        return typeof token === 'string' && token.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Runs the OAuth2 loopback login flow:
+ * 1. Spins up a temporary HTTP server on localhost:3009 (or next free port).
+ * 2. Opens the Enterprise auth portal in the default browser.
+ * 3. Waits for the SSO redirect to deliver the token on /callback.
+ * 4. Saves the session to ~/.mcp-shield/session.json and closes the server.
+ *
+ * Rejects on timeout (5 min), missing token, or session-write failure.
+ */
+export async function runCliLoginFlow() {
+    const port = await findFreePort(LOOPBACK_START);
+    const callbackUrl = `http://localhost:${port}/callback`;
+    const loginUrl = `${AUTH_URL}?client_id=${CLIENT_ID}&redirect_uri=${encodeURIComponent(callbackUrl)}`;
+    process.stderr.write(`[mcp-shield] Starting Enterprise login...\n`);
+    process.stderr.write(`[mcp-shield] If the browser does not open, visit:\n  ${loginUrl}\n`);
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const timeoutHandle = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            server.closeAllConnections();
+            server.close(() => reject(new Error('Login timed out after 5 minutes — no browser response received')));
+        }, LOGIN_TIMEOUT_MS);
+        // Allow the process to exit if something external kills it before the timeout.
+        timeoutHandle.unref();
+        const server = http.createServer((req, res) => {
+            const reqUrl = req.url ?? '';
+            if (!reqUrl.startsWith('/callback')) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not found');
+                return;
+            }
+            const parsedUrl = new URL(reqUrl, `http://localhost:${port}`);
+            const token = parsedUrl.searchParams.get('token');
+            const email = parsedUrl.searchParams.get('email') ?? '';
+            const errorParam = parsedUrl.searchParams.get('error');
+            // El servidor devuelve ?error=... cuando el login no puede completarse
+            // (p. ej. no existe un developer con ese email). Fallamos al instante con
+            // el mensaje en vez de esperar el timeout de 5 minutos.
+            if (errorParam) {
+                res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end(`Login failed: ${errorParam}`);
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeoutHandle);
+                    server.closeAllConnections();
+                    server.close(() => reject(new Error(`Login failed: ${errorParam}`)));
+                }
+                return;
+            }
+            if (!token) {
+                res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end('Authentication error: missing token in callback URL.');
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeoutHandle);
+                    server.closeAllConnections();
+                    server.close(() => reject(new Error('SSO callback did not include a token')));
+                }
+                return;
+            }
+            // Respond with the success page before closing so the browser renders it.
+            res.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                // Tell the browser not to reuse this connection so server.close() drains
+                // immediately after closeAllConnections().
+                'Connection': 'close',
+            });
+            res.end(SUCCESS_HTML, () => {
+                // Response body flushed to OS socket buffer — now tear down.
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutHandle);
+                server.closeAllConnections();
+                server.close(() => {
+                    saveSession({ token, email })
+                        .then(() => {
+                        process.stderr.write(`[mcp-shield] Logged in${email ? ` as ${email}` : ''}. Session saved.\n`);
+                        resolve();
+                    })
+                        .catch(reject);
+                });
+            });
+        });
+        server.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeoutHandle);
+                reject(err);
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            openBrowser(loginUrl);
+        });
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/enterprise/ruleSync.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { type SecurityRule } from '../config/rules.js';
+export declare class RuleSyncManager {
+    private readonly onRulesUpdated;
+    private timer;
+    constructor(onRulesUpdated: (rules: SecurityRule[]) => void);
+    syncRules(): Promise<void>;
+    startPolling(): void;
+    stopPolling(): void;
+}
+/**
+ * Best-effort Enterprise initialization: attempts an initial sync and starts
+ * background polling. Returns the manager on success or null if the developer
+ * has no active Enterprise session — the proxy continues with cached/default
+ * rules either way.
+ */
+export declare function tryStartEnterpriseSync(onRulesUpdated: (rules: SecurityRule[]) => void): Promise<RuleSyncManager | null>;

package/dist/enterprise/ruleSync.js ADDED Viewed

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import process from 'node:process';
+import { CACHE_PATH, isSecurityRule } from '../config/rules.js';
+import { getApiClient, PaymentRequiredError } from './apiClient.js';
+const POLL_INTERVAL_MS = 5 * 60 * 1_000;
+function isSyncResponse(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const obj = v;
+    const version = obj['version'];
+    const rules = obj['rules'];
+    if (typeof version !== 'string')
+        return false;
+    if (!Array.isArray(rules) || !rules.every(isSecurityRule))
+        return false;
+    return true;
+}
+async function saveCache(data) {
+    await fs.mkdir(path.dirname(CACHE_PATH), { recursive: true });
+    await fs.writeFile(CACHE_PATH, JSON.stringify(data, null, 2), 'utf-8');
+}
+export class RuleSyncManager {
+    onRulesUpdated;
+    timer = null;
+    constructor(onRulesUpdated) {
+        this.onRulesUpdated = onRulesUpdated;
+    }
+    async syncRules() {
+        const client = await getApiClient();
+        const raw = await client.get('/api/v1/rules/sync');
+        if (!isSyncResponse(raw)) {
+            throw new Error('MCP-Shield Enterprise: server returned an invalid rule set — ignoring update');
+        }
+        await saveCache(raw);
+        this.onRulesUpdated(raw.rules);
+    }
+    startPolling() {
+        if (this.timer !== null)
+            return;
+        this.timer = setInterval(() => {
+            this.syncRules().catch((err) => {
+                process.stderr.write(`[mcp-shield] enterprise rule sync failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            });
+        }, POLL_INTERVAL_MS);
+        // Must not keep the process alive on its own — the proxy exits when the MCP
+        // client closes the pipe, not when the polling timer fires.
+        this.timer.unref();
+    }
+    stopPolling() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+/**
+ * Best-effort Enterprise initialization: attempts an initial sync and starts
+ * background polling. Returns the manager on success or null if the developer
+ * has no active Enterprise session — the proxy continues with cached/default
+ * rules either way.
+ */
+export async function tryStartEnterpriseSync(onRulesUpdated) {
+    const manager = new RuleSyncManager(onRulesUpdated);
+    try {
+        await manager.syncRules();
+        manager.startPolling();
+        return manager;
+    }
+    catch (err) {
+        if (err instanceof PaymentRequiredError) {
+            process.stderr.write(`[mcp-shield] Enterprise features are OFF — no active subscription or the trial has expired. ` +
+                `Subscribe in the admin console to enable centralized rules and audit. Running with local rules.\n`);
+        }
+        else {
+            process.stderr.write(`[mcp-shield] enterprise sync unavailable: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=ruleSync.js.map

package/dist/enterprise/telemetry.d.ts ADDED Viewed

@@ -0,0 +1,36 @@
+/** What callers supply — manager adds timestamp and session id. */
+export interface TelemetryEventInput {
+    tool: string;
+    arguments?: Record<string, unknown>;
+    verdict: 'allowed' | 'blocked' | 'modified';
+    triggered_rule_name?: string;
+    sanitized_output_detected: boolean;
+}
+export declare class TelemetryManager {
+    private readonly email;
+    private readonly buffer;
+    private timer;
+    private flushing;
+    private warnedPaymentRequired;
+    private constructor();
+    static create(): Promise<TelemetryManager>;
+    /** Append an event to the in-memory buffer. Triggers an immediate flush if the buffer is full. */
+    record(input: TelemetryEventInput): void;
+    startFlushTimer(): void;
+    stopFlushTimer(): void;
+    /**
+     * Drains the in-memory buffer and ships it (plus any offline-queued events) to
+     * the audit endpoint. On network/server failure the buffer contents are
+     * appended to the local queue file so no audit record is ever lost.
+     *
+     * Only one flush runs at a time: concurrent calls (timer + buffer-full trigger)
+     * are no-ops until the current flush settles.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Tries to initialize the telemetry manager and start the flush timer. Returns
+ * null (and logs to stderr) if the developer has no active Enterprise session —
+ * the proxy runs without telemetry rather than failing to start.
+ */
+export declare function tryStartEnterpriseTelemetry(): Promise<TelemetryManager | null>;

package/dist/enterprise/telemetry.js ADDED Viewed

@@ -0,0 +1,136 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { getApiClient, PaymentRequiredError } from './apiClient.js';
+const QUEUE_PATH = path.join(os.homedir(), '.mcp-shield', 'telemetry.queue.json');
+const FLUSH_INTERVAL_MS = 10_000;
+const FLUSH_SIZE = 50;
+// Unique per process startup — generated once when this module is first imported.
+const SESSION_ID = `sess_${Math.random().toString(36).slice(2, 8)}`;
+// ---------------------------------------------------------------------------
+// Offline queue helpers
+// ---------------------------------------------------------------------------
+async function loadQueue() {
+    try {
+        const raw = await fs.readFile(QUEUE_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function saveQueue(events) {
+    await fs.mkdir(path.dirname(QUEUE_PATH), { recursive: true });
+    await fs.writeFile(QUEUE_PATH, JSON.stringify(events), 'utf-8');
+}
+async function clearQueue() {
+    await fs.unlink(QUEUE_PATH).catch(() => { });
+}
+async function appendToQueue(events) {
+    const existing = await loadQueue();
+    await saveQueue([...existing, ...events]);
+}
+// ---------------------------------------------------------------------------
+// TelemetryManager
+// ---------------------------------------------------------------------------
+export class TelemetryManager {
+    email;
+    buffer = [];
+    timer = null;
+    flushing = false;
+    warnedPaymentRequired = false;
+    constructor(email) {
+        this.email = email;
+    }
+    static async create() {
+        const client = await getApiClient();
+        return new TelemetryManager(client.email ?? 'unknown');
+    }
+    /** Append an event to the in-memory buffer. Triggers an immediate flush if the buffer is full. */
+    record(input) {
+        this.buffer.push({ ...input, timestamp: Date.now(), client_session_id: SESSION_ID });
+        if (this.buffer.length >= FLUSH_SIZE) {
+            void this.flush();
+        }
+    }
+    startFlushTimer() {
+        if (this.timer !== null)
+            return;
+        this.timer = setInterval(() => { void this.flush(); }, FLUSH_INTERVAL_MS);
+        // Must not prevent clean process exit — the proxy exits when the MCP client
+        // closes the pipe, not when the telemetry timer fires.
+        this.timer.unref();
+    }
+    stopFlushTimer() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Drains the in-memory buffer and ships it (plus any offline-queued events) to
+     * the audit endpoint. On network/server failure the buffer contents are
+     * appended to the local queue file so no audit record is ever lost.
+     *
+     * Only one flush runs at a time: concurrent calls (timer + buffer-full trigger)
+     * are no-ops until the current flush settles.
+     */
+    async flush() {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        // Drain atomically — new events accumulate in the buffer while we do I/O.
+        const buffered = this.buffer.splice(0);
+        try {
+            // Retry any events that failed to ship in a previous cycle (offline events
+            // come first to maintain chronological order in the audit log).
+            const queued = await loadQueue();
+            const allEvents = [...queued, ...buffered];
+            if (allEvents.length === 0)
+                return;
+            const client = await getApiClient();
+            await client.post('/api/v1/audit/logs', {
+                developer_email: this.email,
+                events: allEvents,
+            });
+            // All events shipped: the queue file is now obsolete.
+            await clearQueue();
+        }
+        catch (err) {
+            if (err instanceof PaymentRequiredError && !this.warnedPaymentRequired) {
+                this.warnedPaymentRequired = true;
+                process.stderr.write(`[mcp-shield] Enterprise audit is OFF — no active subscription or the trial has expired.\n`);
+            }
+            // Network/auth failure — persist what we just drained so it survives the
+            // next flush attempt (old queue events remain on disk untouched).
+            if (buffered.length > 0) {
+                await appendToQueue(buffered).catch(() => { });
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Best-effort startup helper
+// ---------------------------------------------------------------------------
+/**
+ * Tries to initialize the telemetry manager and start the flush timer. Returns
+ * null (and logs to stderr) if the developer has no active Enterprise session —
+ * the proxy runs without telemetry rather than failing to start.
+ */
+export async function tryStartEnterpriseTelemetry() {
+    try {
+        const manager = await TelemetryManager.create();
+        manager.startFlushTimer();
+        return manager;
+    }
+    catch (err) {
+        process.stderr.write(`[mcp-shield] enterprise telemetry unavailable: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * MCP-Shield — entry point.
+ *
+ * Transparent security proxy between an MCP client (e.g. Claude Code) and a
+ * target MCP server. The client speaks line-delimited JSON-RPC 2.0 over stdio;
+ * MCP-Shield launches the real server as a child process and sits inline,
+ * relaying every packet through its security hooks:
+ *
+ *   client (process.stdin) ──▶ [firewall + approval hooks] ──▶ target.stdin
+ *   target.stdout ──▶ [sanitizer hook] ──▶ client (process.stdout)
+ *
+ * process.stdout carries protocol traffic ONLY — every diagnostic goes to
+ * stderr, otherwise the client would try to parse it as JSON-RPC.
+ */
+export {};