@kya-os/mcp-i 1.3.2 → 1.5.0

package/dist/cache/cloudflare-kv-nonce-cache.js

@@ -52,16 +52,11 @@ class CloudflareKVNonceCache {
             const existingWithMetadata = await this.kv.getWithMetadata(key);
             if (existingWithMetadata && existingWithMetadata.value !== null) {
                 // Key exists, check if it's still valid
-                try {
-                    const existingData = JSON.parse(existingWithMetadata.value);
-                    if (Date.now() <= existingData.expiresAt) {
-                        throw new Error(`Nonce ${nonce} already exists - potential replay attack`);
-                    }
-                    // If expired, we can proceed to overwrite
-                }
-                catch {
-                    // If we can't parse existing data, assume it's corrupted and overwrite
+                const existingData = JSON.parse(existingWithMetadata.value);
+                if (Date.now() <= existingData.expiresAt) {
+                    throw new Error(`Nonce ${nonce} already exists - potential replay attack`);
                 }
+                // If expired, we can proceed to overwrite
             }
             // Store with KV TTL as backup (convert to seconds)
             await this.kv.put(key, JSON.stringify(data), {
@@ -69,6 +64,10 @@ class CloudflareKVNonceCache {
             });
         }
         catch (error) {
+            // If this is a replay attack error, always rethrow it
+            if (error.message?.includes("potential replay attack")) {
+                throw error;
+            }
             // If getWithMetadata is not available, fall back to basic approach
             if (error.message?.includes("getWithMetadata")) {
                 // Check if already exists first (less atomic but still functional)

package/dist/cache/memory-nonce-cache.js

@@ -15,6 +15,8 @@ class MemoryNonceCache {
     cleanupInterval;
     constructor(cleanupIntervalMs = 60000) {
         // Default: 1 minute cleanup
+        console.warn("⚠️  MemoryNonceCache is not suitable for multi-instance deployments. " +
+            "For production use with multiple instances, configure Redis, DynamoDB, or Cloudflare KV.");
         // Start periodic cleanup
         this.cleanupInterval = setInterval(() => {
             this.cleanup().catch(console.error);
@@ -43,7 +45,7 @@ class MemoryNonceCache {
         // Check if nonce already exists (atomic check-and-set)
         const existing = this.cache.get(nonce);
         if (existing && Date.now() <= existing.expiresAt) {
-            throw new Error(`Nonce ${nonce} already exists`);
+            throw new Error(`Nonce ${nonce} already exists - potential replay attack`);
         }
         // Handle zero or negative TTL - set expiration to past time
         const expiresAt = ttlSeconds <= 0 ? Date.now() - 1 : Date.now() + ttlSeconds * 1000;

package/dist/cache/nonce-cache-factory.d.ts

@@ -6,7 +6,9 @@ export declare function detectCacheType(): "memory" | "redis" | "dynamodb" | "cl
 /**
  * Create a nonce cache instance based on configuration or environment detection
  */
-export declare function createNonceCache(config?: NonceCacheConfig): Promise<NonceCache>;
+export declare function createNonceCache(config?: NonceCacheConfig, options?: {
+    throwOnError?: boolean;
+}): Promise<NonceCache>;
 /**
  * Configuration override options for nonce cache
  */

package/dist/cache/nonce-cache-factory.js

@@ -70,7 +70,7 @@ function detectCacheType() {
 /**
  * Create a nonce cache instance based on configuration or environment detection
  */
-async function createNonceCache(config) {
+async function createNonceCache(config, options) {
     const cacheType = config?.type || detectCacheType();
     switch (cacheType) {
         case "redis": {
@@ -78,6 +78,10 @@ async function createNonceCache(config) {
                 process.env.REDIS_URL ||
                 getEnvWithFallback("MCPI_REDIS_URL", "XMCPI_REDIS_URL");
             if (!redisUrl) {
+                const error = new Error("Redis URL not found");
+                if (options?.throwOnError) {
+                    throw error;
+                }
                 console.warn("Redis URL not found, falling back to memory cache");
                 return new memory_nonce_cache_1.MemoryNonceCache();
             }
@@ -97,6 +101,9 @@ async function createNonceCache(config) {
                 return new redis_nonce_cache_1.RedisNonceCache(redis, config?.redis?.keyPrefix);
             }
             catch (error) {
+                if (options?.throwOnError) {
+                    throw error;
+                }
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 console.warn("Failed to connect to Redis, falling back to memory cache:", errorMessage);
                 return new memory_nonce_cache_1.MemoryNonceCache();
@@ -106,6 +113,10 @@ async function createNonceCache(config) {
             const tableName = config?.dynamodb?.tableName ||
                 getEnvWithFallback("MCPI_DYNAMODB_TABLE", "XMCPI_DYNAMODB_TABLE");
             if (!tableName) {
+                const error = new Error("DynamoDB table name not found");
+                if (options?.throwOnError) {
+                    throw error;
+                }
                 console.warn("DynamoDB table name not found, falling back to memory cache");
                 return new memory_nonce_cache_1.MemoryNonceCache();
             }
@@ -139,6 +150,9 @@ async function createNonceCache(config) {
                 return new dynamodb_nonce_cache_1.DynamoNonceCache(dynamodb, tableName, config?.dynamodb?.keyAttribute, config?.dynamodb?.ttlAttribute);
             }
             catch (error) {
+                if (options?.throwOnError) {
+                    throw error;
+                }
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 console.warn("Failed to initialize DynamoDB, falling back to memory cache:", errorMessage);
                 return new memory_nonce_cache_1.MemoryNonceCache();
@@ -148,6 +162,10 @@ async function createNonceCache(config) {
             const namespace = config?.cloudflareKv?.namespace ||
                 getEnvWithFallback("MCPI_KV_NAMESPACE", "XMCPI_KV_NAMESPACE");
             if (!namespace) {
+                const error = new Error("Cloudflare KV namespace not found");
+                if (options?.throwOnError) {
+                    throw error;
+                }
                 console.warn("Cloudflare KV namespace not found, falling back to memory cache");
                 return new memory_nonce_cache_1.MemoryNonceCache();
             }
@@ -181,6 +199,9 @@ async function createNonceCache(config) {
                 return new cloudflare_kv_nonce_cache_1.CloudflareKVNonceCache(kv, config?.cloudflareKv?.keyPrefix);
             }
             catch (error) {
+                if (options?.throwOnError) {
+                    throw error;
+                }
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 console.warn("Failed to initialize Cloudflare KV, falling back to memory cache:", errorMessage);
                 return new memory_nonce_cache_1.MemoryNonceCache();
@@ -196,7 +217,9 @@ async function createNonceCache(config) {
  */
 async function createNonceCacheWithConfig(options = {}) {
     try {
-        return await createNonceCache(options.config);
+        return await createNonceCache(options.config, {
+            throwOnError: options.fallbackToMemory === false,
+        });
     }
     catch (error) {
         if (options.fallbackToMemory !== false) {

package/dist/cli-adapter/index.js

@@ -23,7 +23,13 @@ async function enableMCPIdentityCLI(options = {}) {
     // Helper to emit progress events
     const emitProgress = async (stage, message, data) => {
         if (onProgress) {
-            await onProgress({ stage, message, data });
+            try {
+                await onProgress({ stage, message, data });
+            }
+            catch (error) {
+                // Continue even if progress callback throws
+                console.warn("Warning: Progress callback threw an error:", error);
+            }
         }
     };
     // Step 1: Check for existing identity

package/dist/cli-adapter/kta-registration.js

@@ -57,11 +57,12 @@ async function registerWithKTA(options) {
         // Extract agent ID from DID
         const agentId = did.split(":").pop() || `agent-${Date.now()}`;
         // Build result structure
+        // Handle both camelCase (agentUrl, claimUrl) and uppercase (agentURL, claimURL) from API
         const result = {
             agentDID: did,
-            agentURL: data.agentURL || `${endpoint}/agents/by-did/${encodeURIComponent(did)}`,
+            agentURL: data.agentURL || data.agentUrl || `${endpoint}/agents/by-did/${encodeURIComponent(did)}`,
             agentId: data.agentId || agentId,
-            claimURL: data.claimURL || `${endpoint}/claim/${agentId}`,
+            claimURL: data.claimURL || data.claimUrl || `${endpoint}/claim/${agentId}`,
             verificationEndpoint,
             conformanceCapabilities: MCP_I_CAPABILITIES,
             mirrorStatus: data.mirrorStatus || "pending",

package/dist/runtime/auth-handshake.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Authorization Handshake Module
+ *
+ * Orchestrates the authorization flow for MCP-I bouncer:
+ * 1. Check agent reputation (optional)
+ * 2. Verify delegation exists
+ * 3. Return needs_authorization error if missing
+ *
+ * This module implements the "gatekeeper" logic that determines whether
+ * an agent should be allowed to execute a tool or needs human authorization.
+ *
+ * Flow:
+ * - If delegation exists + valid → allow (fast path)
+ * - If delegation missing → return needs_authorization with hints
+ * - If reputation too low (optional) → require authorization
+ *
+ * Related: PHASE_1_XMCP_I_SERVER.md Epic 2 (Runtime Interceptor)
+ */
+import { NeedsAuthorizationError } from '@kya-os/contracts/runtime';
+import { DelegationVerifier } from './delegation-verifier';
+import { DelegationRecord } from '@kya-os/contracts/delegation';
+/**
+ * Agent reputation data from KTA
+ */
+export interface AgentReputation {
+    /** Agent DID */
+    agentDid: string;
+    /** Reputation score (0-100) */
+    score: number;
+    /** Total interactions recorded */
+    totalInteractions: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Risk level assessment */
+    riskLevel: 'low' | 'medium' | 'high' | 'unknown';
+    /** Last updated timestamp */
+    updatedAt: number;
+}
+/**
+ * Configuration for auth handshake
+ */
+export interface AuthHandshakeConfig {
+    /** Delegation verifier instance */
+    delegationVerifier: DelegationVerifier;
+    /** KTA API configuration (optional, for reputation checks) */
+    kta?: {
+        apiUrl: string;
+        apiKey?: string;
+    };
+    /** Bouncer configuration */
+    bouncer: {
+        /** Authorization URL base (e.g., "https://agentshield.example.com/consent") */
+        authorizationUrl: string;
+        /** Resume token TTL in milliseconds (default: 10 minutes) */
+        resumeTokenTtl?: number;
+        /** Whether to require authorization for unknown/untrusted agents */
+        requireAuthForUnknown?: boolean;
+        /** Minimum reputation score to bypass authorization (0-100) */
+        minReputationScore?: number;
+    };
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Result of auth handshake verification
+ */
+export interface VerifyOrHintsResult {
+    /** Whether authorization is granted */
+    authorized: boolean;
+    /** Delegation record (if authorized) */
+    delegation?: DelegationRecord;
+    /** needs_authorization error (if not authorized) */
+    authError?: NeedsAuthorizationError;
+    /** Agent reputation data (if available) */
+    reputation?: AgentReputation;
+    /** Reason for decision */
+    reason?: string;
+}
+/**
+ * Resume token store interface
+ *
+ * Stores short-lived tokens for resuming after authorization
+ */
+export interface ResumeTokenStore {
+    /**
+     * Create resume token
+     *
+     * @param agentDid - Agent DID
+     * @param scopes - Required scopes
+     * @param metadata - Optional metadata (user agent, IP, etc.)
+     * @returns Resume token string
+     */
+    create(agentDid: string, scopes: string[], metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Get resume token data
+     *
+     * @param token - Resume token
+     * @returns Token data or null if expired/invalid
+     */
+    get(token: string): Promise<{
+        agentDid: string;
+        scopes: string[];
+        createdAt: number;
+        expiresAt: number;
+        metadata?: Record<string, any>;
+    } | null>;
+    /**
+     * Mark token as fulfilled (one-time use)
+     *
+     * @param token - Resume token
+     */
+    fulfill(token: string): Promise<void>;
+}
+/**
+ * Simple in-memory resume token store (for testing/development)
+ */
+export declare class MemoryResumeTokenStore implements ResumeTokenStore {
+    private tokens;
+    private ttl;
+    constructor(ttlMs?: number);
+    create(agentDid: string, scopes: string[], metadata?: Record<string, any>): Promise<string>;
+    get(token: string): Promise<any | null>;
+    fulfill(token: string): Promise<void>;
+    clear(): void;
+}
+/**
+ * Main auth handshake function
+ *
+ * Verifies agent authorization or returns authorization hints
+ *
+ * @param agentDid - Agent DID requesting access
+ * @param scopes - Required permission scopes
+ * @param config - Auth handshake configuration
+ * @param resumeToken - Optional resume token from previous authorization
+ * @returns Verification result with delegation or auth error
+ */
+export declare function verifyOrHints(agentDid: string, scopes: string[], config: AuthHandshakeConfig, resumeToken?: string): Promise<VerifyOrHintsResult>;
+/**
+ * Helper: Check if scopes are sensitive and require authorization
+ *
+ * @param scopes - Scopes to check
+ * @returns true if scopes are sensitive
+ */
+export declare function hasSensitiveScopes(scopes: string[]): boolean;

package/dist/runtime/auth-handshake.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Authorization Handshake Module
+ *
+ * Orchestrates the authorization flow for MCP-I bouncer:
+ * 1. Check agent reputation (optional)
+ * 2. Verify delegation exists
+ * 3. Return needs_authorization error if missing
+ *
+ * This module implements the "gatekeeper" logic that determines whether
+ * an agent should be allowed to execute a tool or needs human authorization.
+ *
+ * Flow:
+ * - If delegation exists + valid → allow (fast path)
+ * - If delegation missing → return needs_authorization with hints
+ * - If reputation too low (optional) → require authorization
+ *
+ * Related: PHASE_1_XMCP_I_SERVER.md Epic 2 (Runtime Interceptor)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryResumeTokenStore = void 0;
+exports.verifyOrHints = verifyOrHints;
+exports.hasSensitiveScopes = hasSensitiveScopes;
+const runtime_1 = require("@kya-os/contracts/runtime");
+/**
+ * Simple in-memory resume token store (for testing/development)
+ */
+class MemoryResumeTokenStore {
+    tokens = new Map();
+    ttl;
+    constructor(ttlMs = 600_000) {
+        this.ttl = ttlMs;
+    }
+    async create(agentDid, scopes, metadata) {
+        const token = `rt_${Date.now()}_${Math.random().toString(36).substr(2, 16)}`;
+        const now = Date.now();
+        this.tokens.set(token, {
+            agentDid,
+            scopes,
+            createdAt: now,
+            expiresAt: now + this.ttl,
+            metadata,
+            fulfilled: false,
+        });
+        return token;
+    }
+    async get(token) {
+        const data = this.tokens.get(token);
+        if (!data)
+            return null;
+        // Check expiration
+        if (Date.now() > data.expiresAt) {
+            this.tokens.delete(token);
+            return null;
+        }
+        // Check if already fulfilled
+        if (data.fulfilled) {
+            return null;
+        }
+        return data;
+    }
+    async fulfill(token) {
+        const data = this.tokens.get(token);
+        if (data) {
+            data.fulfilled = true;
+        }
+    }
+    clear() {
+        this.tokens.clear();
+    }
+}
+exports.MemoryResumeTokenStore = MemoryResumeTokenStore;
+/**
+ * Main auth handshake function
+ *
+ * Verifies agent authorization or returns authorization hints
+ *
+ * @param agentDid - Agent DID requesting access
+ * @param scopes - Required permission scopes
+ * @param config - Auth handshake configuration
+ * @param resumeToken - Optional resume token from previous authorization
+ * @returns Verification result with delegation or auth error
+ */
+async function verifyOrHints(agentDid, scopes, config, resumeToken) {
+    const startTime = Date.now();
+    if (config.debug) {
+        console.log(`[AuthHandshake] Verifying ${agentDid} for scopes: ${scopes.join(', ')}`);
+    }
+    // Step 1: Check reputation (optional, if KTA configured)
+    let reputation;
+    if (config.kta && config.bouncer.minReputationScore !== undefined) {
+        try {
+            reputation = await fetchAgentReputation(agentDid, config.kta);
+            if (config.debug) {
+                console.log(`[AuthHandshake] Reputation score: ${reputation.score}`);
+            }
+            // If reputation is too low, require authorization
+            if (reputation.score < config.bouncer.minReputationScore) {
+                if (config.debug) {
+                    console.log(`[AuthHandshake] Reputation ${reputation.score} < ${config.bouncer.minReputationScore}, requiring authorization`);
+                }
+                const authError = await buildNeedsAuthorizationError(agentDid, scopes, config, 'Agent reputation score below threshold');
+                return {
+                    authorized: false,
+                    authError,
+                    reputation,
+                    reason: 'Low reputation score',
+                };
+            }
+        }
+        catch (error) {
+            // Don't fail hard on reputation check failure
+            console.warn('[AuthHandshake] Failed to check reputation:', error);
+        }
+    }
+    // Step 2: Check for existing delegation
+    let delegationResult;
+    try {
+        delegationResult = await config.delegationVerifier.verify(agentDid, scopes);
+    }
+    catch (error) {
+        console.error('[AuthHandshake] Delegation verification failed:', error);
+        return {
+            authorized: false,
+            reason: `Delegation verification error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        };
+    }
+    // Step 3: If delegation exists and valid, authorize immediately
+    if (delegationResult.valid && delegationResult.delegation) {
+        if (config.debug) {
+            console.log(`[AuthHandshake] Delegation valid, authorized (${Date.now() - startTime}ms)`);
+        }
+        return {
+            authorized: true,
+            delegation: delegationResult.delegation,
+            reputation,
+            reason: 'Valid delegation found',
+        };
+    }
+    // Step 4: No delegation found - return needs_authorization error
+    if (config.debug) {
+        console.log(`[AuthHandshake] No delegation found, returning needs_authorization (${Date.now() - startTime}ms)`);
+    }
+    const authError = await buildNeedsAuthorizationError(agentDid, scopes, config, delegationResult.reason || 'No valid delegation found');
+    return {
+        authorized: false,
+        authError,
+        reputation,
+        reason: delegationResult.reason || 'No delegation',
+    };
+}
+/**
+ * Fetch agent reputation from KTA
+ *
+ * @param agentDid - Agent DID
+ * @param ktaConfig - KTA API configuration
+ * @returns Agent reputation data
+ */
+async function fetchAgentReputation(agentDid, ktaConfig) {
+    const apiUrl = ktaConfig.apiUrl.replace(/\/$/, '');
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (ktaConfig.apiKey) {
+        headers['X-API-Key'] = ktaConfig.apiKey;
+    }
+    const response = await fetch(`${apiUrl}/api/v1/reputation/${encodeURIComponent(agentDid)}`, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            // Agent not registered, return default "unknown" reputation
+            return {
+                agentDid,
+                score: 50, // Neutral score
+                totalInteractions: 0,
+                successRate: 0,
+                riskLevel: 'unknown',
+                updatedAt: Date.now(),
+            };
+        }
+        throw new Error(`KTA API error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return {
+        agentDid: data.agentDid || agentDid,
+        score: data.score || 50,
+        totalInteractions: data.totalInteractions || 0,
+        successRate: data.successRate || 0,
+        riskLevel: data.riskLevel || 'unknown',
+        updatedAt: data.updatedAt || Date.now(),
+    };
+}
+/**
+ * Build needs_authorization error with hints
+ *
+ * @param agentDid - Agent DID
+ * @param scopes - Required scopes
+ * @param config - Auth handshake configuration
+ * @param message - Human-readable error message
+ * @returns NeedsAuthorizationError
+ */
+async function buildNeedsAuthorizationError(agentDid, scopes, config, message) {
+    // Generate resume token (simple implementation - use proper store in production)
+    const resumeTokenStore = new MemoryResumeTokenStore(config.bouncer.resumeTokenTtl || 600_000);
+    const resumeToken = await resumeTokenStore.create(agentDid, scopes, {
+        requestedAt: Date.now(),
+    });
+    const expiresAt = Date.now() + (config.bouncer.resumeTokenTtl || 600_000);
+    // Build authorization URL
+    const authUrl = new URL(config.bouncer.authorizationUrl);
+    authUrl.searchParams.set('agent_did', agentDid);
+    authUrl.searchParams.set('scopes', scopes.join(','));
+    authUrl.searchParams.set('resume_token', resumeToken);
+    // Generate short authorization code (for display)
+    const authCode = resumeToken.substring(0, 8).toUpperCase();
+    // Build display hints
+    const display = {
+        title: 'Authorization Required',
+        hint: ['link', 'qr'],
+        authorizationCode: authCode,
+        qrUrl: `https://chart.googleapis.com/chart?cht=qr&chs=300x300&chl=${encodeURIComponent(authUrl.toString())}`,
+    };
+    return (0, runtime_1.createNeedsAuthorizationError)({
+        message,
+        authorizationUrl: authUrl.toString(),
+        resumeToken,
+        expiresAt,
+        scopes,
+        display,
+    });
+}
+/**
+ * Helper: Check if scopes are sensitive and require authorization
+ *
+ * @param scopes - Scopes to check
+ * @returns true if scopes are sensitive
+ */
+function hasSensitiveScopes(scopes) {
+    const sensitivePatterns = [
+        'write',
+        'delete',
+        'admin',
+        'payment',
+        'transfer',
+        'execute',
+        'modify',
+    ];
+    return scopes.some((scope) => sensitivePatterns.some((pattern) => scope.toLowerCase().includes(pattern)));
+}

package/dist/runtime/delegation-verifier-agentshield.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentShield API Delegation Verifier
+ *
+ * Queries delegations from AgentShield managed service API.
+ * Includes local caching to minimize network calls and maximize performance.
+ *
+ * Performance:
+ * - Fast path (cached): < 5ms
+ * - Slow path (API call): < 100ms
+ * - Cache TTL: 1 minute (configurable)
+ *
+ * API Endpoints:
+ * - POST /api/v1/delegations/verify - Verify delegation by agent DID + scopes
+ * - GET /api/v1/delegations/:id - Get delegation by ID
+ * - POST /api/v1/delegations - Create new delegation (admin only)
+ * - POST /api/v1/delegations/:id/revoke - Revoke delegation (admin only)
+ *
+ * Authentication: Bearer token via X-API-Key header
+ *
+ * Related: PHASE_1_XMCP_I_SERVER.md Ticket 1.3
+ * Related: AGENTSHIELD_DASHBOARD_PLAN.md Epic 2 (Public API)
+ */
+import { DelegationRecord } from '@kya-os/contracts/delegation';
+import { DelegationVerifier, DelegationVerifierConfig, VerifyDelegationResult, VerifyDelegationOptions } from './delegation-verifier';
+/**
+ * AgentShield API Delegation Verifier
+ *
+ * Managed mode: Queries delegations from AgentShield dashboard API
+ */
+export declare class AgentShieldAPIDelegationVerifier implements DelegationVerifier {
+    private apiUrl;
+    private apiKey;
+    private cache;
+    private cacheTtl;
+    private debug;
+    constructor(config: DelegationVerifierConfig);
+    /**
+     * Verify agent delegation via API
+     */
+    verify(agentDid: string, scopes: string[], options?: VerifyDelegationOptions): Promise<VerifyDelegationResult>;
+    /**
+     * Get delegation by ID via API
+     */
+    get(delegationId: string): Promise<DelegationRecord | null>;
+    /**
+     * Store delegation (admin operation via API)
+     *
+     * Note: This is typically done via AgentShield dashboard UI,
+     * not by the bouncer directly. Included for completeness.
+     */
+    put(delegation: DelegationRecord): Promise<void>;
+    /**
+     * Revoke delegation via API
+     */
+    revoke(delegationId: string, reason?: string): Promise<void>;
+    /**
+     * Close connections (cleanup)
+     */
+    close(): Promise<void>;
+    /**
+     * Build deterministic scopes key for caching
+     */
+    private buildScopesKey;
+}