@solongate/proxy 0.47.7 → 0.48.1

package/dist/cli-utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared CLI utilities for SolonGate proxy CLI commands.
+ * Consolidates banner art, ANSI colors, and log helpers used by init, inject, and create.
+ */
+export declare const c: {
+    reset: string;
+    bold: string;
+    dim: string;
+    italic: string;
+    white: string;
+    gray: string;
+    blue1: string;
+    blue2: string;
+    blue3: string;
+    blue4: string;
+    blue5: string;
+    blue6: string;
+    green: string;
+    red: string;
+    cyan: string;
+    yellow: string;
+    bgBlue: string;
+};
+export declare function log(msg: string): void;
+export declare const BANNER_FULL: string[];
+export declare const BANNER_COLORS: string[];
+export declare function printBanner(subtitle: string): void;

package/dist/config.d.ts

@@ -0,0 +1,105 @@
+import type { PolicySet } from './core/index.js';
+/**
+ * Upstream MCP server connection config.
+ *
+ * Two modes:
+ * - stdio: spawn a child process (command + args)
+ * - sse/http: connect to a remote URL
+ */
+export interface UpstreamConfig {
+    /** Transport type: stdio (default), sse, or http (StreamableHTTP) */
+    transport?: 'stdio' | 'sse' | 'http';
+    /** Command to spawn the upstream MCP server (stdio mode) */
+    command: string;
+    /** Arguments for the command (stdio mode) */
+    args?: string[];
+    /** Environment variables for the upstream process (stdio mode) */
+    env?: Record<string, string>;
+    /** Working directory for the upstream process (stdio mode) */
+    cwd?: string;
+    /** URL of the upstream MCP server (sse/http mode) */
+    url?: string;
+}
+/**
+ * SolonGate Proxy configuration.
+ */
+export interface ProxyConfig {
+    /** Upstream MCP server to protect */
+    upstream: UpstreamConfig;
+    /** Policy set to enforce (inline or file path) */
+    policy: PolicySet;
+    /** Proxy display name */
+    name?: string;
+    /** Enable verbose error messages */
+    verbose?: boolean;
+    /** Per-tool rate limit (calls per minute) */
+    rateLimitPerTool?: number;
+    /** Global rate limit (calls per minute) */
+    globalRateLimit?: number;
+    /** SolonGate Cloud API key for policy sync and audit forwarding */
+    apiKey?: string;
+    /** SolonGate Cloud API URL (default: https://api.solongate.com) */
+    apiUrl?: string;
+    /** Port to serve on via HTTP (StreamableHTTP). If omitted, serves on stdio. */
+    port?: number;
+    /** Resolved absolute path to the policy JSON file (null if cloud-only) */
+    policyPath?: string;
+    /** Cloud policy ID to fetch (if not set, auto-selects first policy) */
+    policyId?: string;
+    /** Agent name for trust map identification (from --agent-name flag) */
+    agentName?: string;
+}
+export declare const DEFAULT_API_URL = "https://api.solongate.com";
+/**
+ * Fetch policy from SolonGate Cloud API.
+ * TODO: extract cloud policy parsing to shared module with packages/sdk-ts/src/solongate.ts
+ */
+export declare function fetchCloudPolicy(apiKey: string, apiUrl: string, policyId?: string): Promise<PolicySet>;
+/**
+ * Fetch a policy's compiled OPA WASM bundle from the cloud. The cloud API
+ * compiles every policy version to WASM on save; the proxy evaluates with it
+ * (OPA is the sole evaluator — same engine as the airgap product).
+ * Returns the WASM bundle bytes, or null if none is available yet.
+ */
+export declare function fetchCloudPolicyWasm(apiKey: string, apiUrl: string, policyId: string): Promise<Uint8Array | null>;
+export interface AuditLogEntry {
+    tool: string;
+    arguments: Record<string, unknown>;
+    decision: 'ALLOW' | 'DENY';
+    reason: string;
+    permission?: string;
+    matchedRule?: string;
+    evaluationTimeMs: number;
+    /** Agent identity for trust map */
+    agent_id?: string;
+    agent_name?: string;
+    /** Sub-agent identity (within same MCP connection) */
+    sub_agent_id?: string;
+    sub_agent_name?: string;
+}
+export declare function sendAuditLog(apiKey: string, apiUrl: string, entry: AuditLogEntry): Promise<void>;
+/**
+ * Load policy from a JSON file path or inline object.
+ */
+export declare function loadPolicy(source: string | PolicySet): PolicySet;
+/**
+ * Parse CLI arguments into a ProxyConfig.
+ *
+ * Usage:
+ *   solongate-proxy [options] -- <command> [args...]
+ *
+ * Options:
+ *   --policy <file>              Policy JSON file (default: policy.json or cloud fetch)
+ *   --name <name>                Proxy name (default: solongate-proxy)
+ *   --verbose                    Enable verbose errors
+ *   --rate-limit <n>             Per-tool rate limit (calls/min)
+ *   --global-rate-limit <n>      Global rate limit (calls/min)
+ *   --config <file>              Load config from JSON file
+ *   --api-key <key>              SolonGate Cloud API key (enables cloud policy + audit)
+ *   --api-url <url>              SolonGate Cloud API URL (default: https://api.solongate.com)
+ *   --upstream-url <url>         Connect to upstream via URL (SSE or HTTP) instead of stdio
+ *   --upstream-transport <type>  Transport type: stdio (default), sse, http
+ *   --port <n>                   Serve downstream on HTTP port (default: stdio)
+ *   --policy-id <id>             Cloud policy ID to use (default: auto-select first)
+ */
+export declare function parseArgs(argv: string[]): ProxyConfig;

package/dist/core/capability-token.d.ts

@@ -0,0 +1,46 @@
+import type { Permission } from './permissions.js';
+/**
+ * Capability Token: a signed, short-lived, single-use token
+ * that authorizes execution of specific tools within specific scopes.
+ *
+ * Security properties:
+ * - Short-lived: TTL defaults to 30 seconds
+ * - Single-use: nonce prevents replay attacks
+ * - Scoped: limited to specific tools and servers
+ * - Signed: HMAC-SHA256 prevents forgery
+ */
+export interface CapabilityToken {
+    readonly jti: string;
+    readonly iss: string;
+    readonly sub: string;
+    readonly iat: number;
+    readonly exp: number;
+    readonly permissions: readonly Permission[];
+    readonly toolScope: readonly string[];
+    readonly serverScope: readonly string[];
+    readonly pathScope?: readonly string[];
+}
+/**
+ * Configuration for token issuance.
+ */
+export interface TokenConfig {
+    readonly secret: string;
+    readonly ttlSeconds: number;
+    readonly algorithm: 'HS256';
+    readonly issuer: string;
+}
+/**
+ * Default token configuration.
+ * Secret must be provided - no default.
+ */
+export declare const DEFAULT_TOKEN_TTL_SECONDS = 30;
+export declare const TOKEN_ALGORITHM: "HS256";
+export declare const MIN_SECRET_LENGTH = 32;
+/**
+ * Result of token verification.
+ */
+export interface TokenVerificationResult {
+    readonly valid: boolean;
+    readonly payload?: CapabilityToken;
+    readonly reason?: string;
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,47 @@
+/** Default policy effect when no rule matches: DENY */
+export declare const DEFAULT_POLICY_EFFECT: "DENY";
+/** Maximum number of rules in a single PolicySet */
+export declare const MAX_RULES_PER_POLICY_SET = 1000;
+/** Maximum depth for nested argument validation */
+export declare const MAX_ARGUMENT_DEPTH = 10;
+/** Maximum size of tool arguments in bytes */
+export declare const MAX_ARGUMENTS_SIZE_BYTES = 1048576;
+/** Maximum length of a tool name */
+export declare const MAX_TOOL_NAME_LENGTH = 256;
+/** Maximum length of a server name */
+export declare const MAX_SERVER_NAME_LENGTH = 256;
+/** Default rate limit per tool per minute */
+export declare const DEFAULT_RATE_LIMIT_PER_MINUTE = 60;
+/** Maximum rate limit per tool per minute */
+export declare const MAX_RATE_LIMIT_PER_MINUTE = 10000;
+/** Security context timeout in milliseconds (5 minutes) */
+export declare const SECURITY_CONTEXT_TIMEOUT_MS: number;
+/** Policy evaluation timeout in milliseconds (100ms) */
+export declare const POLICY_EVALUATION_TIMEOUT_MS = 100;
+/** Default maximum length per string argument */
+export declare const INPUT_GUARD_MAX_LENGTH = 4096;
+/** Shannon entropy threshold for encoded payload detection */
+export declare const INPUT_GUARD_ENTROPY_THRESHOLD = 4.5;
+/** Minimum string length before entropy check applies */
+export declare const INPUT_GUARD_MIN_ENTROPY_LENGTH = 32;
+/** Maximum wildcards allowed per value */
+export declare const INPUT_GUARD_MAX_WILDCARDS = 3;
+/** Default capability token TTL in seconds */
+export declare const TOKEN_DEFAULT_TTL_SECONDS = 30;
+/** Minimum secret key length for HMAC signing */
+export declare const TOKEN_MIN_SECRET_LENGTH = 32;
+/** Maximum token age before forced expiry (5 minutes) */
+export declare const TOKEN_MAX_AGE_SECONDS = 300;
+/** Default sliding window size in milliseconds (1 minute) */
+export declare const RATE_LIMIT_WINDOW_MS = 60000;
+/** Maximum entries to keep per tool before cleanup */
+export declare const RATE_LIMIT_MAX_ENTRIES = 10000;
+/** Warning messages for unsafe configurations. */
+export declare const UNSAFE_CONFIGURATION_WARNINGS: {
+    readonly WILDCARD_ALLOW: "Wildcard ALLOW rules grant permission to ALL tools. This bypasses the default-deny model.";
+    readonly TRUSTED_LEVEL_EXTERNAL: "Setting trust level to TRUSTED for external requests bypasses all security checks.";
+    readonly WRITE_WITHOUT_READ: "Granting WRITE without READ is unusual and may indicate a misconfiguration.";
+    readonly EXECUTE_WITHOUT_REVIEW: "EXECUTE permission allows tools to perform arbitrary actions. Review carefully.";
+    readonly RATE_LIMIT_ZERO: "A rate limit of 0 means unlimited calls. This removes protection against runaway loops.";
+    readonly DISABLED_VALIDATION: "Disabling schema validation removes input sanitization protections.";
+};

package/dist/core/context-boundary.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Context Boundary Tagging: wraps user-provided tool arguments with
+ * boundary markers so the LLM can distinguish user input from system data.
+ *
+ * This prevents confusion attacks where adversarial input is treated
+ * as trusted system instructions.
+ */
+export type TaggedArguments = Record<string, unknown>;
+/**
+ * Wraps all string values in the arguments with context boundary markers.
+ * Non-string values are passed through unchanged.
+ * Objects and arrays are recursively tagged.
+ */
+export declare function tagUserInput(args: Record<string, unknown>): TaggedArguments;
+/**
+ * Strips all boundary tags from a string (e.g. from tool responses before
+ * returning to client).
+ */
+export declare function stripBoundaryTags(text: string): string;

package/dist/core/context.d.ts

@@ -0,0 +1,24 @@
+import type { TrustLevel } from './trust.js';
+import type { PermissionSet } from './permissions.js';
+/**
+ * SecurityContext represents the security state of a single request.
+ * Created fresh for each MCP request and NEVER reused.
+ * All fields are readonly - state transitions create new contexts.
+ */
+export interface SecurityContext {
+    readonly requestId: string;
+    readonly trustLevel: TrustLevel;
+    readonly grantedPermissions: PermissionSet;
+    readonly sessionId: string | null;
+    readonly createdAt: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly capabilityToken?: string;
+}
+/** Extends SecurityContext with tool-specific execution information. */
+export interface ExecutionContext extends SecurityContext {
+    readonly toolName: string;
+    readonly serverName: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+/** Creates a new SecurityContext with default-deny settings. */
+export declare function createSecurityContext(params: Pick<SecurityContext, 'requestId'> & Partial<Omit<SecurityContext, 'requestId' | 'createdAt' | 'trustLevel' | 'grantedPermissions'>>): SecurityContext;

package/dist/core/errors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Base error class for all SolonGate security errors.
+ * Every error includes a machine-readable code for programmatic handling.
+ */
+export declare class SolonGateError extends Error {
+    readonly code: string;
+    readonly timestamp: string;
+    readonly details: Record<string, unknown>;
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+    /**
+     * Serializable representation for logging and API responses.
+     * Never includes stack traces (information leakage prevention).
+     */
+    toJSON(): Record<string, unknown>;
+}
+/** Thrown when a tool call is denied by policy. */
+export declare class PolicyDeniedError extends SolonGateError {
+    constructor(toolName: string, reason: string, details?: Record<string, unknown>);
+}
+/** Thrown when a trust level escalation is attempted illegally. */
+export declare class TrustEscalationError extends SolonGateError {
+    constructor(message: string);
+}
+/** Thrown when tool input fails schema validation. */
+export declare class SchemaValidationError extends SolonGateError {
+    constructor(toolName: string, validationErrors: readonly string[]);
+}
+/** Thrown when a tool exceeds its rate limit. */
+export declare class RateLimitError extends SolonGateError {
+    constructor(toolName: string, limitPerMinute: number);
+}
+/** Thrown when a tool is not found in the registry. */
+export declare class ToolNotFoundError extends SolonGateError {
+    constructor(toolName: string, serverName: string);
+}
+/** Thrown when an unsafe configuration is detected. */
+export declare class UnsafeConfigurationError extends SolonGateError {
+    constructor(message: string, field: string);
+}
+/** Thrown when input guard detects dangerous patterns. */
+export declare class InputGuardError extends SolonGateError {
+    constructor(toolName: string, threats: readonly {
+        type: string;
+        field: string;
+        description: string;
+    }[]);
+}
+/** Thrown when a network operation fails (API calls, cloud sync, etc.). */
+export declare class NetworkError extends SolonGateError {
+    constructor(operation: string, statusCode?: number, details?: Record<string, unknown>);
+}

package/dist/core/execution.d.ts

@@ -0,0 +1,35 @@
+import type { SecurityContext } from './context.js';
+import type { Permission } from './permissions.js';
+import type { PolicyDecision } from './policy.js';
+import type { SolonGateError } from './errors.js';
+/** An execution request represents a tool call that needs security evaluation. */
+export interface ExecutionRequest {
+    readonly context: SecurityContext;
+    readonly toolName: string;
+    readonly serverName: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+    readonly requiredPermission: Permission;
+    readonly timestamp: string;
+}
+/** Discriminated union on `status` for exhaustive matching. */
+export type ExecutionResult = ExecutionResultAllowed | ExecutionResultDenied | ExecutionResultError;
+export interface ExecutionResultAllowed {
+    readonly status: 'ALLOWED';
+    readonly request: ExecutionRequest;
+    readonly decision: PolicyDecision;
+    readonly toolResult: unknown;
+    readonly durationMs: number;
+    readonly timestamp: string;
+}
+export interface ExecutionResultDenied {
+    readonly status: 'DENIED';
+    readonly request: ExecutionRequest;
+    readonly decision: PolicyDecision;
+    readonly timestamp: string;
+}
+export interface ExecutionResultError {
+    readonly status: 'ERROR';
+    readonly request: ExecutionRequest;
+    readonly error: SolonGateError;
+    readonly timestamp: string;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+export { TrustLevel, isValidTrustLevel, assertValidTransition } from './trust.js';
+export { Permission, PermissionSchema, type PermissionSet, createPermissionSet, hasPermission, hasAllPermissions, permissionForMethod, guessPermission, NO_PERMISSIONS, READ_ONLY, } from './permissions.js';
+export { PolicyEffect, type PolicyRule, type PolicySet, type PolicyDecision, PolicyRuleSchema, PolicySetSchema, } from './policy.js';
+export { type ToolCapability, createToolCapability, } from './tool.js';
+export { type SecurityContext, type ExecutionContext, createSecurityContext, } from './context.js';
+export { type ExecutionRequest, type ExecutionResult, type ExecutionResultAllowed, type ExecutionResultDenied, type ExecutionResultError, } from './execution.js';
+export { SolonGateError, PolicyDeniedError, TrustEscalationError, SchemaValidationError, RateLimitError, ToolNotFoundError, UnsafeConfigurationError, InputGuardError, NetworkError, } from './errors.js';
+export * from './constants.js';
+export { type McpToolDefinition, type McpCallToolParams, type McpCallToolResult, type McpToolResultContent, createDeniedToolResult, } from './mcp-types.js';
+export { validateToolInput, createStrictSchema, type SchemaValidationResult, type SchemaValidatorOptions, } from './schema-validator.js';
+export { detectPathTraversal, detectShellInjection, detectWildcardAbuse, detectSSRF, detectSQLInjection, detectExfiltration, detectBoundaryEscape, checkLengthLimits, checkEntropyLimits, sanitizeInput, sanitizeInputAsync, DEFAULT_INPUT_GUARD_CONFIG, BOUNDARY_PREFIX, BOUNDARY_SUFFIX, type ThreatType, type DetectedThreat, type SanitizationResult, type AsyncSanitizationResult, type InputGuardConfig, } from './input-guard.js';
+export { scanResponse, RESPONSE_WARNING_MARKER, DEFAULT_RESPONSE_SCAN_CONFIG, type ResponseThreatType, type ResponseThreat, type ResponseScanResult, type ResponseScanConfig, } from './response-scanner.js';
+export { tagUserInput, stripBoundaryTags, type TaggedArguments, } from './context-boundary.js';
+export { type CapabilityToken, type TokenConfig, type TokenVerificationResult, DEFAULT_TOKEN_TTL_SECONDS, TOKEN_ALGORITHM, MIN_SECRET_LENGTH, } from './capability-token.js';

package/dist/core/input-guard.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Input Guard: detects and blocks dangerous patterns in tool arguments.
+ *
+ * Prevents physical execution of injected instructions by checking for:
+ * - Path traversal attacks (../, ..\, encoded variants)
+ * - Shell injection (;, |, &, `, $(), etc.)
+ * - Wildcard abuse (**, recursive globs)
+ * - Excessive length
+ * - High-entropy payloads (potential encoded exploits)
+ */
+/** Threat type detected by input guard. */
+export type ThreatType = 'PATH_TRAVERSAL' | 'SHELL_INJECTION' | 'WILDCARD_ABUSE' | 'LENGTH_EXCEEDED' | 'HIGH_ENTROPY' | 'SSRF' | 'SQL_INJECTION' | 'PROMPT_INJECTION' | 'EXFILTRATION' | 'BOUNDARY_ESCAPE';
+/** A detected threat with details. */
+export interface DetectedThreat {
+    readonly type: ThreatType;
+    readonly field: string;
+    readonly value: string;
+    readonly description: string;
+}
+/** Result of sanitization check. */
+export interface SanitizationResult {
+    readonly safe: boolean;
+    readonly threats: readonly DetectedThreat[];
+}
+/** Configuration for input guard checks. */
+export interface InputGuardConfig {
+    readonly pathTraversal: boolean;
+    readonly shellInjection: boolean;
+    readonly wildcardAbuse: boolean;
+    readonly lengthLimit: number;
+    readonly entropyLimit: boolean;
+    readonly ssrf: boolean;
+    readonly sqlInjection: boolean;
+    readonly exfiltration: boolean;
+    readonly boundaryEscape: boolean;
+}
+export declare const DEFAULT_INPUT_GUARD_CONFIG: Readonly<InputGuardConfig>;
+export declare function detectPathTraversal(value: string): boolean;
+export declare function detectShellInjection(value: string): boolean;
+export declare function detectWildcardAbuse(value: string): boolean;
+export declare function detectSSRF(value: string): boolean;
+export declare function detectSQLInjection(value: string): boolean;
+export declare function detectExfiltration(value: string): boolean;
+/** Context boundary markers used by SolonGate. */
+export declare const BOUNDARY_PREFIX = "[USER_INPUT_START]";
+export declare const BOUNDARY_SUFFIX = "[USER_INPUT_END]";
+export declare function detectBoundaryEscape(value: string): boolean;
+export declare function checkLengthLimits(value: string, maxLength?: number): boolean;
+/**
+ * Detects high-entropy strings that may indicate encoded payloads.
+ * Uses Shannon entropy calculation.
+ * Threshold: 4.5 bits per character (base64 encoded data is ~6.0).
+ */
+export declare function checkEntropyLimits(value: string): boolean;
+/**
+ * Runs all input guard checks on a value.
+ * Returns structured result with all detected threats.
+ */
+export declare function sanitizeInput(field: string, value: unknown, config?: InputGuardConfig): SanitizationResult;
+/** Async result shape (kept for API compatibility; same as the sync result). */
+export type AsyncSanitizationResult = SanitizationResult;
+/**
+ * Async wrapper around sanitizeInput(). Kept async so callers (the proxy) can
+ * await it uniformly; the deterministic checks run synchronously.
+ */
+export declare function sanitizeInputAsync(field: string, value: unknown, config?: InputGuardConfig): Promise<AsyncSanitizationResult>;

package/dist/core/mcp-types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Types that bridge between the MCP protocol and SolonGate's type system.
+ * Adapts MCP SDK types without creating a hard dependency.
+ */
+export interface McpToolDefinition {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: {
+        readonly type: 'object';
+        readonly properties?: Record<string, unknown>;
+        readonly required?: readonly string[];
+    };
+}
+export interface McpCallToolParams {
+    readonly name: string;
+    readonly arguments?: Record<string, unknown>;
+}
+export interface McpCallToolResult {
+    readonly content: readonly McpToolResultContent[];
+    readonly isError?: boolean;
+    readonly structuredContent?: unknown;
+}
+export type McpToolResultContent = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'image';
+    readonly data: string;
+    readonly mimeType: string;
+} | {
+    readonly type: 'resource';
+    readonly resource: unknown;
+};
+/** Wraps denied tool calls in MCP error responses. */
+export declare function createDeniedToolResult(reason: string): McpCallToolResult;

package/dist/core/permissions.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * Permission types are ALWAYS evaluated independently.
+ * Having READ does NOT imply WRITE or EXECUTE.
+ */
+export declare const Permission: {
+    readonly READ: "READ";
+    readonly WRITE: "WRITE";
+    readonly EXECUTE: "EXECUTE";
+    readonly NETWORK: "NETWORK";
+};
+export type Permission = (typeof Permission)[keyof typeof Permission];
+export declare const PermissionSchema: z.ZodEnum<["READ", "WRITE", "EXECUTE", "NETWORK"]>;
+/** Guess the permission type from a tool name. */
+export declare function guessPermission(toolName: string): Permission;
+/** Immutable set of permissions granted to a specific scope. */
+export type PermissionSet = ReadonlySet<Permission>;
+/** Creates an immutable permission set from an array. */
+export declare function createPermissionSet(permissions: Permission[]): PermissionSet;
+/** Empty permission set - the default for all new tools (default-deny). */
+export declare const NO_PERMISSIONS: PermissionSet;
+/** Read-only permission set - the maximum default for new tools. */
+export declare const READ_ONLY: PermissionSet;
+export declare function hasPermission(permissions: PermissionSet, required: Permission): boolean;
+export declare function hasAllPermissions(permissions: PermissionSet, required: Permission[]): boolean;
+/** Maps MCP protocol methods to SolonGate permission types. */
+export declare function permissionForMethod(method: string): Permission;