@dotsetlabs/tollgate 0.1.0

package/dist/policy/types.d.ts

@@ -0,0 +1,428 @@
+/**
+ * Policy Type Definitions for Tollgate
+ *
+ * This module defines the core types for Tollgate's policy system:
+ *
+ * - **PolicyAction**: The possible actions (allow, deny, prompt, smart)
+ * - **ToolPolicy**: Configuration for individual tool access control
+ * - **ServerConfig**: MCP server configuration with tool policies
+ * - **TollgateConfig**: Root configuration schema
+ * - **ResilienceConfig**: Failure handling and health monitoring settings
+ *
+ * @example
+ * ```typescript
+ * import type { TollgateConfig, PolicyAction } from './types.js';
+ *
+ * const config: TollgateConfig = {
+ *   version: '1',
+ *   servers: {
+ *     postgres: {
+ *       command: 'npx',
+ *       args: ['-y', '@modelcontextprotocol/server-postgres'],
+ *       tools: {
+ *         'query': { action: 'allow' },
+ *         'execute': { action: 'prompt' }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+import type { RiskLevel, RiskMapping } from '../analyzers/types.js';
+/**
+ * Available policy actions for tool access control.
+ *
+ * - `allow`: Permit the tool call without user approval
+ * - `deny`: Block the tool call entirely
+ * - `prompt`: Ask the user for approval before proceeding
+ * - `smart`: Use content analysis to determine the appropriate action
+ */
+export type PolicyAction = 'allow' | 'deny' | 'prompt' | 'smart';
+/**
+ * Configuration for controlling access to a specific tool.
+ *
+ * Tool policies define how Tollgate should handle requests to invoke
+ * a particular tool. The simplest form just specifies an action, but
+ * policies can include smart analysis, session memory, and custom messages.
+ *
+ * @example
+ * ```typescript
+ * // Simple policy
+ * const readPolicy: ToolPolicy = { action: 'allow' };
+ *
+ * // Smart analysis policy
+ * const sqlPolicy: ToolPolicy = {
+ *   action: 'smart',
+ *   analyzer: 'sql',
+ *   risks: {
+ *     read: 'allow',
+ *     write: 'prompt',
+ *     destructive: 'deny'
+ *   }
+ * };
+ * ```
+ */
+export interface ToolPolicy {
+    /** The action to take when this tool is invoked */
+    action: PolicyAction;
+    /** Custom message to display when prompting for approval */
+    message?: string;
+    /** Reason for the policy decision (shown when denying) */
+    reason?: string;
+    /** Analyzer to use for smart content analysis ('sql', 'filesystem', 'shell', or 'auto') */
+    analyzer?: string;
+    /** Risk level to action mapping for smart analysis */
+    risks?: RiskMapping;
+    /** Session-based approval configuration */
+    session?: SessionConfig;
+}
+/**
+ * Configuration for session-based approval memory.
+ *
+ * When enabled, Tollgate can remember approval decisions for a period of time,
+ * reducing approval fatigue for repetitive operations.
+ *
+ * @example
+ * ```typescript
+ * const sessionConfig: SessionConfig = {
+ *   remember: true,
+ *   scope: 'tool',   // Remember for all calls to this tool
+ *   ttl: 300         // For 5 minutes
+ * };
+ * ```
+ */
+export interface SessionConfig {
+    /** Whether to remember approval decisions */
+    remember?: boolean;
+    /** Scope of the remembered approval */
+    scope?: 'exact' | 'tool' | 'server';
+    /** Time-to-live for the approval in seconds */
+    ttl?: number;
+}
+/**
+ * Configuration for an upstream MCP server.
+ *
+ * Defines how to launch an MCP server and what policies apply to its tools.
+ *
+ * @example
+ * ```typescript
+ * const postgresConfig: ServerConfig = {
+ *   command: 'npx',
+ *   args: ['-y', '@modelcontextprotocol/server-postgres'],
+ *   env: { DATABASE_URL: '${DATABASE_URL}' },
+ *   tools: {
+ *     'query': { action: 'allow' },
+ *     'execute': { action: 'prompt' }
+ *   },
+ *   defaults: { action: 'deny' }
+ * };
+ * ```
+ */
+export interface ServerConfig {
+    /** Command to execute to start the server */
+    command: string;
+    /** Arguments to pass to the command */
+    args?: string[];
+    /** Environment variables for the server process */
+    env?: Record<string, string>;
+    /** Working directory for the server process */
+    cwd?: string;
+    /** Tool-specific policies (tool name or glob pattern to policy) */
+    tools?: Record<string, ToolPolicy | PolicyAction>;
+    /** Default settings for this server */
+    defaults?: {
+        /** Default action when no tool policy matches */
+        action?: PolicyAction;
+        /** Default analyzer for smart analysis */
+        analyzer?: string;
+    };
+}
+/**
+ * Failure mode determines behavior when the upstream server is unavailable.
+ *
+ * - `fail-closed`: Deny all requests (safest, recommended for production)
+ * - `fail-open`: Allow all requests (useful for development/debugging)
+ * - `fail-readonly`: Allow only read operations (balanced approach)
+ */
+export type FailureMode = 'fail-closed' | 'fail-open' | 'fail-readonly';
+/**
+ * Configuration for periodic health checks of upstream servers.
+ *
+ * Health checks help detect upstream server failures proactively,
+ * enabling faster failure mode activation.
+ *
+ * @example
+ * ```typescript
+ * const healthConfig: HealthCheckConfig = {
+ *   enabled: true,
+ *   intervalMs: 15000,      // Check every 15 seconds
+ *   timeoutMs: 3000,        // 3 second timeout per check
+ *   failureThreshold: 2     // Mark unhealthy after 2 failures
+ * };
+ * ```
+ */
+export interface HealthCheckConfig {
+    /** Enable periodic health checks (default: true) */
+    enabled?: boolean;
+    /** Interval between health checks in milliseconds (default: 30000) */
+    intervalMs?: number;
+    /** Timeout for each health check operation in milliseconds (default: 5000) */
+    timeoutMs?: number;
+    /** Number of consecutive failures before marking server unhealthy (default: 3) */
+    failureThreshold?: number;
+}
+/**
+ * Configuration for graceful shutdown behavior.
+ *
+ * Controls how Tollgate handles shutdown signals (SIGINT, SIGTERM),
+ * ensuring in-flight requests complete before termination.
+ */
+export interface ShutdownConfig {
+    /** Maximum time to wait for graceful shutdown in milliseconds (default: 10000) */
+    timeoutMs?: number;
+    /** Time to wait for in-flight requests to complete in milliseconds (default: 5000) */
+    drainTimeoutMs?: number;
+}
+/**
+ * Complete resilience configuration for failure handling and monitoring.
+ *
+ * @example
+ * ```typescript
+ * const resilienceConfig: ResilienceConfig = {
+ *   failureMode: 'fail-readonly',
+ *   upstreamTimeoutMs: 60000,
+ *   healthCheck: { enabled: true, intervalMs: 15000 },
+ *   shutdown: { timeoutMs: 15000, drainTimeoutMs: 10000 }
+ * };
+ * ```
+ */
+export interface ResilienceConfig {
+    /** Behavior when upstream is unavailable (default: 'fail-closed') */
+    failureMode?: FailureMode;
+    /** Timeout for upstream tool calls in milliseconds (default: 30000) */
+    upstreamTimeoutMs?: number;
+    /** Health check configuration */
+    healthCheck?: HealthCheckConfig;
+    /** Graceful shutdown configuration */
+    shutdown?: ShutdownConfig;
+}
+/**
+ * Action to take when a guardrail is triggered.
+ *
+ * - `deny`: Block the request entirely (recommended for production)
+ * - `warn`: Log a warning but allow the request to proceed
+ * - `prompt`: Ask the user for approval before proceeding
+ */
+export type GuardrailAction = 'deny' | 'warn' | 'prompt';
+/**
+ * Configuration for the prompt injection detection guardrail.
+ *
+ * This guardrail scans all tool arguments for common prompt injection
+ * patterns before the request is processed by other analyzers.
+ *
+ * @example
+ * ```typescript
+ * const promptInjection: PromptInjectionGuardrailConfig = {
+ *   enabled: true,
+ *   action: 'deny',
+ *   sensitivity: 'balanced',
+ *   allowlist: ['system_prompt_tool'],
+ * };
+ * ```
+ */
+export interface PromptInjectionGuardrailConfig {
+    /** Enable prompt injection detection (default: false) */
+    enabled?: boolean;
+    /** Action to take when injection is detected (default: 'deny') */
+    action?: GuardrailAction;
+    /**
+     * Detection sensitivity level.
+     * - 'strict': Flag any suspicious patterns (may have false positives)
+     * - 'balanced': Balance between security and usability (default)
+     * - 'permissive': Only flag high-confidence attacks
+     */
+    sensitivity?: 'strict' | 'balanced' | 'permissive';
+    /**
+     * Tools to exclude from prompt injection scanning.
+     * Useful for tools that legitimately need to handle prompts.
+     */
+    allowlist?: string[];
+    /**
+     * Servers to exclude from prompt injection scanning.
+     * All tools from these servers will bypass the guardrail.
+     */
+    serverAllowlist?: string[];
+}
+/**
+ * Configuration for all guardrails.
+ *
+ * Guardrails are security checks that run before normal policy evaluation.
+ * They provide an additional layer of protection against common attack patterns.
+ *
+ * @example
+ * ```typescript
+ * const guardrails: GuardrailsConfig = {
+ *   promptInjection: {
+ *     enabled: true,
+ *     action: 'deny',
+ *   },
+ * };
+ * ```
+ */
+export interface GuardrailsConfig {
+    /** Prompt injection detection configuration */
+    promptInjection?: PromptInjectionGuardrailConfig;
+}
+/**
+ * Root configuration schema for Tollgate.
+ *
+ * This is the top-level configuration object parsed from tollgate.yaml.
+ *
+ * @example
+ * ```typescript
+ * const config: TollgateConfig = {
+ *   version: '1',
+ *   defaults: { action: 'prompt', timeout: 60000 },
+ *   servers: {
+ *     postgres: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'] }
+ *   },
+ *   audit: { enabled: true, path: './audit.db' },
+ *   guardrails: {
+ *     promptInjection: { enabled: true, action: 'deny' }
+ *   }
+ * };
+ * ```
+ */
+export interface TollgateConfig {
+    /** Configuration schema version */
+    version: string;
+    /** Global default settings */
+    defaults?: {
+        /** Default action when no policy matches */
+        action?: PolicyAction;
+        /** Default approval timeout in milliseconds */
+        timeout?: number;
+    };
+    /** Server configurations keyed by server name */
+    servers?: Record<string, ServerConfig>;
+    /** Approval handler configuration */
+    approval?: {
+        /** Approval method: terminal prompt, interactive web UI, or webhook */
+        method?: 'terminal' | 'interactive' | 'webhook';
+        /** Timeout for approval requests in milliseconds */
+        timeout?: number;
+        /** Port for interactive approval UI (default: 9847) */
+        port?: number;
+        /** Webhook URL for remote approvals */
+        url?: string;
+    };
+    /** Audit logging configuration */
+    audit?: {
+        /** Enable audit logging */
+        enabled?: boolean;
+        /** Path to audit database file */
+        path?: string;
+    };
+    /** Session management configuration */
+    session?: {
+        /** Enable persistent session storage (default: false, uses in-memory) */
+        persist?: boolean;
+        /** Path to session database (default: ~/.tollgate/sessions.db) */
+        path?: string;
+    };
+    /** Resilience and failure handling configuration */
+    resilience?: ResilienceConfig;
+    /** Guardrails configuration for additional security protections */
+    guardrails?: GuardrailsConfig;
+    /**
+     * Custom analyzers to load.
+     *
+     * Specify paths to custom analyzer modules that export a default analyzer
+     * created with `defineAnalyzer()` or `defineAsyncAnalyzer()`.
+     *
+     * @example
+     * ```yaml
+     * analyzers:
+     *   - ./analyzers/graphql.ts
+     *   - ./analyzers/redis-commands.js
+     *   - @myorg/custom-analyzers/pii
+     * ```
+     */
+    analyzers?: string[];
+    /**
+     * Natural language policy definitions.
+     *
+     * Define policies using plain English statements that will be parsed
+     * and converted to structured tool policies.
+     *
+     * @example
+     * ```yaml
+     * policies:
+     *   - "Allow read operations on postgres"
+     *   - "Deny destructive queries on any database"
+     *   - "Prompt for file writes outside /tmp"
+     *   - "Block dangerous shell commands"
+     * ```
+     */
+    policies?: string[];
+}
+/**
+ * The result of a guardrail check.
+ */
+export interface GuardrailResult {
+    /** Whether the guardrail was triggered */
+    triggered: boolean;
+    /** The guardrail that was triggered */
+    guardrail: string;
+    /** Risk level detected */
+    risk: RiskLevel;
+    /** Reason for the trigger */
+    reason: string;
+    /** Patterns that triggered the guardrail */
+    triggers?: string[];
+}
+/**
+ * The result of policy evaluation for a tool call.
+ *
+ * A PolicyDecision represents the resolved action after evaluating all
+ * applicable policies. The 'smart' action is always resolved to a concrete
+ * action (allow, deny, or prompt) before returning.
+ */
+export interface PolicyDecision {
+    /** The resolved action (never 'smart', always concrete) */
+    action: Exclude<PolicyAction, 'smart'>;
+    /** Human-readable reason for the decision */
+    reason?: string;
+    /** Custom message for approval prompts */
+    message?: string;
+    /** The policy rule that matched (for debugging) */
+    matchedRule?: string;
+    /** Analysis metadata when smart analysis was used */
+    analysis?: {
+        /** Which analyzer processed the request */
+        analyzer: string;
+        /** Determined risk level */
+        risk: RiskLevel;
+        /** Patterns or keywords that triggered the risk level */
+        triggers?: string[];
+    };
+    /** Guardrail result when a guardrail was triggered */
+    guardrail?: GuardrailResult;
+}
+/**
+ * Context for a tool call being evaluated.
+ *
+ * Captures all relevant information about a tool invocation for
+ * policy evaluation, approval prompts, and audit logging.
+ */
+export interface ToolCallContext {
+    /** Name of the MCP server */
+    server: string;
+    /** Name of the tool being invoked */
+    tool: string;
+    /** Arguments passed to the tool */
+    args: Record<string, unknown>;
+    /** Timestamp of the request */
+    timestamp: Date;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/policy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"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"}

package/dist/policy/types.js

@@ -0,0 +1,32 @@
+/**
+ * Policy Type Definitions for Tollgate
+ *
+ * This module defines the core types for Tollgate's policy system:
+ *
+ * - **PolicyAction**: The possible actions (allow, deny, prompt, smart)
+ * - **ToolPolicy**: Configuration for individual tool access control
+ * - **ServerConfig**: MCP server configuration with tool policies
+ * - **TollgateConfig**: Root configuration schema
+ * - **ResilienceConfig**: Failure handling and health monitoring settings
+ *
+ * @example
+ * ```typescript
+ * import type { TollgateConfig, PolicyAction } from './types.js';
+ *
+ * const config: TollgateConfig = {
+ *   version: '1',
+ *   servers: {
+ *     postgres: {
+ *       command: 'npx',
+ *       args: ['-y', '@modelcontextprotocol/server-postgres'],
+ *       tools: {
+ *         'query': { action: 'allow' },
+ *         'execute': { action: 'prompt' }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/policy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG"}

package/dist/policy/validator.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Policy Validator for Tollgate
+ *
+ * Provides comprehensive validation of Tollgate configuration files
+ * with detailed error messages and suggestions for common issues.
+ *
+ * @example
+ * ```typescript
+ * import { validateConfigWithDetails } from './validator.js';
+ *
+ * const issues = validateConfigWithDetails(config);
+ * if (issues.some(i => i.level === 'error')) {
+ *   console.error('Configuration has errors');
+ *   process.exit(1);
+ * }
+ * ```
+ */
+import type { TollgateConfig } from './types.js';
+/**
+ * Validation issue severity level.
+ */
+export type ValidationLevel = 'error' | 'warning' | 'info';
+/**
+ * A validation issue found in the configuration.
+ */
+export interface ValidationIssue {
+    /** Severity level */
+    level: ValidationLevel;
+    /** Configuration path where the issue was found (e.g., "servers.postgres.tools.query") */
+    path: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Suggested fix (optional) */
+    suggestion?: string;
+    /** Additional context */
+    details?: Record<string, unknown>;
+}
+/**
+ * Summary of validation results.
+ */
+export interface ValidationResult {
+    /** Whether the configuration is valid (no errors) */
+    valid: boolean;
+    /** All issues found */
+    issues: ValidationIssue[];
+    /** Count of errors */
+    errorCount: number;
+    /** Count of warnings */
+    warningCount: number;
+    /** Count of informational messages */
+    infoCount: number;
+    /** Summary statistics */
+    stats: {
+        serversConfigured: number;
+        toolPoliciesConfigured: number;
+        smartAnalysisEnabled: boolean;
+        analyzersUsed: string[];
+    };
+}
+/**
+ * Validates a Tollgate configuration with detailed error reporting.
+ *
+ * @param config - The configuration to validate
+ * @param serverFilter - Optional: only validate a specific server
+ * @returns Validation result with all issues found
+ */
+export declare function validateConfigWithDetails(config: TollgateConfig, serverFilter?: string): ValidationResult;
+/**
+ * Formats validation issues for console output.
+ */
+export declare function formatValidationIssues(issues: ValidationIssue[]): string;
+//# sourceMappingURL=validator.d.ts.map

package/dist/policy/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/policy/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,YAAY,CAAC;AAOpB;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,KAAK,EAAE,eAAe,CAAC;IAEvB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IAEb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAEhB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;IAEf,uBAAuB;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IAEnB,wBAAwB;IACxB,YAAY,EAAE,MAAM,CAAC;IAErB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAElB,yBAAyB;IACzB,KAAK,EAAE;QACL,iBAAiB,EAAE,MAAM,CAAC;QAC1B,sBAAsB,EAAE,MAAM,CAAC;QAC/B,oBAAoB,EAAE,OAAO,CAAC;QAC9B,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;CACH;AAeD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,cAAc,EACtB,YAAY,CAAC,EAAE,MAAM,GACpB,gBAAgB,CAmJlB;AAiTD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAuBxE"}