@permission-protocol/mcp-guard 0.1.0

package/src/pending.ts

@@ -0,0 +1,65 @@
+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);
+}

package/src/proxy.ts

@@ -0,0 +1,173 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import type { Config } from './config.js';
+import { evaluate } from './engine.js';
+import { createReceipt, emitReceipt } from './receipt.js';
+import { addPending, getAction } from './pending.js';
+import { startApprovalServer, setOnApprove, pushReceipt } from './approval-server.js';
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: any;
+}
+
+interface JsonRpcError {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  error: {
+    code: number;
+    message: string;
+  };
+}
+
+export function startProxy(config: Config, agentId: string, serverCommand: string[], approvalPort?: number): void {
+  if (serverCommand.length === 0) {
+    process.stderr.write('[mcp-guard] Error: no server command provided after --\n');
+    process.exit(1);
+  }
+
+  const approvalEnabled = approvalPort !== undefined;
+
+  // Start approval server if enabled
+  if (approvalEnabled) {
+    startApprovalServer(approvalPort);
+  }
+
+  const child: ChildProcess = spawn(serverCommand[0], serverCommand.slice(1), {
+    stdio: ['pipe', 'pipe', 'inherit'],
+  });
+
+  child.on('error', (err) => {
+    process.stderr.write(`[mcp-guard] Failed to start server: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  child.on('exit', (code) => {
+    process.stderr.write(`[mcp-guard] Server exited with code ${code}\n`);
+    process.exit(code ?? 1);
+  });
+
+  // Track pending approval responses waiting for child stdout
+  const pendingChildResponses: Map<string | number, (line: string) => void> = new Map();
+
+  // Forward child stdout → our stdout (or to pending resolver)
+  const childOut = createInterface({ input: child.stdout! });
+  childOut.on('line', (line) => {
+    // Check if this is a response to a forwarded approval
+    try {
+      const parsed = JSON.parse(line);
+      const id = parsed.id;
+      if (id != null && pendingChildResponses.has(id)) {
+        const resolver = pendingChildResponses.get(id)!;
+        pendingChildResponses.delete(id);
+        resolver(line);
+        return;
+      }
+    } catch {
+      // not JSON, pass through
+    }
+    process.stdout.write(line + '\n');
+  });
+
+  // Set up approval callback — when UI approves, forward original request to child
+  if (approvalEnabled) {
+    setOnApprove((actionId: string) => {
+      const action = getAction(actionId);
+      if (!action) return;
+      // Register a listener for the child's response
+      if (action.jsonrpcId != null) {
+        pendingChildResponses.set(action.jsonrpcId, (responseLine: string) => {
+          action.resolve(responseLine);
+        });
+      }
+      // Forward the original request to the child server
+      child.stdin!.write(action.originalLine + '\n');
+    });
+  }
+
+  // Read our stdin, inspect, and forward or reject
+  const stdinRL = createInterface({ input: process.stdin });
+  stdinRL.on('line', (line) => {
+    if (!line.trim()) return;
+
+    let msg: JsonRpcRequest;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      // Not valid JSON — forward as-is
+      child.stdin!.write(line + '\n');
+      return;
+    }
+
+    if (msg.method === 'tools/call') {
+      const toolName: string = msg.params?.name ?? 'unknown';
+      const toolArgs: Record<string, unknown> | undefined = msg.params?.arguments;
+      const decision = evaluate(toolName, toolArgs, config);
+      const serverName = serverCommand.join(' ');
+      const receipt = createReceipt(agentId, toolName, decision, msg.params, serverName, config.mode);
+      emitReceipt(receipt);
+      if (approvalEnabled) pushReceipt(receipt);
+
+      // In observe mode, always forward (log only, don't block)
+      if (config.mode === 'observe') {
+        if (decision.decision !== 'allowed') {
+          process.stderr.write(`[mcp-guard] OBSERVE: would ${decision.decision === 'blocked' ? 'block' : 'hold'} "${toolName}" but forwarding (observe mode)\n`);
+        }
+        child.stdin!.write(line + '\n');
+      } else if (decision.decision === 'allowed') {
+        child.stdin!.write(line + '\n');
+      } else if (decision.decision === 'blocked') {
+        const errResp: JsonRpcError = {
+          jsonrpc: '2.0',
+          id: msg.id ?? null,
+          error: {
+            code: -32001,
+            message: `Blocked: ${decision.reason}`,
+          },
+        };
+        process.stdout.write(JSON.stringify(errResp) + '\n');
+      } else {
+        // held_for_approval
+        if (approvalEnabled) {
+          // Hold the response — add to pending queue
+          const pending = addPending(
+            toolName,
+            toolArgs,
+            agentId,
+            decision.rule_id ?? 'unknown',
+            line,
+            msg.id ?? null,
+            (responseLine: string) => {
+              process.stdout.write(responseLine + '\n');
+            },
+          );
+          process.stderr.write(`[mcp-guard] Held "${toolName}" for approval (${pending.id}) — approve at UI\n`);
+        } else {
+          // No approval server — return error immediately (original behavior)
+          const errResp: JsonRpcError = {
+            jsonrpc: '2.0',
+            id: msg.id ?? null,
+            error: {
+              code: -32002,
+              message: `Held for approval: ${decision.reason}`,
+            },
+          };
+          process.stdout.write(JSON.stringify(errResp) + '\n');
+        }
+      }
+    } else {
+      // Pass through all non-tools/call methods
+      child.stdin!.write(line + '\n');
+    }
+  });
+
+  stdinRL.on('close', () => {
+    child.stdin!.end();
+  });
+
+  // Handle signals gracefully
+  process.on('SIGINT', () => child.kill('SIGINT'));
+  process.on('SIGTERM', () => child.kill('SIGTERM'));
+}

package/src/receipt.ts

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+import { v4 as uuidv4 } from 'uuid';
+import type { Decision } from './engine.js';
+
+export interface Receipt {
+  receipt_id: string;
+  timestamp: string;
+  agent_id: string;
+  tool_name: string;
+  decision: Decision['decision'];
+  reason: string;
+  rule_id: string | null;
+  request_payload_hash: string;
+  target_server: string;
+  mode: 'enforce' | 'observe';
+}
+
+export function createReceipt(
+  agentId: string,
+  toolName: string,
+  decision: Decision,
+  requestPayload: unknown,
+  targetServer: string = 'unknown',
+  mode: 'enforce' | 'observe' = 'enforce',
+): Receipt {
+  const payloadStr = JSON.stringify(requestPayload ?? {});
+  const hash = createHash('sha256').update(payloadStr).digest('hex');
+
+  return {
+    receipt_id: uuidv4(),
+    timestamp: new Date().toISOString(),
+    agent_id: agentId,
+    tool_name: toolName,
+    decision: decision.decision,
+    reason: decision.reason,
+    rule_id: decision.rule_id,
+    request_payload_hash: hash,
+    target_server: targetServer,
+    mode,
+  };
+}
+
+export function emitReceipt(receipt: Receipt, receiptsPath: string = 'pp-receipts.jsonl'): void {
+  const json = JSON.stringify(receipt);
+  process.stderr.write(`[mcp-guard] receipt: ${json}\n`);
+  try {
+    appendFileSync(receiptsPath, json + '\n');
+  } catch {
+    // Best effort — don't crash the proxy if file write fails
+  }
+}

package/src/tests/config.test.ts

@@ -0,0 +1,61 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFileSync, unlinkSync, mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadConfig } from '../config.js';
+
+describe('Config Parser', () => {
+  it('parses a valid config', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'mcp-guard-test-'));
+    const path = join(dir, 'config.yaml');
+    writeFileSync(path, `
+default_action: allow
+rules:
+  - id: block-delete
+    tool: delete_user_data
+    action: block
+  - id: hold-deploy
+    tool: deploy_production
+    action: require_approval
+`);
+    const config = loadConfig(path);
+    assert.equal(config.default_action, 'allow');
+    assert.equal(config.rules.length, 2);
+    assert.equal(config.rules[0].id, 'block-delete');
+    assert.equal(config.rules[0].tool, 'delete_user_data');
+    assert.equal(config.rules[0].action, 'block');
+    assert.equal(config.rules[1].action, 'require_approval');
+    assert.equal(config.mode, 'enforce'); // default
+    unlinkSync(path);
+  });
+
+  it('rejects invalid config (bad action)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'mcp-guard-test-'));
+    const path = join(dir, 'config.yaml');
+    writeFileSync(path, `
+default_action: allow
+rules:
+  - id: bad
+    tool: foo
+    action: nuke_it
+`);
+    assert.throws(() => loadConfig(path), /invalid action/i);
+    unlinkSync(path);
+  });
+
+  it('throws on missing file', () => {
+    assert.throws(() => loadConfig('/tmp/nonexistent-mcp-guard-config.yaml'), /Failed to read config/);
+  });
+
+  it('rejects config with invalid default_action', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'mcp-guard-test-'));
+    const path = join(dir, 'config.yaml');
+    writeFileSync(path, `
+default_action: yolo
+rules: []
+`);
+    assert.throws(() => loadConfig(path), /Invalid default_action/);
+    unlinkSync(path);
+  });
+});

package/src/tests/engine.test.ts

@@ -0,0 +1,47 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { evaluate } from '../engine.js';
+import type { Config } from '../config.js';
+
+describe('Decision Engine', () => {
+  const config: Config = {
+    default_action: 'allow',
+    mode: 'enforce',
+    rules: [
+      { id: 'block-delete', tool: 'delete_user_data', action: 'block' },
+      { id: 'hold-deploy', tool: 'deploy_production', action: 'require_approval' },
+      { id: 'allow-email', tool: 'send_email', action: 'allow' },
+    ],
+  };
+
+  it('matches a block rule', () => {
+    const d = evaluate('delete_user_data', undefined, config);
+    assert.equal(d.decision, 'blocked');
+    assert.equal(d.rule_id, 'block-delete');
+  });
+
+  it('matches a require_approval rule', () => {
+    const d = evaluate('deploy_production', undefined, config);
+    assert.equal(d.decision, 'held_for_approval');
+    assert.equal(d.rule_id, 'hold-deploy');
+  });
+
+  it('matches an allow rule', () => {
+    const d = evaluate('send_email', undefined, config);
+    assert.equal(d.decision, 'allowed');
+    assert.equal(d.rule_id, 'allow-email');
+  });
+
+  it('falls back to default_action: allow', () => {
+    const d = evaluate('unknown_tool', undefined, config);
+    assert.equal(d.decision, 'allowed');
+    assert.equal(d.rule_id, null);
+  });
+
+  it('falls back to default_action: block', () => {
+    const blockConfig: Config = { default_action: 'block', mode: 'enforce', rules: [] };
+    const d = evaluate('any_tool', undefined, blockConfig);
+    assert.equal(d.decision, 'blocked');
+    assert.equal(d.rule_id, null);
+  });
+});

package/src/tests/receipt.test.ts

@@ -0,0 +1,44 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createReceipt } from '../receipt.js';
+import type { Decision } from '../engine.js';
+
+describe('Receipt Emitter', () => {
+  it('generates a valid receipt with all fields', () => {
+    const decision: Decision = {
+      decision: 'blocked',
+      rule_id: 'block-delete',
+      reason: 'Matched rule "block-delete"',
+    };
+
+    const receipt = createReceipt('agent-1', 'delete_user_data', decision, { name: 'delete_user_data', arguments: {} });
+
+    assert.ok(receipt.receipt_id, 'has receipt_id');
+    assert.match(receipt.receipt_id, /^[0-9a-f-]{36}$/, 'receipt_id is UUID');
+    assert.ok(receipt.timestamp, 'has timestamp');
+    assert.doesNotThrow(() => new Date(receipt.timestamp), 'timestamp is valid ISO');
+    assert.equal(receipt.agent_id, 'agent-1');
+    assert.equal(receipt.tool_name, 'delete_user_data');
+    assert.equal(receipt.decision, 'blocked');
+    assert.equal(receipt.reason, 'Matched rule "block-delete"');
+    assert.equal(receipt.rule_id, 'block-delete');
+    assert.equal(typeof receipt.request_payload_hash, 'string');
+    assert.equal(receipt.request_payload_hash.length, 64, 'SHA-256 hex is 64 chars');
+    assert.equal(receipt.target_server, 'unknown');
+    assert.equal(receipt.mode, 'enforce');
+  });
+
+  it('hashes different payloads differently', () => {
+    const decision: Decision = { decision: 'allowed', rule_id: null, reason: 'test' };
+    const r1 = createReceipt('a', 'tool', decision, { foo: 1 });
+    const r2 = createReceipt('a', 'tool', decision, { foo: 2 });
+    assert.notEqual(r1.request_payload_hash, r2.request_payload_hash);
+  });
+
+  it('generates unique receipt IDs', () => {
+    const decision: Decision = { decision: 'allowed', rule_id: null, reason: 'test' };
+    const r1 = createReceipt('a', 'tool', decision, {});
+    const r2 = createReceipt('a', 'tool', decision, {});
+    assert.notEqual(r1.receipt_id, r2.receipt_id);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts", "example/server.ts"],
+  "exclude": ["node_modules", "dist"]
+}