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

package/dist/services/storage.service.js

@@ -1,411 +0,0 @@
-"use strict";
-/**
- * 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
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.StorageKeyHelpers = void 0;
-exports.createStorageProviders = createStorageProviders;
-exports.migrateLegacyKeys = migrateLegacyKeys;
-const base_js_1 = require("../providers/base.js");
-const memory_js_1 = require("../providers/memory.js");
-/**
- * Key helper functions for consistent key formatting
- */
-class StorageKeyHelpers {
-    /**
-     * Build delegation key using composite format
-     * Format: delegation:${userDid}:${agentDid}:${projectId}
-     */
-    static buildDelegationKey(userDid, agentDid, projectId) {
-        return `delegation:${userDid}:${agentDid}:${projectId}`;
-    }
-    /**
-     * Build session key
-     * Format: session:${sessionId}
-     */
-    static buildSessionKey(sessionId) {
-        return `session:${sessionId}`;
-    }
-    /**
-     * Build nonce key
-     * Format: nonce:${agentDid}:${nonce}
-     */
-    static buildNonceKey(agentDid, nonce) {
-        return `nonce:${agentDid}:${nonce}`;
-    }
-    /**
-     * 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) {
-        if (!key.startsWith("delegation:")) {
-            return null;
-        }
-        // Remove "delegation:" prefix
-        const rest = key.slice("delegation:".length);
-        // Find the last colon (separates agentDid from projectId)
-        const lastColonIndex = rest.lastIndexOf(":");
-        if (lastColonIndex === -1) {
-            return null; // No colon found, invalid format
-        }
-        // Last part is projectId (doesn't contain colons)
-        const projectId = rest.slice(lastColonIndex + 1);
-        if (!projectId) {
-            return null; // Empty projectId
-        }
-        // Everything before the last colon is userDid:agentDid
-        const userDidAndAgentDid = rest.slice(0, lastColonIndex);
-        // Find the second occurrence of "did:" to separate userDid from agentDid
-        // First occurrence is at the start (userDid), second is agentDid
-        const firstDidIndex = userDidAndAgentDid.indexOf("did:");
-        if (firstDidIndex !== 0) {
-            return null; // userDid must start with "did:"
-        }
-        // Find where the first DID ends by looking for the pattern "did:method:identifier"
-        // A DID has the format: did:method:identifier (where identifier may contain colons)
-        // We need to find the next "did:" that appears after a complete DID
-        // Strategy: Find the method separator colon (after "did:"), then search for the next "did:" after that
-        // This ensures we find the second complete DID, not a substring within the first DID's identifier
-        const firstMethodColon = userDidAndAgentDid.indexOf(":", firstDidIndex + "did:".length);
-        if (firstMethodColon === -1) {
-            return null; // Invalid DID format - no method separator
-        }
-        // Now search for the next "did:" after the first complete DID
-        // The first DID ends somewhere after the method colon, so search from there
-        const secondDidIndex = userDidAndAgentDid.indexOf("did:", firstMethodColon + 1);
-        if (secondDidIndex === -1) {
-            return null; // No second "did:" found, can't separate userDid and agentDid
-        }
-        // userDid is everything before the second "did:", agentDid is everything after
-        const userDid = userDidAndAgentDid.slice(0, secondDidIndex);
-        const agentDid = userDidAndAgentDid.slice(secondDidIndex);
-        // Remove trailing colon from userDid if present
-        const cleanUserDid = userDid.endsWith(":") ? userDid.slice(0, -1) : userDid;
-        if (!cleanUserDid || !agentDid) {
-            return null; // Empty userDid or agentDid
-        }
-        return {
-            userDid: cleanUserDid,
-            agentDid,
-            projectId,
-        };
-    }
-}
-exports.StorageKeyHelpers = StorageKeyHelpers;
-/**
- * Durable Object Storage Provider
- * Wraps Cloudflare Durable Object state storage
- */
-class DurableObjectStorageProvider extends base_js_1.StorageProvider {
-    state;
-    constructor(state) {
-        super();
-        this.state = state;
-    }
-    async get(key) {
-        const value = await this.state.storage.get(key);
-        return value ?? null;
-    }
-    async set(key, value) {
-        await this.state.storage.put(key, value);
-    }
-    async delete(key) {
-        await this.state.storage.delete(key);
-    }
-    async exists(key) {
-        const value = await this.state.storage.get(key);
-        return value !== undefined;
-    }
-    async list(prefix) {
-        const result = await this.state.storage.list(prefix ? { prefix } : undefined);
-        return Array.from(result.keys());
-    }
-}
-/**
- * Durable Object Nonce Cache Provider
- */
-class DurableObjectNonceCacheProvider extends base_js_1.NonceCacheProvider {
-    state;
-    constructor(state) {
-        super();
-        this.state = state;
-    }
-    async has(nonce, agentDid) {
-        const key = agentDid
-            ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
-            : `nonce:${nonce}`;
-        const value = await this.state.storage.get(key);
-        if (!value) {
-            return false;
-        }
-        const expiresAt = parseInt(value, 10);
-        return Date.now() < expiresAt;
-    }
-    async add(nonce, ttlSeconds, agentDid) {
-        const key = agentDid
-            ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
-            : `nonce:${nonce}`;
-        // Convert TTL seconds to absolute expiration timestamp for storage
-        const expiresAt = Date.now() + ttlSeconds * 1000;
-        await this.state.storage.put(key, expiresAt.toString());
-    }
-    async cleanup() {
-        // Durable Objects don't support efficient bulk operations
-        // Cleanup would require listing all keys, which is expensive
-        // For now, rely on TTL checking in has() method
-    }
-    async destroy() {
-        // Durable Objects state persists automatically
-        // No explicit cleanup needed
-    }
-}
-/**
- * Redis Storage Provider
- * Uses Redis for storage operations
- */
-class RedisStorageProvider extends base_js_1.StorageProvider {
-    redis; // Redis client from 'redis' package
-    constructor(redisClient) {
-        super();
-        this.redis = redisClient;
-    }
-    async get(key) {
-        return await this.redis.get(key);
-    }
-    async set(key, value) {
-        await this.redis.set(key, value);
-    }
-    async delete(key) {
-        await this.redis.del(key);
-    }
-    async exists(key) {
-        const result = await this.redis.exists(key);
-        return result === 1;
-    }
-    async list(prefix) {
-        const pattern = prefix ? `${prefix}*` : "*";
-        const keys = await this.redis.keys(pattern);
-        return keys;
-    }
-}
-/**
- * Redis Nonce Cache Provider
- */
-class RedisNonceCacheProvider extends base_js_1.NonceCacheProvider {
-    redis;
-    keyPrefix;
-    constructor(redisClient, keyPrefix = "nonce:") {
-        super();
-        this.redis = redisClient;
-        this.keyPrefix = keyPrefix;
-    }
-    async has(nonce, agentDid) {
-        const key = agentDid
-            ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
-            : `${this.keyPrefix}${nonce}`;
-        const result = await this.redis.exists(key);
-        return result === 1;
-    }
-    async add(nonce, ttlSeconds, agentDid) {
-        const key = agentDid
-            ? StorageKeyHelpers.buildNonceKey(agentDid, nonce)
-            : `${this.keyPrefix}${nonce}`;
-        // Use TTL directly in seconds (callers now pass TTL, not absolute timestamp)
-        await this.redis.setEx(key, ttlSeconds, "1");
-    }
-    async cleanup() {
-        // Redis handles TTL automatically, no cleanup needed
-    }
-    async destroy() {
-        // Redis connection should be managed by caller
-    }
-}
-/**
- * KV Storage Provider wrapper
- * Uses existing KVStorageProvider from mcp-i-cloudflare
- */
-/**
- * Create Cloudflare KV storage providers
- *
- * This function dynamically imports Cloudflare-specific storage providers.
- * The @ts-ignore is necessary because @kya-os/mcp-i-cloudflare/providers/storage
- * is an optional dependency that may not exist in Node.js environments.
- * This is intentional for platform-specific code - the import will fail at runtime
- * if the module doesn't exist, which is handled by the try-catch block.
- */
-async function createKVStorageProvider(kvNamespace) {
-    // Dynamic import to avoid bundling Cloudflare-specific code
-    // This is an optional dependency that may not exist in all environments
-    try {
-        // Use string literal to avoid TypeScript checking the module path at compile time
-        const storageModulePath = "@kya-os/mcp-i-cloudflare/providers/storage";
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore TS2307 - Optional dependency: @kya-os/mcp-i-cloudflare/providers/storage
-        // may not exist in Node.js environments. This is intentional for platform-specific code.
-        const { KVStorageProvider, KVNonceCacheProvider } = await import(storageModulePath);
-        const storage = new KVStorageProvider(kvNamespace);
-        const nonceCache = new KVNonceCacheProvider(kvNamespace);
-        return { storage, nonceCache };
-    }
-    catch (error) {
-        throw new Error(`Failed to import Cloudflare storage providers: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-/**
- * 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)
- */
-async function createStorageProviders(config) {
-    const fallbackToMemory = config.fallbackToMemory !== false;
-    // Priority 1: Redis
-    if (config.redisUrl) {
-        try {
-            // Dynamic import to avoid bundling Redis in environments that don't need it
-            // Use string literal to avoid TypeScript checking the module path at compile time
-            const redisModulePath = "redis";
-            // @ts-ignore TS2307 - Optional dependency: 'redis' package may not be installed.
-            // This is intentional - the import will fail at runtime if Redis is not available,
-            // which is handled by the try-catch block.
-            const redisModule = await import(redisModulePath).catch(() => null);
-            if (!redisModule) {
-                throw new Error("Redis package not available");
-            }
-            const { createClient } = redisModule;
-            // @ts-ignore TS2307 - Type inference from dynamic import
-            // Redis client type is inferred from the runtime module
-            const redis = createClient({
-                url: config.redisUrl,
-                socket: {
-                    connectTimeout: 5000,
-                },
-            });
-            await redis.connect();
-            await redis.ping();
-            const storageProvider = new RedisStorageProvider(redis);
-            const nonceCacheProvider = new RedisNonceCacheProvider(redis);
-            return {
-                storageProvider,
-                nonceCacheProvider,
-            };
-        }
-        catch (error) {
-            if (!fallbackToMemory) {
-                throw error;
-            }
-            console.warn("[StorageService] Failed to connect to Redis, falling back to memory:", error instanceof Error ? error.message : String(error));
-        }
-    }
-    // Priority 2: Cloudflare KV
-    if (config.kvNamespace) {
-        try {
-            const providers = await createKVStorageProvider(config.kvNamespace);
-            return {
-                storageProvider: providers.storage,
-                nonceCacheProvider: providers.nonceCache,
-            };
-        }
-        catch (error) {
-            if (!fallbackToMemory) {
-                throw error;
-            }
-            console.warn("[StorageService] Failed to initialize KV, falling back to memory:", error instanceof Error ? error.message : String(error));
-        }
-    }
-    // Priority 3: Cloudflare Durable Objects
-    if (config.durableObjectState) {
-        try {
-            const storageProvider = new DurableObjectStorageProvider(config.durableObjectState);
-            const nonceCacheProvider = new DurableObjectNonceCacheProvider(config.durableObjectState);
-            return {
-                storageProvider,
-                nonceCacheProvider,
-            };
-        }
-        catch (error) {
-            if (!fallbackToMemory) {
-                throw error;
-            }
-            console.warn("[StorageService] Failed to initialize Durable Objects, falling back to memory:", error instanceof Error ? error.message : String(error));
-        }
-    }
-    // Priority 4: In-memory fallback
-    if (fallbackToMemory) {
-        return {
-            storageProvider: new memory_js_1.MemoryStorageProvider(),
-            nonceCacheProvider: new memory_js_1.MemoryNonceCacheProvider(),
-        };
-    }
-    throw new Error("No storage provider configured and fallbackToMemory is false");
-}
-/**
- * Migration utility for legacy key formats
- *
- * Migrates keys from old format (e.g., `agent:${did}:delegation`) to new composite format
- */
-async function migrateLegacyKeys(oldKeyPrefix, newKeyFormat, storageProvider, batchSize = 100) {
-    let migrated = 0;
-    try {
-        // List all keys with old prefix
-        const oldKeys = await storageProvider.list(oldKeyPrefix);
-        for (const oldKey of oldKeys) {
-            const newKey = newKeyFormat(oldKey);
-            if (!newKey) {
-                continue; // Skip if transformation fails
-            }
-            // Check if new key already exists
-            const existing = await storageProvider.exists(newKey);
-            if (existing) {
-                continue; // Skip if already migrated
-            }
-            // Read old value
-            const value = await storageProvider.get(oldKey);
-            if (!value) {
-                continue; // Skip if old key has no value
-            }
-            // Write to new key
-            await storageProvider.set(newKey, value);
-            // Optionally delete old key (commented out for safety)
-            // await storageProvider.delete(oldKey);
-            migrated++;
-            if (migrated % batchSize === 0) {
-                // Yield to event loop for large migrations
-                await new Promise((resolve) => setTimeout(resolve, 0));
-            }
-        }
-    }
-    catch (error) {
-        console.error("[StorageService] Migration error:", error);
-        throw error;
-    }
-    return migrated;
-}
-//# sourceMappingURL=storage.service.js.map

package/dist/services/tool-context-builder.d.ts

@@ -1,74 +0,0 @@
-/**
- * Tool Context Builder
- *
- * Builds ToolExecutionContext for tool handlers by resolving IDP tokens
- * based on tool protection configuration and user identity.
- *
- * Updated for CRED-003: Builds idpHeaders based on tokenUsage metadata
- * to support credential providers with custom token usage patterns.
- *
- * @package @kya-os/mcp-i-core
- */
-import type { ToolExecutionContext } from "@kya-os/contracts/config";
-import type { IdpTokenResolver } from "../identity/idp-token-resolver.js";
-import type { ToolProtection } from "../types/tool-protection.js";
-import type { OAuthConfigService } from "./oauth-config.service.js";
-import type { ProviderResolver } from "./provider-resolver.js";
-export interface ToolContextBuilderConfig {
-    /** IDP token resolver for resolving tokens from User DID */
-    tokenResolver: IdpTokenResolver;
-    /** OAuth config service for fetching provider configurations */
-    configService: OAuthConfigService;
-    /** Provider resolver for resolving OAuth providers for tools */
-    providerResolver: ProviderResolver;
-    /** Project ID for fetching OAuth config */
-    projectId: string;
-    /** Optional logger callback for diagnostics */
-    logger?: (message: string, data?: unknown) => void;
-}
-/**
- * Builder for tool execution context
- *
- * Resolves IDP tokens and builds context for tool handlers.
- * Phase 1: Uses configured provider as temporary fallback.
- * Phase 2+: Requires explicit oauthProvider on tool protection.
- */
-export declare class ToolContextBuilder {
-    private config;
-    constructor(config: ToolContextBuilderConfig);
-    /**
-     * Build tool execution context
-     *
-     * @param toolName - Name of the tool being executed
-     * @param userDid - User DID (optional, required for OAuth/credentials)
-     * @param sessionId - Session ID (optional)
-     * @param delegationToken - Delegation token (optional)
-     * @param toolProtection - Tool protection configuration (optional)
-     * @returns Tool execution context or undefined if not needed
-     */
-    buildContext(toolName: string, userDid: string | undefined, sessionId: string | undefined, delegationToken: string | undefined, toolProtection: ToolProtection | null): Promise<ToolExecutionContext | undefined>;
-    /**
-     * Build authentication headers based on token usage metadata (CRED-003)
-     *
-     * Supports three modes:
-     * - "cookie": Cookie header (with optional cookieFormat template)
-     * - "bearer": Authorization: Bearer xxx
-     * - "header": Custom header name
-     *
-     * Also includes any apiHeaders from provider config.
-     *
-     * @param tokenData - Token data with usage metadata
-     * @returns Headers object for API calls
-     */
-    private buildAuthHeaders;
-    /**
-     * Resolve OAuth provider for a tool
-     *
-     * Phase 2: Uses ProviderResolver with priority-based resolution
-     *
-     * @param toolProtection - Tool protection configuration
-     * @returns Provider name or throws error if not found
-     */
-    private resolveProvider;
-}
-//# sourceMappingURL=tool-context-builder.d.ts.map