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

package/src/proxy/server.ts

@@ -1,499 +0,0 @@
-/**
- * AGA Governance Proxy Server
- * TCP proxy that intercepts MCP JSON-RPC 2.0 tool calls,
- * evaluates them against a sealed policy, and produces
- * Ed25519-signed governance receipts.
- *
- * Receipt format: Ed25519-SHA256-JCS (canonical across TS gateway,
- * Python SDK, Go CLI, and browser verifier).
- *
- * Architecture: Client → Proxy (:18800) → Downstream MCP Server
- * The proxy holds ALL signing keys. The client holds NONE.
- *
- * Patent: USPTO App. No. 19/433,835
- * Copyright (c) 2026 Attested Intelligence Holdings LLC
- * SPDX-License-Identifier: MIT
- */
-
-import * as net from 'node:net';
-import { EventEmitter } from 'node:events';
-import { generateKeyPair, pkToHex, signStr } from '../crypto/sign.js';
-import { bytesToHex, hexToBytes as utilHexToBytes } from '@noble/hashes/utils';
-import { sha256 } from '@noble/hashes/sha256';
-import { sha256Str } from '../crypto/hash.js';
-import { canonicalize } from '../utils/canonical.js';
-import { evaluate, resetRateLimits } from './evaluator.js';
-import { StdioBridge, type StdioBridgeOptions } from './stdio-bridge.js';
-import { PERMISSIVE } from './profiles.js';
-import { utcNow } from '../utils/timestamp.js';
-import { uuid } from '../utils/uuid.js';
-import type { ToolPolicy } from './types.js';
-import type { KeyPair } from '../crypto/types.js';
-
-// ── Gateway-format receipt (canonical across all SDKs) ──────
-
-export interface GovernanceReceipt {
-  receipt_id: string;
-  receipt_version: string;
-  algorithm: string;
-  timestamp: string;
-  request_id: string | number | null;
-  method: string;
-  tool_name: string;
-  decision: 'PERMITTED' | 'DENIED';
-  reason: string;
-  policy_reference: string;
-  arguments_hash: string;
-  previous_receipt_hash: string;
-  gateway_id: string;
-  signature: string;
-  public_key: string;
-}
-
-export interface EvidenceBundle {
-  schema_version: string;
-  bundle_id: string;
-  algorithm: string;
-  generated_at: string;
-  gateway_id: string;
-  public_key: string;
-  policy_reference: string;
-  receipts: GovernanceReceipt[];
-  merkle_root: string;
-  merkle_proofs: MerkleProof[];
-  offline_capable: boolean;
-}
-
-export interface MerkleProof {
-  leaf_hash: string;
-  leaf_index: number;
-  siblings: string[];
-  directions: ('left' | 'right')[];
-  merkle_root: string;
-}
-
-// ── Proxy options ───────────────────────────────────────────
-
-export interface ProxyServerOptions {
-  port?: number;
-  policy?: ToolPolicy;
-  upstream?: StdioBridgeOptions;
-  upstreamUrl?: string;
-  gatewayId?: string;
-}
-
-export class GovernanceProxy extends EventEmitter {
-  private server: net.Server | null = null;
-  private bridge: StdioBridge | null = null;
-
-  // Crypto key - never leaves this process
-  private signingKP: KeyPair;
-
-  // State
-  private policy: ToolPolicy;
-  private port: number;
-  private started = false;
-  private upstreamOptions: StdioBridgeOptions | null;
-  private upstreamUrl: string | null;
-  private gatewayId: string;
-
-  // Receipt chain
-  private receipts: GovernanceReceipt[] = [];
-  private lastReceiptHash: string = '';
-  private policyHash: string = '';
-
-  // Stats
-  private stats = { permitted: 0, denied: 0, total: 0, started_at: '' };
-
-  constructor(options: ProxyServerOptions = {}) {
-    super();
-    this.port = options.port ?? 18800;
-    this.policy = options.policy ?? PERMISSIVE;
-    this.upstreamOptions = options.upstream ?? null;
-    this.upstreamUrl = options.upstreamUrl ?? null;
-    this.gatewayId = options.gatewayId ?? 'aga-proxy';
-    this.signingKP = generateKeyPair();
-  }
-
-  // ── Start / Stop ───────────────────────────────────────────
-
-  async start(): Promise<void> {
-    if (this.started) throw new Error('Proxy already running');
-
-    this.policyHash = sha256Str(canonicalize(this.policy));
-
-    // Start downstream bridge if configured
-    if (this.upstreamOptions) {
-      this.bridge = new StdioBridge(this.upstreamOptions);
-      await this.bridge.start();
-      this.bridge.on('error', (err) => this.emit('error', err));
-      this.bridge.on('exit', (code: number) => {
-        process.stderr.write(`[aga-proxy] Downstream exited with code ${code}\n`);
-      });
-    }
-
-    // Start TCP server
-    this.server = net.createServer((socket) => this.handleConnection(socket));
-    await new Promise<void>((resolve, reject) => {
-      this.server!.listen(this.port, () => resolve());
-      this.server!.on('error', reject);
-    });
-
-    this.started = true;
-    this.stats.started_at = new Date().toISOString();
-    resetRateLimits();
-    this.emit('started', { port: this.port });
-  }
-
-  async stop(): Promise<void> {
-    if (!this.started) return;
-
-    if (this.bridge) {
-      await this.bridge.stop();
-      this.bridge = null;
-    }
-
-    if (this.server) {
-      await new Promise<void>((resolve) => {
-        this.server!.close(() => resolve());
-      });
-      this.server = null;
-    }
-
-    this.started = false;
-    this.emit('stopped');
-  }
-
-  // ── Connection handler ─────────────────────────────────────
-
-  private handleConnection(socket: net.Socket): void {
-    let buffer = '';
-
-    socket.on('data', (chunk) => {
-      buffer += chunk.toString();
-      const lines = buffer.split('\n');
-      buffer = lines.pop() || '';
-
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        this.handleMessage(trimmed, socket).catch((err) => {
-          process.stderr.write(`[aga-proxy] Error handling message: ${err}\n`);
-        });
-      }
-    });
-
-    socket.on('error', () => { /* client disconnected */ });
-  }
-
-  private async handleMessage(raw: string, socket: net.Socket): Promise<void> {
-    let parsed: Record<string, unknown>;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      this.respond(socket, { jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' }, id: null });
-      return;
-    }
-
-    if (parsed.jsonrpc !== '2.0') {
-      this.respond(socket, { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request: missing jsonrpc 2.0' }, id: null });
-      return;
-    }
-
-    const requestId = (parsed.id as string | number | null) ?? null;
-    const method = parsed.method as string | undefined;
-
-    // Non-tools/call methods: forward transparently
-    if (method !== 'tools/call') {
-      if (this.bridge) {
-        try {
-          const response = await this.bridge.send(parsed);
-          this.respond(socket, response);
-        } catch (err) {
-          this.respond(socket, {
-            jsonrpc: '2.0',
-            error: { code: -32603, message: `Downstream error: ${err}` },
-            id: requestId,
-          });
-        }
-      } else if (this.upstreamUrl) {
-        await this.forwardHttp(raw, socket, requestId);
-      } else {
-        this.respond(socket, {
-          jsonrpc: '2.0',
-          error: { code: -32603, message: 'No upstream configured' },
-          id: requestId,
-        });
-      }
-      return;
-    }
-
-    // tools/call - governance intercept
-    await this.interceptToolCall(parsed, socket, requestId);
-  }
-
-  // ── Tool call interception ─────────────────────────────────
-
-  private async interceptToolCall(
-    parsed: Record<string, unknown>,
-    socket: net.Socket,
-    requestId: string | number | null,
-  ): Promise<void> {
-    const params = parsed.params as Record<string, unknown> | undefined;
-    const toolName = params?.name as string | undefined;
-    const toolArgs = params?.arguments as Record<string, unknown> | undefined;
-
-    this.stats.total++;
-
-    // Fail-closed: no tool name
-    if (!toolName) {
-      const receipt = this.generateReceipt('UNKNOWN', 'DENIED', 'tool name extraction failed, fail-closed', requestId, undefined);
-      this.stats.denied++;
-      this.respond(socket, {
-        jsonrpc: '2.0',
-        error: {
-          code: -32600,
-          message: 'Missing tool name',
-          data: { receipt_id: receipt.receipt_id, decision: 'DENIED' },
-        },
-        id: requestId,
-      });
-      return;
-    }
-
-    // Evaluate against policy
-    const decision = evaluate(this.policy, toolName, toolArgs);
-    const receipt = this.generateReceipt(
-      toolName,
-      decision.allowed ? 'PERMITTED' : 'DENIED',
-      decision.reason,
-      requestId,
-      toolArgs,
-    );
-
-    if (!decision.allowed) {
-      this.stats.denied++;
-      this.respond(socket, {
-        jsonrpc: '2.0',
-        error: {
-          code: -32600,
-          message: `Tool denied: ${decision.reason}`,
-          data: { receipt_id: receipt.receipt_id, decision: 'DENIED', reason: decision.reason },
-        },
-        id: requestId,
-      });
-      return;
-    }
-
-    // Permitted - forward to downstream
-    this.stats.permitted++;
-
-    if (this.bridge) {
-      try {
-        const response = await this.bridge.send(parsed);
-        this.respond(socket, response);
-      } catch (err) {
-        this.respond(socket, {
-          jsonrpc: '2.0',
-          error: { code: -32603, message: `Downstream error: ${err}` },
-          id: requestId,
-        });
-      }
-    } else if (this.upstreamUrl) {
-      await this.forwardHttp(JSON.stringify(parsed), socket, requestId);
-    } else {
-      // No upstream - return success with receipt info
-      this.respond(socket, {
-        jsonrpc: '2.0',
-        result: {
-          content: [{ type: 'text', text: JSON.stringify({ permitted: true, receipt_id: receipt.receipt_id, tool: toolName }) }],
-        },
-        id: requestId,
-      });
-    }
-  }
-
-  // ── Receipt generation (Ed25519-SHA256-JCS canonical format) ─
-
-  private generateReceipt(
-    toolName: string,
-    decision: 'PERMITTED' | 'DENIED',
-    reason: string,
-    requestId: string | number | null,
-    toolArgs: Record<string, unknown> | undefined,
-  ): GovernanceReceipt {
-    const pubKeyHex = pkToHex(this.signingKP.publicKey);
-
-    // Arguments hash tri-state per spec Section 3.5
-    let argumentsHash: string;
-    if (toolArgs === undefined) {
-      argumentsHash = '';
-    } else {
-      argumentsHash = sha256Str(canonicalize(toolArgs));
-    }
-
-    const unsigned = {
-      receipt_id: uuid(),
-      receipt_version: '1.0',
-      algorithm: 'Ed25519-SHA256-JCS',
-      timestamp: utcNow(),
-      request_id: requestId,
-      method: 'tools/call',
-      tool_name: toolName,
-      decision,
-      reason,
-      policy_reference: this.policyHash,
-      arguments_hash: argumentsHash,
-      previous_receipt_hash: this.lastReceiptHash,
-      gateway_id: this.gatewayId,
-      public_key: pubKeyHex,
-    };
-
-    const sig = signStr(canonicalize(unsigned), this.signingKP.secretKey);
-    const receipt: GovernanceReceipt = { ...unsigned, signature: bytesToHex(sig) };
-
-    this.receipts.push(receipt);
-    this.lastReceiptHash = sha256Str(canonicalize(receipt));
-
-    return receipt;
-  }
-
-  // ── Merkle tree (binary, odd-node promotion, binary concat) ─
-
-  private merkleNodeHash(leftHex: string, rightHex: string): string {
-    const left = utilHexToBytes(leftHex);
-    const right = utilHexToBytes(rightHex);
-    const combined = new Uint8Array(left.length + right.length);
-    combined.set(left, 0);
-    combined.set(right, left.length);
-    return bytesToHex(sha256(combined));
-  }
-
-  private computeMerkleRoot(leaves: string[]): string {
-    if (leaves.length === 0) return '';
-    if (leaves.length === 1) return leaves[0];
-    let level = [...leaves];
-    while (level.length > 1) {
-      const next: string[] = [];
-      for (let i = 0; i < level.length; i += 2) {
-        if (i + 1 < level.length) {
-          next.push(this.merkleNodeHash(level[i], level[i + 1]));
-        } else {
-          next.push(level[i]);
-        }
-      }
-      level = next;
-    }
-    return level[0];
-  }
-
-  private computeMerkleProof(leaves: string[], leafIndex: number): MerkleProof {
-    const siblings: string[] = [];
-    const directions: ('left' | 'right')[] = [];
-    let level = [...leaves];
-    let idx = leafIndex;
-
-    while (level.length > 1) {
-      const next: string[] = [];
-      for (let i = 0; i < level.length; i += 2) {
-        if (i + 1 < level.length) {
-          next.push(this.merkleNodeHash(level[i], level[i + 1]));
-        } else {
-          next.push(level[i]);
-        }
-      }
-      if (idx % 2 === 0) {
-        if (idx + 1 < level.length) {
-          siblings.push(level[idx + 1]);
-          directions.push('right');
-        }
-      } else {
-        siblings.push(level[idx - 1]);
-        directions.push('left');
-      }
-      idx = Math.floor(idx / 2);
-      level = next;
-    }
-
-    return {
-      leaf_hash: leaves[leafIndex],
-      leaf_index: leafIndex,
-      siblings,
-      directions,
-      merkle_root: level[0],
-    };
-  }
-
-  // ── HTTP forwarding ────────────────────────────────────────
-
-  private async forwardHttp(body: string, socket: net.Socket, requestId: string | number | null): Promise<void> {
-    try {
-      const resp = await fetch(this.upstreamUrl!, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body,
-      });
-      const data = await resp.json();
-      this.respond(socket, data as Record<string, unknown>);
-    } catch (err) {
-      this.respond(socket, {
-        jsonrpc: '2.0',
-        error: { code: -32603, message: `HTTP upstream error: ${err}` },
-        id: requestId,
-      });
-    }
-  }
-
-  // ── Response helper ────────────────────────────────────────
-
-  private respond(socket: net.Socket, msg: Record<string, unknown>): void {
-    if (!socket.destroyed) {
-      socket.write(JSON.stringify(msg) + '\n');
-    }
-  }
-
-  // ── Public API ─────────────────────────────────────────────
-
-  async switchPolicy(newPolicy: ToolPolicy): Promise<void> {
-    this.policy = newPolicy;
-    this.policyHash = sha256Str(canonicalize(newPolicy));
-    resetRateLimits();
-    this.emit('policy_switched');
-  }
-
-  exportBundle(): EvidenceBundle {
-    if (this.receipts.length === 0) throw new Error('No receipts');
-
-    const leafHashes = this.receipts.map(r => sha256Str(canonicalize(r)));
-    const root = this.computeMerkleRoot(leafHashes);
-    const proofs = leafHashes.map((_, i) => this.computeMerkleProof(leafHashes, i));
-
-    return {
-      schema_version: '1.0',
-      bundle_id: uuid(),
-      algorithm: 'Ed25519-SHA256-JCS',
-      generated_at: utcNow(),
-      gateway_id: this.gatewayId,
-      public_key: pkToHex(this.signingKP.publicKey),
-      policy_reference: this.policyHash,
-      receipts: this.receipts,
-      merkle_root: root,
-      merkle_proofs: proofs,
-      offline_capable: true,
-    };
-  }
-
-  getStatus() {
-    return {
-      running: this.started,
-      port: this.port,
-      policy_mode: this.policy.mode,
-      receipt_count: this.receipts.length,
-      ...this.stats,
-      public_key: pkToHex(this.signingKP.publicKey),
-    };
-  }
-
-  getPublicKey(): string { return pkToHex(this.signingKP.publicKey); }
-  getReceipts(): GovernanceReceipt[] { return this.receipts; }
-}

package/src/proxy/stdio-bridge.ts

@@ -1,171 +0,0 @@
-/**
- * AGA Governance Proxy - Stdio Bridge
- * Spawns a downstream MCP server as a child process and manages
- * JSON-RPC message framing over stdin/stdout.
- *
- * Patent: USPTO App. No. 19/433,835
- * Copyright (c) 2026 Attested Intelligence Holdings LLC
- * SPDX-License-Identifier: MIT
- */
-
-import { spawn, type ChildProcess } from 'node:child_process';
-import { EventEmitter } from 'node:events';
-
-export interface StdioBridgeOptions {
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-  cwd?: string;
-}
-
-/**
- * Bridges JSON-RPC messages to/from a child process via stdio.
- * Handles newline-delimited JSON framing.
- */
-export class StdioBridge extends EventEmitter {
-  private child: ChildProcess | null = null;
-  private buffer = '';
-  private pendingRequests = new Map<string | number, {
-    resolve: (response: Record<string, unknown>) => void;
-    reject: (error: Error) => void;
-    timer: ReturnType<typeof setTimeout>;
-  }>();
-
-  constructor(private options: StdioBridgeOptions) {
-    super();
-  }
-
-  async start(): Promise<void> {
-    const { command, args = [], env, cwd } = this.options;
-
-    this.child = spawn(command, args, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, ...env },
-      cwd,
-      shell: process.platform === 'win32',
-    });
-
-    this.child.stdout!.on('data', (chunk: Buffer) => {
-      this.buffer += chunk.toString();
-      this.processBuffer();
-    });
-
-    this.child.stderr!.on('data', (chunk: Buffer) => {
-      // Log downstream stderr but don't treat as JSON-RPC
-      process.stderr.write(`[downstream] ${chunk.toString()}`);
-    });
-
-    this.child.on('exit', (code, signal) => {
-      this.emit('exit', code, signal);
-      this.rejectAllPending(new Error(`Downstream process exited: code=${code} signal=${signal}`));
-    });
-
-    this.child.on('error', (err) => {
-      this.emit('error', err);
-      this.rejectAllPending(err);
-    });
-  }
-
-  private processBuffer(): void {
-    const lines = this.buffer.split('\n');
-    // Keep the last (possibly incomplete) line in the buffer
-    this.buffer = lines.pop() || '';
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-
-      try {
-        const msg = JSON.parse(trimmed) as Record<string, unknown>;
-        this.handleMessage(msg);
-      } catch {
-        // Not valid JSON - skip
-      }
-    }
-  }
-
-  private handleMessage(msg: Record<string, unknown>): void {
-    // If it has an id and either result or error, it's a response
-    if ('id' in msg && ('result' in msg || 'error' in msg)) {
-      const id = msg.id as string | number;
-      const pending = this.pendingRequests.get(id);
-      if (pending) {
-        clearTimeout(pending.timer);
-        this.pendingRequests.delete(id);
-        pending.resolve(msg);
-      }
-      return;
-    }
-
-    // Notifications from downstream (no id, or has method) - emit for proxy to handle
-    this.emit('notification', msg);
-  }
-
-  /**
-   * Send a JSON-RPC request to the downstream server and wait for a response.
-   */
-  async send(message: Record<string, unknown>, timeoutMs = 30_000): Promise<Record<string, unknown>> {
-    if (!this.child?.stdin?.writable) {
-      throw new Error('Downstream process not running');
-    }
-
-    const id = message.id as string | number | undefined;
-
-    // Notifications (no id) - fire and forget
-    if (id === undefined || id === null) {
-      this.child.stdin.write(JSON.stringify(message) + '\n');
-      return { jsonrpc: '2.0', result: null, id: null };
-    }
-
-    return new Promise<Record<string, unknown>>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(id);
-        reject(new Error(`Timeout waiting for response to request ${id}`));
-      }, timeoutMs);
-
-      this.pendingRequests.set(id, { resolve, reject, timer });
-      this.child!.stdin!.write(JSON.stringify(message) + '\n');
-    });
-  }
-
-  /**
-   * Send a raw message without waiting for a response.
-   */
-  sendRaw(message: Record<string, unknown>): void {
-    if (!this.child?.stdin?.writable) {
-      throw new Error('Downstream process not running');
-    }
-    this.child.stdin.write(JSON.stringify(message) + '\n');
-  }
-
-  async stop(): Promise<void> {
-    this.rejectAllPending(new Error('Bridge stopped'));
-    if (this.child) {
-      this.child.kill('SIGTERM');
-      // Give it a moment, then force kill
-      await new Promise<void>(resolve => {
-        const timer = setTimeout(() => {
-          this.child?.kill('SIGKILL');
-          resolve();
-        }, 3000);
-        this.child!.on('exit', () => {
-          clearTimeout(timer);
-          resolve();
-        });
-      });
-      this.child = null;
-    }
-  }
-
-  get running(): boolean {
-    return this.child !== null && this.child.exitCode === null;
-  }
-
-  private rejectAllPending(err: Error): void {
-    for (const [id, pending] of this.pendingRequests) {
-      clearTimeout(pending.timer);
-      pending.reject(err);
-    }
-    this.pendingRequests.clear();
-  }
-}

package/src/proxy/types.ts

@@ -1,40 +0,0 @@
-/**
- * AGA Governance Proxy - Types
- * Adapted from aga-mcp-gateway/src/governance/types.ts
- *
- * Patent: USPTO App. No. 19/433,835
- * Copyright (c) 2026 Attested Intelligence Holdings LLC
- * SPDX-License-Identifier: MIT
- */
-
-export interface ToolConstraint {
-  name: string;
-  allowed: boolean;
-  max_calls_per_minute?: number;
-  path_prefix?: string;
-  path_keys?: string[];
-  denied_patterns?: string[];
-}
-
-export interface ToolPolicy {
-  mode: 'allowlist' | 'denylist' | 'audit_only';
-  constraints: Record<string, ToolConstraint>;
-}
-
-export interface ToolCallDecision {
-  allowed: boolean;
-  reason: string;
-  tool_name: string;
-  policy_mode: string;
-}
-
-export interface ProxyConfig {
-  port: number;
-  upstream: string;
-  upstreamType: 'stdio' | 'http';
-  policy: ToolPolicy;
-  dataDir: string;
-}
-
-export const DEFAULT_PROXY_PORT = 18800;
-export const DEFAULT_DATA_DIR = '.aga-proxy';