@kya-os/mcp-i-core 1.7.0 → 1.8.1

package/dist/services/provider-validator.js

@@ -1,135 +0,0 @@
-"use strict";
-/**
- * Provider Validator
- *
- * Validates OAuth provider configurations for custom IDP support.
- * Ensures provider configurations are valid before registration.
- *
- * @package @kya-os/mcp-i-core
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProviderValidator = exports.ProviderValidationError = void 0;
-/**
- * Reserved OAuth parameters that cannot be overridden by custom parameters
- */
-const RESERVED_PARAMETERS = [
-    "response_type",
-    "client_id",
-    "redirect_uri",
-    "scope",
-    "state",
-    "code_challenge",
-    "code_challenge_method",
-];
-/**
- * Validation error for provider configuration issues
- */
-class ProviderValidationError extends Error {
-    field;
-    constructor(message, field) {
-        super(message);
-        this.field = field;
-        this.name = "ProviderValidationError";
-    }
-}
-exports.ProviderValidationError = ProviderValidationError;
-/**
- * Service for validating OAuth provider configurations
- */
-class ProviderValidator {
-    /**
-     * Validate provider configuration
-     *
-     * @param provider - Provider configuration to validate
-     * @param name - Provider name (for error messages)
-     * @throws ProviderValidationError if validation fails
-     */
-    validate(provider, name) {
-        // Validate required fields
-        if (!provider.clientId || provider.clientId.trim().length === 0) {
-            throw new ProviderValidationError(`Provider "${name}" must have a clientId`, "clientId");
-        }
-        if (!provider.authorizationUrl || provider.authorizationUrl.trim().length === 0) {
-            throw new ProviderValidationError(`Provider "${name}" must have an authorizationUrl`, "authorizationUrl");
-        }
-        if (!provider.tokenUrl || provider.tokenUrl.trim().length === 0) {
-            throw new ProviderValidationError(`Provider "${name}" must have a tokenUrl`, "tokenUrl");
-        }
-        // Validate URL formats
-        this.validateUrl(provider.authorizationUrl, name, "authorizationUrl");
-        this.validateUrl(provider.tokenUrl, name, "tokenUrl");
-        if (provider.userInfoUrl) {
-            this.validateUrl(provider.userInfoUrl, name, "userInfoUrl");
-        }
-        // Validate proxy mode requirements
-        if (provider.proxyMode && !provider.requiresClientSecret) {
-            throw new ProviderValidationError(`Provider "${name}" with proxyMode=true must have requiresClientSecret=true`, "proxyMode");
-        }
-        // Validate custom parameters don't conflict with reserved parameters
-        if (provider.customParams) {
-            this.validateCustomParams(provider.customParams, name);
-        }
-    }
-    /**
-     * Validate URL format
-     *
-     * @param url - URL to validate
-     * @param providerName - Provider name (for error messages)
-     * @param fieldName - Field name (for error messages)
-     * @throws ProviderValidationError if URL is invalid
-     */
-    validateUrl(url, providerName, fieldName) {
-        try {
-            const parsedUrl = new URL(url);
-            if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
-                throw new ProviderValidationError(`Provider "${providerName}" ${fieldName} must use HTTP or HTTPS protocol`, fieldName);
-            }
-        }
-        catch (error) {
-            if (error instanceof ProviderValidationError) {
-                throw error;
-            }
-            throw new ProviderValidationError(`Provider "${providerName}" ${fieldName} is not a valid URL: ${error instanceof Error ? error.message : String(error)}`, fieldName);
-        }
-    }
-    /**
-     * Validate custom parameters don't override reserved OAuth parameters
-     *
-     * @param customParams - Custom parameters to validate
-     * @param providerName - Provider name (for error messages)
-     * @throws ProviderValidationError if reserved parameter is overridden
-     */
-    validateCustomParams(customParams, providerName) {
-        for (const [key, value] of Object.entries(customParams)) {
-            const normalizedKey = key.toLowerCase();
-            if (RESERVED_PARAMETERS.includes(normalizedKey)) {
-                throw new ProviderValidationError(`Provider "${providerName}" custom parameter "${key}" conflicts with reserved OAuth parameter. Reserved parameters: ${RESERVED_PARAMETERS.join(", ")}`, `customParams.${key}`);
-            }
-            if (!value || value.trim().length === 0) {
-                throw new ProviderValidationError(`Provider "${providerName}" custom parameter "${key}" has empty value`, `customParams.${key}`);
-            }
-        }
-    }
-    /**
-     * Test provider endpoint reachability (optional)
-     *
-     * @param provider - Provider configuration
-     * @param fetchProvider - Fetch implementation
-     * @returns True if endpoint is reachable, false otherwise
-     */
-    async testProvider(provider, fetchProvider) {
-        try {
-            // Test authorization URL (HEAD request to avoid triggering OAuth flow)
-            const authResponse = await fetchProvider(provider.authorizationUrl, {
-                method: "HEAD",
-                signal: AbortSignal.timeout(5000), // 5 second timeout
-            });
-            return authResponse.ok || authResponse.status === 405; // 405 Method Not Allowed is OK
-        }
-        catch (error) {
-            return false;
-        }
-    }
-}
-exports.ProviderValidator = ProviderValidator;
-//# sourceMappingURL=provider-validator.js.map

package/dist/services/session-registration.service.d.ts

@@ -1,80 +0,0 @@
-/**
- * Session Registration Service
- *
- * Registers MCP sessions with the AgentShield dashboard, enabling
- * visibility into which MCP clients are connecting to agents.
- *
- * This is a fire-and-forget service - session registration should not
- * block tool execution or affect the user experience.
- *
- * @package @kya-os/mcp-i-core
- */
-import type { RegisterSessionRequest } from "@kya-os/contracts/agentshield-api";
-import type { FetchProvider } from "../providers/base.js";
-/**
- * Configuration for the session registration service
- */
-export interface SessionRegistrationServiceConfig {
-    /** Base URL for the AgentShield API (e.g., "https://kya.vouched.id") */
-    baseUrl: string;
-    /** API key for authentication */
-    apiKey: string;
-    /** Fetch provider for making HTTP requests (platform-agnostic) */
-    fetchProvider: FetchProvider;
-    /** Optional logger callback for diagnostics */
-    logger?: (message: string, data?: unknown) => void;
-    /** Timeout in milliseconds for the registration request (default: 5000) */
-    timeoutMs?: number;
-}
-/**
- * Result of a session registration attempt
- */
-export interface SessionRegistrationResult {
-    /** Whether registration was successful */
-    success: boolean;
-    /** Session ID that was registered */
-    sessionId: string;
-    /** Error message if registration failed */
-    error?: string;
-}
-/**
- * Session Registration Service
- *
- * Registers MCP sessions with AgentShield for dashboard visibility.
- * Designed to be non-blocking - failures are logged but don't throw.
- */
-export declare class SessionRegistrationService {
-    private config;
-    constructor(config: SessionRegistrationServiceConfig);
-    /**
-     * Register a session with AgentShield
-     *
-     * This is a fire-and-forget operation. Failures are logged but don't throw.
-     * The method returns quickly and doesn't block the caller.
-     *
-     * @param request - Session registration request data
-     * @returns Result indicating success or failure
-     */
-    registerSession(request: RegisterSessionRequest): Promise<SessionRegistrationResult>;
-    /**
-     * Fire-and-forget session registration
-     *
-     * Starts registration in the background without waiting for completion.
-     * Useful when you want to register a session but not delay the response.
-     *
-     * @param request - Session registration request data
-     */
-    registerSessionAsync(request: RegisterSessionRequest): void;
-}
-/**
- * Create a session registration service from common runtime config
- *
- * Helper function to create the service from typical environment config.
- */
-export declare function createSessionRegistrationService(options: {
-    apiUrl: string;
-    apiKey: string;
-    fetchProvider: FetchProvider;
-    logger?: (message: string, data?: unknown) => void;
-}): SessionRegistrationService | null;
-//# sourceMappingURL=session-registration.service.d.ts.map

package/dist/services/session-registration.service.js

@@ -1,174 +0,0 @@
-"use strict";
-/**
- * Session Registration Service
- *
- * Registers MCP sessions with the AgentShield dashboard, enabling
- * visibility into which MCP clients are connecting to agents.
- *
- * This is a fire-and-forget service - session registration should not
- * block tool execution or affect the user experience.
- *
- * @package @kya-os/mcp-i-core
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionRegistrationService = void 0;
-exports.createSessionRegistrationService = createSessionRegistrationService;
-const agentshield_api_1 = require("@kya-os/contracts/agentshield-api");
-/**
- * Session Registration Service
- *
- * Registers MCP sessions with AgentShield for dashboard visibility.
- * Designed to be non-blocking - failures are logged but don't throw.
- */
-class SessionRegistrationService {
-    config;
-    constructor(config) {
-        this.config = {
-            baseUrl: config.baseUrl,
-            apiKey: config.apiKey,
-            fetchProvider: config.fetchProvider,
-            logger: config.logger || (() => { }),
-            timeoutMs: config.timeoutMs ?? 5000,
-        };
-    }
-    /**
-     * Register a session with AgentShield
-     *
-     * This is a fire-and-forget operation. Failures are logged but don't throw.
-     * The method returns quickly and doesn't block the caller.
-     *
-     * @param request - Session registration request data
-     * @returns Result indicating success or failure
-     */
-    async registerSession(request) {
-        const sessionId = request.session_id;
-        try {
-            // Validate request
-            const validationResult = agentshield_api_1.registerSessionRequestSchema.safeParse(request);
-            if (!validationResult.success) {
-                const errorMsg = `Invalid session registration request: ${validationResult.error.message}`;
-                this.config.logger("[SessionRegistration] Validation failed", {
-                    sessionId,
-                    error: errorMsg,
-                });
-                return { success: false, sessionId, error: errorMsg };
-            }
-            const url = `${this.config.baseUrl}${agentshield_api_1.AGENTSHIELD_ENDPOINTS.SESSIONS}`;
-            // NOTE: This registers the SESSION with AgentShield for dashboard visibility
-            // This is NOT the same as agent registration with Know That AI (which happens during deploy)
-            this.config.logger("[SessionRegistration] Registering session for dashboard visibility", {
-                sessionId,
-                agentDid: request.agent_did,
-                clientName: request.client_info.name,
-                url,
-            });
-            // Make the request with timeout
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
-            try {
-                const response = await this.config.fetchProvider.fetch(url, {
-                    method: "POST",
-                    headers: {
-                        "Content-Type": "application/json",
-                        Authorization: `Bearer ${this.config.apiKey}`,
-                    },
-                    body: JSON.stringify(request),
-                    signal: controller.signal,
-                });
-                clearTimeout(timeoutId);
-                if (!response.ok) {
-                    // Log error but don't throw - this is fire-and-forget
-                    const errorText = await response.text().catch(() => "Unknown error");
-                    this.config.logger("[SessionRegistration] Registration failed", {
-                        sessionId,
-                        status: response.status,
-                        error: errorText,
-                    });
-                    return {
-                        success: false,
-                        sessionId,
-                        error: `HTTP ${response.status}: ${errorText}`,
-                    };
-                }
-                // Parse response
-                const responseData = (await response.json());
-                const parseResult = agentshield_api_1.registerSessionResponseSchema.safeParse(responseData.data || responseData);
-                if (!parseResult.success) {
-                    this.config.logger("[SessionRegistration] Invalid response format", {
-                        sessionId,
-                        response: responseData,
-                    });
-                    // Still consider it a success if we got a 200 OK
-                    return { success: true, sessionId };
-                }
-                this.config.logger("[SessionRegistration] Session now visible in AgentShield dashboard", {
-                    sessionId,
-                    registered: parseResult.data.registered,
-                });
-                return { success: true, sessionId };
-            }
-            finally {
-                clearTimeout(timeoutId);
-            }
-        }
-        catch (error) {
-            // Handle abort/timeout
-            if (error instanceof Error && error.name === "AbortError") {
-                this.config.logger("[SessionRegistration] Request timed out", {
-                    sessionId,
-                    timeoutMs: this.config.timeoutMs,
-                });
-                return { success: false, sessionId, error: "Request timed out" };
-            }
-            // Log any other error
-            const errorMsg = error instanceof Error ? error.message : "Unknown error";
-            this.config.logger("[SessionRegistration] Unexpected error", {
-                sessionId,
-                error: errorMsg,
-            });
-            return { success: false, sessionId, error: errorMsg };
-        }
-    }
-    /**
-     * Fire-and-forget session registration
-     *
-     * Starts registration in the background without waiting for completion.
-     * Useful when you want to register a session but not delay the response.
-     *
-     * @param request - Session registration request data
-     */
-    registerSessionAsync(request) {
-        // Start registration in background - don't await
-        this.registerSession(request).catch((error) => {
-            // This should never happen since registerSession catches all errors,
-            // but just in case
-            this.config.logger("[SessionRegistration] Background registration failed", {
-                sessionId: request.session_id,
-                error: error instanceof Error ? error.message : "Unknown error",
-            });
-        });
-    }
-}
-exports.SessionRegistrationService = SessionRegistrationService;
-/**
- * Create a session registration service from common runtime config
- *
- * Helper function to create the service from typical environment config.
- */
-function createSessionRegistrationService(options) {
-    // Validate required config
-    if (!options.apiUrl || !options.apiKey) {
-        options.logger?.("[SessionRegistration] Missing required config - session registration disabled", {
-            hasApiUrl: !!options.apiUrl,
-            hasApiKey: !!options.apiKey,
-        });
-        return null;
-    }
-    return new SessionRegistrationService({
-        baseUrl: options.apiUrl,
-        apiKey: options.apiKey,
-        fetchProvider: options.fetchProvider,
-        logger: options.logger,
-    });
-}
-//# sourceMappingURL=session-registration.service.js.map

package/dist/services/storage.service.d.ts

@@ -1,116 +0,0 @@
-/**
- * Storage Service Factory
- *
- * Auto-selects storage providers based on available configuration.
- * Priority: Redis > Cloudflare KV > Cloudflare Durable Objects > Memory
- *
- * @package @kya-os/mcp-i-core
- */
-import { StorageProvider, NonceCacheProvider } from "../providers/base.js";
-/**
- * Storage service configuration
- */
-export interface StorageServiceConfig {
-    /** Redis URL (e.g., "redis://localhost:6379") */
-    redisUrl?: string;
-    /** Cloudflare KV namespace */
-    kvNamespace?: {
-        get(key: string): Promise<string | null>;
-        put(key: string, value: string, options?: {
-            expirationTtl?: number;
-        }): Promise<void>;
-        delete(key: string): Promise<void>;
-        list(options?: {
-            prefix?: string;
-        }): Promise<{
-            keys: Array<{
-                name: string;
-            }>;
-        }>;
-    };
-    /** Cloudflare Durable Object state */
-    durableObjectState?: {
-        storage: {
-            get(key: string): Promise<string | undefined>;
-            put(key: string, value: string): Promise<void>;
-            delete(key: string): Promise<void>;
-            list(options?: {
-                prefix?: string;
-            }): Promise<Map<string, string>>;
-        };
-    };
-    /** Fallback to memory if no external storage configured (default: true) */
-    fallbackToMemory?: boolean;
-}
-/**
- * Storage providers result
- */
-export interface StorageProviders {
-    storageProvider: StorageProvider;
-    nonceCacheProvider: NonceCacheProvider;
-}
-/**
- * Key helper functions for consistent key formatting
- */
-export declare class StorageKeyHelpers {
-    /**
-     * Build delegation key using composite format
-     * Format: delegation:${userDid}:${agentDid}:${projectId}
-     */
-    static buildDelegationKey(userDid: string, agentDid: string, projectId: string): string;
-    /**
-     * Build session key
-     * Format: session:${sessionId}
-     */
-    static buildSessionKey(sessionId: string): string;
-    /**
-     * Build nonce key
-     * Format: nonce:${agentDid}:${nonce}
-     */
-    static buildNonceKey(agentDid: string, nonce: string): string;
-    /**
-     * Parse delegation key back into components
-     *
-     * Format: delegation:${userDid}:${agentDid}:${projectId}
-     *
-     * Note: DIDs contain colons (e.g., did:key:z123), so we can't simply split by ":"
-     * Instead, we:
-     * 1. Check that key starts with "delegation:"
-     * 2. Take the last part as projectId (doesn't contain colons)
-     * 3. Find where agentDid starts (look for "did:" pattern)
-     * 4. Everything before agentDid is userDid, everything between agentDid and projectId is agentDid
-     *
-     * Strategy: Since DIDs always start with "did:", we can find the second occurrence of "did:"
-     * to determine where agentDid begins. However, this assumes userDid and agentDid both start with "did:".
-     *
-     * For keys like "delegation:did:key:user123:did:key:agent456:project-789":
-     * - Remove "delegation:" prefix → "did:key:user123:did:key:agent456:project-789"
-     * - Find last ":" → separates agentDid from projectId
-     * - projectId = "project-789"
-     * - Find second occurrence of "did:" → separates userDid from agentDid
-     * - userDid = "did:key:user123"
-     * - agentDid = "did:key:agent456"
-     */
-    static parseDelegationKey(key: string): {
-        userDid: string;
-        agentDid: string;
-        projectId: string;
-    } | null;
-}
-/**
- * Create storage providers based on configuration
- *
- * Priority order:
- * 1. Redis (if redisUrl provided)
- * 2. Cloudflare KV (if kvNamespace provided)
- * 3. Cloudflare Durable Objects (if durableObjectState provided)
- * 4. In-memory fallback (if fallbackToMemory is true, default)
- */
-export declare function createStorageProviders(config: StorageServiceConfig): Promise<StorageProviders>;
-/**
- * Migration utility for legacy key formats
- *
- * Migrates keys from old format (e.g., `agent:${did}:delegation`) to new composite format
- */
-export declare function migrateLegacyKeys(oldKeyPrefix: string, newKeyFormat: (oldKey: string) => string | null, storageProvider: StorageProvider, batchSize?: number): Promise<number>;
-//# sourceMappingURL=storage.service.d.ts.map