protect-mcp 0.2.2 → 0.3.1

package/dist/demo-server.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+// src/demo-server.ts
+import { createInterface } from "readline";
+var TOOLS = [
+  {
+    name: "read_file",
+    description: "Read the contents of a file",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string", description: "File path to read" } },
+      required: ["path"]
+    }
+  },
+  {
+    name: "write_file",
+    description: "Write content to a file",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path to write" },
+        content: { type: "string", description: "Content to write" }
+      },
+      required: ["path", "content"]
+    }
+  },
+  {
+    name: "delete_file",
+    description: "Delete a file from the filesystem",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string", description: "File path to delete" } },
+      required: ["path"]
+    }
+  },
+  {
+    name: "web_search",
+    description: "Search the web for information",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string", description: "Search query" } },
+      required: ["query"]
+    }
+  },
+  {
+    name: "deploy",
+    description: "Deploy the application to production",
+    inputSchema: {
+      type: "object",
+      properties: {
+        environment: { type: "string", description: "Target environment", enum: ["staging", "production"] },
+        reason: { type: "string", description: "Deployment reason" }
+      },
+      required: ["environment"]
+    }
+  }
+];
+function handleRequest(request) {
+  if (request.method === "initialize") {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id: request.id,
+      result: {
+        protocolVersion: "2024-11-05",
+        serverInfo: { name: "protect-mcp-demo", version: "0.2.0" },
+        capabilities: { tools: {} }
+      }
+    });
+  }
+  if (request.method === "notifications/initialized") {
+    return "";
+  }
+  if (request.method === "tools/list") {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id: request.id,
+      result: { tools: TOOLS }
+    });
+  }
+  if (request.method === "tools/call") {
+    const toolName = request.params?.name || "unknown";
+    const args = request.params?.arguments || {};
+    let resultText;
+    switch (toolName) {
+      case "read_file":
+        resultText = `[demo] Read file: ${args.path || "/example.txt"}
+Contents: Hello from protect-mcp demo server!`;
+        break;
+      case "write_file":
+        resultText = `[demo] Wrote ${String(args.content || "").length} bytes to ${args.path || "/example.txt"}`;
+        break;
+      case "delete_file":
+        resultText = `[demo] Deleted file: ${args.path || "/example.txt"}`;
+        break;
+      case "web_search":
+        resultText = `[demo] Search results for "${args.query || "test"}":
+1. Example result \u2014 scopeblind.com
+2. MCP security \u2014 modelcontextprotocol.io`;
+        break;
+      case "deploy":
+        resultText = `[demo] Deployed to ${args.environment || "staging"}${args.reason ? ` (reason: ${args.reason})` : ""}`;
+        break;
+      default:
+        resultText = `[demo] Unknown tool: ${toolName}`;
+    }
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id: request.id,
+      result: {
+        content: [{ type: "text", text: resultText }]
+      }
+    });
+  }
+  if (request.id !== void 0) {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id: request.id,
+      error: { code: -32601, message: `Method not found: ${request.method}` }
+    });
+  }
+  return "";
+}
+var rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  try {
+    const request = JSON.parse(trimmed);
+    const response = handleRequest(request);
+    if (response) {
+      process.stdout.write(response + "\n");
+    }
+  } catch {
+  }
+});
+process.stderr.write("[DEMO_SERVER] protect-mcp demo server started \u2014 5 tools registered\n");

package/dist/index.d.mts

@@ -21,6 +21,8 @@ interface ToolPolicy {
     rate_limit?: string;
     /** Explicitly block this tool */
     block?: boolean;
+    /** Require human approval before executing (non-blocking: returns MCP error for LLM to suspend) */
+    require_approval?: boolean;
     /** Minimum trust tier required for this tool (v2) */
     min_tier?: TrustTier;
     /** Tier-specific rate limits (v2) */
@@ -113,9 +115,9 @@ interface DecisionLog {
     /** Tool name that was called */
     tool: string;
     /** Decision: allow or deny */
-    decision: 'allow' | 'deny';
+    decision: 'allow' | 'deny' | 'require_approval';
     /** Why this decision was made */
-    reason_code: 'policy_allow' | 'policy_block' | 'rate_limit_exceeded' | 'observe_mode' | 'default_allow' | 'tier_insufficient' | 'external_pdp_allow' | 'external_pdp_deny' | 'external_pdp_error';
+    reason_code: string;
     /** SHA-256 digest of the canonicalized policy file */
     policy_digest: string;
     /** Which policy engine made the decision */
@@ -154,6 +156,63 @@ interface ProtectConfig {
     credentials?: Record<string, CredentialConfig>;
 }
 
+/**
+ * Summary of evidence for tier evaluation.
+ */
+interface EvidenceSummary$1 {
+    receipt_count: number;
+    epoch_span: number;
+    issuer_count: number;
+}
+/**
+ * Thresholds for the 'evidenced' tier.
+ */
+interface EvidenceThresholds {
+    min_receipts: number;
+    min_epoch_span: number;
+    min_issuers: number;
+}
+/**
+ * Evidence store — tracks receipt history per agent.
+ */
+declare class EvidenceStore {
+    private agents;
+    private filePath;
+    private dirty;
+    constructor(dir?: string);
+    /**
+     * Record a receipt observation for an agent.
+     */
+    record(agentId: string, issuer: string, timestamp?: string): void;
+    /**
+     * Get the evidence summary for an agent.
+     */
+    getSummary(agentId: string): EvidenceSummary$1;
+    /**
+     * Check if an agent meets the evidenced tier thresholds.
+     */
+    meetsEvidencedThreshold(agentId: string, thresholds?: EvidenceThresholds): boolean;
+    /**
+     * Persist to disk (call periodically or on shutdown).
+     */
+    save(): void;
+    /**
+     * Load from disk.
+     */
+    private load;
+    /**
+     * Get total agent count (for status display).
+     */
+    agentCount(): number;
+    /**
+     * Get all agent summaries (for status display).
+     */
+    allSummaries(): Array<{
+        agent_id: string;
+        summary: EvidenceSummary$1;
+    }>;
+}
+
 /**
  * @scopeblind/protect-mcp — Trust Tier Admission Evaluator
  *
@@ -163,8 +222,7 @@ interface ProtectConfig {
  *
  * Tiers (ascending): unknown → signed-known → evidenced → privileged
  *
- * Sprint 2: Simple evaluation (has valid manifest = signed-known).
- * Full evidence evaluation (evidenced tier) is stubbed.
+ * v2: Real evidence evaluation via EvidenceStore when available.
  */
 
 /**
@@ -180,7 +238,7 @@ interface ManifestPresentation {
     public_key?: string;
     /** Whether the manifest signature was verified */
     signature_valid?: boolean;
-    /** Optional evidence summary for tier upgrade */
+    /** Optional evidence summary for tier upgrade (inline, without store) */
     evidence_summary?: {
         receipt_count: number;
         epoch_span: number;
@@ -201,92 +259,56 @@ interface AdmissionResult {
  * Maps agent IDs to explicitly assigned tiers.
  */
 type TierOverrides = Record<string, TrustTier>;
+/**
+ * Options for tier evaluation.
+ */
+interface EvaluateTierOptions {
+    overrides?: TierOverrides;
+    evidenceStore?: EvidenceStore;
+    thresholds?: EvidenceThresholds;
+}
 /**
  * Evaluate an agent's trust tier based on their presented credentials.
  *
  * @param manifest - Manifest presentation from the agent (or null if none)
- * @param overrides - Operator-configured tier overrides
+ * @param opts - Evaluation options (overrides, evidence store, thresholds)
  * @returns AdmissionResult with assigned tier
  */
-declare function evaluateTier(manifest: ManifestPresentation | null, overrides?: TierOverrides): AdmissionResult;
+declare function evaluateTier(manifest: ManifestPresentation | null, opts?: TierOverrides | EvaluateTierOptions): AdmissionResult;
 /**
  * Check if a trust tier meets the minimum required tier.
  */
 declare function meetsMinTier(actual: TrustTier, required: TrustTier): boolean;
 
-/**
- * ProtectGateway — stdio MITM proxy for MCP servers.
- *
- * Sits between an MCP client (stdin/stdout) and a wrapped MCP server (child process).
- * Intercepts `tools/call` requests for policy enforcement and decision logging.
- * Passes through all other JSON-RPC messages transparently.
- *
- * v2 features:
- * - Shadow mode (default): observe + signed receipts, no blocking
- * - Trust-tier gating: evaluate manifest at admission, assign tier
- * - Credential vault: inject secrets, agent never sees raw keys
- * - BYOPE: pluggable policy decision via external HTTP webhook
- * - Signed receipts: every decision produces a signed artifact
- */
 declare class ProtectGateway {
     private child;
     private config;
     private rateLimitStore;
     private clientReader;
+    private logFilePath;
+    private receiptFilePath;
+    private evidenceStore;
+    private receiptBuffer;
+    /** Approval grants keyed by request_id (scoped to the specific action that was requested) */
+    private approvalStore;
+    /** Random nonce generated at startup — required for approval endpoint authentication */
+    private readonly approvalNonce;
     private currentTier;
     private admissionResult;
     constructor(config: ProtectConfig);
-    /**
-     * Start the gateway: spawn child process and wire up message relay.
-     */
     start(): Promise<void>;
-    /**
-     * Set the trust tier for this session.
-     * Called at admission (first interaction) or by explicit manifest presentation.
-     */
     setManifest(manifest: ManifestPresentation | null): AdmissionResult;
-    /**
-     * Handle a message from the MCP client (stdin).
-     * Intercept tools/call requests; pass through everything else.
-     */
     private handleClientMessage;
-    /**
-     * Handle a message from the wrapped MCP server (child stdout).
-     * Forward to client (stdout) transparently.
-     */
+    private interceptToolCallAsync;
     private handleServerMessage;
-    /**
-     * Intercept a tools/call request. Returns a JSON-RPC error response if denied, null if allowed.
-     */
+    private injectParamsCredentials;
     private interceptToolCall;
-    /**
-     * Get the applicable rate limit spec based on the agent's tier.
-     */
     private getTierRateLimit;
-    /**
-     * Emit a structured decision log to stderr.
-     * If signing is enabled, also emits a signed artifact.
-     */
     private emitDecisionLog;
-    /**
-     * Create a JSON-RPC error response.
-     */
     private makeErrorResponse;
-    /**
-     * Send a message to the child process (wrapped MCP server).
-     */
     private sendToChild;
-    /**
-     * Send a message to the MCP client (stdout).
-     */
     private sendToClient;
-    /**
-     * Log a message to stderr (debug output).
-     */
     private log;
-    /**
-     * Stop the gateway: kill child process and exit.
-     */
     stop(): void;
 }
 

package/dist/index.d.ts

@@ -21,6 +21,8 @@ interface ToolPolicy {
     rate_limit?: string;
     /** Explicitly block this tool */
     block?: boolean;
+    /** Require human approval before executing (non-blocking: returns MCP error for LLM to suspend) */
+    require_approval?: boolean;
     /** Minimum trust tier required for this tool (v2) */
     min_tier?: TrustTier;
     /** Tier-specific rate limits (v2) */
@@ -113,9 +115,9 @@ interface DecisionLog {
     /** Tool name that was called */
     tool: string;
     /** Decision: allow or deny */
-    decision: 'allow' | 'deny';
+    decision: 'allow' | 'deny' | 'require_approval';
     /** Why this decision was made */
-    reason_code: 'policy_allow' | 'policy_block' | 'rate_limit_exceeded' | 'observe_mode' | 'default_allow' | 'tier_insufficient' | 'external_pdp_allow' | 'external_pdp_deny' | 'external_pdp_error';
+    reason_code: string;
     /** SHA-256 digest of the canonicalized policy file */
     policy_digest: string;
     /** Which policy engine made the decision */
@@ -154,6 +156,63 @@ interface ProtectConfig {
     credentials?: Record<string, CredentialConfig>;
 }
 
+/**
+ * Summary of evidence for tier evaluation.
+ */
+interface EvidenceSummary$1 {
+    receipt_count: number;
+    epoch_span: number;
+    issuer_count: number;
+}
+/**
+ * Thresholds for the 'evidenced' tier.
+ */
+interface EvidenceThresholds {
+    min_receipts: number;
+    min_epoch_span: number;
+    min_issuers: number;
+}
+/**
+ * Evidence store — tracks receipt history per agent.
+ */
+declare class EvidenceStore {
+    private agents;
+    private filePath;
+    private dirty;
+    constructor(dir?: string);
+    /**
+     * Record a receipt observation for an agent.
+     */
+    record(agentId: string, issuer: string, timestamp?: string): void;
+    /**
+     * Get the evidence summary for an agent.
+     */
+    getSummary(agentId: string): EvidenceSummary$1;
+    /**
+     * Check if an agent meets the evidenced tier thresholds.
+     */
+    meetsEvidencedThreshold(agentId: string, thresholds?: EvidenceThresholds): boolean;
+    /**
+     * Persist to disk (call periodically or on shutdown).
+     */
+    save(): void;
+    /**
+     * Load from disk.
+     */
+    private load;
+    /**
+     * Get total agent count (for status display).
+     */
+    agentCount(): number;
+    /**
+     * Get all agent summaries (for status display).
+     */
+    allSummaries(): Array<{
+        agent_id: string;
+        summary: EvidenceSummary$1;
+    }>;
+}
+
 /**
  * @scopeblind/protect-mcp — Trust Tier Admission Evaluator
  *
@@ -163,8 +222,7 @@ interface ProtectConfig {
  *
  * Tiers (ascending): unknown → signed-known → evidenced → privileged
  *
- * Sprint 2: Simple evaluation (has valid manifest = signed-known).
- * Full evidence evaluation (evidenced tier) is stubbed.
+ * v2: Real evidence evaluation via EvidenceStore when available.
  */
 
 /**
@@ -180,7 +238,7 @@ interface ManifestPresentation {
     public_key?: string;
     /** Whether the manifest signature was verified */
     signature_valid?: boolean;
-    /** Optional evidence summary for tier upgrade */
+    /** Optional evidence summary for tier upgrade (inline, without store) */
     evidence_summary?: {
         receipt_count: number;
         epoch_span: number;
@@ -201,92 +259,56 @@ interface AdmissionResult {
  * Maps agent IDs to explicitly assigned tiers.
  */
 type TierOverrides = Record<string, TrustTier>;
+/**
+ * Options for tier evaluation.
+ */
+interface EvaluateTierOptions {
+    overrides?: TierOverrides;
+    evidenceStore?: EvidenceStore;
+    thresholds?: EvidenceThresholds;
+}
 /**
  * Evaluate an agent's trust tier based on their presented credentials.
  *
  * @param manifest - Manifest presentation from the agent (or null if none)
- * @param overrides - Operator-configured tier overrides
+ * @param opts - Evaluation options (overrides, evidence store, thresholds)
  * @returns AdmissionResult with assigned tier
  */
-declare function evaluateTier(manifest: ManifestPresentation | null, overrides?: TierOverrides): AdmissionResult;
+declare function evaluateTier(manifest: ManifestPresentation | null, opts?: TierOverrides | EvaluateTierOptions): AdmissionResult;
 /**
  * Check if a trust tier meets the minimum required tier.
  */
 declare function meetsMinTier(actual: TrustTier, required: TrustTier): boolean;
 
-/**
- * ProtectGateway — stdio MITM proxy for MCP servers.
- *
- * Sits between an MCP client (stdin/stdout) and a wrapped MCP server (child process).
- * Intercepts `tools/call` requests for policy enforcement and decision logging.
- * Passes through all other JSON-RPC messages transparently.
- *
- * v2 features:
- * - Shadow mode (default): observe + signed receipts, no blocking
- * - Trust-tier gating: evaluate manifest at admission, assign tier
- * - Credential vault: inject secrets, agent never sees raw keys
- * - BYOPE: pluggable policy decision via external HTTP webhook
- * - Signed receipts: every decision produces a signed artifact
- */
 declare class ProtectGateway {
     private child;
     private config;
     private rateLimitStore;
     private clientReader;
+    private logFilePath;
+    private receiptFilePath;
+    private evidenceStore;
+    private receiptBuffer;
+    /** Approval grants keyed by request_id (scoped to the specific action that was requested) */
+    private approvalStore;
+    /** Random nonce generated at startup — required for approval endpoint authentication */
+    private readonly approvalNonce;
     private currentTier;
     private admissionResult;
     constructor(config: ProtectConfig);
-    /**
-     * Start the gateway: spawn child process and wire up message relay.
-     */
     start(): Promise<void>;
-    /**
-     * Set the trust tier for this session.
-     * Called at admission (first interaction) or by explicit manifest presentation.
-     */
     setManifest(manifest: ManifestPresentation | null): AdmissionResult;
-    /**
-     * Handle a message from the MCP client (stdin).
-     * Intercept tools/call requests; pass through everything else.
-     */
     private handleClientMessage;
-    /**
-     * Handle a message from the wrapped MCP server (child stdout).
-     * Forward to client (stdout) transparently.
-     */
+    private interceptToolCallAsync;
     private handleServerMessage;
-    /**
-     * Intercept a tools/call request. Returns a JSON-RPC error response if denied, null if allowed.
-     */
+    private injectParamsCredentials;
     private interceptToolCall;
-    /**
-     * Get the applicable rate limit spec based on the agent's tier.
-     */
     private getTierRateLimit;
-    /**
-     * Emit a structured decision log to stderr.
-     * If signing is enabled, also emits a signed artifact.
-     */
     private emitDecisionLog;
-    /**
-     * Create a JSON-RPC error response.
-     */
     private makeErrorResponse;
-    /**
-     * Send a message to the child process (wrapped MCP server).
-     */
     private sendToChild;
-    /**
-     * Send a message to the MCP client (stdout).
-     */
     private sendToClient;
-    /**
-     * Log a message to stderr (debug output).
-     */
     private log;
-    /**
-     * Stop the gateway: kill child process and exit.
-     */
     stop(): void;
 }