@attested-intelligence/aga-mcp-server 2.0.1 → 2.2.0

package/src/middleware/governance.ts

@@ -0,0 +1,95 @@
+/**
+ * Governance Middleware - wraps every MCP tool handler.
+ *
+ * NCCoE filing Section 4: "The portal operates as a Policy Enforcement Point (PEP)...
+ * Every tool invocation, API call, actuator command, and data access passes through
+ * the portal, which evaluates it against the sealed artifact's enforcement parameters."
+ *
+ * Behavior:
+ * - TERMINATED state → reject all governed tools
+ * - PHANTOM_QUARANTINE → capture tool call as forensic input, reject
+ * - ACTIVE_MONITORING → allow, log to chain
+ * - Ungoverned tools (get_server_info, get_portal_state, list_claims) → always allow
+ */
+import type { Portal } from '../core/portal.js';
+import type { QuarantineState } from '../core/types.js';
+import { captureInput } from '../core/quarantine.js';
+import type { BehavioralMonitor } from '../core/behavioral.js';
+import { sha256Str } from '../crypto/hash.js';
+import { canonicalize } from '../utils/canonical.js';
+
+export type ToolResult = { content: Array<{ type: 'text'; text: string }> };
+export type ToolHandler<T = any> = (args: T) => Promise<ToolResult>;
+
+const UNGOVERNED_TOOLS = new Set([
+  'get_server_info',
+  'get_portal_state',
+  'get_receipts',
+  'get_chain_events',
+  'list_claims',
+  'init_chain',        // must work before attestation
+  'attest_subject',    // creates the governance relationship
+  'verify_chain',      // read-only verification
+]);
+
+export function createGovernanceWrapper(
+  portal: Portal,
+  quarantine: { current: QuarantineState | null },
+  toolName: string,
+  behavioralMonitor?: BehavioralMonitor
+) {
+  const isGoverned = !UNGOVERNED_TOOLS.has(toolName);
+
+  return function wrapHandler<T>(handler: ToolHandler<T>): ToolHandler<T> {
+    if (!isGoverned) return handler;
+
+    return async (args: T): Promise<ToolResult> => {
+      const j = (x: unknown): ToolResult => ({
+        content: [{ type: 'text', text: JSON.stringify(x, null, 2) }]
+      });
+
+      // TERMINATED → reject everything
+      if (portal.state === 'TERMINATED') {
+        return j({
+          success: false,
+          error: 'GOVERNANCE_BLOCKED: Portal is terminated. Agent governance has been revoked. Re-attestation required.',
+          portal_state: portal.state,
+          tool: toolName,
+        });
+      }
+
+      // PHANTOM_QUARANTINE → capture as forensic input, reject
+      if (portal.state === 'PHANTOM_QUARANTINE' && quarantine.current?.active) {
+        captureInput(quarantine.current, `tool_call:${toolName}`, {
+          tool: toolName,
+          args,
+          timestamp: new Date().toISOString(),
+        });
+        return j({
+          success: false,
+          error: 'GOVERNANCE_QUARANTINED: Agent is in phantom quarantine. All outputs are severed. Inputs are being captured for forensic analysis.',
+          portal_state: portal.state,
+          tool: toolName,
+          forensic_capture: true,
+        });
+      }
+
+      // INITIALIZATION or ARTIFACT_VERIFICATION → not yet governed
+      if (portal.state === 'INITIALIZATION' || portal.state === 'ARTIFACT_VERIFICATION') {
+        return j({
+          success: false,
+          error: 'GOVERNANCE_NOT_READY: No active policy artifact. Call attest_subject first.',
+          portal_state: portal.state,
+          tool: toolName,
+        });
+      }
+
+      // ACTIVE_MONITORING or DRIFT_DETECTED → record + allow through
+      if (behavioralMonitor) {
+        const argsHash = sha256Str(canonicalize(args));
+        behavioralMonitor.recordInvocation(toolName, argsHash);
+      }
+      return handler(args);
+    };
+  };
+}

package/src/middleware/index.ts

@@ -0,0 +1 @@
+export * from './governance.js';

package/src/proxy/evaluator.ts

@@ -0,0 +1,176 @@
+/**
+ * AGA Governance Proxy - Tool Policy Evaluator
+ * Ported from aga-mcp-gateway/src/governance/policy.ts with rate limiting.
+ *
+ * Patent: USPTO App. No. 19/433,835
+ * Copyright (c) 2026 Attested Intelligence Holdings LLC
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { ToolPolicy, ToolCallDecision } from './types.js';
+
+// ── Rate Limiter ────────────────────────────────────────────
+
+interface RateWindow {
+  timestamps: number[];
+}
+
+const rateLimits = new Map<string, RateWindow>();
+
+function checkRateLimit(toolName: string, maxPerMinute: number): boolean {
+  const now = Date.now();
+  const cutoff = now - 60_000;
+
+  let window = rateLimits.get(toolName);
+  if (!window) {
+    window = { timestamps: [] };
+    rateLimits.set(toolName, window);
+  }
+
+  // Prune expired entries
+  window.timestamps = window.timestamps.filter(t => t > cutoff);
+
+  if (window.timestamps.length >= maxPerMinute) return false;
+
+  window.timestamps.push(now);
+  return true;
+}
+
+export function resetRateLimits(): void {
+  rateLimits.clear();
+}
+
+// ── Path Utilities (from aga-mcp-gateway) ───────────────────
+
+export function cleanPath(p: string): string {
+  p = p.replace(/\\/g, '/');
+  p = p.replace(/\/+/g, '/');
+
+  const segments = p.split('/');
+  const resolved: string[] = [];
+  const absolute = segments[0] === '';
+
+  for (const seg of segments) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') {
+      if (resolved.length > 0 && resolved[resolved.length - 1] !== '..') {
+        resolved.pop();
+      } else if (!absolute) {
+        resolved.push('..');
+      }
+    } else {
+      resolved.push(seg);
+    }
+  }
+
+  let result = (absolute ? '/' : '') + resolved.join('/');
+  if (result === '') result = '.';
+  return result;
+}
+
+export function matchesPrefix(prefix: string, candidate: string): boolean {
+  const cleanPrefix = cleanPath(prefix);
+  const cleanCandidate = cleanPath(candidate);
+
+  if (cleanCandidate === cleanPrefix) return true;
+  const prefixWithSlash = cleanPrefix.endsWith('/') ? cleanPrefix : cleanPrefix + '/';
+  return cleanCandidate.startsWith(prefixWithSlash);
+}
+
+function checkPathConstraints(
+  constraint: { path_prefix?: string; path_keys?: string[] },
+  args?: Record<string, unknown>,
+): string | null {
+  if (!constraint.path_prefix) return null;
+  const keys = constraint.path_keys?.length ? constraint.path_keys : ['path'];
+  if (!args) return null;
+
+  for (const key of keys) {
+    const val = args[key];
+    if (typeof val === 'string') {
+      if (!matchesPrefix(constraint.path_prefix, val)) {
+        return `path "${val}" outside allowed prefix "${constraint.path_prefix}"`;
+      }
+    }
+  }
+  return null;
+}
+
+function checkDeniedPatterns(
+  constraint: { denied_patterns?: string[] },
+  args?: Record<string, unknown>,
+): string | null {
+  if (!constraint.denied_patterns?.length) return null;
+  if (!args) return null;
+
+  for (const [, val] of Object.entries(args)) {
+    if (typeof val !== 'string') continue;
+    for (const pattern of constraint.denied_patterns) {
+      if (val.includes(pattern)) {
+        return `argument value matches denied pattern "${pattern}"`;
+      }
+    }
+  }
+  return null;
+}
+
+// ── Main Evaluator ──────────────────────────────────────────
+
+export function evaluate(
+  policy: ToolPolicy,
+  toolName: string,
+  args?: Record<string, unknown>,
+): ToolCallDecision {
+  const base = { tool_name: toolName, policy_mode: policy.mode };
+
+  // Audit-only mode: always permit
+  if (policy.mode === 'audit_only') {
+    return { ...base, allowed: true, reason: 'audit_only: all calls permitted' };
+  }
+
+  if (policy.mode !== 'allowlist' && policy.mode !== 'denylist') {
+    return { ...base, allowed: false, reason: `unknown policy mode: ${policy.mode}` };
+  }
+
+  const constraint = policy.constraints[toolName];
+
+  if (policy.mode === 'allowlist') {
+    if (!constraint) {
+      return { ...base, allowed: false, reason: 'tool not in allowlist' };
+    }
+    if (!constraint.allowed) {
+      return { ...base, allowed: false, reason: 'tool explicitly disallowed' };
+    }
+
+    // Rate limit check
+    if (constraint.max_calls_per_minute) {
+      if (!checkRateLimit(toolName, constraint.max_calls_per_minute)) {
+        return { ...base, allowed: false, reason: `rate limit exceeded: ${constraint.max_calls_per_minute}/min` };
+      }
+    }
+
+    const pathResult = checkPathConstraints(constraint, args);
+    if (pathResult !== null) {
+      return { ...base, allowed: false, reason: pathResult };
+    }
+    const patternResult = checkDeniedPatterns(constraint, args);
+    if (patternResult !== null) {
+      return { ...base, allowed: false, reason: patternResult };
+    }
+    return { ...base, allowed: true, reason: 'tool permitted by allowlist' };
+  }
+
+  // Denylist mode
+  if (constraint && !constraint.allowed) {
+    return { ...base, allowed: false, reason: 'tool denied by denylist' };
+  }
+
+  // Rate limit check for denylist mode (tool not explicitly denied)
+  if (constraint?.max_calls_per_minute) {
+    if (!checkRateLimit(toolName, constraint.max_calls_per_minute)) {
+      return { ...base, allowed: false, reason: `rate limit exceeded: ${constraint.max_calls_per_minute}/min` };
+    }
+  }
+
+  return { ...base, allowed: true, reason: 'tool not denied' };
+}

package/src/proxy/index.ts

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * AGA Governance Proxy - CLI Entry Point
+ *
+ * Usage:
+ *   aga-proxy start --upstream "node server.js"     # stdio upstream
+ *   aga-proxy start --upstream-url http://host:port  # HTTP upstream
+ *   aga-proxy start --profile standard               # policy profile
+ *   aga-proxy stop
+ *   aga-proxy status
+ *   aga-proxy export --output bundle.json
+ *   aga-proxy verify bundle.json
+ *
+ * Patent: USPTO App. No. 19/433,835
+ * Copyright (c) 2026 Attested Intelligence Holdings LLC
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Command } from 'commander';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { GovernanceProxy } from './server.js';
+import { PROFILES } from './profiles.js';
+import type { ToolPolicy } from './types.js';
+
+const program = new Command();
+let proxy: GovernanceProxy | null = null;
+
+function getDataDir(): string {
+  return path.join(os.homedir(), '.aga-proxy');
+}
+
+function getPidFile(): string {
+  return path.join(getDataDir(), 'proxy.pid');
+}
+
+program
+  .name('aga-proxy')
+  .description('AGA Governance Proxy - cryptographic runtime governance for MCP tool calls')
+  .version('0.1.0');
+
+// ── start ────────────────────────────────────────────────────
+
+program
+  .command('start')
+  .description('Start the governance proxy')
+  .option('-p, --port <port>', 'Proxy port', '18800')
+  .option('--upstream <command>', 'Downstream MCP server command (stdio)')
+  .option('--upstream-url <url>', 'Downstream MCP server URL (HTTP)')
+  .option('--profile <name>', 'Policy profile: permissive, standard, restrictive', 'permissive')
+  .option('--policy <path>', 'Custom policy JSON file')
+  .action(async (opts) => {
+    const port = parseInt(opts.port, 10);
+    let policy: ToolPolicy;
+
+    if (opts.policy) {
+      policy = JSON.parse(fs.readFileSync(opts.policy, 'utf-8'));
+    } else {
+      policy = PROFILES[opts.profile] ?? PROFILES.permissive;
+    }
+
+    const upstream = opts.upstream ? parseUpstreamCommand(opts.upstream) : undefined;
+
+    proxy = new GovernanceProxy({
+      port,
+      policy,
+      upstream,
+      upstreamUrl: opts.upstreamUrl,
+    });
+
+    proxy.on('started', ({ port: p }: { port: number }) => {
+      console.log(`AGA Governance Proxy started on port ${p}`);
+      console.log(`Policy mode: ${policy.mode}`);
+      if (opts.upstream) console.log(`Upstream (stdio): ${opts.upstream}`);
+      if (opts.upstreamUrl) console.log(`Upstream (HTTP): ${opts.upstreamUrl}`);
+    });
+
+    proxy.on('error', (err: Error) => {
+      console.error(`Proxy error: ${err.message}`);
+    });
+
+    // Ensure data dir exists
+    const dataDir = getDataDir();
+    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+
+    await proxy.start();
+
+    // Write PID file
+    fs.writeFileSync(getPidFile(), String(process.pid));
+
+    // Graceful shutdown
+    const shutdown = async () => {
+      console.log('\nShutting down...');
+      if (proxy) {
+        await proxy.stop();
+        try { fs.unlinkSync(getPidFile()); } catch { /* ok */ }
+      }
+      process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });
+
+// ── run (foreground, alias for start) ────────────────────────
+
+program
+  .command('run')
+  .description('Run proxy in foreground (same as start, Ctrl+C to stop)')
+  .option('-p, --port <port>', 'Proxy port', '18800')
+  .option('--upstream <command>', 'Downstream MCP server command (stdio)')
+  .option('--upstream-url <url>', 'Downstream MCP server URL (HTTP)')
+  .option('--profile <name>', 'Policy profile', 'permissive')
+  .option('--policy <path>', 'Custom policy JSON file')
+  .action(async (opts) => {
+    // Delegate to start - identical behavior in Node.js
+    await program.commands.find(c => c.name() === 'start')!.parseAsync(
+      ['node', 'aga-proxy', 'start', ...process.argv.slice(3)],
+    );
+  });
+
+// ── stop ─────────────────────────────────────────────────────
+
+program
+  .command('stop')
+  .description('Stop the running proxy')
+  .action(async () => {
+    const pidFile = getPidFile();
+    if (!fs.existsSync(pidFile)) {
+      console.log('No running proxy found');
+      return;
+    }
+    const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+    try {
+      process.kill(pid, 'SIGTERM');
+      console.log(`Sent SIGTERM to proxy (PID ${pid})`);
+      fs.unlinkSync(pidFile);
+    } catch {
+      console.log('Proxy process not found, cleaning up PID file');
+      fs.unlinkSync(pidFile);
+    }
+  });
+
+// ── status ───────────────────────────────────────────────────
+
+program
+  .command('status')
+  .description('Show proxy status')
+  .action(async () => {
+    if (proxy) {
+      console.log(JSON.stringify(proxy.getStatus(), null, 2));
+    } else {
+      const pidFile = getPidFile();
+      if (fs.existsSync(pidFile)) {
+        const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+        try {
+          process.kill(pid, 0); // Check if alive
+          console.log(JSON.stringify({ running: true, pid }, null, 2));
+        } catch {
+          console.log(JSON.stringify({ running: false, stale_pid: pid }, null, 2));
+        }
+      } else {
+        console.log(JSON.stringify({ running: false }, null, 2));
+      }
+    }
+  });
+
+// ── export ───────────────────────────────────────────────────
+
+program
+  .command('export')
+  .description('Export evidence bundle')
+  .option('-o, --output <path>', 'Output file', 'evidence-bundle.json')
+  .action(async (opts) => {
+    if (!proxy) {
+      console.error('Proxy not running in this process. Start the proxy first.');
+      process.exit(1);
+    }
+    const bundle = await proxy.exportBundle();
+    fs.writeFileSync(opts.output, JSON.stringify(bundle, null, 2));
+    console.log(`Evidence bundle exported to ${opts.output}`);
+  });
+
+// ── verify ───────────────────────────────────────────────────
+
+program
+  .command('verify <bundle>')
+  .description('Verify an evidence bundle (Ed25519-SHA256-JCS format)')
+  .action(async (bundlePath) => {
+    const { verifyGatewayBundle } = await import('./verify.js');
+    const bundleJson = fs.readFileSync(bundlePath, 'utf-8');
+    const result = await verifyGatewayBundle(bundleJson);
+
+    console.log(`Algorithm:        ${result.algorithm_valid ? 'PASS' : 'FAIL'}`);
+    console.log(`Signatures:       ${result.receipt_signatures_valid ? 'PASS' : 'FAIL'} (${result.receipts_checked} receipts)`);
+    console.log(`Chain integrity:  ${result.chain_integrity_valid ? 'PASS' : 'FAIL'}`);
+    console.log(`Merkle proofs:    ${result.merkle_proofs_valid ? 'PASS' : 'FAIL'}`);
+    console.log(`Consistency:      ${result.bundle_consistent ? 'PASS' : 'FAIL'}`);
+    console.log(`\nOVERALL: ${result.overall_valid ? 'VERIFIED' : 'FAILED'}`);
+    if (result.error) console.log(`Error: ${result.error}`);
+
+    process.exit(result.overall_valid ? 0 : 1);
+  });
+
+// ── policy ───────────────────────────────────────────────────
+
+const policyCmd = program.command('policy').description('Policy management');
+
+policyCmd
+  .command('show')
+  .description('Show current policy')
+  .action(() => {
+    if (!proxy) {
+      console.error('Proxy not running in this process.');
+      process.exit(1);
+    }
+    console.log(JSON.stringify(proxy.getStatus(), null, 2));
+  });
+
+policyCmd
+  .command('switch <profile>')
+  .description('Switch policy profile')
+  .action(async (profile) => {
+    if (!proxy) {
+      console.error('Proxy not running in this process.');
+      process.exit(1);
+    }
+    const newPolicy = PROFILES[profile];
+    if (!newPolicy) {
+      console.error(`Unknown profile: ${profile}. Available: ${Object.keys(PROFILES).join(', ')}`);
+      process.exit(1);
+    }
+    await proxy.switchPolicy(newPolicy);
+    console.log(`Switched to ${profile} profile`);
+  });
+
+// ── helpers ──────────────────────────────────────────────────
+
+function parseUpstreamCommand(cmd: string): { command: string; args: string[] } {
+  const parts = cmd.split(/\s+/);
+  return { command: parts[0], args: parts.slice(1) };
+}
+
+// ── main ─────────────────────────────────────────────────────
+
+export { GovernanceProxy } from './server.js';
+export { evaluate, resetRateLimits } from './evaluator.js';
+export { PROFILES, PERMISSIVE, STANDARD, RESTRICTIVE } from './profiles.js';
+export type { ToolPolicy, ToolConstraint, ToolCallDecision, ProxyConfig } from './types.js';
+
+// Only parse CLI if run directly
+const isDirectRun = process.argv[1]?.includes('proxy') || process.argv[1]?.includes('aga-proxy');
+if (isDirectRun) {
+  program.parseAsync().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/proxy/profiles.ts

@@ -0,0 +1,48 @@
+/**
+ * AGA Governance Proxy - Built-in Policy Profiles
+ *
+ * Patent: USPTO App. No. 19/433,835
+ * Copyright (c) 2026 Attested Intelligence Holdings LLC
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { ToolPolicy } from './types.js';
+
+/** All tools permitted, no rate limits, logging only. */
+export const PERMISSIVE: ToolPolicy = {
+  mode: 'audit_only',
+  constraints: {},
+};
+
+/** All common tools allowed with rate limits. Dangerous patterns denied. */
+export const STANDARD: ToolPolicy = {
+  mode: 'allowlist',
+  constraints: {
+    filesystem_read:   { name: 'filesystem_read',   allowed: true, max_calls_per_minute: 30 },
+    filesystem_write:  { name: 'filesystem_write',  allowed: true, max_calls_per_minute: 30, denied_patterns: ['/etc/', '/sys/', '/proc/'] },
+    shell_execute:     { name: 'shell_execute',     allowed: true, max_calls_per_minute: 10, denied_patterns: ['rm -rf', 'mkfs', 'dd if=', ':(){:|:&};:'] },
+    web_search:        { name: 'web_search',        allowed: true, max_calls_per_minute: 20 },
+    web_fetch:         { name: 'web_fetch',         allowed: true, max_calls_per_minute: 20 },
+    send_message:      { name: 'send_message',      allowed: true, max_calls_per_minute: 5 },
+    calendar_create:   { name: 'calendar_create',   allowed: true, max_calls_per_minute: 5 },
+    memory_search:     { name: 'memory_search',     allowed: true, max_calls_per_minute: 30 },
+    memory_store:      { name: 'memory_store',      allowed: true, max_calls_per_minute: 10 },
+    code_execute:      { name: 'code_execute',      allowed: true, max_calls_per_minute: 10 },
+  },
+};
+
+/** Explicit allowlist only. All unrecognized tools denied. Low rate limits. */
+export const RESTRICTIVE: ToolPolicy = {
+  mode: 'allowlist',
+  constraints: {
+    filesystem_read:  { name: 'filesystem_read',  allowed: true, max_calls_per_minute: 10, path_prefix: '/home' },
+    web_search:       { name: 'web_search',       allowed: true, max_calls_per_minute: 5 },
+    memory_search:    { name: 'memory_search',    allowed: true, max_calls_per_minute: 10 },
+  },
+};
+
+export const PROFILES: Record<string, ToolPolicy> = {
+  permissive: PERMISSIVE,
+  standard: STANDARD,
+  restrictive: RESTRICTIVE,
+};