@permission-protocol/mcp-guard 0.1.0

package/example/README.md

@@ -0,0 +1,38 @@
+# MCP Guard Example
+
+Run this demo in 2 minutes.
+
+## Prerequisites
+
+- Node.js 20+
+- npm
+
+## Steps
+
+```bash
+# 1. Install dependencies
+cd /path/to/mcp-guard
+npm install
+
+# 2. Build
+npm run build
+
+# 3. Run the demo
+bash example/test.sh
+```
+
+## What happens
+
+The demo sends three `tools/call` requests through `mcp-guard`:
+
+| Tool | Config Rule | Result |
+|------|-----------|--------|
+| `send_email` | allow | ✅ Forwarded to server, response returned |
+| `delete_user_data` | block | 🚫 Blocked, JSON-RPC error returned |
+| `deploy_production` | require_approval | ⏸️ Held, JSON-RPC error returned |
+
+Each decision generates a receipt written to stderr and `pp-receipts.jsonl`.
+
+## Config
+
+See `pp.config.yaml` for the policy rules used in this demo.

package/example/pp.config.yaml

@@ -0,0 +1,15 @@
+default_action: allow
+mode: enforce  # or "observe" to log decisions without blocking
+
+rules:
+  - id: allow-company-email
+    tool: send_email
+    action: allow
+
+  - id: block-delete-user-data
+    tool: delete_user_data
+    action: block
+
+  - id: require-approval-prod-deploy
+    tool: deploy_production
+    action: require_approval

package/example/server.ts

@@ -0,0 +1,52 @@
+/**
+ * Tiny MCP server for testing mcp-guard.
+ * Responds to tools/call, tools/list, and initialize.
+ * Newline-delimited JSON-RPC over stdio.
+ */
+import { createInterface } from 'node:readline';
+
+const TOOLS = [
+  { name: 'send_email', description: 'Send an email', inputSchema: { type: 'object', properties: { to: { type: 'string' }, body: { type: 'string' } } } },
+  { name: 'delete_user_data', description: 'Delete all user data', inputSchema: { type: 'object', properties: { user_id: { type: 'string' } } } },
+  { name: 'deploy_production', description: 'Deploy to production', inputSchema: { type: 'object', properties: { version: { type: 'string' } } } },
+];
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on('line', (line) => {
+  if (!line.trim()) return;
+
+  let msg: any;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+
+  if (msg.method === 'initialize') {
+    respond(msg.id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'example-server', version: '0.1.0' },
+    });
+  } else if (msg.method === 'tools/list') {
+    respond(msg.id, { tools: TOOLS });
+  } else if (msg.method === 'tools/call') {
+    const toolName = msg.params?.name ?? 'unknown';
+    respond(msg.id, {
+      content: [{ type: 'text', text: `Executed ${toolName} successfully` }],
+    });
+  } else if (msg.method === 'notifications/initialized') {
+    // No response needed for notifications
+  } else {
+    respondError(msg.id, -32601, `Method not found: ${msg.method}`);
+  }
+});
+
+function respond(id: any, result: any) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+}
+
+function respondError(id: any, code: number, message: string) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n');
+}

package/example/test.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "=== MCP Guard Demo ==="
+echo ""
+echo "Building..."
+cd "$ROOT_DIR"
+npm run build --silent 2>/dev/null
+
+echo "Sending test requests through mcp-guard proxy..."
+echo ""
+
+# Create a temp file for responses
+RESPONSES=$(mktemp)
+RECEIPTS=$(mktemp)
+
+# Send three tool calls through the proxy
+{
+  # 1. Initialize
+  echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'
+  sleep 0.3
+
+  # 2. Allowed: send_email
+  echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"send_email","arguments":{"to":"user@example.com","body":"Hello!"}}}'
+  sleep 0.3
+
+  # 3. Blocked: delete_user_data
+  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"delete_user_data","arguments":{"user_id":"123"}}}'
+  sleep 0.3
+
+  # 4. Held: deploy_production
+  echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"deploy_production","arguments":{"version":"1.0.0"}}}'
+  sleep 0.3
+} | node dist/src/cli.js --config example/pp.config.yaml --agent-id demo-agent -- node dist/example/server.js > "$RESPONSES" 2>"$RECEIPTS"
+
+echo "--- Responses (stdout) ---"
+cat "$RESPONSES" | while IFS= read -r line; do
+  echo "$line" | python3 -m json.tool 2>/dev/null || echo "$line"
+done
+
+echo ""
+echo "--- Receipts (stderr) ---"
+grep "receipt:" "$RECEIPTS" | sed 's/\[mcp-guard\] receipt: //' | while IFS= read -r line; do
+  echo "$line" | python3 -m json.tool 2>/dev/null || echo "$line"
+done
+
+echo ""
+echo "--- Guard Log ---"
+grep -v "receipt:" "$RECEIPTS" || true
+
+rm -f "$RESPONSES" "$RECEIPTS"
+echo ""
+echo "=== Approval Flow ==="
+echo ""
+echo "To try the approval UI, run:"
+echo "  node dist/src/cli.js --config example/pp.config.yaml --approval-port 3100 --agent-id demo-agent -- node dist/example/server.js"
+echo ""
+echo "Then open http://localhost:3100 and send a require_approval tool call."
+echo "The proxy will hold the response until you approve or deny in the UI."
+echo ""
+echo "Done!"

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@permission-protocol/mcp-guard",
+  "version": "0.1.0",
+  "description": "MCP Guard blocks dangerous AI agent actions using a simple YAML config file.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/src/proxy.js",
+  "bin": {
+    "mcp-guard": "bin/mcp-guard"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/src/tests/*.test.js",
+    "demo": "npm run build && bash example/test.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "guard", "proxy", "ai", "safety", "permission-protocol"],
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.7.0",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/approval-server.ts

@@ -0,0 +1,136 @@
+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

@@ -0,0 +1,154 @@
+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

@@ -0,0 +1,84 @@
+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

@@ -0,0 +1,68 @@
+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

@@ -0,0 +1,31 @@
+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}"`,
+  };
+}