@solongate/sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,511 @@
+import * as _solongate_policy_engine from '@solongate/policy-engine';
+import { PolicyEngine } from '@solongate/policy-engine';
+export { PolicyDiff, PolicyEngine, PolicyStore, PolicyVersion, createDefaultDenyPolicySet, createReadOnlyPolicySet } from '@solongate/policy-engine';
+import { PolicySet, InputGuardConfig, TokenConfig, Permission, TokenVerificationResult, McpCallToolParams, McpCallToolResult, ExecutionResult, TrustLevel, PolicyDecision } from '@solongate/core';
+export { CapabilityToken, RateLimitError as CoreRateLimitError, DetectedThreat, ExecutionRequest, ExecutionResult, InputGuardConfig, InputGuardError, McpCallToolParams, McpCallToolResult, NetworkError, Permission, PolicyDecision, PolicyDeniedError, PolicyEffect, PolicyRule, PolicySet, SanitizationResult, SchemaValidationError, SecurityContext, SolonGateError, ThreatType, TokenConfig, ToolCapability, TrustLevel, checkEntropyLimits, checkLengthLimits, createDeniedToolResult, createSecurityContext, detectPathTraversal, detectSQLInjection, detectSSRF, detectShellInjection, detectWildcardAbuse, sanitizeInput, validateToolInput } from '@solongate/core';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Implementation } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Configuration for the SolonGate SDK.
+ * All fields have secure defaults. Weakening requires explicit opt-in.
+ */
+interface SolonGateConfig {
+    readonly policySet?: PolicySet;
+    readonly validateSchemas: boolean;
+    readonly enableLogging: boolean;
+    readonly logLevel: 'debug' | 'info' | 'warn' | 'error';
+    readonly evaluationTimeoutMs: number;
+    readonly verboseErrors: boolean;
+    readonly globalRateLimitPerMinute: number;
+    readonly rateLimitPerTool: number;
+    readonly tokenSecret?: string;
+    readonly tokenTtlSeconds: number;
+    readonly tokenIssuer?: string;
+    readonly gatewaySecret?: string;
+    readonly inputGuardConfig: InputGuardConfig;
+    readonly enableVersionedPolicies: boolean;
+    readonly apiUrl?: string;
+}
+declare const DEFAULT_CONFIG: Readonly<SolonGateConfig>;
+declare function resolveConfig(userConfig?: Partial<SolonGateConfig>): {
+    config: SolonGateConfig;
+    warnings: string[];
+};
+
+/**
+ * Issues and verifies capability tokens using HMAC-SHA256.
+ *
+ * Security properties:
+ * - Short-lived TTL (default 30 seconds)
+ * - Single-use nonces (replay prevention)
+ * - Revocation support
+ * - No external JWT library dependency
+ */
+declare class TokenIssuer {
+    private readonly secret;
+    private readonly ttlSeconds;
+    private readonly issuer;
+    private readonly usedNonces;
+    private readonly revokedTokens;
+    constructor(config: TokenConfig);
+    /**
+     * Issues a signed capability token.
+     */
+    issue(requestId: string, permissions: readonly Permission[], toolScope: readonly string[], serverScope?: readonly string[], pathScope?: readonly string[]): string;
+    /**
+     * Verifies a capability token and consumes the nonce (single-use).
+     */
+    verify(token: string): TokenVerificationResult;
+    /**
+     * Revokes a token by its ID.
+     */
+    revoke(jti: string): void;
+    /**
+     * Checks if a token ID has been revoked.
+     */
+    isRevoked(jti: string): boolean;
+    private sign;
+    private parseAndVerify;
+    private computeSignature;
+}
+
+/**
+ * Result of a rate limit check.
+ */
+interface RateLimitResult {
+    readonly allowed: boolean;
+    readonly remaining: number;
+    readonly resetAt: number;
+}
+/**
+ * Sliding window rate limiter for tool calls.
+ *
+ * Tracks per-tool and global call rates using an in-memory sliding window.
+ * Window size defaults to 1 minute.
+ */
+declare class RateLimiter {
+    private readonly windowMs;
+    private readonly records;
+    private globalRecords;
+    constructor(options?: {
+        windowMs?: number;
+    });
+    /**
+     * Checks if a tool call is within the rate limit.
+     * Does NOT record the call - use recordCall() after successful execution.
+     */
+    checkLimit(toolName: string, limitPerWindow: number): RateLimitResult;
+    /**
+     * Checks the global rate limit across all tools.
+     */
+    checkGlobalLimit(limitPerWindow: number): RateLimitResult;
+    /**
+     * Atomically checks and records a tool call.
+     * Prevents TOCTOU race conditions between check and record.
+     * Returns the rate limit result; if allowed, the call is already recorded.
+     */
+    checkAndRecord(toolName: string, limitPerWindow: number, globalLimit?: number): RateLimitResult;
+    /**
+     * Records a tool call for rate limiting.
+     * Call this after successful execution.
+     */
+    recordCall(toolName: string): void;
+    /**
+     * Gets usage stats for a tool.
+     */
+    getUsage(toolName: string): {
+        count: number;
+        windowStart: number;
+    };
+    /**
+     * Resets rate tracking for a specific tool.
+     */
+    resetTool(toolName: string): void;
+    /**
+     * Resets all rate tracking.
+     */
+    resetAll(): void;
+    private getActiveRecords;
+}
+
+/**
+ * Error thrown when a valid SolonGate license (API key) is missing or invalid.
+ */
+declare class LicenseError extends Error {
+    constructor(message: string);
+}
+/**
+ * SolonGate - Security Gateway for MCP Tool Servers.
+ *
+ * Requires a valid API key. Get one at https://solongate.com
+ *
+ * Usage:
+ * ```typescript
+ * const gate = new SolonGate({ name: 'my-gateway', apiKey: 'sg_live_xxx' });
+ *
+ * // Intercept a tool call
+ * const result = await gate.executeToolCall(
+ *   { name: 'file.read', arguments: { path: '/etc/passwd' } },
+ *   async (params) => upstreamMcpServer.callTool(params),
+ * );
+ * ```
+ *
+ * Architecture:
+ *   [LLM] -> [SolonGate.executeToolCall] -> [Security Pipeline] -> [Upstream MCP Server]
+ *
+ * Pipeline:
+ *   Rate Limit → Input Guard → Policy Eval → Token Issue → Sign → Call → Audit
+ */
+declare class SolonGate {
+    private readonly policyEngine;
+    private readonly config;
+    private readonly logger;
+    private readonly configWarnings;
+    private readonly tokenIssuer;
+    private readonly serverVerifier;
+    private readonly rateLimiter;
+    private readonly apiKey;
+    private licenseValidated;
+    constructor(options: {
+        name: string;
+        version?: string;
+        apiKey?: string;
+        config?: Partial<SolonGateConfig>;
+        policySet?: PolicySet;
+    });
+    /**
+     * Validate the API key against the SolonGate cloud API.
+     * Called once on first executeToolCall. Throws LicenseError if invalid.
+     * Test keys (sg_test_) skip online validation.
+     */
+    private validateLicense;
+    /**
+     * Intercept and evaluate a tool call against the full security pipeline.
+     * If denied at any stage, returns an error result without calling upstream.
+     * If allowed, calls upstream and returns the result.
+     */
+    executeToolCall(params: McpCallToolParams, upstreamCall: (params: McpCallToolParams) => Promise<McpCallToolResult>): Promise<McpCallToolResult>;
+    /** Load a new policy set at runtime. */
+    loadPolicy(policySet: PolicySet, options?: {
+        reason?: string;
+        createdBy?: string;
+    }): _solongate_policy_engine.ValidationResult;
+    /** Get current security warnings. */
+    getWarnings(): readonly string[];
+    /** Get the policy engine for direct access. */
+    getPolicyEngine(): PolicyEngine;
+    /** Get the rate limiter for direct access. */
+    getRateLimiter(): RateLimiter;
+    /** Get the token issuer (null if not configured). */
+    getTokenIssuer(): TokenIssuer | null;
+}
+
+/**
+ * SecureMcpServer — Drop-in replacement for McpServer with SolonGate protection.
+ *
+ * Extends the standard McpServer and automatically wraps every tool handler
+ * with SolonGate's security pipeline (rate limiting, input guard, policy eval,
+ * audit logging). No manual wrapping of individual tool handlers needed.
+ *
+ * Usage:
+ * ```typescript
+ * import { SecureMcpServer } from '@solongate/sdk';
+ *
+ * // Just replace `new McpServer(...)` with `new SecureMcpServer(...)`
+ * const server = new SecureMcpServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ * });
+ *
+ * // Register tools as normal — they're automatically protected
+ * server.tool('file_read', { path: z.string() }, async ({ path }) => {
+ *   return { content: [{ type: 'text', text: readFileSync(path, 'utf-8') }] };
+ * });
+ *
+ * // API key comes from env: SOLONGATE_API_KEY=sg_live_xxx
+ * ```
+ */
+
+/**
+ * Options for SecureMcpServer that control SolonGate behavior.
+ */
+interface SecureMcpServerOptions {
+    /** SolonGate Cloud API key. Defaults to process.env.SOLONGATE_API_KEY */
+    apiKey?: string;
+    /** Policy set to enforce. If omitted, uses cloud policy or default. */
+    policySet?: PolicySet;
+    /** SolonGate configuration overrides. */
+    config?: Partial<SolonGateConfig>;
+}
+declare class SecureMcpServer extends McpServer {
+    private readonly gate;
+    /**
+     * Create a secure MCP server.
+     *
+     * @param serverInfo - MCP server info (name, version)
+     * @param solongateOptions - SolonGate security options
+     * @param mcpOptions - Standard McpServer options (capabilities, etc.)
+     */
+    constructor(serverInfo: Implementation, solongateOptions?: SecureMcpServerOptions, mcpOptions?: ConstructorParameters<typeof McpServer>[1]);
+    /**
+     * Override tool() to auto-wrap handlers with SolonGate security pipeline.
+     *
+     * Supports all McpServer.tool() overloads — the handler (always the last
+     * argument) is transparently wrapped. Tool name, description, schema, and
+     * annotations pass through unchanged.
+     */
+    tool(name: string, ...rest: unknown[]): ReturnType<McpServer['tool']>;
+    /**
+     * Override registerTool() to auto-wrap handlers with SolonGate security pipeline.
+     *
+     * This is the modern (non-deprecated) API for registering tools.
+     */
+    registerTool(name: string, config: Parameters<McpServer['registerTool']>[1], cb: unknown): ReturnType<McpServer['registerTool']>;
+    /** Get the underlying SolonGate instance for direct access. */
+    getSolonGate(): SolonGate;
+}
+
+/**
+ * A signed MCP request that includes capability token and integrity signature.
+ * Requests without valid gateway signature should be rejected by MCP servers.
+ */
+interface SignedMcpRequest {
+    readonly params: McpCallToolParams;
+    readonly capabilityToken: string;
+    readonly signature: string;
+    readonly timestamp: string;
+    readonly nonce: string;
+}
+/**
+ * Result of validating a signed request.
+ */
+interface SignatureValidationResult {
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+/**
+ * Signs and verifies MCP requests to ensure they originate from the gateway.
+ *
+ * Security properties:
+ * - HMAC-SHA256 signature of request params + token
+ * - Timestamp to prevent old request replays
+ * - Nonce for uniqueness
+ * - Configurable max age for timestamp validation
+ */
+declare class ServerVerifier {
+    private readonly gatewaySecret;
+    private readonly maxAgeMs;
+    private readonly usedNonces;
+    constructor(config: {
+        gatewaySecret: string;
+        maxAgeMs?: number;
+    });
+    /**
+     * Computes HMAC signature for request data.
+     */
+    signRequest(params: McpCallToolParams, capabilityToken: string): string;
+    /**
+     * Verifies the HMAC signature of request data.
+     */
+    verifySignature(params: McpCallToolParams, capabilityToken: string, signature: string): boolean;
+    /**
+     * Creates a complete signed request including timestamp and nonce.
+     */
+    createSignedRequest(params: McpCallToolParams, capabilityToken: string): SignedMcpRequest;
+    /**
+     * Validates a complete signed request including timestamp, nonce, and signature.
+     */
+    validateSignedRequest(request: SignedMcpRequest): SignatureValidationResult;
+}
+
+interface InterceptorOptions {
+    readonly policyEngine: PolicyEngine;
+    readonly validateSchemas: boolean;
+    readonly verboseErrors: boolean;
+    readonly onDecision?: (result: ExecutionResult) => void;
+    readonly tokenIssuer?: TokenIssuer;
+    readonly serverVerifier?: ServerVerifier;
+    readonly rateLimiter?: RateLimiter;
+    readonly inputGuardConfig?: InputGuardConfig;
+    readonly rateLimitPerTool?: number;
+    readonly globalRateLimitPerMinute?: number;
+}
+/**
+ * Intercepts an MCP tool call and runs the full security pipeline:
+ *
+ * 1. Rate limit check → RateLimitError if exceeded
+ * 2. Input guard (sanitization) → SchemaValidationError if dangerous
+ * 3. Policy evaluation → PolicyDeniedError if denied
+ * 4. Issue capability token (if TokenIssuer configured)
+ * 5. Sign request (if ServerVerifier configured)
+ * 6. Call upstream
+ * 7. Record rate limit usage
+ * 8. Log to audit trail
+ * 9. Return result
+ */
+declare function interceptToolCall(params: McpCallToolParams, upstreamCall: (params: McpCallToolParams) => Promise<McpCallToolResult>, options: InterceptorOptions): Promise<McpCallToolResult>;
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured security event logger.
+ * Outputs JSON-formatted log entries for machine consumption.
+ */
+declare class SecurityLogger {
+    private readonly minLevel;
+    private readonly enabled;
+    constructor(options: {
+        level: LogLevel;
+        enabled: boolean;
+    });
+    logDecision(result: ExecutionResult): void;
+    private log;
+}
+
+/**
+ * SolonGate API Client for TypeScript/JavaScript
+ *
+ * Provides cloud-based security management with API keys.
+ *
+ * @example
+ * ```typescript
+ * import { SolonGateAPI } from '@solongate/sdk';
+ *
+ * const api = new SolonGateAPI({ apiKey: 'sg_live_xxx' });
+ *
+ * const result = await api.validate('file.read', { path: '/home/user/doc.txt' });
+ * if (result.allowed) {
+ *   console.log('Allowed! Token:', result.token);
+ * }
+ * ```
+ */
+
+interface APIConfig {
+    apiKey: string;
+    apiUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+interface ValidationRequest {
+    tool: string;
+    arguments: Record<string, unknown>;
+    trustLevel?: TrustLevel;
+    includeToken?: boolean;
+}
+interface ValidationResult {
+    allowed: boolean;
+    tool: string;
+    decision?: PolicyDecision;
+    token?: string;
+    tokenExpiresAt?: number;
+    requestId?: string;
+    latencyMs?: number;
+}
+interface TokenResult {
+    token: string;
+    tool: string;
+    scope: string;
+    expiresAt: string;
+    nonce: string;
+}
+interface Tool {
+    id: string;
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    permissions: string[];
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+declare class APIError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly requestId?: string | undefined;
+    readonly code: string;
+    constructor(message: string, statusCode?: number | undefined, requestId?: string | undefined, code?: string);
+}
+declare class AuthenticationError extends APIError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends APIError {
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, retryAfter?: number | undefined);
+}
+declare class PoliciesResource {
+    private client;
+    constructor(client: SolonGateAPI);
+    get(policyId?: string, version?: number): Promise<PolicySet>;
+    list(): Promise<{
+        policies: Array<{
+            id: string;
+            name: string;
+            version: number;
+        }>;
+    }>;
+    create(policy: PolicySet): Promise<PolicySet>;
+    update(policyId: string, policy: PolicySet): Promise<PolicySet>;
+}
+declare class TokensResource {
+    private client;
+    constructor(client: SolonGateAPI);
+    create(tool: string, scope?: string, ttlSeconds?: number): Promise<TokenResult>;
+    verify(token: string): Promise<{
+        valid: boolean;
+        error?: string;
+        tool?: string;
+        scope?: string;
+    }>;
+}
+declare class ToolsResource {
+    private client;
+    constructor(client: SolonGateAPI);
+    list(): Promise<{
+        tools: Tool[];
+    }>;
+    get(name: string): Promise<Tool>;
+    register(name: string, description: string, inputSchema?: Record<string, unknown>, permissions?: string[]): Promise<Tool>;
+    update(name: string, data: Partial<Tool>): Promise<Tool>;
+    delete(name: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+declare class SolonGateAPI {
+    private readonly apiKey;
+    private readonly apiUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    readonly policies: PoliciesResource;
+    readonly tokens: TokensResource;
+    readonly tools: ToolsResource;
+    constructor(config: APIConfig | string);
+    /**
+     * Make an API request.
+     * @internal
+     */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /**
+     * Validate a tool call against policies.
+     *
+     * @example
+     * ```typescript
+     * const result = await api.validate('file.read', { path: '/home/user/doc.txt' });
+     * if (result.allowed) {
+     *   // Proceed with the tool call
+     * }
+     * ```
+     */
+    validate(tool: string, args: Record<string, unknown>, options?: {
+        trustLevel?: TrustLevel;
+        includeToken?: boolean;
+    }): Promise<ValidationResult>;
+    /**
+     * Check if using live (production) API key.
+     */
+    isLiveMode(): boolean;
+    /**
+     * Check if using test (development) API key.
+     */
+    isTestMode(): boolean;
+}
+
+export { type APIConfig, APIError, AuthenticationError, DEFAULT_CONFIG, type InterceptorOptions, LicenseError, RateLimitError, type RateLimitResult, RateLimiter, SecureMcpServer, type SecureMcpServerOptions, SecurityLogger, ServerVerifier, type SignatureValidationResult, type SignedMcpRequest, SolonGate, SolonGateAPI, type SolonGateConfig, TokenIssuer, type TokenResult, type Tool, type ValidationRequest, type ValidationResult, interceptToolCall, resolveConfig };