@permission-protocol/mcp-guard 0.1.0 → 0.2.0

package/src/approval-server.ts

@@ -1,136 +0,0 @@
-import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
-import { getPending, getAction, resolveAction, recentResolved } from './pending.js';
-import { getApprovalHTML } from './approval-ui.js';
-import type { Receipt } from './receipt.js';
-
-/** Recent receipts store (ring buffer) */
-const recentReceipts: Receipt[] = [];
-const MAX_RECEIPTS = 50;
-
-export function pushReceipt(receipt: Receipt): void {
-  recentReceipts.push(receipt);
-  if (recentReceipts.length > MAX_RECEIPTS) recentReceipts.shift();
-}
-
-/** Callback invoked when an action is approved — proxy registers this */
-let onApproveCallback: ((id: string) => void) | null = null;
-
-export function setOnApprove(cb: (id: string) => void): void {
-  onApproveCallback = cb;
-}
-
-function parseBody(req: IncomingMessage): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    req.on('data', (c: Buffer) => chunks.push(c));
-    req.on('end', () => resolve(Buffer.concat(chunks).toString()));
-    req.on('error', reject);
-  });
-}
-
-function json(res: ServerResponse, status: number, data: unknown): void {
-  const body = JSON.stringify(data);
-  res.writeHead(status, {
-    'Content-Type': 'application/json',
-    'Access-Control-Allow-Origin': '*',
-  });
-  res.end(body);
-}
-
-function text(res: ServerResponse, status: number, msg: string): void {
-  res.writeHead(status, { 'Content-Type': 'text/plain' });
-  res.end(msg);
-}
-
-export function startApprovalServer(port: number): void {
-  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
-    const url = req.url ?? '/';
-    const method = req.method ?? 'GET';
-
-    // CORS preflight
-    if (method === 'OPTIONS') {
-      res.writeHead(204, {
-        'Access-Control-Allow-Origin': '*',
-        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-        'Access-Control-Allow-Headers': 'Content-Type',
-      });
-      res.end();
-      return;
-    }
-
-    try {
-      // GET / — Approval UI
-      if (method === 'GET' && url === '/') {
-        res.writeHead(200, { 'Content-Type': 'text/html' });
-        res.end(getApprovalHTML());
-        return;
-      }
-
-      // GET /api/pending
-      if (method === 'GET' && url === '/api/pending') {
-        const pending = getPending().map(p => ({
-          id: p.id,
-          timestamp: p.timestamp,
-          tool_name: p.tool_name,
-          tool_args: p.tool_args,
-          agent_id: p.agent_id,
-          rule_id: p.rule_id,
-          status: p.status,
-        }));
-        json(res, 200, pending);
-        return;
-      }
-
-      // POST /api/approve/:id
-      const approveMatch = url.match(/^\/api\/approve\/([a-f0-9-]+)$/);
-      if (method === 'POST' && approveMatch) {
-        const id = approveMatch[1];
-        const action = resolveAction(id, 'approved');
-        if (!action) {
-          json(res, 404, { error: 'Not found or already resolved' });
-          return;
-        }
-        process.stderr.write(`[mcp-guard] Approved: ${action.tool_name} (${id})\n`);
-        // Notify proxy to forward the original request
-        if (onApproveCallback) onApproveCallback(id);
-        json(res, 200, { id, status: 'approved' });
-        return;
-      }
-
-      // POST /api/deny/:id
-      const denyMatch = url.match(/^\/api\/deny\/([a-f0-9-]+)$/);
-      if (method === 'POST' && denyMatch) {
-        const id = denyMatch[1];
-        const action = resolveAction(id, 'denied');
-        if (!action) {
-          json(res, 404, { error: 'Not found or already resolved' });
-          return;
-        }
-        process.stderr.write(`[mcp-guard] Denied: ${action.tool_name} (${id})\n`);
-        // Return JSON-RPC error to the waiting caller
-        const errResp = JSON.stringify({
-          jsonrpc: '2.0',
-          id: action.jsonrpcId,
-          error: { code: -32002, message: 'Denied by administrator' },
-        });
-        action.resolve(errResp);
-        json(res, 200, { id, status: 'denied' });
-        return;
-      }
-
-      // GET /api/receipts
-      if (method === 'GET' && url === '/api/receipts') {
-        json(res, 200, recentReceipts.slice(-50).reverse());
-        return;
-      }
-
-      text(res, 404, 'Not found');
-    } catch (err: any) {
-      text(res, 500, err.message ?? 'Internal error');
-    }
-  });
-
-  server.listen(port, () => {
-    process.stderr.write(`[mcp-guard] Approval UI: http://localhost:${port}\n`);
-  });
-}

package/src/approval-ui.ts

@@ -1,154 +0,0 @@
-export function getApprovalHTML(): string {
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>MCP Guard — Approval Queue</title>
-<style>
-  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
-    background: #0d1117; color: #c9d1d9; line-height: 1.5;
-    padding: 24px; max-width: 900px; margin: 0 auto;
-  }
-  h1 { color: #58a6ff; font-size: 24px; margin-bottom: 4px; }
-  .subtitle { color: #8b949e; font-size: 14px; margin-bottom: 24px; }
-  .badge {
-    display: inline-block; padding: 2px 8px; border-radius: 12px;
-    font-size: 12px; font-weight: 600; text-transform: uppercase;
-  }
-  .badge-pending { background: #d29922; color: #0d1117; }
-  .badge-approved { background: #238636; color: #fff; }
-  .badge-denied { background: #da3633; color: #fff; }
-  .badge-allowed { background: #238636; color: #fff; }
-  .badge-blocked { background: #da3633; color: #fff; }
-  .badge-held_for_approval { background: #d29922; color: #0d1117; }
-  .card {
-    border: 1px solid #30363d; border-radius: 8px; padding: 16px;
-    margin-bottom: 12px; background: #161b22;
-  }
-  .card-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
-  .tool-name { font-size: 18px; font-weight: 700; color: #f0f6fc; }
-  .meta { font-size: 13px; color: #8b949e; margin-bottom: 8px; }
-  .meta span { margin-right: 16px; }
-  .args-toggle {
-    background: none; border: 1px solid #30363d; color: #58a6ff;
-    padding: 4px 10px; border-radius: 4px; cursor: pointer; font-size: 12px;
-    margin-bottom: 8px;
-  }
-  .args-toggle:hover { border-color: #58a6ff; }
-  .args-content {
-    display: none; background: #0d1117; border: 1px solid #30363d;
-    border-radius: 4px; padding: 12px; margin-bottom: 12px;
-    font-family: 'SF Mono', Consolas, monospace; font-size: 13px;
-    overflow-x: auto; white-space: pre-wrap; word-break: break-all;
-  }
-  .args-content.open { display: block; }
-  .actions { display: flex; gap: 8px; }
-  .btn {
-    padding: 6px 16px; border-radius: 6px; border: none;
-    font-size: 14px; font-weight: 600; cursor: pointer; transition: opacity 0.15s;
-  }
-  .btn:hover { opacity: 0.85; }
-  .btn:disabled { opacity: 0.4; cursor: not-allowed; }
-  .btn-approve { background: #238636; color: #fff; }
-  .btn-deny { background: #da3633; color: #fff; }
-  .empty {
-    text-align: center; padding: 40px; color: #8b949e;
-    border: 1px dashed #30363d; border-radius: 8px; margin-bottom: 24px;
-  }
-  h2 { color: #c9d1d9; font-size: 18px; margin: 24px 0 12px; }
-  table { width: 100%; border-collapse: collapse; font-size: 13px; }
-  th { text-align: left; padding: 8px; border-bottom: 2px solid #30363d; color: #8b949e; font-weight: 600; }
-  td { padding: 8px; border-bottom: 1px solid #21262d; }
-  .pulse { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: #3fb950; margin-right: 8px; animation: pulse 2s infinite; }
-  @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.3; } }
-  .status-bar { display: flex; align-items: center; font-size: 12px; color: #8b949e; margin-bottom: 16px; }
-</style>
-</head>
-<body>
-<h1>MCP Guard — Approval Queue</h1>
-<p class="subtitle">Human-in-the-loop approval for AI tool calls</p>
-<div class="status-bar"><span class="pulse"></span> Polling every 3s</div>
-
-<div id="pending"></div>
-<h2>Recent Decisions</h2>
-<div id="receipts"></div>
-
-<script>
-function esc(s) { const d = document.createElement('div'); d.textContent = s; return d.innerHTML; }
-
-function toggleArgs(btn) {
-  const c = btn.nextElementSibling;
-  c.classList.toggle('open');
-  btn.textContent = c.classList.contains('open') ? '▾ Hide arguments' : '▸ Show arguments';
-}
-
-async function act(id, action) {
-  const btns = document.querySelectorAll('[data-id="'+id+'"]');
-  btns.forEach(b => b.disabled = true);
-  try {
-    const r = await fetch('/api/' + action + '/' + id, { method: 'POST' });
-    if (!r.ok) { const e = await r.text(); alert('Error: ' + e); }
-  } catch(e) { alert('Network error'); }
-  refresh();
-}
-
-async function refresh() {
-  try {
-    const [pRes, rRes] = await Promise.all([
-      fetch('/api/pending'), fetch('/api/receipts')
-    ]);
-    const pending = await pRes.json();
-    const receipts = await rRes.json();
-
-    const pEl = document.getElementById('pending');
-    if (pending.length === 0) {
-      pEl.innerHTML = '<div class="empty">No pending approvals</div>';
-    } else {
-      pEl.innerHTML = pending.map(p => \`
-        <div class="card">
-          <div class="card-header">
-            <span class="tool-name">\${esc(p.tool_name)}</span>
-            <span class="badge badge-pending">pending</span>
-          </div>
-          <div class="meta">
-            <span>Agent: <strong>\${esc(p.agent_id)}</strong></span>
-            <span>Rule: <strong>\${esc(p.rule_id)}</strong></span>
-            <span>\${esc(new Date(p.timestamp).toLocaleTimeString())}</span>
-          </div>
-          <button class="args-toggle" onclick="toggleArgs(this)">▸ Show arguments</button>
-          <div class="args-content">\${esc(JSON.stringify(p.tool_args, null, 2))}</div>
-          <div class="actions">
-            <button class="btn btn-approve" data-id="\${p.id}" onclick="act('\${p.id}','approve')">✅ Approve</button>
-            <button class="btn btn-deny" data-id="\${p.id}" onclick="act('\${p.id}','deny')">❌ Deny</button>
-          </div>
-        </div>
-      \`).join('');
-    }
-
-    const rEl = document.getElementById('receipts');
-    if (receipts.length === 0) {
-      rEl.innerHTML = '<div class="empty">No recent decisions</div>';
-    } else {
-      rEl.innerHTML = \`<table>
-        <thead><tr><th>Time</th><th>Tool</th><th>Decision</th><th>Agent</th><th>Rule</th></tr></thead>
-        <tbody>\${receipts.map(r => \`<tr>
-          <td>\${esc(new Date(r.timestamp).toLocaleTimeString())}</td>
-          <td><strong>\${esc(r.tool_name)}</strong></td>
-          <td><span class="badge badge-\${r.decision}">\${esc(r.decision)}</span></td>
-          <td>\${esc(r.agent_id)}</td>
-          <td>\${esc(r.rule_id || '—')}</td>
-        </tr>\`).join('')}</tbody>
-      </table>\`;
-    }
-  } catch(e) { /* retry next cycle */ }
-}
-
-refresh();
-setInterval(refresh, 3000);
-</script>
-</body>
-</html>`;
-}

package/src/cli.ts

@@ -1,84 +0,0 @@
-import { loadConfig } from './config.js';
-import { startProxy } from './proxy.js';
-import { join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-
-export function main(): void {
-  const args = process.argv.slice(2);
-
-  if (args[0] === 'demo') {
-    // When running via npx @permission-protocol/mcp-guard demo
-    const scriptPath = join(__dirname, '../../example/test.sh');
-    const result = spawnSync('bash', [scriptPath], { stdio: 'inherit' });
-    process.exit(result.status ?? 0);
-  }
-
-  let configPath = './pp.config.yaml';
-  let agentId = 'unknown';
-  let modeOverride: 'enforce' | 'observe' | undefined;
-  let approvalPort: number | undefined;
-  let serverCommand: string[] = [];
-
-  const dashDashIndex = args.indexOf('--');
-  const cliArgs = dashDashIndex >= 0 ? args.slice(0, dashDashIndex) : args;
-  serverCommand = dashDashIndex >= 0 ? args.slice(dashDashIndex + 1) : [];
-
-  for (let i = 0; i < cliArgs.length; i++) {
-    if (cliArgs[i] === '--config' && cliArgs[i + 1]) {
-      configPath = cliArgs[++i];
-    } else if (cliArgs[i] === '--agent-id' && cliArgs[i + 1]) {
-      agentId = cliArgs[++i];
-    } else if (cliArgs[i] === '--mode' && cliArgs[i + 1]) {
-      const m = cliArgs[++i];
-      if (m === 'enforce' || m === 'observe') modeOverride = m;
-    } else if (cliArgs[i] === '--approval-port' && cliArgs[i + 1]) {
-      approvalPort = parseInt(cliArgs[++i], 10);
-      if (isNaN(approvalPort)) {
-        process.stderr.write('[mcp-guard] Error: --approval-port must be a number\n');
-        process.exit(1);
-      }
-    } else if (cliArgs[i] === '--help' || cliArgs[i] === '-h') {
-      printHelp();
-      process.exit(0);
-    }
-  }
-
-  if (serverCommand.length === 0) {
-    process.stderr.write('[mcp-guard] Error: No server command. Use: mcp-guard [options] -- <server command>\n');
-    process.exit(1);
-  }
-
-  const config = loadConfig(configPath);
-  if (modeOverride) config.mode = modeOverride;
-  process.stderr.write(`[mcp-guard] Loaded ${config.rules.length} rules (default: ${config.default_action}, mode: ${config.mode})\n`);
-  process.stderr.write(`[mcp-guard] Starting server: ${serverCommand.join(' ')}\n`);
-
-  startProxy(config, agentId, serverCommand, approvalPort);
-}
-
-function printHelp(): void {
-  const help = `
-mcp-guard — MCP tool-call policy proxy
-
-Usage:
-  mcp-guard [options] -- <server command>
-
-Options:
-  --config <path>         Path to config file (default: ./pp.config.yaml)
-  --agent-id <id>         Agent identifier for receipts (default: "unknown")
-  --mode <mode>           enforce or observe (overrides config; default: enforce)
-  --approval-port <port>  Enable approval UI on this port (e.g. 3100)
-  -h, --help              Show this help
-
-Example:
-  mcp-guard --config pp.config.yaml -- node my-mcp-server.js
-
-  # With approval UI:
-  mcp-guard --config pp.config.yaml --approval-port 3100 -- node my-mcp-server.js
-`.trim();
-  console.log(help);
-}
-
-main();

package/src/config.ts

@@ -1,68 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { parse } from 'yaml';
-
-export type Action = 'allow' | 'block' | 'require_approval';
-
-export interface Rule {
-  id: string;
-  tool: string;
-  action: Action;
-}
-
-export type Mode = 'enforce' | 'observe';
-
-export interface Config {
-  default_action: Action;
-  mode: Mode;
-  rules: Rule[];
-}
-
-const VALID_ACTIONS: Action[] = ['allow', 'block', 'require_approval'];
-
-export function loadConfig(configPath: string): Config {
-  let raw: string;
-  try {
-    raw = readFileSync(configPath, 'utf-8');
-  } catch (err: any) {
-    throw new Error(`Failed to read config file: ${configPath} (${err.code ?? err.message})`);
-  }
-
-  const parsed = parse(raw);
-
-  if (!parsed || typeof parsed !== 'object') {
-    throw new Error('Config must be a YAML object');
-  }
-
-  if (!VALID_ACTIONS.includes(parsed.default_action)) {
-    throw new Error(`Invalid default_action: "${parsed.default_action}". Must be one of: ${VALID_ACTIONS.join(', ')}`);
-  }
-
-  const VALID_MODES: Mode[] = ['enforce', 'observe'];
-  const mode: Mode = parsed.mode ?? 'enforce';
-  if (!VALID_MODES.includes(mode)) {
-    throw new Error(`Invalid mode: "${parsed.mode}". Must be one of: ${VALID_MODES.join(', ')}`);
-  }
-
-  if (!Array.isArray(parsed.rules)) {
-    throw new Error('Config must include a "rules" array');
-  }
-
-  const rules: Rule[] = parsed.rules.map((r: any, i: number) => {
-    if (!r.id || typeof r.id !== 'string') {
-      throw new Error(`Rule ${i} missing valid "id"`);
-    }
-    if (!r.tool || typeof r.tool !== 'string') {
-      throw new Error(`Rule ${i} missing valid "tool"`);
-    }
-    if (!VALID_ACTIONS.includes(r.action)) {
-      throw new Error(`Rule ${i} has invalid action: "${r.action}"`);
-    }
-    return { id: r.id, tool: r.tool, action: r.action as Action };
-  });
-
-  return {
-    default_action: parsed.default_action as Action,
-    mode,
-    rules,
-  };
-}

package/src/engine.ts

@@ -1,31 +0,0 @@
-import type { Config } from './config.js';
-
-export interface Decision {
-  decision: 'allowed' | 'blocked' | 'held_for_approval';
-  rule_id: string | null;
-  reason: string;
-}
-
-const ACTION_TO_DECISION = {
-  allow: 'allowed',
-  block: 'blocked',
-  require_approval: 'held_for_approval',
-} as const;
-
-export function evaluate(toolName: string, _toolArgs: Record<string, unknown> | undefined, config: Config): Decision {
-  for (const rule of config.rules) {
-    if (rule.tool === toolName) {
-      return {
-        decision: ACTION_TO_DECISION[rule.action],
-        rule_id: rule.id,
-        reason: `Matched rule "${rule.id}"`,
-      };
-    }
-  }
-
-  return {
-    decision: ACTION_TO_DECISION[config.default_action],
-    rule_id: null,
-    reason: `No matching rule; default action "${config.default_action}"`,
-  };
-}

package/src/pending.ts

@@ -1,65 +0,0 @@
-import { v4 as uuidv4 } from 'uuid';
-
-export interface PendingAction {
-  id: string;
-  timestamp: string;
-  tool_name: string;
-  tool_args: any;
-  agent_id: string;
-  rule_id: string;
-  status: 'pending' | 'approved' | 'denied';
-  /** The original JSON-RPC line to forward on approval */
-  originalLine: string;
-  /** The JSON-RPC request id for matching child responses */
-  jsonrpcId: string | number | null;
-  /** Resolver — call with the response line (or error JSON) to unblock the proxy */
-  resolve: (responseLine: string) => void;
-}
-
-const queue: Map<string, PendingAction> = new Map();
-
-export function addPending(
-  toolName: string,
-  toolArgs: any,
-  agentId: string,
-  ruleId: string,
-  originalLine: string,
-  jsonrpcId: string | number | null,
-  resolve: (responseLine: string) => void,
-): PendingAction {
-  const action: PendingAction = {
-    id: uuidv4(),
-    timestamp: new Date().toISOString(),
-    tool_name: toolName,
-    tool_args: toolArgs,
-    agent_id: agentId,
-    rule_id: ruleId,
-    status: 'pending',
-    originalLine,
-    jsonrpcId,
-    resolve,
-  };
-  queue.set(action.id, action);
-  return action;
-}
-
-export function getPending(): PendingAction[] {
-  return Array.from(queue.values()).filter(a => a.status === 'pending');
-}
-
-export function getAction(id: string): PendingAction | undefined {
-  return queue.get(id);
-}
-
-export function resolveAction(id: string, status: 'approved' | 'denied'): PendingAction | undefined {
-  const action = queue.get(id);
-  if (!action || action.status !== 'pending') return undefined;
-  action.status = status;
-  return action;
-}
-
-export function recentResolved(limit: number = 50): PendingAction[] {
-  return Array.from(queue.values())
-    .filter(a => a.status !== 'pending')
-    .slice(-limit);
-}