protect-mcp 0.3.0 → 0.3.2

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,7 +115,7 @@ 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: string;
     /** SHA-256 digest of the canonicalized policy file */
@@ -152,6 +154,27 @@ interface ProtectConfig {
     signing?: SigningConfig;
     /** Credential vault: maps credential labels to injection config */
     credentials?: Record<string, CredentialConfig>;
+    /** Multi-agent mode: identify calling agents and apply per-agent policy */
+    multiAgent?: MultiAgentConfig;
+}
+/**
+ * Multi-agent mode configuration.
+ *
+ * When enabled, protect-mcp resolves the calling agent's passport kid
+ * from request metadata (x-passport-kid header or _passport_kid param)
+ * and applies agent-specific policy overrides.
+ */
+interface MultiAgentConfig {
+    /** Enable multi-agent mode */
+    enabled: boolean;
+    /** Registry endpoint for agent manifest lookup */
+    registryUrl?: string;
+    /** Per-agent policy overrides: maps kid → tool policy overrides */
+    agentPolicies?: Record<string, Record<string, ToolPolicy>>;
+    /** Default policy for unrecognized agents (default: use base policy) */
+    unknownAgentPolicy?: 'base' | 'deny' | 'shadow-only';
+    /** Cache TTL for agent manifests in ms (default: 300000 = 5 min) */
+    cacheTtlMs?: number;
 }
 
 /**
@@ -284,8 +307,13 @@ declare class ProtectGateway {
     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);
@@ -563,6 +591,132 @@ declare function createAuditBundle(opts: AuditBundleOptions): AuditBundle;
  */
 declare function collectSignedReceipts(logs: DecisionLog[]): Record<string, unknown>[];
 
+/**
+ * protect-mcp simulate — dry-run policy evaluation
+ *
+ * Reads a recorded log file (.protect-mcp-log.jsonl) and evaluates
+ * each tool call against a policy file. Shows what would have been
+ * blocked, rate-limited, or approved — without wrapping a live server.
+ *
+ * Usage:
+ *   npx protect-mcp simulate --policy strict.json [--log .protect-mcp-log.jsonl] [--json]
+ */
+
+interface LogEntry {
+    v: number;
+    tool: string;
+    decision: string;
+    reason_code: string;
+    mode: string;
+    timestamp: number;
+    tier?: string;
+    rate_limit_remaining?: number;
+    [key: string]: unknown;
+}
+interface SimulationResult {
+    tool: string;
+    calls: number;
+    results: {
+        allow: number;
+        block: number;
+        rate_limited: number;
+        require_approval: number;
+        tier_insufficient: number;
+    };
+    original: {
+        allow: number;
+        deny: number;
+    };
+}
+interface SimulationSummary {
+    policy_file: string;
+    log_file: string;
+    total_calls: number;
+    results: {
+        allow: number;
+        block: number;
+        rate_limited: number;
+        require_approval: number;
+        tier_insufficient: number;
+    };
+    original: {
+        allow: number;
+        deny: number;
+    };
+    tool_breakdown: SimulationResult[];
+    changes: string[];
+}
+/**
+ * Parse a JSONL log file into log entries.
+ */
+declare function parseLogFile(path: string): LogEntry[];
+/**
+ * Simulate a policy against a set of log entries.
+ * Evaluates each entry against the policy's per-tool rules,
+ * including block, rate_limit, min_tier, and require_approval.
+ */
+declare function simulate(entries: LogEntry[], policy: ProtectPolicy, tier?: TrustTier): SimulationSummary;
+/**
+ * Format simulation results for terminal output.
+ */
+declare function formatSimulation(summary: SimulationSummary): string;
+
+/**
+ * protect-mcp report — compliance report generation
+ *
+ * Generates structured compliance reports from local log and receipt files.
+ * Output as JSON (machine-readable) or Markdown (human-readable, PDF-convertible).
+ *
+ * Usage:
+ *   npx protect-mcp report --period 30d --output report.json
+ *   npx protect-mcp report --period 30d --format md --output report.md
+ */
+interface ComplianceReport {
+    generated_at: string;
+    period: {
+        from: string;
+        to: string;
+    };
+    signing_identity: {
+        kid: string;
+        issuer: string;
+    } | null;
+    summary: {
+        total_decisions: number;
+        allowed: number;
+        blocked: number;
+        rate_limited: number;
+        approval_required: number;
+        unique_tools: number;
+        unique_tiers: number;
+    };
+    tool_breakdown: Array<{
+        tool: string;
+        total: number;
+        allowed: number;
+        blocked: number;
+        rate_limited: number;
+        approval_required: number;
+    }>;
+    policy_changes: Array<{
+        at: string;
+        policy_digest: string;
+    }>;
+    verification: {
+        receipts_signed: number;
+        receipts_unsigned: number;
+        verify_command: string;
+    };
+}
+/**
+ * Generate a compliance report from local log and receipt files.
+ */
+declare function generateReport(logPath: string, receiptPath: string, periodDays: number): ComplianceReport;
+/**
+ * Format a compliance report as Markdown.
+ */
+declare function formatReportMarkdown(report: ComplianceReport): string;
+
 /**
  * Agent identity format: sb:agent:{first 32 hex chars of SHA-256(public key bytes)}
  * Example: "sb:agent:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
@@ -844,4 +998,4 @@ declare function validateManifest(manifest: unknown): string[];
  */
 declare function validateEvidenceReceipt(receipt: unknown): string[];
 
-export { type AdmissionResult, type AgentId, type AgentManifest, type ArenaPayload, type ArenaReceipt, type AttestationPayload, type AttestationReceipt, type AuditBundle, type AuditBundleOptions, type BenchmarkPayload, type BenchmarkReceipt, type BuilderId, type CredentialConfig, type DecisionContext, type DecisionLog, type DisclosureMode, type Ed25519PublicKey, type EvidenceIssuer, type EvidenceReceipt, type EvidenceReceiptBase, type EvidenceSummary, type EvidenceSummaryEntry, type EvidenceType, type ExternalDecision, type ExternalPDPConfig, type IssuerType, type JsonRpcRequest, type JsonRpcResponse, type LeaseCompatibility, type ManifestBuilder, type ManifestCapabilities, type ManifestConfig, type ManifestIdentity, type ManifestPresentation, type ManifestSignature, type ManifestStatus, type PolicyEngineMode, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, type RestraintPayload, type RestraintReceipt, type SHA256Hash, type SigningConfig, type TierOverrides, type ToolPolicy, type TrustTier, type WorkPayload, type WorkReceipt, buildDecisionContext, checkRateLimit, collectSignedReceipts, createAuditBundle, evaluateTier, getSignerInfo, getToolPolicy, initSigning, isAgentId, isDisclosureMode, isEvidenceType, isManifestStatus, isSigningEnabled, listCredentialLabels, loadPolicy, meetsMinTier, parseRateLimit, queryExternalPDP, resolveCredential, signDecision, validateCredentials, validateEvidenceReceipt, validateManifest };
+export { type AdmissionResult, type AgentId, type AgentManifest, type ArenaPayload, type ArenaReceipt, type AttestationPayload, type AttestationReceipt, type AuditBundle, type AuditBundleOptions, type BenchmarkPayload, type BenchmarkReceipt, type BuilderId, type ComplianceReport, type CredentialConfig, type DecisionContext, type DecisionLog, type DisclosureMode, type Ed25519PublicKey, type EvidenceIssuer, type EvidenceReceipt, type EvidenceReceiptBase, type EvidenceSummary, type EvidenceSummaryEntry, type EvidenceType, type ExternalDecision, type ExternalPDPConfig, type IssuerType, type JsonRpcRequest, type JsonRpcResponse, type LeaseCompatibility, type ManifestBuilder, type ManifestCapabilities, type ManifestConfig, type ManifestIdentity, type ManifestPresentation, type ManifestSignature, type ManifestStatus, type PolicyEngineMode, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, type RestraintPayload, type RestraintReceipt, type SHA256Hash, type SigningConfig, type SimulationResult, type SimulationSummary, type TierOverrides, type ToolPolicy, type TrustTier, type WorkPayload, type WorkReceipt, buildDecisionContext, checkRateLimit, collectSignedReceipts, createAuditBundle, evaluateTier, formatReportMarkdown, formatSimulation, generateReport, getSignerInfo, getToolPolicy, initSigning, isAgentId, isDisclosureMode, isEvidenceType, isManifestStatus, isSigningEnabled, listCredentialLabels, loadPolicy, meetsMinTier, parseLogFile, parseRateLimit, queryExternalPDP, resolveCredential, signDecision, simulate, validateCredentials, validateEvidenceReceipt, validateManifest };

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,7 +115,7 @@ 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: string;
     /** SHA-256 digest of the canonicalized policy file */
@@ -152,6 +154,27 @@ interface ProtectConfig {
     signing?: SigningConfig;
     /** Credential vault: maps credential labels to injection config */
     credentials?: Record<string, CredentialConfig>;
+    /** Multi-agent mode: identify calling agents and apply per-agent policy */
+    multiAgent?: MultiAgentConfig;
+}
+/**
+ * Multi-agent mode configuration.
+ *
+ * When enabled, protect-mcp resolves the calling agent's passport kid
+ * from request metadata (x-passport-kid header or _passport_kid param)
+ * and applies agent-specific policy overrides.
+ */
+interface MultiAgentConfig {
+    /** Enable multi-agent mode */
+    enabled: boolean;
+    /** Registry endpoint for agent manifest lookup */
+    registryUrl?: string;
+    /** Per-agent policy overrides: maps kid → tool policy overrides */
+    agentPolicies?: Record<string, Record<string, ToolPolicy>>;
+    /** Default policy for unrecognized agents (default: use base policy) */
+    unknownAgentPolicy?: 'base' | 'deny' | 'shadow-only';
+    /** Cache TTL for agent manifests in ms (default: 300000 = 5 min) */
+    cacheTtlMs?: number;
 }
 
 /**
@@ -284,8 +307,13 @@ declare class ProtectGateway {
     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);
@@ -563,6 +591,132 @@ declare function createAuditBundle(opts: AuditBundleOptions): AuditBundle;
  */
 declare function collectSignedReceipts(logs: DecisionLog[]): Record<string, unknown>[];
 
+/**
+ * protect-mcp simulate — dry-run policy evaluation
+ *
+ * Reads a recorded log file (.protect-mcp-log.jsonl) and evaluates
+ * each tool call against a policy file. Shows what would have been
+ * blocked, rate-limited, or approved — without wrapping a live server.
+ *
+ * Usage:
+ *   npx protect-mcp simulate --policy strict.json [--log .protect-mcp-log.jsonl] [--json]
+ */
+
+interface LogEntry {
+    v: number;
+    tool: string;
+    decision: string;
+    reason_code: string;
+    mode: string;
+    timestamp: number;
+    tier?: string;
+    rate_limit_remaining?: number;
+    [key: string]: unknown;
+}
+interface SimulationResult {
+    tool: string;
+    calls: number;
+    results: {
+        allow: number;
+        block: number;
+        rate_limited: number;
+        require_approval: number;
+        tier_insufficient: number;
+    };
+    original: {
+        allow: number;
+        deny: number;
+    };
+}
+interface SimulationSummary {
+    policy_file: string;
+    log_file: string;
+    total_calls: number;
+    results: {
+        allow: number;
+        block: number;
+        rate_limited: number;
+        require_approval: number;
+        tier_insufficient: number;
+    };
+    original: {
+        allow: number;
+        deny: number;
+    };
+    tool_breakdown: SimulationResult[];
+    changes: string[];
+}
+/**
+ * Parse a JSONL log file into log entries.
+ */
+declare function parseLogFile(path: string): LogEntry[];
+/**
+ * Simulate a policy against a set of log entries.
+ * Evaluates each entry against the policy's per-tool rules,
+ * including block, rate_limit, min_tier, and require_approval.
+ */
+declare function simulate(entries: LogEntry[], policy: ProtectPolicy, tier?: TrustTier): SimulationSummary;
+/**
+ * Format simulation results for terminal output.
+ */
+declare function formatSimulation(summary: SimulationSummary): string;
+
+/**
+ * protect-mcp report — compliance report generation
+ *
+ * Generates structured compliance reports from local log and receipt files.
+ * Output as JSON (machine-readable) or Markdown (human-readable, PDF-convertible).
+ *
+ * Usage:
+ *   npx protect-mcp report --period 30d --output report.json
+ *   npx protect-mcp report --period 30d --format md --output report.md
+ */
+interface ComplianceReport {
+    generated_at: string;
+    period: {
+        from: string;
+        to: string;
+    };
+    signing_identity: {
+        kid: string;
+        issuer: string;
+    } | null;
+    summary: {
+        total_decisions: number;
+        allowed: number;
+        blocked: number;
+        rate_limited: number;
+        approval_required: number;
+        unique_tools: number;
+        unique_tiers: number;
+    };
+    tool_breakdown: Array<{
+        tool: string;
+        total: number;
+        allowed: number;
+        blocked: number;
+        rate_limited: number;
+        approval_required: number;
+    }>;
+    policy_changes: Array<{
+        at: string;
+        policy_digest: string;
+    }>;
+    verification: {
+        receipts_signed: number;
+        receipts_unsigned: number;
+        verify_command: string;
+    };
+}
+/**
+ * Generate a compliance report from local log and receipt files.
+ */
+declare function generateReport(logPath: string, receiptPath: string, periodDays: number): ComplianceReport;
+/**
+ * Format a compliance report as Markdown.
+ */
+declare function formatReportMarkdown(report: ComplianceReport): string;
+
 /**
  * Agent identity format: sb:agent:{first 32 hex chars of SHA-256(public key bytes)}
  * Example: "sb:agent:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
@@ -844,4 +998,4 @@ declare function validateManifest(manifest: unknown): string[];
  */
 declare function validateEvidenceReceipt(receipt: unknown): string[];
 
-export { type AdmissionResult, type AgentId, type AgentManifest, type ArenaPayload, type ArenaReceipt, type AttestationPayload, type AttestationReceipt, type AuditBundle, type AuditBundleOptions, type BenchmarkPayload, type BenchmarkReceipt, type BuilderId, type CredentialConfig, type DecisionContext, type DecisionLog, type DisclosureMode, type Ed25519PublicKey, type EvidenceIssuer, type EvidenceReceipt, type EvidenceReceiptBase, type EvidenceSummary, type EvidenceSummaryEntry, type EvidenceType, type ExternalDecision, type ExternalPDPConfig, type IssuerType, type JsonRpcRequest, type JsonRpcResponse, type LeaseCompatibility, type ManifestBuilder, type ManifestCapabilities, type ManifestConfig, type ManifestIdentity, type ManifestPresentation, type ManifestSignature, type ManifestStatus, type PolicyEngineMode, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, type RestraintPayload, type RestraintReceipt, type SHA256Hash, type SigningConfig, type TierOverrides, type ToolPolicy, type TrustTier, type WorkPayload, type WorkReceipt, buildDecisionContext, checkRateLimit, collectSignedReceipts, createAuditBundle, evaluateTier, getSignerInfo, getToolPolicy, initSigning, isAgentId, isDisclosureMode, isEvidenceType, isManifestStatus, isSigningEnabled, listCredentialLabels, loadPolicy, meetsMinTier, parseRateLimit, queryExternalPDP, resolveCredential, signDecision, validateCredentials, validateEvidenceReceipt, validateManifest };
+export { type AdmissionResult, type AgentId, type AgentManifest, type ArenaPayload, type ArenaReceipt, type AttestationPayload, type AttestationReceipt, type AuditBundle, type AuditBundleOptions, type BenchmarkPayload, type BenchmarkReceipt, type BuilderId, type ComplianceReport, type CredentialConfig, type DecisionContext, type DecisionLog, type DisclosureMode, type Ed25519PublicKey, type EvidenceIssuer, type EvidenceReceipt, type EvidenceReceiptBase, type EvidenceSummary, type EvidenceSummaryEntry, type EvidenceType, type ExternalDecision, type ExternalPDPConfig, type IssuerType, type JsonRpcRequest, type JsonRpcResponse, type LeaseCompatibility, type ManifestBuilder, type ManifestCapabilities, type ManifestConfig, type ManifestIdentity, type ManifestPresentation, type ManifestSignature, type ManifestStatus, type PolicyEngineMode, type ProtectConfig, ProtectGateway, type ProtectPolicy, type RateLimit, type RestraintPayload, type RestraintReceipt, type SHA256Hash, type SigningConfig, type SimulationResult, type SimulationSummary, type TierOverrides, type ToolPolicy, type TrustTier, type WorkPayload, type WorkReceipt, buildDecisionContext, checkRateLimit, collectSignedReceipts, createAuditBundle, evaluateTier, formatReportMarkdown, formatSimulation, generateReport, getSignerInfo, getToolPolicy, initSigning, isAgentId, isDisclosureMode, isEvidenceType, isManifestStatus, isSigningEnabled, listCredentialLabels, loadPolicy, meetsMinTier, parseLogFile, parseRateLimit, queryExternalPDP, resolveCredential, signDecision, simulate, validateCredentials, validateEvidenceReceipt, validateManifest };